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.tex3927
1 files changed, 2090 insertions, 1837 deletions
diff --git a/macros/latex/contrib/acro/acro-manual.tex b/macros/latex/contrib/acro/acro-manual.tex
index 43462b6bac..6470c95ba4 100644
--- a/macros/latex/contrib/acro/acro-manual.tex
+++ b/macros/latex/contrib/acro/acro-manual.tex
@@ -1,8 +1,8 @@
-% !arara: pdflatex: { interaction: nonstopmode }
-% !arara: biber
-% arara: pdflatex: { interaction: nonstopmode }
% arara: pdflatex: { interaction: nonstopmode }
+% !arara: biber
% arara: pdflatex: { interaction: nonstopmode }
+% !arara: pdflatex: { interaction: nonstopmode }
+% !arara: pdflatex: { interaction: nonstopmode }
% --------------------------------------------------------------------------
% the ACRO package
%
@@ -10,7 +10,7 @@
%
% --------------------------------------------------------------------------
% Clemens Niederberger
-% Web: https://bitbucket.org/cgnieder/acro/
+% Web: https://github.com/cgnieder/acro/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2011--2020 Clemens Niederberger
@@ -23,7 +23,7 @@
% 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'.
+% This work has nce status `maintained'.
%
% The Current Maintainer of this work is Clemens Niederberger.
% --------------------------------------------------------------------------
@@ -35,2105 +35,2358 @@
% If you have any ideas, questions, suggestions or bugs to report, please
% feel free to contact me.
% --------------------------------------------------------------------------
+\PassOptionsToPackage{ngerman,latin,english}{babel}
+\PassOptionsToPackage{version=3,upgrade}{acro}
\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},
+ urldate = {2020-04-11},
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}
+ year = {2020}
}
\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
- }
+\addbibresource{\jobname.bib}
+\addbibresource{cnltx.bib}
+
+% declare example acronyms
+\DeclareAcronym{cd}{
+ short = CD ,
+ long = compact disc
+}
+\DeclareAcronym{ctan}{
+ short = ctan ,
+ long = Comprehensive \TeX\ Archive Network ,
+ short-format = \scshape ,
+ pdfstring = CTAN ,
+ short-acc = CTAN ,
+ first-style = short-long ,
+ single-style = short
+}
+\DeclareAcronym{ecu}{
+ short = ECU ,
+ long = Steuergerät ,
+ foreign = Electronic Control Unit ,
+ foreign-babel = english ,
+ foreign-locale = englisch
+}
+\DeclareAcronym{eg}{
+ short = e.g\acdot ,
+ long = for example ,
+ foreign = exempli gratia ,
+ foreign-babel = latin ,
+ short-format = \textit ,
+ foreign-format = \textit
+}
+\DeclareAcronym{etc}{
+ short = etc\acdot ,
+ long = et cetera ,
+ format = \textit ,
+ first-style = long ,
+ plural =
+}
+\DeclareAcronym{hadopi}{
+ short = HADOPI ,
+ long = Haute Autorit\'{e} pour la diffusion des \oe uvres et la protection des
+ droits sur l’Internet ,
+ short-definite = l'\nospace ,
+ long-definite = la ,
+}
+\DeclareAcronym{id}{
+ short = id ,
+ long = identification string ,
+ short-format = \scshape ,
+ short-acc = ID ,
+ pdfstring = ID ,
+ first-style = short
+}
+\DeclareAcronym{jpg}{
+ short = JPEG ,
+ sort = jpeg ,
+ alt = JPG ,
+ long = Joint Photographic Experts Group
+}
+\DeclareAcronym{la}{
+ short = LA ,
+ long = Los Angeles,
+ plural = ,
+ tag = city
+}
+\DeclareAcronym{lppl}{
+ short = lppl ,
+ long = \unexpanded{\LaTeX} Project Public License ,
+ short-format = \scshape ,
+ pdfstring = LPPL ,
+ short-acc = LPPL
+}
+\DeclareAcronym{MP}{
+ short = MP ,
+ long = Member of Parliament ,
+ plural-form = Members of Parliament ,
+ long-possessive-form = Member's of Parliament
+}
+\DeclareAcronym{nato}{
+ short = nato ,
+ long = Organisation des Nordatlantikvertrags ,
+ foreign = North Atlantic Treaty Organization ,
+ foreign-babel = english ,
+ foreign-locale = englisch ,
+ short-format = \scshape
+}
+\DeclareAcronym{ny}{
+ short = NY ,
+ long = New York ,
+ plural = ,
+ tag = city ,
+ cite = NewYork
+}
+\DeclareAcronym{pdf}{
+ short = pdf ,
+ long = Portable Document Format ,
+ short-format = \scshape ,
+ pdfstring = PDF ,
+ short-acc = PDF
+}
+\DeclareAcronym{png}{
+ short = PNG ,
+ long = Portable Network Graphics ,
+ first-style = short-long ,
+ single-style = short
+}
+\DeclareAcronym{PU}{
+ short = PU ,
+ long = Polyurethan ,
+ long-plural = e
+}
+\DeclareAcronym{sw}{
+ short = SW ,
+ long = Sammelwerk ,
+ long-plural = e ,
+ tag = exclude
+}
+\DeclareAcronym{tex.sx}{
+ short = \TeX.sx ,
+ sort = TeX.sx ,
+ long = \TeX{} StackExchange
+}
\DeclareAcronym{ufo}{
- short = UFO ,
- long = unidentified flying object ,
- long-indefinite = an
+ short = UFO ,
+ long = unidentified flying object ,
+ foreign = unbekanntes Flugobjekt ,
+ foreign-plural-form = unbekannte Flugobjekte ,
+ foreign-acc-plural-form = unbekannte Flugobjekte ,
+ foreign-babel = ngerman ,
+ long-indefinite = an
+}
+
+% declare glossary terms:
+\DeclareAcronym{property}{
+ long = A \property*{property} is an option to the second argument of the
+ \cs*{DeclareAcroym} command. They are options of an individual acronym if
+ you will. ,
+ tag = glossary , no-index
+}
+\DeclareAcronym{option}{
+ long = An \option*{option} is a package option of \acro\ which must set
+ with \cs*{acsetup}. It \emph{cannot} be set as option to \cs*{usepackage}. ,
+ tag = glossary , no-index
+}
+\DeclareAcronym{load-time option}{
+ long = A load-time \option*{option} is a package option of \acro\ which must
+ be set as option to \cs*{usepackage}\oarg{options}\Marg{acro}. ,
+ tag = glossary , no-index
+}
+\DeclareAcronym{template}{
+ long = A template determines how different objects of \acro\ are printed.
+ This includes the acronyms themselves but also for example the list of
+ acronyms as a whole. ,
+ tag = glossary , no-index
+}
+\DeclareAcronym{articles}{
+ long = {Articles are prefixes to acronyms, usually separated with a blank.
+ \emph{Different types of articles are mutually exclusive.}} ,
+ tag = glossary , no-index
+}
+\DeclareAcronym{endings}{
+ long = {Endings are postfixes to acronyms, usually not separated from the
+ acronym. \emph{Different types of endings are mutually exclusive.}} ,
+ tag = glossary , no-index
+}
+\DeclareAcronym{translations}{
+ long = Localisation strings which can be modified. ,
+ tag = glossary , no-index
}
-% because the mannual does not activate the `macros' option:
-\newcommand*\nato{\ac{nato}}
-\newcommand*\ny{\ac{ny}}
+\newcommand*\issues{\url{https://github.com/cgnieder/acro/issues}}
\newcommand*\latin[1]{\textit{#1}}
\begin{document}
-\section{Licence and Requirements}
+
+\clearpage
+\part{Get started with \acro}\label{part:get-started-with}
+
+\section{Licence and requirements}\label{sec:licence-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{Glossary}
+\printacronyms[include=glossary,template=glossary]
+
+\section{\acro\ for the impatient}\label{sec:acro-impatient}
+
+Acronyms are defined in the preamble via the command
+\begin{commands}
+ \command{DeclareAcronym}[\marg{id}\marg{properties}]
+ where \meta{id} is a unique string to identify the acronym and
+ \meta{properties} is a key\slash value list of acronym properties. These
+ include:
+\end{commands}
+\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.
+ %% long
+ \propval{long}{text}\Default!
+ The long form of the acronym. \emph{This property is required}: an
+ acronym must have a description.
+\end{properties}
+\begin{bewareofthedog}
+ In its simplest form an acronym needs a short and a long form. Please note
+ that both properties \emph{must} be set.
+\end{bewareofthedog}
+
+In the document acronyms are used with these commands:
+\begin{commands}
+ \command{ac}[\marg{id}\quad\cs{Ac}\marg{id}]
+ \cs{ac} prints the acronym \meta{id}, the first time with full description
+ and every subsequent use only the abbreviated form. \cs{Ac} does the same
+ but uppercases the first letter -- this may be needed at the beginning of
+ a sentence.
+ \command{acs}[\marg{id}\quad\cs{Acs}\marg{id}]
+ \cs{acs} prints the short form of the acronym \meta{id}. \cs{Acs} does the
+ same but uppercases the first letter.
+ \command{acl}[\marg{id}\quad\cs{Acl}\marg{id}]
+ \cs{acl} prints the long form of the acronym \meta{id}. \cs{Acl} does the
+ same but uppercases the first letter.
+ \command{acf}[\marg{id}\quad\cs{Acf}\marg{id}]
+ \cs{acf} prints the full form of the acronym \meta{id}. \cs{Acf} does the
+ same but uppercases the first letter.
+\end{commands}
+
+Let's say you defined \acs*{cd} as follows:
+\begin{sourcecode}
+ \DeclareAcronym{cd}{
+ short = CD ,
+ long = compact disc
+ }
+\end{sourcecode}
+Then the usage is
+\begin{example}[side-by-side]
+ \begin{tabular}{ll}
+ first & \ac{cd} \\
+ second & \ac{cd} \\
+ long & \acl{cd} \\
+ short & \acs{cd} \\
+ full & \acf{cd}
+ \end{tabular}
+\end{example}
+
+\section{Setting options}\label{sec:setting-options}
+\subsection{Load-time options}\label{sec:load-time-options}
+\acro\ knows only a small set of load-time options which can be used as
+argument to \cs*{usepackage}:
+\begin{options}
+ \keychoice{version}{2,3}\Default{3}
+ The option allows you to use the last version prior to the update to
+ version~3. This may help if you don't have the time to fix issues after
+ upgrading to the new version.
+ \keybool{upgrade}\Default{true}
+ When this option is used \acro\ tries to give as much helpful and
+ meaningful warning or error messages when a deprecated or removed command,
+ property, or option is used. This is especially useful if you are
+ upgrading from version~2. The option will initially be true for a few
+ months after the upgrade to version~3.
+\end{options}
+
+\subsection{Setup command}\label{sec:setup-command}
+All options of \acro\ that have \emph{not} been mentioned in
+section~\ref{sec:load-time-options} have to be set up either with this command
+\begin{commands}
+ \command{acsetup}[\marg{options}]
+ or as option to other commands. If the latter is possible then it is
+ described when the corresponding commands are explained. Options usually
+ follow a key\slash value syntax and are always described in the following
+ way:
+\end{commands}
+\begin{options}
+ \opt*{option}
+ An option without a value. Those options are very rare if there are any.
+ \keyval*{option}{value}\Default{preset}
+ An option where a value can be given. The pre-set value is given to the
+ right.
+ \keychoice*{option}{\default{choiceA},choiceB,choiceC}\Default{choiceB}
+ An option with a determined set of choices. The underlined value is
+ chosen if the option is given without value.
+ \keybool*{option}
+ A boolean option with only the choices \code{true} and \code{false}.
+ \opt*{option}\Module{module}
+ An option at a deeper level belonging to the module \module*{module}.
+\end{options}
+All of the above is probably clear from an example (using real options):
+\begin{sourcecode}
+ \acsetup{
+ make-links = true , % boolean
+ index , % boolean
+ format = \emph , % standard
+ list / local , % boolean option of the list module
+ list/display = all % choice option of the list module
+ }
+\end{sourcecode}
+
+\part{Comprehensive description of creation and usage of acronyms}\label{part:compr-descr-creat}
+\section{Declaring acronyms and other abbreviations}\label{sec:decl-acronyms-other}
-\section{Basics}
-\subsection{Creating New Acronyms}
-Acronyms are created with the command \cs{DeclareAcronym}.
+All acronyms have to be declared in the preamble with the following command in
+order to be used in the document. Any usage of an acronym which has not been
+declared leads to an error message.
\begin{commands}
- \command{DeclareAcronym}[\marg{id}\marg{list of keys}]
+ \command{DeclareAcronym}[\marg{id}\marg{list of properties}]
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.
+ string identifying the acronym. Per default this is case sensitive which
+ means \code{id} is different from \code{ID}, for example.
\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.
+The command understands a number of properties which are listed in the
+following sections. This is a comprehensive overview over the existing
+properties. Many properties are also explained in more detail in later
+sections of this manual.
+\begin{options}
+ \keybool{case-sensitive}\Default{false}
+ When this is set you can write the \ac{id} of the acronym upper- or lower-
+ or mixed case and it is recognized by \acro\ as the same. This might be
+ useful when the acronym appears in the page header, for example.
+\end{options}
+
+\begin{bewareofthedog}
+ In its simplest form an acronym needs a short and a long form. Please note
+ that both properties \emph{must} be set.
+\end{bewareofthedog}
+
+\subsection{Basic properties}\label{sec:basic-properties}
\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.
+ acronym must have a short form.
+\end{properties}
+Maybe you mostly have simple acronyms where the \ac{id} and short form are
+the same. In that case you can use
+\begin{options}
+ \keybool{use-id-as-short}\Default{false}
+ to use the \ac{id} of the acronym as short form. For more complicated
+ cases this would still allow you to set the short form.
+\end{options}
+\begin{properties}
%% long
\propval{long}{text}\Default!
The long form of the acronym. \emph{This property is required}: an
acronym must have a description.
+ %% alt
+ \propval{alt}{text}\Default
+ Alternative short form.
+ %% extra
+ \propval{extra}{text}\Default
+ Extra information to be added in the list of acronyms.
+ %% foreign
+ \propval{foreign}{long form in foreign language}\Default
+ Can be useful when dealing with acronyms in foreign languages, see
+ section~\vref{sec:fore-lang-acronyms} for details.
+ %% long-post
+ \propval{long-post}{text}\Default
+ \meta{text} is appended to the long form of the acronym in the text but
+ not in the list of acronyms.
+ %% post
+ \propval{post}{text}\Default
+ \meta{text} is appended to the acronym in the text but not in the list of
+ acronyms.
+ %% single
+ \propval{single}{text}\Default={long}
+ 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
+ \option{single} has been set, see section~\vref{sec:single-appe-an}.
+ %% sort
+ \propval{sort}{text}\Default={short}
+ If used the acronym will be sorted according to this property instead of
+ its \ac{id}.
+ %% tag
+ \propval{tag}{csv list}\Default
+ The tag(s) of an acronym.
+ %% cite
+ \proplit-{cite}{\oarg{prenote}\oarg{postnote}\marg{citation keys}}\Default
+ A citation that is printed to the acronym according to an option explained
+ later.
+ %% before-citation
+ \propval{before-citation}{text}\Default
+ \meta{text} is prepended to the citation of the acronym when and where
+ the citation is printed.
+ %% index
+ \propval{index}{text}\Default
+ This property allows to overwrite the automatic index entry with an
+ arbitrary one. See section~\vref{sec:indexing} for details.
+ %% index-sort
+ \propval{index-sort}{text}\Default={sort}
+ If you use the option \option{index} every occurrence of an acronym is
+ recorded to the index and sorted by its short form or (if set) by the
+ value of the \property{sort} property. This property allows to set an
+ individual sorting option for the index. See section~\vref{sec:indexing}
+ for details.
+\end{properties}
+
+\subsection{Properties related to plural and indefinite forms}\label{sec:prop-relat-plur}
+\begin{properties}
%% 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.
+ \propval{short-plural-form}{text}\Default
+ The 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}
+ \propval{long-plural-form}{text}\Default
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.
+ The 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.
+ \propval{alt-plural-form}{text}\Default
+ The 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.
+ The 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.
+ \propval{foreign-plural-form}{text}\Default
+ Plural foreign form of the acronym; replaces the foreign form when used
+ instead of appending the plural ending.
%% 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.
+\end{properties}
+
+\subsection{Properties related to formatting}\label{sec:prop-relat-form}
+\begin{properties}
+ \propval{format}{code}\Default
+ The format used for both short and long form of the acronym.
%% short-format
- \propval{short-format}{\TeX{} code}
+ \propval{short-format}{code}\Default={format}
The format used for the short form of the acronym.
%% long-format
- \propval{long-format}{\TeX{} code}
+ \propval{long-format}{code}\Default={format}
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.
+ \propval{first-long-format}{code}\Default={long-format}
+ The format used for the first appearance of the long form of the acronym.
+ %% alt-format
+ \propval{alt-format}{code}\Default={short-format}
+ The format used for the alternative form of the acronym. If this is not
+ given the short format will be used.
+ %% extra-format
+ \propval{extra-format}{code}\Default
+ The format used for the additional information of the acronym.
+ %% foreign-format
+ \propval{foreign-format}{code}\Default
+ The format used for the foreign form of the acronym.
%% 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.
+ \propval{single-format}{code}\Default={long-format}
+ The format used for the acronym if the acronym is only used a single
+ time.
+ %% list-format
+ \propval{list-format}{code}\Default={long-format}
+ The format used for the long form of the acronym in the list if the list
+ template supports it. All pre-defined list templates \emph{do} support
+ it.
%% 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}.
+ \propchoice{first-style}{long-short,short-long,short,long,footnote}\Default
+ The style of the first appearance of the acronym, see also
+ section~\vref{sec:first-or-full}.
+ %% single-style
+ \propchoice{single-style}{long-short,short-long,short,long,footnote}\Default
+ The style of a single appearance of the acronym, see also
+ section~\vref{sec:single-appe-an}.
+\end{properties}
+
+\subsection{Properties related to the created \acs*{pdf} file}\label{sec:prop-relat-creat}
+\begin{properties}
%% 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.
+ \propval{pdfstring}{pdfstring}\Default={short}
+ Used as \acs{pdf} string replacement in bookmarks when used together with
+ the \pkg{hyperref}~\cite{pkg:hyperref} or the \pkg{bookmark}
+ package~\cite{pkg:bookmark}.
+ %% pdfcomment
+ \propval{pdfcomment}{text}
+ Sets a tooltip description for an acronym. For actually getting
+ tooltips you also need an appropriate setting of the options
+ \option{pdfcomment/cmd} and \option{pdfcomment/use}, see also
+ section~\vref{sec:pdf-comments}.
+ %% short-acc
+ \propval{short-acc}{text}\Default={short}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the short form of the acronym.
+ %% long-acc
+ \propval{long-acc}{text}\Default={long}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the long form of the acronym.
+ %% alt-acc
+ \propval{alt-acc}{text}\Default={alt}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the alternative short form of the acronym.
+ %% foreign-acc
+ \propval{foreign-acc}{text}\Default={foreign}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the foreign form of the acronym.
+ %% extra-acc
+ \propval{extra-acc}{text}\Default={extra}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the extra information of the acronym.
+ %% single-acc
+ \propval{single-acc}{text}\Default={long-acc}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for a single appearance of the acronym.
+ %% list-acc
+ \propval{list-acc}{text}\Default={list}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the appearance in the list of acronyms.
\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}
+\subsection{Futher properties}\label{sec:futher-properties}
+\begin{properties}
+ %% list
+ \propval{list}{text}\Default={long}
+ If specified this will be written in the list as description instead of
+ the long form if the corresponding list template supports it.
+ %% foreign-babel
+ \propval{foreign-babel}{language}\Default
+ 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}.
+ %% foreign-locale
+ \propval{foreign-locale}{language}\Default
+ The language name that is output when the option
+ \module{locale}\code{/}\option{display} is used. If this property is not
+ set then the appropriate value might be derived from
+ \property{foreign-babel}. See section~\vref{sec:fore-lang-acronyms} for
+ details.
+\end{properties}
+\section{Using acronyms}\label{sec:using-acronyms}
+There are a number of commands to use acronyms with. Their names always follow
+the same pattern which should make their usage intuitive immediately.
+
+All of these commands have a starred form which means \enquote{don't count
+ this as usage}. All of these commands also have an optional argument that
+allows to set options for that usage only.
+\begin{commands}
+ \command*{acrocommand}[\sarg\oarg{options}\marg{id}]
+ This is the general syntax of all of the commands listed below. The star
+ and the optional argument is left way for the sake of readability.
+ \emph{A command \cs*{acrocommand} does not actually exist.}
+ \command{ac}[\marg{id}\quad\cs{Ac}\marg{id}\quad\cs{acp}\marg{id}\quad
+ \cs{Acp}\marg{id}\quad\cs{iac}\marg{id}\quad\cs{Iac}\marg{id}]
+ \cs{ac} prints the acronym \meta{id}, the first time with full description
+ and every subsequent use only the abbreviated form. \cs{Ac} does the same
+ but uppercases the first letter -- this may be needed at the beginning of
+ a sentence. The commands \cs{acp} and \cs{Acp}, resp., print the
+ corresponding plural forms. The commands \cs{iac} and \cs{Iac}, resp.,
+ print indefinite forms.
+ \command{acs}[\marg{id}\quad\cs{Acs}\marg{id}\quad\cs{acsp}\marg{id}\quad
+ \cs{Acsp}\marg{id}\quad\cs{iacs}\marg{id}\quad\cs{Iacs}\marg{id}]
+ \cs{acs} prints the short form of the acronym \meta{id}. \cs{Acs} does the
+ same but uppercases the first letter. The commands \cs{acsp} and
+ \cs{Acsp}, resp., print the corresponding plural forms. The commands
+ \cs{iacs} and \cs{Iacs}, resp., print indefinite forms.
+ \command{acl}[\marg{id}\quad\cs{Acl}\marg{id}\quad\cs{aclp}\marg{id}\quad
+ \cs{Aclp}\marg{id}\quad\cs{iacl}\marg{id}\quad\cs{Iacl}\marg{id}]
+ \cs{acl} prints the long form of the acronym \meta{id}. \cs{Acl} does the
+ same but uppercases the first letter. The commands \cs{aclp} and
+ \cs{Aclp}, resp., print the corresponding plural forms. The commands
+ \cs{iacl} and \cs{Iacl}, resp., print indefinite forms.
+ \command{aca}[\marg{id}\quad\cs{Aca}\marg{id}\quad\cs{acap}\marg{id}\quad
+ \cs{Acap}\marg{id}\quad\cs{iaca}\marg{id}\quad\cs{Iaca}\marg{id}]
+ \cs{aca} prints the alternative short form of the acronym \meta{id}.
+ \cs{Aca} does the same but uppercases the first letter. The commands
+ \cs{acap} and \cs{Acap}, resp., print the corresponding plural forms. The
+ commands \cs{iaca} and \cs{Iaca}, resp., print indefinite forms.
+ \command{acf}[\marg{id}\quad\cs{Acf}\marg{id}\quad\cs{acfp}\marg{id}\quad
+ \cs{Acfp}\marg{id}\quad\cs{iacf}\marg{id}\quad\cs{Iacf}\marg{id}]
+ \cs{acf} prints the full form of the acronym \meta{id}. \cs{Acf} does the
+ same but uppercases the first letter. The commands \cs{acfp} and
+ \cs{Acfp}, resp., print the corresponding plural forms. The commands
+ \cs{iacf} and \cs{Iacf}, resp., print indefinite forms.
+\end{commands}
+
+The usage should be clear. Let's assume you have defined an acronym
+\acs*{ufo}\label{ufo} like this:
\begin{sourcecode}
- % preamble:
- \DeclareAcronym{test}{
- short = ST ,
- long = Some Test
+ \DeclareAcronym{ufo}{
+ short = UFO ,
+ long = unidentified flying object ,
+ foreign = unbekanntes Flugobjekt ,
+ foreign-plural-form = unbekannte Flugobjekte ,
+ foreign-babel = ngerman ,
+ long-indefinite = an
}
\end{sourcecode}
-This creates the acronym ``\acs{test}'' with the \acs{id} ``test'' and the
-long form ``\acl{test}.''
+Then typical outputs look like this:
+\begin{example}
+ \ac{ufo} \\
+ \iac{ufo} \\
+ \iacl{ufo} \\
+ \Iacf{ufo} \\
+ \acfp{ufo}
+\end{example}
-The \property{short-format} key allows you to choose a specific format for the
-short form of an acronym:
+\section{Alternative short forms}\label{sec:altern-short-forms}
+Sometimes expressions have two different short forms. And example might be
+\acs*{jpg} which also often is \aca*{jpg}. This is what the property
+\property{alt} is there for.
+\begin{properties}
+ \propval{alt}{text}
+ Alternative short form.
+\end{properties}
+Let's define \acs*{jpg}:
\begin{sourcecode}
- % preamble:
- \DeclareAcronym{ot}{
- short = ot ,
- long = Other Test ,
- short-format = \scshape
+ \DeclareAcronym{jpg}{
+ short = JPEG ,
+ sort = jpeg ,
+ alt = JPG ,
+ long = Joint Photographic Experts Group
}
\end{sourcecode}
-The short form now looks like this: \acs{ot}.
+And let's see how to use it:
+\begin{example}
+ \ac{jpg} \\
+ \ac{jpg} \\
+ \aca{jpg}
+\end{example}
+As you can see the full form shows both short forms of the acronym. This could
+be changed by altering the template for the full form, see
+section~\vref{sec:templates} and section~\vref{sec:first-or-full}. The
+alternative form is also printed in the list of acronyms, see
+section~\vref{sec:acronyms}. This can also be changed by altering the
+template for the list, again see section~\ref{sec:templates}.
+
+\section{The first or full appearance}\label{sec:first-or-full}
+If an acronym is used for the first time with \cs{ac} (after any number of
+usages with the starred forms of the usage commands listed in
+section~\vref{sec:using-acronyms}) or if an acronym is used \cs{acf}, then the
+first or full appearance of the acronym is printed\footnote{This usually
+ requires at least two \LaTeX\ runs until it is stable.}.
+
+The first or full appearance of an acronym is determined by this option:
+\begin{options}
+ \keychoice{first-style}{long-short,short-long,short,long,footnote}\Default{long-short}
+ The style of the first appearance of the acronym. This options sets the
+ appearance for all acronyms. Available options in reality are the names
+ of all defined templates of the type \code{acronym}. All pre-defined
+ templates can be found in section~\vref{sec:pre-defin-templ}.
+\end{options}
+It might be desirable to set the first appearance of an acronym
+individually. This is possible by setting the corresponding property:
+\begin{properties}
+ \propchoice{first-style}{long-short,short-long,short,long,footnote}\Default
+ The style of the first appearance of the acronym.
+\end{properties}
+Let's again look at an example:
+\begin{example}[side-by-side]
+ \acf[first-style=long-short]{cd} \\
+ \acf[first-style=short-long]{cd} \\
+ \acf[first-style=footnote]{cd} \\
+ \acf[first-style=long]{cd} \\
+ \acf[first-style=short]{cd}
+\end{example}
+This also demonstrates the use of the optional argument.
-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.
+An example of an abbreviation that should have \code{long} as first appearance
+might be \enquote{\acs*{etc}}, defined like this
\begin{sourcecode}
- % preamble:
- \DeclareAcronym{ny}{
- short = NY ,
- short-plural = ,
- long = New York ,
- long-plural = ,
- cite = {NewYork}
+ \DeclareAcronym{etc}{
+ short = etc\acdot ,
+ long = et cetera ,
+ format = \textit ,
+ first-style = long ,
+ plural =
}
\end{sourcecode}
+and output like this:
+\begin{example}[side-by-side]
+ \ac{etc}, \ac{etc} \ac{etc}.
+\end{example}
+The command \cs{acdot} is explained in section~\vref{sec:trailing-tokens}.
+Basically it checks if a dot follows and outputs a dot if not.
-\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}.
+\section{Single appearances of an acronym}\label{sec:single-appe-an}
+If an acronym is used only once (not counting usages with the starred forms of
+the usage commands listed in section~\vref{sec:using-acronyms}), then the
+single appearance of the acronym is printed\footnote{This usually requires at
+ least two \LaTeX\ runs until it is stable.}.
-\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.
+The single appearance of an acronym is determined by this option:
\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.
+ \keychoice{single}{\default{true},false,\meta{number}}\Default{false}
+ This option determines wether a single appearance of an acronym counts as
+ \emph{usage}. It might be desirable in such cases that an acronym is
+ simply printed as long form and not added to the list of acronym. This is
+ what this option does. With \meta{number} the minimal number of usages
+ can be given that needs to be exceeded. \keyis{single}{1} is the same as
+ \keyis{single}{true}.
+ \keychoice{single-style}{long-short,short-long,short,long,footnote}\Default{long}
+ The style of the single appearance of an acronym. Can be used to
+ determine how a single appearance is printed if the option \option{single}
+ has been set. This option sets the appearance for all acronyms.
+ Available options in reality are the names of all defined templates of the
+ type \code{acronym}. All pre-defined templates can be found in
+ section~\vref{sec:pre-defin-templ}.
\end{options}
-This is an example of the logging info with \keyis{log}{true} or
-\keyis{log}{silent}.
+If you like you can also set the single appearance of an acronym individually:
+\begin{properties}
+ \propval{single}{text}\Default={long}
+ 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
+ \option{single} has been set.
+ \propval{single-format}{code}\Default={long-format}
+ The format used for the acronym if the acronym is only used a single
+ time.
+ \propchoice{single-style}{long-short,short-long,short,long,footnote}\Default
+ The style of the single appearance of the acronym.
+\end{properties}
+Let's again look at an example. The acronym \acs*{png} is defined as follows:
\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 = {}
- =================================================
+ \DeclareAcronym{png}{
+ short = PNG ,
+ long = Portable Network Graphics ,
+ first-style = short-long ,
+ single-style = short
+ }
\end{sourcecode}
+And it is used only once in this manual\footnote{You will find it in the list
+ of acronyms in section~\ref{sec:acronyms} nonetheless as this document does
+ \keyis{list/display}{all}.}:
+\begin{example}[side-by-side]
+ \ac{png}
+\end{example}
+Please be aware that \cs{acf} would still print the full form, of course.
-\subsection{Using the Acronyms -- the Commands}\label{sec:using-acronyms-comm}
-Acronyms are used with one of the following commands:
+\section{Printing the list}\label{sec:printing-list}
+\subsection{The main command and its options}\label{sec:main-list}
+The main idea is simple: just place
\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}.
+ \command{printacronyms}[\oarg{options}]
+ where you want the list to appear. It may require several (most times
+ two) \LaTeX\ runs for it to stabilize so look out for any warnings
+ from \acro\ requiring to re-run.
\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.
+The options controlling the list are these:
+\begin{options}
+ \keychoice{template}{description,table,longtable,lof,toc}%
+ \Module{list}\Default{description}
+ Choose the template to create the list with. See more on this in
+ sections~\vref{sec:templates} and~\vref{sec:examples}.
+ \keybool{sort}\Module{list}\Default{true}
+ Decide wether to sort the list of acronyms alphabetically or to print it
+ in order of definition.
+ \keychoice{display}{all,used}\Module{list}\Default{used}
+ Decide wether to print only the acronyms actually used in the document or
+ all acronyms which have been declared in the preamble.
+ \keyval{exclude}{csv list of tags}\Module{list}\Default
+ Set a list of tags to exclude from the list. Only acronyms not
+ belonging to one of these tags will be included.
+ \keyval{include}{csv list of tags}\Module{list}\Default
+ Set a list of tags to include in the list. Only acronyms belonging to
+ one of these tags will be included.
+ \keychoice{heading}{none,section,section*,chapter,chapter*}\Module{list}
+ Choose the heading template for the list of acronyms.
+
+ This only has an effect if the list template supports it. All pre-defined
+ templates \emph{do} support it.
+ \keyval{name}{text}\Module{list}\Default{\cs{acrotranslate}\Marg{list-name}}
+ Overwrites the text which is used in the heading.
+
+ This only has an effect if the list template supports heading templates
+ \emph{and} the heading templates support it. All pre-defined heading
+ templates \emph{do} support this.
+ \keyval{preamble}{text}\Module{list}\Default
+ Set a preamble to be placed between heading and actual list.
+
+ This only has an effect if the list template supports it. All pre-defined
+ templates \emph{do} support it.
+ \keybool{display}\Module{list,locale}\Default{false}
+ This options determines wether the language of the foreign form is printed
+ or not.
+
+ This only has an effect if the list template supports foreign forms. All
+ pre-defined templates \emph{do} support them.
+\end{options}
-\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}
+All these options can be set with \cs{acsetup} globally or locally as options
+to \cs{printacronyms}. In the latter case omit the leading
+\module{list}:
+\begin{sourcecode}
+ \acsetup{list/display=all,list/exclude=units}
+ or
+ \printacronyms[display=all,exclude=units]
+\end{sourcecode}
-\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.
+\subsection{Add page numbers to the list}\label{sec:page-numbers}
+If you want to include the page numbers where the acronyms have been used in
+the list of acronym you can use these options:
+\begin{options}
+ \keychoice{display}{first,all,none}\Module{pages}\Default{none}
+ Decide wether to include page numbers in the list of acroynms and wether
+ to add the first page or every page. When you choose \code{first} and
+ have \pkg{hyperref} loaded you will also get a backlink to that page.
+ \keybool{use}\Module{pages,seq}\Default{true}
+ Turns a two-page range into \meta{num}\,f.\ (\latin{sequens}) and a
+ three-page range into \meta{num}\,ff.\ (\latin{sequentes}) when set to
+ \code{true}.
+ \keyval{pre}{code}\Module{pages,seq}\Default{\cs*{,}}
+ \meta{code} is inserted between the page number and the sequens or
+ sequentes symbol.
+ \keyval{threshold}{num}\Module{pages,seq}\Default{3}
+ The threshold for a page range to be turned into \latin{sequentes}. A
+ page range above the threshold is still typeset as a range:
+ \meta{num1}--\meta{num2}.
+ \keyval{fill}{code}\Module{pages}\Default{\cs*{dotfill}}
+ This is the code that is placed between acronym description and actual
+ page numbers.
+ \keybool{name}\Module{pages}\Default{false}
+ If set to true the page numbers are preceded with p.\ or pp.
+\end{options}
-For these reasons \cs{DeclareAcronym} can get the following keys:
+\subsection{Filter lists using tags}\label{sec:lists-tags}
+With the property \property{tag} you can assign one or more tags to an
+acronym. These tags can be used to filter the list of acronyms.
\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.
+ %% tag
+ \propval{tag}{csv list}\Default
+ The tag(s) of an acronym.
\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{options}
+ \keyval{exclude}{csv list of tags}\Module{list}\Default
+ Set a list of tags to exclude from the list. Only acronyms not
+ belonging to one of these tags will be included.
+ \keyval{include}{csv list of tags}\Module{list}\Default
+ Set a list of tags to include in the list. Only acronyms belonging to
+ one of these tags will be included.
+\end{options}
+
+Let's look at an example. This manual declares these two acronyms with the tag
+\code{city}:
\begin{sourcecode}
- \DeclareAcronym{cd}{
- short = cd ,
- long = Compact Disc ,
- short-format = \scshape
+ \DeclareAcronym{la}{
+ short = LA ,
+ long = Los Angeles,
+ plural = ,
+ tag = city
}
\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
+ short = NY ,
+ long = New York ,
+ plural = ,
+ tag = city
}
\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}
+We can now use this to either print a list \emph{without} these acronyms by
+saying
+\begin{sourcecode}
+ \printacronyms[exclude=city]
+\end{sourcecode}
+or print a list \emph{with only} these acronyms with
+\begin{example}
+ \printacronyms[include=city,heading=none]
\end{example}
+\begin{bewareofthedog}
+ If you use both \option{exclude} and \option{include} and list a tag in both
+ \option{exclude} takes precedence over \option{include}.
+ \begin{sourcecode}
+ \printacronyms[exclude={a,b},include={b,c}]
+ \end{sourcecode}
+ would only print acronyms with tag \code{c}.
+\end{bewareofthedog}
-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.
+\subsection{Local lists}\label{sec:local-lists}
+Maybe you like a list of acronyms for each chapter in a book which only lists
+the acronyms used within this chapter. You need to do three things: set
\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.
+ \keybool{use}\Module{barriers}\Default{false}
+ this option to \code{true}, place
\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.
+\begin{commands}
+ \command{acbarrier}
+ before a new chapter starts (this is not necessary for the first chapter),
+ and use \cs{printacronyms} with the option
+\end{commands}
+\begin{options}
+ \keybool{local}\Module{list}\Default{false}
+ or set this option once in the preamble with \cs{acsetup} so it is applied
+ to every list.
+\end{options}
+Please read more on barriers in section~\vref{sec:barriers}.
+\begin{bewareofthedog}
+ Please don't use page numbers together with local lists for the time being.
+ If an acronym appears in more than one list both lists would contain the
+ \emph{same} page numbers anstead of only the ones local to barriers.
-\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.
+ For the similar reasons please also don't use \option{make-links} together
+ with local lists.
-\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}
+ This \emph{might} be resolved on day.
+\end{bewareofthedog}
-\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:
+\section{Formatting}\label{sec:formatting}
+\acro\ has a number of options and parameters which can be used to influence
+the formatting of acronyms.
+\begin{options}
+ \keyval{format}{code}\Default
+ Sets the format for both the short and the long form.
+ \keyval{short}{code}\Module{format}\Default
+ Sets the format for the short form.
+ \keyval{long}{code}\Module{format}\Default
+ Sets the format for the long form.
+ \keyval{first-long}{code}\Module{format}\Default
+ Sets the format for the first appearance of the long form.
+ \keyval{alt}{code}\Module{format}\Default
+ Sets the format for the alternative form.
+ \keyval{extra}{code}\Module{format}\Default
+ Sets the format for the extra information.
+ \keyval{foreign}{code}\Module{format}\Default
+ Sets the format for the foreign form.
+ \keyval{list}{code}\Module{format}\Default
+ Sets the format for the long form in the list form.
+\end{options}
+While this options influence the formatting of the acronyms globally you can
+also give each acronym its own formatting individually:
\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}.
+ \propval{format}{code}\Default
+ The format used for both short and long form of the acronym.
+ %% short-format
+ \propval{short-format}{code}\Default={format}
+ The format used for the short form of the acronym.
+ %% long-format
+ \propval{long-format}{code}\Default={format}
+ The format used for the long form of the acronym.
+ %% first-long-format
+ \propval{first-long-format}{code}\Default={long-format}
+ The format used for the first appearance of the long form of the acronym.
+ %% alt-format
+ \propval{alt-format}{code}\Default={short-format}
+ The format used for the alternative form of the acronym. If this is not
+ given the short format will be used.
+ %% extra-format
+ \propval{extra-format}{code}\Default
+ The format used for the additional information of the acronym.
+ %% foreign-format
+ \propval{foreign-format}{code}\Default
+ The format used for the foreign form of the acronym.
+ %% single-format
+ \propval{single-format}{code}\Default={long-format}
+ The format used for the acronym if the acronym is only used a single
+ time.
+ %% list-format
+ \propval{list-format}{code}\Default={long-format}
+ The format used for the long form of the acronym in the list if the list
+ template supports it. All pre-defined list templates \emph{do} support
+ it.
+ %% first-style
+ \propchoice{first-style}{long-short,short-long,short,long,footnote}\Default
+ The style of the first appearance of the acronym, see also
+ section~\vref{sec:first-or-full}.
+ %% single-style
+ \propchoice{single-style}{long-short,short-long,short,long,footnote}\Default
+ The style of a single appearance of the acronym, see also
+ section~\vref{sec:single-appe-an}.
\end{properties}
+Per default the individual formatting instructions are \emph{additive} to the
+global ones. This can be changed through the option
+\begin{options}
+ \keybool{replace}\Module{format}\Default{false}
+ With this option active local options will \emph{replace} the global ones.
+\end{options}
-Here is the definition of the above mentioned \ac{ecu} acronym:
+Let's see an example:
\begin{sourcecode}
- \DeclareAcronym{ecu}{
- short = ECU ,
- long = Steuerger\"at ,
- foreign = Electronic Control Unit ,
- foreign-lang = english
+ \DeclareAcronym{pdf}{
+ short = pdf ,
+ long = Portable Document Format ,
+ short-format = \scshape
}
\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}
+ \acsetup{format = \itshape}
+ \acf{pdf} \par
+ \acsetup{format/replace=true}
+ \acf{pdf}
\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:
+\section{Plural forms and other endings}\label{sec:plural-forms-other}
+\subsection{The plural ending and the plural form}\label{sec:plural-ending-form}
+Not in all languages plural forms are as easy as always appending an
+\enquote{s}. Not even English. Sometimes there's other endings
+instead\footnote{German is full of such examples.}. This is why \acro\ has
+quite a number of different properties related to plural forms or endings:
+\begin{properties}
+ %% short-plural
+ \propval{short-plural}{text}\Default{s}
+ The plural ending appended to the short form.
+ %% short-plural-form
+ \propval{short-plural-form}{text}\Default
+ The 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}\Default
+ 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 plural ending appended to the alternative form.
+ %% alt-plural-form
+ \propval{alt-plural-form}{text}\Default
+ The 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 plural ending appended to the foreign form.
+ %% foreign-plural-form
+ \propval{foreign-plural-form}{text}\Default
+ Plural foreign form of the acronym; replaces the foreign form when used
+ instead of appending the plural ending.
+\end{properties}
+There are two options which allow to change the default values for the whole
+document:
\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.
+ \keyval{short-plural-ending}{text}\Default{s}
+ Defines the plural ending for the short forms to be \meta{text}.
+ \keyval{long-plural-ending}{text}\Default{s}
+ Defines the plural ending for the long forms to be \meta{text}.
\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}
-
+Now let's see two simple examples demonstrating the two different kinds of plural
+settings:
+\begin{sourcecode}
+ \DeclareAcronym{sw}{
+ short = SW ,
+ long = Sammelwerk ,
+ long-plural = e
+ }
+ \DeclareAcronym{MP}{
+ short = MP ,
+ long = Member of Parliament ,
+ plural-form = Members of Parliament
+ }
+\end{sourcecode}
+The first one has another plural ending than the usual \enquote{s}. The second
+one has a different plural form altogether because appending an \enquote{s}
+would give a wrong form:
\begin{example}[side-by-side]
- \acsetup{first-style=footnote}
- \acflike{ny}{the big apple}
+ \acfp{sw} \par
+ \acfp{MP}
\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}
+\subsection{Other endings}\label{sec:other-endings}
+Besides plural endings there are other ones like the genitive case, for
+example. This is why \acro\ generalized the concept.
+Section~\vref{sec:endings} explains in detail how to define and use additional
+endings.
+\section{Articles}
+\subsection{Indefinite forms}\label{sec:indefinite-forms}
+Indefinite forms can be a problem if the short and the long form of acronyms
+have different indefinite articles\footnote{This may very well be a language
+ specific issue.}.
\begin{example}[side-by-side]
- \acsingle{ny}
+ \acreset{ufo}%
+ a \ac{ufo} \par
+ an \ac{ufo}
\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:
+And what good would it be to use a package like \acro\ if you have to keep
+track of of and second uses, anyway? This is why \acs{ufo} should be defined
+like we did on page~\pageref{ufo}. We then can just use the dedicated
+commands and let them decide for us:
+\begin{example}[side-by-side]
+ \acreset{ufo}%
+ \iac{ufo} \par
+ \iac{ufo}
+\end{example}
+The commands which also output the indefinite article all start with an
+\enquote{i} and have all been described in section~\vref{sec:using-acronyms}
+already: \cs{iac}, \cs{Iac}, \cs{iacs}, \cs{Iacs}, \cs{iacl}, \cs{Iacl},
+\cs{iaca}, \cs{Iaca}, \cs{iacf}, and \cs{Iacf}.
+
+\subsection{Other articles}\label{sec:other-articles}
+There might be cases -- most likely depending on your language -- when you
+would like to have other articles behaving similar to the indefinite ones.
+Section~\ref{sec:articles} explains in detail how to define and use additional
+articles.
+
+\section{Foreign language acronyms}\label{sec:fore-lang-acronyms}
+Sometimes and in some fields more often than in others abbreviations are used
+that are derived from another language. \acro\ provides a number of
+properties for such cases:
\begin{properties}
- \propval{class}{csv list}
- Associated\changedversion{2.4} class(es) for an acronym.
+ %% foreign
+ \propval{foreign}{long form in foreign language}\Default
+ Can be useful when dealing with acronyms in foreign languages, see
+ section~\vref{sec:fore-lang-acronyms} for details.
+ %% foreign-plural
+ \propval{foreign-plural}{text}\Default{s}
+ The plural ending appended to the foreign form.
+ %% foreign-plural-form
+ \propval{foreign-plural-form}{text}\Default
+ Plural foreign form of the acronym; replaces the foreign form when used
+ instead of appending the plural ending.
+ %% foreign-format
+ \propval{foreign-format}{code}\Default
+ The format used for the foreign form of the acronym.
+ %% foreign-babel
+ \propval{foreign-babel}{language}\Default
+ The \pkg{babel} or \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}.
+ %% foreign-locale
+ \propval{foreign-locale}{language}\Default
+ The language name that is output when the option
+ \module{locale}\code{/}\option{display} is used. If this property is not
+ set then the appropriate value might be derived from
+ \property{foreign-babel}.
\end{properties}
+There are also some options:
+\begin{options}
+ \keybool{display}\Module{locale}\Default{false}
+ This options determines wether the language of the foreign form is printed
+ or not when the full form of the acronym is printed.
+ \keybool{display}\Module{list,locale}\Default{false}
+ The same but for the list of acronyms.
+ \keyval{format}{code}\Module{locale}\Default{\cs*{em}\cs*{text\_titlecase\_first:n}}
+ Determines how said language is formatted when printed. The last command
+ in \meta{code} may take a mandatory argument.
+\end{options}
-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})
+Let's say you are writing a German document and are using the abbreviation
+\acs*{ecu} for \acl*{ecu} which stems from the English \enquote{Electronic
+ Control Unit}. Then you can define it as follows:
+\begin{sourcecode}
+ \DeclareAcronym{ecu}{
+ short = ECU ,
+ long = Steuergerät ,
+ foreign = Electronic Control Unit ,
+ foreign-babel = english ,
+ foreign-locale = englisch
+ }
+\end{sourcecode}
+Now the abbreviation is introduced so that everyone understands the confusion:
+\begin{example}
+ \ac{ecu} \par
+ \acsetup{locale/display,locale/format=\emph}
+ \acf{ecu}
\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}
+The property \property{foreign-babel} is used for ensuring correct hyphenation
+as long as you use \pkg{babel} or \pkg{polyglossia} and load the corresponding
+language, too. If you are writing your document in English then \acro\ is
+able to deduce the language used for the \enquote{locale} field by itself:
+\begin{sourcecode}
+ \DeclareAcronym{eg}{
+ short = e.g\acdot ,
+ long = for example ,
+ foreign = exempli gratia ,
+ foreign-babel = latin ,
+ short-format = \textit ,
+ foreign-format = \textit
+ }
+\end{sourcecode}
+\begin{example}
+ \acsetup{locale/display,first-style=short-long}
+ \acf{eg}
\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.
+\section{Uppercasing}\label{sec:uppercasing}
-\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}
+Depending on the kind of abbreviations you have and depending on their
+definition and maybe also depending on your language the long and sometimes
+also the short forms need to start with an uppercase letter at the beginning
+of a sentence while it starts with a lowercase letter otherwise.
-For example the \acs{pdf} acronym used in the title for this section is defined
-as follows:
+For this \acro\ provides uppercase versions for all predefined acronym
+commands listed in section~\ref{sec:using-acronyms}. The usage is
+self-explaining:
+\begin{example}
+ There was \iacl{ufo} hovering \dots \par
+ \Aclp{ufo} were hovering \dots
+\end{example}
+If you defined them with uppercase letters to begin with then these commands
+have no effect, of course.
\begin{sourcecode}
- \DeclareAcronym{pdf}{
- short = pdf ,
- long = Portable Document Format ,
- format = \scshape ,
- pdfstring = PDF ,
- accsupp = PDF
+ \DeclareAcronym{ufo}{
+ short = UFO ,
+ long = Unidentified Flying Object
}
\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}
+There are a number of options to control the uppercasing behavior:
\begin{options}
- \keybool{accsupp}\Default{false}
- Activate \acro's accessibility support.
+ \opt{first}\Module{uppercase}
+ The default setting. Converts the first letter to uppercase.
+ \opt{title}\Module{uppercase}
+ This is just a synonym of \option{first}.
+ \opt{all}\Module{uppercase}
+ Converts \emph{all} letters to uppercase.
+ \opt{none}\Module{uppercase}
+ Converts \emph{all} letters to \emph{lowercase}
+ \keyval{cmd}{command}\Module{uppercase}
+ All of the above options just choose the right command using this option
+ internally. This means you can choose a different behavior altogether by
+ setting this option to something else. For example you could use
+ \cs*{capitalisewords} from the package
+ \pkg{mfirstuc}~\cite{pkg:mfirstuc}. The command needs to have one
+ mandatory argument.
\end{options}
-\subsubsection{Tooltips}
+There may be reasons to exclude short forms from being uppercased. This can
+be controlled by this option:
+\begin{options}
+ \keybool{short}\Module{uppercase}\Default{true}
+ It allows you to disable the mechanism for the \property{short} and
+ \property{alt} properties.
+\end{options}
-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.
+\section{Citing and indexing}\label{sec:citing-indexing}
+\subsection{Citing}\label{sec:citing}
+Acronyms can be given cite keys. This makes it possible to add a citation
+reference automatically when the acronym is used for the first time.
+Let's see an example first. \acs*{ny} has been defined like this:
+\begin{sourcecode}
+ \DeclareAcronym{ny}{
+ short = NY ,
+ long = New York ,
+ plural = ,
+ tag = city ,
+ cite = NewYork
+ }
+\end{sourcecode}
+The property \property{cite} will now trigger \acro\ to input
+\verbcode+\cite{NewYork}+ after the acronym:
+\begin{example}[side-by-side]
+ \ac{ny}
+\end{example}
+Depending on the citation style (and probably other factors, too) it might be
+desirable to add the citation rather inside the parentheses together with the
+short form of the acronym and even cited with a different command. For cases
+like these \acro\ offers a number of options:\acuse{ny}
\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.
+ \keyval{cmd}{citation command}\Module{cite}\Default{\cs*{cite}}
+ Choose the command with which citations ar printed.
+ \keybool{group}\Module{cite}\Default{false}
+ Decide wether to group citations with the short form in the parentheses.
+ The template must support this. \acro's pre-defined templates \emph{do}
+ support it.
+ \keychoice{display}{first,all,none}\Module{cite}\Default{first}
+ Decide wether to output the citation in the first/full usage only or
+ always or never.
+ \keyval{pre}{text}\Module{cite}\Default{\cs*{nobreakspace}}
+ Arbitrary code directly output before the citation.
+ \keyval{cmd}{citation command}\Module{cite,group}\Default{\cs*{cite}}
+ Choose the command with which grouped citations are printed.
+ \keyval{pre}{text}\Module{cite,group}\Default{,\textvisiblespace}
+ Arbitrary code directly output before the citation in the grouped case.
\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:
+If for example you use \pkg{biblatex}'s \code{authoryear}
+style~\cite{pkg:biblatex} you might want to have settings like these:
+\begin{sourcecode}
+ \acsetup{
+ cite/group = true ,
+ cite/cmd = \parencite ,
+ cite/group/cmd = \cite
+ }
+\end{sourcecode}
+\begin{cnltxcode}
+\begin{lstlisting}[style=cnltx]
+ \acsetup{cite/display = all}
+ \acf{ny} \\
+ \ac{ny}
+\end{lstlisting}
+\tcblower
+ New York (NY, Wikipedia 2020) \\
+ NY (Wikipedia 2020)
+\end{cnltxcode}
+
+\subsection{Indexing}\label{sec:indexing}
+Maybe you want to add your acronyms to an index. In that case it is probably
+desirable to let \acro\ make this automatically. In the simplest case just
+enable it:
\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}.
+ \keybool{use}\Module{index}\Default{false}
+ Enable indexing.
+ \keyval{cmd}{index command}\Module{index}\Default{\cs*{index}}
+ Choose a command for indexing.
+ \keyval{disable}{code}\Module{index}\Default{\cs*{def}\cs*{@}\{\}}
+ Sometimes it is desirable to change the meaning of a command inside an
+ index entry. For the entries created by \acro\ this can be achieved with
+ this option.
+ \opt{clear}\Module{index}
+ This option clears the disable list.
+\end{options}
+While these options set global behavior there are also properties to set them
+for an acronym individually.
+\begin{properties}
+ %% index
+ \propval{index}{text}\Default
+ This property allows to overwrite the automatic index entry with an
+ arbitrary one.
+ %% index-sort
+ \propval{index-sort}{text}\Default={sort}
+ If you use the option \option{index} every occurrence of an acronym is
+ recorded to the index and sorted by its short form or (if set) by the
+ value of the \property{sort} property. This property allows to set an
+ individual sorting option for the index.
+ %% no-index
+ \propbool{no-index}\Default{true}
+ This property allows to exclude an acronym from being indexed.
+\end{properties}
+This manual is an example for the indexing feature. Each acronym from
+section~\vref{sec:acronyms} that has been used in this manual is also listed
+in the manual.
+
+\section{Barriers}\label{sec:barriers}
+The main purpose of the concept of barriers is to be able to have \emph{local}
+lists of acronyms. This concept does a little bit more than that, though,
+which should become clear from the following options:
+\begin{options}
+ \keybool{use}\Module{barriers}\Default{false}
+ Activate usage of barriers. Otherwise the command \cs{acbarrier} just
+ does nothing except writing a warning in the log.
+ \keybool{reset}\Module{barriers}\Default{false}
+ When set to \code{true} the acronym usage is reset for all acronyms at a
+ barrier. The first use of \cs{ac} after a barrier will again look like
+ the \cs{acf}.
+ \keybool{single}\Module{barriers}\Default{false}
+ When set to \code{true} a single usage of an acronym between two barriers
+ with \cs{ac} will look according to the chosen style as explained in
+ section~\vref{sec:single-appe-an}. This option only has an effect when
+ the option \option{single} is used as well.
\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:
+There are two natural barriers in a document: \beginenv*\Marg{document} and
+\endenv*\Marg{document}. You can add an arbitrary number of additional
+barriers with
\begin{commands}
- \command{acsetup}[\marg{options}]
- Set up \acro.
+ \command{acbarrier}
+ For this command to have any effect you must set
+ \module{barriers}\code{/}\option{single} to \code{true}!
\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.
+ It takes usually two or even three \LaTeX\ runs until acronym usages
+ between barriers are properly counted.
\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}
+\section{Trailing tokens}\label{sec:trailing-tokens}
+\subsection{What is it about?}
+\acro\ has the possibility to look ahead for certain tokens and switch a
+boolean variable if it finds them. Per default \acro\ knows about three
+tokens: the \enquote{\code{dot}} (\sym{.}), the \enquote{\code{dash}}
+(\sym{-}) and the \enquote{\code{babel-hyphen}} (\cs*{babelhyphen}).
-\begin{example}
- % with \acsetup{macros} activated:
- we could have used these before: \nato, \ny
+Yeu have seen an example for this already:
+\begin{sourcecode}
+ \DeclareAcronym{etc}{
+ short = etc\acdot ,
+ long = et cetera ,
+ format = \textit ,
+ first-style = long ,
+ plural =
+ }
+\end{sourcecode}
+The macro \cs{acdot} recognizes if a dot is directly following. It only prints
+a dot if it doesn't.
+\begin{example}[side-by-side]
+ \ac{etc} and \ac{etc}.
\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}
-
+Another example: let's say you're a German scientist, you have
+\begin{sourcecode}
+ \DeclareAcronym{PU}{
+ short = 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.
\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}
+ \acf{PU}-Hartschaum
\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:
+This works because the template \code{long-short}\footnote{The template that
+ is used by default for the first appearance.} uses \cs{acspace} at the
+appropriate place and the manual setup does
\begin{sourcecode}
- \AcroRegisterTrailing . {dot}
- \AcroRegisterTrailing - {dash}
- \AcroRegisterTrailing \babelhyphen {babel-hyphen}
+ \acsetup{activate-trailing-tokens = dash}
\end{sourcecode}
+\cs{acspace} looks ahead for a trailing dash and adds a space it it doesn't
+find it.
-If a token is registered it doesn't mean that \acro\ looks for it. The token
-must first be activated for this:
+\subsection{How does it work?}
+Tokens to look for can be defined and activated through the following options:
\begin{options}
- \keyval{activate-trailing-tokens}{csv list of token names}
+ \keylit-{define}{\meta{token}\marg{name}}\Module{trailing}
+ Defines token \meta{name} and tells \acro\ look for \meta{token} if
+ \meta{name} is activated.
+ \keyval{activate}{csv list of token names}\Module{trailing}
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}
+ \keyval{deactivate}{csv list of token names}\Module{trailing}
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}
+The package itself does this:
+\begin{sourcecode}
+ \acsetup{
+ trailing/define = . {dot} ,
+ trailing/define = {, {comma}} ,
+ trailing/define = - {dash}
+ trailing/define = \babelhyphen {babel-hyphen} ,
+ trailing/activate = {dot,comma}
+ }
+\end{sourcecode}
-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:
+In order to make use of this mechanism there is the following command:
\begin{commands}
- \command{aciftrailing}[\marg{csv list of token
+ \expandable\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:
+This command is used to define the two commands you already know:
\begin{commands}
- \command{acdot} Inserts a \code{.} if no \code{dot} follows.
- \command{acspace} Inserts a \cs*{space} if no \code{dash} or
+ \expandable\command{acdot} Inserts \cs{abbrdot} if no \code{dot} follows.
+ \expandable\command{acspace} Inserts a \cs*{space} if no \code{dash} or
\code{babel-hyphen} follows.
+ \expandable\command{abbrdot} Inserts \sym{.}\cs*{@}
\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*\acdot{\aciftrailing{dot}{}{\abbrdot}}
\newcommand*\acspace{\aciftrailing{dash,babel-hyphen}{}{\space}}
\end{sourcecode}
+You are of course free to redefine them according to your needs.
-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.
+\section{Using or resetting acronyms}\label{sec:using-or-resetting}
+Sometimes it is necessary to mark an acronym as used before it actually has
+been used or to mark an acronym as unused even though it \emph{has} been
+used. You have already seen one of the commands which make it possible:
+\begin{commands}
+ \command{acuse}[\marg{csv list of acronym ids}]
+ Every acronym given in the list will be marked as used.
+ \command{acuseall}
+ Every acronym is marked as used.
+ \command{acreset}[\marg{csv list of acronym ids}]
+ Every acronym given in the list will be reset.
+ \command{acresetall}
+ Every acronym will be reset.
+\end{commands}
+
+\section{Bookmarks, backlinks and accessibility support}\label{sec:pdf-properties}
+\subsection{Backlinks}\label{sec:backlinks}
+When \acro\ is used together with the package
+\pkg{hyperref}~\cite{pkg:hyperref} then you can make use of the following
+option:
+\begin{options}
+ \keybool{make-links}\Default{false}
+ If this is activated then every short or alternative appearance of an
+ acronym will be linked to its description in the list of acronyms.
+\end{options}
+\begin{bewareofthedog}
+ This will fail miserably together with local lists if an acronym appears in
+ more than one list. This \emph{might} be resolved on day.
+\end{bewareofthedog}
-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
+\subsection{Bookmarks}\label{sec:bookmarks}
+Since bookmarks (which are created by the \pkg{hyperref} or the \pkg{bookmark}
+packages~\cite{pkg:bookmark}) can only contain simple text \acro\ simplifies
+the output of the acronym commands when they appear in a bookmark. Although
+the output can be modified with a dedicated template-mechanism there is no
+user interface at the moment. Contact me at \issues\ if you need it.
+
+Acronyms have the property \property{pdfstring}:
+\begin{properties}
+ %% pdfstring
+ \propval{pdfstring}{pdfstring}\Default={short}
+ Used as \acs{pdf} string replacement for the short form in bookmarks when
+ used together with the \pkg{hyperref}~\cite{pkg:hyperref} or the
+ \pkg{bookmark} package~\cite{pkg:bookmark}.
+\end{properties}
+
+This is for acronyms like
\begin{sourcecode}
- \DeclareAcronym{PU}{
- long = Polyurethan ,
- long-plural = e
+ \DeclareAcronym{pdf}{
+ short = pdf ,
+ long = Portable Document Format ,
+ short-format = \scshape ,
+ pdfstring = PDF
}
\end{sourcecode}
-and you use it the first time like this:
+where the bookmark would write \enquote{pdf} instead of \enquote{\textsc{pdf}}
+if the property where not set.
+
+\subsection{\acs*{pdf} comments}\label{sec:pdf-comments}
+Some people like see comments in the \ac{pdf} when they're hovering with the
+mouse over the short form of an acronym. This can be achieved.
+\begin{options}
+ \keybool{use}\Module{pdfcomments}\Default{false}
+ This enables the creation of \ac{pdf} comments.
+ \keyval{cmd}{code}\Module{pdfcomments}\Default{\cs*{pdftooltip}\Marg{\#1}\Marg{\#2}}
+ Chooses the command for actually creating the comment. You must refer to
+ the printed output in the \ac{pdf} with \code{\#1} and to the comment with
+ \code{\#2}. The default command \cs*{pdftooltip} is provided by the
+ package \pkg{pdfcomment}~\cite{pkg:pdfcomment}. You must load it in order
+ to use it.
+\end{options}
+Only acronyms where the corresponding property has been set will get comments:
+\begin{properties}
+ %% pdfcomment
+ \propval{pdfcomment}{text}
+ Sets a tooltip description for an acronym.
+\end{properties}
+
+\subsection{Accessibility support}\label{sec:access-supp}
+\acro\ supports the \pkg{accsupp} package~\cite{pkg:accsupp} when you
+\emph{also load \pkg{hyperref}}. Then \acro\ uses
\begin{sourcecode}
- \ac{PU}-Hartschaum
+ \BeginAccSupp{ method = pdfstringdef , ActualText = {PDF} }
+ \textsc{pdf}%
+ \EndAccSupp{}%
\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
+for an acronym defined like this:
\begin{sourcecode}
- \acsetup{activate-trailing-tokens = {dash,babel-hyphen}}
+ \DeclareAcronym{pdf}{
+ short = pdf ,
+ long = Portable Document Format ,
+ short-format = \scshape ,
+ pdfstring = PDF ,
+ short-acc = PDF
+ }
\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}
+Without accessibility support when a string like \enquote{\textsc{pdf}} is
+copied from the \ac{pdf} and pasted you get \enquote{pdf}. If you don't care
+about that simply don't load \pkg{accsupp} and ignore this section.
+
+You have a few options to be able to manipulate what \acro\ does here but I
+recommend to stay with the default settings:
\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}.
+ \keybool{use}\Module{accsupp}\Default{true}
+ When this is true and the package \pkg{accsupp} is loaded then
+ accessibility support is used.
+ \keyval{options}{text}\Module{accsupp}\Default
+ Additional option to be passed to \cs{BeginAccSupp}. See the
+ \pkg{accsupp} manual for possible settings.
+ \keyval{method}{method}\Module{accsupp}\Default{pdfstringdef}
+ The method used by \cs{BeginAccSupp}. See the
+ \pkg{accsupp} manual for possible values.
\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.
+The \enquote{ActualText} that is used by \acro\ always defaults to the values
+of the acronym properties themselves. You can choose these values
+individually by setting the corresponding properties:
+\begin{properties}
+ %% short-acc
+ \propval{short-acc}{text}\Default={short}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the short form of the acronym.
+ %% long-acc
+ \propval{long-acc}{text}\Default={long}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the long form of the acronym.
+ %% alt-acc
+ \propval{alt-acc}{text}\Default={alt}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the alternative short form of the acronym.
+ %% foreign-acc
+ \propval{foreign-acc}{text}\Default={foreign}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the foreign form of the acronym.
+ %% extra-acc
+ \propval{extra-acc}{text}\Default={extra}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the extra information of the acronym.
+ %% single-acc
+ \propval{single-acc}{text}\Default={long-acc}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for a single appearance of the acronym.
+ %% list-acc
+ \propval{list-acc}{text}\Default={list}
+ Sets the \code{ActualText} property as presented by the \pkg{accsupp}
+ package for the appearance in the list of acronyms.
+\end{properties}
+Extra care has to be taken for plural forms as these can not be picked up
+automatically right now. You have to explicitly set them for the
+accessibility support, too:
\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.}
+ \DeclareAcronym{ufo}{
+ short = UFO ,
+ long = unidentified flying object ,
+ foreign = unbekanntes Flugobjekt ,
+ foreign-plural-form = unbekannte Flugobjekte ,
+ foreign-acc-plural-form = unbekannte Flugobjekte ,
+ foreign-babel = ngerman ,
+ long-indefinite = an
+ }
\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:
+\section{Localisation}\label{sec:localisation}
+There are places when \acro\ uses text strings which depend on the language of
+the document. In order to recognize the language from \pkg{babel} of
+\pkg{polyglossia} and print the strings in the correct language \acro\ uses
+the \pkg{translations}~\cite{pkg:translations}.
+
+If the language is detected incorrectly or you want \acro\ to use another
+language than it detects you can use the following option:
+\begin{options}
+ \keychoice{language}{auto,\meta{language}}\Default{auto}
+ The default setting \code{auto} lets \acro\ detect the language setting
+ automatically. Valid choices are all language names known to the package
+ \pkg{translations}. Mostly just type your language and it should work.
+\end{options}
+\acro\ only provides support for a handful of languages. You can easily teach
+\acro\ your language -- see section~\vref{sec:translations} -- if it isn't
+supported, yet\footnote{If you like you can always open an issue at \issues\
+ and provide your translations so I can add them to \acro.}.
\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}.
+ \expandable\command{acrotranslate}[\marg{key}]
+ This command fetches the translation of \meta{key} for the current
+ language. It is meant for usage in template definitions.
\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}.}.
+Available keywords and their English, French, and German translations are
+shown in table~\vref{tab:translations}.
+
+\begin{table}
+ \centering
+ \begin{tabular}{llll}
+ \toprule
+ \bfseries Key & \bfseries English & \bfseries French & \bfseries German \\
+ \midrule
+ \translationtable
+ \bottomrule
+ \end{tabular}
+ \caption{Available translation keywords.}
+ \label{tab:translations}
+\end{table}
-\paragraph{Acronym fetching commands}
+\part{Extending \acro}\label{part:extending-acro}
+\section{Background}\label{sec:background}
+\subsection{Templates}
+One of the core ideas of \acro\ version~3.0 is the use of \emph{templates}
+which manage how different how anything is printed, from the output of \cs{ac}
+and friends to the list of acronyms. \acro\ uses three types of templates:
+\begin{description}
+ \item[acronym] These templates can be used to define \emph{acronym
+ commands}, see section~\vref{sec:own-acronym-commands}.
+ \item[list] These templates are used by the \cs{printacronyms} command.
+ \item[heading] These templates only make sense if a \emph{list} template
+ uses \cs{acroheading}. This command makes use of them.
+\end{description}
+
+How these templates are defined, which are available from the start and how
+they are used is explained in section~\vref{sec:templates}.
+
+\subsection{Objects}
+\acro\ uses certain kinds of objects in some of its commands. It is possible
+to defines own such objects:
+\begin{description}
+ \item[articles] Per default only the \enquote{indefinite} article is
+ defined. But it is possible to define and add other articles to \acro.
+ This is explained in section~\vref{sec:other-articles}.
+ \item[endings] Per default only the ending \enquote{plural} is defined. But
+ it is possible to define and add other endings to \acro. This is
+ explained in section~\vref{sec:other-endings}.
+ \item[properties] You have already learned about properties. It is possible
+ to define and add further acronym properties to \acro. This is explained
+ in section~\vref{sec:new-properties}.
+ \item[translations] \acro\ uses localisation strings at a number of places.
+ It is possible to change these strings and add further strings. This is
+ explained in section~\vref{sec:localisation}.
+\end{description}
+
+\section{Templates}\label{sec:templates}
+\subsection{Pre-defined templates}\label{sec:pre-defin-templ}
+\subsubsection{Acronym templates}
+\begin{templates}
+ \tmpl{alt}
+ Display the alternative form of an acronym.
+ \tmpl{first}
+ This is a \emph{pseudo} template which always displays what is
+ set through the option \option{first-style} or the property
+ \property{first-style}.
+ \tmpl{footnote}
+ A template for the first appearance where the long form is printed in a
+ footnote.
+ \tmpl{long}
+ Display the long form of an acronym.
+ \tmpl{long-short}
+ A template for the first appearance where the long form is printed and the
+ short form follows in parentheses.
+ \tmpl{first}
+ This is a \emph{pseudo} template which always displays what is
+ set through the \option{single-style} or the property
+ \property{single-style}.
+ \tmpl{short}
+ Display the short form of an acronym.
+ \tmpl{short-long}
+ A template for the first appearance where the short form is printed and the
+ long form follows in parentheses.
+ \tmpl{show}
+ A template which writes all properties of an acronym into the log file.
+\end{templates}
+
+\subsubsection{List templates}
+\begin{templates}
+ \tmpl{description}
+ The default list style which places the short form in the item of a
+ \env*{description} environment and adds the all the rest as description of
+ the item.
+ \tmpl{lof}
+ A style which mimicks the list of figures. This style does not support
+ page ranges.
+ \tmpl{longtable}
+ A style that uses a \env*{longtable} environment for building the list.
+ This needs the \pkg{longtable} package~\cite{pkg:longtable} loaded.
+ \tmpl{longtabu}
+ A style that uses a \env*{longtabu} environment for building the
+ list. This needs the \pkg{longtable} package and the \pkg{tabu}
+ package~\cite{pkg:tabu} loaded.
+ \tmpl{tabular}
+ A style that uses a \env*{tabular} environment for building the list.
+ Since a \env*{tabular} cannot break across pages this is only suited for
+ short lists.
+ \tmpl{toc}
+ A style which mimicks the table of contents. This style does not support
+ page ranges.
+\end{templates}
+
+\subsubsection{Header templates}
+\begin{templates}
+ \tmpl{addchap}
+ Only defined in a \KOMAScript\ class and if \cs*{chapter} is defined. Uses
+ \cs*{addchap} for the heading.
+ \tmpl{addsec}
+ Only defined in a \KOMAScript\ class. Uses \cs*{addsec} for the heading.
+ \tmpl{chapter}
+ Only defined if \cs*{chapter} is defined. Uses \cs*{chapter} for the heading.
+ \tmpl{chapter*}
+ Uses \cs*{chapter}\sarg\ for the heading.
+ \tmpl{none}
+ Displays nothing.
+ \tmpl{section}
+ Uses \cs*{section} for the heading.
+ \tmpl{section*}
+ Uses \cs*{section}\sarg* for the heading.
+\end{templates}
+
+\subsection{Defining new templates}\label{sec:defin-new-templ}
+For the definition of templates these commends are available:
\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.
+ \command{NewAcroTemplate}[\oarg{type}\marg{name}\marg{code}]
+ This defines a template of type \meta{type} with the name \meta{name}
+ which inserts \meta{code} when used. A template of type \meta{type} with
+ name \meta{name} must not exist. The default type is \code{acronym}.
+ \command{RenewAcroTemplate}[\oarg{type}\marg{name}\marg{code}]
+ This re-defines a template of type \meta{type} woth the name \meta{name}
+ which inserts \meta{code} when used. A template of type \meta{type} with
+ name \meta{name} must exist. The default type is \code{acronym}.
\end{commands}
-\paragraph{Acronym setup commands}
+How to use these commands is best explained by examples of how the existing
+templates have been defined. The following sections will show several
+examples for their usage.
+
+\subsection{Commands to be used in template definitions}
+
+\acro\ provides and uses a large number of commands that are meant to be used
+in temmplate definitions and that often are useless or will raise errors if
+used outside. Depending on their purpose the commands can be used in
+different types of templates or only in certain types of templates.
+
+In the descriptions below a \expandablesymbol\ indicates a fully expandable
+command when used in an \cs*{edef}, \cs*{write} or in \cs*{expanded}.
+
+A \TF\ always refers to a \meta{true} and \meta{false} branch and indicates
+that \emph{three} commands exist: one exactly as described, one with only the
+\code{\textcolor{cs}{T}} and the \meta{true} branch, and one with only the
+\code{\textcolor{cs}{F}} and the \meta{false} branch. So \cs{acroif\TF} means
+there is \cs*{acroifTF}, \cs*{acroifT}, and \cs*{acroifF}, where \cs*{acroifT}
+and \cs*{acroifF} each have an argument less than \cs*{acroifTF}.
+
+\subsubsection{Commands for common uses}
\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
+ \expandable\command{acrolistname}
+ Expnads to whatever is currently set with
+ \module{list}\code{/}\option{name}.
+ \command{acrowrite}[\marg{property}]
+ Prints the property \meta{property} of the current acronym. Depending on
+ the circumstances this prints the property together with an article or an
+ ending either in uppercase or lowercase form. Default is the lowercase
+ form without ending or article. The actual outcome is determined by
+ switches which are explained in section~\vref{sec:own-acronym-commands}.
+ \command{acroformat}[\marg{type}\marg{text}]
+ This formats \meta{text} according to \meta{type} where \meta{type} has
+ either been set as property or as option from the \module{format} module.
+ Valid values are \code{short}, \code{long}, \code{alt}, \code{extra},
+ \code{foreign}, \code{list}, and \code{first-long}.
+ \command{acroshow}[\marg{property}]
+ For debugging puposes: writes the property \meta{property} of the current
+ acronym to the log file.
+ \command{acroif\TF}[\marg{property}\marg{true}\marg{false}]
+ Checks if the property \meta{property} has been set for the current
+ acronym and either leaves \meta{true} or \meta{false} in the input stream.
+ \command{acroifall\TF}[\marg{properties}\marg{true}\marg{false}]
+ Checks if all properties in the csv list \meta{properties} have been set
+ for the current acronym and either leaves \meta{true} or \meta{false} in
+ the input stream.
+ \command{acroifany\TF}[\marg{properties}\marg{true}\marg{false}]
+ Checks if any of the properties in the csv list \meta{properties} has been
+ set for the current acronym and either leaves \meta{true} or \meta{false}
+ in the input stream.
+ \command{acroiftag\TF}[\marg{tag}\marg{true}\marg{false}]
+ Checks if the current acronym has been given the tag \meta{tag} and either
+ leaves \meta{true} or \meta{false} in the input stream.
+ \command{AcroPropertiesMap}[\marg{code}]
+ Maps over all defined acronym properties. Within \meta{code} you can
+ refer to the current property with \code{\#1}.
\end{commands}
-\paragraph{Additional macros for further uses}
+\subsubsection{Commands for usage in acronym templates}
\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.
+ \expandable\command{acroifused\TF}[\marg{true}\marg{false}]
+ Checks if the current acronym has been used before and either leaves
+ \meta{true} or \meta{false} in the input stream.
+ \command{acroiffirst\TF}[\marg{true}\marg{false}]
+ Checks if the current usage of the current acronym is the first time and
+ either leaves \meta{true} or \meta{false} in the input stream.
+ \command{acroifsingle\TF}[\marg{true}\marg{false}]
+ Checks if the current acronym is used a single time and either leaves
+ \meta{true} or \meta{false} in the input stream.
+ \command{acrogroupcite}
\end{commands}
-\paragraph{Examples}
-The usage of above macros is best explained with a few examples. The
-following definition is done by \acro:
+\subsubsection{Commands for usage in list templates}
+\begin{commands}
+ \expandable\command{acroifchapter\TF}[\marg{true}\marg{false}]
+ This just check if \cs*{chapter} is defined. Used in the \template{toc}
+ template.
+ \expandable\command{acroifpages\TF}[\marg{true}\marg{false}]
+ This is \meta{true} if the option \module{pages}\code{/}\option{display}
+ is set, \emph{and} the current acronym is not single, \emph{and} has at
+ least one page number. \meta{false} otherwise.
+ \command{acropages}[\marg{first}\marg{range}]
+ If \cs{acroifpages\TF} would be \meta{false} this would do nothing.
+ Otherwise, if \module{pages}\code{/}\option{display} is \code{first} it
+ prints the first page number, preceded by \meta{first} if
+ \module{pages}\code{/}\option{name} is true. If
+ \module{pages}\code{/}\option{display} is \code{all} it prints the page
+ range, preceded by \meta{range} if \module{pages}\code{/}\option{name} is
+ true.
+ \command{acronopagerange}
+ This disables page ranges. Used in the \template{toc} and \template{lof}
+ templates.
+ \command{acropagefill}
+ If \cs{acroifpages\TF} would be \meta{false} this would do
+ nothing. Otherwise it prints whatever is set by
+ \module{pages}\code{/}\option{fill}.
+ \command{acronymsmap}[\marg{code}]
+ Maps over the acronyms in order of appearance in the list. Which acronyms
+ these are depends on settings. They might only have certain tags, be ones
+ local to barriers, \dots \par
+ Within \meta{code} \code{\#1} refers to the current \ac{id} of the
+ acronym. Also \cs{AcronymID} expands to the current \ac{id}. The latter
+ is important for all the commands that check or print properties of
+ acronyms.
+ \command{acronymsmap\TF}[\marg{code}\marg{true}\marg{false}]
+ This does the same as \cs{acronymsmap} and also leaves \meta{true} in the
+ input stream if the list is not empty and \meta{false} otherwise. This is
+ useful to trigger a rerun warning.
+ \command{AcronymTable}
+ This is an empty token list at the beginning of a list template.
+ \command{AcroAddRow}[\marg{code}]
+ Adds \meta{code} to the right of \cs{AcronymTable} and ensures that
+ \cs{AcronymID} has the correct global definition for this code. With this
+ the code for the \template{tabular} template and other table templates can
+ be built in a comfortable way.
+ \command{AcroNeedPackage}[\marg{package}]
+ Checks if the package \meta{package} is loaded and throws an error
+ otherwise.
+ \command{AcroRerun}
+ Triggers \acro\ to throw an \enquote{empty list} rerun warning.
+\end{commands}
+
+\subsection{New acronym templates}\label{sec:new-acronym-templ}
+
+Some templates are quite short and self-explaining:
\begin{sourcecode}
- \NewAcroCommand \ac { \acro_use:n {#1} }
+ \NewAcroTemplate{short}{\acrowrite{short}}
\end{sourcecode}
-An equivalent definition for \cs{ac} would be
+
+Some are a little bit more elaborate:
\begin{sourcecode}
- \NewDocumentCommand \ac {sm}
- {
- \acro_begin:
- \acro_reset_specials:
- \acro_check_and_mark_if:nn {#1} {#2}
- \acro_use:n {#2}
- \acro_end:
- }
+ \NewAcroTemplate{alt}{%
+ \acroifTF{alt}
+ {\acrowrite{alt}}
+ {\acrowrite{short}}%
+ }
\end{sourcecode}
-which should explain what the actual framework is which \cs{NewAcroCommand}
-adds.
-Other definitions by \acro\ are for example the following ones:
+And some templates need to do a lot more:
\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}
- }
+ \NewAcroTemplate{long-short}{%
+ \acroiffirstTF{%
+ \acrowrite{long}%
+ \acspace(%
+ \acroifT{foreign}{\acrowrite{foreign}, }%
+ \acrowrite{short}%
+ \acroifT{alt}{ \acrotranslate{or} \acrowrite{alt}}%
+ \acrogroupcite
+ )%
+ }%
+ {\acrowrite{short}}%
+ }
\end{sourcecode}
-\section{About Plural Forms, Possessive Forms and Similar Constructs -- the
- Concept of Endings}\label{sec:about-plural-forms}
+\subsection{New list templates}\label{sec:new-list-templates}
+This section shows the definition of three templates: \template{description},
+\template{tabular}, and \template{toc}.
-\acro\ has a concept of \emph{endings}. All of \acro's plural options are
-defined by saying
+First the \template{description} template:
\begin{sourcecode}
- \ProvideAcroEnding {plural} {s} {s}
+ \NewAcroTemplate[list]{description}{%
+ \acroheading
+ \acropreamble
+ \begin{description}
+ \acronymsmapF{%
+ \item[\acrowrite{short}\acroifT{alt}{/\acrowrite{alt}}]
+ \acrowrite{list}%
+ \acroifanyT{foreign,extra}{ (}%
+ \acroifT{foreign}{\acrowrite{foreign}\acroifT{extra}{, }}%
+ \acroifT{extra}{\acrowrite{extra}}%
+ \acroifanyT{foreign,extra}{)}%
+ \acropagefill
+ \acropages
+ {\acrotranslate{page}\nobreakspace}
+ {\acrotranslate{pages}\nobreakspace}%
+ }
+ {\item\AcroRerun}
+ \end{description}
+ }
\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}
+The following shows how to define templates using tome kind of table
+environment. Special care is necessary due to the way \LaTeX\ tables work:
+first the table body is built and only then the table itself is printed:
+\begin{sourcecode}
+ \NewAcroTemplate[list]{tabular}{%
+ \AcroNeedPackage{array}%
+ \acronymsmapF{%
+ \AcroAddRow{
+ \acrowrite{short}%
+ \acroifT{alt}{/\acrowrite{alt}}
+ &
+ \acrowrite{list}%
+ \acroifanyT{foreign,extra}{ (}%
+ \acroifT{foreign}{\acrowrite{foreign}\acroifT{extra}{, }}%
+ \acroifT{extra}{\acrowrite{extra}}%
+ \acroifanyT{foreign,extra}{)}%
+ \acropagefill
+ \acropages
+ {\acrotranslate{page}\nobreakspace}
+ {\acrotranslate{pages}\nobreakspace}%
+ \tabularnewline
+ }%
}
- \ExplSyntaxOff
- The \acg{cd} booklet says\ldots
-\end{example}
+ {\AcroRerun}%
+ \acroheading
+ \acropreamble
+ \par\noindent
+ \begin{tabular}{>{\bfseries}lp{.7\linewidth}}
+ \AcronymTable
+ \end{tabular}
+ }
+\end{sourcecode}
-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}
+ \NewAcroTemplate[list]{toc}{%
+ \acroheading
+ \acropreamble
+ \acronopagerange
+ \acronymsmapF{%
+ \contentsline{\acroifchapterTF{chapter}{section}}
+ {\acrowrite{short}\acroifT{alt}{/\acrowrite{alt}}}
+ {}{}%
+ \contentsline{\acroifchapterF{sub}section}
+ {
+ \acrowrite{list}%
+ \acroifT{foreign}{\acrowrite{foreign}\acroifT{extra}{, }}%
+ \acroifT{extra}{\acrowrite{extra}}%
+ \acroifanyT{foreign,extra}{)}%
+ }
+ {\acropages{}{}}
+ {}%
}
+ {\AcroRerun}
+ }
\end{sourcecode}
-This would give \enquote{\ac{cd}s's} instead of \enquote{\ac{cd}s'}. To solve
-this you might want to consider
+
+\subsection{New heading templates}\label{sec:new-head-templ}
+
+\section{Endings}\label{sec:endings}
+Referring to section~\vref{sec:other-endings} this section explains how to
+define and use additional endings.
+\begin{commands}
+ \command{DeclareAcroEnding}[\marg{name}\marg{short default}\marg{long default}]
+ This command can be used to define properties and options analoguous to
+ the plural endings which have been defined this way:
+\end{commands}
\begin{sourcecode}
- \ProvideAcroEnding {possessive-singular} {'s} {'s}
- \ProvideAcroEnding {possessive-plural} {s'} {s'}
+ \DeclareAcroEnding{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
+In general \cs{DeclareAcroEnding}\marg{foo}\marg{x}\marg{y} defines these
+options
+\begin{options}
+ \keyval*{short-\meta{foo}-ending}{value}\Default*{\meta{x}}
+ \keyval*{long-\meta{foo}-ending}{value}\Default*{\meta{y}}
+\end{options}
+and these properties
+\begin{properties}
+ \propval*{short-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{short-\meta{foo}-form}{value}\Default*
+ \propval*{alt-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{alt-\meta{foo}-form}{value}\Default*
+ \propval*{long-\meta{foo}}{value}\Default*{\meta{y}}
+ \propval*{long-\meta{foo}-form}{value}\Default*
+ \propval*{foreign-\meta{foo}}{value}\Default*{\meta{y}}
+ \propval*{foreign-\meta{foo}-form}{value}\Default*
+ \propval*{single-\meta{foo}}{value}\Default*{\meta{y}}
+ \propval*{single-\meta{foo}-form}{value}\Default*
+ \propval*{extra-\meta{foo}}{value}\Default*{\meta{y}}
+ \propval*{extra-\meta{foo}-form}{value}\Default*
+\end{properties}
+In addition another command is defined which is meant to be used in
+template definitions.
\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}.
+ \command*{acro\meta{foo}}
+ This command tells the template that the ending \meta{foo} should be
+ used.
\end{commands}
+Section~\vref{sec:own-acronym-commands} has an example of how this can be used
+to define a possessive ending and commands that make use of them like this:
+\begin{example}[side-by-side]
+ \acfg{MP}
+\end{example}
-\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:
-
+\section{Articles}\label{sec:articles}
+Referring to section~\vref{sec:other-articles} this section explains how to
+define and use additional articles.
\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.
+ \command{DeclareAcroArticle}[\marg{name}\marg{default}]
+ This command can be used to define properties and options analoguous to
+ the indefnite article which have been defined this way:
\end{commands}
+\begin{sourcecode}
+ \DeclareAcroArticle{indefinite}{a}
+\end{sourcecode}
+In general \cs{DeclareAcroArticle}\marg{foo}\marg{x} defines the
+option
+\begin{options}
+ \keyval*{\meta{foo}}{value}\Default*{\meta{x}}
+\end{options}
+and these properties
+\begin{properties}
+ \propval*{short-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{alt-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{long-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{foreign-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{single-\meta{foo}}{value}\Default*{\meta{x}}
+ \propval*{extra-\meta{foo}}{value}\Default*{\meta{x}}
+\end{properties}
+In addition another command is defined which is meant to be used in
+template definitions.
+\begin{commands}
+ \command*{acro\meta{foo}}
+ This command tells the template that the article \meta{foo} should be
+ used.
+\end{commands}
+Section~\vref{sec:own-acronym-commands} has an example of how this can be used
+to define definite articles and commands that make use of them like this:
+\begin{example}
+ \dacs{hadopi} \par
+ \dacl{hadopi}
+\end{example}
-\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}:
-
+\section{Translations}\label{sec:translations}
+For adding additional keywords, or for adding translations to existing
+keywords, or for changing existing translations \acro\ uses this command:
+\begin{commands}
+ \command{DeclareAcroTranslation}[\marg{key}\marg{language=translation list}]
+ With this command new translations keywords can be added and translations
+ for existing keywords can be changed.
+ \command{AddAcroTranslations}[\marg{key}\marg{language=translation list}]
+ Basically the same but this time per language rather than per keyword.
+\end{commands}
+As an example this is how \acro\ declares translations for the \code{pages}
+keyword:
\begin{sourcecode}
- \usepackage{tabu,longtable}
- \DeclareAcroListStyle{longtabu}{table}{
- table = longtabu ,
- table-spec = @{}>{\bfseries}lX@{}
+ \DeclareAcroTranslation{pages}{
+ Fallback = pp\abbrdot ,
+ English = pp\abbrdot ,
+ French = pp\abbrdot ,
+ German = S\abbrdot ,
+ Portuguese = pp\abbrdot
}
- \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}:
-
+Translations for a language could be added this way\footnote{\acro\ already
+ has the translations for Italian.}:
\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 }
+ \AddAcroTranslations{Italian}{
+ list-name = Acronimi ,
+ page = p\abbrdot ,
+ pages = pp\abbrdot ,
+ sequens = s\abbrdot ,
+ sequentes = ss\abbrdot ,
+ also = anche ,
+ and = e ,
+ or = o
+ }
\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:
+The existing keywords had been shown in table~\vref{tab:translations}.
+
+\section{Properties}\label{sec:new-properties}
+As you know from section~\ref{sec:decl-acronyms-other} \acro\ comes with
+quiute a number of predefined properties for the control of acronyms.
+However, there are cases when additional properties would be nice to have and
+to use. \acro\ provides this command:
\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.
+ \command{DeclareAcroProperty}[\sarg\qarg\barg\uarg\marg{name}]
+ This defines the new property \meta{name}. The command has four optional
+ arguments most of which you probably never need. \par
+ The optional star \sym{*} ensures that each acronym gets a \emph{unique}
+ value for the property. \par
+ The optional question mark \sym{?} creates a \emph{boolean} property.
+ That is a property that only can get the values \code{true} or
+ \code{false} and when it is used without value (not an empty value!) then
+ \code{true} is assumed. \par
+ The optional exclamation mark \sym{!} creates a \emph{mandatory}
+ property. An error if raised if an acronym does not set it. \par
+ The optional pipe \sym{|} creates a \emph{static} property which means
+ its value is written to an auxiliary file and read in again at begin
+ document. Once set the value is the same throughout the document
+ \command{DeclareAcroPropertyAlias}[\sarg\qarg\barg\uarg\marg{name1}\marg{name2}]
+ This newly declares property \meta{name1} and makes it an alias of
+ property \meta{name2}. This means that \meta{name1} gets the same value
+ that \meta{name2} has unless it is set explicitly. Property \meta{name2}
+ must exist.
+ \command{MakeAcroPropertyAlias}[\marg{name1}\marg{name2}]
+ This makes property \meta{name1} and makes it an alias of property
+ \meta{name2}. Both properties must exist.
\end{commands}
-As an example here is how the value \code{section} is defined:
+Exmaples for defining and using new properties are shown in
+section~\ref{sec:examples}, \ac*{eg}, examples~\ref{example:texsx-505891}
+or~\ref{example:texsx-507726}.
+
+\section{Own acronym commands}\label{sec:own-acronym-commands}
+\subsection{Background}
+You can define own acronym commands or redefine the existing ones with
+commands similar to \cs*{NewDocumentCommand} from the \pkg{xparse}
+package~\cite{pkg:xparse}.
+\begin{commands}
+ \command{NewAcroCommand}[\marg{command}\marg{arg. spec.}\marg{code}]
+ This creates the new command \meta{command} with the argument
+ specification\footnote{in the sense of an \pkg{xparse}
+ command.} \code{so\meta{arg. spec.}} and replacement text \meta{code}.
+ There are significant differences to \cs*{NewDocumentCommand}: the new
+ command always has two additional arguments: an optional star and an
+ optional argument for options. You can ignore this fact in your
+ definition, though. However, the command \emph{must} at least have one
+ argument \emph{and} the first argument \emph{must} refer to the \ac{id}.
+ Everything else is up to you. \par
+ The new command has the suiting framework to recognize trailing tokens,
+ count usage, index, and add a citation if necessary.
+ \command{RenewAcroCommand}[\marg{command}\marg{arg. spec.}\marg{code}]
+ Like \cs{NewAcroCommand} but redefines an existing command.
+ \command{UseAcroTemplate}[\oarg{type}\marg{name}\oarg{argument number}\meta{arguments}]
+ The argument \meta{type} defaults to \code{acronym} and \meta{argument
+ number} defaults to \code{1}. The command must be followed by as many
+ mandatory arguments as you specify with \meta{argument number}. All
+ predefined acronym templates use the first argument as \ac{id} so they
+ must use one argument.
+\end{commands}
+Let's see an example. This is the definition of \cs{ac}:
\begin{sourcecode}
- \DeclareAcroListHeading{section}{\section}
+ \NewAcroCommand\ac{m}{\UseAcroTemplate{first}{#1}}
+\end{sourcecode}
+Equivalent definitions would be:
+\begin{sourcecode}
+ \NewAcroCommand\ac{m}{\UseAcroTemplate[acroynm]{first}{#1}}
+ \NewAcroCommand\ac{m}{\UseAcroTemplate[acroynm]{first}[1]{#1}}
+ \NewAcroCommand\ac{m}{\UseAcroTemplate{first}[1]{#1}}
+ \NewAcroCommand\ac{m}{\UseAcroTemplate{first}[2]{#1}{}}
\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:
+There are a number of switch commands which determine a certain behavior.
+They tell the following template how to interpret certain conditionals and how
+to use \cs{acrowrite}.
\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.
+ \command{acrocite}
+ Tells \acro\ to output the citation.
+ \command{acrodonotuse}
+ Tells \acro\ to not count this as usage.
+ \command{acroplural}
+ Use plural form.
+ \command{acroindefinite}
+ Use indefinite article
+ \command{acroupper}
+ Use uppercase form.
+ \command{acrofull}
+ Use first or full form.
\end{commands}
-Here are two examples of the already available styles and how they are
-defined:
+Here is an example that makes use of them:
\begin{sourcecode}
- \DeclareAcroFirstStyle{short}{inline}{
- only-short = true ,
- brackets = false
- }
- \DeclareAcroFirstStyle{sidenote-reversed}{note}{
- note-command = \sidenote{#1} ,
- reversed = true
+ \NewAcroCommand\Iacs{m}{%
+ \acroupper\acroindefinite\UseAcroTemplate{short}{#1}%
}
\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:
+\subsection{Create commands for possessive endings}
+Let's say you want to add an ending for the genitive case.
+First you define the appropriate ending:
\begin{sourcecode}
- \DeclareAcroExtraStyle{default}{inline}{
- brackets = false ,
- punct = true ,
- punct-symbol = .
+ \DeclareAcroEnding{possessive}{'s}{'s}
+\end{sourcecode}
+Then you define commands which make use of this ending:
+\begin{sourcecode}
+ \NewAcroCommand\acg{m}{\acropossessive\UseAcroTemplate{first}{#1}}
+ \NewAcroCommand\acsg{m}{\acropossessive\UseAcroTemplate{short}{#1}}
+ \NewAcroCommand\aclg{m}{\acropossessive\UseAcroTemplate{long}{#1}}
+ \NewAcroCommand\acfg{m}{%
+ \acrofull
+ \acropossessive
+ \UseAcroTemplate{first}{#1}%
}
- \DeclareAcroExtraStyle{paren}{inline}{
- brackets = true ,
- punct = true ,
- punct-symbol =
+ \NewAcroCommand\iacsg{m}{%
+ \acroindefinite
+ \acropossessive
+ \UseAcroTemplate{short}{#1}%
}
\end{sourcecode}
+You maybe also define acronyms with corresponding properties\footnote{Bear
+ with me if this is incorrect: English is not my native language.}:
+\begin{sourcecode}
+ \DeclareAcronym{MP}{
+ short = MP ,
+ long = Member of Parliament ,
+ plural-form = Members of Parliament ,
+ long-possessive-form = Member's of Parliament
+ }
+\end{sourcecode}
+Now you can use it like this:
+\begin{example}
+ This is the \acg{MP} first day at work after \dots
+\end{example}
-\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:
+\section{Own \acro\ style files}
+When you want to use your definitions regarding \acro\ repeatedly then it
+makes sense to put them in a file which you put somewhere in your local
+\LaTeX\ tree. There are three options:
+\begin{enumerate}
+ \item Put them in a simple \code{.tex} file in \cs*{input} it.
+ \item Put in in a \code{.sty} file and include it with \cs*{usepackage}
+ \emph{after} \acro.
+ \item Create a style file following this pattern decribed below.
+\end{enumerate}
+\begin{center}
+ \code{acro.style.\meta{name}.code.tex}
+\end{center}
+This file should start with
+\begin{sourcecode}
+ \AcroStyle{name}
+\end{sourcecode}
+and input the file with \cs{acsetup} using the option
+\begin{options}
+ \keyval{load-style}{name}
+ This is more or less the same as if you'd use the package variant but
+ naturally ensures that you load it after \acro\ and in the future might
+ provide other bells and whistles, too.
+\end{options}
+The 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.
+ \command{AcroStyle}[\sarg\marg{style}\oarg{details}]
+ has an optional star which switches to expl3 syntax. It also has an
+ optional argument \meta{details} with the same purpose and usage as
+ the one from \cs*{ProvidesPackage}. A typical usage would look like
\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 = .
+ \AcroStyle{abbrev}[2020/04/21 abbreviations with acro (CN)]
+ \NewDocumentCommand\newabbreviation{mmm}{%
+ \DeclareAcronym{#1}{ short = #2 , #3 , class = abbrev , no-index }%
}
- \DeclareAcroPageStyle{paren}{inline}{
- brackets=true ,
- punct-symbol = ~
+ \NewDocumentCommand\printabbreviations{O{}}{%
+ \printacronyms[#1,include=abbrev]%
}
\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).
-
+
+\clearpage
\appendix
+\part{Appendix}\label{part: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
-}
+\section{Examples}\label{sec:examples}
+
+\listexamplefiles
-\printacronyms
+\printacronyms[
+ preamble = {\label{sec:acronyms}Below all abbreviations are listed which
+ have been defined for the manual.} ,
+ exclude = {exclude,glossary}
+]
\printbibliography