The Csquotes Package Context Sensitive Quotation Facilities Philipp Lehman, Joseph Wright Version V5.2L Joseph.Wright@Morningstar2.Co.Uk 2021-02-22

Home , Baseline (typography), Ellipsis, Guillemet, Quotation mark, Terminal punctuation

The csquotes Package Context Sensitive Quotation Facilities Philipp Lehman, Joseph Wright Version v5.2l [email protected] 2021-02-22

Contents

List of Tables1 7 Auxiliary Commands 15

1 Introduction1 8 Conﬁguration 16

2 Package Options2 9 Usage Notes 26

3 Basic Interface5 10 Hints and Caveats 31

4 Active Quotes9 11 Author Interface 35

5 Integrated Interface 12 12 Bug reports 40

6 Display Environments 14 13 Revision History 40

List of Tables

1 Language Options...... 3 4 Conﬁgurable Parameters.... 20 2 Styles and Variants...... 17 5 Auxiliary Hooks...... 21 3 Language Aliases...... 18 6 Quotation Marks...... 31

1 Introduction

1.1 About 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 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.

1 1.2 License Copyright © 2003–2011 Philipp Lehman, 2015–2019,2021 Joseph Wright. Permis- sion is granted to copy, distribute and/or modify this software under the terms of the LaTeX Project Public License, version 1.3c or any later version.1

1.3 Contributions The multilingual support of this package depends on user contributions. If you want to contribute a quote style, please refer to § 8.1 for an overview of the components a quote style is composed of and to table6 for a list of commands which should be used in the deﬁnition of quote styles.

2 Package Options

All package options are given in hkeyi=hvaluei syntax.

2.1 Main Options

strict=true, false default: false This option turns all package warnings into error messages. This is useful to ensure that no problem will go unnoticed when ﬁnalizing a document. The short form strict is equivalent to strict=true.

style=hstylei default: american This option selects a ﬁxed quotation style. The style is used throughout the document unless it is changed manually, see § 3.7 for details. This option implicitly sets autostyle=false. Please refer to tables2 and3 for a list of available quote styles and aliases. See §§ 8.1, 8.2, 9.1 for instructions on adding or modifying quote styles. autostyle=true, false, try, once, tryonce default: tryonce

This option controls multilingual support. It requires either the babel package or the polyglossia package.2 autostyle=true continuously adapts the quote style to the current document language; once will only adapt the style once so that it matches the main language of the document. autostyle=try and tryonce are similar to true and once if multilingual support is available but will not issue any warnings if not (i. e., if neither babel nor polyglossia have been loaded). The short form autostyle is equivalent to autostyle=true. See also § 3.7.

1http://www.latex-project.org/lppl/ 2Note that polyglossia support requires polyglossia v1.45 (2019/10/27) or above. With older polyglossia versions language variants will not be detected as expected.

2 Option key Possible values austrian quotes, guillemets croatian quotes, guillemets czech quotes, guillemets danish quotes, guillemets, topquotes english american, british estonian french quotes, quotes*, guillemets, guillemets* galician quotes, guillemets german quotes, guillemets, swiss hungarian italian guillemets, quotes latin italianguillemets, germanquotes, germanguillemets, britishquotes, americanquotes latvian norwegian guillemets, quotes polish guillemets, guillemets* portuguese portuguese, brazilian romanian serbian quotes, guillemets, german spanish spanish, mexican swedish quotes, guillemets, guillemets*

Table 1: Language Options Deﬁned by Default hlanguagei=hvarianti Use the language options listed in table1 to choose a style variant if there is more than one for a certain language. The ﬁrst variant in the list is the default for the respective style. In the following example, the autostyle option causes csquotes to continuously adapt the quote style to the current language using the default style for that language. The defaults for German and Norwegian are changed:

\usepackage[english,ngerman]{babel} \usepackage[autostyle,german=guillemets,norwegian=quotes]{csquotes}

Note that babel’s language name is ngerman here whereas csquotes uses 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 table3 for details. Table1 indicates the language options defined by default. Additional options may be defined in the configuration file. See §§ 8.3 and 9.1 for details. Also see § 10.9 for some additional notes concerning the predefined styles.

maxlevel=hintegeri default: 2 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

3 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 maxlevel option. The minimum is 2.

autopunct=true, false default: true This option controls whether the quotation commands scan ahead for trailing punctuation marks. See §§ 3.3, 3.5, 5.1, 5.3 for details. Also see \DeclareAutoPunct in § 8.9 and § 8.7 on how to conﬁgure and use the punctuation look-ahead feature. The short form autopunct is equivalent to autopunct=true.

threshold=hintegeri default: 3 This option deﬁnes 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 \SetBlockThreshold command. See §§ 3.5 and 8.6 for further details. thresholdtype=lines, words default: lines

This option selects the block threshold type. With thresholdtype=lines, the block quotation facilities will determine the number of lines required to typeset the quotation; with thresholdtype=words, they count the number of words in the quotation.3 The default threshold setup is 3 lines. If you prefer something like 50 words, set threshold=50 and thresholdtype=words. See § 3.5 for further details.

parthreshold=true, false default: true This option ﬁne-tunes the block threshold detection. If enabled, any explicit paragraph or line break in the quotation will trigger the threshold, i. e., the quotation will be typeset in display mode regardless of its length. If disabled, explicit paragraph or line breaks are applied normally if thresholdtype=lines, and treated as a regular word boundary if thresholdtype=words. The short form parthreshold is equivalent to parthreshold=true.

