Context Sensitive Quotation Marks (csquotes)
--------------------------------------------

For authors in the humanities, quotations are as crucial as verbatim code
fragments for computer scientists and equations for mathematicians. LaTeX
provides environments for typesetting longer quotations, but there is no
dedicated markup for short quotations embedded in the text body. Apart from
that, you might need to type control sequences to get proper quotation marks in
some languages. This is rather tedious and decreases readability of the
document source.

The csquotes package:

 * provides proper markup for inline quotations in the first place
 * supports both control sequences and active characters for the markup
 * toggles between inner and outer quotation marks for nested quotes
 * interfaces with Babel and adapts quotation marks to the document language
 * features fully configurable quotation styles and active characters


License
-------

Copyright (c) 2003 Philipp Lehman, lehman@gmx.net

Permission is granted to copy, distribute and/or modify this software under the
terms of the the LaTeX Project Public License (LPPL), version 1.2.


Installation Instructions
-------------------------

Copy csquotes.sty and csquotes.cfg to a directory that is searched for LaTeX
input files. Please see the following TeX FAQ answers for details:

http://www.tex.ac.uk/cgi-bin/texfaq2html?label=instpackages
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=wherefiles
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds

Don't forget to update the file hash tables!


Usage Instructions
------------------

*** Package Options ***

The csquotes package employs a key=value syntax for all package options. It
offers the following options:

* Activating Babel Support

	babel=true
	      false

This options turns Babel support on or off. Babel support is not activated by
default. Instead of the verbose form 'babel=true' you may also use the short
form 'babel' which implies 'true'. If Babel support is activated, csquotes will
adapt the style of all quotation marks to the active document language.

* Selecting a Fixed Quotation Style

	style=quotation style

If you are not using the Babel package or if you don't want csquotes to sync
the quotation mark style with the active document language, you can also select
a fixed style explicitly. csquotes comes with several predefined styles and
adding more styles or changing the predefined ones is straightforward. Please
see the configuration instructions given below for details.

The following quotation styles are available by default:

afrikaans, american, austrian, brazilian, british, canadian, czech, danish,
dutch, english, finnish, french, german, hungarian, italian, norwegian, polish,
portuguese, romanian, slovakian, spanish, swedish, swiss, turkish.

The selected style will be used throughout the entire document. Note that the
'babel' option will override any fixed style.

* Selecting Language and Style Variants

	english=american        (default)
	        british

	 danish=quotes          (default)
	        guillemets

	 german=quotes          (default)
	        guillemets
	        swiss

	swedish=quotes          (default)
	        guillemets

In some languages there is more than one quotation style. Use the above options
to choose a variant.

Examples:

	\usepackage[babel,english=british,swedish=guillemets]{csquotes}

Here, csquotes will sync the quotation mark style with the active document
language, using the default style for that language. The above line changes
some of these defaults: within English text quotation marks will adhere to the
British standard; within Swedish text csquotes will use guillemets instead of
quotes.

Here's another example: Babel does not offer dedicated support for Swiss
German. This language variant is more or less covered by the regular German
language extension. The quotation marks used in the German-speaking parts of
Switzerland, however, differ from the practice in Germany and Austria.

I suppose Swiss users are using the 'ngerman' option of the Babel package. To
get proper Swiss quotation marks, you need to instruct csquotes to use the
'swiss' variant of the 'german' style in this case:

	\usepackage[ngerman]{babel}
	\usepackage[babel,german=swiss]{csquotes}

Note that the Babel language is 'ngerman' here while csquotes uses 'german'.
Essentially, csquotes will normalize Babel's language names first, using a list
of aliases which map Babel's languages to csquotes's quotation styles. That's
because some languages are known to the Babel package by more than one name.
'USenglish' is an alias of 'american', for example.

While 'ngerman' is different from 'german' as far as Babel is concerned (new
vs. old orthographical rules) this difference is irrelevant for csquotes, hence
'ngerman' is defined as an alias of 'german'. csquotes will expand all aliases
first and select the quotation style after that. A list of all predefined
aliases is included in the configuration instructions given below.


*** Core Macros for the Document ***

* Basic Quoting

