summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/csquotes/tutorial.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/csquotes/tutorial.tex')
-rw-r--r--Master/texmf-dist/doc/latex/csquotes/tutorial.tex178
1 files changed, 80 insertions, 98 deletions
diff --git a/Master/texmf-dist/doc/latex/csquotes/tutorial.tex b/Master/texmf-dist/doc/latex/csquotes/tutorial.tex
index 57dd1163966..f4f4af69607 100644
--- a/Master/texmf-dist/doc/latex/csquotes/tutorial.tex
+++ b/Master/texmf-dist/doc/latex/csquotes/tutorial.tex
@@ -1,4 +1,4 @@
-% $Id: tutorial.tex,v 3.1 2005/08/29 18:07:39 lehman pub $
+% $Id: tutorial.tex,v 3.4 2006/04/02 15:58:08 lehman stable $
%
% This tutorial will give you an introduction to the csquotes package by way of
% example. All the instructions are included as comments in this file. There is
@@ -30,14 +30,19 @@
% The first two are obvious choices:
\MakeOuterQuote{"}
\MakeAutoQuote{«}{»}
-
% The next one is more or less evident as well:
\MakeBlockQuote{<}{|}{>}
-% The next two are rather uncommon. They are mainly included in this tutorial
-% to demonstrate math mode compatibility:
-\MakeOuterQuote{_}
-\MakeInnerQuote{^}
+% In general, an active quote must be a single character with category code 12
+% or 13 (or a valid UTF-8 sequence representing a single character, if you are
+% using UTF-8 encoding). The csquotes package will automatically check all
+% characters for validity as you allocate them with a command like
+% \MakeOuterQuote. Apart from characters which are not suitable because of
+% their category code, csquotes will also reject numbers, punctuation marks,
+% the apostrophe, and all characters which are part of LaTeX's syntax or
+% reserved for a specific purpose (such as '*', '[', ']', '~'). If you are
+% unsure, there is no harm in trying. If a character you choose is unsuitable,
+% csquotes will issue an error message.
% Some additional packages used or discussed in this tutorial:
\usepackage[noadjust]{cite}
@@ -102,7 +107,7 @@ series of comments which are included in the source.
% The csquotes package supports two markup styles for quotations: control
% sequences and active characters. An active character is a single character
-% functioning like a control sequence. Think of them as `smart quotes' done
+% functioning as a control sequence. Think of them as `smart quotes' done
% right. The active characters are defined in the document preamble or in the
% configuration file. There are several commands which make that a trivial
% task:
@@ -241,17 +246,17 @@ series of comments which are included in the source.
\example{4} "a "o "u "i
% You can reclaim active quotes after their definitions have been overwritten
-% by another package with \RestoreQuotes. This command will replay the
+% by another package with \EnableQuotes. This command will replay the
% definitions of all active quotes recorded in the configuration file and the
-% preamble. Note that it doesn't make sense to use \RestoreQuotes in the
+% preamble. Note that it doesn't make sense to use \EnableQuotes in the
% preamble because a lot of packages (including csquotes) defer the activation
% of such characters until \begin{document}.
-\RestoreQuotes
+\EnableQuotes
\example{5} "Zitat"
-% Use \RestoreQuotes with care as you may break other packages by reclaiming
+% Use \EnableQuotes with care as you may break other packages by reclaiming
% active quotes. Even if things don't break outright, you might loose
% functionality. With babel's German extension, for example, you can do without
% the " shorthand as far as diacritics and (babel's) quotes are concerned when
@@ -265,7 +270,7 @@ series of comments which are included in the source.
%
% \addto\extrasgerman{%
% \aliasshorthand{"}{|}%
-% \RestoreQuotes}
+% \EnableQuotes}
%
% \selectlanguage{german}
%
@@ -376,7 +381,7 @@ series of comments which are included in the source.
% <This is a quote in American English.>
% «Voici une citation en français.»
-\RestoreQuotes % because \selectlanguage{german} overwrites the " special
+\EnableQuotes % because \selectlanguage{german} overwrites the " special
\selectlanguage{american}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -514,7 +519,7 @@ the running text.
% is not used, the entire piece of text between the opening and the closing
% mark will be treated as quotation text. Note that the marks and the delimiter
% must not be included in the quoted piece of text and the citation. See the
-% section entitled "Literal active quotes" on how to work around this
+% section entitled "Controlling active quotes" on how to work around this
% limitation.
% Let's go over our verbose example once again, using active quotes this time:
@@ -554,12 +559,10 @@ quotation is integrated with the running text.
% The integrated quotation facilities differ from their regular counterparts in
% that they integrate automated citations into their syntax. Instead of adding
% \cite manually, you pass the arguments for \cite to the respective quotation
-% command.
+% command. You would normally give a citation like that:
\example{1} \enquote{This is the quotation.} \cite[174]{citekey}
-\example{2} \textcquote[174]{citekey}{This is the quotation.}
-
% The commands for formal quotations already take the citation as an argument,
% but using \cite in an optional argument may lead to some rather convoluted
% constructs with multiple nested pairs of brackets and braces:
@@ -567,7 +570,11 @@ quotation is integrated with the running text.
% \textquote[{\cite[174]{citekey}}]{This is the quotation.}
%
% The integrated quotation facilities allow you to write that in a much more
-% readable, sequential way. This works with block quotations as well:
+% readable, sequential way:
+
+\example{2} \textcquote[174]{citekey}{This is the quotation.}
+
+% This works with block quotations as well:
\example{3} \blockcquote[174]{citekey}{This is the quotation.}
@@ -622,7 +629,7 @@ quotation is integrated with the running text.
\renewcommand*{\citeleft}{}
\renewcommand*{\citeright}{.}
-\renewcommand*{\citemid}{, }
+\renewcommand*{\citemid}{, p.~}
\example{5} \blockcquote[174]{doe96}{This is the quotation.}
@@ -697,6 +704,19 @@ quotation environment has been modified so that the font size of the quotation
is decreased by one step with respect to the size of the surrounding text.}
This is some filler text.
+% All adjustments made by means of \SetBlockEnvironment will automatically
+% apply to the `display' environments as well:
+
+\example{2}
+This is some filler text.
+\begin{displayquote}
+This is a quotation typeset with one of the quotation environments of the
+\texttt{csquotes} package. Quotations typeset by way of these environments
+will behave exactely like a long quotation set with the block quotation
+commands.
+\end{displayquote}
+This is some filler text.
+
% If you want to use this setup by default, add the following to csquotes.cfg:
%
% \RequirePackage{relsize}
@@ -725,7 +745,7 @@ This is some filler text.
% lists. If they are part of a paragraph, the first line after the environment
% will not be indented:
-\example{2}
+\example{3}
This is some filler text.
\begin{quote}
This is a quotation typeset with the standard \texttt{quote} environment. In
@@ -738,7 +758,7 @@ This line is not indented.
% blank line, the first line after the environment will get regular paragraph
% indentation:
-\example{3}
+\example{4}
This is some filler text.
\begin{quote}
@@ -756,7 +776,7 @@ This line gets regular paragraph indentation.
% implies that the first line after the environment will not get regular
% paragraph indentation:
-\example{4}
+\example{5}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. In the source
of this example the quotation is part of a paragraph. By default, the block
@@ -788,7 +808,7 @@ indented.} This line is not indented.
% Now all long quotes will be treated as separate paragraphs:
-\example{5}
+\example{6}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. In the source
of this example the quotation is also part of a larger paragraph. However, the
@@ -796,21 +816,6 @@ block quotation environment has been redefined so that the first line after
the quotation gets regular paragraph indentation.} This line gets regular
paragraph indentation.
-% All adjustments made by means of \SetBlockEnvironment will automatically
-% apply to the `display' environments as well:
-
-\example{6}
-This is some filler text.
-
-\begin{displayquote}
-This is a quotation typeset with one of the quotation environments of the
-\texttt{csquotes} package. Quotations typeset by way of these environments
-will behave exactely like a long quotation set with the block quotation
-commands.
-\end{displayquote}
-
-This is some filler text.
-
% Our `paraquote' environment may also be merged with the `smallquote'
% environment discussed above:
%
@@ -862,7 +867,7 @@ This is some filler text.
% argument, even if it is not used in their definition. We will use it further
% down, though.
%
-% When quoting, we simply omit the terminal period:
+% Now, when quoting, we simply omit the terminal period:
\example{1}
\blockquote[Doe 174]{This is a short quotation. The terminal period is omitted
@@ -1018,9 +1023,9 @@ quotation is not the end of the quoted sentence%, which goes on like this.
\end{otherlanguage}}
% Note that the extra set of braces in the example above was merely added to
-% work around a bug in older versions of the babel package. They are not related
-% to csquotes in any way and should not be required with a recent version of
-% babel.
+% work around a bug in older versions of the babel package. They are not
+% related to csquotes in any way and should not be required with a recent
+% version of babel.
% The starred version of this environment switches hyphenation patterns and
% activates the language specific adjustments without modifying the strings:
@@ -1063,81 +1068,58 @@ quotation is not the end of the quoted sentence%, which goes on like this.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Active quotes and math mode}
-
-% Whether you're working with several foreign languages and prefer using active
-% quotes or whether you simply want to stick with Ascii for the active quotes:
-% you might quickly run out of suitable characters in a lot of situations.
-% While you can always fall back to the built-in commands, it is also worth
-% mentioning that the csquotes package will effectively disable all active
-% quotes in math mode. It is perfectly possible to use characters as active
-% quotes which are frequently used in math mode, such as < and >, or which have
-% a special meaning, such as _ and ^, without interfering with math mode:
-
-\example{1} _text_ $x_n$
-
-\example{2} ^text^ $y^2$
-
-% Quotations tagged with active quotes may include math as well:
+\subsection{Controlling active quotes}
-\example{3} _$x_n$_
+% Once made active, the active quotes cannot be used any more as if they were
+% ordinary characters. You may always include them literally in the text by
+% using a verbatim environment, but it is also possible to control their
+% current state in situations in which a verbatim environment is not feasible.
-\example{4} ^$y^2$^
+% The commands \EnableQuotes and \DisableQuotes will turn the active quotes on
+% and off:
-% We could push that even further by `quoting' math-mode material:
-
-\example{5} _$x_{\mbox{^$n^2$^}}$_
-
-\example{6} _$y^{\mbox{^$x_n$^}}$_
+\example{1}
+"text" «text» <text>
-% Just kidding...
+\DisableQuotes
+"" «» <>
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\EnableQuotes
+"text" «text» <text>
-\subsection{Literal active quotes}
+% Like verbatim environments, these commands modify category codes. This
+% implies that you cannot use them to change the behavior of the argument read
+% in by a command. In this case, use \VerbatimQuotes instead. This command
+% will print all active quotes literally without changing category codes.
+% Since the scope of this command is local, you don't even need \EnableQuotes
+% if you put everything in a group. Here's an example:
-% Once made active, active quotes cannot be used any more as if they were
-% ordinary characters. Apart from using a verbatim environment, there are
-% typically two ways to include them literally in the text.
-%
-% If the active quote is an Ascii character, you can simply use the primitive
-% TeX command \string to print it literally in most cases:
+\newcommand{\printverbquotes}[1]{\begingroup\VerbatimQuotes #1\endgroup}
-\example{1} \string" \string_ \string^
+\example{2}
+"text" «text» <text>
-% If it is not, you need to use an alternative control sequence:
+\printverbquotes{"" «» <>}
-\example{2} \guillemotleft\ \guillemotright
+"text" «text» <text>
% Note that the situation is slighly different with active block quotes. Only
-% the opening mark is an active character, the delimiter and the closing mark
-% are not. Outside the scope of a block quotation the latter may therefore be
-% employed as usual. When included in a block quotation, however, they would
-% confuse TeX's argument scanner. You can prevent that by wrapping the
-% offending character in curly brackets.
-%
-% In the preamble, we have defined some active block quotes with
-% \MakeBlockQuote{<}{|}{>}. These characters can be used literally as follows:
+% the opening mark really is an active quote. The delimiter and the closing
+% mark are also active characters, but their behavior is different. Outside
+% the scope of a block quotation they may be employed as usual:
-\example{3} \string< | >
+\example{3} \printverbquotes{<} | >
-\example{4} <quotation \string< {|} {>}|citation>
+% When included in a block quotation, however, they would confuse TeX's
+% argument scanner. You can prevent that by wrapping the offending character
+% in curly brackets:
+
+\example{4} <quotation \printverbquotes{<} {|} {>}|citation>
% Of course you can always use control sequences instead:
\example{5} <quotation \textless\ \textbar\ \textgreater|citation>
-% If all else fails, you can still disable the active quotes for a certain part
-% of the document:
-
-\DisableQuotes
-
-\example{6} "" «» <>
-
-\RestoreQuotes
-
-\example{7} "text" «text» <text>
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% That's it.