diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/csquotes/README | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/csquotes/RELEASE | 12 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/csquotes/csquotes.pdf | bin | 241840 -> 241717 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/csquotes/csquotes.tex | 342 |
4 files changed, 193 insertions, 163 deletions
diff --git a/Master/texmf-dist/doc/latex/csquotes/README b/Master/texmf-dist/doc/latex/csquotes/README index 3d9726318dd..5987b594e25 100644 --- a/Master/texmf-dist/doc/latex/csquotes/README +++ b/Master/texmf-dist/doc/latex/csquotes/README @@ -1,4 +1,4 @@ -$Id: README,v 5.0c 2010/09/21 18:17:28 lehman stable $ +$Id: README,v 5.1 2010/11/19 15:15:40 lehman stable $ ABOUT diff --git a/Master/texmf-dist/doc/latex/csquotes/RELEASE b/Master/texmf-dist/doc/latex/csquotes/RELEASE index 779843535e0..20a4f1a72b5 100644 --- a/Master/texmf-dist/doc/latex/csquotes/RELEASE +++ b/Master/texmf-dist/doc/latex/csquotes/RELEASE @@ -1,4 +1,14 @@ -$Id: RELEASE,v 5.0c 2010/09/21 18:17:28 lehman stable $ +$Id: RELEASE,v 5.1 2010/11/19 15:15:40 lehman stable $ + +RELEASE NOTES FOR VERSION 5.1 + +* Improved block quotation facilities + + The hightlight of this release is an extension of the block + quotation facilities. When measuring the length of a quotation, + \blockquote and related commands can determine either the word + count or the number of lines. See the pointers in the changelog + for details. RELEASE NOTES FOR VERSION 5.0 diff --git a/Master/texmf-dist/doc/latex/csquotes/csquotes.pdf b/Master/texmf-dist/doc/latex/csquotes/csquotes.pdf Binary files differindex bfe84058075..c47901a29ca 100644 --- a/Master/texmf-dist/doc/latex/csquotes/csquotes.pdf +++ b/Master/texmf-dist/doc/latex/csquotes/csquotes.pdf diff --git a/Master/texmf-dist/doc/latex/csquotes/csquotes.tex b/Master/texmf-dist/doc/latex/csquotes/csquotes.tex index ef7bd4690f2..ccb64754e4d 100644 --- a/Master/texmf-dist/doc/latex/csquotes/csquotes.tex +++ b/Master/texmf-dist/doc/latex/csquotes/csquotes.tex @@ -1,5 +1,5 @@ -% $Id: csquotes.tex,v 5.0c 2010/09/21 18:17:28 lehman stable $ -\documentclass{ltxdockit}[2009/05/24] +% $Id: csquotes.tex,v 5.1 2010/11/19 15:15:40 lehman stable $ +\documentclass{ltxdockit}[2010/09/26] \usepackage[latin9]{inputenc} \usepackage[american]{babel} \usepackage[strict,autostyle=once]{csquotes} @@ -13,7 +13,7 @@ \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: csquotes.tex,v 5.0c 2010/09/21 18:17:28 lehman stable $} +\rcsid{$Id: csquotes.tex,v 5.1 2010/11/19 15:15:40 lehman stable $} \titlepage{% title={The \sty{csquotes} Package}, @@ -43,15 +43,8 @@ \newcommand*{\vcmd}[1]{\rotatehead{1.5em}{9.5em}{\cmd{#1}}} \newcommand*{\venv}[1]{\rotatehead{1.5em}{9.5em}{\env{#1}}} - -\ifpdf - \newcommand*{\rotatehead}[3]{% - \makebox[#1][c]{\rotatebox{90}{\makebox[#2][l]{\scriptsize #3}}}} -\else - \newcommand*{\rotatehead}[3]{% - \makebox[#1][c]{\rule{0pt}{#2}}} -\fi - +\newcommand*{\rotatehead}[3]{% + \makebox[#1][c]{\rotatebox{90}{\makebox[#2][l]{\scriptsize #3}}}} \newcommand{\tickmarkyes}{\Pisymbol{psy}{183}} \newcommand{\tickmarkno}{\textendash} @@ -61,7 +54,6 @@ \newcommand*{\mksample}[2][25]{% \mkmetrics[#1]{#2\,\textcolor{grid}{AaGg}\,#2}} - \newcommand*{\mkmetrics}[2][25]{% \setlength{\unitlength}{1pt}% \linethickness{0.25pt}% @@ -72,7 +64,6 @@ %\put(0,0){\parbox[b]{#1\unitlength}{\mkgrid{-\fontdimen11\font}}} \put(0,0){\parbox[b]{#1\unitlength}{\centering #2}} \end{picture}} - \newcommand*{\mkgrid}[1]{% \begingroup\color{grid}% \hrule height 0.25pt depth 0pt width \linewidth @@ -99,10 +90,13 @@ % hyphenation -\hyphenation{star-red} -\hyphenation{New-speak} -\hyphenation{thres-hold} -\hyphenation{re-pre-sent-ing} +\hyphenation{% + star-red + New-speak + thres-hold + re-pre-sent-ing + hand-ling +} \begin{document} @@ -115,7 +109,7 @@ \subsection[About]{About \sty{csquotes}} -This package provides advanced facilities for inline and display quotations. It is designed for a wide range of tasks ranging from the most simple applications to the more complex demands of formal quotations. The facilities include commands, environments, and user"=definable <smart quotes> which dynamically adjust to their context. Quotation marks are switched automatically if quotations are nested and can adjust to the current language. There are additional facilities designed to cope with the more specific demands of academic writing, especially in the humanities and the social sciences. All quote styles as well as the optional active quotes are freely configurable. +This package provides advanced facilities for inline and display quotations. It is designed for a wide range of tasks ranging from the most simple applications to the more complex demands of formal quotations. The facilities include commands, environments, and user"=definable <smart quotes> which dynamically adjust to their context. Quotation marks are switched automatically if quotations are nested and can adjust to the current language. There are additional features designed to cope with the more specific demands of academic writing. All quote styles as well as the optional active quotes are freely configurable. \subsection{License} @@ -139,17 +133,13 @@ All package options are given in \keyval syntax. This option turns all package warnings into error messages. This is useful to ensure that no problem will go unnoticed when finalizing a document. The short form \opt{strict} is equivalent to \kvopt{strict}{true}. -\intitem[2]{maxlevel} - -This option controls the maximum nesting level of quotations. By default, this package supports two levels of quotations, outer and inner ones, and issues an error if quotations are nested more deeply. Alternatively, it can reuse the outer and inner quotes on further quotation levels. This alternative behavior is enabled implicitly when increasing the value of the \opt{maxlevel} option. The minimum is~\texttt{2}. - \optitem[american]{style}{\prm{style}} This option selects a fixed quotation style. The style is used throughout the document unless it is changed manually, see \secref{bas:set} for details. This option implicitly sets \kvopt{autostyle}{false}. Please refer to \tabref{tab:sty,tab:als} for a list of available quote styles and aliases. See \secref{cfg:sty,cfg:als,use:spl} for instructions on adding or modifying quote styles. \optitem[tryonce]{autostyle}{\opt{true}, \opt{false}, \opt{try}, \opt{once}, \opt{tryonce}} -This option controls multilingual support. It requires either the \sty{babel} package or the \sty{polyglossia} package.\footnote{Note that \sty{polyglossia} support is currently in a preliminary state because \sty{polyglossia} does not make sufficient information available to other packages. In practice, this means that \sty{csquotes} can detect the language (\eg \texttt{english}) but not the language variant (\eg \texttt{british}).} \kvopt{autostyle}{true} continuously adapts the quote style to the current document language; \opt{once} will only adapt the style once so that it matches the main language of the document. \kvopt{autostyle}{try} and \opt{tryonce} are similar to \opt{true} and \opt{once} if multilingual support is available but will not issue any warnings if not (\ie if neither \sty{babel} nor \sty{polyglossia} have been loaded). The short form \opt{autostyle} is equivalent to \kvopt{autostyle}{true}. See also \secref{bas:set}. +This option controls multilingual support. It requires either the \sty{babel} package or the \sty{polyglossia} package.\footnote{Note that \sty{polyglossia} support is currently in a preliminary state because \sty{polyglossia} is lacking a proper interface for other packages. In practice, this means that \sty{csquotes} can detect the language (\eg \texttt{english}) but not the language variant (\eg \texttt{british}).} \kvopt{autostyle}{true} continuously adapts the quote style to the current document language; \opt{once} will only adapt the style once so that it matches the main language of the document. \kvopt{autostyle}{try} and \opt{tryonce} are similar to \opt{true} and \opt{once} if multilingual support is available but will not issue any warnings if not (\ie if neither \sty{babel} nor \sty{polyglossia} have been loaded). The short form \opt{autostyle} is equivalent to \kvopt{autostyle}{true}. See also \secref{bas:set}. \begin{table} \tablesetup @@ -184,13 +174,37 @@ Use the language options listed in \tabref{tab:lng} to choose a style variant if % Note that \sty{babel}'s language name is \opt{ngerman} here whereas \sty{csquotes} uses \opt{german}. When selecting a quote style automatically, this package will essentially normalize the language names first, using a list of aliases which map languages to quote styles. See \tabref{tab:als} for details. \Tabref{tab:lng} indicates the language options defined by default. Additional options may be defined in the configuration file. See \secref{cfg:opt,use:spl} for details. Also see \secref{hnt:pre} for some additional notes concerning the predefined styles. +\intitem[2]{maxlevel} + +This option controls the maximum nesting level of quotations. By default, this package supports two levels of quotations, outer and inner ones, and issues an error if quotations are nested more deeply. Alternatively, it can reuse the outer and inner quotes on further quotation levels. This alternative behavior is enabled implicitly when increasing the value of the \opt{maxlevel} option. The minimum is~\texttt{2}. + \boolitem[true]{autopunct} -This option controls whether quotation commands scan ahead for trailing punctuation marks. See \secref{bas:txt:reg,bas:blk:reg,int:txt:reg,int:blk:reg} for details. Also see \cmd{DeclareAutoPunct} in \secref{cfg:dap} and \secref{cfg:aux} on how to configure and use the punctuation look-ahead feature. +This option controls whether the quotation commands scan ahead for trailing punctuation marks. See \secref{bas:txt:reg,bas:blk:reg,int:txt:reg,int:blk:reg} for details. Also see \cmd{DeclareAutoPunct} in \secref{cfg:dap} and \secref{cfg:aux} on how to configure and use the punctuation look-ahead feature. The short form \opt{autopunct} is equivalent to \kvopt{autopunct}{true}. + +\intitem[3]{threshold} + +This option defines the number of lines or words the block quotation facilities use as a threshold when determining whether a quotation should be typeset in inline or in display mode. It corresponds to the \cmd{SetBlockThreshold} command. See \secref{bas:blk:reg, cfg:blk} for further details. + +\optitem[lines]{thresholdtype}{\opt{lines}, \opt{words}} + +This option selects the block threshold type. With \kvopt{thresholdtype}{lines}, the block quotation facilities will determine the number of lines required to typeset the quotation; with \kvopt{thresholdtype}{words}, they count the number of words in the quotation.\footnote{The word counting code is based on an idea by Donald Arseneau.} The default threshold setup is 3~lines. If you prefer something like 50~words, set \kvopt{threshold}{50} and \kvopt{thresholdtype}{words}. See \secref{bas:blk:reg} for further details. + +\boolitem[true]{parthreshold} + +This option fine-tunes the block threshold detection. If enabled, any explicit paragraph or line break in the quotation will trigger the threshold, \ie the quotation will be typeset in display mode regardless of its length. If disabled, explicit paragraph or line breaks are applied normally if \kvopt{thresholdtype}{lines}, and treated as a regular word boundary if \kvopt{thresholdtype}{words}. The short form \opt{parthreshold} is equivalent to \kvopt{parthreshold}{true}. + +\boolitem[true]{splitcomp} + +This option is applicable with \kvopt{thresholdtype}{words} only. It fine-tunes the handling of compounds with explicit hyphens. If enabled, compounds are split up at all hyphens and the components are counted as separate words. If disabled, compounds are treated as a single word. The short form \opt{splitcomp} is equivalent to \kvopt{splitcomp}{true}. \boolitem[false]{csdisplay} -By default, the block quotation facilities discussed in \secref{bas:blk:reg, bas:blk:bbl, int:blk:reg, int:blk:bbl} will automatically force inline quotations in footnotes, parboxes, minipages, and floats. Set this option to \texttt{true} to permit context sensitive display quotations in these contexts. This option may also be set locally with \cmd{csdisplaytrue} and \cmd{csdisplayfalse}, respectively. +By default, the block quotation facilities will automatically force inline quotations in footnotes, parboxes, minipages, and floats. Setting this option to \texttt{true} will permit context-sensitive switching to display quotations in these contexts, as in the text body. The short form \opt{csdisplay} is equivalent to \kvopt{csdisplay}{true}. This option may also be set locally with \cmd{csdisplaytrue} and \cmd{csdisplayfalse}, respectively. + +\boolitem[false]{debug} + +This option controls the debugging feature of the block quotation facilities. If enabled, all block quotation commands will output diagnostic messages to the transcript file. These messages indicate the calculated line\slash word count, explicit paragaph or line breaks detected in the quotation text, and the final inline\slash display determination. The short form \opt{debug} is equivalent to \kvopt{debug}{true}. \end{optionlist} @@ -201,11 +215,11 @@ By default, the block quotation facilities discussed in \secref{bas:blk:reg, bas \optitem{version}{\prm{version}, \opt{4.4}, \opt{3.6}, \opt{3.0}} -This option is an attempt at making \sty{csquotes} backwards compatible with earlier versions, at least to some extent. Currently, it supports backwards compatibility with version 4.4, which covers 3.7--4.4, version 3.6, which covers 3.1--3.6, and version 3.0. Older versions are not supported. It is possible to specify any arbitrary \prm{version}, even if it is not explicitly listed above. In this case, the package will keep increasing the \prm{version} number until it either finds a suitable compatibility mode or hits the current version number. For example, when specifying \kvopt{version}{4.0}, \sty{csquotes} will increase the version number until it hits 4.4, and activate the v4.4 compatibility mode because this is the highest version still compatible with the requested 4.0 release. This implies that \sty{csquotes} may be invoked in a, to some extent, <future proof> way by making the version which is current at the time of writing sticky. If future versions break backwards compatibility, they will automatically activate the best compatibility mode. If not, the \opt{version} option will simply not have any effect. +This option is an attempt at making \sty{csquotes} backwards compatible with earlier versions, at least to some extent. Currently, it supports backwards compatibility with version 4.4, which covers 3.7--4.4, version 3.6, which covers 3.1--3.6, and version 3.0. Older versions are not supported. It is possible to specify any arbitrary \prm{version}, even if it is not explicitly listed above. In this case, the package will keep increasing the \prm{version} number until it either finds a suitable compatibility mode or hits the current version number. For example, when specifying \kvopt{version}{4.0}, \sty{csquotes} will increase the version number until it hits 4.4, and activate the v4.4 compatibility mode because this is the highest version still compatible with the requested 4.0 release. This implies that \sty{csquotes} may be invoked in a, to some extent, <future proof> way by making the version which is current at the time of writing sticky. If future versions break backwards compatibility, they will automatically activate the best compatibility mode. If not, the \opt{version} option will simply have no effect. \optitem{babel}{\opt{true}, \opt{false}, \opt{try}, \opt{once}, \opt{tryonce}} -A legacy alias for the \opt{autostyle} option. This option is depreciated. +An older name of the \opt{autostyle} option. This option is depreciated. \end{optionlist} @@ -247,7 +261,6 @@ This command combines \cmd{enquote} with the \env{hyphenrules} environment, that \end{ltxsyntax} -\needspace{4\baselineskip} \subsection{Formal Quoting of Regular Text} \label{bas:txt:reg} @@ -293,13 +306,13 @@ This command combines \cmd{textquote} with the \env{hyphenrules} environment. Ap \subsection{Block Quoting of Regular Text} \label{bas:blk:reg} -A common requirement in academic writing demands that quotations be embedded in the text if they are short but set off as an indented paragraph if they are longer than a certain number of lines. In the latter case no quotation marks are inserted. The following command deals with this requirement automatically: +Formal requirements in academic writing frequently demand that quotations be embedded in the text if they are short but set off as a distinct and typically indented paragraph, a so-called block quotation, if they are longer than a certain number of lines or words. In the latter case no quotation marks are inserted. The following command deals with this requirement automatically: \begin{ltxsyntax} \cmditem{blockquote}[cite][punct]{text}<tpunct> -This command determines the number of lines required to typeset \prm{text}. If \prm{text} is longer than a given number of lines or if it spans more than one paragraph, it is wrapped in a block quotation environment. Otherwise \cmd{blockquote} behaves like \cmd{textquote}. The default threshold is three lines and the environment used for long quotations is the \env{quote} environment. See \secref{cfg:blk} on how to change these parameters. Note that \sty{csquotes} will force inline quotations in footnotes, parboxes, minipages, and floats by default. Use the \opt{csdisplay} option from \secref{opt:opt} to change this behavior. The optional arguments \prm{cite} and \prm{punct} specify the citation and any terminal punctuation of \prm{text}. \prm{tpunct} denotes trailing punctuation after the command. If the \opt{autopunct} option is enabled, the quotation commands will scan ahead for punctuation marks immediately following their last argument and can move them around if required. See \secref{cfg:aux} on how to change the way these arguments are handled and \secref{use:hok} for reasons why you may want to specify the punctuation as a separate argument. +This command determines the length of the \prm{text}. If the length exceeds a certain threshold, the \prm{text} will be typeset in display mode, \ie as a block quotation. If not, \cmd{blockquote} will behave like \cmd{textquote}. Depending on the \opt{thresholdtype} option, the threshold may be based on the number of lines required to typeset the \prm{text} or on the number of words in the \prm{text}. If the \opt{parthreshold} option has been enabled, any explicit paragraph or line break in the \prm{text} will trigger the threshold, \ie it will be typeset in display mode regardless of its length. The default threshold setup is three lines with \opt{parthreshold} enabled. The default environment used for display quotations is the \env{quote} environment. See \secref{opt:opt, cfg:blk} on how to change these parameters. Note that \sty{csquotes} will force inline quotations in footnotes, parboxes, minipages, and floats by default. Use the \opt{csdisplay} option from \secref{opt:opt} to change this behavior. The optional arguments \prm{cite} and \prm{punct} specify the citation and any terminal punctuation of the \prm{text}. \prm{tpunct} denotes trailing punctuation after the command. If the \opt{autopunct} option is enabled, the quotation commands will scan ahead for punctuation marks immediately following their last argument and can move them around if required. See \secref{cfg:aux} on how to change the way these arguments are handled and \secref{use:hok} for reasons why you may want to specify the punctuation as a separate argument. \end{ltxsyntax} @@ -324,7 +337,6 @@ This command behaves like \cmd{hyphenquote} if the quotation is short. If it exc \end{ltxsyntax} -\needspace{6\baselineskip} \subsection{Selecting Quote Styles} \label{bas:set} @@ -487,7 +499,7 @@ This command combines \cmd{textcquote} with the \env{hyphenrules} environment. T \subsection{Block Quoting of Regular Text} \label{int:blk:reg} -Block quotations may be combined with automated citations as well by using the extended version of \cmd{blockquote}: +Block quotations may be combined with automated citations by using the extended version of \cmd{blockquote}: \begin{ltxsyntax} @@ -544,7 +556,6 @@ This environment combines \env{displayquote} with \env{hyphenrules}. Apart from \end{ltxsyntax} -\needspace{4\baselineskip} \subsection{Integrated Display Environments} \label{env:cit} @@ -792,7 +803,7 @@ The following commands change the default values used by various quotation facil \cmditem{SetBlockEnvironment}{environment} \cmditem{SetCiteCommand}{command} -\cmd{SetBlockThreshold} changes the number of lines the block quotation facilities use as a threshold when deciding whether a quotation should be set inline or as a block quotation. The default is three lines. \cmd{SetBlockEnvironment} specifies the environment used for block and display quotations. It takes the name of an existing environment as its argument. The default is the \env{quote} environment provided by most document classes. The argument to \cmd{SetCiteCommand} specifies a replacement for \cmd{cite} which will be used by all integrated quotation facilities to handle citations. It must be a single command which takes one or two optional arguments followed by a mandatory one, the citation key. The default is \cmd{cite}. The citation commands of the \sty{natbib}, \sty{jurabib}, and \sty{biblatex} packages, which take two optional arguments, are supported. +\cmd{SetBlockThreshold} defines the number of lines or words the block quotation facilities use as a threshold when determining whether a quotation should be typeset in inline or in display mode. The default is three. \cmd{SetBlockEnvironment} specifies the environment used for block and display quotations. It takes the name of an existing environment as its argument. The default is the \env{quote} environment provided by most document classes. The argument to \cmd{SetCiteCommand} specifies a replacement for \cmd{cite} which will be used by all integrated quotation facilities to handle citations. It must be a single command which takes one or two optional arguments followed by a mandatory one, the citation key. The default is \cmd{cite}. The citation commands of the \sty{natbib}, \sty{jurabib}, and \sty{biblatex} packages, which take two optional arguments, are supported. \end{ltxsyntax} @@ -1040,6 +1051,7 @@ This section will give some comprehensive examples of how to define new quote st % Now suppose that we wanted to add a quote style for an imaginary language called Newspeak and that there were two quote styles commonly used in Newspeak, an official one and an unofficial one. In this case, we need two backend styles implemented as variants of the \opt{newspeak} style, \opt{newspeak/official} and \opt{newspeak/unofficial}: +\needspace{3\baselineskip} \begin{ltxcode} \DeclareQuoteStyle[official]{newspeak} {\textquotedblleft}{\textquotedblright} @@ -1169,7 +1181,7 @@ This is accomplished by the following definitions: \renewcommand{\mktextquote}[6]{#1#2#4#5#3#6} \end{ltxcode} % -The style commonly seen in French books uses semantically strict punctuation placement. The unusual aspect of this style is the footnote mark, which is placed inside the quotes, before the terminal punctuation mark. Given the above input, we need the following output: +The style usually seen in French books uses semantically strict punctuation placement. The unusual aspect of this style is the footnote mark, which is placed inside the quotes, before the terminal punctuation mark. Given the above input, we need the following output: \begin{quotesample}{french} \renewcommand{\mkcitation}[1]{\footnote{#1}} @@ -1186,7 +1198,7 @@ This is accomplished by the following definitions: \renewcommand{\mktextquote}[6]{#1#2#6#4#3#5} \end{ltxcode} % -Note that the spacing of the quotation marks, as is common in French typography, is handled automatically by the quote style, as defined with \cmd{DeclareQuoteStyle}. There is no need to deal with these details when redefining \cmd{mktextquote} and similar hooks. \cmd{mktextquote} will get the quotation marks plus spacing as parameters |#1| and |#3|. +Note that the spacing of the quotation marks, as is common in French typography, is handled by the quote style, as defined with \cmd{DeclareQuoteStyle}. There is no need to deal with these details when redefining \cmd{mktextquote} and similar hooks. \cmd{mktextquote} will get the quotation marks plus spacing as parameters |#1| and |#3|. In addition to language and style specific adaptions, the formatting hooks discussed in this section may be used to further automate the quoting process. For example, they can be configured to automatically insert an ellipsis mark when quoting a sentence truncated at the end. In the following examples, we assume these lines of input: @@ -1239,11 +1251,11 @@ The \cmd{ifpunct} test will check the last character in |#2| and omit the ellips \item \textquote[citation]{This is a complete sentence.} \end{quotesample} % -If you are using automated citations, it is convenient to employ the integrated quotations commands from \secref{cit}. For example, instead of this: +When using automated citations, it is convenient to employ the integrated quotations commands from \secref{cit}. For example, instead of this: \begin{ltxcode} -\textquote[citation][.]{This is a complete sentence} -\textquote[citation][]{This is an incomplete sentence}. +\textquote[{\cite[55]{key}}][.]{This is a complete sentence} +\textquote[{\cite[55]{key}}][]{This is an incomplete sentence}. \end{ltxcode} % you might use \cmd{textcquote} instead of \cmd{textquote}: @@ -1260,7 +1272,7 @@ The definition of the punctuation hooks is the same in both cases, but citations \renewcommand{\mkccitation}[1]{\footnote{#1}} \end{ltxcode} % -Some citation packages, such as \sty{natbib} and \sty{biblatex}, provide dedicated commands for various types of citations. It is advisable to use the appropriate citation command and hand control of citations to that command, \ie \cmd{mkccitation} is used only to insert an interword space where required, but will leave the rest to the citation command. In the case of \sty{biblatex}, this boils down to: +Advanced citation packages such as \sty{natbib} and \sty{biblatex} provide dedicated commands for various types of citations. In this case, it is advisable to hand control of citations to the respective citation command, \ie \cmd{mkccitation} is used to add spacing where required but will leave the rest to the citation command. In the case of \sty{biblatex}, this boils down to: \begin{ltxcode} \SetCiteCommand{\parencite} @@ -1282,12 +1294,12 @@ for citations in footnotes. \subsection{Input Encodings} \label{hnt:inc} -The active quotes provided by this package may depend on or benefit from the \sty{inputenc} package under certain circumstances. As long as the active quotes are in the range 0--127, there is no benefit in loading \sty{inputenc}. If you are using an 8-bit input encoding such as \opt{latin1}, \sty{inputenc} is required for the quotes to function properly in a verbatim context. It should therefore be loaded before any active quotes are allocated (not necessarily before this package is loaded). The \utf support of this package builds on the \path{utf8} module of the inputenc package. When using this encoding, ensure that inputenc is loaded with the \opt{utf8} option. Do not use the \opt{utf8x} option as this would implicitly load the \sty{ucs} package which is not supported by \sty{csquotes}. \utf encoding will be detected automatically. All commands discussed in \secref{act} work as usual with this encoding. See also \secref{hnt:mod}. +The active quotes provided by this package may depend on or benefit from the \sty{inputenc}\slash \sty{inputenx} packages under certain circumstances. As long as the active quotes are in the range 0--127, there is no benefit in loading \sty{inputenc}. If you are using an 8-bit input encoding such as \opt{latin1}, \sty{inputenc} is required for the quotes to function properly in a \emph{verbatim} context. It should therefore be loaded before any active quotes are allocated (not necessarily before \sty{csquotes} is loaded). The macro-level \utf support of this package builds on the \path{utf8} module of the inputenc package. When using this encoding, make sure that inputenc is loaded with the \opt{utf8} option. Do not use the \opt{utf8x} option as this would implicitly load the \sty{ucs} package which is not supported by \sty{csquotes}. \utf encoding will be detected automatically. All commands discussed in \secref{act} work as usual with this encoding. \xetex and \luatex in native \utf mode will also work as expected and do not require any additional packages. See also \secref{hnt:mod}. \subsection{Output Encodings} \label{hnt:onc} -The \acr{OT1} font encoding, the default output encoding of \latex, merely includes the quotation marks used in English. You will need to switch to an encoding like \acr{T1} or \acr{LY1} in order to get guillemets or baseline quotation marks. This package deliberately refrains from providing any workarounds for the \acr{OT1} legacy encoding. If you need \acr{T1} encoding for some of the quotation marks, you will most likely need it anyway to get proper hyphenation for the respective language. See \tabref{tab:out} for a list of common quotation marks included in both \acr{T1} and \acr{LY1} encoding. +The \acr{OT1} font encoding, which is the default output encoding of \latex, merely includes the quotation marks used in English. You will need an encoding like \acr{T1}, \acr{LY1}, or, with \xetex or \luatex, \acr{EU1}\slash \acr{EU2}, in order to get guillemets or baseline quotation marks. This package deliberately refrains from providing any workarounds for the \acr{OT1} legacy encoding. If you need \acr{T1} or some other extended encoding for some of the quotation marks, you will most likely need it anyway to get proper hyphenation for the respective language. See \tabref{tab:out} for a list of common quotation marks included in \acr{T1}, \acr{LY1}, and \acr{EU1}\slash \acr{EU2}. \begin{table} \tablesetup @@ -1310,7 +1322,7 @@ The \acr{OT1} font encoding, the default output encoding of \latex, merely inclu \cmd{guilsinglright} & \mksample[60]{\guilsinglright} \\ \bottomrule \end{tabularx} -\caption[Quotation Marks]{Quotation Marks Included in \acr{T1} and \acr{LY1} Encoding} +\caption[Quotation Marks]{Quotation Marks Provided by Encodings \acr{T1}, \acr{LY1}, \acr{EU1}\slash \acr{EU2}} \label{tab:out} \end{table} @@ -1327,16 +1339,14 @@ Every quotation forms a group which includes both the quoted piece of text and t \subsection{Active Quotes in Special Contexts} \label{hnt:mod} -The commands provided by this package are designed for use in text mode. If you inadvertently use them in math mode, they will issue an error message. Note that all active quotes retain their original function in math mode. It is perfectly possible to use a character like the greater-than symbol as an active quote without interfering with math mode. - -In a verbatim context, the active quotes will normally be disabled. If a character is in the range 128--255, however, its original function is restored so that the \sty{inputenc} package may handle it in verbatim environments. This implies that \sty{inputenc} must be loaded before any active quotes are allocated. This feature is available with the standard verbatim environments as well as those provided by (or defined via) the packages \sty{verbatim}, \sty{fancyvrb}, \sty{moreverb}, and \sty{alltt}. This also applies to the \cmd{verb} command and the \sty{shortvrb} package. The \sty{listings} package provides dedicated support for extended input encodings. When using this package, activate its <extended characters> option and specify the input encoding. As of this writing, the \sty{listings} package does not support \utf encoding. +All quotation commands are designed for use in text mode and will issue an error message in math mode. Note that all active quotes retain their original function in math mode. It is perfectly possible to use a character like the greater-than symbol as an active quote without interfering with math mode. In a verbatim context, the active quotes will normally be disabled. If a character is in the range 128--255, its original function is restored so that the \sty{inputenc}\slash \sty{inputenx} package may handle it in verbatim environments. This feature is available with the standard verbatim environments and with those provided by (or defined via) the packages \sty{verbatim}, \sty{fancyvrb}, \sty{moreverb}, and \sty{alltt}. This also applies to the \cmd{verb} command and the \sty{shortvrb} package. The \sty{listings} package provides dedicated support for extended input encodings. When using this package, activate its <extended characters> option and specify the input encoding. Note that \sty{listings} does not support macro-level \utf decoding. \xetex and \luatex in native \utf mode will work as expected and do not require the \sty{inputenc} package. Some care is still required when choosing active quotes. Note that you normally cannot use active characters in the argument to commands expecting a string of characters, such as \cmd{input}, \cmd{label}, or \cmd{cite}. There are two packages which try to remedy this situation: the \sty{babel} package and the \sty{underscore} package (when loaded with the \opt{strings} option). Both packages redefine several standard commands affected by this general problem. If any one of these packages is loaded, \sty{csquotes} will take advantage of all improvements automatically. Unfortunately, both packages patch a different set of commands and neither one covers all possibly vulnerable commands. \subsection{\pdf Strings and \sty{hyperref} Support} \label{hnt:pdf} -This package interfaces with the \sty{hyperref} package as \pdf strings such as bookmarks are generated. See \secref{cfg:pdf} on how to configure the quotation marks used in \pdf strings. Support for \pdf strings is only available with the basic facilities presented in \secref{bas:reg,bas:bbl} as well as \secref{act:reg,act:bbl}. Be advised that the way \sty{hyperref} builds \pdf strings imposes severe limitations on the capabilities of all commands. Most notably, the nesting level of quotations cannot be tracked in this context. Nested quotations will generally get outer marks, but you may use starred commands or active inner quotes to request inner marks explicitly. If quotation marks are to be included in the document properties of a \pdf file, you must use \cmd{hypersetup} to specify the strings. The replacement mechanism will not function within the optional argument to \cmd{usepackage}. For information about \pdf strings see the \sty{hyperref} documentation. +This package interfaces with the \sty{hyperref} package as \pdf strings such as bookmarks are generated. See \secref{cfg:pdf} on how to configure the quotation marks used in \pdf strings. Support for \pdf strings is only available with the basic facilities presented in \secref{bas:reg,bas:bbl} as well as \secref{act:reg,act:bbl}. Be advised that the way \sty{hyperref} builds \pdf strings imposes severe limitations on the capabilities of all commands. Most notably, the nesting level of quotations cannot be tracked in this context. Nested quotations will generally get outer marks, but you may use starred commands or active inner quotes to request inner marks explicitly. If quotation marks are to be included in the document properties of a \pdf file, you must use \cmd{hypersetup} to specify the strings. The replacement mechanism will not function within the optional argument to \cmd{usepackage}. See the \sty{hyperref} manual for information further details. \subsection{Footnotes Inside Quotations} \label{hnt:ftn} @@ -1448,7 +1458,7 @@ The \prm{code} may be arbitrary \latex code which redefines vulnerable commands \subsection{Registering Quotation Marks} \label{aut:sfc} -In order to track punctuation marks inside quotations, this package requires that all quotation marks be transparent to the space factor, \ie that they have a space factor code of zero. This setting is specific to the output encoding. Settings for the encodings \acr{OT1}, \acr{OT2}, \acr{OT4}, \acr{T1}, \acr{LY1}, \acr{LGR}, \acr{T2A}, \acr{T2B}, \acr{T2C}, \acr{LCY}, \acr{X2}, \acr{EU1}, and \acr{EU2} are provided by default. Other encodings may be set up in the configuration file using the following command: +In order to track punctuation marks inside quotations, this package requires that all quotation marks be transparent to the space factor, \ie that they have a space factor code of zero. This setting is specific to the output encoding. Settings for the encodings \acr{OT1}, \acr{OT2}, \acr{OT4}, \acr{T1}, \acr{LY1}, \acr{LGR}, \acr{T2A}, \acr{T2B}, \acr{T2C}, \acr{LCY}, \acr{X2}, and \acr{EU1}\slash \acr{EU2} are provided by default. Other encodings may be set up in the configuration file using the following command: \begin{ltxsyntax} \cmditem{DeclareQuoteGlyph}{encoding}{position} @@ -1522,6 +1532,16 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{changelog} +\begin{release}{5.1}{2010-11-19} +\item Added package option \opt{debug}\see{opt:opt} +\item Added package option \opt{threshold}\see{opt:opt} +\item Added package option \opt{thresholdtype}\see{opt:opt} +\item Added package option \opt{parthreshold}\see{opt:opt} +\item Added package option \opt{splitcomp}\see{opt:opt} +\item Improved block quotation facilities\see{bas:blk:reg} +\item Improved integrated block quotation facilities\see{int:blk:reg} +\end{release} + \begin{release}{5.0c}{2010-09-21} \item Added package option \opt{csdisplay}\see{opt:opt} \item Added \cmd{csdisplaytrue} and \cmd{csdisplayfalse}\see{opt:opt} @@ -1790,118 +1810,118 @@ This revision history is a list of changes relevant to users of this package. Ch \item Improved nesting control when running under \etex \end{release} -\begin{release}{2.8}{2005-05-11} -\item Added \cmd{DisableQuotes}\see{act:ctl} -\item Fixed bug causing kerning restoration to fail in some rare cases -\end{release} - -\begin{release}{2.7}{2005-04-13} -\item Use the font's kerning pairs for adjoining quotes, if available\see{cfg:sty} -\item Renamed \cmd{setblockthreshold} to \cmd{SetBlockThreshold}\see{cfg:blk} -\item Renamed \cmd{setblockenvironment} to \cmd{SetBlockEnvironment}\see{cfg:blk} -\item Provided more useful default definition of \cmd{blockcite}\see{cfg:aux} -\item Improved handling of adjoining quotes with respect to line breaking -\item When restoring active quotes, restore catcodes of delimiters as well -\item Improved workaround for \cmd{uppercase} and some \sty{babel} languages -\item Issue error message on quote mismatch regardless of \opt{strict} option -\item Issue \sty{hyperref} warning with block quotation commands in \pdf strings -\item Fixed bug in \cmd{DeclareQuoteStyle} and \cmd{DeclareQuoteAlias} -\end{release} - -\begin{release}{2.6}{2005-02-24} -\item Always reset quote style, even for inner quotations -\item Fixed bug preventing hyphenation in certain places -\end{release} - -\begin{release}{2.5}{2004-12-04} -\item Added \cmd{MakeBlockQuote}\see{act:blk:reg} -\item Added \cmd{MakeForeignBlockQuote}\see{act:blk:bbl} -\item Added \cmd{MakeHyphenBlockQuote}\see{act:blk:bbl} -\item Added \cmd{ifblockquote}\see{cfg:tst} -\item Modified \cmd{blockquote}\see{bas:blk:reg} -\item Modified \cmd{foreignblockquote}\see{bas:blk:bbl} -\item Modified \cmd{hyphenblockquote}\see{bas:blk:bbl} -\item Changed default threshold for block quotations\see{cfg:blk} -\item Improved math mode compatibility\see{hnt:mod} -\item Improved verbatim compatibility\see{hnt:mod} -\item Improved backend and active character handling -\item Improved validation of user"=defined active characters -\item Fixed bug suppressing kerning after block quotations -\item Issue error message with nested block quotations -\end{release} - -\begin{release}{2.4}{2004-11-01} -\item Prevent use of \cmd{RestoreQuotes} in preamble\see{act:ctl} -\item Fixed bug causing premature expansion of backend quote macros -\item Fixed bug suppressing kerning before closing quotes -\end{release} - -\begin{release}{2.3}{2004-09-18} -\item Reduced default kerning between adjoining curved quotes -\item Fixed bug with \cmd{DeclareQuoteStyle} in preamble -\end{release} - -\begin{release}{2.2}{2004-07-13} -\item Extended \cmd{DeclareQuoteStyle}\see{cfg:sty} -\item Added initialization hook for inner quotations\see{cfg:sty} -\item Added support for middle inner quotes\see{cfg:sty} -\item Rearranged French quote styles, removing two variants\see{hnt:pre} -\item Added new style variant for French\see{hnt:pre} -\item Fixed bug causing stacking of reset hook for footnotes -\item Fixed bug preventing hyphenation in certain places -\item Fixed kerning issue specific to \textsc{ec} fonts -\end{release} - -\begin{release}{2.1}{2004-06-15} -\item Added auxiliary environment \env{quoteblock}\see{cfg:aux} -\item Added support for language reset in footnotes\see{hnt:ftn} -\item Disable active characters in \cmd{verb} and \env{verbatim}\see{hnt:mod} -\item Disable active characters in \cmd{index} and \cmd{glossary}\see{hnt:mod} -\item Added package option and style variants for Norwegian -\item Removed some uncertain quote styles and aliases -\item Rearranged quote styles and aliases -\end{release} - -\begin{release}{2.0}{2004-06-04} -\item Added \cmd{blockquote}\see{bas:blk:reg} -\item Added \cmd{foreignblockquote}\see{bas:blk:bbl} -\item Added \cmd{hyphenblockquote}\see{bas:blk:bbl} -\item Added \cmd{setblockthreshold}\see{cfg:blk} -\item Added \cmd{setblockenvironment}\see{cfg:blk} -\item Added auxiliary command \cmd{blockcite}\see{cfg:aux} -\item Extended \cmd{DeclareQuoteStyle}\see{cfg:sty} -\item Added initialization hook for outer quotations\see{cfg:sty} -\item Added support for middle outer quotes\see{cfg:sty} -\item Added support for kerning between adjoining quotes\see{cfg:sty} -\item Disable active characters in math and display math mode\see{hnt:mod} -\item Revised and improved error recovery\see{opt:opt} -\item Added package option \opt{strict}\see{opt:opt} -\item Added package option and new style variants for French -\item Added package option and new style variant for Italian -\item Added new style variant for English -\end{release} - -\begin{release}{1.7}{2004-05-14} -\item Added \cmd{setquotestyle}\see{bas:set} -\item Modified \cmd{DeclarePlainStyle}\see{cfg:pdf} -\item Improved quote handling in \pdf strings\see{hnt:pdf} -\item Amended default French quote style\see{hnt:pre} -\end{release} - -\begin{release}{1.5}{2004-02-27} -\item Reset quote nesting level in footnotes within quotations\see{hnt:ftn} -\end{release} - -\begin{release}{1.4}{2003-12-13} -\item Added \cmd{MakeForeignQuote}\see{act:bbl} -\item Added \cmd{MakeHyphenQuote}\see{act:bbl} -\item Added \cmd{RestoreQuotes}\see{act:ctl} -\item Improved \sty{hyperref} interface\see{hnt:pdf} -\end{release} - -\begin{release}{1.0}{2003-09-14} -\item Initial public release -\end{release} +%\begin{release}{2.8}{2005-05-11} +%\item Added \cmd{DisableQuotes}\see{act:ctl} +%\item Fixed bug causing kerning restoration to fail in some rare cases +%\end{release} +% +%\begin{release}{2.7}{2005-04-13} +%\item Use the font's kerning pairs for adjoining quotes, if available\see{cfg:sty} +%\item Renamed \cmd{setblockthreshold} to \cmd{SetBlockThreshold}\see{cfg:blk} +%\item Renamed \cmd{setblockenvironment} to \cmd{SetBlockEnvironment}\see{cfg:blk} +%\item Provided more useful default definition of \cmd{blockcite}\see{cfg:aux} +%\item Improved handling of adjoining quotes with respect to line breaking +%\item When restoring active quotes, restore catcodes of delimiters as well +%\item Improved workaround for \cmd{uppercase} and some \sty{babel} languages +%\item Issue error message on quote mismatch regardless of \opt{strict} option +%\item Issue \sty{hyperref} warning with block quotation commands in \pdf strings +%\item Fixed bug in \cmd{DeclareQuoteStyle} and \cmd{DeclareQuoteAlias} +%\end{release} +% +%\begin{release}{2.6}{2005-02-24} +%\item Always reset quote style, even for inner quotations +%\item Fixed bug preventing hyphenation in certain places +%\end{release} +% +%\begin{release}{2.5}{2004-12-04} +%\item Added \cmd{MakeBlockQuote}\see{act:blk:reg} +%\item Added \cmd{MakeForeignBlockQuote}\see{act:blk:bbl} +%\item Added \cmd{MakeHyphenBlockQuote}\see{act:blk:bbl} +%\item Added \cmd{ifblockquote}\see{cfg:tst} +%\item Modified \cmd{blockquote}\see{bas:blk:reg} +%\item Modified \cmd{foreignblockquote}\see{bas:blk:bbl} +%\item Modified \cmd{hyphenblockquote}\see{bas:blk:bbl} +%\item Changed default threshold for block quotations\see{cfg:blk} +%\item Improved math mode compatibility\see{hnt:mod} +%\item Improved verbatim compatibility\see{hnt:mod} +%\item Improved backend and active character handling +%\item Improved validation of user"=defined active characters +%\item Fixed bug suppressing kerning after block quotations +%\item Issue error message with nested block quotations +%\end{release} +% +%\begin{release}{2.4}{2004-11-01} +%\item Prevent use of \cmd{RestoreQuotes} in preamble\see{act:ctl} +%\item Fixed bug causing premature expansion of backend quote macros +%\item Fixed bug suppressing kerning before closing quotes +%\end{release} +% +%\begin{release}{2.3}{2004-09-18} +%\item Reduced default kerning between adjoining curved quotes +%\item Fixed bug with \cmd{DeclareQuoteStyle} in preamble +%\end{release} +% +%\begin{release}{2.2}{2004-07-13} +%\item Extended \cmd{DeclareQuoteStyle}\see{cfg:sty} +%\item Added initialization hook for inner quotations\see{cfg:sty} +%\item Added support for middle inner quotes\see{cfg:sty} +%\item Rearranged French quote styles, removing two variants\see{hnt:pre} +%\item Added new style variant for French\see{hnt:pre} +%\item Fixed bug causing stacking of reset hook for footnotes +%\item Fixed bug preventing hyphenation in certain places +%\item Fixed kerning issue specific to \textsc{ec} fonts +%\end{release} +% +%\begin{release}{2.1}{2004-06-15} +%\item Added auxiliary environment \env{quoteblock}\see{cfg:aux} +%\item Added support for language reset in footnotes\see{hnt:ftn} +%\item Disable active characters in \cmd{verb} and \env{verbatim}\see{hnt:mod} +%\item Disable active characters in \cmd{index} and \cmd{glossary}\see{hnt:mod} +%\item Added package option and style variants for Norwegian +%\item Removed some uncertain quote styles and aliases +%\item Rearranged quote styles and aliases +%\end{release} +% +%\begin{release}{2.0}{2004-06-04} +%\item Added \cmd{blockquote}\see{bas:blk:reg} +%\item Added \cmd{foreignblockquote}\see{bas:blk:bbl} +%\item Added \cmd{hyphenblockquote}\see{bas:blk:bbl} +%\item Added \cmd{setblockthreshold}\see{cfg:blk} +%\item Added \cmd{setblockenvironment}\see{cfg:blk} +%\item Added auxiliary command \cmd{blockcite}\see{cfg:aux} +%\item Extended \cmd{DeclareQuoteStyle}\see{cfg:sty} +%\item Added initialization hook for outer quotations\see{cfg:sty} +%\item Added support for middle outer quotes\see{cfg:sty} +%\item Added support for kerning between adjoining quotes\see{cfg:sty} +%\item Disable active characters in math and display math mode\see{hnt:mod} +%\item Revised and improved error recovery\see{opt:opt} +%\item Added package option \opt{strict}\see{opt:opt} +%\item Added package option and new style variants for French +%\item Added package option and new style variant for Italian +%\item Added new style variant for English +%\end{release} +% +%\begin{release}{1.7}{2004-05-14} +%\item Added \cmd{setquotestyle}\see{bas:set} +%\item Modified \cmd{DeclarePlainStyle}\see{cfg:pdf} +%\item Improved quote handling in \pdf strings\see{hnt:pdf} +%\item Amended default French quote style\see{hnt:pre} +%\end{release} +% +%\begin{release}{1.5}{2004-02-27} +%\item Reset quote nesting level in footnotes within quotations\see{hnt:ftn} +%\end{release} +% +%\begin{release}{1.4}{2003-12-13} +%\item Added \cmd{MakeForeignQuote}\see{act:bbl} +%\item Added \cmd{MakeHyphenQuote}\see{act:bbl} +%\item Added \cmd{RestoreQuotes}\see{act:ctl} +%\item Improved \sty{hyperref} interface\see{hnt:pdf} +%\end{release} +% +%\begin{release}{1.0}{2003-09-14} +%\item Initial public release +%\end{release} \end{changelog} |