The core macro provided by the csquotes package will enclose its argument in
quotation marks:

	\enquote{#1}
	\enquote*{#1}

This macro takes one mandatory argument:

	#1 string to be quoted

\enquote is context sensitive. Depending on the nesting level, it will toggle
between outer and inner quotation marks for plain quotations and quotations
inside another quotation respectively. The 'starred' version, \enquote*, jumps
to the inner level right away. If Babel support is activated by means of the
respective package option, the style of all quotation marks will be synced with
the active document language.

* Quoting Text in a Foreign Language

To make typesetting quotations in a foreign language more convenient, the
csquotes package features two macros which combine \enquote with Babel's local
language switches:

	\foreignquote{#1}{#2}
	\foreignquote*{#1}{#2}

The \foreignquote macro combines the features of \enquote with those of Babel's
\foreignlanguage macro. It takes two mandatory arguments:

	#1 language name (as defined by Babel)
	#2 string to be quoted

Babel's \foreignlanguage macro switches hyphenation patterns and activates all
extra definitions for the respective language, such as shorthands and (for some
languages) micro-typographical adjustments. In addition to that, \foreignquote
will typeset quotation marks matching the language of the quoted string. Like
\enquote*, the starred version of \foreignquote jumps directly to the inner
quotation level.

The \hyphenquote macro works in a similar way:

	\hyphenquote{#1}{#2}
	\hyphenquote*{#1}{#2}

It takes two mandatory arguments:

	#1 language name (as defined by Babel)
	#2 string to be quoted

\hyphenquote combines the features of \enquote with an inline version of
Babel's 'hyphenrules' environment. Unlike \foreignquote, it merely switches the
hyphenation patterns. It will neither activate any extra definitions provided
by Babel nor will it adapt the quotation marks to the language of the quoted
string. The quotation marks will match the style of the text surrounding the
quotation instead. The starred version of \hyphenquote jumps directly to the
inner quotation level.

More verbose instructions concerning these macros are given by way of example
in 'tutorial.tex'.


*** Additional Macros for the Preamble ***

In addition to the control sequences discussed above, csquotes also supports
so-called active characters. An active character is a single character which
works like a control sequence. Designating characters to serve as active
quotation marks is very convenient with csquotes, which comes with several
macros facilitating this. All of these macros may be used in the document
preamble as well as in the configuration file.

* Basic Quoting

The macros \MakeOuterQuote and \MakeInnerQuote define active characters which
will typeset either outer or inner quotation marks respectively:

	\MakeOuterQuote{#1}
	\MakeInnerQuote{#1}

Both macros take one mandatory argument:

	#1 character serving as opening and closing quotation mark

The macro \MakeAutoQuote defines active characters which are capable of
toggling between inner and outer quotation marks for nested quotes:

	\MakeAutoQuote{#1}{#2}

This macro takes two mandatory arguments which must be distinct from each
other:

	#1 character serving as opening quotation mark
	#2 character serving as closing quotation mark

The active characters defined by \MakeAutoQuote are similar in function to the
\enquote macro. Those defined by \MakeOuterQuote and \MakeInnerQuote cover only
a certain part of the functionality provided by \enquote. \MakeOuterQuote
corresponds to the outer level of \enquote (without nesting support) whereas
\MakeInnerQuote corresponds to the inner level (like \enquote*).

Examples:

	\MakeOuterQuote{"}
	\MakeInnerQuote{|}
	\MakeAutoQuote{<}{>}

* Quoting Text in a Foreign Language

You can also define active characters which will typeset quotation marks and
change the language which will be in effect within the quotation (as far as
Babel's specials and hyphenation patterns are concerned):

	\MakeForeignQuote{#1}{#2}{#3}
	\MakeHyphenQuote{#1}{#2}{#3}

Both macros take three mandatory arguments:

	#1 language to activate Babel support for
	#2 character serving as opening quotation mark
	#3 character serving as closing quotation mark

The active characters defined by \MakeForeignQuote are similar in function to
the \foreignquote macro whereas the ones defined by \MakeHyphenQuote work line
\hyphenquote.

Examples:

	\MakeForeignQuote{french}{<}{>}
	\MakeHyphenQuote{dutch}{<}{>}

More examples and some hints concerning the choice of active characters are
given in 'tutorial.tex'.

* Restoring Active Characters

If the definitions of active characters set up by the macros above get
overwritten by another package, you can restore them with the following macro:

	\RestoreQuotes

This macro takes no arguments. It will 'replay' the definitions of all active
characters as recorded in the configuration file and the document preamble. It
only makes sense to use \RestoreQuotes after '\begin{document}'. Since csquotes
will activate its active characters at '\begin{document}', using \RestoreQuotes
earlier would be redundant and might even interfere with other packages.

Use \RestoreQuotes with care. By reclaiming active characters, you may break
other packages. Since the choice of active characters used by csquotes is
entirely up to you, try to choose active characters which are not used by any
other package in the first place.


Hints and Known Issues
----------------------

 * Some of the standard LaTeX classes convert all page headers to uppercase
   strings. When using any language switches provided by the Babel package in a
   page header, Babel will abort with an error message complaining about an
   undefined language. Whenever you say 'language' in a page header (or a
   chapter title used as a running head), Babel will in fact get 'LANGUAGE'.
   Since language names are case-sensitive the garbled name is unknown.

   Due to the nature of TeX's \uppercase primitive this is not easily remedied.
   csquotes works around the problem by converting all language names to
   lowercase before passing them on to Babel. This works well for almost all
   language names except some aliases which include capital letters.
   Fortunately, there are only two such aliases, namely 'USenglish' and
   'UKenglish'. The workaround is simple: just use 'american' and 'british'
   instead.

 * Using quote macros or active quotation marks in PDF bookmarks in conjuntion
   with the Hyperref package is possible, albeit with limited funtionality.
   Hyperref support will be discussed in greater detail in the next section. If
   you intend to use quote macros or active quotation marks in PDF file
   informations strings, note that you have to use \hypersetup to specify the
   strings. Using them in the optional argument of \usepackage when loading the
   Hyperref package will not work.

 * When defining active characters, make sure they don't conflict with other
   packages, most notably the language extensions of the Babel package. More
   verbose hints concerning the choice of active characters are given in
   'tutorial.tex'.


Configuration Instructions
--------------------------

If available, the csquotes package will read a configuration file called
'csquotes.cfg'. Use this file to define additional quotation styles/aliases or
redefine existing ones. csquotes comes with several quotation styles
predefined. For a lot of languages supported by the Babel package no action on
the part of the user should be required. You will only need to delve into the
configuration file if your language is missing or if you intend to add
additional quotation styles for some other reason.


*** Defining Quotation Styles ***

The macro \DeclareQuoteStyle defines a new quotation style or redefines an
existing one.

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

It takes one optional and five mandatory arguments:

	#1 quotation style variant (optional)
	#2 quotation style name
	#3 opening outer quotation mark
	#4 closing outer quotation mark
	#5 opening inner quotation mark
	#6 closing inner quotation mark

This macro may be used in the configuration file or in the document preamble.

As an example, here are some of the predefined styles:

\DeclareQuoteStyle[american]{english}
	{\textquotedblleft}{\textquotedblright}
	{\textquoteleft}{\textquoteright}

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

The following styles/variants are defined by default and have been verified by
a native speaker (these are the actual backend styles only, see the list of
language aliases further down as well):

	danish/guillemets, english/american, english/british, french,
	german/guillemets, german/quotes, german/swiss, italian,
	swedish/guillemets, swedish/quotes

The following styles/variants are defined by default and have been partly
verified:

	danish/quotes

The following styles are defined by default but have not been verified:

	afrikaans, czech, dutch, finnish, hungarian, norwegian, polish,
	portuguese, romanian, slovakian, spanish, turkish

There is no predefined style for the following languages of the Babel package:

	bahasa, basque, breton, bulgarian, catalan, croatian, esperanto,
	estonian, galician, greek, hebrew, icelandic, irish gaelic, latin,
	lower sorbian, north sami, russian, scottish gaelic, slovenian,
	serbian, ukrainian, upper sorbian, welsh

If you need support for one of these languages, use \DeclareQuoteStyle to add a
new quotation style (see the complete example further down). If anyone sends me
suitable styles for the missing languages, I'll gladly include them in
csquotes.


*** Defining Language Aliases ***

If the name of a quotation style differs from the language name used by the
Babel package or if several (Babel) languages share a common quotation style,
use \DeclareQuoteAlias to define a quote alias.

	\DeclareQuoteAlias[#1]{#2}{#3}

This macro takes one optional and two mandatory arguments:

	#1 quotation style variant (optional)
	#2 quotation style name
	#3 alias name

This macro may be used in the configuration file or in the document preamble.

If you define an alias for Babel, the alias name must be identical to the
language name used by the Babel package, i.e. the string used in
'\usepackage[language]{babel}' and '\selectlanguage{language}'. The quotation
style can be either a style defined by \DeclareQuoteStyle or another alias.

Some examples (predefined):

american -> english/american

	\DeclareQuoteAlias[american]{english}{american}

canadian -> english/american

	\DeclareQuoteAlias[american]{english}{canadian}

german   -> german/quotes

	\DeclareQuoteAlias[quotes]{german}{german}

ngerman  -> german

	\DeclareQuoteAlias{german}{ngerman}

The following aliases are defined by default:

	Alias                   Style (or Alias)
	----------------------  -----------------------
	english                 english/american
	american                english/american
	USenglish               american
	canadian                english/american
	british                 english/british
	UKenglish               british
	brazil                  portuguese
	brazilian               portuguese
	portuges                portuguese
	german                  german/quotes
	austrian                german/quotes
	swiss                   german/swiss
	ngerman                 german
	naustrian               austrian
	danish                  danish/quotes
	swedish                 swedish/quotes
	magyar                  hungarian
	norsk                   norwegian
	nynorsk                 norwegian


*** Adding Additional Package Options ***

The macro \DeclareQuoteOption will create a new package option based on a
key=value syntax.

	\DeclareQuoteOption{#1}

It takes one mandatory argument: the quotation style name as defined by the
first mandatory argument of \DeclareQuoteStyle. When using the new package
option, the quotation style will serve as the key. The value of this key can by
any style variant defined for the respective quotation style.

This macro may be used in the configuration file only.


*** Adding a New Quotation Style ***

Here's a comprehensive example. If you wanted to add quotation marks for a
language called Newspeek, you might put the following in your configuration
file:

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

Suppose there were two quotation styles commonly used in Newspeek, an official
one and an inofficial one often seen in low-budget publications. In this case,
you would define the following two styles instead of the one above:

\DeclareQuoteStyle[official]{newspeek}
  {\textquotedblleft}{\textquotedblright}
  {\textquoteleft}{\textquoteright}

\DeclareQuoteStyle[inofficial]{newspeek}
  {\textquotedbl}{\textquotedbl}
  {\textquotesingle}{\textquotesingle}

The official style is, well, official, so it should be the default whenever we
select the style 'newspeek':

\DeclareQuoteAlias[official]{newspeek}{newspeek}

Now suppose Babel offered support for Newspeek, but this language was know as
Oldspeek to Babel:

\DeclareQuoteAlias{newspeek}{oldspeek}

This is an example for an alias pointing to another alias defined before. When
Babel support is turned on and the document language is set to 'oldspeek', the
above aliases will be expanded as follows:

oldspeek -> newspeek -> newspeek/official

Finally, you may want to create a package option to select which of the two
styles to use in a given document:

\DeclareQuoteOption{newspeek}

This will define a new package option called 'newspeek'. The value of this
option may be any variant of the 'newspeek' style. To select a variant, use the
package option as follows:

default style, fixed:

	\usepackage[style=newspeek]{csquotes}

'inofficial' style, fixed:

	\usepackage[style=newspeek,newspeek=inofficial]{csquotes}

default style with Babel:

	\usepackage[babel]{csquotes}

'inofficial' style with Babel:

	\usepackage[babel,newspeek=inofficial]{csquotes}


*** PDF Strings and Hyperref Support ***

You can redefine the characters used as quotation marks in PDF strings:

	\DeclarePlainStyle{#1}{#2}

This macro takes two mandatory arguments:

	#1 opening quotation mark (inner and outer)
	#2 closing quotation mark (inner and outer)

This macro may be used in the configuration file or in the document preamble.

If you use any quotation commands or active quote characters in a chapter
heading, load the Hyperref package and create a PDF file, the quotes will be
included in the bookmarks of the PDF file. csquotes does interface with the
Hyperref package, but note that the capabilities of all macros are severely
limited in this context: there is no way for csquotes to distinguish between
inner and outer quotation marks. This is not a limitation of csquotes but
related to PDF strings and the way Hyperref handles them.

By default, csquotes will replace all quotation marks with plain double
quotes in PDF strings. If you prefer guillemets, add something like the
following to your configuration file:

	\DeclarePlainStyle{\guillemotleft}{\guillemotright}

This replacement mechanism will work in PDF bookmarks as well as in PDF file
information strings, provided that you use \hypersetup to specify the strings.
Please be advised that quote macros or active quotation will not work in the
optional argument of \usepackage when loading the Hyperref package.

For details on the limitations in PDF strings see the Hyperref documentation,
most notably the files 'paper.pdf' and 'slides.pdf'.


Acknowledgments
---------------

I'm indebted to Donald Arseneau, Mark Wooding, and Heiko Oberdiek for their help.


Changelog
---------

2003-12-13      v1.4
  * Improved Hyperref interface

2003-12-11      v1.3
  * Added \MakeForeignQuote and \MakeHyphenQuote
  * Added \RestoreQuotes

2003-09-14      v1.0
  * Initial release
