summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/csquotes/csquotes.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-05-30 22:56:17 +0000
committerKarl Berry <karl@freefriends.org>2009-05-30 22:56:17 +0000
commitbce65f52a3f2fd1c56c758f8d3440caac7dd2549 (patch)
tree619be4a5a84c6c2baf88659a7316ce51f613ae34 /Master/texmf-dist/doc/latex/csquotes/csquotes.tex
parent002b09de2b07d6155b7dca17dace030555dfe592 (diff)
csquotes 4.4 (30may09)
git-svn-id: svn://tug.org/texlive/trunk@13534 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/csquotes/csquotes.tex')
-rw-r--r--Master/texmf-dist/doc/latex/csquotes/csquotes.tex177
1 files changed, 103 insertions, 74 deletions
diff --git a/Master/texmf-dist/doc/latex/csquotes/csquotes.tex b/Master/texmf-dist/doc/latex/csquotes/csquotes.tex
index 27265076df5..b1374be4281 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 4.3 2008/11/23 16:02:45 lehman stable $
-\documentclass{ltxdockit}
+% $Id: csquotes.tex,v 4.4 2009/05/30 13:12:20 lehman stable $
+\documentclass{ltxdockit}[2009/05/24]
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
\usepackage[strict,babel=once]{csquotes}
@@ -12,7 +12,7 @@
\MakeAutoQuote*{<}{>}
\MakeShortVerb{\|}
-\rcsid{$Id: csquotes.tex,v 4.3 2008/11/23 16:02:45 lehman stable $}
+\rcsid{$Id: csquotes.tex,v 4.4 2009/05/30 13:12:20 lehman stable $}
\titlepage{%
title={The \sty{csquotes} package},
@@ -100,35 +100,54 @@ This document is a systematic reference manual for the \sty{csquotes} package. I
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.
-\subsection{Requirements}
-\label{int:req}
+\subsection{License}
-This package requires \etex and the \sty{etoolbox} package which is readily available from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/} \tex distributions have been shipping \etex binaries for quite some time, most distributions even use them by default these days. The \sty{csquotes} package checks if it is running under \etex. Simply try compiling your documents as you usually do, the chances are that it just works. If you get an error message, try compiling the document with \path{elatex} instead of \path{latex} or \path{pdfelatex} instead of \path{pdflatex}, respectively.
+Copyright © 2003--2009 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3c.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/csquotes/LICENSE}
+%\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt}
+This package is author"=maintained.
-\subsection{License}
+\subsection{Acknowledgments}
-Copyright © 2003--2008 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained.
+I am indebted to Donald Arseneau, Mark Wooding, and David Carlisle for valuable hints in the early stages of development. Frank Mittelbach kindly provided hooks in the \sty{inputenc} package. Additional thanks go to Robert Schlicht for his testing.
\subsection{Contributions}
-The multilingual support of this package depends on user contributions. If you want to contribute a quote style, please refer to section \ref{cfg:sty} for an overview of the components a quote style is composed of and to table \ref{hnt:onc:tab} for a list of commands which should be used in the definition of quote styles.
+The multilingual support of this package depends on user contributions. If you want to contribute a quote style, please refer to section \ref{cfg:sty} for an overview of the components a quote style is composed of and to table \ref{tab:out} for a list of commands which should be used in the definition of quote styles.
-\subsection{Acknowledgments}
+\subsection{Requirements}
+\label{int:req}
-I am indebted to Donald Arseneau, Mark Wooding, and David Carlisle for valuable hints in the early stages of development. Frank Mittelbach kindly provided hooks in the \sty{inputenc} package. Additional thanks go to Robert Schlicht.
+This package requires \etex and the \sty{etoolbox} package which is readily available from \acr{CTAN}.\fnurl{http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/} \tex distributions have been shipping \etex binaries for quite some time, most distributions even use them by default these days. The \sty{csquotes} package checks if it is running under \etex. Simply try compiling your documents as you usually do, the chances are that it just works. If you get an error message, try compiling the document with \path{elatex} instead of \path{latex} or \path{pdfelatex} instead of \path{pdflatex}, respectively.
\section{Package options}
\label{opt}
+All package options are given in \keyval syntax.
+
+\begin{optionlist}
+
+\boolitem[false]{strict}
+
+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}.
+
+\optitem[tryonce]{babel}{\opt{true}, \opt{false}, \opt{try}, \opt{once}, \opt{tryonce}}
+
+This option controls multilingual support. \kvopt{babel}{true} continuously adapts the quote style to the language of the \sty{babel} package; \opt{once} will only adapt the style once so that it matches \sty{babel}'s main language. \kvopt{babel}{try} and \opt{tryonce} are similar to \opt{true} and \opt{once} if \sty{babel} is loaded but will not issue any warnings if it is not. The short form \opt{babel} is equivalent to \kvopt{babel}{true}. See also section \ref{bas:set}.
+
+\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 section \ref{bas:set} for details. This option implicitly sets \kvopt{babel}{false}. Please refer to tables \ref{tab:sty} and \ref{tab:als} for a list of available quote styles and aliases. See sections \ref{cfg:sty}, \ref{cfg:als}, and \ref{cfg:spl} for instructions on adding or modifying quote styles.
+
\begin{table}
\tablesetup
\begin{tabularx}{\columnwidth}{@{}P@{}X@{}}
\toprule
\multicolumn{1}{@{}H}{Option key} & \multicolumn{1}{@{}H}{Possible values} \\
\cmidrule(r){1-1}\cmidrule{2-2}
- strict & true, false \\
- babel & true, false, try, once, tryonce \\
- style & \prm{style} or \prm{alias} \\
danish & quotes, guillemets \\
english & american, british\\
french & quotes, quotes\*, guillemets, guillemets\*\\
@@ -139,38 +158,22 @@ I am indebted to Donald Arseneau, Mark Wooding, and David Carlisle for valuable
swedish & quotes, guillemets, guillemets\*\\
\bottomrule
\end{tabularx}
-\caption[Package options]{Package options defined by default}
-\label{opt:tab}
+\caption[Language options]{Language options defined by default}
+\label{tab:lng}
\end{table}
-Package options are given in \keyval syntax. Table \ref{opt:tab} indicates the default option keys and their possible values. Additional options may be defined in the configuration file. See sections \ref{cfg:opt} and \ref{cfg:spl} for details.
-
-\subsection{The \opt{strict} option}
-\label{opt:sct}
-
-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}.
-
-\subsection{The \opt{babel} option}
-\label{opt:bbl}
+\varitem{language}{\prm{variant}}
-Controls multilingual support. \kvopt{babel}{true} continuously adapts the quote style to the language of the \sty{babel} package. \kvopt{babel}{once} will only adapt the style once so that it matches \sty{babel}'s main language. \kvopt{babel}{try} and \kvopt{babel}{tryonce} are similar to \kvopt{babel}{true} and \kvopt{babel}{once} if \sty{babel} is loaded but will not issue any warnings if it is not. The short form \opt{babel} is equivalent to \kvopt{babel}{true}. The default setting is \kvopt{babel}{tryonce}. See also section \ref{bas:set}.
-
-\subsection{The \opt{style} option}
-\label{opt:sty}
-
-Selects a fixed quotation style. The style is used throughout the document unless it is changed manually, see section \ref{bas:set} for details. This option implicitly sets \kvopt{babel}{false}. Please refer to tables \ref{cfg:sty:tab} and \ref{cfg:als:tab} for a list of available quote styles and aliases. See sections \ref{cfg:sty}, \ref{cfg:als}, and \ref{cfg:spl} for instructions on adding or modifying quote styles.
-
-\subsection{The language options}
-\label{opt:lng}
-
-Use the language options listed in table \ref{opt:tab} to choose a style variant if there is more than one. The first variant in the list is the default for the respective style. In the following example, the quote style would generally be adapted to the current language using the default style for that language. In the English parts of the text, the quotation marks would follow the British standard. The German parts would use guillemets instead of curly quotes:
+Use the language options listed in table \ref{tab:lng} to choose a style variant if there is more than one for a certain language. The first variant in the list is the default for the respective style. In the following example, the quote style would generally be adapted to the current language using the default style for that language. In the English parts of the text, the quotation marks would follow the British standard. The German parts would use guillemets instead of curly quotes:
\begin{ltxcode}
\usepackage[english,ngerman]{babel}
\usepackage[babel,english=british,german=guillemets]{csquotes}
\end{ltxcode}
%
-Note that \sty{babel}'s language name is \opt{ngerman} here whereas this package 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 section \ref{cfg:spl} and table \ref{cfg:als:tab} for details. See section \ref{hnt:lng} for some additional notes concerning the predefined styles.
+Note that \sty{babel}'s language name is \opt{ngerman} here whereas this package 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 table \ref{tab:als} for details. Table \ref{tab:lng} indicates the language options defined by default. Additional options may be defined in the configuration file. See sections \ref{cfg:opt} and \ref{cfg:spl} for details. Also see section \ref{hnt:pre} for some additional notes concerning the predefined styles.
+
+\end{optionlist}
\section{Basic interface}
\label{bas}
@@ -293,7 +296,7 @@ Quote styles may be selected manually at any point in the document body by way o
\cmditem*{setquotestyle}{alias}
\cmditem*{setquotestyle}*
-The regular form of this command selects a quote style and disables multilingual support. Its mandatory argument may be a quote style or an alias. If it is a quote style, the optional argument indicates the style variant. The starred version, which takes no arguments, enables multilingual support. Please refer to tables \ref{cfg:sty:tab} and \ref{cfg:als:tab} for a list of available styles, style variants, and language aliases.
+The regular form of this command selects a quote style and disables multilingual support. Its mandatory argument may be a quote style or an alias. If it is a quote style, the optional argument indicates the style variant. The starred version, which takes no arguments, enables multilingual support. Please refer to tables \ref{tab:sty} and \ref{tab:als} for a list of available styles, style variants, and language aliases.
\end{ltxsyntax}
@@ -529,12 +532,13 @@ If available, this package will load the configuration file \path{csquotes.cfg}.
german & quotes, guillemets, swiss \\
italian & quotes, guillemets \\
norwegian & guillemets, quotes \\
+ russian & -- \\
spanish & spanish, mexican \\
swedish & quotes, guillemets, guillemets\*\\
\bottomrule
\end{tabularx}
\caption[Styles and variants]{Quote styles and style variants defined by default}
-\label{cfg:sty:tab}
+\label{tab:sty}
\end{table}
\subsection{Defining quote styles}
@@ -548,9 +552,7 @@ The following command defines additional quote styles and variants or redefines
{opening outer mark}[middle outer mark]{closing outer mark}[kern]\\
{opening inner mark}[middle inner mark]{closing inner mark}
-This command may be used in the configuration file or in the document preamble. The term <outer> refers to the first quotation level, <inner> means quotations within another quotation. A <middle mark> is a quotation mark inserted at the beginning of every paragraph within a quotation spanning multiple paragraphs. In most cases, the arguments defining the quotation marks will simply contain one of the commands listed in table \ref{hnt:onc:tab}. If both an outer and an inner quotation begin or end simultaneously, the kerning specified by the value \prm{kern} will be inserted between the adjoining quotation marks. While this value can be given in any unit known to \tex, it is advisable to use the relative, font"=dependent unit <em> instead of absolute units such as points, inches, or millimeters. Note that \prm{kern} is used as a fallback value only. If the font provides kerning data for the respective pair of quotation marks the font's kerning takes precedence.
-
-\prm{outer init} and \prm{inner init} are all"=purpose hooks initializing the quote style. Selecting a quote style will make these hooks available to all quotation commands without expanding them. The execution of \prm{outer init} will take place immediately before the opening outer quote is inserted, but inside the group formed by the quotation. \prm{inner init} is executed before the opening inner quote is inserted. It is advisable to avoid any global assignments in this context to prevent interference with other styles. Whenever \prm{inner init} is used \prm{outer init} has to be given as well, even if the argument is empty. Refer to table \ref{cfg:sty:tab} for a list of all predefined quote styles and their variants. These are the backend styles only, see also table \ref{cfg:als:tab} for a list of language aliases. See section \ref{cfg:spl} for some examples as well as an illustration of how quote styles, aliases, and package options interact.
+This command may be used in the configuration file or in the document preamble. The term <outer> refers to the first quotation level, <inner> means quotations within another quotation. A <middle mark> is a quotation mark inserted at the beginning of every paragraph within a quotation spanning multiple paragraphs. In most cases, the arguments defining the quotation marks will simply contain one of the commands listed in table \ref{tab:out}. If both an outer and an inner quotation begin or end simultaneously, the kerning specified by the value \prm{kern} will be inserted between the adjoining quotation marks. While this value can be given in any unit known to \tex, it is advisable to use the relative, font"=dependent unit <em> instead of absolute units such as points, inches, or millimeters. Note that \prm{kern} is used as a fallback value only. If the font provides kerning data for the respective pair of quotation marks the font's kerning takes precedence. \prm{outer init} and \prm{inner init} are all"=purpose hooks initializing the quote style. Selecting a quote style will make these hooks available to all quotation commands without expanding them. The execution of \prm{outer init} will take place immediately before the opening outer quote is inserted, but inside the group formed by the quotation. \prm{inner init} is executed before the opening inner quote is inserted. It is advisable to avoid any global assignments in this context to prevent interference with other styles. Whenever \prm{inner init} is used \prm{outer init} has to be given as well, even if the argument is empty. Refer to table \ref{tab:sty} for a list of all predefined quote styles and their variants. These are the backend styles only, see also table \ref{tab:als} for a list of language aliases. See section \ref{cfg:spl} for some examples as well as an illustration of how quote styles, aliases, and package options interact.
\end{ltxsyntax}
@@ -564,7 +566,7 @@ The following command defines quote aliases:
\cmditem{DeclareQuoteAlias}[variant]{style}{alias}
\cmditem*{DeclareQuoteAlias}{first-level alias}{second-level alias}
-This command may be used in the configuration file or in the document preamble. The alias may point to a backend style or to another alias. Most language aliases refer to a backend style, but some point to an intermediate alias instead. If the alias is defined for the sake of the \sty{babel} package, its name must be identical to the language name used by \sty{babel}, i.e. the expansion of \cmd{languagename}. See section \ref{cfg:spl} for an illustration of how quote styles, aliases, and package options interact. A list of all aliases defined by default is given in table \ref{cfg:als:tab}.
+This command may be used in the configuration file or in the document preamble. The alias may point to a backend style or to another alias. Most language aliases refer to a backend style, but some point to an intermediate alias instead. If the alias is defined for the sake of the \sty{babel} package, its name must be identical to the language name used by \sty{babel}, i.e. the expansion of \cmd{languagename}. See section \ref{cfg:spl} for an illustration of how quote styles, aliases, and package options interact. A list of all aliases defined by default is given in table \ref{tab:als}.
\end{ltxsyntax}
@@ -600,7 +602,7 @@ This command may be used in the configuration file or in the document preamble.
\bottomrule
\end{tabularx}
\caption[Language aliases]{Language aliases defined by default}
-\label{cfg:als:tab}
+\label{tab:als}
\end{table}
\subsection{Defining package options}
@@ -689,9 +691,7 @@ To select the default or the alternative style with multilingual support we use:
\usepackage[babel,newspeak=unofficial]{csquotes}
\end{ltxcode}
%
-The base style must be implemented as an alias in this case since the \opt{newspeak} option will select a variant by redefining and thus overwriting the \opt{newspeak} alias. Since the \opt{otherspeak} alias points to \opt{newspeak} and not directly to any backend style, using the \opt{newspeak} option will also have the desired effect if multilingual support is enabled.
-
-Note that there are two style names which have a special meaning: \opt{default} and \opt{fallback}. The former is an alias pointing to the default quote style used if the multilingual interface is not enabled. The package option \opt{style} and the command \cmd{setquotestyle} will redefine this alias. The latter is a backend style used as a fallback whenever the multilingual interface is enabled but there is no quote style for the current language. It will print bold question marks by default.
+The base style must be implemented as an alias in this case since the \opt{newspeak} option will select a variant by redefining and thus overwriting the \opt{newspeak} alias. Since the \opt{otherspeak} alias points to \opt{newspeak} and not directly to any backend style, using the \opt{newspeak} option will also have the desired effect if multilingual support is enabled. Note that there are some style names which have a special meaning. See section \ref{hnt:pre} for details.
\subsection{Defining quotes for \pdf strings}
\label{cfg:pdf}
@@ -718,7 +718,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 commands affected by these parameters are indicated in table \ref{cfg:blk:tab}.
+\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 commands affected by these parameters are indicated in table \ref{tab:blk}.
\end{ltxsyntax}
@@ -758,7 +758,7 @@ The following commands change the default values used by various quotation facil
\bottomrule
\end{tabularx}
\caption[Configurable parameters]{Scope of configurable parameters}
-\label{cfg:blk:tab}
+\label{tab:blk}
\end{table}
\subsection{Hooks for quotations and citations}
@@ -816,7 +816,7 @@ The integrated quotation facilities have slightly different requirements since t
\bottomrule
\end{tabularx}
\caption[Auxiliary hooks]{Availability of auxiliary hooks}
-\label{cfg:aux:tab}
+\label{tab:aux}
\end{table}
\begin{ltxcode}[showspaces=true]
@@ -848,7 +848,7 @@ The hooks \cmd{mkpredisppunct}, \cmd{mkmiddisppunct}, and \cmd{mkfindisppunct} h
\newcommand*{<<\mkfindisppunct>>}[1]{#1}
\end{ltxcode}
%
-The difference between \cmd{mkpredisppunct} is \cmd{mkmiddisppunct} is subtle because there are no closing quotation marks in display quotations. The two hooks differ in that \cmd{mkpredisppunct} is executed before the \env{quoteblock} environment is closed whereas \cmd{mkmiddisppunct} is executed after this environment. This also applies to \cmd{mkpreblockpunct} and \cmd{mkmidblockpunct} in display mode. Table \ref{cfg:aux:tab} gives an overview of the facilities affected by a redefinition of the above hooks. See the tutorial for usage examples. Also see section \ref{cfg:tst} for tests which may be useful when redefining the above hooks.
+The difference between \cmd{mkpredisppunct} is \cmd{mkmiddisppunct} is subtle because there are no closing quotation marks in display quotations. The two hooks differ in that \cmd{mkpredisppunct} is executed before the \env{quoteblock} environment is closed whereas \cmd{mkmiddisppunct} is executed after this environment. This also applies to \cmd{mkpreblockpunct} and \cmd{mkmidblockpunct} in display mode. Table \ref{tab:aux} gives an overview of the facilities affected by a redefinition of the above hooks. See the tutorial for usage examples. Also see section \ref{cfg:tst} for tests which may be useful when redefining the above hooks.
\subsection{Additional tests in quotation hooks}
\label{cfg:tst}
@@ -892,7 +892,7 @@ The active quotes provided by this package may depend on or benefit from the \st
\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 \acr{T1} or \acr{LY1} encoding 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 table \ref{hnt:onc:tab} for a list of common quotation marks included in both \acr{T1} and \acr{LY1} encoding.
+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 table \ref{tab:out} for a list of common quotation marks included in both \acr{T1} and \acr{LY1} encoding.
\begin{table}
\tablesetup
@@ -916,7 +916,7 @@ The \acr{OT1} font encoding, the default output encoding of \latex, merely inclu
\bottomrule
\end{tabularx}
\caption[Quotation marks]{Quotation marks included in \acr{T1} and \acr{LY1} encoding}
-\label{hnt:onc:tab}
+\label{tab:out}
\end{table}
\subsection{Valid active quotes}
@@ -943,7 +943,7 @@ Some care is still required when choosing active quotes. Note that you normally
This package interfaces with the \sty{hyperref} package as \pdf strings such as bookmarks are generated. See section \ref{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 sections \ref{bas:reg} and \ref{bas:bbl} as well as \ref{act:reg} and \ref{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.
-\subsection{Footnotes within quotations}
+\subsection{Footnotes inside quotations}
\label{hnt:ftn}
This package will automatically reset the nesting level within any footnote included in a quotation. If the \sty{babel} package has been loaded, it will also reset the language. The language of the footnote text including the hyphenation patterns will match the language of the text surrounding the quotation. This applies to parboxes, minipages, and floats as well.
@@ -954,14 +954,11 @@ This package will automatically reset the nesting level within any footnote incl
The commands discussed in section \ref{aut:amk} may be combined with the shorthands of the \sty{babel} package such that \sty{babel} provides the user interface and \sty{csquotes} the backend. For example, the German module of the \sty{babel} package defines, amongst other things, the shorthands |"`| and |"'|. Such shorthands are input aids, \ie physical markup elements with a fixed definition. Typing |"`| is a short way of saying |\quotedblbase| but it is not different in concept. These shorthands can be transformed into <smart quotes> which behave like \cmd{enquote}. Here is a simple ad~hoc solution suitable for documents with only one language:
\begin{ltxexample}[upquote]
-\documentclass{article}
+\documentclass{...}
\usepackage[german]{babel}
\usepackage[babel=once]{csquotes}
\defineshorthand{"`}{\openautoquote}
\defineshorthand{"'}{\closeautoquote}
-\begin{document}
-...
-\end{document}
\end{ltxexample}
%
It is possible to move such definitions to \path{csquotes.cfg}. In this case, the code is slightly more complex because it needs to be more general:
@@ -976,13 +973,15 @@ It is possible to move such definitions to \path{csquotes.cfg}. In this case, th
{}}
\end{ltxcode}
%
-The above code redefines the shorthands only if the \sty{babel} package has been loaded and the main language of the document is \texttt{german}. Note that \sty{babel}'s shorthands are language"=specific. The way they are configured and handled is technically and conceptually different from the active quotes discussed in section \ref{act}. Active quotes are defined globally and automatically adapt to the current language. With \sty{babel}, each language has its own set of shorthands. Also note that \sty{babel} uses \cmd{AtBeginDocument} to initialize the main document language, including the corresponding shorthands. We use \cmd{AtEndPreamble} to defer the code until the end of the preamble. This way, we can be sure that \sty{babel} has been loaded but that the main document language has not been initialized yet. See the \sty{babel} manual for further details. The \cmd{AtEndPreamble} command is provided by the \sty{etoolbox} package.
+This code redefines the shorthands only if the \sty{babel} package has been loaded and the main language is \texttt{german}. Note that \sty{babel}'s shorthands are language"=specific. The way they are configured and handled is technically and conceptually different from the active quotes discussed in section \ref{act}. Active quotes are defined globally and automatically adapt to the current language. With \sty{babel}, each language has its own set of shorthands. Also note that \sty{babel} uses \cmd{AtBeginDocument} to initialize the main document language, including the corresponding shorthands. We use \cmd{AtEndPreamble} to defer the code until the end of the preamble. This way, we can be sure that \sty{babel} has been loaded but that the main document language has not been initialized yet. See the \sty{babel} manual for further details. The \cmd{AtEndPreamble} command is provided by the \sty{etoolbox} package.
\subsection{Miscellaneous notes about the predefined styles}
-\label{hnt:lng}
+\label{hnt:pre}
All variants of the \opt{french} style use spaced out guillemets as outer marks. The style variant \opt{quotes} uses double quotes as inner marks. The starred variant \opt{quotes*} is similar to its regular counterpart except that it will also space out the inner marks. The \opt{guillemets} variant employs spaced out guillemets on all levels. It will also insert guillemets at the beginning of every paragraph inside a quotation spanning multiple paragraphs. In addition to that, two adjoining marks at the end of a quotation are replaced by a single one; if two nested quotations end simultaneously, the second closing mark is omitted automatically. The starred variant \opt{guillemets*} is similar to its regular counterpart, differing only in the middle mark inserted at the beginning of every paragraph. The regular variant uses a left"=pointing guillemet whereas the starred one uses a right"=pointing one.
+There are three styles which serve a special purpose: \opt{default}, \opt{fallback}, and \opt{debug}. The \opt{default} style is a dynamic alias pointing to the default quote style used if the multilingual interface is not enabled. The package option \opt{style} and the command \cmd{setquotestyle} will redefine this alias. The \opt{fallback} style is a backend style used as a fallback whenever the multilingual interface is enabled but there is no matching quote style for the current language. It will print bold question marks by default. The \opt{debug} style will not print quotation marks but the current quote level as a bold number. This style may be selected using the \opt{style} option or the \cmd{setquotestyle} command. It is intended for debugging only.
+
\section{Author interface}
\label{aut}
@@ -1020,7 +1019,7 @@ This command implicitly executes \cmd{@disablequotes} and deallocates all active
\subsection{Active quotes in a strings-only context}
\label{aut:str}
-A possible problem with active characters are strings-only contexts, i.\,e. cases in which an active character is used in the formation of a control sequence name or as a plain string. A typical example is a command like \cmd{label} which expects a string of characters. Any active character may break \cmd{label} when used in its argument. There are two packages which try to remedy this situation, albeit in different ways: \sty{babel} and \sty{underscore}.
+A possible problem with active characters are strings-only contexts, i.\,e. cases in which an active character is used in the formation of a control sequence name. A typical example is the \cmd{label} command which expects a string of characters. Any active character may break \cmd{label} when used in its argument. There are two packages which try to remedy this situation, albeit in different ways: \sty{babel} and \sty{underscore}.
The \sty{babel} package defines the switch \cmd{if@safe@actives} and patches several standard commands such that the switch is set to \opt{true} while they process their arguments. The approach taken by the \sty{underscore} package is slightly different. If \sty{underscore} is loaded with the \opt{strings} option, it patches several commands such that \cmd{protect} is equivalent to \cmd{string} while the arguments are processed. If any one of these packages is loaded, \sty{csquotes} will take advantage of that automatically. Unfortunately, both packages patch a different set of commands and neither one covers all possibly vulnerable commands. If \sty{babel} is loaded, for example, you may use active quotes in the argument of \cmd{label}, but not in the argument of \cmd{input}. If you load \sty{underscore} with its \opt{strings} option, active quotes may also be used in the argument of \cmd{input}.
@@ -1052,6 +1051,26 @@ The \prm{code} may be arbitrary \latex code which redefines vulnerable commands
\end{ltxsyntax}
+\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{T2A}, \acr{T2B}, \acr{T2C}, \acr{LCY}, and \acr{X2} are provided by default. Other encodings may be set up in the configuration file using the following command:
+
+\begin{ltxsyntax}
+\cmditem{DeclareQuoteGlyph}{encoding}{position}
+\end{ltxsyntax}
+
+The \prm{encoding} is the name of the output encoding, for example \texttt{OT1}. This string corresponds to the identifiers used when loading the \sty{fontenc} package. The \prm{position} argument is an integer indicating the position of a glyph in this encoding. You need to reqister all quotation marks in the output encoding, using one declaration for each glyph. As an example, these are the settings for the \acr{OT1} encoding:
+
+\begin{ltxcode}
+\DeclareQuoteGlyph{OT1}{34}% = \textquotedblright
+\DeclareQuoteGlyph{OT1}{39}% = \textquoteright
+\DeclareQuoteGlyph{OT1}{92}% = \textquotedblleft
+\DeclareQuoteGlyph{OT1}{96}% = \textquoteleft
+\end{ltxcode}
+%
+See the settings in \path{csquotes.def} for further examples. The advantage of registering quotes with the above command (rather than adjusting the space factor codes globally) is that the declarations are only used locally inside quotations and will not affect any other part of the document.
+
\subsection{Automatic quotation marks}
\label{aut:amk}
@@ -1073,7 +1092,7 @@ In terms of their function, the above commands correspond to the regular version
\end{ltxsyntax}
-The above commands may be used to implement an alternative user interface. You can combine them with the shorthands of the \sty{babel} package such that \sty{babel} provides the user interface and \sty{csquotes} the backend. See section \ref{hnt:bbl} and the \sty{babel} manual for details.
+The above commands may be used to implement an alternative user interface. For example, you can combine them with the shorthands of the \sty{babel} package such that \sty{babel} provides the user interface and \sty{csquotes} the backend. See section \ref{hnt:bbl} and the \sty{babel} manual for details.
\subsection{Internal quotation marks}
\label{aut:imk}
@@ -1101,7 +1120,7 @@ Note that the initialization hooks for the respective quotation style are not ex
\end{ltxsyntax}
-The scope of these hooks should always be confined to a group.
+The scope of these hooks must always be confined to a group.
\section{Revision history}
@@ -1109,8 +1128,18 @@ This revision history is a list of changes relevant to users of this package. Ch
\begin{changelog}
+\begin{release}{4.4}{2009-05-30}
+\item Added package option \opt{maxlevel}\see{opt}
+\item Added special quote style \opt{debug}\see{hnt:pre}
+\item Added \cmd{DeclareQuoteGlyph}\see{aut:sfc}
+\item Added support for \acr{OT2} and \acr{OT4} encodings
+\item Added support for \acr{T2A}, \acr{T2B}, \acr{T2C}, \acr{X2} encodings
+\item Added support for \acr{LCY} encoding
+\item Added quote style for Russian
+\end{release}
+
\begin{release}{4.3}{2008-11-23}
-\item Made package option \kvopt{babel}{tryonce} the default setting\see{opt:bbl}
+\item Made package option \kvopt{babel}{tryonce} the default setting\see{opt}
\item Internal updates for \path{biblatex} package
\end{release}
@@ -1146,8 +1175,8 @@ This revision history is a list of changes relevant to users of this package. Ch
\end{release}
\begin{release}{3.7}{2007-03-25}
-\item Added package option \kvopt{babel}{try}\see{opt:bbl}
-\item Added package option \kvopt{babel}{tryonce}\see{opt:bbl}
+\item Added package option \kvopt{babel}{try}\see{opt}
+\item Added package option \kvopt{babel}{tryonce}\see{opt}
\item Added \cmd{MakeAutoQuote*}\see{act:reg}
\item Added \cmd{MakeForeignQuote*}\see{act:bbl}
\item Added \cmd{MakeHyphenQuote*}\see{act:bbl}
@@ -1166,7 +1195,7 @@ This revision history is a list of changes relevant to users of this package. Ch
\end{release}
\begin{release}{3.5}{2006-08-24}
-\item Exchanged definitions of French \opt{quotes} and \opt{quotes*} variants\see{hnt:lng}
+\item Exchanged definitions of French \opt{quotes} and \opt{quotes*} variants\see{hnt:pre}
\item Internal updates for \path{inputenc} 1.1\,b (2006-05-05)
\end{release}
@@ -1190,8 +1219,8 @@ This revision history is a list of changes relevant to users of this package. Ch
\item Added \cmd{DeleteQuotes}\see{act:ctl}
\item Added \cmd{VerbatimQuotes}\see{act:ctl}
\item Added \cmd{ExecuteQuoteOptions}\see{cfg:exe}
-\item Added package option \kvopt{babel}{once}\see{opt:bbl}
-\item Added new style variant for French\see{hnt:lng}
+\item Added package option \kvopt{babel}{once}\see{opt}
+\item Added new style variant for French\see{hnt:pre}
\item Improved nesting control of active block quotes
\item Made active block quotes robust
\end{release}
@@ -1321,8 +1350,8 @@ This revision history is a list of changes relevant to users of this package. Ch
\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:lng}
-\item Added new style variant for French\see{hnt:lng}
+\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
@@ -1350,8 +1379,8 @@ This revision history is a list of changes relevant to users of this package. Ch
\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:sct}
-\item Added package option \opt{strict}\see{opt:sct}
+\item Revised and improved error recovery\see{opt}
+\item Added package option \opt{strict}\see{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
@@ -1361,7 +1390,7 @@ This revision history is a list of changes relevant to users of this package. Ch
\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:lng}
+\item Amended default French quote style\see{hnt:pre}
\end{release}
\begin{release}{1.5}{2004-02-27}