acro (11jan20)

git-svn-id: svn://tug.org/texlive/trunk@53368 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 2140 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/acro/acro-manual.tex b/Master/texmf-dist/doc/latex/acro/acro-manual.tex
new file mode 100644
index 00000000000..43462b6bacc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/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}