summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/acro/acro-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/acro/acro-manual.tex')
-rw-r--r--macros/latex/contrib/acro/acro-manual.tex2140
1 files changed, 2140 insertions, 0 deletions
diff --git a/macros/latex/contrib/acro/acro-manual.tex b/macros/latex/contrib/acro/acro-manual.tex
new file mode 100644
index 0000000000..43462b6bac
--- /dev/null
+++ b/macros/latex/contrib/acro/acro-manual.tex
@@ -0,0 +1,2140 @@
+% !arara: pdflatex: { interaction: nonstopmode }
+% !arara: biber
+% arara: pdflatex: { interaction: nonstopmode }
+% arara: pdflatex: { interaction: nonstopmode }
+% arara: pdflatex: { interaction: nonstopmode }
+% --------------------------------------------------------------------------
+% the ACRO package
+%
+% Typeset Acronyms
+%
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web: https://bitbucket.org/cgnieder/acro/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2011--2020 Clemens Niederberger
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Clemens Niederberger.
+% --------------------------------------------------------------------------
+% The acro package consists of the files
+% - acro.sty, acro.definitions.tex, acro.cfg
+% - acro-manual.tex, acro-manual.pdf, acro-manual.cls
+% - acro.history, README
+% --------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% --------------------------------------------------------------------------
+\documentclass{acro-manual}
+
+\addbibresource{\jobname.bib}
+\addbibresource{cnltx.bib}
+\begin{filecontents}{\jobname.bib}
+@online{wikipedia,
+ author = {Wikipedia},
+ title = {Acronym and initialism},
+ urldate = {2012-06-21},
+ url = {http://en.wikipedia.org/wiki/Acronyms},
+ year = {2012}
+}
+@online{NewYork,
+ author = {Wikipedia},
+ title = {New York City},
+ urldate = {2012-09-27},
+ url = {http://en.wikipedia.org/wiki/New_York_City},
+ year = {2012}
+}
+@manual{interface3,
+ author = {{The \LaTeX3 Project Team}} ,
+ shorthand = {L3P} ,
+ sortname = {LaTeX3 Project Team} ,
+ title = {The \LaTeX3 Interfaces} ,
+ date = {2015-09-06} ,
+ url = {http://mirrors.ctan.org/macros/latex/contrib/l3kernel/interface3.pdf}
+}
+\end{filecontents}
+
+% declare acronyms
+\DeclareAcronym{cd}
+ {
+ short = cd ,
+ long = Compact Disc ,
+ short-format = \scshape
+ }
+\DeclareAcronym{ctan}
+ {
+ short = ctan ,
+ long = Comprehensive \TeX\ Archive Network ,
+ format = \scshape ,
+ pdfstring = CTAN ,
+ accsupp = CTAN
+ }
+\DeclareAcronym{ecu}
+ {
+ short = ECU ,
+ long = Steuerger\"at ,
+ foreign = Electronic Control Unit ,
+ foreign-lang = english
+ }
+\DeclareAcronym{id}
+ {
+ short = id ,
+ long = identification string ,
+ short-format = \scshape
+ }
+\DeclareAcronym{jpg}
+ {
+ short = JPEG ,
+ sort = jpeg ,
+ alt = JPG ,
+ long = Joint Photographic Experts Group
+ }
+\DeclareAcronym{la}
+ {
+ short = LA ,
+ short-plural = ,
+ long = Los Angeles,
+ long-plural = ,
+ class = city
+ }
+\DeclareAcronym{lppl}
+ {
+ short = lppl ,
+ long = \LaTeX\ Project Public License ,
+ format = \scshape ,
+ pdfstring = LPPL ,
+ accsupp = LPPL ,
+ index-cmd = \csname @gobble\endcsname
+ }
+\DeclareAcronym{MP}
+ {
+ short = MP ,
+ long = Member of Parliament ,
+ long-plural-form = Members of Parliament
+ }
+\DeclareAcronym{nato}
+ {
+ short = nato ,
+ long = North Atlantic Treaty Organization ,
+ extra = \emph{deutsch}: Organisation des Nordatlantikvertrags ,
+ short-format = \scshape
+ }
+\DeclareAcronym{ny}
+ {
+ short = NY ,
+ short-plural = ,
+ long = New York ,
+ long-plural = ,
+ class = city ,
+ cite = NewYork
+ }
+\DeclareAcronym{ot}
+ {
+ short = ot ,
+ long = Other Test ,
+ short-format = \scshape
+ }
+\DeclareAcronym{pdf}
+ {
+ short = pdf ,
+ long = Portable Document Format ,
+ format = \scshape ,
+ pdfstring = PDF ,
+ accsupp = PDF
+ }
+\DeclareAcronym{sw}
+ {
+ short = SW ,
+ long = Sammelwerk ,
+ long-plural = e
+ }
+\DeclareAcronym{test}
+ {
+ short = ST ,
+ long = Some Test
+ }
+\DeclareAcronym{tex.sx}
+ {
+ short = \TeX.sx ,
+ sort = TeX.sx ,
+ long = \TeX{} StackExchange
+ }
+\DeclareAcronym{ufo}{
+ short = UFO ,
+ long = unidentified flying object ,
+ long-indefinite = an
+}
+
+% because the mannual does not activate the `macros' option:
+\newcommand*\nato{\ac{nato}}
+\newcommand*\ny{\ac{ny}}
+
+\newcommand*\latin[1]{\textit{#1}}
+
+\begin{document}
+\section{Licence and Requirements}
+\license
+
+\acro\ loads and needs the following packages:
+\pkg{expl3}\footnote{\CTANurl{l3kernel}}, \pkg{xparse}, \pkg{xtemplate},
+\pkg{l3keys2e}\footnote{\CTANurl{l3packages}},
+\pkg{zref-abspage}\footnote{\CTANurl{oberdiek}} and
+\needpackage{translations}~\cite{pkg:translations}.
+
+\section{Basics}
+\subsection{Creating New Acronyms}
+Acronyms are created with the command \cs{DeclareAcronym}.
+\begin{commands}
+ \command{DeclareAcronym}[\marg{id}\marg{list of keys}]
+ The basic command for declaring an acronym where \meta{id} is a unique
+ string identifying the acronym. Per default behaviour this is case
+ sensitive which means \code{id} is different from \code{ID}, for example.
+ There is an option \option{case-sensitive}\sinceversion{2.11} to change
+ this.
+\end{commands}
+This command understands a number of keys which are listed below. Some of
+them are not described immediately but at appropriate places in the
+documentation.
+\begin{properties}
+ %% short
+ \propval{short}{text}\Default!
+ The short form of the acronym. \emph{This property is required}: an
+ acronym must have a short form. If this is set it \emph{must} be set as
+ first option! If another property is set first and notices the
+ \property{short} property missing it assumes that the \acs{id} should be
+ used as short version and sets it accordingly. A warning will be written
+ to the log then.
+ %% long
+ \propval{long}{text}\Default!
+ The long form of the acronym. \emph{This property is required}: an
+ acronym must have a description.
+ %% short-plural
+ \propval{short-plural}{text}\Default{s}
+ The plural ending appended to the short form.
+ %% short-plural-form
+ \propval{short-plural-form}{text}
+ The\sinceversion{2.0} plural short form of the acronym; replaces the short
+ form when used instead of appending the plural ending.
+ %% long-plural
+ \propval{long-plural}{text}\Default{s}
+ The plural ending appended to the long form.
+ %% long-plural-form
+ \propval{long-plural-form}{text}
+ Plural long form of the acronym; replaces the long form when used
+ instead of appending the plural ending.
+ %% alt-plural
+ \propval{alt-plural}{text}\Default{s}
+ The\sinceversion{2.0} plural ending appended to the alternative form.
+ %% alt-plural-form
+ \propval{alt-plural-form}{text}
+ The\sinceversion{2.0} plural alternative form of the acronym; replaces the
+ alternative form when used instead of appending the plural ending.
+ %% foreign-plural
+ \propval{foreign-plural}{text}\Default{s}
+ The\sinceversion{2.9} plural ending appended to the foreign form.
+ %% foreign-plural-form
+ \propval{foreign-plural-form}{text}
+ Plural\sinceversion{2.9} foreign form of the acronym; replaces the
+ foreign form when used instead of appending the plural ending.
+ %% list
+ \propval{list}{text}
+ If specified this will be written in the list as description instead of
+ the long form.
+ %% short-indefinite
+ \propval{short-indefinite}{text}\Default{a}
+ Indefinite article for the short form.
+ %% long-indefinite
+ \propval{long-indefinite}{text}\Default{a}
+ Indefinite article for the long form.
+ %% long-pre
+ \propval{long-pre}{text}
+ \meta{text} is prepended to the long form in the text but not in the list
+ of acronyms.
+ %% long-post
+ \propval{long-post}{text}
+ \meta{text} is appended to the long form in the text but not in the list
+ of acronyms.
+ %% long-post
+ \propval{post}{text}
+ \meta{text}\sinceversion{2.8} is appended to the acronym in the text but
+ not in the list of acronyms.
+ %% alt
+ \propval{alt}{text}
+ Alternative short form.
+ %% alt-indefinite
+ \propval{alt-indefinite}{text}\Default{a}
+ Indefinite article for the alternative form.
+ %% extra
+ \propval{extra}{text}
+ Extra information to be added in the list of acronyms.
+ %% foreign
+ \propval{foreign}{original long form}
+ Can be useful when dealing with acronyms in foreign languages, see
+ section~\vref{ssec:foreign} for details.
+ %% foreign-lang
+ \propval{foreign-lang}{language}
+ \sinceversion{2.3}The \pkg{babel}~\cite{pkg:babel} or
+ \pkg{polyglossia}~\cite{pkg:polyglossia} language of the foreign form.
+ This language is used to wrap the entry with
+ \cs*{foreignlanguage}\marg{language} if either \pkg{babel} or
+ \pkg{polyglossia} is loaded. You'll need to take care that the
+ corresponding language is loaded by \pkg{babel} or \pkg{polyglossia}.
+ %% single
+ \propval{single}{text}
+ \sinceversion{2.3}If provided \meta{text} will be used instead of the long
+ form if the acronym is only used a single time \emph{and} the option
+ \keyis{single}{true} is active.
+ %% sort
+ \propval{sort}{text}
+ If used the acronym will be sorted according to this key instead of its
+ \acs{id}.
+ %% class
+ \propval{class}{csv list}
+ The\changedversion{2.4} class(es) the acronym belongs to.
+ %% cite
+ \proplit-{cite}{\oarg{prenote}\oarg{postnote}\marg{citation keys}}
+ A citation that is printed to the acronym according to an option explained
+ later.
+ %% before-citation
+ \propval{before-citation}{code}
+ \meta{code}\sinceversion{2.11} is inserted directly before \property{cite}
+ and \emph{ony when} \property{cite} is used.
+ %% after-citation
+ \propval{after-citation}{code}
+ \meta{code}\sinceversion{2.11} is inserted directly after \property{cite}
+ and \emph{ony when} \property{cite} is used.
+ %% short-format
+ \propval{short-format}{\TeX{} code}
+ The format used for the short form of the acronym.
+ %% long-format
+ \propval{long-format}{\TeX{} code}
+ The format used for the long form of the acronym.
+ %% short-format
+ \propval{alt-format}{\TeX{} code}
+ The\sinceversion{2.10} format used for the alternative form of the
+ acronym. If this is not given the short format will be used.
+ %% first-long-format
+ \propval{first-long-format}{\TeX{} code}
+ The format used for the first long form of the acronym as set with \cs{ac},
+ \cs{acf} or \cs{acflike} and their uppercase, plural and indefinite forms.
+ %% single-format
+ \propval{single-format}{\TeX{} code}
+ \sinceversion{2.3}The format used for the acronym if the acronym is only
+ used a single time.
+ %% first-style
+ \propchoice{first-style}{default,empty,square,short,long,reversed,footnote,sidenote,%
+ footnote-reversed,sidenote-reversed}
+ \sinceversion{2.3}The style of the first appearance of the acronym, see
+ also section~\ref{sec:opti-regard-acronyms}.
+ %% pdfstring
+ \proplit-{pdfstring}{\Marg{\meta{pdfstring}/\meta{plural ending}}}
+ \changedversion{2.4b}Used as \acs{pdf} string replacement in bookmarks
+ when used together with the \pkg{hyperref} package. The appended plural
+ ending is optional. If you leave it (\emph{and} the \code{/}) the default
+ ending is used. \meta{text} is expanded before it is saved.
+ %% accsupp
+ \propval{accsupp}{text}
+ Sets the \code{ActualText} key as presented by the \pkg{accsupp} package
+ for the acronym.
+ %% tooltip
+ \propval{tooltip}{text}
+ \sinceversion{2.1}Sets the tooltip description for an acronym. For
+ actually getting tooltips you also need an appropriate setting of the
+ \option{tooltip-cmd} option or to set the package option
+ \option{tooltip}.
+ %% index-sort
+ \propval{index-sort}{text}
+ If you use the package option \option{index} every occurrence of an
+ acronym is recorded to the index and sorted by its \acs{id} or (if set) by
+ the value of the \property{sort} property. This key allows to set an
+ individual sorting option for the index. See section~\vref{ssec:index}
+ for details.
+ %% index
+ \propval{index}{text}
+ This key allows to overwrite the automatic index entry with an arbitrary
+ one. See section~\vref{ssec:index} for details.
+ %% index-cmd
+ \propval{index-cmd}{control sequence}
+ This key let's you set an individual index creating command for this
+ acronym. It should be a command that takes one mandatory argument. See
+ section~\vref{ssec:index} for details.
+\end{properties}
+
+\begin{bewareofthedog}
+ In its simplest form an acronym needs a short and a long form. Please note
+ that both keys \emph{must} be set and that the \property{short} property
+ \emph{must} always be the \emph{first} property that is set.
+\end{bewareofthedog}
+
+\begin{sourcecode}
+ % preamble:
+ \DeclareAcronym{test}{
+ short = ST ,
+ long = Some Test
+ }
+\end{sourcecode}
+This creates the acronym ``\acs{test}'' with the \acs{id} ``test'' and the
+long form ``\acl{test}.''
+
+The \property{short-format} key allows you to choose a specific format for the
+short form of an acronym:
+\begin{sourcecode}
+ % preamble:
+ \DeclareAcronym{ot}{
+ short = ot ,
+ long = Other Test ,
+ short-format = \scshape
+ }
+\end{sourcecode}
+The short form now looks like this: \acs{ot}.
+
+The \property{cite} key needs a bit explaining. It expects arguments like the
+standard \cs*{cite} command, \latin{i.e.}, two optional arguments setting the
+\meta{prenote} and \meta{postnote} and one mandatory argument setting the
+citation key.
+\begin{sourcecode}
+ % preamble:
+ \DeclareAcronym{ny}{
+ short = NY ,
+ short-plural = ,
+ long = New York ,
+ long-plural = ,
+ cite = {NewYork}
+ }
+\end{sourcecode}
+
+\begin{sourcecode}[sourcecode-options={style=cnltx-bibtex}]
+ % bib file for use with biber/biblatex:
+ @online{NewYork,
+ author = {Wikipedia},
+ title = {New York City},
+ urldate = {2012-09-27},
+ url = {http://en.wikipedia.org/wiki/New_York_City},
+ year = {2012}
+ }
+\end{sourcecode}
+The first appearance now looks as follows\footnote{The appearance of the
+ citation of course depends on the citation style you're using.}: \acf{ny}.
+
+\subsection{Logging of Acronyms}
+When you activate \acro's option\sinceversion{2.5} \option{log} \acro' writes
+information about the acronyms it defines to the log file.
+\begin{options}
+ \keychoice{log}{\default{true},false,silent,verbose}\Default{false}
+ When set to \code{true}/\code{silent} \acro{} writes the main properties
+ of an acronym to the log file. When set to \code{verbose} \acro' writes
+ \emph{all} properties of an acronym to the log file.
+\end{options}
+
+This is an example of the logging info with \keyis{log}{true} or
+\keyis{log}{silent}.
+\begin{sourcecode}
+ =================================================
+ | Package acro Info -- defining new acronym:
+ | ID = {jpg}
+ | short = {JPEG}
+ | long = {Joint Photographic Experts Group}
+ | alt = {JPG}
+ | sort = {jpeg}
+ | class = {}
+ | list = {}
+ | extra = {}
+ | foreign = {}
+ | pdfstring = {}
+ | cite = {}
+ =================================================
+\end{sourcecode}
+
+\subsection{Using the Acronyms -- the Commands}\label{sec:using-acronyms-comm}
+Acronyms are used with one of the following commands:
+\begin{commands}
+ %%
+ \command{ac}[\sarg\marg{id}]
+ basic command; the first output is different from subsequent ones.
+ \command{Ac}[\sarg\marg{id}]
+ same as \cs{ac} but capitalizes the first letter. Obeys the option
+ \option{uppercase-short}.
+ %%
+ \command{acs}[\sarg\marg{id}]
+ \h{s}hort form; the actual acronym.
+ \command{Acs}[\sarg\marg{id}]
+ same\sinceversion{2.10} as \cs{acs} but capitalizes the first letter.
+ %%
+ \command{acl}[\sarg\marg{id}]
+ \h{l}ong form; the meaning of the acronym.
+ \command{Acl}[\sarg\marg{id}]
+ same as \cs{acl} but capitalizes first letter.
+ %%
+ \command{aca}[\sarg\marg{id}]
+ \h{a}lternative short form as specified in the \property{alt} property of
+ \cs{DeclareAcronym}; if it hasn't been specified this is identical to
+ \cs{acs}.
+ \command{Aca}[\sarg\marg{id}]
+ same\sinceversion{2.10} as \cs{aca} but capitalizes the first letter.
+ %%
+ \command{acf}[\sarg\marg{id}]
+ first form; output like the first time \cs{ac} is output.
+ \command{Acf}[\sarg\marg{id}]
+ same as \cs{acf} but capitalizes first letter. Obeys the option
+ \option{uppercase-short}.
+ %%
+ \command{acp}[\sarg\marg{id}]
+ \h{p}lural form of \cs{ac};
+ \command{Acp}[\sarg\marg{id}]
+ same as \cs{acp} but capitalizes first letter. Obeys the option
+ \option{uppercase-short}.
+ %%
+ \command{acsp}[\sarg\marg{id}]
+ plural form of \cs{acs};
+ \command{Acsp}[\sarg\marg{id}]
+ same\sinceversion{2.10} as \cs{acsp} but capitalizes the first letter.
+ %%
+ \command{aclp}[\sarg\marg{id}]
+ plural form of \cs{acl};
+ \command{Aclp}[\sarg\marg{id}]
+ same as \cs{aclp} but capitalizes first letter.
+ %%
+ \command{acap}[\sarg\marg{id}]
+ plural form of \cs{aca};
+ \command{Acap}[\sarg\marg{id}]
+ same\sinceversion{2.10} as \cs{acap} but capitalizes the first letter.
+ %%
+ \command{acfp}[\sarg\marg{id}]
+ plural form of \cs{acf};
+ \command{Acfp}[\sarg\marg{id}]
+ same as \cs{acfp} but capitalizes first letter of the long form. Obeys
+ the option \option{uppercase-short}.
+\end{commands}
+If an acronym is used the first time with \cs{ac} its output is different from
+subsequent uses. To be clear on this: the first time! If the acronym has
+been used with \emph{any} of the output commands before it is \emph{not} the
+first time any more.
+
+If you use the starred variant an acronym will not be marked as used. This
+proves useful if an acronym is typeset in a section title, for example, since
+then the appearance in the table of contents won't mark it as used.
+
+\begin{example}[side-by-side]
+ % preamble:
+ % \DeclareAcronym{cd}{
+ % short = cd ,
+ % long = Compact Disc ,
+ % short-format = \scshape
+ % }
+ first time: \ac{cd} \\
+ second time: \ac{cd} \\
+ short: \acs{cd} \\
+ alternative: \aca{cd} \\
+ first again: \acf{cd} \\
+ long: \acl{cd} \\
+ short plural: \acsp{cd} \\
+ long plural: \aclp{cd}
+\end{example}
+
+\subsection{Plural Forms}
+If an acronym is defined in the standard way \acro\ uses an `s' that's appended
+to both the short and the long form when one of the plural commands is used.
+However, that is not always the best solution. For one thing not all acronyms
+may have a plural form. Second, the plural form especially of the long forms
+may be formed differently. And third, other languages can have other plural
+endings.
+
+For these reasons \cs{DeclareAcronym} can get the following keys:
+\begin{properties}
+ \propval{short-plural}{text}\Default{s}
+ The plural ending of the short form.
+ \propval{long-plural}{text}\Default{s}
+ The plural ending of the long form.
+ \propval{long-plural-form}{text}
+ An alternative plural form for the long form.
+\end{properties}
+These keys are optional. If they're not used, the default setting is
+\code{s}. If you use \property{long-plural-form} the long form will be
+replaced by the specified plural form when necessary.
+
+Suppose we define the following acronyms:
+\begin{sourcecode}
+ \DeclareAcronym{cd}{
+ short = cd ,
+ long = Compact Disc ,
+ short-format = \scshape
+ }
+ \DeclareAcronym{ny}{
+ short = NY ,
+ short-plural = ,
+ long = New York ,
+ long-plural =
+ }
+ \DeclareAcronym{sw}{
+ short = SW ,
+ long = Sammelwerk ,
+ long-plural = e
+ }
+ \DeclareAcronym{MP}{
+ short = MP ,
+ long = Member of Parliament ,
+ long-plural-form = Members of Parliament
+ }
+\end{sourcecode}
+These acronyms now have the following plural appearances:
+\begin{example}[side-by-side]
+ \acsp{cd}, \aclp{cd} \\
+ \acsp{ny}, \aclp{ny} \\
+ \acsp{sw}, \aclp{sw} \\
+ \acsp{MP}, \aclp{MP}
+\end{example}
+
+In the default setting the format of the long or short form is not extended to
+the plural ending which might look strange if you choose bold weight as
+format, for example. In this case you can tell \acro\ to extend the format.
+\begin{options}
+ \keybool{format-include-endings}\Default{false}
+ Tell\sinceversion{2.8} \acro\ to use the format of the base form for the
+ endings, too.
+\end{options}
+For a more general view on endings please read section
+\vref{sec:about-plural-forms}.
+
+\subsection{Alternative Short Forms}
+For some acronyms it might be useful to have alternative forms. For this
+\cs{DeclareAcronym} has another key:
+\begin{properties}
+ \propval{alt}{text}
+ Alternative short form.
+\end{properties}
+\begin{example}
+ % preamble:
+ % \DeclareAcronym{jpg}{
+ % short = JPEG ,
+ % sort = jpeg ,
+ % alt = JPG ,
+ % long = Joint Photographic Experts Group
+ % }
+ default: \acs{jpg} \\
+ alt.: \aca{jpg}
+\end{example}
+The alternative form uses the same plural ending as the default short form and
+is formatted in the same way.
+
+\subsection{Extra Information for the List Entry}
+Of course you can print a list of acronyms where their meaning is explained.
+Sometimes it can be useful to add additional information there. This is done
+with another key to \cs{DeclareAcronym}:
+\begin{properties}
+ \propval{extra}{text}
+ Additional information for the list of acronyms.
+\end{properties}
+These information will only be displayed in the list. See
+section~\vref{sec:print_lists} for the impact of the following example.
+
+\begin{example}
+ % preamble:
+ % \DeclareAcronym{nato}{
+ % short = nato ,
+ % long = North Atlantic Treaty Organization ,
+ % extra = \textit{deutsch}: Organisation des Nordatlantikvertrags ,
+ % short-format = \scshape
+ % }
+ The \ac{nato} is an intergovernmental military alliance based on the
+ North Atlantic Treaty which was signed on 4~April 1949. \ac{nato}
+ headquarters are in Brussels, Belgium, one of the 28 member states
+ across North America and Europe, the newest of which, Albania and
+ Croatia, joined in April 2009.
+\end{example}
+
+\subsection{Foreign Language Acronyms}\label{ssec:foreign}
+I repeatedly read the wish for being able to add translations to acronyms when
+the acronyms stem from another language than the document language,
+\latin{i.e.}, something like the following in a German document:
+\begin{example}[side-by-side]
+ \ac{ecu}\\
+ \ac{ecu}
+\end{example}
+That's why I decided to add the following properties:
+\begin{properties}
+ \propval{foreign}{original long form}
+ A description for an acronym originating in another language than the
+ document language.
+ \propval{foreign-lang}{language}
+ \sinceversion{2.3}The \pkg{babel}~\cite{pkg:babel} or
+ \pkg{polyglossia}~\cite{pkg:polyglossia} language of the foreign form.
+ This language is used to wrap the entry with
+ \cs*{foreignlanguage}\marg{language}.
+\end{properties}
+
+Here is the definition of the above mentioned \ac{ecu} acronym:
+\begin{sourcecode}
+ \DeclareAcronym{ecu}{
+ short = ECU ,
+ long = Steuerger\"at ,
+ foreign = Electronic Control Unit ,
+ foreign-lang = english
+ }
+\end{sourcecode}
+As you have seen this adds the \property{foreign} entry to the first
+appearance of an acronym. It is also added in parentheses to the list of
+acronyms after the \property{long} entry. Actually the entry there is the
+argument to the following command:
+\begin{commands}
+ \command{acroenparen}[\marg{argument}]
+ Places \meta{argument} in parentheses: \cs{acroenparen}\Marg{example}:
+ \acroenparen{example}. See page~\pageref{key:list-foreign-format} for a
+ way to customize this other than redefining it.
+\end{commands}
+
+\section{Additional Commands and Possibilities}
+\subsection{Indefinite Forms}
+
+Unlike many other languages\footnote{Let's better say: unlike the other
+ languages where I know at least the basics.} in English the indefinite
+article is not determined by the grammatical case, gender or number but by the
+pronounciation of the following word. This means that the short and the long
+form of an acronym can have different indefinite articles. For these cases
+\acro\ offers the following keys:
+\begin{properties}
+ \propval{short-indefinite}{article}\Default{a}
+ Indefinite article for the short form.
+ \propval{alt-indefinite}{article}\Default{a}
+ Indefinite article for the alternative form.
+ \propval{long-indefinite}{article}\Default{a}
+ Indefinite article for the long form.
+\end{properties}
+For every lowercase singular command two alternatives exist, preceded by
+\code{i} and \code{I}, respectively, which output the lowercase and uppercase
+version of the corresponding indefinite article.
+
+\begin{example}
+ % preamble:
+ % \DeclareAcronym{ufo}{
+ % short = UFO ,
+ % long = unidentified flying object ,
+ % long-indefinite = an
+ % }
+ \Iac{ufo}; \iacs{ufo}; \iacl{ufo}
+\end{example}
+
+\subsection{Uppercasing}
+\begin{commands}
+ \command{acfirstupper}[\marg{token list}]
+ This command uppercases the first token in \meta{token list}. The
+ command is less powerful than \cs{makefirstuc} that is provided by the
+ \pkg{mfirstuc} package~\cite{pkg:mfirstuc} but it is expandable. Obvious
+ downsides are for example that it does not uppercase accented letters.
+\end{commands}
+The following options control the behaviour of the uppercasing commands:
+\begin{options}
+ \keyval{uc-cmd}{control sequence}\Default{\cs{acfirstupper}}
+ The command that is used to capitalize the first word in the \cs{Ac} and
+ the like commands. You can change it to another one like for example
+ \cs*{makefirstuc}\footnote{from the \pkg{mfirstuc} package} or
+ \cs*{MakeTextUppercase}\footnote{from the \pkg*{textcase} package}.
+ %%
+ \keybool{uppercase-short}\Default{true}
+ If\sinceversion{2.10} set to \code{true} commands like \cs{Ac} or \cs{Acp}
+ will uppercase the first letter of the short form. Commands like \cs{Acs}
+ or \cs{Acsp} will uppercase the short form in any case.
+\end{options}
+
+\subsection{Simulating the First Appearance}\label{sec:simul-first-appe}
+Users told me\footnote{Well -- one, to be precise ;)} that there are cases
+when it might be useful to have the the acronym typeset according to the
+\option{first-style} option (or \property{first-style} property) but with
+another text than the long form. For such cases \acro\ offers the following
+commands.
+\begin{commands}
+ \command{acflike}[\sarg\marg{id}\marg{instead of long form}]
+ Write some alternative long form for acronym with \acs{id} \meta{id} as if
+ it were the first time the acronym was used.
+ \command{acfplike}[\sarg\marg{id}\marg{instead of long form}]
+ Plural form of \cs{acflike}.
+\end{commands}
+
+\begin{example}[side-by-side]
+ \acsetup{first-style=footnote}
+ \acflike{ny}{the big apple}
+\end{example}
+
+The plural ending in \cs{acfplike} is only appended to the short form. It
+makes no sense to append it to the text that is inserted manually anyway.
+Note that whatever text you're inserting might be gobbled depending on the
+\option{first-style} you're using.
+
+\subsection{Fetching the Single Appearance}
+There\sinceversion{2.3} are macros that fetch the \emph{single} appearance of
+an acronym even if it has been used more than once and the \option{single}
+option is active.
+\begin{commands}
+ \command{acsingle}[\sarg\marg{id}]
+ Write acronym as if it were used only a single time.
+ \command{Acsingle}[\sarg\marg{id}]
+ Uppercase form of \cs{acsingle}.
+ \command{acpsingle}[\sarg\marg{id}]
+ Plural\sinceversion{2.11} form of \cs{acsingle}.
+ \command{Acsingle}[\sarg\marg{id}]
+ Plural\sinceversion{2.11} form of \cs{Acsingle}.
+\end{commands}
+
+\begin{example}[side-by-side]
+ \acsingle{ny}
+\end{example}
+
+\subsection{Using Classes}
+The acronyms of \acro\ can be divided into different classes. This doesn't
+change the output but allows different acronym lists, see
+section~\vref{sec:print_lists}. For this \cs{DeclareAcronym} has an additional
+key:
+\begin{properties}
+ \propval{class}{csv list}
+ Associated\changedversion{2.4} class(es) for an acronym.
+\end{properties}
+
+This might be useful if you can and want to divide your acronyms into
+different types, technical and grammatical ones, say, that shall be listed in
+different lists. Since every acronym can get a list of associated classes
+those classes can effectively be used like tags for filtering acronyms.
+
+\begin{example}[side-by-side]
+ % preamble:
+ % \DeclareAcronym{la}{
+ % short = LA ,
+ % short-plural = ,
+ % long = Los Angeles ,
+ % long-plural = ,
+ % class = city
+ % }
+ % \DeclareAcronym{ny}{
+ % short = NY ,
+ % short-plural = ,
+ % long = New York ,
+ % long-plural = ,
+ % class = city ,
+ % cite = NewYork
+ % }
+ \acl{la} (\acs{la}) \\
+ \acl{ny} (\acs{ny})
+\end{example}
+
+\subsection{Reset or Mark as Used, Test if Acronym Has Been Used}
+
+If you want for some reason to fool \acro\ into thinking that an acronym is
+used for the first time you can call one of these commands:
+\begin{commands}
+ \command{acreset}[\marg{comma separated list of ids}]
+ This will reset a used acronym such that the next use of \cs{ac} will
+ again print it as if it were used the first time. This will \emph{not}
+ remove an acronym from being printed in the list if it actually \emph{has}
+ been used before.
+ \command{acresetall}
+ Reset all acronyms.
+ \command{acifused}[\marg{id}\marg{true}\marg{false}]
+ This command tests if the acronym with \ac{id} \meta{id} has already been
+ used and either puts \code{true} or \code{false} in the input stream.
+ \command{aciffirst}[\marg{true}\marg{false}]
+ To\sinceversion{2.8} be used inside of acronym definitions in order to
+ test if we are inside the first instance of the acronym or not.
+\end{commands}
+\begin{example}[side-by-side]
+ \acreset{ny}\ac{ny}
+\end{example}
+Beware that both commands act \emph{globally}! There are also commands that
+effectively do the opposite of \cs{acreset}, \latin{i.e.}, mark acronyms as
+used:
+\begin{commands}
+ \command{acuse}[\marg{comma separated list of ids}]
+ This has the same effect as if an acronym had been used twice, that is,
+ further uses of \cs{ac} will print the short form and the acronym will in
+ any case be printed in the list (as long as its class is not excluded).
+ \command{acuseall}
+ Mark all acronyms as used.
+\end{commands}
+Then there are two further commands related to using acronyms:
+\begin{commands}
+ \command{acswitchoff}
+ This\sinceversion{2.6} command is for patching in certain situations. For
+ example some table environments like \env*{tabularx} or \env*{tabu} pass
+ their content two or more times for determining the width of the table
+ columns. Those can be patched to add \cs{acswitchoff} to their trial
+ phase.
+ \command{acswitchon}
+ Effectively\sinceversion{2.6} the opposite of \cs{acswitchoff} -- this
+ command should probably never be needed.
+\end{commands}
+
+\subsection{\cs*{ac} and Friends in \acs*{pdf} Bookmarks, Accessibility
+ Support, Tooltips}
+\subsubsection{\acs*{pdf} Bookmarks}
+\acro's commands usually are not expandable which means they'd leave unallowed
+tokens in \acs{pdf} bookmarks. \pkg{hyperref} offers \cs*{texorpdfstring} to
+circumvent that issue manually but that isn't really a nice solution. What's
+the point of having macros to get output for you if you have to specify it
+manually after all?
+
+That is why \acro\ offers a preliminary solution for this. In a bookmark
+every \cs{ac} like command falls back to a simple text string typesetting what
+\cs{acs} would do (or \cs{acsp} for plural forms). These text strings both
+can accessed manually and can be modified to an output reserved for \acs{pdf}
+bookmarks.
+
+\begin{commands}
+ \command{acpdfstring}[\marg{id}]
+ Access the text string used in \acs{pdf} bookmarks.
+ \command{acpdfstringplural}[\marg{id}]
+ Access the plural form of the text string used in \acs{pdf} bookmarks.
+\end{commands}
+\begin{properties}
+ \proplit-{pdfstring}{\Marg{\meta{pdfstring}/\meta{plural ending}}}
+ Key for \cs{DeclareAcronym} to declare a custom text string for \acs{pdf}
+ bookmarks. The plural ending can be set optionally.
+\end{properties}
+
+For example the \acs{pdf} acronym used in the title for this section is defined
+as follows:
+\begin{sourcecode}
+ \DeclareAcronym{pdf}{
+ short = pdf ,
+ long = Portable Document Format ,
+ format = \scshape ,
+ pdfstring = PDF ,
+ accsupp = PDF
+ }
+\end{sourcecode}
+
+\subsubsection{Accessibility Support}
+
+The last example also demonstrates the \property{accsupp} key. The idea is to
+have something different visible in the \acs{pdf} file compared to what you
+get when you select and copy the corresponding string. In the example visible
+string is a lowercase \code{pdf} in small caps while the string copied is an
+uppercase \code{PDF}.
+
+For this to work you need to use the \emph{package option} \option{accsupp},
+too, which will load the package \pkg{accsupp} if it isn't loaded by the user
+already. Then the key \property{accsupp} will set the \code{ActualText}
+property of \cs*{BeginAccSupp}. Please refer to \pkg{accsupp}'s documentation
+for details. To see its effect copy \ac{pdf} and paste it into a text file.
+You should get uppercase letters instead of lowercase ones.
+
+\begin{properties}
+ \propval{accsupp}{text}
+ Key for \cs{DeclareAcronym} to set the \code{ActualText} property of
+ \cs*{BeginAccSupp} (see \pkg{accsupp}'s documentation for details) to be
+ used for an acronym. It only has an effect when the package option
+ \option{accsupp} is used, too.
+\end{properties}
+\begin{options}
+ \keybool{accsupp}\Default{false}
+ Activate \acro's accessibility support.
+\end{options}
+
+\subsubsection{Tooltips}
+
+The idea of a tooltip is to have some text shown when you hover with the
+mouse over the short form of an acronym. This is only available in some
+\acs{pdf} viewers, though. On possibility for such tooltips is loading the
+\pkg{pdfcomment} package~\cite{pkg:pdfcomment} and using its \cs*{pdftooltip}
+macro.
+
+\begin{options}
+ \keybool{tooltip}\Default{false}
+ This\sinceversion{2.1} options loads the \pkg{pdfcomment} package and sets
+ the command for creating tooltips to \cs*{pdftooltip}.
+ \keyval{tooltip-cmd}{control sequence}\Default{\cs*{@firstoftwo}}
+ This\sinceversion{2.1} allows users using another macro for tooltips --
+ maybe one provided by another package or some own macro. It needs to be a
+ macro with two mandatory arguments, the first being the string typeset in
+ the \acs{pdf}, the second being the tooltip description text.
+\end{options}
+
+For using this with acronyms they have a property \property{tooltip} which can
+be used inside \cs{DeclareAcronym} for specifying the description text of the
+tooltip. If the \option{tooltip} package option is used but the property is
+not set for an acronym then the \property{long} property is used instead.
+
+If an acronym is used inside of another acronym then the tooltips of the
+``inner'' acronyms are disabled.
+
+\subsection{Adding Acronyms to the Index}\label{ssec:index}
+\acro\ has the package option \option{index}. If it is used an index entry
+will be recorded every time an \emph{unstarred} acronym command is used. The
+index entry will be \code{\meta{id}@\meta{short}},
+\code{\meta{sort}@\meta{short}} if the \property{sort} property has been set,
+\code{\meta{index-sort}@\meta{short}} if the property \property{index-sort}
+has been set, or \meta{index} if the property \property{index} has been set
+for the specific acronym. The short versions appearing there are formatted
+according to the chosen format of the corresponding acronym, of course.
+
+This document demonstrates the feature. You can find every acronym that has
+been declared in the index. In order to allow flexibility the indexing
+command can be chosen both globally via package option and individually for
+every acronym. This would allow to add acronyms to a specific index if more
+than one index is used, for example with help of the \pkg*{imakeidx} package.
+
+I'm not yet convinced this is a feature many people if anyone needs and if
+they do if it is flexible enough. If you have any thoughts on this I'd
+appreciate an email.
+
+\section{Printing the List}\label{sec:print_lists}
+Printing the whole list of acronyms is easy: just place \cs{printacronyms}
+where ever you want the list to be.
+\begin{commands}
+ \command{printacronyms}[\oarg{options}]
+ Print the list of acronyms.
+\end{commands}
+The commands takes a few options, namely the following ones:
+\begin{options}
+ \keyval{include-classes}{list of classes}
+ Takes a comma-separated list of the classes of acronyms that should be in
+ the list.
+ \keyval{exclude-classes}{list of classes}
+ Takes a comma-separated list of the classes of acronyms that should
+ \emph{not} be in the list. \emph{Note that this list overwrites any
+ entries in \option{include-classes}!} If a class is both included and
+ excluded then the corresponding acronyms will not be added to the list.
+ \keyval{name}{name of the list}
+ sets the name for the list.
+ \keyval{heading}{sectioning command without leading backslash}%
+ \Default{section*}
+ Sets the sectioning command for the heading of the list. A special value
+ is \code{none} which suppresses the heading.
+ \keybool{sort}\Default{true}
+ Set sorting for this list only.
+ \keybool{local-to-barriers}\Default{false}
+ This\sinceversion{2.4} option can be used to create a list of only the
+ acronyms of the current \enquote{barrier group}, see
+ section~\ref{sec:divid-your-docum}.
+\end{options}
+\begin{example}
+ \acsetup{extra-style=comma}
+ \printacronyms[exclude-classes=city]
+
+ \printacronyms[include-classes=city,name={City Acronyms}]
+\end{example}
+
+You can see that the default layout is a \code{description} list with a
+\cs*{section}\sarg\ title. Both can be changed, see
+section~\vref{sec:customization}.
+
+The command \cs{printacronyms} needs two \LaTeX{} runs. This is a precaution
+to avoid error messages with a possibly empty list. But since almost all
+documents need at least two runs and often are compiled much more often than
+that, this fact shouldn't cause too much inconvenience.
+
+\section{Options and Customization}\label{sec:customization}
+\subsection{General Options}
+There are a few options which change the general behaviour of \acro.
+\default{Underlined} values are used if no value is given. \acro's package
+options are best set onyl via the setup command:
+\begin{commands}
+ \command{acsetup}[\marg{options}]
+ Set up \acro.
+\end{commands}
+\begin{bewareofthedog}
+ They \emph{might} work as package options to \cs*{usepackage} as well but
+ \emph{I do not recommend it} and will likely remove this in a future
+ version~3 of \acro.
+\end{bewareofthedog}
+
+\begin{options}
+ \keychoice{messages}{silent,loud}\Default{loud}
+ Setting \keyis{messages}{silent} will turn all of \acro's error messages
+ into warnings and all of \acro's warnings into info messages. Be sure to
+ check the log file carefully if you decide to set this option.
+ %%
+ \keybool{single}\Default{false}
+ If set to \code{true} an acronym that's used only once (with \cs{ac}) in a
+ document will only print the acronym in a specified form and will not be
+ printed in the list.
+ %%
+ \keybool{case-sensitive}\Default{true}
+ If\sinceversion{2.11} set to \code{true} the \meta{id} as used in
+ \cs{DeclareAcronym} or \cs{ac} is read \emph{case sensitive},
+ \latin{i.e.}, \code{id} would differ from \code{ID}. This is \acro's
+ default behaviour.
+
+ If set to \code{true} \code{id} would be the same as \code{ID}. This can
+ be useful when acronyms are used in page headings for example.
+ %%
+ \keychoice{single-form}{long,short,alt,first}\Default{long}
+ \sinceversion{2.0}Determines how a single appearance of an acronym is
+ printed if \keyis{single}{true} has been chosen.
+ %%
+ \keybool{hyperref}\Default{false}
+ If set to \code{true} the short forms of the acronyms will be linked to
+ their list entry.
+ %%
+ \keybool{label}\Default{false}
+ If set to \code{true} this option will place
+ \cs*{label}\Marg{\meta{prefix}\meta{id}} the first time the acronym with
+ \ac{id} \meta{id} is used.
+ %%
+ \keyval{label-prefix}{text}\Default{ac:}
+ The prefix for the \cs*{label} that is placed when option
+ \keyis{label}{true} is used.
+ %%
+ \keybool{only-used}\Default{true}
+ This option is \code{true} as default. It means that only acronyms that
+ are actually used in the document are printed in the list. If
+ \code{false}, all acronyms defined with \cs{DeclareAcronym} will be
+ written to the list.
+ %%
+ \keychoice{mark-as-used}{first,any}\Default{any}
+ This option determines wether an acronym is mark as used when the
+ \emph{first} form is used the first time (with \cs{ac}, \cs{acf} or
+ \cs{acflike} and their uppercase, plural and indefinite forms) or when any
+ of the \cs{ac}-like commands is used.
+ %%
+ \keybool{macros}\Default{false}
+ If set to \code{true} this option will create a macro \cs*{\meta{id}} for
+ each acronym as a shortcut for \cs{ac}\marg{id}. Already existing macros
+ will \emph{not} be overwritten.
+ %%
+ \keybool{xspace}\Default{false}
+ If set to \code{true} this option will append \cs*{xspace} from the
+ \pkg*{xspace} package to the commands created with the \option{macros}
+ option.
+ %%
+ \keybool{strict}\Default{false}
+ If set to \code{true} and the option \keyis{macros}{true} is in effect
+ then already existing macros will be overwritten.
+ %%
+ \keybool{sort}\Default{true}
+ If set to \code{true} the acronym list will be sorted alphabetically. The
+ entries are sorted by their \acs{id} ignoring upper and lower case. This
+ option needs the experimental package \pkg{l3sort} (from the
+ \pkg{l3experimental} bundle) and can only be set in the preamble.
+ If set to \code{false} the acronyms are listed in order of their
+ declaration.
+ %%
+ \keybool{display-foreign}\Default{true}
+ When set to \code{false} any \property{foreign} property is ignored and
+ foreign forms are not displayed.
+ %%
+ \keychoice{cite}{\default{all},first,none}\Default{first}
+ \changedversion{2.4b}This option decides whether citations that are added
+ via \property{cite} are added to each first, every or no appearance of an
+ acronym. If \code{first} is chosen, the option \keyis{single}{true} is
+ active and an acronym appears only once it still will get the citation.
+ %%
+ \keyval{cite-cmd}{control sequence}\Default{\cs*{cite}}
+ This option determines which command is used for the citation. Each
+ citation command that takes the cite key as argument is valid, for example
+ \pkg*{biblatex}'s \cs*{footcite}.
+ %%
+ \keyval{cite-connect}{code}\Default{\cs*{nobreakspace}}
+ Depending on the citation command in use a space should be inserted before
+ the citation or maybe not (e.g.\ \cs*{footcite}\ldots). This option
+ allows you to set this. Actually it can be used to place arbitrary code
+ right before the citation.
+ %%
+ \keybool{group-citation}\Default{false}
+ \sinceversion{2.0}If set to true the short form (or the long form) and the
+ citation of an acronym will be printed together in parentheses when an
+ acronym is used the first time.
+ %%
+ \keyval{group-cite-cmd}{control sequence}\Default{\cs*{cite}}
+ \sinceversion{2.0}This option determines which command is used for the
+ citation when an acronym is used the first time \emph{and}
+ \keyis{group-citation}{true}. Each citation command that takes the cite
+ key as argument is valid, for example \pkg*{biblatex}'s \cs*{footcite}.
+ %%
+ \keyval{group-cite-connect}{code}\Default{\code{,\cs*{nobreakspace}}}
+ \sinceversion{2.0}When \keyis{group-citation}{true} this is inserted
+ between the long/short form of the acronym and the citation within the
+ parentheses.
+ %%
+ \keybool{index}\Default{false}
+ If set to \code{true} an index entry will be recorded every time an
+ \emph{unstarred} acronym command is used for the corresponding acronym.
+ %%
+ \keyval{index-cmd}{control sequence}\Default{\cs*{index}}
+ Chooses the index command that is used when option \option{index} has been
+ set to \code{true}.
+ %%
+ \keybool{accsupp}\Default{false}
+ Activates the access support as provided by the \pkg{accsupp} package.
+ %%
+ \keybool{tooltip}\Default{false}
+ \sinceversion{2.1}Activates tooltip support for \acro\ using the
+ \pkg{pdfcomment} package.
+ %%
+ \keyval{tooltip-cmd}{control sequence}\Default{\cs*{@firstoftwo}}
+ \sinceversion{2.1}A macro taking two mandatory arguments, the first being
+ the short form of the acronym and the second being some tooltip
+ description.
+ %%
+ \keyval{uc-cmd}{control sequence}\Default{\cs{acfirstupper}}
+ The command that is used to capitalize the first word in the \cs{Ac} and
+ the like commands. You can change it to another one like for example
+ \cs*{makefirstuc}\footnote{from the \pkg{mfirstuc} package} or
+ \cs*{MakeTextUppercase}\footnote{from the \pkg*{textcase} package}.
+ %%
+ \keybool{uppercase-short}\Default{true}
+ If\sinceversion{2.10} set to \code{true} commands like \cs{Ac} or \cs{Acp}
+ will uppercase the first letter of the short version.
+\end{options}
+
+\begin{example}
+ % with \acsetup{macros} activated:
+ we could have used these before: \nato, \ny
+\end{example}
+
+\subsection{Options Regarding Acronyms}\label{sec:opti-regard-acronyms}
+The options described in this section all influence the layout of one of the
+possible output forms of the acronyms.
+\begin{options}
+ %%
+ \keyval{short-format}{format}\Default
+ Sets a format for all short forms. For example
+ \keyis{short-format}{\cs*{scshape}} would print all short forms in small
+ caps.
+ %%
+ \keyval{long-format}{format}\Default
+ The same for the long forms.
+ %%
+ \keyval{foreign-format}{format}\Default
+ The format for the \property{foreign} entry when it appears as part of the
+ first appearance of an acronym.
+ %%
+ \keyval{single-format}{format}\Default
+ \sinceversion{2.3}%
+ The format for the acronym when it is used only once. If not specified
+ the formatting according to \option{single-form} is used.
+ %%
+ \keyval{first-long-format}{format}\Default
+ The format for the long form on first usage (with \cs{ac}, \cs{acf} or
+ \cs{acflike} and their uppercase, plural and indefinite forms).
+ %%
+ \keyval{list-short-format}{format}\Default
+ An extra format for the short entries in the list. If not used this is
+ the same as \option{short-format}. Please be aware that a call of
+ \option{short-format} after this one will overwrite it again.
+ %%
+ \keyval{list-short-width}{dim}\Default{3em}
+ \sinceversion{2.1}This option controls the width reserved for the short
+ forms of the acronyms in the \code{lof} list style.
+ %%
+ \keyval{list-long-format}{format}\Default
+ An extra format for the long entries in the list. If not used this is the
+ same as \option{long-format}. Please be aware that a call of
+ \option{long-format} after this one will overwrite it again.
+ %%
+ \keyval{list-foreign-format}{format}\Default{\cs{acroenparen}}
+ \label{key:list-foreign-format}The format for the \property{foreign} entry
+ as it appears in the list. This may be code that ends with a macro that
+ takes a mandatory argument.
+ %%
+ \keyval{extra-format}{format}\Default
+ The same for the extra information.
+ %%
+ \keychoice{first-style}{default,empty,square,short,long,reversed,footnote,sidenote,%
+ footnote-reversed,sidenote-reversed}\Default{default}
+ The basic style of the first appearance of an acronym. The value
+ \code{sidenote} needs the command \cs*{sidenote} to be defined (for
+ example by the \pkg*{sidenotes} package).
+ %%
+ \keychoice{extra-style}{default,plain,comma,paren,bracket}\Default{default}
+ Defines the way the extra information is printed in the list.
+ %%
+ \keylit{plural-ending}{\meta{short}/\meta{long}}\Default{s/s}
+ \changedversion{2.4b}With this option the default plural ending can be
+ set. The appended \meta{long} ending is optional. If you leave it
+ (\emph{and} the \code{/}) the \meta{short} ending is used for both short
+ and long versions.
+\end{options}
+
+\begin{example}[side-by-side]
+ % (Keep in mind that we're in
+ % a minipage here!)
+ \acsetup{first-style=empty}
+ empty: \acf{ny} \\
+ \acsetup{first-style=footnote}
+ footnote: \acf{ny} \\
+ \acsetup{first-style=square}
+ square: \acf{ny} \\
+ \acsetup{first-style=short}
+ short: \acf{ny} \\
+ \acsetup{first-style=long}
+ long: \acf{ny} \\
+ \acsetup{first-style=reversed}
+ reversed: \acf{ny} \\
+ \acsetup{first-style = footnote-reversed}
+ footnote-reversed: \acf{ny}
+\end{example}
+
+\subsection{Options Regarding the List}
+\begin{options}
+ %%
+ \keychoice{page-style}{none,plain,comma,paren}\Default{none}
+ If this option is set to a value other than \code{none} the page numbers
+ of the an acronym appeared on are printed in the list. Please note that
+ this is an experimental feature and might fail in quite a number of cases.
+ If you notice anything please send me an email!
+ %%
+ \keychoice{pages}{all,first}\Default{all}
+ If the option \option{page-style} has any value other than \code{none}
+ this option determines wether all usages of the acronyms are listed or
+ only the first time. Implicitly sets \keyis{label}{true}.
+ %%
+ \keyval{page-name}{page name}\Default{p.\cs*{@}\cs*{,}}
+ The ``name'' of the page label. This is automatically translated to the
+ active language. However for the time being there are many translations
+ missing, yet. Please notify me if you find your language missing.
+ %%
+ \keyval{pages-name}{page name plural}\Default{pp.\cs*{@}\cs*{,}}
+ The ``name'' of the page label when there are more than one page. This is
+ automatically translated to the active language. However for the time
+ being there are many translations missing, yet. Please notify me if you
+ find your language missing.
+ %%
+ \keybool{following-page}\Default{false}
+ If set to \code{true} a page range in the list of acronyms that consists
+ of two pages will be written by the first page and an appended
+ \code{f}. This depends on the option \option{next-page}.
+ %%
+ \keybool{following-pages}\Default{false}
+ If set to \code{true} a page range in the list of acronyms that set
+ consists of more than two pages will be written by the first page and an
+ appended \code{ff}. This depends on the option \option{next-pages}.
+ %%
+ \keybool{following-pages*}\Default{false}
+ \sinceversion{2.5}If set to \code{true} this sets both options
+ \keyis{following-page}{true} and \keyis{following-pages}{true}.
+ \code{false} sets \keyis{following-page}{false} and
+ \keyis{following-pages}{false}.
+ %%
+ \keyval{next-page}{text}\Default{\cs*{,}f.\cs*{@}}
+ Appended to a page number when \option{following-page} is set to
+ \code{true} and the range is only 2 pages long. This is automatically
+ translated to the active language. However, for the time being there are
+ many translations missing, yet. Please notify me if you find your
+ language missing.
+ %%
+ \keyval{next-pages}{text}\Default{\cs*{,}ff.\cs*{@}}
+ Appended to a page number when \option{following-pages} is set to
+ \code{true} and the range is more than 2 pages long. This is
+ automatically translated to the active language. However, for the time
+ being there are many translations missing, yet. Please notify me if you
+ find your language missing.
+ %%
+ \keychoice{list-style}{description,lof,longtable,extra-longtable,%
+ extra-longtable-rev,extra-tabular,extra-tabular-rev,tabular,toc}%
+ \Default{description}
+ \changedversion{2.2}Choose with which style the list of acronyms should be
+ typeset. If you choose \meta{longtable}, \code{extra-longtable} or
+ \code{extra-longtable-rev} you have to load the
+ \pkg{longtable}~\cite{pkg:longtable} package in your preamble. The values
+ \code{extra-\meta{something}} put the extra information in a column of it
+ own. \emph{Be aware that per default \emph{all} \code{extra-table} styles
+ only use \code{l} columns. Since acronym descriptions can easily get
+ longer that a line you should probably define your own style if you want
+ to use them.} See section~\vref{sec:lists} for details.
+ %%
+ \keychoice{list-heading}{chapter,chapter*,section,section*,subsection,%
+ subsection*,subsubsection,subsubsection*,addchap,addsec,none}%
+ \Default{section*}
+ \changedversion{2.0}The heading type of the list. The last two only work
+ with a \KOMAScript{} class that also defines the appropriate command. A
+ special value is \code{none} which suppresses the heading.
+ %%
+ \keyval{list-name}{list name}\Default{Acronyms}
+ The name of the list. This is what's written in the list-heading. This
+ is automatically translated to the active language. However, for the time
+ being there are many translations missing, yet. Please notify me if you
+ find your language missing.
+ %%
+ \keybool{list-caps}\Default{false}
+ Print the first letters of the long form capitalized.
+\end{options}
+
+\section{Trailing Tokens and Special Action}
+
+\acro\ has the possibility\sinceversion{2.0} to look ahead for certain tokens
+and switch a boolean if it finds them. Per default \acro\ knows about three
+tokens: the \enquote{\code{dot}} (\code{.}), the \enquote{\code{dash}}
+(\code{-}) and the \enquote{\code{babel-hyphen}} (\cs*{babelhyphen}).
+
+A token is made known to \acro\ with the following macro:
+\begin{commands}
+ \command{AcroRegisterTrailing}[\meta{token}\marg{name}]
+ This registers the token \meta{token} so \acro\ looks if it follows
+ directly after an acronym macro. \meta{name} is the internal name for
+ this token.
+\end{commands}
+The \acro\ package already registers the above mentioned tokens:
+\begin{sourcecode}
+ \AcroRegisterTrailing . {dot}
+ \AcroRegisterTrailing - {dash}
+ \AcroRegisterTrailing \babelhyphen {babel-hyphen}
+\end{sourcecode}
+
+If a token is registered it doesn't mean that \acro\ looks for it. The token
+must first be activated for this:
+\begin{options}
+ \keyval{activate-trailing-tokens}{csv list of token names}
+ Tell \acro\ to look for trailing tokens. This is done by giving a csv
+ list of the internal \emph{names} of the tokens. Per default only
+ \code{dot} is activated.
+ \keyval{deactivate-trailing-tokens}{csv list of token names}
+ Tell \acro\ not to look for trailing tokens. This is done by giving a csv
+ list of the internal \emph{names} of the tokens.
+\end{options}
+
+All of the above on its own does nothing visible. However: inside of an
+acronym, \ie, for example inside the long or the short form it can be tested
+for those trailing tokens:
+\begin{commands}
+ \command{aciftrailing}[\marg{csv list of token
+ names}\marg{true}\marg{false}]
+ Check if one of the tokens listed in \meta{csv list of token names} is
+ following and either place \meta{true} or \meta{false} in the input
+ stream.
+\end{commands}
+\acro\ uses this to define to further macros:
+\begin{commands}
+ \command{acdot} Inserts a \code{.} if no \code{dot} follows.
+ \command{acspace} Inserts a \cs*{space} if no \code{dash} or
+ \code{babel-hyphen} follows.
+\end{commands}
+The definitions are equivalent\footnote{Not \emph{quite}: \acro's definitions
+ are engine protected.} to the following code:
+\begin{sourcecode}
+ \newcommand*\acdot{\aciftrailing{dot}{}{.\@}}
+ \newcommand*\acspace{\aciftrailing{dash,babel-hyphen}{}{\space}}
+\end{sourcecode}
+
+This could be used to define an acronym as follows:
+\begin{sourcecode}
+ \DeclareAcronym{etc}{
+ short = {\textit{etc}\acdot} ,
+ long = {\textit{et cetera}} ,
+ short-plural = , long-plural =
+ }
+\end{sourcecode}
+If now you somewhere use
+\begin{sourcecode}
+ \ac{etc}.
+\end{sourcecode}
+there won't be two dots printed.
+
+The command \cs{acspace} is used already in the definition of the first
+appearance of a macro. Let's say you're a German chemist and you have
+\begin{sourcecode}
+ \DeclareAcronym{PU}{
+ long = Polyurethan ,
+ long-plural = e
+ }
+\end{sourcecode}
+and you use it the first time like this:
+\begin{sourcecode}
+ \ac{PU}-Hartschaum
+\end{sourcecode}
+then according to German orthography and typesetting rules this should be
+printed as
+\begin{center}
+ \enquote{Polyurethan(PU)-Hartschaum}
+\end{center}
+\ie, with \emph{no} space between long and short form. This is exactly what
+happens it you say
+\begin{sourcecode}
+ \acsetup{activate-trailing-tokens = {dash,babel-hyphen}}
+\end{sourcecode}
+in the preamble.
+
+\section{About Page Ranges}
+If you enable the \option{page-style} option \acro\ adds page numbers to the list
+of acronyms. In version~0.\versionstar{} it would add a page reference for an
+acronym in the list of acronyms that used \cs*{pageref} to refer to the first
+appearance of an acronym. This is retained using \keyis{pages}{first}.
+Version~1.0 uses a different approach that doesn't use a label but instead
+will list \emph{all} pages an acronym appeared on. With \pkg{hyperref} the
+pages are referenced using \cs*{hyperpage}.
+
+There are some options that control how this list will be typeset, e.g.,
+\option{following-page}, \option{next-pages} or the option \option{page-style}
+itself. It is important to mention that the page list will always take at
+least two compilation runs until changes in the options or the actual page
+numbers affect it. This is due to the fact that the updated sequence is first
+written to the \code{aux} file and only read in during the next run.
+
+\section{Dividing Your Document Into Pieces -- Creating Local
+ Lists}\label{sec:divid-your-docum}
+
+\acro\sinceversion{2.4} introduces the concept of \emph{barriers} which can
+divide the document into parts. It is possible to create lists of only those
+acronyms used between two such barriers.
+\begin{commands}
+ \command{acbarrier}
+ Sets a barrier at the point of use in the document. The begin and the end
+ of the document mark implicit barriers.
+\end{commands}
+\begin{options}
+ \keybool{use-barriers}\Default{false}
+ \sinceversion{2.5}If you want to use barriers and local lists you have to
+ activate the feature first. This should be set in the preamble in order
+ to work reliably. Make sure to watch out for log file messages asking you
+ to rerun.
+ \keybool{reset-at-barriers}\Default{false}
+ If this option is set to \code{true} \cs{acbarrier} implicitly calls
+ \cs{acresetall}.
+ \keybool{local-to-barriers}\Default{false}
+ This option can \emph{only} be used as option to the \cs{printacronyms}
+ command. It then prints a list of only the acronyms of the current
+ \enquote{barrier group}.
+\end{options}
+
+\begin{example}
+ \acbarrier
+ \printacronyms[local-to-barriers]
+ \ac{ctan} and \ac{lppl}
+ \acbarrier
+\end{example}
+
+\section{Language Support}
+\acro\ detects if packages \pkg{babel}~\cite{pkg:babel} or
+\pkg{polyglossia}~\cite{pkg:babel} are being loaded and tries to adapt certain
+strings to match the chosen language. However, due to my limited language
+knowledge only a few translations are provided. I'll show how the English
+translations are defined so you can add the translations to your preamble if
+needed. Even better would be you'd send me a short email to
+\mailto{contact@mychemistry.eu} with the appropriate translations for your
+language and I'll add them to \acro.
+
+\begin{sourcecode}
+ \DeclareTranslation{English}{acronym-list-name}{Acronyms}
+ \DeclareTranslation{English}{acronym-page-name}{p.}
+ \DeclareTranslation{English}{acronym-pages-name}{pp.}
+ \DeclareTranslation{English}{acronym-next-page}{f.}
+ \DeclareTranslation{English}{acronym-next-pages}{ff.}
+\end{sourcecode}
+
+\section{hyperref Support}
+The option \keyis{hyperref}{true} adds internal links from all short (or
+alternative) forms to their respective list entries. Of course this only
+works if you have loaded the \pkg{hyperref} package in your preamble. You
+should use this option with care: if you don't use \cs{printacronyms} anywhere
+this option will result in loads of \pkg{hyperref} warnings. Also printing
+several lists can result in warnings if don't clearly separate the lists into
+different classes. If an acronym appears in more than one list there will
+also be more than one hypertarget for this acronym.
+
+Using \pkg{hyperref} will also add \cs*{hyperpage} to the page numbers in the
+list (provided they are displayed in the style chosen). Like with an index
+the references will thus not point to the acronyms directly but to the page
+they're on.
+
+\section{Defining Own Acronym Macros}\label{sec:defining-own-acronym}
+
+The commands\sinceversion{2.0} explained in
+section~\vref{sec:using-acronyms-comm} have all been defined with a dedicated
+command -- there is a family of dedicated commands, actually:
+\begin{commands}
+ \command{NewAcroCommand}[\marg{cs}\marg{code}]
+ Defines a new \acro\ acronym command \meta{cs}. This sets up the
+ necessary framework needed by acronym commands and defines \meta{cs} with
+ an optional star argument and a mandatory argument for the acronym id
+ using \pkg{xparse}'s \cs*{NewDocumentCommand}. Inside \meta{code} one can
+ refer to the \acs{id} \meta{id} with \code{\#1}.
+ \command{RenewAcroCommand}[\marg{cs}\marg{code}]
+ Defines a new \acro\ acronym command \meta{cs}. This sets up the
+ necessary framework needed by acronym commands and defines \meta{cs} with
+ an optional star argument and a mandatory argument for the acronym id
+ using \pkg{xparse}'s \cs*{RenewDocumentCommand}. Inside \meta{code} one
+ can refer to the \acs{id} \meta{id} with \code{\#1}.
+ \command{DeclareAcroCommand}[\marg{cs}\marg{code}]
+ Defines a new \acro\ acronym command \meta{cs}. This sets up the
+ necessary framework needed by acronym commands and defines \meta{cs} with
+ an optional star argument and a mandatory argument for the acronym id
+ using \pkg{xparse}'s \cs*{DeclareDocumentCommand}. Inside \meta{code} one
+ can refer to the \acs{id} \meta{id} with \code{\#1}.
+ \command{ProvideAcroCommand}[\marg{cs}\marg{code}]
+ Defines a new \acro\ acronym command \meta{cs}. This sets up the
+ necessary framework needed by acronym commands and defines \meta{cs} with
+ an optional star argument and a mandatory argument for the acronym id
+ using \pkg{xparse}'s \cs*{ProvideDocumentCommand}. Inside \meta{code} one
+ can refer to the \acs{id} \meta{id} with \code{\#1}.
+\end{commands}
+
+Inside these macros one can use a number of low-level expl3
+commands\footnote{Which is why you need to use them inside an expl3
+ programming environment. This means in the preamble surround the
+ definitions with \cs*{ExplSyntaxOn} and \cs*{ExplSyntaxOff}.}.
+
+\paragraph{Acronym fetching commands}
+\begin{commands}
+ \command*{acro_use:n}[ \marg{id}]
+ Fetches the acronym using either the first or the short form depending on
+ earlier uses.
+ \command*{acro_short:n}[ \marg{id}]
+ Fetches the short form of the acronym.
+ \command*{acro_long:n}[ \marg{id}]
+ Fetches the long form of the acronym.
+ \command*{acro_alt:n}[ \marg{id}]
+ Fetches the alternative short form of the acronym.
+ \command*{acro_foreign:n}[ \marg{id}]
+ Fetches the foreign property of the acronym if available.
+ \command*{acro_extra:n}[ \marg{id}]
+ Fetches the extra property of the acronym if available.
+\end{commands}
+
+\paragraph{Acronym setup commands}
+\begin{commands}
+ \command*{acro_first_upper:}
+ \acro\ setup command which tells the macros above that we want to
+ uppercase the first letter of the long version. Should be used
+ \emph{before} one of the acronym fetching commands.
+ \command*{acro_plural:}
+ \acro\ setup command which tells the macros above that we want to use
+ plural forms. Should be used \emph{before} one of the acronym fetching
+ commands.
+ \command*{acro_indefinite:}
+ \acro\ setup command which tells the macros above that we want to add the
+ indefinite article. Should be used \emph{before} one of the acronym
+ fetching commands.
+ \command*{acro_cite:}
+ \acro\ setup command which tells the macros above that we want to add the
+ citation in any case independent of the option \option{cite}. Should be
+ used \emph{before} one of the acronym fetching commands.
+ \command*{acro_no_cite:}
+ \acro\ setup command which tells the macros above that we want to have no
+ citation independent of the option \option{cite}. Should be used
+ \emph{before} one of the acronym fetching commands.
+ \command*{acro_index:}
+ \acro\ setup command which tells the macros above that we want to add an
+ index entry in any case independent of the option \option{index}. Should
+ be used \emph{before} one of the acronym fetching commands.
+ \command*{acro_reset_specials:}
+ This\sinceversion{2.0b} macro is called implicitly by \cs{NewAcroCommand}
+ and \cs{NewPseudoAcroCommand}. If you plan to define an \acro\ command by
+ yourself using \cs*{NewDocumentCommand} this should be the first macro
+ after \verbcode+\acro_begin:+. It ensures that in nested acronyms the
+ inner acronyms don't inherit indefinite articles, uppercasing,
+ endings\ldots
+\end{commands}
+
+\paragraph{Additional macros for further uses}
+\begin{commands}
+ \command*{acro_begin:}
+ When an acronym macro is defined \enquote{by hand}, \ie, \emph{not using
+ \cs{NewAcroCommand}} then this must be the first macro in the code.
+ \emph{Must have a matching \cs*{acro_end:}}.
+ \command*{acro_end:}
+ When an acronym macro is defined \enquote{by hand}, \ie, \emph{not using
+ \cs{NewAcroCommand}} then this must be the last macro in the code.
+ \emph{Must have a matching \cs*{acro_begin:}}.
+ \command*{acro_check_and_mark_if:nn}[ \marg{boolean expression} \marg{id}]
+ Checks if the acronym with the \acs{id} \meta{id} exists and marks it as
+ used when \meta{boolean} expression evaluates to \code{true}. This macro
+ is used inside \cs{NewAcroCommand} and friends implicitly.
+ \command*{acro_check_acronym:nn}[ \marg{id} \Marg{true|false}]
+ Checks if the acronym with the \acs{id} \meta{id} exists and marks it as
+ used if \code{true} or doesn't. This macro is used inside
+ \cs*{acro_check_and_mark_if:nn}.
+ \command*{acro_use_acronym:n}[ \Marg{true|false}]
+ Tell \cs*{acro_use:n} and similar commands wether to mark the acronym as
+ used or not. This macro is used inside \cs*{acro_check_acronym:nn}. If
+ this macro is used explicitly it should be used before \cs*{acro_use:n}
+ (or a similar command) otherwise it has no effect. An acronym marked as
+ used cannot be unmarked.
+ \command*{acro_mark_as_used:n}[ \marg{id}]
+ Explicitly use the acronym with the \acs{id} \meta{id}. This is the expl3
+ macro applied to all entries in \cs{acuse}.
+ \expandable\command*{acro_if_acronym_used:n}[\TF\ \marg{id} \marg{true}
+ \marg{false}]
+ The code-level version of \cs{acifused}. This macro is expandable.
+ \command*{acro_for_all_acronyms_do:n}[ \marg{code}]
+ Loops over all acronyms known when the macro is used. Inside of
+ \meta{code} you can refer to the \acs{id} \meta{id} of an acronym with
+ \verbcode+#1+.
+ \command*{acro_barrier:}
+ The code-level version of \cs{acbarrier}.
+ \command*{acro_switch_off:}
+ The\sinceversion{2.6} expl3 version of \cs{acswitchoff}.
+ \command*{acro_switch_on:}
+ The\sinceversion{2.6} expl3 version of \cs{acswitchon}.
+ \command*{acro_add_action:n}[ \marg{code}]
+ Adds\sinceversion{2.7} code to \cs*{acro_get:n}. Inside of \meta{code}
+ you can refer to the \ac{id} of the acronym with \verbcode+#1+.
+ The \cs*{acro_get:n} command is called the first macro that is called by
+ \cs*{acro_use:n} which for example enables conditionals to test for
+ certain acronym properties.
+ \command*{acro_property_get:nn}[\TF\ \marg{id} \marg{property} \marg{true}
+ \marg{false}]
+ Fetches\changedversion{2.11} the property \meta{property} of the acronym
+ \meta{id} and stores it in a tokenlist variable
+ \cs*{l__acro_\meta{property}_tl} where all dashes in the property names
+ are replaced with underscores. \meta{true} is placed in the input stream
+ if the property had been set, \meta{false} otherwise.
+ \command*{acro_property_get:nn}[\marg{id} \marg{property}]
+ Like\changedversion{2.11} \cs*{acro_property_get:nn}\TF, but without the
+ \meta{true} and \meta{false} arguments.
+ \command*{acro_property_if_set:nn}[\TF\ \marg{id} \marg{property} \marg{true}
+ \marg{false}]
+ Checks\changedversion{2.11} if the property \meta{property} of the acronym
+ \meta{id} is set and places \meta{true} is in the input stream if yes and
+ \meta{false} otherwise.
+\end{commands}
+
+\paragraph{Examples}
+The usage of above macros is best explained with a few examples. The
+following definition is done by \acro:
+\begin{sourcecode}
+ \NewAcroCommand \ac { \acro_use:n {#1} }
+\end{sourcecode}
+An equivalent definition for \cs{ac} would be
+\begin{sourcecode}
+ \NewDocumentCommand \ac {sm}
+ {
+ \acro_begin:
+ \acro_reset_specials:
+ \acro_check_and_mark_if:nn {#1} {#2}
+ \acro_use:n {#2}
+ \acro_end:
+ }
+\end{sourcecode}
+which should explain what the actual framework is which \cs{NewAcroCommand}
+adds.
+
+Other definitions by \acro\ are for example the following ones:
+\begin{sourcecode}
+ \NewAcroCommand \Ac
+ {
+ \acro_first_upper:
+ \acro_use:n {#1}
+ }
+ \NewAcroCommand \iac
+ {
+ \acro_indefinite:
+ \acro_use:n {#1}
+ }
+ \NewAcroCommand \acp
+ {
+ \acro_plural:
+ \acro_use:n {#1}
+ }
+ \NewAcroCommand \Acp
+ {
+ \acro_plural:
+ \acro_first_upper:
+ \acro_use:n {#1}
+ }
+ \NewAcroCommand \Aclp
+ {
+ \acro_plural:
+ \acro_first_upper:
+ \acro_long:n {#1}
+ }
+\end{sourcecode}
+
+\section{About Plural Forms, Possessive Forms and Similar Constructs -- the
+ Concept of Endings}\label{sec:about-plural-forms}
+
+\acro\ has a concept of \emph{endings}. All of \acro's plural options are
+defined by saying
+\begin{sourcecode}
+ \ProvideAcroEnding {plural} {s} {s}
+\end{sourcecode}
+The command's syntax and what it does is as follows:
+\begin{commands}
+ \command{ProvideAcroEnding}[\marg{name}\marg{short default}\marg{long default}]
+ This macro defines the options
+ \begin{itemize}
+ \item \option*{\meta{name}-ending},
+ \item \option*{short-\meta{name}-ending},
+ \item \option*{alt-\meta{name}-ending},
+ \item \option*{long-\meta{name}-ending} and
+ \item \option*{foreign-\meta{name}-ending}.
+ \end{itemize}
+ It also defines the acronym properties
+ \begin{itemize}
+ \item \property*{short-\meta{name}},
+ \item \property*{short-\meta{name}-form},
+ \item \property*{alt-\meta{name}},
+ \item \property*{alt-\meta{name}-form},
+ \item \property*{long-\meta{name}},
+ \item \property*{long-\meta{name}-form},
+ \item \property*{foreign-\meta{name}} and
+ \item \property*{foreign-\meta{name}-form}.
+ \end{itemize}
+ Additionally it defines a setup macro as
+ described in section~\vref{sec:defining-own-acronym},
+ \cs*{acro_\meta{name}:}. If \meta{name} contains a \code{-} (dash) it is
+ replaced by \code{\_} before \cs*{acro_\meta{name}:} is built. So if you
+ choose \code{my-name} the corresponding macro is named
+ \cs*{acro_my_name:}. If you use any other non-letters you are on your
+ own. \changedversion{2.4b}If you use the command with the same \meta{name}
+ a second time the command only resets the defaults.
+
+ Note that you \emph{must use \cs{ProvideAcroEnding} before any acronym
+ definition}!
+\end{commands}
+
+This could be used together with the macros described in
+section~\vref{sec:defining-own-acronym} for adding support for possessive
+forms:
+\begin{example}
+ \ExplSyntaxOn
+ % this now only works because I've used the same already in the preamble so
+ % it does nothing here:
+ \ProvideAcroEnding {possessive} {'s} {'s}
+
+ \ProvideAcroCommand \acg
+ {
+ \acro_possessive:
+ \acro_use:n {#1}
+ }
+ \ExplSyntaxOff
+ The \acg{cd} booklet says\ldots
+\end{example}
+
+Please note that different endings are cumulative which you probably want to
+avoid! Imagine a macro
+\begin{sourcecode}
+ \NewAcroCommand \acgp
+ {
+ \acro_possessive:
+ \acro_plural:
+ \acro_use:n {#1}
+ }
+\end{sourcecode}
+This would give \enquote{\ac{cd}s's} instead of \enquote{\ac{cd}s'}. To solve
+this you might want to consider
+\begin{sourcecode}
+ \ProvideAcroEnding {possessive-singular} {'s} {'s}
+ \ProvideAcroEnding {possessive-plural} {s'} {s'}
+\end{sourcecode}
+
+\section{More on Customization}\label{sec:more-custom}
+\subsection{Background Information}
+Several of \acro's objects are customized using templates. For each of these
+objects it is possible to define own templates\footnote{This requires some
+knowledge of \pkg{xtemplate} and expl3. Plans are to provide a documented
+interface for users of \acro{} in the future.}. Possibly more interesting: it
+is easily possible to define further instances of an object using a certain
+template. How this works is explained in the following sections. However, the
+basics are always the same. There is a command
+\begin{commands}
+ \command*{DeclareAcro\meta{object
+ type}Style}[\marg{name}\marg{template}\marg{options}]
+ which allows to define a new style (\ie, instance) for the object
+ \meta{object type} using the template \marg{template}.
+\end{commands}
+
+\subsection{Lists}\label{sec:lists}
+\subsubsection{Own List Style}
+
+The different existing list styles are all built from four different
+templates, \code{list}, \code{list-of}, \code{table} and \code{extra-table}.
+Those templates are defined with the help of the \pkg{xtemplate}
+package (from~\cite{bnd:l3packages}). Each of these templates has a few
+options which are described in table~\vref{tab:list-templates}. New list
+styles now are defined via the following macro:
+
+\begin{commands}
+ \command{DeclareAcroListStyle}[\marg{name}\marg{template}\marg{options}]
+ Declares a new \acro\ list style \meta{name}. \meta{name} will be the
+ value which can be chosen in the option \option{list-style}.
+ \meta{template} is the name of the template to be used by the style.
+ Available templates are listed in table~\ref{tab:list-templates}.
+ \meta{options} are the option settings for the corresponding template.
+\end{commands}
+
+\begin{table}
+ \centering
+ \caption{Available List Templates and Their Options}\label{tab:list-templates}
+ \begin{tabular}{*{4}{>{\ttfamily}l}}
+ \toprule
+ \normalfont\bfseries Template & \normalfont\bfseries Option &
+ \normalfont\bfseries Option Type & \normalfont\bfseries Default \\
+ \midrule
+ list & list & tokenlist & description \\
+ & foreign-sep & tokenlist & \cs*{space} \\
+ & reverse & boolean & false \\
+ & before & tokenlist \\
+ & after & tokenlist \\
+ \midrule
+ list-of & style & tokenlist & toc \\
+ & foreign-sep & tokenlist & \cs*{space} \\
+ & reverse & boolean & false \\
+ & before & tokenlist \\
+ & after & tokenlist \\
+ \midrule
+ table & table & tokenlist & tabular \\
+ & table-spec & tokenlist & lp\{.7\cs*{linewidth}\} \\
+ & foreign-sep & tokenlist & \cs*{space} \\
+ & reverse & boolean & false \\
+ & before & tokenlist \\
+ & after & tokenlist \\
+ \midrule
+ extra-table & table & tokenlist & tabular \\
+ & table-spec & tokenlist & llll \\
+ & foreign-sep & tokenlist & \cs*{space} \\
+ & reverse & boolean & false \\
+ & before & tokenlist \\
+ & after & tokenlist \\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+For defining new styles you need some information on what the different
+templates and options do:
+\begin{itemize}
+ \item The option \code{list} of the \code{list} template sets the list
+ environment. This must be a classic \LaTeX\ list where items are listed
+ with \cs*{item}. In those lists short entries will always be fed as
+ optional argument to \cs*{item}: \\
+ \code{\cs*{item}[\meta{short}]\meta{long}\meta{extra}\meta{page}}
+ \item The template \code{list-of} simulates a table of contents or a list of
+ figures. This can be chosen by setting the option \code{style} to either
+ \code{toc} or \code{lof}.
+ \item The template \code{table} typesets the list in a table with two
+ columns: \\
+ \code{\meta{short} \& \meta{long}\meta{extra}\meta{page}
+ \cs*{tabularnewline}}
+ \item The template \code{extra-table} typesets the list in a table with four
+ columns: \\
+ \code{\meta{short} \& \meta{long} \& \meta{extra} \& \meta{page}
+ \cs*{tabularnewline}}
+ \item The option \code{foreign-sep} is the code inserted between long form
+ and foreign entry (if a foreign entry is present).
+ \item The options \code{before} and \code{after} are inserted directly
+ before and after the complete list.
+ \item The option \code{reverse} switches the place of \meta{long} with
+ \meta{extra}.
+ \item The option \code{table-spec} sets the column types for the table
+ templates. It must correspond to the number of columns the corresponding
+ template uses.
+\end{itemize}
+
+As an example let's define a style \code{longtabu} which uses the corresponding
+table environment from the package \pkg{tabu}~\cite{pkg:tabu}:
+
+\begin{sourcecode}
+ \usepackage{tabu,longtable}
+ \DeclareAcroListStyle{longtabu}{table}{
+ table = longtabu ,
+ table-spec = @{}>{\bfseries}lX@{}
+ }
+ \acsetup{list-style=longtabu}
+\end{sourcecode}
+
+As another example let's define a new list with the help of the \pkg{enumitem}
+package~\cite{pkg:enumitem}:
+
+\begin{sourcecode}
+ % preamble:
+ % \usepackage{enumitem}
+ \newlist{acronyms}{description}{1}
+ \newcommand*\addcolon[1]{#1:}
+ \setlist[acronyms]{
+ labelwidth = 3em,
+ leftmargin = 3.5em,
+ noitemsep,
+ itemindent = 0pt,
+ font=\addcolon}
+ \DeclareAcroListStyle{mystyle}{list}{ list = acronyms }
+ \acsetup{ list-style = mystyle }
+\end{sourcecode}
+This would look as follows:
+\newlist{acronyms}{description}{1}
+\newcommand*\addcolon[1]{#1:}
+\setlist[acronyms]{
+ labelwidth=3em,
+ leftmargin=3.5em,
+ noitemsep,
+ itemindent=0pt,
+ font=\addcolon}
+\DeclareAcroListStyle{mystyle}{list}{ list = acronyms }
+\acsetup{list-style=mystyle,hyperref=false}
+\printacronyms
+
+\subsubsection{Own List Heading Command}
+
+With the option \option{list-heading} you can choose which command prints the
+heading of the list. If you need a different choice than what's already
+provided you can use the following command to define a new option:
+\begin{commands}
+ \command{DeclareAcroListHeading}[\marg{name}\marg{control sequence}]
+ Defines a new value \meta{name} for the option \option{list-heading}.
+ \meta{control sequence} must be a control sequence which takes one
+ mandatory argument.
+\end{commands}
+As an example here is how the value \code{section} is defined:
+\begin{sourcecode}
+ \DeclareAcroListHeading{section}{\section}
+\end{sourcecode}
+
+\subsection{First Styles}
+The first styles define how an acronym is typeset when it is used for the
+first time. It is set with the option \option{first-style}. Legal values for
+this option are defined with the following command:
+\begin{commands}
+ \command{DeclareAcroFirstStyle}[\marg{name}\marg{template}\marg{options}]
+ Declares a new \acro\ first style \meta{name}. \meta{name} will be the
+ value which can be chosen in the option \option{first-style}.
+ \meta{template} is the name of the template to be used by the style.
+ Available templates are listed in table~\ref{tab:first-templates}.
+ \meta{options} are the option settings for the corresponding template.
+\end{commands}
+
+Here are two examples of the already available styles and how they are
+defined:
+\begin{sourcecode}
+ \DeclareAcroFirstStyle{short}{inline}{
+ only-short = true ,
+ brackets = false
+ }
+ \DeclareAcroFirstStyle{sidenote-reversed}{note}{
+ note-command = \sidenote{#1} ,
+ reversed = true
+ }
+\end{sourcecode}
+
+\begin{table}[!h]
+ \centering
+ \caption{Available First Style Templates and Their Options}\label{tab:first-templates}
+ \begin{tabular}{*{4}{>{\ttfamily}l}}
+ \toprule
+ \normalfont\bfseries Template & \normalfont\bfseries Option &
+ \normalfont\bfseries Option Type & \normalfont\bfseries Default \\
+ \midrule
+ inline & brackets & boolean & true \\
+ & brackets-type & tokenlist & () \\
+ & only-short & boolean & false \\
+ & only-long & boolean & false \\
+ & reversed & boolean & false \\
+ & between & tokenlist \\
+ & foreign-sep & tokenlist & ,\textasciitilde \\
+ \midrule
+ note & use-note & boolean & true \\
+ & note-command & function & \cs*{footnote}\Marg{\#1} \\
+ & reversed & boolean & false \\
+ & foreign-sep & tokenlist & ,\textasciitilde \\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+\subsection{Extra Styles}
+The extra styles define how the extra information of an acronym is typeset in
+the list. It is set with the option \option{extra-style}. Legal values for
+this option are defined with the following command:
+\begin{commands}
+ \command{DeclareAcroExtraStyle}[\marg{name}\marg{template}\marg{options}]
+ Declares a new \acro\ extra style \meta{name}. \meta{name} will be the
+ value which can be chosen in the option \option{extra-style}.
+ \meta{template} is the name of the template to be used by the style.
+ Available templates are listed in table~\ref{tab:extra-templates}.
+ \meta{options} are the option settings for the corresponding template.
+\end{commands}
+
+Here are two examples of the already available styles and how they are
+defined:
+\begin{sourcecode}
+ \DeclareAcroExtraStyle{default}{inline}{
+ brackets = false ,
+ punct = true ,
+ punct-symbol = .
+ }
+ \DeclareAcroExtraStyle{paren}{inline}{
+ brackets = true ,
+ punct = true ,
+ punct-symbol =
+ }
+\end{sourcecode}
+
+\begin{table}
+ \centering
+ \caption{Available Extra Style Templates and Their Options}\label{tab:extra-templates}
+ \begin{tabular}{*{4}{>{\ttfamily}l}}
+ \toprule
+ \normalfont\bfseries Template & \normalfont\bfseries Option &
+ \normalfont\bfseries Option Type & \normalfont\bfseries Default \\
+ \midrule
+ inline & punct & boolean & true \\
+ & punct-symbol & tokenlist & , \\
+ & brackets & boolean & true \\
+ & brackets-type & tokenlist & () \\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+\subsection{Page Number Styles}
+The page number styles define how the page numbers where acronyms have been
+used are typeset in the list. It is set with the option \option{page-style}.
+Legal values for this option are defined with the following command:
+\begin{commands}
+ \command{DeclareAcroPageStyle}[\marg{name}\marg{template}\marg{options}]
+ Declares a new \acro\ extra style \meta{name}. \meta{name} will be the
+ value which can be chosen in the option \option{page-style}.
+ \meta{template} is the name of the template to be used by the style.
+ Available templates are listed in table~\ref{tab:page-templates}.
+ \meta{options} are the option settings for the corresponding template.
+\end{commands}
+
+Here are two examples of the already available styles and how they are
+defined:
+\begin{sourcecode}
+ \DeclareAcroPageStyle{default}{inline}{
+ punct = true ,
+ punct-symbol = .
+ }
+ \DeclareAcroPageStyle{paren}{inline}{
+ brackets=true ,
+ punct-symbol = ~
+ }
+\end{sourcecode}
+
+\begin{table}
+ \centering
+ \caption{Available Page Number Style Templates and Their
+ Options}\label{tab:page-templates}
+ \begin{tabular}{*{3}{>{\ttfamily}l}>{\ttfamily}p{.25\linewidth}}
+ \toprule
+ \normalfont\bfseries Template & \normalfont\bfseries Option &
+ \normalfont\bfseries Option Type & \normalfont\bfseries Default \\
+ \midrule
+ inline & display & boolean & true \\
+ & punct & boolean & false \\
+ & punct-symbol & tokenlist & , \\
+ & brackets & boolean & false \\
+ & brackets-type & tokenlist & () \\
+ & space & skip & .333333em plus .166666em minus
+ .111111em \\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+\subsection{Configuration Files}
+If\sinceversion{2.2} you repeatedly have the same setup and definitions for
+\acro\ in your preamble\footnote{For example defining new endings, \acro{}
+ commands, list styles, \ldots} you might want to place those in a
+configuration file. If \acro\ finds a file named \code{acro.cfg} present it
+inputs it at the end of the package. The only thing to be aware of is that
+this file is input like a package which means that \code{@} is treated as a
+letter (category code~11).
+
+\appendix
+
+\acsetup{
+ list-style = description ,
+ list-heading = section ,
+ list-name = All Acronyms Used in this Documentation ,
+ page-style = comma ,
+ following-pages* = true ,
+ extra-style = comma
+}
+
+\printacronyms
+
+\printbibliography
+
+\end{document}