path: root/Master/texmf-dist/doc/latex/csquotes/tutorial.tex

% $Id: tutorial.tex,v 3.4 2006/04/02 15:58:08 lehman stable $
%
% This tutorial will give you an introduction to the csquotes package by way of
% example. All the instructions are included as comments in this file. There is
% 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{<}{|}{>}

% In general, an active quote must be a single character with category code 12
% or 13 (or a valid UTF-8 sequence representing a single character, if you are
% using UTF-8 encoding). The csquotes package will automatically check all
% characters for validity as you allocate them with a command like
% \MakeOuterQuote. Apart from characters which are not suitable because of
% their category code, csquotes will also reject numbers, punctuation marks,
% the apostrophe, and all characters which are part of LaTeX's syntax or
% reserved for a specific purpose (such as '*', '[', ']', '~'). If you are
% unsure, there is no harm in trying. If a character you choose is unsuitable,
% csquotes will issue an error message.

% Some additional packages used or discussed in this tutorial:
\usepackage[noadjust]{cite}
\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 as a control sequence. Think of them as `smart quotes' done
% right. The active characters are defined in the document preamble or in the
% configuration file. There are several commands which make that a trivial
% task:
%
% \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 \EnableQuotes. This command will replay the
% definitions of all active quotes recorded in the configuration file and the
% preamble. Note that it doesn't make sense to use \EnableQuotes in the
% preamble because a lot of packages (including csquotes) defer the activation
% of such characters until \begin{document}.

\EnableQuotes

\example{5} "Zitat"

% Use \EnableQuotes with care as you may break other packages by reclaiming
% active quotes. Even if things don't break outright, you might loose
% functionality. With babel's German extension, for example, you can do without
% the " shorthand as far as diacritics and (babel's) quotes are concerned when
% 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{"}{|}%
%   \EnableQuotes}
%
% \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.»

\EnableQuotes % 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 "Controlling 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. You would normally give a citation like that:

\example{1} \enquote{This is the quotation.} \cite[174]{citekey}

% 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:

\example{2} \textcquote[174]{citekey}{This is the quotation.}

% This works with block quotations as well:

\example{3} \blockcquote[174]{citekey}{This is the quotation.}

% 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}{, p.~}

\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.

% All adjustments made by means of \SetBlockEnvironment will automatically
% apply to the `display' environments as well:

\example{2}
This is some filler text.
\begin{displayquote}
This is a quotation typeset with one of the quotation environments of the
\texttt{csquotes} package. Quotations typeset by way of these environments
will behave exactely like a long quotation set with the block quotation
commands.
\end{displayquote}
This is some filler text.

% If you want to use this setup by default, add the following to csquotes.cfg:
%
%    \RequirePackage{relsize}
%
%    \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{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 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{4}
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{5}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. In the source
of this example the quotation is part of a paragraph. By default, the block
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{6}
This is some filler text. \blockquote{This is a quotation typeset with one of
the block quotation commands of the \texttt{csquotes} package. In the source
of this example the quotation is also part of a larger paragraph. However, the
block quotation environment has been redefined so that the first line after
the quotation gets regular paragraph indentation.} This line gets regular
paragraph indentation.

% 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.
%
% Now, 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{Controlling active quotes}

% Once made active, the active quotes cannot be used any more as if they were
% ordinary characters. You may always include them literally in the text by
% using a verbatim environment, but it is also possible to control their
% current state in situations in which a verbatim environment is not feasible.

% The commands \EnableQuotes and \DisableQuotes will turn the active quotes on
% and off:

\example{1}
"text" «text» <text>

\DisableQuotes
"" «» <>

\EnableQuotes
"text" «text» <text>

% Like verbatim environments, these commands modify category codes. This
% implies that you cannot use them to change the behavior of the argument read
% in by a command. In this case, use \VerbatimQuotes instead. This command
% will print all active quotes literally without changing category codes.
% Since the scope of this command is local, you don't even need \EnableQuotes
% if you put everything in a group. Here's an example:

\newcommand{\printverbquotes}[1]{\begingroup\VerbatimQuotes #1\endgroup}

\example{2}
"text" «text» <text>

\printverbquotes{"" «» <>}

"text" «text» <text>

% Note that the situation is slighly different with active block quotes. Only
% the opening mark really is an active quote. The delimiter and the closing
% mark are also active characters, but their behavior is different. Outside
% the scope of a block quotation they may be employed as usual:

\example{3} \printverbquotes{<} | >

% When included in a block quotation, however, they would confuse TeX's
% argument scanner. You can prevent that by wrapping the offending character
% in curly brackets:

\example{4} <quotation \printverbquotes{<} {|} {>}|citation>

% Of course you can always use control sequences instead:

\example{5} <quotation \textless\ \textbar\ \textgreater|citation>

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% 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}