From b4fc5f639874db951177ec539299d20908adb654 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 9 Jan 2006 00:44:40 +0000
Subject: doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/latex/csquotes/tutorial.tex | 1155 +++++++++++++++++++++
 1 file changed, 1155 insertions(+)
 create mode 100644 Master/texmf-dist/doc/latex/csquotes/tutorial.tex

(limited to 'Master/texmf-dist/doc/latex/csquotes/tutorial.tex')

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}
-- 
cgit v1.2.3

