diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/csquotes/tutorial.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/csquotes/tutorial.tex | 1155 |
1 files changed, 1155 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/csquotes/tutorial.tex b/Master/texmf-dist/doc/latex/csquotes/tutorial.tex new file mode 100644 index 00000000000..57dd1163966 --- /dev/null +++ b/Master/texmf-dist/doc/latex/csquotes/tutorial.tex @@ -0,0 +1,1155 @@ +% $Id: tutorial.tex,v 3.1 2005/08/29 18:07:39 lehman pub $ +% +% 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 +% nothing fancy to see in the typeset version of this file but you should +% compare the document source to the typeset result while reading this +% tutorial to see what the commands do. +% +% Note that this file uses ISO-8859-1 (Latin 1) encoding. +% Please adjust your text editor as required. + +\documentclass[a4paper]{article} + +% We're using 8-bit input and T1 encoded fonts for proper output: +\usepackage[latin1]{inputenc} +\usepackage[T1]{fontenc} + +% In order to demonstrate babel support we load the babel package: +\usepackage[french,german,portuguese,american]{babel} + +% We load csquotes with the `babel' option. The csquotes package works just +% fine without babel, but it will support multilingual typesetting if babel +% has been loaded. +\usepackage[babel]{csquotes} + +% In this tutorial, we'll make use of a few active quotes. They will be +% discussed in greater detail below. Active quotes are defined in the document +% preamble or the configuration file. + +% 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{^} + +% Some additional packages used or discussed in this tutorial: +\usepackage[noadjust]{cite} +\usepackage{relsize} + +% Some generic settings: +\setcounter{secnumdepth}{1} +\pagestyle{empty} +\frenchspacing +\raggedbottom + +\makeatletter +\renewcommand{\@makefntext}[1]{% + \@hangfrom{\makebox[0.5em][r]{\@thefnmark}% + \hspace{1em}}% + #1} +\makeatother + +\newcommand*{\example}[1]{% + \addvspace{\baselineskip}% + \par\noindent\hspace{-4em}% + \makebox[3em][r]{\textbf{Ex. #1}}% + \hspace{1em}\ignorespaces} + +% Let's go +\begin{document} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% We include a short note to anyone looking at the typeset file first: + +\noindent This is the typeset version of \texttt{\jobname.tex}. There is +nothing fancy to see here. The tutorial you are looking for consists of a +series of comments which are included in the source. + +\clearpage + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Basic quotations} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% Csquotes is able to interface with the babel package. To demonstrate that, +% we will occasionally change the document language. We start off with American +% English: + +\selectlanguage{american} + +\subsection{\languagename} + +% Getting started is simple: just load the package and use the command \enquote +% to enclose a piece of text in quotation marks: + +\example{1} \enquote{outer quote \enquote{inner quote} outer quote} + +% \enquote can detect nested quotations. It will toggle between outer and inner +% quotation marks depending on the nesting level. There is also a starred +% version of this command which jumps to the inner level right away: + +\example{2} \enquote*{inner quote} + +% 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 +% 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: +% +% \MakeOuterQuote{<character>} +% \MakeInnerQuote{<character>} +% \MakeAutoQuote{<first character>}{<second character>} +% +% \MakeOuterQuote and \MakeInnerQuote set up active characters which typeset +% outer or inner quotation marks respectively. +% +% Preamble: \MakeOuterQuote{"} + +\example{3} "outer quote" + +% Using the straight Ascii quote as an active quote is tempting. However, note +% that this may cause problems because it is used as an active character by +% several language extensions of the babel package. It will conflict with the +% following language extensions: +% +% Basque, Bulgarian, Catalan, Danish, Dutch, Estonian, Finnish, Galician, +% German, Greek, Icelandic, Italian, Latin, Norwegian, Polish, Portuguese, +% Russian, Serboportuguese, Slovenian, Spanish, Swedish, Ukrainian. +% +% Looks like a long list? It certainly is. But then again, you could use it in +% conjunction with the English or the French extensions. More hints concerning +% active characters will be given below, so make sure you read the entire +% tutorial. +% +% \MakeAutoQuote sets up two active characters that toggle between outer and +% inner quotation marks like the \enquote command. You need two distinct +% characters in this case. +% +% Preamble: \MakeAutoQuote{«}{»} + +\example{4} «outer quote «inner quote» outer quote» + +% Since the control sequences and active quotes of csquotes are essentially +% different frontends to a common backend, you may also mix them: + +\example{5} \enquote{outer quote «inner quote» outer quote} + +\example{6} "outer quote \enquote{inner quote} outer quote" + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% We're switching languages: + +\selectlanguage{french} + +\subsection{\languagename} + +% Csquotes will detect the change and adjust the quotation marks to the new +% language automatically: + +\example{1} les guillemets \enquote{à la française} + +% Of course the active quotes will obey the language change as well: + +\example{2} les guillemets «à la française» + +% A note about French: when using \enquote or active quotes, don't add any +% nonbreakable spaces. Csquotes will space out the guillemets automatically as +% is custom in French. The spacing is similar to what you get when using the +% commands \og and \fg provided by the French extension of the babel package +% and superior to explicit nonbreakable spaces. This feature is not hard-coded, +% it is part of the quote styles for French and could be modified if desired. + +\example{3} les guillemets \og à la française\fg + +\example{4} les guillemets "à la française" + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% We're switching languages once again: + +\selectlanguage{german} + +\subsection{\languagename} + +% ... and csquotes will adjust the quotation marks as well: + +\example{1} «Zitat «Zitat im Zitat» Zitat» + +% Before we continue with the multilingual capabilities of csquotes, a few +% general notes concerning active quotes are in order. + +% Like the quotation commands provided by csquotes, the active quotes are +% fully-fledged markup elements which allow for basic validation of the +% document structure. They differ substantially from the quote commands +% provided by the babel package. Conceptually, the latter are input aids. +% Babel's German extension, for example, provides the command \glqq and the +% shorthand "` to typset the opening quotation mark used in German: + +\example{2} \glqq Zitat\grqq\ "`Zitat"' + +% The shorthand "` is more convenient than something like \quotedblbase, but +% it's not different in concept. If you get the shorthands wrong by mixing up +% "` and "', TeX will happily typeset the wrong quotation marks without giving +% any warning: + +\example{3} "'Zitat"` + +% If you get the active quotes of this package wrong, TeX will bail out with an +% error message drawing you attention to the problem. This package tracks the +% nesting level of all quotations and issues an error message if they are +% nested in an invalid way. It also employs grouping to make sure that a +% quotation opened with an active quote is also closed properly. All active +% quotes have essentially the same effect as { and } or \begingroup and +% \endgroup. This means that active quotes must always be properly balanced and +% nested. +% +% Some grouping mistakes may trigger a generic TeX error. Note that packages +% cannot catch low-level errors caused by grouping mistakes, nor do they have +% any control over the wording of generic error messages. Error messages like: +% +% ! Missing } inserted. +% or +% ! Too many }'s. +% +% could be caused by unbalanced quotes or by intersecting groups. In some +% cases, all a package can do is make sure that there will be *some* kind of +% error message. Bear this in mind when tracking down the cause of such +% seemingly cryptical errors. When running under e-TeX, this package will +% generally catch more errors and print a specific error message instead. + +% When defining active quotes, make sure that they don't conflict with other +% packages. Several language extensions of the babel package use the Ascii +% double quote as a shorthand for diacritics and special hyphenation points. +% When switching to one of these languages with \selectlanguage (or any +% command/environment activating babel's specials locally), babel will +% overwrite the definitions set up by csquotes: + +\selectlanguage{german} + +\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 +% 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 because a lot of packages (including csquotes) defer the activation +% of such characters until \begin{document}. + +\RestoreQuotes + +\example{5} "Zitat" + +% Use \RestoreQuotes 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 +% using inputenc and csquotes. But sooner or later you might still need it to +% mark special hyphenation points. + +% Unfortunately, the choice of " as shorthand is hard-coded into babel. All you +% can do is work around the conflict by using babel's \aliasshorthand to define +% an alternative shorthand. This is accomplished by putting something like the +% following right after \begin{document}: +% +% \addto\extrasgerman{% +% \aliasshorthand{"}{|}% +% \RestoreQuotes} +% +% \selectlanguage{german} +% +% This will define the additional shorthand | which you may use instead of " +% for babel's shorthands. It will then reclaim " as an active quote. If you use +% several languages in your document, this step is required for every language +% using the " shorthand. The change will take effect after \selectlanguage or +% an equivalent command is given. + +% The above might be acceptable as a one-time workaround, but it is not really +% advisable as a general solution. Since the choice of active quotes is up to +% you, it is a good idea to choose characters which are not used by any other +% package in the first place. If you are using an input encoding like Latin 1 +% or Latin 9 anyway, I recommend using 8-bit characters as active quotes. Such +% characters will not conflict with other packages since they have to make do +% with Ascii for hard-wired active characters. The left and right guillemets +% («») used as an example here are particularly well suited for this purpose. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\selectlanguage{portuguese} + +\subsection{\languagename} + +% Quote styles for some of the languages covered by babel are still missing +% simply because I'm not familiar with the respective language and nobody has +% contributed a suitable style yet. In this case, csquotes will typeset bold +% question marks and issue a warning: + +\example{1} «citação» + +% You can easily add support for your language or change a predefined style. +% All you need to do is add a declaration to the configuration file, +% csquotes.cfg. Detailed instructions concerning this are included in the +% manual. The configuration file also includes some example styles. + +\selectlanguage{american} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Foreign language quotations} + +% In the following, we will have a closer look at the multilingual capabilities +% of csquotes. First of all, we're changing the default language: + +\selectlanguage{german} + +\example{1} «Zitat in der Standardsprache.» % "quote in the default language" + +% Babel offers environments for changing the language locally. This works just +% fine with csquotes: + +\begin{otherlanguage*}{american} + +\example{2} «This is a quote in a different language.» + +\end{otherlanguage*} + +% Babel's `hyphenrules' environment merely switches hyphenation patterns but +% does not affect the typesetting in any other way. Consequently, csquotes will +% not change the quotation mark style within this environment either: + +\begin{hyphenrules}{american} + +\example{3} «quote snippet in a different language» + +\end{hyphenrules} + +% Babel also features the command \foreignlanguage which changes the language +% for a foreign phrase embedded in the text body. This command corresponds to +% the `otherlanguage*' environment. Csquotes provides a command which combines +% the features of \foreignlanguage and \enquote: + +\example{4} \foreignquote{american}{This is a quote in a different language.} + +% In addition to that, csquotes provides an inline substitute for the +% `hyphenrules' environment which changes the hyphenation rules used within the +% quotation without adapting the quotation mark style: + +\example{5} \hyphenquote{american}{quote snippet in a different language} + +% Since the syntax of these commands is somewhat verbose you might want to +% build your own, shorter commands on top of them. Note that all \foreign... +% and \hyphen... commands take the language as their first argument, hence you +% can easily include the language in your own commands if you like: +% +% \newcommand*{\usquot}{\foreignquote{american}} +% \newcommand*{\frhyph}{\hyphenquote{french}} +% +% Which would be used as follows: +% +% \usquote{This is a quote in American English.} +% \frhyph{Voici une citation en français.} +% +% Or you might prefer using active quotes. There are two commands which +% facilitate that: +% +% \MakeForeignQuote{<language>}{<first character>}{<second character>} +% \MakeHyphenQuote{<language>}{<first character>}{<second character>} +% +% For example: +% +% \MakeForeignQuote{american}{<}{>} +% \MakeHyphenQuote{french}{«}{»} +% +% Which would be used as follows: +% +% <This is a quote in American English.> +% «Voici une citation en français.» + +\RestoreQuotes % because \selectlanguage{german} overwrites the " special +\selectlanguage{american} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Formal quotations} + +% A common requirement in academic writing demands that quotations be embedded +% in the flow of text if they are short but set off as an indented paragraph, a +% so-called block quotation, if they are longer than a certain number of lines. +% This package provides commands which will determine the number of lines +% required to typeset the quotation and then decide on the format +% automatically. + +\example{1} +This is some filler text demonstrating how the quotation is integrated with +the running text. \blockquote{This is a short quotation. Since it's shorter +than three lines it will be embedded in the running text.} This is some filler +text demonstrating how the quotation is integrated with the running text. +\blockquote{This is a long quotation. Since it's longer than three lines it +will be presented as an indented paragraph. By default, the csquotes package +will use the \texttt{quote} environment for block quotations. Both the line +threshold and the block quotation environment may be adapted to your +requirements.} This is some filler text demonstrating how the quotation is +integrated with the running text. + +% Formal quotations are always accompanied by a citation indicating the source +% of the quoted text. The citation will usually have a specific format which is +% used consistently throughout the entire text. For example, it might be +% enclosed in parentheses or put in a footnote. Therefore, the block quotation +% facilities take the citation as an optional argument and pass it to an +% auxiliary command called \mkcitation. This command may be redefined to format +% the citation. Here is an example: + +\renewcommand{\mkcitation}[1]{ (#1)} % this is the default + +\example{2} +This is some filler text demonstrating how the quotation is integrated with +the running text. \blockquote[Citation]{This is a short quotation. Since it's +shorter than three lines it will be embedded in the running text.} This is +some filler text demonstrating how the quotation is integrated with the +running text. \blockquote[Citation]{This is a long quotation. Since it's +longer than three lines it will be presented as an indented paragraph. By +default, the csquotes package will use the \texttt{quote} environment for +block quotations. Both the line threshold and the block quotation environment +may be adapted to your requirements.} This is some filler text demonstrating +how the quotation is integrated with the running text. + +% There is another useful command called \ifblockquote which you may use in the +% definition of \mkcitation to present the citation in a way that depends on +% the format of the corresponding quotation: + +\renewcommand{\mkcitation}[1]{% + \ifblockquote{\footnote{#1.}}{ (#1)}} + +% If the quotation is embedded in the running text, this definition will behave +% like the one discussed above. If the quotation is presented as a block +% quotation, however, the citation will be given in a footnote. + +\example{3} +This is some filler text demonstrating how the quotation is integrated with +the running text. \blockquote[Citation]{This is a short quotation. Since it's +shorter than three lines it will be embedded in the running text.} This is +some filler text demonstrating how the quotation is integrated with the +running text. \blockquote[Citation]{This is a long quotation. Since it's +longer than three lines it will be presented as an indented paragraph. By +default, the csquotes package will use the \texttt{quote} environment for +block quotations. Both the line threshold and the block quotation environment +may be adapted to your requirements.} This is some filler text demonstrating +how the quotation is integrated with the running text. + +% You may also want to present a quotation in inline or in display style, +% regardless of its length. That's what the text and display quotation +% facilities are for. Quotations typeset with the text quotation facilities +% look like a `short' quotation, those typeset by means of the display +% quotation facilities look like a `long' quotation. Citations are supported +% as well and will be formated consistently with \mkcitation. \ifblockquote +% will also work as expected in this context. +% +% This is the current definition of \mkcitation: +% +% \renewcommand{\mkcitation}[1]{% +% \ifblockquote{\footnote{#1.}}{ (#1)}} +% +% That's what a text quotation ... + +\example{4} +This is some filler text demonstrating how the quotation is integrated with +the running text. +\textquote[Citation]{This is a short quotation typeset with a text quotation +command. It would be presented in inline style even if it were longer than +three lines.} +This is some filler text demonstrating how the quotation is integrated with +the running text. + +% ... and a display quotation looks like: + +\example{5} +This is some filler text demonstrating how the quotation is integrated with +the running text. +\begin{displayquote}[Citation] +This is a fairly short quotation. Since it is enclosed in a +\texttt{displayquote} environment, however, it is typeset just like a long +one. +\end{displayquote} +This is some filler text demonstrating how the quotation is integrated with +the running text. + +% See the sections entitled "Fine-tuning block/display quotations" and +% "Fine-tuning terminal punctuation" for additional hints. + +% For the remaining examples, we restore the default definition: + +\renewcommand{\mkcitation}[1]{ (#1)} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% If you prefer using active quotes, you may do so with block quotations as +% well. In the preamble we already defined some active quotes including the +% following: +% +% \MakeBlockQuote{<}{|}{>} +% +% These active quotes are used as follows: + +\example{5} <quotation> + +\example{6} <quotation|citation> + +% This is equivalent to: +% +% \blockquote{quotation} +% \blockquote[citation]{quotation} +% +% The delimiter | separates the quotation from the citation. If the delimiter +% 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 +% limitation. + +% Let's go over our verbose example once again, using active quotes this time: + +\example{7} +This is some filler text demonstrating how the quotation is integrated with +the running text. <This is a short quotation. Since it's shorter than three +lines it will be embedded in the running text.|Citation> This is some filler +text demonstrating how the quotation is integrated with the running text. +<This is a long quotation. Since it's longer than three lines it will be +presented as an indented paragraph. By default, the csquotes package will use +the \texttt{quote} environment for block quotations. Both the line threshold +and the block quotation environment may be adapted to your +requirements.|Citation> This is some filler text demonstrating how the +quotation is integrated with the running text. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Integrated quotations} + +% For every quotation command/environment which takes a citation as an +% argument, there is also a corresponding `integrated' command/environment with +% the letter `c' for `cite' in its name: +% +% \textquote \textcquote +% \foreigntextquote \foreigntextcquote +% \hyphentextquote \hyphentextcquote +% +% \blockquote \blockcquote +% \foreignblockquote \foreignblockcquote +% \hyphenblockquote \hyphenblockcquote +% +% displayquote displaycquote +% foreigndisplayquote foreigndisplaycquote +% hyphendisplayquote hyphendisplaycquote +% +% 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. + +\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: +% +% \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: + +\example{3} \blockcquote[174]{citekey}{This is the quotation.} + +% The \cite command will format the citation in a certain way (it is enclosed +% in square brackets by default). Since csquotes' \mkcitation would interfere +% with \cite's formatting, all integrated quotation facilities use \mkccitation +% instead of \mkcitation. The citation arguments are handed over to \cite and +% this entire unit is passed to \mkccitation. +% +% When using citation packages such as cite, natbib, or jurabib, you might want +% to put the format of the citation completely under the control of the +% respective package and have \mkccitation do nothing at all: +% +% \renewcommand*{\mkccitation}[1]{#1} +% +% Obviously, anything inserted by \cite cannot be removed by \mkccitation. +% Hence you might need additional packages which redefine \cite in order to +% adjust the format of the automated citations. Here's an example using the +% cite package to present the citation in a way that is better suited for the +% author-year citation format: + +\renewcommand*{\mkccitation}[1]{ #1} % this is the default (note the space) +\renewcommand*{\citeleft}{(} % -> cite.sty +\renewcommand*{\citeright}{)} % -> cite.sty +\renewcommand*{\citemid}{, p.~} % -> cite.sty + +\example{4} \textcquote[174]{doe96}{This is the quotation.} + +% Of course you may also combine \mkccitation and the features of additional +% citation packages. Depending on the citation package, there may be more than +% one way to achieve a certain result. +% +% Suppose that we wanted to put all citations in a footnote. The jurabib +% package offers a \footcite command which does just that. In this case, +% \mkccitation need not do anything: +% +% \renewcommand*{\mkccitation}[1]{#1} +% \SetCiteCommand{\footcite} +% +% With natbib, \mkccitation may take care of the footnote but we still need to +% use an alternative \cite command to get a suitable citation format: +% +% \renewcommand*{\mkccitation}[1]{\footnote{#1}} +% \SetCiteCommand{\citealp} +% +% Here's one last example combining \mkccitation with the features of the cite +% package to achieve a similar result. \mkccitation will put the citation in a +% footnote while the cite package is used to format the citation: + +\renewcommand*{\mkccitation}[1]{\footnote{#1}} +\SetCiteCommand{\cite} + +\renewcommand*{\citeleft}{} +\renewcommand*{\citeright}{.} +\renewcommand*{\citemid}{, } + +\example{5} \blockcquote[174]{doe96}{This is the quotation.} + +% All of this also works with the text... + +\example{6} \textcquote[174]{doe96}{This is the quotation.} + +% ...and the display quotation facilities: + +\example{7} +This is some filler text. +\begin{displaycquote}[174]{doe96} +This is the quotation. +\end{displaycquote} +This is some filler text. + +% The natbib and jurabib packages redefine \cite so that it takes two optional +% arguments. If one of these packages is loaded, all integrated quotation +% facilities will automatically accept this additional argument as well: +% +% \usepackage{natbib} +% ... +% \textcquote[See][174]{doe96}{...} +% +% The citation arguments are handed over to \cite in the order in which they +% were given. How they are interpreted is at the discretion of \cite. With the +% natbib package, the first optional argument is a pre-note. With jurabib, it +% has a different function by default. + +% See the section entitled "Fine-tuning terminal punctuation" for additional +% hints. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Miscellaneous hints} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Fine-tuning block/display quotations} + +% The most frequent complaint about the traditional `quote' and `quotation' +% environments is that they do not adjust the font size of the quoted text. It +% is very common to set block quotations slightly smaller than the surrounding +% text. This problem is easily remedied: +% +% \newenvironment{smallquote} +% {\begin{quote}\small} +% {\end{quote}} +% +% Because of the way environments are implemented in LaTeX, it is better to +% avoid nesting \begin and \end when including an environment in the definition +% of another one. Another problem with this definition is that \small will +% effectively hard-code the font size. It is advisable to use the \smaller +% command from the relsize package. \smaller will decrease the font size by one +% step (from \normalsize to \small or from \footnotesize to \scriptsize) so +% that this environment will also work as expected when used in a footnote. +% +% Hence our final definition is written as follows: + +\newenvironment*{smallquote} + {\quote\smaller} + {\endquote} + +% Now we instruct csquotes to use the new environment: + +\SetBlockEnvironment{smallquote} + +\example{1} +This is some filler text. \blockquote{This is a quotation typeset with one of +the block quotation commands of the \texttt{csquotes} package. The block +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. + +% If you want to use this setup by default, add the following to csquotes.cfg: +% +% \RequirePackage{relsize} +% +% \newenvironment{smallquote} +% {\quote\smaller} +% {\endquote} +% +% \SetBlockEnvironment{smallquote} +% +% Of course you could also redefine the original `quote' environment, but keep +% in mind that the `quote' and `quotation' environments are not part of the +% LaTeX kernel. They are defined in the document class. Since any definition +% given in csquotes.cfg should be independent of the document class, it's +% better to build a new environment on top of `quote'. + +% For the next examples, we'll switch back to the default: + +\SetBlockEnvironment{quote} + +% You may have noticed that the first line of text after the quotation is not +% indented in the example above. This is possibly not what you would expect. +% However, this is in fact a feature of the standard `quote' environment which +% is used for long quotations by default. Strictly speaking, it is a feature of +% LaTeX's list environments and both `quote' and `quotation' are implemented as +% lists. If they are part of a paragraph, the first line after the environment +% will not be indented: + +\example{2} +This is some filler text. +\begin{quote} +This is a quotation typeset with the standard \texttt{quote} environment. In +the source of this example the environment is part of a paragraph, hence the +first line after the environment is not indented. +\end{quote} +This line is not indented. + +% If the environment is separated from the surrounding text by \par or by a +% blank line, the first line after the environment will get regular paragraph +% indentation: + +\example{3} +This is some filler text. + +\begin{quote} +This is a quotation typeset with the standard \texttt{quote} environment. In +the source of this example the environment is separated from the surrounding +text by blank lines, hence the first line after the environment gets regular +paragraph indentation. +\end{quote} + +This line gets regular paragraph indentation. + +% Block quotation commands such as \blockquote will usually be integrated in +% the text in the document source since \blockquote may decide to typeset its +% argument inline. When using the `quote' environment for long quotations, this +% implies that the first line after the environment will not get regular +% paragraph indentation: + +\example{4} +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 +quote commands will use the standard \texttt{quote} environment for long +quotations. Therefore, the first line after the block quotation is not +indented.} This line is not indented. + +% This behavior is perfectly in line with LaTeX's list environments, but it can +% lead to inconsistencies in the layout. The csquotes package will not insert +% an explicit \par before and after block quotations automatically since you +% might prefer it the other way and suppressing the indentation later on is a +% somewhat tricky thing to do. It is much easier to force indentation after +% paragraph quotations automatically. If you want to force indentation in all +% cases, a suitable environment is easily defined: +% +% \newenvironment*{paraquote} +% {\par\begin{quote}} +% {\end{quote}\par} +% +% As mentioned above, it is better to avoid nesting \begin and \end: + +\newenvironment*{paraquote} + {\begingroup\quote} + {\endquote\endgroup} + +% We instruct csquotes to use the new environment: + +\SetBlockEnvironment{paraquote} + +% Now all long quotes will be treated as separate paragraphs: + +\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 also part of a larger paragraph. However, the +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: +% +% \newenvironment*{smallparaquote} +% {\begingroup\quote\smaller} +% {\endquote\endgroup} +% +% \SetBlockEnvironment{smallparaquote} + +\subsection{Fine-tuning terminal punctuation} + +% Style guides often include subtleties such as detailed provisions concerning +% the placement of terminal punctuation. With \blockquote, such provisions can +% complicate matters quite a bit since you don't know in advance how the +% quotation is going to be typeset. +% +% The csquotes package is designed to cope with as many of these provisions as +% possible. The facilities for formal quotations provide a combination of +% `hooks' and tests which may be used to deal with them automatically. We'll +% consider MLA-style quotations as an example. The APA style uses a different +% citation format (author-year) but is very similar in concept otherwise. + +% The MLA style guide demands that quotations of up to four lines be set inline +% and quotations of five or more lines be presented as an indented paragraph. +% The \blockquote command and its various companions can deal with this task +% automatically. The required settings are obvious: + +\SetBlockThreshold{4} % the default is 3 lines +\SetBlockEnvironment{quote} % this is the default + +% The source of the quotation is indicated in the body by a short citation in +% parentheses. This is what the default definition of \mkcitation already does: + +\renewcommand*{\mkcitation}[1]{ (#1)} % this is the default + +% What complicates this further is the placement of the terminal punctuation. +% With long quotations, the period is simply placed at the end of the +% quotation. With short quotations, however, the final period is omitted from +% the quotation and placed after the whole unit formed by quotation and +% citation. This can be automated as follows: + +\renewcommand*{\mkmidblockpunct}[1]{% + \ifblockquote{.}{}} + +\renewcommand*{\mkfinblockpunct}[1]{% + \ifblockquote{}{.}} + +% Note that both \mkmidblockpunct and \mkfinblockpunct must take one mandatory +% 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: + +\example{1} +\blockquote[Doe 174]{This is a short quotation. The terminal period is omitted +from the quotation and inserted automatically} + +\blockquote[Doe 174]{This is a long quotation. Apart from this absolutely +pointless filler text (which serves no purpose whatsoever besides making the +quotation exceed the block threshold so that the command used to typeset the +quotation will finally have mercy and present it as an indented paragraph) it +is similar to the short quotation above. The terminal period is also omitted +from the quotation and inserted automatically} + +% But what if the quotation ends with a question mark? With short quotations +% there is no problem because the whole unit including the citation should +% still be closed with a terminal period. Therefore, our definition of +% \mkfinblockpunct does not require any adjustments. With long quotations, +% however, this would result in `?.' at the end of the quotation. We need an +% additional test in the definition of \mkmidblockpunct: \ifquotepunct tells +% us if the quotation ends with a punctuation mark. If so, we don't add a +% terminal period to the block quotations: + +\renewcommand*{\mkmidblockpunct}[1]{% + \ifblockquote + {\ifquotepunct{}{.}} + {}} + +\example{2} +\blockquote[Doe 174]{This is a short quotation ending with a question +mark. You see?} + +\blockquote[Doe 174]{This is a long quotation. Apart from this absolutely +pointless filler text (which serves no purpose whatsoever besides making the +quotation exceed the block threshold so that the command used to typeset the +quotation will finally have mercy and present it as an indented paragraph) it +is similar to the short quotation above. It also ends with a question mark. +You see?} + +% But it gets even more complicated. What about inline quotations with a +% terminal question mark which is not part of the quotation? For example, +% consider something like the following: +% +% Is it true, as Epimenides claims, that "all Cretans are liars"? +% +% This might be given as follows in the source document: +% +% Is it true, as Epimenides claims, that +% \blockquote[][?]{all Cretans are liars} +% +% Note that the `punctuation' argument is passed to both \mkmidblockpunct and +% \mkfinblockpunct. (But only on of them should actually insert it!) In the +% above definitions of these commands, the argument was simply discarded. Our +% final definitions will subject #1 to an \ifstringblank test to find out if +% the `punctuation' argument is used and handle it in an appropriate way: + +\renewcommand*{\mkmidblockpunct}[1]{% + \ifblockquote + {\ifstringblank{#1} + {\ifquotepunct{}{.}} + {}} + {}} + +\renewcommand*{\mkfinblockpunct}[1]{% + \ifblockquote + {\ifstringblank{#1}{}{#1}} + {\ifstringblank{#1}{.}{#1}}} + +\example{3} +\blockquote[Doe 174][?]{This is a short quotation closed with a question mark +which is not part of the quotation itself} + +\blockquote[Doe 174][?]{This is a long quotation. Apart from this absolutely +pointless filler text (which serves no purpose whatsoever besides making the +quotation exceed the block threshold so that the command used to typeset the +quotation will finally have mercy and present it as an indented paragraph) it +is similar to the short quotation above. It is closed with a question mark +which is not part of the quotation itself} + +% Setting the long quotation this way is not a good idea because it's still +% somewhat ambiguous. Let's make that more explicit: + +\renewcommand*{\mkmidblockpunct}[1]{% + \ifblockquote + {\ifstringblank{#1} + {\ifquotepunct{}{.}} + { [\dots\unkern]\,[#1]}} + {}} + +\renewcommand*{\mkfinblockpunct}[1]{% + \ifblockquote + {} + {\ifstringblank{#1}{.}{#1}}} + +\example{4} +\blockquote[Doe 174][?]{This is a short quotation closed with a question mark +which is not part of the quotation itself} + +\blockquote[Doe 174][?]{This is a long quotation. Apart from this absolutely +pointless filler text (which serves no purpose whatsoever besides making the +quotation exceed the block threshold so that the command used to typeset the +quotation will finally have mercy and present it as an indented paragraph) it +is similar to the short quotation above. It is closed with a question mark +which is not part of the quotation itself} + +% There's an additional benefit to this last solution: if you quote a partial +% sentence, that is, if the end of the quotation is not the end of the quoted +% sentence, you can have csquotes mark the omission automatically be passing +% a period as the optional `punctuation' argument: + +\blockquote[Doe 174][.]{This is a long quotation. Apart from this absolutely +pointless filler text (which serves no purpose whatsoever besides making the +quotation exceed the block threshold so that the command used to typeset the +quotation will finally have mercy and present it as an indented paragraph) it +is similar to the quotation above. In this case, however, the end of the +quotation is not the end of the quoted sentence%, which goes on like this. +} + +% For the remaining examples, we restore the defaults: + +\SetBlockThreshold{3} +\SetBlockEnvironment{quote} +\renewcommand*{\mkcitation}[1]{ (#1)} +\renewcommand*{\mkmidblockpunct}[1]{} +\renewcommand*{\mkfinblockpunct}[1]{#1} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Babel and csquotes} + +% Let's take another, more systematic look at the commands and environments +% provided by the babel package to see how csquotes fits into the picture. +% +% First of all, we (re)set the main document language to `american'. This will +% reset strings like \chaptername and the date as printed by \today to the +% defaults: + +\selectlanguage{american} + +\example{1} \chaptername: \today + +% Babel's `otherlanguage' environment switches hyphenation patterns and +% activates all extra definitions for the respective language, such as +% shorthands and language specific adjustments. It will also translate strings +% like \chaptername and localize the date format of \today. Essentially, it's +% like \selectlanguage but restricted to the scope of the environment. +% +% We'll use French as an example here because the language specific adjustments +% are obvious in this case (note the spaced out colon): + +{\begin{otherlanguage}{french} + +\example{2} \chaptername: \today + +\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. + +% The starred version of this environment switches hyphenation patterns and +% activates the language specific adjustments without modifying the strings: + +\begin{otherlanguage*}{french} + +\example{3} \chaptername: \today + +\end{otherlanguage*} + +% Babel's \foreignlanguage command is an inline version of the `otherlanguage*' +% environment: + +\example{4} \foreignlanguage{french}{\chaptername: \today} + +% Csquotes' \foreignquote command and all active quotes defined with +% \MakeForeignQuote behave the same as \foreignlanguage. The quotation mark +% style will be adapted to the language of the quotation: + +\example{5} \foreignquote{french}{\chaptername: \today} + +% Babel's `hyphenrules' environment switches hyphenation patterns without +% making any further adjustments. You won't see it in the typeset version of +% the example below, but inside the environment the active hyphenation patterns +% are actually the French ones while everything else adheres to the standards +% of the main document language (`american' here): + +\begin{hyphenrules}{french} + +\example{6} \chaptername: \today + +\end{hyphenrules} + +% The \hyphenquote command and all active quotes defined with \MakeHyphenQuote +% are inline versions of babel's `hyphenrules' environment plus quotation +% marks. They will switch hyphenation patterns without making any further +% adjustments. The quotation marks match the text surrounding the quotation: + +\example{7} \hyphenquote{french}{\chaptername: \today} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\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: + +\example{3} _$x_n$_ + +\example{4} ^$y^2$^ + +% We could push that even further by `quoting' math-mode material: + +\example{5} _$x_{\mbox{^$n^2$^}}$_ + +\example{6} _$y^{\mbox{^$x_n$^}}$_ + +% Just kidding... + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subsection{Literal active quotes} + +% 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: + +\example{1} \string" \string_ \string^ + +% If it is not, you need to use an alternative control sequence: + +\example{2} \guillemotleft\ \guillemotright + +% 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: + +\example{3} \string< | > + +\example{4} <quotation \string< {|} {>}|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. + +\clearpage + +% The bibliography is required by the integrated quotation commands discussed +% above. + +\begin{thebibliography}{Doe 1996} +\bibitem{citekey} This is an example\dots +\bibitem[Doe 1996]{doe96} This is an example\dots +\end{thebibliography} + +\end{document} |