splitcomp=true, false default: true

This option is applicable with thresholdtype=words only. It ﬁne-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 splitcomp is equivalent to splitcomp= true.

3The word counting code is based on an idea by Donald Arseneau.

4 csdisplay=true, false default: false By default, the block quotation facilities will automatically force inline quotations in footnotes, parboxes, minipages, and ﬂoats. Setting this option to true will permit context-sensitive switching to display quotations in these contexts, as in the text body. The short form csdisplay is equivalent to csdisplay=true. This option may also be set locally with \csdisplaytrue and \csdisplayfalse, respectively.

debug=true, false default: false This option controls the debugging feature of the block quotation facilities. If enabled, all block quotation commands will output diagnostic messages to the tran- script ﬁle. These messages indicate the calculated line/word count, explicit para- gaph or line breaks detected in the quotation text, and the ﬁnal inline/display de- termination. The short form debug is equivalent to debug=true.

2.2 Compatibility Options

version=hversioni, 4.4, 3.6, 3.0

This option is an attempt at making 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 hversioni, even if it is not explicitly listed above. In this case, the package will keep increasing the hversioni number until it either ﬁnds a suitable compatibility mode or hits the current version number. For example, when specifying version=4.0, 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 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 version option will simply have no effect.

babel=true, false, try, once, tryonce

An older name of the autostyle option. This option is depreciated.

3 Basic Interface

This package supports two ways to tag quotations: built-in commands and active quotes defined in the document preamble or the configuration file. This section will introduce the basic commands, active quotes are discussed in §4. When working

5 with automated citations, you might also want to learn about the integrated quotation facilities presented in §5.

3.1 Quoting Regular Text The most basic command will simply enclose its argument in quotation marks:

\enquote{htexti} \enquote*{htexti} Like all quotation facilities, this command is context sensitive. Depending on the nesting level, it will toggle between outer and inner quotation marks with plain and nested quotations. The starred version of this command skips directly to the inner level. If multilingual support is enabled, the style of all quotation marks will be adapted to the current language.

3.2 Quoting Text in a Foreign Language

To facilitate typesetting quotations in a foreign language, csquotes provides two commands which combine \enquote with the language switches of the babel or the polyglossia package:

\foreignquote{hlangi}{htexti} \foreignquote*{hlangi}{htexti}

This command combines \enquote with \foreignlanguage. It switches hyphenation patterns and enables the extra deﬁnitions provided by babel/polyglossia for hlangi, which must be a language name known to the respective package. The quotation marks will match the language of the quoted piece of text.

\hyphenquote{hlangi}{htexti} \hyphenquote*{hlangi}{htexti}

This command combines \enquote with the hyphenrules environment, that is, it merely switches hyphenation patterns. The quotation marks will match the language of the text surrounding the quotation.

3.3 Formal Quoting of Regular Text Formal quotations are typically accompanied by a citation indicating the source of the quoted text. The following command is an extended version of \enquote which encloses the quoted piece of text in quotation marks and adds a citation after the quotation:

6 \textquote[hcitei][hpuncti]{htexti}htpuncti \textquote*[hcitei][hpuncti]{htexti}htpuncti The htexti may be any arbitrary piece of text to be enclosed in quotation marks. The optional arguments hcitei and hpuncti specify the citation and any terminal punctuation of htexti. htpuncti denotes trailing punctuation after the command. If the 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 § 8.7 on how to change the way these arguments are handled and § 9.2 for reasons why you may want to specify the punctuation as a separate argument. The starred version of this command skips directly to the inner quotation level. Here are some usage examples:

\textquote{...} \textquote[][.]{...} \textquote[Doe 1990, 67]{...} \textquote[{\cite[67]{doe90}}]{...}

Note the use of the optional arguments in the examples above. As seen in the second example, hcitei is required whenever hpuncti is used, even if it is empty. Also keep in mind that an optional argument containing square brackets must be wrapped in an additional pair of curly braces as shown in the last example. When working with automated citations, you might also want to learn about the integrated quotation facilities presented in §5.

3.4 Formal Quoting of Text in a Foreign Language

There are two additional commands which combine \textquote with the language switches of the babel or the polyglossia package:

\foreigntextquote{hlangi}[hcitei][hpuncti]{htexti}htpuncti \foreigntextquote*{hlangi}[hcitei][hpuncti]{htexti}htpuncti

This command combines \textquote with \foreignlanguage. Apart from the language, the arguments are handled as with \textquote.

\hyphentextquote{hlangi}[hcitei][hpuncti]{htexti}htpuncti \hyphentextquote*{hlangi}[hcitei][hpuncti]{htexti}htpuncti

This command combines \textquote with the hyphenrules environment. Apart from the language, the arguments are handled as with \textquote.

7 3.5 Block Quoting of Regular Text Formal requirements in academic writing frequently demand that quotations be em- bedded 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:

\blockquote[hcitei][hpuncti]{htexti}htpuncti This command determines the length of the htexti. If the length exceeds a certain threshold, the htexti will be typeset in display mode, i. e., as a block quotation. If not, \blockquote will behave like \textquote. Depending on the thresholdtype option, the threshold may be based on the number of lines required to typeset the htexti or on the number of words in the htexti. If the parthreshold option has been enabled, any explicit paragraph or line break in the htexti will trigger the threshold, i. e., it will be typeset in display mode regardless of its length. The default threshold setup is three lines with parthreshold enabled. The default environment used for display quotations is the quote environment. See §§ 2.1 and 8.6 on how to change these parameters. Note that csquotes will force inline quotations in footnotes, parboxes, minipages, and ﬂoats by default. Use the csdisplay option from § 2.1 to change this behavior. The optional arguments hcitei and hpuncti specify the citation and any terminal punctuation of the htexti. htpuncti denotes trailing punctuation after the command. If the 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 § 8.7 on how to change the way these arguments are handled and § 9.2 for reasons why you may want to specify the punctuation as a separate argument.

3.6 Block Quoting of Text in a Foreign Language

The following commands combine \blockquote with the language switches of the babel or the polyglossia package:

\foreignblockquote{hlangi}[hcitei][hpuncti]{htexti}htpuncti

This command behaves like \foreignquote if the quotation is short. If it exceeds the threshold, it will be wrapped in an otherlanguage* environment which is in turn wrapped in a block quotation environment. The arguments are handled as with \blockquote.

8 \hyphenblockquote{hlangi}[hcitei][hpuncti]{htexti}htpuncti

This command behaves like \hyphenquote if the quotation is short. If it exceeds the threshold, it will be wrapped in a hyphenrules environment which is in turn wrapped in a block quotation environment. The arguments are handled as with \blockquote.

\hybridblockquote{hlangi}[hcitei][hpuncti]{htexti}htpuncti

This command behaves like \hyphenquote if the quotation is short. If it exceeds the threshold, the command behaves like \foreignblockquote. In other words, it combines features of \foreignblockquote and \hyphenblockquote. The arguments are handled as with \blockquote.

3.7 Selecting Quote Styles Quote styles may be selected manually at any point in the document body by way of the following command:

\setquotestyle[hvarianti]{hstylei} \setquotestyle{haliasi} \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 tables2 and3 for a list of available styles, style variants, and language aliases.

4 Active Quotes

This package also supports active characters corresponding to the commands presented in §3. Roughly speaking, an active character is a single character which functions as a command. Like the corresponding control sequences, active quotes are fully-fledged markup elements which verify the nesting level and issue an error if quotations are nested in an invalid way. If multilingual support is enabled, the style of all quotation marks will be adapted to the current language. The commands presented in the following allocate such active quotes. They may be used in the configuration file, the preamble, or the document body. Note that all characters are automatically checked for validity as they are allocated. This package will re- ject characters which are unsuitable as active quotes. See § 10.3 for details on the characters which may be used as active quotes.

9 4.1 Quoting Regular Text

\MakeOuterQuote and \MakeInnerQuote deﬁne active quotes which print outer and inner quotation marks. Both take one mandatory argument, the character serving as both opening and closing mark:

\MakeOuterQuote{hcharacteri} \MakeInnerQuote{hcharacteri}

\MakeAutoQuote deﬁnes active quotes which toggle between outer and inner quotations automatically. The two mandatory arguments serve as opening and closing mark and must be distinct:

\MakeAutoQuote{hcharacter 1i}{hcharacter 2i} \MakeAutoQuote*{hcharacter 1i}{hcharacter 2i}

All active quotes deﬁned with \MakeAutoQuote work like \enquote. Those deﬁned with \MakeOuterQuote and \MakeInnerQuote cover only a part of this functionality. The former correspond to the outer level of \enquote whereas the latter correspond to the starred version. \MakeAutoQuote* is similar to \MakeInnerQuote, i.e. it corresponds to \enquote*.

4.2 Quoting Text in a Foreign Language

These commands combine \MakeAutoQuote with the language switches of the babel or the polyglossia package:

\MakeForeignQuote{hlangi}{hcharacter 1i}{hcharacter 2i} \MakeForeignQuote*{hlangi}{hcharacter 1i}{hcharacter 2i} The active quotes deﬁned with the above commands are similar in concept and function to \foreignquote and \foreignquote*, respectively.

\MakeHyphenQuote{hlangi}{hcharacter 1i}{hcharacter 2i} \MakeHyphenQuote*{hlangi}{hcharacter 1i}{hcharacter 2i} The active quotes deﬁned with the above commands are similar in concept and function to \hyphenquote and \hyphenquote*, respectively.

4.3 Block Quoting of Regular Text

\MakeBlockQuote deﬁnes active quotes which will set quotations inline or as a separate paragraph, depending on their length. This command takes three mandatory arguments which must be distinct:

10 \MakeBlockQuote{hcharacter 1i}{hdelimiteri}{hcharacter 2i} The arguments are checked for validity, see § 10.3 for details. All active quotes deﬁned with \MakeBlockQuote behave essentially the same as \blockquote, but the handling of the citation is slightly different. hcharacter 1i will serve as the opening mark in the source ﬁle, hcharacter 2i as the closing one. The character indicated by the middle argument hdelimiteri will serve as a delimiter separating the quoted text from the citation which is given last as the active quotes are used:

\MakeBlockQuote{<}{|}{>} ...

If the delimiter is omitted, the entire text between the opening and the closing mark will be treated as quotation text.

4.4 Block Quoting of Text in a Foreign Language

These commands combine \MakeBlockQuote with the language switches of the babel or the polyglossia package:

\MakeForeignBlockQuote{hlangi}{hcharacter 1i}{hdelimiteri}{hcharacter 2i} The active quotes defined with this command are similar in concept and function to \foreignblockquote. The behavior of the delimiter character is similar to \MakeBlockQuote. \MakeHyphenBlockQuote{hlangi}{hcharacter 1i}{hdelimiteri}{hcharacter 2i} The active quotes defined with this command are similar in concept and function to \hyphenblockquote. The behavior of the delimiter character is similar to \MakeBlockQuote. \MakeHybridBlockQuote{hlangi}{hcharacter 1i}{hdelimiteri}{hcharacter 2i} The active quotes defined with this command are similar in concept and function to \hybridblockquote. The behavior of the delimiter character is similar to \MakeBlockQuote.

4.5 Controlling Active Quotes The commands introduced above merely allocate active quotes, but these characters are not immediately made active. All allocated quotes are automatically enabled at the beginning of the document body. If any active quotes are allocated in the document body, they need to be enabled with \EnableQuotes. The following commands control the state of the active quotes within a local scope.

11 \EnableQuotes Enables all active quotes by redeﬁning the allocated characters and making them active. It also restores them when disabled, set to verbatim, or overwritten.

\DisableQuotes Disables all active quotes by restoring the original category codes and deﬁnitions of all allocated characters.

\VerbatimQuotes Switches to verbatim active quotes. All active quotes will be printed verbatim until their default behavior is restored with \EnableQuotes.

\DeleteQuotes Disables and deallocates all active quotes, i.e. performs a complete reset of all allocated characters so that they may be newly deﬁned.

5 Integrated Interface

The commands presented in this section are extended versions of some of those discussed in §3. They differ from their counterparts in that they integrate automated citations into their syntax. Instead of adding \cite manually, you pass the citation arguments to the respective quotation command. See § 8.6 on how to use a command other than \cite to handle the citations.

5.1 Formal Quoting of Regular Text

The basic integrated command is an extended version of \textquote:

\textcquote[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti \textcquote*[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti The htexti may be any arbitrary piece of text to be enclosed in quotation marks. The optional arguments hcitei and hpuncti specify the citation and any terminal punctuation of htexti. htpuncti denotes trailing punctuation after the command. If the 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 § 8.7 on how to change the way these arguments are handled and § 9.2 for reasons why you may want to specify the punctuation as a separate argument. The starred version of this command skips directly to the inner quotation level. The remaining arguments are handed over to \cite. Note that \cite normally supports one optional argument only. hprenotei is only available in conjunction with the natbib, jurabib, and biblatex packages. How these arguments are handled depends on the citation command. With natbib and biblatex, hprenotei is in fact a notice such as ‘see’. With jurabib, this argument has a different function by default. The argument hpostnotei, which is always available, indicates the citation postnote. This is usually a page number. hkeyi is the citation key. See §§ 8.6 and 8.7 on how to customize the citation.

12 5.2 Formal Quoting of Text in a Foreign Language

The following commands combine \textcquote with the language switches of the babel or the polyglossia package:

\foreigntextcquote{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti \foreigntextcquote*{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti

This command combines \textcquote with \foreignlanguage. The handling of the arguments is similar to \textcquote.

\hyphentextcquote{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti \hyphentextcquote*{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti

This command combines \textcquote with the hyphenrules environment. The handling of the arguments is similar to \textcquote.

5.3 Block Quoting of Regular Text Block quotations may be combined with automated citations by using the extended version of \blockquote:

\blockcquote[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti

The difference between \blockcquote and \blockquote is that there are three citation arguments instead of one. The handling of these citation arguments is similar to \textcquote; see § 5.1 for details. Also see §§ 8.6, 8.7, 9.2 on how to customize block quotations.

5.4 Block Quoting of Text in a Foreign Language

The following commands combine \blockcquote with the language switches of the babel or the polyglossia package:

\foreignblockcquote{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti

This command combines \blockcquote with \foreignlanguage. Long quotations will be wrapped in an otherlanguage* environment. The handling of the citation arguments is similar to \textcquote.

\hyphenblockcquote{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti

This command combines \blockcquote with the hyphenrules environment. The handling of the citation arguments is similar to \textcquote.

13 \hybridblockcquote{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti]{htexti}htpuncti

This command behaves like \hyphenblockcquote if the quotation is short, and like \foreignblockquote if it is long. The handling of the citation arguments is similar to \textcquote.

6 Display Environments

The environments introduced in this section will typeset quotations as a separate paragraph which looks exactly like a long quotation set by means of the block quotation facilities. Use them for quotations which are to be presented as a separate paragraph regardless of their length. Note that these environments are not replacements for the standard quote environment in the strict sense. They function as an additional layer on top of the latter, just like the block quotation facilities. The advantage of using these environments instead of resorting to the standard quote environment is that they are conﬁgurable, support citations, and will always be in sync with the block quotation facilities with respect to the conﬁguration options discussed in §§ 8.6 and 8.7.

6.1 Basic Display Environments

The arguments of all display environments are generally appended to the \begin section of the environment:

\begin{displayquote}[hcitei][hpuncti] \end{displayquote} The optional arguments hcitei and hpuncti specify the citation and any terminal punctuation of the quotation. See §§ 8.6 and 8.7 on how to customize this environment. Also see § 8.7 on how to change the way the optional arguments are handled and § 9.2 for reasons why you may want to specify the punctuation as a separate argument. Trailing white space at the end of the environment is removed automatically. There are two additional environments which combine displayquote with the language switches of the babel or the polyglossia package:

\begin{foreigndisplayquote}{hlangi}[hcitei][hpuncti] \end{foreigndisplayquote}

This environment combines displayquote with otherlanguage*. Apart from the language, the arguments are handled as with displayquote.

14 \begin{hyphendisplayquote}{hlangi}[hcitei][hpuncti] \end{hyphendisplayquote}

This environment combines displayquote with hyphenrules. Apart from the language, the arguments are handled as with displayquote.

6.2 Integrated Display Environments

The following environment is an extended version of displayquote:

\begin{displaycquote}[hprenotei][hpostnotei]{hkeyi}[hpuncti] \end{displaycquote}

The difference between displaycquote and its more basic counterpart is that there are three citation arguments instead of one. The placement of the citation is similar to displayquote. The handling of the citation arguments is similar to \textcquote, see § 5.1 for details. See §§ 8.6 and 8.7 on how to customize this environment. Also see § 8.7 on how to change the way the optional arguments are handled and § 9.2 for reasons why you may want to specify the punctuation as a separate argument. There are two environments which combine displaycquote with the language switches of the babel or the polyglossia package:

\begin{foreigndisplaycquote}{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti] \end{foreigndisplaycquote}

This environment combines displaycquote with otherlanguage*. Apart from the language, the arguments are handled as with displaycquote.

\begin{hyphendisplaycquote}{hlangi}[hprenotei][hpostnotei]{hkeyi}[hpuncti] \end{hyphendisplaycquote}

This environment combines displaycquote with hyphenrules. Apart from the language, the arguments are handled as with displaycquote.

7 Auxiliary Commands

When quoting text in a formal way, any changes applied to the quoted material, such as omissions, insertions, or alterations, are typically marked as such by using square brackets or parentheses and, where appropriate, ellipses. Use the following commands to indicate such changes in formal quotations:

15 \textelp{} \textelp{htexti} \textelp*{htexti} When used with an empty htexti argument, this command prints an ellipsis symbol to indicate the omission of material from the quoted material. When used with a non-empty argument, the ellipsis symbol is followed by the htexti enclosed in square brackets to indicate that the htexti has been added after the omitted material. The starred version reverts the order, i. e., it prints the htexti followed by an ellipsis symbol to indicate that the htexti has been added before the omitted material. In sum, there are three ways to use this command:

\textelp{} = [. . .] \textelp{text} = [. . .][text] \textelp*{text} = [text] [. . .]

The insertion of text or individual letters may be indicated with the following command:

\textins{htexti} \textins*{htexti} By default, \textins will enclose the htexti added to the quoted material in square brackets. The starred version is intended for minor changes, such as the capitaliza- tion of a word, which are required to adapt the quoted material to the new context in which it is quoted.

\textins{text} = [text] \textins*{T}ext = [T]ext

The deletion of individual letters may be indicated with the following command:

\textdel{htexti} By default, \textdel will output two square brackets. The omitted htexti is not output.

text\textdel{s} = text[]

See § 8.10 on how to conﬁgure the appearance of ellipses and insertions.

8 Conﬁguration

If available, this package will load the configuration file csquotes.cfg. You may use this file to define new quote styles and aliases or redefine existing ones.

16 Quote style Style variants austrian quotes, guillemets croatian quotes, guillemets czech quotes, guillemets danish quotes, guillemets dutch – english american, british ﬁnnish – french quotes, quotes*, guillemets, guillemets* german quotes, guillemets, swiss greek – italian guillemets, quotes latin italianguillemets, germanquotes, germanguillemets, britishquotes, americanquotes norwegian guillemets, quotes portuguese portuguese, brazilian russian – serbian quotes, guillemets, german spanish spanish, mexican swedish quotes, guillemets, guillemets*

Table 2: Quote Styles and Style Variants Deﬁned by Default

8.1 Deﬁning Quote Styles Use the following command to deﬁne quote styles and style variants:

\DeclareQuoteStyle[hvarianti]{hstylei}[houter initi][hinner initi]% {hopening outer marki}[hmiddle outer marki]{hclosing outer marki}[hkerni]% {hopening inner marki}[hmiddle inner marki]{hclosing inner marki} 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 table6. If both an outer and an inner quotation begin or end si- multaneously, the kerning specified by the value hkerni 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 hkerni 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. houter initi and hinner initi 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 houter initi

17 Alias Backend style or alias Alias Backend style or alias american english/american newzealand english/british australian english/british ngerman german austrian austrian/quotes norsk norwegian brazil brazilian norwegian norwegian/guillemets brazilian portuguese/brazilian nswissgerman swissgerman british english/british nynorsk norwegian canadian english/american portuges portuguese croatian croatian/quotes portuguese portuguese/portuguese danish danish/quotes serbian serbian/quotes english english/american spanish spanish/spanish french french/quotes swedish swedish/quotes german german/quotes swiss german/swiss italian italian/guillemets swissgerman german/swiss latin latin/italianguillemets UKenglish british mexican spanish/mexican USenglish american naustrian austrian

Table 3: Language Aliases Deﬁned by Default

will take place immediately before the opening outer quote is inserted, but inside the group formed by the quotation. hinner initi 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 hinner initi is used houter initi has to be given as well, even if the argument is empty. Refer to table2 for a list of all predeﬁned quote styles and their variants. These are the backend styles only, see also table3 for a list of language aliases. See § 9.1 for some examples as well as an illustration of how quote styles, aliases, and package options interact.

8.2 Deﬁning Quote Aliases The following command deﬁnes quote aliases:

\DeclareQuoteAlias[hvarianti]{hstylei}{haliasi} \DeclareQuoteAlias{hfirst-level aliasi}{hsecond-level aliasi} 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 babel or the polyglossia package, its name must be identical to the language name used by babel/polyglossia, i. e., the expansion of \languagename. See § 9.1 for an illustration of how quote styles, aliases, and package options interact. A list of all aliases defined by default is given in table3.

18 8.3 Deﬁning Package Options The following command creates a new package option based on a key/value syntax. It takes one mandatory argument, the quote style name:

\DeclareQuoteOption{hstylei} When using the new option, the name of the quote style will serve as the key. The value may be any style variant defined for the respective style. The package option will select a variant by defining an alias pointing to the desired backend style. This command is available in the configuration file only. See § 9.1 for an illustration of how quote styles, aliases, and package options interact.

8.4 Executing Package Options Apart from passing options to this package as it is loaded, you may also execute options using the following command:

\ExecuteQuoteOptions{hkey=value, . . . i} This command permits presetting package options in the conﬁguration ﬁle. It may also be used in the document preamble.

8.5 Deﬁning Quotes for PDF Strings The following command speciﬁes the quotation marks for PDF strings:

\DeclarePlainStyle{hopening outer marki}{hclosing outer marki}% {hopening inner marki}{hclosing inner marki} This command may be used in the conﬁguration ﬁle or in the document preamble. By default, outer quotations get straight double quotes and inner quotations straight single quotes. See § 10.6 for additional hints concerning PDF strings.

8.6 Conﬁguring Quotations and Citations The following commands change the default values used by various quotation facilities of this package. The commands affected by these parameters are indicated in table4.

\SetBlockThreshold{hintegeri} \SetBlockEnvironment{henvironmenti} \SetCiteCommand{hcommandi} \SetBlockThreshold deﬁnes the number of lines or words the block quotation facilities use as a threshold when determining whether a quotation should be typeset in

19 Parameter Command or environment \enquote \foreignquote \hyphenquote \textquote \foreigntextquote \hyphentextquote \textcquote \foreigntextcquote \hyphentextcquote \blockquote \foreignblockquote \hyphenblockquote \blockcquote \foreignblockcquote \hyphenblockcquote displayquote foreigndisplayquote hyphendisplayquote displaycquote foreigndisplaycquote hyphendisplaycquote

Threshold – – – – – – – – – •••••• –––––– Environment – – – – – – – – – •••••••••••• Cite command – – – – – – ••• ––– ••• ––– •••

Table 4: Scope of Conﬁgurable Parameters

inline or in display mode. The default is three. \SetBlockEnvironment speciﬁes the environment used for block and display quotations. It takes the name of an existing environment as its argument. The default is the quote environment provided by most document classes. The argument to \SetCiteCommand speciﬁes a replacement for \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 \cite. The citation commands of the natbib, jurabib, and biblatex packages, which take two optional arguments, are supported.

8.7 Hooks for Quotations and Citations The appearance of quotes may be configured at a low level by redefining the hooks introduced below. This section will give an overview of their syntax. See § 9.2 for practical examples. The quotation facilities which are responsive to these hooks are indicated in table5. Also see § 8.8 for tests which may be useful when redefining the hooks.

\mkcitation{hcitei}

All facilities which take a hcitei argument will pass it to the \mkcitation hook, which may be redeﬁned to format the citation. \mkcitation will only be executed if there is a citation. The default behavior is to separate the citation from the preceding text by an interword space and enclose it in parentheses. This is equivalent to the following deﬁnition:

\newcommand*{\mkcitation}[1]{␣(#1)}

20 Hook Command or environment \enquote \foreignquote \hyphenquote \textquote \foreigntextquote \hyphentextquote \textcquote \foreigntextcquote \hyphentextcquote \blockquote \foreignblockquote \hyphenblockquote \blockcquote \foreignblockcquote \hyphenblockcquote displayquote foreigndisplayquote hyphendisplayquote displaycquote foreigndisplaycquote hyphendisplaycquote

\mktextquote ––– •••••••••••• –––––– \mkblockquote ––––––––– •••••• –––––– \mkbegdispquote ––––––––––––––– •••••• \mkenddispquote ––––––––––––––– •••••• \mkcitation ––– ••• ––– ••• ––– ••• ––– \mkccitation –––––– ••• ––– ••• ––– •••

Table 5: Availability of Auxiliary Hooks

\mkccitation{hcite codei}

The integrated quotation facilities use \mkccitation instead of \mkcitation. The default behavior of this command is to separate the citation from the preceding text by an interword space. This is equivalent to the following deﬁnition:

\newcommand*{\mkccitation}[1]{␣#1}

\mktextquote{hopeni}{htexti}{hclosei}{hpuncti}{htpuncti}{hcitei}

The \mktextquote hook controls the layout of all text quotations. This hook is used by \textquote and related commands from §§ 3.3, 3.4, 5.1, 5.2. \blockquote and related commands from §§ 3.5, 3.6, 5.3, 5.4 use this hook for short quotations. It takes six arguments which may be arranged according to the desired output:

#1 The opening quotation mark. #2 The htexti argument of the command. #3 The closing quotation mark. #4 The optional hpuncti argument of the command. If there is no hpuncti argument, this parameter is empty. #5 Trailing htpuncti punctuation immediately after the command. If there is no such punctuation or if the autopunct feature is disabled, this parameter is empty.

21 #6 The optional hcitei argument of the command, wrapped in \mkcitation. If there is no hcitei argument, this parameter is empty. With integrated quotation commands, this parameter is the citation code, wrapped in \mkccitation. By default, \mktextquote encloses the hpuncti argument in the quotation marks along with the htexti and inserts the hcitei argument or the citation code before any trailing htpuncti punctuation. This is equivalent to the following deﬁnition:

\newcommand{\mktextquote}[6]{#1#2#4#3#6#5}

The way in which \mktextquote hooks into the formatting process is best seen when looking at an example. The commands

\textquote[cite]{short quote} \textcquote[55]{key1}[.]{short quote} \blockcquote[87]{key2}{short quote}.

would execute \mktextquote with the following arguments:

\mktextquote{open}{short quote}{close}{}{}{\mkcitation{cite}} \mktextquote{open}{short quote}{close}{.}{}{\mkccitation{\cite[55]{key1}}} \mktextquote{open}{short quote}{close}{}{.}{\mkccitation{\cite[87]{key2}}}

where \cite is the command selected with \SetCiteCommand and open/close are internal macros which print the opening and closing quotation marks. Note that these internal macros are fully-ﬂedged markup elements with grouping and nesting control. They must be placed in the correct order, otherwise csquotes will report errors about unbalanced groups or invalidly nested quotations. Since the htexti should obviously be enclosed in the quotation marks, the parameter order #1#2#3 is effectively ﬁxed. The parameters #4, #5, #6 may be placed freely.

\mkblockquote{htexti}{hpuncti}{htpuncti}{hcitei}

The \mkblockquote hook controls the layout of all block quotations. This hook is used by \blockquote and related commands from §§ 3.5, 3.6, 5.3, 5.4 for long quotations. It takes four arguments which may be arranged according to the desired output: #1 The htexti argument of the command. #2 The optional hpuncti argument of the command. If there is no hpuncti argument, this parameter is empty. #3 Trailing htpuncti punctuation immediately after the command. If there is no such punctuation or if the autopunct feature is disabled, this parameter is empty.

22 #4 The optional hcitei argument of the command, wrapped in \mkcitation. If there is no hcitei argument, this parameter is empty. With integrated quotation commands, this parameter is the citation code, wrapped in \mkccitation. By default, \mkblockquote inserts the hcitei argument or the citation code immediately after the htexti and adds any trailing htpuncti punctuation at the very end. This is equivalent to the following deﬁnition:

\newcommand{\mkblockquote}[4]{#1#2#4#3}

\mkbegdispquote{hpuncti}{hcitei} \mkenddispquote{hpuncti}{hcitei}

The \mkbegdispquote and \mkenddispquote hooks are used by displayquote and related environments from §§ 6.1 and 6.2. These hooks take two arguments:

#1 The hpuncti argument passed to the \begin line of the environment. If there is no hpuncti argument, this parameter is empty. #2 The hcitei argument passed to the environment, wrapped in \mkcitation. If there is no hcitei argument, this parameter is empty. With integrated quotation environments, this parameter is the citation code, wrapped in \mkccitation. By default, \mkenddispquote adds the hpuncti argument as well as the hcitei argument or the citation code at the very end of the quotation. \mkbegdispquote does not insert anything be default. This is equivalent to the following deﬁnition:

\newcommand{\mkbegdispquote}[2]{} \newcommand{\mkenddispquote}[2]{#1#2}

See § 9.2 for practical examples.

8.8 Additional Tests in Quotation Hooks The commands in this section increase the ﬂexibility of the hooks discussed in § 8.7. For example, it may be desirable to adjust the format of a citation depending on the way the corresponding quotation is typeset. It may also be useful to known if the quotation ends with a punctuation mark.

\ifpunctmark{hcharacteri}{htruei}{hfalsei} Expands to htruei if preceeded by the punctuation mark hcharacteri, and to hfalsei otherwise. The hcharacteri may be a period, a comma, a semicolon, a colon, an exclamation mark, or a question mark. Note that this test is only available in the deﬁnition of the hooks from § 8.7.

23 \ifpunct{htruei}{hfalsei} Expands to htruei if preceeded by any punctuation mark, and to hfalsei otherwise. Note that this test is only available in the deﬁnition of the hooks from § 8.7.

\ifterm{htruei}{hfalsei} Expands to htruei if preceeded by a terminal punctuation mark (period, exclamation mark, or question mark), and to hfalsei otherwise. Note that this test is only available in the deﬁnition of the hooks from § 8.7.

\iftextpunctmark{htexti}{hcharacteri}{htruei}{hfalsei} Executes htruei if the htexti ends with the punctuation mark hcharacteri, and to hfalsei otherwise. The hcharacteri may be a period, a comma, a semicolon, a colon, an exclamation mark, or a question mark. This command is robust.

\iftextpunct{htexti}{htruei}{hfalsei} Executes htruei if the htexti ends with any punctuation mark, and to hfalsei otherwise. This command is robust.

\iftextterm{htexti}{htruei}{hfalsei} Executes htruei if the htexti ends with a terminal punctuation mark (period, exclamation mark, or question mark), and to hfalsei otherwise. This command is robust.

\ifblockquote{htruei}{hfalsei} Expands to htruei in all block and display quotations, and to hfalsei otherwise.

\ifblank{hstringi}{htruei}{hfalsei}

This generic command, which is provided by the etoolbox package, expands to htruei if the hstringi is blank (empty or spaces), and to hfalsei otherwise. This is useful to test for an empty argument in the deﬁnition of the \mk...quote commands. Note that this test is redundant in the deﬁnition of the citation hooks because they are only executed if there is a citation.

\unspace Removes preceding whitespace, i. e., removes all skips and penalties from the end of the current horizontal list.

24 8.9 Conﬁguring Punctuation Look-Ahead

\DeclareAutoPunct{hcharactersi} This command deﬁnes the punctuation marks to be considered by the quotation commands as they scan ahead for punctuation. Note that hcharactersi is an unde- limited list of characters. Valid hcharactersi are period, comma, semicolon, colon, exclamation and question mark. The default setting is:

\DeclareAutoPunct{.,;:!?}

This deﬁnition is restored automatically whenever the autopunct package option is set to true. Executing \DeclareAutoPunctuation{} is equivalent to setting autopunct=false, i. e., it disables this feature.

8.10 Conﬁguring Auxiliary Commands The appearance of ellipses and insertions formatted with the auxiliary commands from §7 is controlled by six hooks. When \textelp is used with an empty argument (ellipsis only), it will execute \mktextelp. When used with a non-empty htexti argument (ellipsis and insertion), the htexti will be passed as an argument to \mktextelpins. The starred form will pass the htexti to \mktextinselp instead. These are the default deﬁnitions:

\newcommand{\mktextelp}{[\textellipsis\unkern]} \newcommand{\mktextelpins}[1]{[\textellipsis\unkern]␣[#1]} \newcommand{\mktextinselp}[1]{[#1]␣[\textellipsis\unkern]}

The \textins command passes its htexti argument to \mktextins for further pro- cessing. The starred variant of \textins uses \mktextmod instead. These are the default deﬁnitions:

\newcommand{\mktextins}[1]{[#1]} \newcommand{\mktextmod}[1]{[#1]}

The \textdel command passes its htexti argument to \mktextdel for further pro- cessing. This is the default deﬁnition (note that the argument is not output):

\newcommand{\mktextdel}[1]{[]}

You may redeﬁne the above hooks to change the format of the printed output. For example, if you prefer replacements to be indicated by “[. . . text]” rather than “[. . .] [text]”, redeﬁne \mktextelpins accordingly:

\renewcommand{\mktextelpins}[1]{[\textellipsis #1]}

25 The \unkern in the default definitions is required because \textellipsis adds asymmetric kerning by default. The kerning after the final dot is similar to the spacing between the dots, which is fine if \textellipsis is followed by any text, but undesirable if it is enclosed in brackets.

9 Usage Notes

9.1 Adding a New Quote Style This section will give some comprehensive examples of how to deﬁne new quote styles. The examples presented here will only make use of the most basic components a quote style can be composed of. The main point is to illustrate the interaction of quote styles, variants, aliases, and package options. To get started, consider a simple house style which may be selected by way of the package option style or the command \setquotestyle:

\DeclareQuoteStyle{house} {\textquotedblleft}{\textquotedblright} {\textquoteleft}{\textquoteright}

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 ofﬁcial one and an unofﬁcial one. In this case, we need two backend styles implemented as variants of the newspeak style, newspeak/official and newspeak/unofficial:

\DeclareQuoteStyle[official]{newspeak} {\textquotedblleft}{\textquotedblright} {\textquoteleft}{\textquoteright} \DeclareQuoteStyle[unofficial]{newspeak} {\textquotedblright}{\textquotedblleft} {\textquoteright}{\textquoteleft}

The official variant should be the default for this style. There is no need to copy the definition of the official variant to accomplish that. We simply define an alias labeled newspeak which points to the desired variant:

\DeclareQuoteAlias[official]{newspeak}{newspeak}

The reason why we are using variants and aliases instead of two independent styles will become clear in a moment. Suppose that the babel package offered support for Newspeak, but this language was known to babel as otherspeak:

\DeclareQuoteAlias{newspeak}{otherspeak}

26 This is an example of a second-level alias pointing to a ﬁrst-level alias. If the current language is otherspeak, the above aliases will be expanded as follows: otherspeak = newspeak = newspeak/official

We also deﬁne a new package option to choose a style variant:

\DeclareQuoteOption{newspeak}

This will add a new package option with a key called newspeak. The value of this option may be any variant of the newspeak style defined in the configuration file. In this example, there are two possible values: official and unofficial. To select the default or the alternative style for the entire document we use:

\usepackage[style=newspeak]{csquotes} \usepackage[style=newspeak,newspeak=unofficial]{csquotes}

To select the default or the alternative style with multilingual support we use:

\usepackage[babel]{csquotes} \usepackage[babel,newspeak=unofficial]{csquotes}

The base style must be implemented as an alias in this case since the newspeak option will select a variant by redeﬁning and thus overwriting the newspeak alias. Since the otherspeak alias points to newspeak and not directly to any backend style, using the 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 § 10.9 for details.

9.2 Using Quotation and Citation Hooks Style guides for writers usually make detailed provisions concerning the formatting of quotations and citations, including rules dealing with punctuation placement. This section will discuss some typical usage scenarios, using hooks and other facilities introduced in §§ 8.7, 8.8, 8.9. In the examples below, we assume the following input:

\textquote[citation][.]{This is a complete sentence} \textquote[citation][]{This is an incomplete sentence}.

We start off with semantically strict punctuation placement, i. e., terminal punctuation is enclosed in the quotation marks if it in fact is part of the quotation, and printed after the closing mark if it is not. Our ﬁrst sample cases will use German quotation marks, but the formatting convention, as far as punctuation placement is concerned, is very common. We assume citations in footnotes in the ﬁrst example, hence the desired output is as follows:

27 „This is a complete sentence.“1 „This is an incomplete sentence“.2