From b0cb2086fcb39d89f7f5f6b8a9eea09f78272b52 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sun, 12 Jan 2020 03:00:58 +0000 Subject: CTAN sync 202001120300 --- macros/latex/contrib/acro/README | 8 +- macros/latex/contrib/acro/acro-manual.cls | 389 +++++ macros/latex/contrib/acro/acro-manual.pdf | Bin 0 -> 593251 bytes macros/latex/contrib/acro/acro-manual.tex | 2140 +++++++++++++++++++++++ macros/latex/contrib/acro/acro.definitions.tex | 574 +++++++ macros/latex/contrib/acro/acro.history | 70 +- macros/latex/contrib/acro/acro.sty | 1644 +++++++----------- macros/latex/contrib/acro/acro_en.pdf | Bin 567166 -> 0 bytes macros/latex/contrib/acro/acro_en.tex | 2185 ------------------------ macros/latex/contrib/acro/example_one.tex | 3 +- macros/latex/contrib/acro/example_two.tex | 5 +- 11 files changed, 3743 insertions(+), 3275 deletions(-) create mode 100644 macros/latex/contrib/acro/acro-manual.cls create mode 100644 macros/latex/contrib/acro/acro-manual.pdf create mode 100644 macros/latex/contrib/acro/acro-manual.tex create mode 100644 macros/latex/contrib/acro/acro.definitions.tex delete mode 100644 macros/latex/contrib/acro/acro_en.pdf delete mode 100644 macros/latex/contrib/acro/acro_en.tex (limited to 'macros/latex/contrib/acro') diff --git a/macros/latex/contrib/acro/README b/macros/latex/contrib/acro/README index 5bfe1ce016..17088db3c0 100644 --- a/macros/latex/contrib/acro/README +++ b/macros/latex/contrib/acro/README @@ -1,5 +1,5 @@ -------------------------------------------------------------------------- -the ACRO package v2.10d 2019/12/30 +the ACRO package v2.11 2020/01/11 Typeset Acronyms @@ -8,7 +8,7 @@ Clemens Niederberger Web: https://bitbucket.org/cgnieder/acro E-Mail: contact@mychemistry.eu -------------------------------------------------------------------------- -Copyright 2012--2019 Clemens Niederberger +Copyright 2012--2020 Clemens Niederberger This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 @@ -23,7 +23,9 @@ This work has the LPPL maintenance status `maintained'. The Current Maintainer of this work is Clemens Niederberger. -------------------------------------------------------------------------- The acro package consists of the files - - acro.sty, acro_en.tex, acro_en.pdf, README, acro.history +- acro.sty, acro.definitions.tex, acro.cfg +- acro-manual.tex, acro-manual.pdf, acro-manual.cls +- acro.history, README -------------------------------------------------------------------------- If you have any ideas, questions, suggestions or bugs to report, please feel free to contact me. diff --git a/macros/latex/contrib/acro/acro-manual.cls b/macros/latex/contrib/acro/acro-manual.cls new file mode 100644 index 0000000000..e65b3a635b --- /dev/null +++ b/macros/latex/contrib/acro/acro-manual.cls @@ -0,0 +1,389 @@ +% -------------------------------------------------------------------------- +% the ACRO package +% +% Typeset Acronyms +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://bitbucket.org/cgnieder/acro/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2011--2020 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +% The acro package consists of the files +% - acro.sty, acro.definitions.tex, acro.cfg +% - acro-manual.tex, acro-manual.pdf, acro-manual.cls +% - acro.history, README +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +\ProvidesClass{acro-manual}[2020/01/11] + +\LoadClass[load-preamble,add-index]{cnltx-doc} +\RequirePackage{imakeidx} +\RequirePackage[utf8]{inputenc} + +\usepackage{acro} +\acsetup{ + single = true , + accsupp = true , + index = true , + use-barriers = true , + hyperref = true , + log = true +} + +\setcnltx{ + package = {acro} , + info = {Typeset Acronyms and other Abbreviations} , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , + url = https://bitbucket.org/cgnieder/acro/ , + abstract = {% + \acro\ allows you to define and use abbreviations in a simple way. + Abbreviations can be divided into different classes of abbreviations. + Lists of abbreviations can be created (also of separate classes of + abbreviations) and printed wherever you want the lists to appear.\par + \acro\ provides an option \option{single} which ignores abbreviations that + are used only once in the whole document.\par + As an experimental feature \acro\ also offers the option \option{sort} which + automatically sorts the list created by \cs{printacronyms}.\par + \acro\ also has the feature of creating \emph{local} lists + } , + add-cmds = { + ac, Ac, aca, Aca, acap, Acap, acbarrier, acdot, acf, Acf, acflike, acg, + acfp, Acfp, acfplike, aciftrailing, acl, Acl, aclp, Aclp, acp, Acp, + acpsingle, Acpsingle, AcroRegisterTrailing, acs, Acs, acsingle, + Acsingle, acsp, Acsp, acspace, acreset, acresetall, acsetup, + DeclareAcroCommand, DeclareAcronym, DeclareAcroExtraStyle, + DeclareAcroFirstStyle, DeclareAcroListHeading, + DeclareAcroListStyle, DeclareAcroPageStyle, DeclarePseudoAcroCommand, + iac, Iac, iaca, Iaca, iacs, Iacs, iacl, Iacl, iacf, Iacf, iacflike, + Iacflike, + NewAcroCommand, NewPseudoAcroCommand, + printacronyms, + ProvideAcroCommand, ProvideAcroEnding, ProvidePseudoAcroCommand, + RenewAcroCommand, RenewPseudoAcroCommand + } , + add-silent-cmds = { + addcolon, DeclareInstance, babelhyphen, ExplSyntaxOff, ExplSyntaxOn, nato, + NewDocumentCommand, newlist, ny, setlist + } , + index-setup = { level = \section , headers={\indexname}{\indexname} } +} + +\colorlet{property}{blue} +\newidxcmd\property{\code{\textcolor{property}{#1}}}[ (property)] +\newrobustcmd*\prop{\@ifstar{\cnltx@prop@star}{\cnltx@prop@nostar}} + +\newrobustcmd*\cnltx@prop@star{% + \cnltx@ifdash + {\cnltx@prop@aux*\meta} + {\cnltx@prop@aux*\marg}% +} +\newrobustcmd*\cnltx@prop@nostar{% + \cnltx@ifdash + {\cnltx@prop@aux{}\meta} + {\cnltx@prop@aux{}\marg}% +} +\newcommand*\cnltx@prop@aux[4]{% + \code{\property#1{#3}\cnltx@isvalue#2{#4}}% +} + +\newrobustcmd*\propis{% + \@ifstar + {\cnltx@propis*} + {\cnltx@propis{}}% +} +\newrobustcmd*\cnltx@propis[1]{% + \cnltx@ifdash + {\cnltx@prop@aux{#1}\@firstofone} + {\cnltx@prop@aux{#1}\Marg}% +} +\newrobustcmd*\choiceprop{% + \@ifstar + {\cnltx@choiceprop@star} + {\cnltx@choiceprop@nostar}% +} +\def\cnltx@choiceprop@star#1#2{% + \code{\property*{#1}\cnltx@isvalue\choices{#2}}} +\def\cnltx@choiceprop@nostar#1#2{% + \code{\property{#1}\cnltx@isvalue\choices{#2}}} +\newcommand*\boolprop{% + \@ifstar + {\cnltx@boolprop@star} + {\cnltx@boolprop@nostar}% +} +\def\cnltx@boolprop@star#1{\choiceprop*{#1}{\default{true},false}} +\def\cnltx@boolprop@nostar#1{\choiceprop{#1}{\default{true},false}} + +\newenvironment{properties} + {% + \def\propert{\@cnltx@option@item\property}% + \def\propval{\@cnltx@option@item\prop}% + \def\proplit{\@cnltx@option@item\propis}% + \def\propchoice{\@cnltx@option@item\choiceprop}% + \def\propbool{\@cnltx@option@item\boolprop}% + \cnltxlist + } + {\endcnltxlist} + +\protected\def\@versionstar{\raisebox{-.25em}{*}} +\newcommand\versionstar{\texorpdfstring{\@versionstar}{*}} + +\newcommand*\TF{\textcolor{red}{\uline{\code{\textcolor{cs}{\textit{TF}}}}}} + +\RequirePackage{fontawesome} +\RequirePackage{datetime2} +\DTMsetup{useregional=numeric,datesep=/} +\newrobustcmd*\acro@add@version[2]{% + \csdef{ac@ver@#2}{% + \DTMdate{#1}% + \csgdef{ac@ver@#2used}{}% + \csdef{ac@ver@#2}{\DTMdate{#1}}% + }% +} + +\newrobustcmd*\ac@date[1]{\ifcsdef{ac@ver@#1used}{}{ (\csuse{ac@ver@#1})}} +\newrobustcmd*\ac@ifnew[1]{\ifcsstring{c_acro_version_tl}{#1}} +\newrobustcmd*\ac@NEW{\faStarO\ New} + +\renewrobustcmd*\sinceversion[1]{% + \ac@ifnew{#1}% + {\cnltx@version@note{\textcolor{red}{\ac@NEW}}}% + {\cnltx@version@note{\GetTranslation{cnltx-introduced}~#1\ac@date{#1}}}% +} +\renewrobustcmd*\changedversion[1]{% + \cnltx@version@note{\GetTranslation{cnltx-changed}~#1\ac@date{#1}}% +} + +\newnote*\sincechanged[2]{% + \GetTranslation{cnltx-introduced}~#1\ac@date{#1}, + changed with version~#2\ac@date{#2}\ac@ifnew{#2}{ \ac@NEW}{}% +} + +\RenewDocumentEnvironment{commands}{} + {% + \cnltx@set@catcode_{12}% + \let\command\cnltx@command + \cnltxlist + } + {\endcnltxlist} + +\RequirePackage{tcolorbox,xsimverb} +\tcbuselibrary{skins,breakable} +\tcbset{enhanced,enhanced jigsaw} + +\newtcolorbox{bewareofthedog}{ + colback = white , + colframe = red , + underlay={% + \path[draw=none] + (interior.south west) + rectangle node[red]{\Huge\bfseries !} + ([xshift=-4mm]interior.north west); + }% +} + +\newtcolorbox{cnltxcode}[1][]{ + boxrule = 1pt , + colback = cnltxbg , + colframe = cnltx , + arc = 5pt , + beforeafter skip = .5\baselineskip ,% + #1% +} + +\newcommand*\acroman@readoptions[1]{% + \catcode`\^^M=13 + \acroman@read@options{#1}% +} + +\begingroup +\catcode`\^^M=13 +\gdef\acroman@read@options#1#2^^M{% + \ifblank{#2}{}{\acroman@read@options@#2}% + #1% + \XSIMfilewritestart*{\jobname.tmp}% +}% +\endgroup +\def\acroman@read@options@[#1]{\pgfqkeys{/cnltx}{#1}} + +\RenewDocumentEnvironment{sourcecode}{} + {% + \begingroup + \acroman@readoptions{% + \endgroup + \setlength\cnltx@sidebysidewidth + {\dimexpr .45\columnwidth -\lst@xleftmargin -\lst@xrightmargin\relax}% + \expanded{% + \noexpand\lstset{ + style=cnltx, + \ifboolexpe{ bool {cnltx@sidebyside} and not bool {cnltx@codeonly} } + {linewidth=\cnltx@sidebysidewidth,}{}% + \expandonce\cnltx@local@listings@options + }% + }% + \XSIMgobblechars{2}% + }% + } + {% + \XSIMfilewritestop + \cnltxcode[breakable]% + \lstinputlisting[style=cnltx]{\jobname.tmp}% + \endcnltxcode + } + +\RenewDocumentEnvironment{example}{} + {% + \begingroup + \acroman@readoptions{% + \endgroup + \setlength\cnltx@sidebysidewidth + {\dimexpr .45\columnwidth -\lst@xleftmargin -\lst@xrightmargin\relax}% + \expanded{% + \noexpand\lstset{ + style=cnltx, + \ifboolexpe{ bool {cnltx@sidebyside} and not bool {cnltx@codeonly} } + {linewidth=\cnltx@sidebysidewidth,}{}% + \expandonce\cnltx@local@listings@options + }% + }% + \XSIMgobblechars{2}% + }% + } + {% + \XSIMfilewritestop + \ifbool{cnltx@sidebyside} + {% + \cnltxcode + \noindent + \minipage[c]{\cnltx@sidebysidewidth}% + \cnltx@pre@source@hook + \lstinputlisting[style=cnltx] {\jobname.tmp}% + \cnltx@after@source@hook + \endminipage\hfill + \minipage[c]{\cnltx@sidebysidewidth}% + \cnltx@pre@example@hook + \input {\jobname.tmp}% + \cnltx@after@example@hook + \endminipage + } + {% + \cnltxcode[breakable]% + \cnltx@pre@source@hook + \lstinputlisting{\jobname.tmp}% + \cnltx@after@source@hook + \tcblower + \cnltx@pre@example@hook + \input {\jobname.tmp}% + \cnltx@after@example@hook + }% + \endcnltxcode + } + +\RequirePackage[ + backend=biber, + style=cnltx, + sortlocale=en_US, + indexing=cite]{biblatex} +\RequirePackage{csquotes,varioref} +\defbibheading{bibliography}{\section{References}} + +\RequirePackage[biblatex]{embrac}[2012/06/29] +\ChangeEmph{[}[,.02em]{]}[.055em,-.08em] +\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] + +% additional packages: +\RequirePackage{longtable,array,booktabs,enumitem,amssymb} + +\newcommand*\h[1]{\textcolor{cnltx}{\textbf{#1}}} +\newcommand*\mailto[1]{\texttt{\href{mailto:#1}{#1}}} + +\ProvideAcroEnding {possessive} {'s} {'s} + +\acro@add@version{2012-06-22}{0.1} +\acro@add@version{2012-06-23}{0.1a} +\acro@add@version{2012-06-24}{0.1b} +\acro@add@version{2012-06-24}{0.1c} +\acro@add@version{2012-06-24}{0.2} +\acro@add@version{2012-06-25}{0.2a} +\acro@add@version{2012-06-25}{0.3} +\acro@add@version{2012-06-27}{0.3a} +\acro@add@version{2012-06-29}{0.3b} +\acro@add@version{2012-07-16}{0.3c} +\acro@add@version{2012-07-23}{0.3d} +\acro@add@version{2012-07-24}{0.3e} +\acro@add@version{2012-09-28}{0.4} +\acro@add@version{2012-10-07}{0.4a} +\acro@add@version{2012-11-30}{0.5} +\acro@add@version{2012-12-14}{0.6} +\acro@add@version{2013-01-02}{0.6a} +\acro@add@version{2013-01-16}{1.0} +\acro@add@version{2013-01-26}{1.1} +\acro@add@version{2013-01-29}{1.1a} +\acro@add@version{2013-02-09}{1.2} +\acro@add@version{2013-04-04}{1.2a} +\acro@add@version{2013-05-06}{1.3} +\acro@add@version{2013-05-09}{1.3a} +\acro@add@version{2013-05-30}{1.3b} +\acro@add@version{2013-06-16}{1.3c} +\acro@add@version{2013-07-08}{1.3d} +\acro@add@version{2013-08-07}{1.3e} +\acro@add@version{2013-08-27}{1.4} +\acro@add@version{2013-09-02}{1.4a} +\acro@add@version{2013-09-24}{1.4b} +\acro@add@version{2013-11-04}{1.4c} +\acro@add@version{2013-11-22}{1.4d} +\acro@add@version{2013-12-18}{1.5} +\acro@add@version{2015-02-26}{1.6} +\acro@add@version{2015-04-08}{1.6a} +\acro@add@version{2015-05-10}{1.6b} +\acro@add@version{2015-08-16}{2.0} +\acro@add@version{2015-08-25}{2.0a} +\acro@add@version{2015-08-29}{2.0b} +\acro@add@version{2015-09-05}{2.1} +\acro@add@version{2015-10-03}{2.2} +\acro@add@version{2016-01-07}{2.2a} +\acro@add@version{2016-01-21}{2.2b} +\acro@add@version{2016-02-02}{2.2c} +\acro@add@version{2016-03-14}{2.3} +\acro@add@version{2016-03-25}{2.4} +\acro@add@version{2016-04-14}{2.4a} +\acro@add@version{2016-05-03}{2.4b} +\acro@add@version{2016-05-25}{2.5} +\acro@add@version{2016-05-26}{2.5a} +\acro@add@version{2016-05-30}{2.5b} +\acro@add@version{2016-07-20}{2.6} +\acro@add@version{2016-08-13}{2.6a} +\acro@add@version{2016-08-13}{2.6b} +\acro@add@version{2016-08-16}{2.6c} +\acro@add@version{2016-08-30}{2.6d} +\acro@add@version{2016-09-04}{2.6e} +\acro@add@version{2017-01-22}{2.7} +\acro@add@version{2017-02-09}{2.7a} +\acro@add@version{2017-06-21}{2.7b} +\acro@add@version{2017-08-28}{2.7c} +\acro@add@version{2018-01-30}{2.8} +\acro@add@version{2019-02-17}{2.9} +\acro@add@version{2019-09-23}{2.10} +\acro@add@version{2019-10-02}{2.10a} +\acro@add@version{2019-10-06}{2.10b} +\acro@add@version{2019-10-12}{2.10c} +\acro@add@version{2019-12-30}{2.10d} +\acro@add@version{2020-01-11}{2.11} + +\endinput diff --git a/macros/latex/contrib/acro/acro-manual.pdf b/macros/latex/contrib/acro/acro-manual.pdf new file mode 100644 index 0000000000..8d5fded23e Binary files /dev/null and b/macros/latex/contrib/acro/acro-manual.pdf differ diff --git a/macros/latex/contrib/acro/acro-manual.tex b/macros/latex/contrib/acro/acro-manual.tex new file mode 100644 index 0000000000..43462b6bac --- /dev/null +++ b/macros/latex/contrib/acro/acro-manual.tex @@ -0,0 +1,2140 @@ +% !arara: pdflatex: { interaction: nonstopmode } +% !arara: biber +% arara: pdflatex: { interaction: nonstopmode } +% arara: pdflatex: { interaction: nonstopmode } +% arara: pdflatex: { interaction: nonstopmode } +% -------------------------------------------------------------------------- +% the ACRO package +% +% Typeset Acronyms +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://bitbucket.org/cgnieder/acro/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2011--2020 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +% The acro package consists of the files +% - acro.sty, acro.definitions.tex, acro.cfg +% - acro-manual.tex, acro-manual.pdf, acro-manual.cls +% - acro.history, README +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +\documentclass{acro-manual} + +\addbibresource{\jobname.bib} +\addbibresource{cnltx.bib} +\begin{filecontents}{\jobname.bib} +@online{wikipedia, + author = {Wikipedia}, + title = {Acronym and initialism}, + urldate = {2012-06-21}, + url = {http://en.wikipedia.org/wiki/Acronyms}, + year = {2012} +} +@online{NewYork, + author = {Wikipedia}, + title = {New York City}, + urldate = {2012-09-27}, + url = {http://en.wikipedia.org/wiki/New_York_City}, + year = {2012} +} +@manual{interface3, + author = {{The \LaTeX3 Project Team}} , + shorthand = {L3P} , + sortname = {LaTeX3 Project Team} , + title = {The \LaTeX3 Interfaces} , + date = {2015-09-06} , + url = {http://mirrors.ctan.org/macros/latex/contrib/l3kernel/interface3.pdf} +} +\end{filecontents} + +% declare acronyms +\DeclareAcronym{cd} + { + short = cd , + long = Compact Disc , + short-format = \scshape + } +\DeclareAcronym{ctan} + { + short = ctan , + long = Comprehensive \TeX\ Archive Network , + format = \scshape , + pdfstring = CTAN , + accsupp = CTAN + } +\DeclareAcronym{ecu} + { + short = ECU , + long = Steuerger\"at , + foreign = Electronic Control Unit , + foreign-lang = english + } +\DeclareAcronym{id} + { + short = id , + long = identification string , + short-format = \scshape + } +\DeclareAcronym{jpg} + { + short = JPEG , + sort = jpeg , + alt = JPG , + long = Joint Photographic Experts Group + } +\DeclareAcronym{la} + { + short = LA , + short-plural = , + long = Los Angeles, + long-plural = , + class = city + } +\DeclareAcronym{lppl} + { + short = lppl , + long = \LaTeX\ Project Public License , + format = \scshape , + pdfstring = LPPL , + accsupp = LPPL , + index-cmd = \csname @gobble\endcsname + } +\DeclareAcronym{MP} + { + short = MP , + long = Member of Parliament , + long-plural-form = Members of Parliament + } +\DeclareAcronym{nato} + { + short = nato , + long = North Atlantic Treaty Organization , + extra = \emph{deutsch}: Organisation des Nordatlantikvertrags , + short-format = \scshape + } +\DeclareAcronym{ny} + { + short = NY , + short-plural = , + long = New York , + long-plural = , + class = city , + cite = NewYork + } +\DeclareAcronym{ot} + { + short = ot , + long = Other Test , + short-format = \scshape + } +\DeclareAcronym{pdf} + { + short = pdf , + long = Portable Document Format , + format = \scshape , + pdfstring = PDF , + accsupp = PDF + } +\DeclareAcronym{sw} + { + short = SW , + long = Sammelwerk , + long-plural = e + } +\DeclareAcronym{test} + { + short = ST , + long = Some Test + } +\DeclareAcronym{tex.sx} + { + short = \TeX.sx , + sort = TeX.sx , + long = \TeX{} StackExchange + } +\DeclareAcronym{ufo}{ + short = UFO , + long = unidentified flying object , + long-indefinite = an +} + +% because the mannual does not activate the `macros' option: +\newcommand*\nato{\ac{nato}} +\newcommand*\ny{\ac{ny}} + +\newcommand*\latin[1]{\textit{#1}} + +\begin{document} +\section{Licence and Requirements} +\license + +\acro\ loads and needs the following packages: +\pkg{expl3}\footnote{\CTANurl{l3kernel}}, \pkg{xparse}, \pkg{xtemplate}, +\pkg{l3keys2e}\footnote{\CTANurl{l3packages}}, +\pkg{zref-abspage}\footnote{\CTANurl{oberdiek}} and +\needpackage{translations}~\cite{pkg:translations}. + +\section{Basics} +\subsection{Creating New Acronyms} +Acronyms are created with the command \cs{DeclareAcronym}. +\begin{commands} + \command{DeclareAcronym}[\marg{id}\marg{list of keys}] + The basic command for declaring an acronym where \meta{id} is a unique + string identifying the acronym. Per default behaviour this is case + sensitive which means \code{id} is different from \code{ID}, for example. + There is an option \option{case-sensitive}\sinceversion{2.11} to change + this. +\end{commands} +This command understands a number of keys which are listed below. Some of +them are not described immediately but at appropriate places in the +documentation. +\begin{properties} + %% short + \propval{short}{text}\Default! + The short form of the acronym. \emph{This property is required}: an + acronym must have a short form. If this is set it \emph{must} be set as + first option! If another property is set first and notices the + \property{short} property missing it assumes that the \acs{id} should be + used as short version and sets it accordingly. A warning will be written + to the log then. + %% long + \propval{long}{text}\Default! + The long form of the acronym. \emph{This property is required}: an + acronym must have a description. + %% short-plural + \propval{short-plural}{text}\Default{s} + The plural ending appended to the short form. + %% short-plural-form + \propval{short-plural-form}{text} + The\sinceversion{2.0} plural short form of the acronym; replaces the short + form when used instead of appending the plural ending. + %% long-plural + \propval{long-plural}{text}\Default{s} + The plural ending appended to the long form. + %% long-plural-form + \propval{long-plural-form}{text} + Plural long form of the acronym; replaces the long form when used + instead of appending the plural ending. + %% alt-plural + \propval{alt-plural}{text}\Default{s} + The\sinceversion{2.0} plural ending appended to the alternative form. + %% alt-plural-form + \propval{alt-plural-form}{text} + The\sinceversion{2.0} plural alternative form of the acronym; replaces the + alternative form when used instead of appending the plural ending. + %% foreign-plural + \propval{foreign-plural}{text}\Default{s} + The\sinceversion{2.9} plural ending appended to the foreign form. + %% foreign-plural-form + \propval{foreign-plural-form}{text} + Plural\sinceversion{2.9} foreign form of the acronym; replaces the + foreign form when used instead of appending the plural ending. + %% list + \propval{list}{text} + If specified this will be written in the list as description instead of + the long form. + %% short-indefinite + \propval{short-indefinite}{text}\Default{a} + Indefinite article for the short form. + %% long-indefinite + \propval{long-indefinite}{text}\Default{a} + Indefinite article for the long form. + %% long-pre + \propval{long-pre}{text} + \meta{text} is prepended to the long form in the text but not in the list + of acronyms. + %% long-post + \propval{long-post}{text} + \meta{text} is appended to the long form in the text but not in the list + of acronyms. + %% long-post + \propval{post}{text} + \meta{text}\sinceversion{2.8} is appended to the acronym in the text but + not in the list of acronyms. + %% alt + \propval{alt}{text} + Alternative short form. + %% alt-indefinite + \propval{alt-indefinite}{text}\Default{a} + Indefinite article for the alternative form. + %% extra + \propval{extra}{text} + Extra information to be added in the list of acronyms. + %% foreign + \propval{foreign}{original long form} + Can be useful when dealing with acronyms in foreign languages, see + section~\vref{ssec:foreign} for details. + %% foreign-lang + \propval{foreign-lang}{language} + \sinceversion{2.3}The \pkg{babel}~\cite{pkg:babel} or + \pkg{polyglossia}~\cite{pkg:polyglossia} language of the foreign form. + This language is used to wrap the entry with + \cs*{foreignlanguage}\marg{language} if either \pkg{babel} or + \pkg{polyglossia} is loaded. You'll need to take care that the + corresponding language is loaded by \pkg{babel} or \pkg{polyglossia}. + %% single + \propval{single}{text} + \sinceversion{2.3}If provided \meta{text} will be used instead of the long + form if the acronym is only used a single time \emph{and} the option + \keyis{single}{true} is active. + %% sort + \propval{sort}{text} + If used the acronym will be sorted according to this key instead of its + \acs{id}. + %% class + \propval{class}{csv list} + The\changedversion{2.4} class(es) the acronym belongs to. + %% cite + \proplit-{cite}{\oarg{prenote}\oarg{postnote}\marg{citation keys}} + A citation that is printed to the acronym according to an option explained + later. + %% before-citation + \propval{before-citation}{code} + \meta{code}\sinceversion{2.11} is inserted directly before \property{cite} + and \emph{ony when} \property{cite} is used. + %% after-citation + \propval{after-citation}{code} + \meta{code}\sinceversion{2.11} is inserted directly after \property{cite} + and \emph{ony when} \property{cite} is used. + %% short-format + \propval{short-format}{\TeX{} code} + The format used for the short form of the acronym. + %% long-format + \propval{long-format}{\TeX{} code} + The format used for the long form of the acronym. + %% short-format + \propval{alt-format}{\TeX{} code} + The\sinceversion{2.10} format used for the alternative form of the + acronym. If this is not given the short format will be used. + %% first-long-format + \propval{first-long-format}{\TeX{} code} + The format used for the first long form of the acronym as set with \cs{ac}, + \cs{acf} or \cs{acflike} and their uppercase, plural and indefinite forms. + %% single-format + \propval{single-format}{\TeX{} code} + \sinceversion{2.3}The format used for the acronym if the acronym is only + used a single time. + %% first-style + \propchoice{first-style}{default,empty,square,short,long,reversed,footnote,sidenote,% + footnote-reversed,sidenote-reversed} + \sinceversion{2.3}The style of the first appearance of the acronym, see + also section~\ref{sec:opti-regard-acronyms}. + %% pdfstring + \proplit-{pdfstring}{\Marg{\meta{pdfstring}/\meta{plural ending}}} + \changedversion{2.4b}Used as \acs{pdf} string replacement in bookmarks + when used together with the \pkg{hyperref} package. The appended plural + ending is optional. If you leave it (\emph{and} the \code{/}) the default + ending is used. \meta{text} is expanded before it is saved. + %% accsupp + \propval{accsupp}{text} + Sets the \code{ActualText} key as presented by the \pkg{accsupp} package + for the acronym. + %% tooltip + \propval{tooltip}{text} + \sinceversion{2.1}Sets the tooltip description for an acronym. For + actually getting tooltips you also need an appropriate setting of the + \option{tooltip-cmd} option or to set the package option + \option{tooltip}. + %% index-sort + \propval{index-sort}{text} + If you use the package option \option{index} every occurrence of an + acronym is recorded to the index and sorted by its \acs{id} or (if set) by + the value of the \property{sort} property. This key allows to set an + individual sorting option for the index. See section~\vref{ssec:index} + for details. + %% index + \propval{index}{text} + This key allows to overwrite the automatic index entry with an arbitrary + one. See section~\vref{ssec:index} for details. + %% index-cmd + \propval{index-cmd}{control sequence} + This key let's you set an individual index creating command for this + acronym. It should be a command that takes one mandatory argument. See + section~\vref{ssec:index} for details. +\end{properties} + +\begin{bewareofthedog} + In its simplest form an acronym needs a short and a long form. Please note + that both keys \emph{must} be set and that the \property{short} property + \emph{must} always be the \emph{first} property that is set. +\end{bewareofthedog} + +\begin{sourcecode} + % preamble: + \DeclareAcronym{test}{ + short = ST , + long = Some Test + } +\end{sourcecode} +This creates the acronym ``\acs{test}'' with the \acs{id} ``test'' and the +long form ``\acl{test}.'' + +The \property{short-format} key allows you to choose a specific format for the +short form of an acronym: +\begin{sourcecode} + % preamble: + \DeclareAcronym{ot}{ + short = ot , + long = Other Test , + short-format = \scshape + } +\end{sourcecode} +The short form now looks like this: \acs{ot}. + +The \property{cite} key needs a bit explaining. It expects arguments like the +standard \cs*{cite} command, \latin{i.e.}, two optional arguments setting the +\meta{prenote} and \meta{postnote} and one mandatory argument setting the +citation key. +\begin{sourcecode} + % preamble: + \DeclareAcronym{ny}{ + short = NY , + short-plural = , + long = New York , + long-plural = , + cite = {NewYork} + } +\end{sourcecode} + +\begin{sourcecode}[sourcecode-options={style=cnltx-bibtex}] + % bib file for use with biber/biblatex: + @online{NewYork, + author = {Wikipedia}, + title = {New York City}, + urldate = {2012-09-27}, + url = {http://en.wikipedia.org/wiki/New_York_City}, + year = {2012} + } +\end{sourcecode} +The first appearance now looks as follows\footnote{The appearance of the + citation of course depends on the citation style you're using.}: \acf{ny}. + +\subsection{Logging of Acronyms} +When you activate \acro's option\sinceversion{2.5} \option{log} \acro' writes +information about the acronyms it defines to the log file. +\begin{options} + \keychoice{log}{\default{true},false,silent,verbose}\Default{false} + When set to \code{true}/\code{silent} \acro{} writes the main properties + of an acronym to the log file. When set to \code{verbose} \acro' writes + \emph{all} properties of an acronym to the log file. +\end{options} + +This is an example of the logging info with \keyis{log}{true} or +\keyis{log}{silent}. +\begin{sourcecode} + ================================================= + | Package acro Info -- defining new acronym: + | ID = {jpg} + | short = {JPEG} + | long = {Joint Photographic Experts Group} + | alt = {JPG} + | sort = {jpeg} + | class = {} + | list = {} + | extra = {} + | foreign = {} + | pdfstring = {} + | cite = {} + ================================================= +\end{sourcecode} + +\subsection{Using the Acronyms -- the Commands}\label{sec:using-acronyms-comm} +Acronyms are used with one of the following commands: +\begin{commands} + %% + \command{ac}[\sarg\marg{id}] + basic command; the first output is different from subsequent ones. + \command{Ac}[\sarg\marg{id}] + same as \cs{ac} but capitalizes the first letter. Obeys the option + \option{uppercase-short}. + %% + \command{acs}[\sarg\marg{id}] + \h{s}hort form; the actual acronym. + \command{Acs}[\sarg\marg{id}] + same\sinceversion{2.10} as \cs{acs} but capitalizes the first letter. + %% + \command{acl}[\sarg\marg{id}] + \h{l}ong form; the meaning of the acronym. + \command{Acl}[\sarg\marg{id}] + same as \cs{acl} but capitalizes first letter. + %% + \command{aca}[\sarg\marg{id}] + \h{a}lternative short form as specified in the \property{alt} property of + \cs{DeclareAcronym}; if it hasn't been specified this is identical to + \cs{acs}. + \command{Aca}[\sarg\marg{id}] + same\sinceversion{2.10} as \cs{aca} but capitalizes the first letter. + %% + \command{acf}[\sarg\marg{id}] + first form; output like the first time \cs{ac} is output. + \command{Acf}[\sarg\marg{id}] + same as \cs{acf} but capitalizes first letter. Obeys the option + \option{uppercase-short}. + %% + \command{acp}[\sarg\marg{id}] + \h{p}lural form of \cs{ac}; + \command{Acp}[\sarg\marg{id}] + same as \cs{acp} but capitalizes first letter. Obeys the option + \option{uppercase-short}. + %% + \command{acsp}[\sarg\marg{id}] + plural form of \cs{acs}; + \command{Acsp}[\sarg\marg{id}] + same\sinceversion{2.10} as \cs{acsp} but capitalizes the first letter. + %% + \command{aclp}[\sarg\marg{id}] + plural form of \cs{acl}; + \command{Aclp}[\sarg\marg{id}] + same as \cs{aclp} but capitalizes first letter. + %% + \command{acap}[\sarg\marg{id}] + plural form of \cs{aca}; + \command{Acap}[\sarg\marg{id}] + same\sinceversion{2.10} as \cs{acap} but capitalizes the first letter. + %% + \command{acfp}[\sarg\marg{id}] + plural form of \cs{acf}; + \command{Acfp}[\sarg\marg{id}] + same as \cs{acfp} but capitalizes first letter of the long form. Obeys + the option \option{uppercase-short}. +\end{commands} +If an acronym is used the first time with \cs{ac} its output is different from +subsequent uses. To be clear on this: the first time! If the acronym has +been used with \emph{any} of the output commands before it is \emph{not} the +first time any more. + +If you use the starred variant an acronym will not be marked as used. This +proves useful if an acronym is typeset in a section title, for example, since +then the appearance in the table of contents won't mark it as used. + +\begin{example}[side-by-side] + % preamble: + % \DeclareAcronym{cd}{ + % short = cd , + % long = Compact Disc , + % short-format = \scshape + % } + first time: \ac{cd} \\ + second time: \ac{cd} \\ + short: \acs{cd} \\ + alternative: \aca{cd} \\ + first again: \acf{cd} \\ + long: \acl{cd} \\ + short plural: \acsp{cd} \\ + long plural: \aclp{cd} +\end{example} + +\subsection{Plural Forms} +If an acronym is defined in the standard way \acro\ uses an `s' that's appended +to both the short and the long form when one of the plural commands is used. +However, that is not always the best solution. For one thing not all acronyms +may have a plural form. Second, the plural form especially of the long forms +may be formed differently. And third, other languages can have other plural +endings. + +For these reasons \cs{DeclareAcronym} can get the following keys: +\begin{properties} + \propval{short-plural}{text}\Default{s} + The plural ending of the short form. + \propval{long-plural}{text}\Default{s} + The plural ending of the long form. + \propval{long-plural-form}{text} + An alternative plural form for the long form. +\end{properties} +These keys are optional. If they're not used, the default setting is +\code{s}. If you use \property{long-plural-form} the long form will be +replaced by the specified plural form when necessary. + +Suppose we define the following acronyms: +\begin{sourcecode} + \DeclareAcronym{cd}{ + short = cd , + long = Compact Disc , + short-format = \scshape + } + \DeclareAcronym{ny}{ + short = NY , + short-plural = , + long = New York , + long-plural = + } + \DeclareAcronym{sw}{ + short = SW , + long = Sammelwerk , + long-plural = e + } + \DeclareAcronym{MP}{ + short = MP , + long = Member of Parliament , + long-plural-form = Members of Parliament + } +\end{sourcecode} +These acronyms now have the following plural appearances: +\begin{example}[side-by-side] + \acsp{cd}, \aclp{cd} \\ + \acsp{ny}, \aclp{ny} \\ + \acsp{sw}, \aclp{sw} \\ + \acsp{MP}, \aclp{MP} +\end{example} + +In the default setting the format of the long or short form is not extended to +the plural ending which might look strange if you choose bold weight as +format, for example. In this case you can tell \acro\ to extend the format. +\begin{options} + \keybool{format-include-endings}\Default{false} + Tell\sinceversion{2.8} \acro\ to use the format of the base form for the + endings, too. +\end{options} +For a more general view on endings please read section +\vref{sec:about-plural-forms}. + +\subsection{Alternative Short Forms} +For some acronyms it might be useful to have alternative forms. For this +\cs{DeclareAcronym} has another key: +\begin{properties} + \propval{alt}{text} + Alternative short form. +\end{properties} +\begin{example} + % preamble: + % \DeclareAcronym{jpg}{ + % short = JPEG , + % sort = jpeg , + % alt = JPG , + % long = Joint Photographic Experts Group + % } + default: \acs{jpg} \\ + alt.: \aca{jpg} +\end{example} +The alternative form uses the same plural ending as the default short form and +is formatted in the same way. + +\subsection{Extra Information for the List Entry} +Of course you can print a list of acronyms where their meaning is explained. +Sometimes it can be useful to add additional information there. This is done +with another key to \cs{DeclareAcronym}: +\begin{properties} + \propval{extra}{text} + Additional information for the list of acronyms. +\end{properties} +These information will only be displayed in the list. See +section~\vref{sec:print_lists} for the impact of the following example. + +\begin{example} + % preamble: + % \DeclareAcronym{nato}{ + % short = nato , + % long = North Atlantic Treaty Organization , + % extra = \textit{deutsch}: Organisation des Nordatlantikvertrags , + % short-format = \scshape + % } + The \ac{nato} is an intergovernmental military alliance based on the + North Atlantic Treaty which was signed on 4~April 1949. \ac{nato} + headquarters are in Brussels, Belgium, one of the 28 member states + across North America and Europe, the newest of which, Albania and + Croatia, joined in April 2009. +\end{example} + +\subsection{Foreign Language Acronyms}\label{ssec:foreign} +I repeatedly read the wish for being able to add translations to acronyms when +the acronyms stem from another language than the document language, +\latin{i.e.}, something like the following in a German document: +\begin{example}[side-by-side] + \ac{ecu}\\ + \ac{ecu} +\end{example} +That's why I decided to add the following properties: +\begin{properties} + \propval{foreign}{original long form} + A description for an acronym originating in another language than the + document language. + \propval{foreign-lang}{language} + \sinceversion{2.3}The \pkg{babel}~\cite{pkg:babel} or + \pkg{polyglossia}~\cite{pkg:polyglossia} language of the foreign form. + This language is used to wrap the entry with + \cs*{foreignlanguage}\marg{language}. +\end{properties} + +Here is the definition of the above mentioned \ac{ecu} acronym: +\begin{sourcecode} + \DeclareAcronym{ecu}{ + short = ECU , + long = Steuerger\"at , + foreign = Electronic Control Unit , + foreign-lang = english + } +\end{sourcecode} +As you have seen this adds the \property{foreign} entry to the first +appearance of an acronym. It is also added in parentheses to the list of +acronyms after the \property{long} entry. Actually the entry there is the +argument to the following command: +\begin{commands} + \command{acroenparen}[\marg{argument}] + Places \meta{argument} in parentheses: \cs{acroenparen}\Marg{example}: + \acroenparen{example}. See page~\pageref{key:list-foreign-format} for a + way to customize this other than redefining it. +\end{commands} + +\section{Additional Commands and Possibilities} +\subsection{Indefinite Forms} + +Unlike many other languages\footnote{Let's better say: unlike the other + languages where I know at least the basics.} in English the indefinite +article is not determined by the grammatical case, gender or number but by the +pronounciation of the following word. This means that the short and the long +form of an acronym can have different indefinite articles. For these cases +\acro\ offers the following keys: +\begin{properties} + \propval{short-indefinite}{article}\Default{a} + Indefinite article for the short form. + \propval{alt-indefinite}{article}\Default{a} + Indefinite article for the alternative form. + \propval{long-indefinite}{article}\Default{a} + Indefinite article for the long form. +\end{properties} +For every lowercase singular command two alternatives exist, preceded by +\code{i} and \code{I}, respectively, which output the lowercase and uppercase +version of the corresponding indefinite article. + +\begin{example} + % preamble: + % \DeclareAcronym{ufo}{ + % short = UFO , + % long = unidentified flying object , + % long-indefinite = an + % } + \Iac{ufo}; \iacs{ufo}; \iacl{ufo} +\end{example} + +\subsection{Uppercasing} +\begin{commands} + \command{acfirstupper}[\marg{token list}] + This command uppercases the first token in \meta{token list}. The + command is less powerful than \cs{makefirstuc} that is provided by the + \pkg{mfirstuc} package~\cite{pkg:mfirstuc} but it is expandable. Obvious + downsides are for example that it does not uppercase accented letters. +\end{commands} +The following options control the behaviour of the uppercasing commands: +\begin{options} + \keyval{uc-cmd}{control sequence}\Default{\cs{acfirstupper}} + The command that is used to capitalize the first word in the \cs{Ac} and + the like commands. You can change it to another one like for example + \cs*{makefirstuc}\footnote{from the \pkg{mfirstuc} package} or + \cs*{MakeTextUppercase}\footnote{from the \pkg*{textcase} package}. + %% + \keybool{uppercase-short}\Default{true} + If\sinceversion{2.10} set to \code{true} commands like \cs{Ac} or \cs{Acp} + will uppercase the first letter of the short form. Commands like \cs{Acs} + or \cs{Acsp} will uppercase the short form in any case. +\end{options} + +\subsection{Simulating the First Appearance}\label{sec:simul-first-appe} +Users told me\footnote{Well -- one, to be precise ;)} that there are cases +when it might be useful to have the the acronym typeset according to the +\option{first-style} option (or \property{first-style} property) but with +another text than the long form. For such cases \acro\ offers the following +commands. +\begin{commands} + \command{acflike}[\sarg\marg{id}\marg{instead of long form}] + Write some alternative long form for acronym with \acs{id} \meta{id} as if + it were the first time the acronym was used. + \command{acfplike}[\sarg\marg{id}\marg{instead of long form}] + Plural form of \cs{acflike}. +\end{commands} + +\begin{example}[side-by-side] + \acsetup{first-style=footnote} + \acflike{ny}{the big apple} +\end{example} + +The plural ending in \cs{acfplike} is only appended to the short form. It +makes no sense to append it to the text that is inserted manually anyway. +Note that whatever text you're inserting might be gobbled depending on the +\option{first-style} you're using. + +\subsection{Fetching the Single Appearance} +There\sinceversion{2.3} are macros that fetch the \emph{single} appearance of +an acronym even if it has been used more than once and the \option{single} +option is active. +\begin{commands} + \command{acsingle}[\sarg\marg{id}] + Write acronym as if it were used only a single time. + \command{Acsingle}[\sarg\marg{id}] + Uppercase form of \cs{acsingle}. + \command{acpsingle}[\sarg\marg{id}] + Plural\sinceversion{2.11} form of \cs{acsingle}. + \command{Acsingle}[\sarg\marg{id}] + Plural\sinceversion{2.11} form of \cs{Acsingle}. +\end{commands} + +\begin{example}[side-by-side] + \acsingle{ny} +\end{example} + +\subsection{Using Classes} +The acronyms of \acro\ can be divided into different classes. This doesn't +change the output but allows different acronym lists, see +section~\vref{sec:print_lists}. For this \cs{DeclareAcronym} has an additional +key: +\begin{properties} + \propval{class}{csv list} + Associated\changedversion{2.4} class(es) for an acronym. +\end{properties} + +This might be useful if you can and want to divide your acronyms into +different types, technical and grammatical ones, say, that shall be listed in +different lists. Since every acronym can get a list of associated classes +those classes can effectively be used like tags for filtering acronyms. + +\begin{example}[side-by-side] + % preamble: + % \DeclareAcronym{la}{ + % short = LA , + % short-plural = , + % long = Los Angeles , + % long-plural = , + % class = city + % } + % \DeclareAcronym{ny}{ + % short = NY , + % short-plural = , + % long = New York , + % long-plural = , + % class = city , + % cite = NewYork + % } + \acl{la} (\acs{la}) \\ + \acl{ny} (\acs{ny}) +\end{example} + +\subsection{Reset or Mark as Used, Test if Acronym Has Been Used} + +If you want for some reason to fool \acro\ into thinking that an acronym is +used for the first time you can call one of these commands: +\begin{commands} + \command{acreset}[\marg{comma separated list of ids}] + This will reset a used acronym such that the next use of \cs{ac} will + again print it as if it were used the first time. This will \emph{not} + remove an acronym from being printed in the list if it actually \emph{has} + been used before. + \command{acresetall} + Reset all acronyms. + \command{acifused}[\marg{id}\marg{true}\marg{false}] + This command tests if the acronym with \ac{id} \meta{id} has already been + used and either puts \code{true} or \code{false} in the input stream. + \command{aciffirst}[\marg{true}\marg{false}] + To\sinceversion{2.8} be used inside of acronym definitions in order to + test if we are inside the first instance of the acronym or not. +\end{commands} +\begin{example}[side-by-side] + \acreset{ny}\ac{ny} +\end{example} +Beware that both commands act \emph{globally}! There are also commands that +effectively do the opposite of \cs{acreset}, \latin{i.e.}, mark acronyms as +used: +\begin{commands} + \command{acuse}[\marg{comma separated list of ids}] + This has the same effect as if an acronym had been used twice, that is, + further uses of \cs{ac} will print the short form and the acronym will in + any case be printed in the list (as long as its class is not excluded). + \command{acuseall} + Mark all acronyms as used. +\end{commands} +Then there are two further commands related to using acronyms: +\begin{commands} + \command{acswitchoff} + This\sinceversion{2.6} command is for patching in certain situations. For + example some table environments like \env*{tabularx} or \env*{tabu} pass + their content two or more times for determining the width of the table + columns. Those can be patched to add \cs{acswitchoff} to their trial + phase. + \command{acswitchon} + Effectively\sinceversion{2.6} the opposite of \cs{acswitchoff} -- this + command should probably never be needed. +\end{commands} + +\subsection{\cs*{ac} and Friends in \acs*{pdf} Bookmarks, Accessibility + Support, Tooltips} +\subsubsection{\acs*{pdf} Bookmarks} +\acro's commands usually are not expandable which means they'd leave unallowed +tokens in \acs{pdf} bookmarks. \pkg{hyperref} offers \cs*{texorpdfstring} to +circumvent that issue manually but that isn't really a nice solution. What's +the point of having macros to get output for you if you have to specify it +manually after all? + +That is why \acro\ offers a preliminary solution for this. In a bookmark +every \cs{ac} like command falls back to a simple text string typesetting what +\cs{acs} would do (or \cs{acsp} for plural forms). These text strings both +can accessed manually and can be modified to an output reserved for \acs{pdf} +bookmarks. + +\begin{commands} + \command{acpdfstring}[\marg{id}] + Access the text string used in \acs{pdf} bookmarks. + \command{acpdfstringplural}[\marg{id}] + Access the plural form of the text string used in \acs{pdf} bookmarks. +\end{commands} +\begin{properties} + \proplit-{pdfstring}{\Marg{\meta{pdfstring}/\meta{plural ending}}} + Key for \cs{DeclareAcronym} to declare a custom text string for \acs{pdf} + bookmarks. The plural ending can be set optionally. +\end{properties} + +For example the \acs{pdf} acronym used in the title for this section is defined +as follows: +\begin{sourcecode} + \DeclareAcronym{pdf}{ + short = pdf , + long = Portable Document Format , + format = \scshape , + pdfstring = PDF , + accsupp = PDF + } +\end{sourcecode} + +\subsubsection{Accessibility Support} + +The last example also demonstrates the \property{accsupp} key. The idea is to +have something different visible in the \acs{pdf} file compared to what you +get when you select and copy the corresponding string. In the example visible +string is a lowercase \code{pdf} in small caps while the string copied is an +uppercase \code{PDF}. + +For this to work you need to use the \emph{package option} \option{accsupp}, +too, which will load the package \pkg{accsupp} if it isn't loaded by the user +already. Then the key \property{accsupp} will set the \code{ActualText} +property of \cs*{BeginAccSupp}. Please refer to \pkg{accsupp}'s documentation +for details. To see its effect copy \ac{pdf} and paste it into a text file. +You should get uppercase letters instead of lowercase ones. + +\begin{properties} + \propval{accsupp}{text} + Key for \cs{DeclareAcronym} to set the \code{ActualText} property of + \cs*{BeginAccSupp} (see \pkg{accsupp}'s documentation for details) to be + used for an acronym. It only has an effect when the package option + \option{accsupp} is used, too. +\end{properties} +\begin{options} + \keybool{accsupp}\Default{false} + Activate \acro's accessibility support. +\end{options} + +\subsubsection{Tooltips} + +The idea of a tooltip is to have some text shown when you hover with the +mouse over the short form of an acronym. This is only available in some +\acs{pdf} viewers, though. On possibility for such tooltips is loading the +\pkg{pdfcomment} package~\cite{pkg:pdfcomment} and using its \cs*{pdftooltip} +macro. + +\begin{options} + \keybool{tooltip}\Default{false} + This\sinceversion{2.1} options loads the \pkg{pdfcomment} package and sets + the command for creating tooltips to \cs*{pdftooltip}. + \keyval{tooltip-cmd}{control sequence}\Default{\cs*{@firstoftwo}} + This\sinceversion{2.1} allows users using another macro for tooltips -- + maybe one provided by another package or some own macro. It needs to be a + macro with two mandatory arguments, the first being the string typeset in + the \acs{pdf}, the second being the tooltip description text. +\end{options} + +For using this with acronyms they have a property \property{tooltip} which can +be used inside \cs{DeclareAcronym} for specifying the description text of the +tooltip. If the \option{tooltip} package option is used but the property is +not set for an acronym then the \property{long} property is used instead. + +If an acronym is used inside of another acronym then the tooltips of the +``inner'' acronyms are disabled. + +\subsection{Adding Acronyms to the Index}\label{ssec:index} +\acro\ has the package option \option{index}. If it is used an index entry +will be recorded every time an \emph{unstarred} acronym command is used. The +index entry will be \code{\meta{id}@\meta{short}}, +\code{\meta{sort}@\meta{short}} if the \property{sort} property has been set, +\code{\meta{index-sort}@\meta{short}} if the property \property{index-sort} +has been set, or \meta{index} if the property \property{index} has been set +for the specific acronym. The short versions appearing there are formatted +according to the chosen format of the corresponding acronym, of course. + +This document demonstrates the feature. You can find every acronym that has +been declared in the index. In order to allow flexibility the indexing +command can be chosen both globally via package option and individually for +every acronym. This would allow to add acronyms to a specific index if more +than one index is used, for example with help of the \pkg*{imakeidx} package. + +I'm not yet convinced this is a feature many people if anyone needs and if +they do if it is flexible enough. If you have any thoughts on this I'd +appreciate an email. + +\section{Printing the List}\label{sec:print_lists} +Printing the whole list of acronyms is easy: just place \cs{printacronyms} +where ever you want the list to be. +\begin{commands} + \command{printacronyms}[\oarg{options}] + Print the list of acronyms. +\end{commands} +The commands takes a few options, namely the following ones: +\begin{options} + \keyval{include-classes}{list of classes} + Takes a comma-separated list of the classes of acronyms that should be in + the list. + \keyval{exclude-classes}{list of classes} + Takes a comma-separated list of the classes of acronyms that should + \emph{not} be in the list. \emph{Note that this list overwrites any + entries in \option{include-classes}!} If a class is both included and + excluded then the corresponding acronyms will not be added to the list. + \keyval{name}{name of the list} + sets the name for the list. + \keyval{heading}{sectioning command without leading backslash}% + \Default{section*} + Sets the sectioning command for the heading of the list. A special value + is \code{none} which suppresses the heading. + \keybool{sort}\Default{true} + Set sorting for this list only. + \keybool{local-to-barriers}\Default{false} + This\sinceversion{2.4} option can be used to create a list of only the + acronyms of the current \enquote{barrier group}, see + section~\ref{sec:divid-your-docum}. +\end{options} +\begin{example} + \acsetup{extra-style=comma} + \printacronyms[exclude-classes=city] + + \printacronyms[include-classes=city,name={City Acronyms}] +\end{example} + +You can see that the default layout is a \code{description} list with a +\cs*{section}\sarg\ title. Both can be changed, see +section~\vref{sec:customization}. + +The command \cs{printacronyms} needs two \LaTeX{} runs. This is a precaution +to avoid error messages with a possibly empty list. But since almost all +documents need at least two runs and often are compiled much more often than +that, this fact shouldn't cause too much inconvenience. + +\section{Options and Customization}\label{sec:customization} +\subsection{General Options} +There are a few options which change the general behaviour of \acro. +\default{Underlined} values are used if no value is given. \acro's package +options are best set onyl via the setup command: +\begin{commands} + \command{acsetup}[\marg{options}] + Set up \acro. +\end{commands} +\begin{bewareofthedog} + They \emph{might} work as package options to \cs*{usepackage} as well but + \emph{I do not recommend it} and will likely remove this in a future + version~3 of \acro. +\end{bewareofthedog} + +\begin{options} + \keychoice{messages}{silent,loud}\Default{loud} + Setting \keyis{messages}{silent} will turn all of \acro's error messages + into warnings and all of \acro's warnings into info messages. Be sure to + check the log file carefully if you decide to set this option. + %% + \keybool{single}\Default{false} + If set to \code{true} an acronym that's used only once (with \cs{ac}) in a + document will only print the acronym in a specified form and will not be + printed in the list. + %% + \keybool{case-sensitive}\Default{true} + If\sinceversion{2.11} set to \code{true} the \meta{id} as used in + \cs{DeclareAcronym} or \cs{ac} is read \emph{case sensitive}, + \latin{i.e.}, \code{id} would differ from \code{ID}. This is \acro's + default behaviour. + + If set to \code{true} \code{id} would be the same as \code{ID}. This can + be useful when acronyms are used in page headings for example. + %% + \keychoice{single-form}{long,short,alt,first}\Default{long} + \sinceversion{2.0}Determines how a single appearance of an acronym is + printed if \keyis{single}{true} has been chosen. + %% + \keybool{hyperref}\Default{false} + If set to \code{true} the short forms of the acronyms will be linked to + their list entry. + %% + \keybool{label}\Default{false} + If set to \code{true} this option will place + \cs*{label}\Marg{\meta{prefix}\meta{id}} the first time the acronym with + \ac{id} \meta{id} is used. + %% + \keyval{label-prefix}{text}\Default{ac:} + The prefix for the \cs*{label} that is placed when option + \keyis{label}{true} is used. + %% + \keybool{only-used}\Default{true} + This option is \code{true} as default. It means that only acronyms that + are actually used in the document are printed in the list. If + \code{false}, all acronyms defined with \cs{DeclareAcronym} will be + written to the list. + %% + \keychoice{mark-as-used}{first,any}\Default{any} + This option determines wether an acronym is mark as used when the + \emph{first} form is used the first time (with \cs{ac}, \cs{acf} or + \cs{acflike} and their uppercase, plural and indefinite forms) or when any + of the \cs{ac}-like commands is used. + %% + \keybool{macros}\Default{false} + If set to \code{true} this option will create a macro \cs*{\meta{id}} for + each acronym as a shortcut for \cs{ac}\marg{id}. Already existing macros + will \emph{not} be overwritten. + %% + \keybool{xspace}\Default{false} + If set to \code{true} this option will append \cs*{xspace} from the + \pkg*{xspace} package to the commands created with the \option{macros} + option. + %% + \keybool{strict}\Default{false} + If set to \code{true} and the option \keyis{macros}{true} is in effect + then already existing macros will be overwritten. + %% + \keybool{sort}\Default{true} + If set to \code{true} the acronym list will be sorted alphabetically. The + entries are sorted by their \acs{id} ignoring upper and lower case. This + option needs the experimental package \pkg{l3sort} (from the + \pkg{l3experimental} bundle) and can only be set in the preamble. + If set to \code{false} the acronyms are listed in order of their + declaration. + %% + \keybool{display-foreign}\Default{true} + When set to \code{false} any \property{foreign} property is ignored and + foreign forms are not displayed. + %% + \keychoice{cite}{\default{all},first,none}\Default{first} + \changedversion{2.4b}This option decides whether citations that are added + via \property{cite} are added to each first, every or no appearance of an + acronym. If \code{first} is chosen, the option \keyis{single}{true} is + active and an acronym appears only once it still will get the citation. + %% + \keyval{cite-cmd}{control sequence}\Default{\cs*{cite}} + This option determines which command is used for the citation. Each + citation command that takes the cite key as argument is valid, for example + \pkg*{biblatex}'s \cs*{footcite}. + %% + \keyval{cite-connect}{code}\Default{\cs*{nobreakspace}} + Depending on the citation command in use a space should be inserted before + the citation or maybe not (e.g.\ \cs*{footcite}\ldots). This option + allows you to set this. Actually it can be used to place arbitrary code + right before the citation. + %% + \keybool{group-citation}\Default{false} + \sinceversion{2.0}If set to true the short form (or the long form) and the + citation of an acronym will be printed together in parentheses when an + acronym is used the first time. + %% + \keyval{group-cite-cmd}{control sequence}\Default{\cs*{cite}} + \sinceversion{2.0}This option determines which command is used for the + citation when an acronym is used the first time \emph{and} + \keyis{group-citation}{true}. Each citation command that takes the cite + key as argument is valid, for example \pkg*{biblatex}'s \cs*{footcite}. + %% + \keyval{group-cite-connect}{code}\Default{\code{,\cs*{nobreakspace}}} + \sinceversion{2.0}When \keyis{group-citation}{true} this is inserted + between the long/short form of the acronym and the citation within the + parentheses. + %% + \keybool{index}\Default{false} + If set to \code{true} an index entry will be recorded every time an + \emph{unstarred} acronym command is used for the corresponding acronym. + %% + \keyval{index-cmd}{control sequence}\Default{\cs*{index}} + Chooses the index command that is used when option \option{index} has been + set to \code{true}. + %% + \keybool{accsupp}\Default{false} + Activates the access support as provided by the \pkg{accsupp} package. + %% + \keybool{tooltip}\Default{false} + \sinceversion{2.1}Activates tooltip support for \acro\ using the + \pkg{pdfcomment} package. + %% + \keyval{tooltip-cmd}{control sequence}\Default{\cs*{@firstoftwo}} + \sinceversion{2.1}A macro taking two mandatory arguments, the first being + the short form of the acronym and the second being some tooltip + description. + %% + \keyval{uc-cmd}{control sequence}\Default{\cs{acfirstupper}} + The command that is used to capitalize the first word in the \cs{Ac} and + the like commands. You can change it to another one like for example + \cs*{makefirstuc}\footnote{from the \pkg{mfirstuc} package} or + \cs*{MakeTextUppercase}\footnote{from the \pkg*{textcase} package}. + %% + \keybool{uppercase-short}\Default{true} + If\sinceversion{2.10} set to \code{true} commands like \cs{Ac} or \cs{Acp} + will uppercase the first letter of the short version. +\end{options} + +\begin{example} + % with \acsetup{macros} activated: + we could have used these before: \nato, \ny +\end{example} + +\subsection{Options Regarding Acronyms}\label{sec:opti-regard-acronyms} +The options described in this section all influence the layout of one of the +possible output forms of the acronyms. +\begin{options} + %% + \keyval{short-format}{format}\Default + Sets a format for all short forms. For example + \keyis{short-format}{\cs*{scshape}} would print all short forms in small + caps. + %% + \keyval{long-format}{format}\Default + The same for the long forms. + %% + \keyval{foreign-format}{format}\Default + The format for the \property{foreign} entry when it appears as part of the + first appearance of an acronym. + %% + \keyval{single-format}{format}\Default + \sinceversion{2.3}% + The format for the acronym when it is used only once. If not specified + the formatting according to \option{single-form} is used. + %% + \keyval{first-long-format}{format}\Default + The format for the long form on first usage (with \cs{ac}, \cs{acf} or + \cs{acflike} and their uppercase, plural and indefinite forms). + %% + \keyval{list-short-format}{format}\Default + An extra format for the short entries in the list. If not used this is + the same as \option{short-format}. Please be aware that a call of + \option{short-format} after this one will overwrite it again. + %% + \keyval{list-short-width}{dim}\Default{3em} + \sinceversion{2.1}This option controls the width reserved for the short + forms of the acronyms in the \code{lof} list style. + %% + \keyval{list-long-format}{format}\Default + An extra format for the long entries in the list. If not used this is the + same as \option{long-format}. Please be aware that a call of + \option{long-format} after this one will overwrite it again. + %% + \keyval{list-foreign-format}{format}\Default{\cs{acroenparen}} + \label{key:list-foreign-format}The format for the \property{foreign} entry + as it appears in the list. This may be code that ends with a macro that + takes a mandatory argument. + %% + \keyval{extra-format}{format}\Default + The same for the extra information. + %% + \keychoice{first-style}{default,empty,square,short,long,reversed,footnote,sidenote,% + footnote-reversed,sidenote-reversed}\Default{default} + The basic style of the first appearance of an acronym. The value + \code{sidenote} needs the command \cs*{sidenote} to be defined (for + example by the \pkg*{sidenotes} package). + %% + \keychoice{extra-style}{default,plain,comma,paren,bracket}\Default{default} + Defines the way the extra information is printed in the list. + %% + \keylit{plural-ending}{\meta{short}/\meta{long}}\Default{s/s} + \changedversion{2.4b}With this option the default plural ending can be + set. The appended \meta{long} ending is optional. If you leave it + (\emph{and} the \code{/}) the \meta{short} ending is used for both short + and long versions. +\end{options} + +\begin{example}[side-by-side] + % (Keep in mind that we're in + % a minipage here!) + \acsetup{first-style=empty} + empty: \acf{ny} \\ + \acsetup{first-style=footnote} + footnote: \acf{ny} \\ + \acsetup{first-style=square} + square: \acf{ny} \\ + \acsetup{first-style=short} + short: \acf{ny} \\ + \acsetup{first-style=long} + long: \acf{ny} \\ + \acsetup{first-style=reversed} + reversed: \acf{ny} \\ + \acsetup{first-style = footnote-reversed} + footnote-reversed: \acf{ny} +\end{example} + +\subsection{Options Regarding the List} +\begin{options} + %% + \keychoice{page-style}{none,plain,comma,paren}\Default{none} + If this option is set to a value other than \code{none} the page numbers + of the an acronym appeared on are printed in the list. Please note that + this is an experimental feature and might fail in quite a number of cases. + If you notice anything please send me an email! + %% + \keychoice{pages}{all,first}\Default{all} + If the option \option{page-style} has any value other than \code{none} + this option determines wether all usages of the acronyms are listed or + only the first time. Implicitly sets \keyis{label}{true}. + %% + \keyval{page-name}{page name}\Default{p.\cs*{@}\cs*{,}} + The ``name'' of the page label. This is automatically translated to the + active language. However for the time being there are many translations + missing, yet. Please notify me if you find your language missing. + %% + \keyval{pages-name}{page name plural}\Default{pp.\cs*{@}\cs*{,}} + The ``name'' of the page label when there are more than one page. This is + automatically translated to the active language. However for the time + being there are many translations missing, yet. Please notify me if you + find your language missing. + %% + \keybool{following-page}\Default{false} + If set to \code{true} a page range in the list of acronyms that consists + of two pages will be written by the first page and an appended + \code{f}. This depends on the option \option{next-page}. + %% + \keybool{following-pages}\Default{false} + If set to \code{true} a page range in the list of acronyms that set + consists of more than two pages will be written by the first page and an + appended \code{ff}. This depends on the option \option{next-pages}. + %% + \keybool{following-pages*}\Default{false} + \sinceversion{2.5}If set to \code{true} this sets both options + \keyis{following-page}{true} and \keyis{following-pages}{true}. + \code{false} sets \keyis{following-page}{false} and + \keyis{following-pages}{false}. + %% + \keyval{next-page}{text}\Default{\cs*{,}f.\cs*{@}} + Appended to a page number when \option{following-page} is set to + \code{true} and the range is only 2 pages long. This is automatically + translated to the active language. However, for the time being there are + many translations missing, yet. Please notify me if you find your + language missing. + %% + \keyval{next-pages}{text}\Default{\cs*{,}ff.\cs*{@}} + Appended to a page number when \option{following-pages} is set to + \code{true} and the range is more than 2 pages long. This is + automatically translated to the active language. However, for the time + being there are many translations missing, yet. Please notify me if you + find your language missing. + %% + \keychoice{list-style}{description,lof,longtable,extra-longtable,% + extra-longtable-rev,extra-tabular,extra-tabular-rev,tabular,toc}% + \Default{description} + \changedversion{2.2}Choose with which style the list of acronyms should be + typeset. If you choose \meta{longtable}, \code{extra-longtable} or + \code{extra-longtable-rev} you have to load the + \pkg{longtable}~\cite{pkg:longtable} package in your preamble. The values + \code{extra-\meta{something}} put the extra information in a column of it + own. \emph{Be aware that per default \emph{all} \code{extra-table} styles + only use \code{l} columns. Since acronym descriptions can easily get + longer that a line you should probably define your own style if you want + to use them.} See section~\vref{sec:lists} for details. + %% + \keychoice{list-heading}{chapter,chapter*,section,section*,subsection,% + subsection*,subsubsection,subsubsection*,addchap,addsec,none}% + \Default{section*} + \changedversion{2.0}The heading type of the list. The last two only work + with a \KOMAScript{} class that also defines the appropriate command. A + special value is \code{none} which suppresses the heading. + %% + \keyval{list-name}{list name}\Default{Acronyms} + The name of the list. This is what's written in the list-heading. This + is automatically translated to the active language. However, for the time + being there are many translations missing, yet. Please notify me if you + find your language missing. + %% + \keybool{list-caps}\Default{false} + Print the first letters of the long form capitalized. +\end{options} + +\section{Trailing Tokens and Special Action} + +\acro\ has the possibility\sinceversion{2.0} to look ahead for certain tokens +and switch a boolean if it finds them. Per default \acro\ knows about three +tokens: the \enquote{\code{dot}} (\code{.}), the \enquote{\code{dash}} +(\code{-}) and the \enquote{\code{babel-hyphen}} (\cs*{babelhyphen}). + +A token is made known to \acro\ with the following macro: +\begin{commands} + \command{AcroRegisterTrailing}[\meta{token}\marg{name}] + This registers the token \meta{token} so \acro\ looks if it follows + directly after an acronym macro. \meta{name} is the internal name for + this token. +\end{commands} +The \acro\ package already registers the above mentioned tokens: +\begin{sourcecode} + \AcroRegisterTrailing . {dot} + \AcroRegisterTrailing - {dash} + \AcroRegisterTrailing \babelhyphen {babel-hyphen} +\end{sourcecode} + +If a token is registered it doesn't mean that \acro\ looks for it. The token +must first be activated for this: +\begin{options} + \keyval{activate-trailing-tokens}{csv list of token names} + Tell \acro\ to look for trailing tokens. This is done by giving a csv + list of the internal \emph{names} of the tokens. Per default only + \code{dot} is activated. + \keyval{deactivate-trailing-tokens}{csv list of token names} + Tell \acro\ not to look for trailing tokens. This is done by giving a csv + list of the internal \emph{names} of the tokens. +\end{options} + +All of the above on its own does nothing visible. However: inside of an +acronym, \ie, for example inside the long or the short form it can be tested +for those trailing tokens: +\begin{commands} + \command{aciftrailing}[\marg{csv list of token + names}\marg{true}\marg{false}] + Check if one of the tokens listed in \meta{csv list of token names} is + following and either place \meta{true} or \meta{false} in the input + stream. +\end{commands} +\acro\ uses this to define to further macros: +\begin{commands} + \command{acdot} Inserts a \code{.} if no \code{dot} follows. + \command{acspace} Inserts a \cs*{space} if no \code{dash} or + \code{babel-hyphen} follows. +\end{commands} +The definitions are equivalent\footnote{Not \emph{quite}: \acro's definitions + are engine protected.} to the following code: +\begin{sourcecode} + \newcommand*\acdot{\aciftrailing{dot}{}{.\@}} + \newcommand*\acspace{\aciftrailing{dash,babel-hyphen}{}{\space}} +\end{sourcecode} + +This could be used to define an acronym as follows: +\begin{sourcecode} + \DeclareAcronym{etc}{ + short = {\textit{etc}\acdot} , + long = {\textit{et cetera}} , + short-plural = , long-plural = + } +\end{sourcecode} +If now you somewhere use +\begin{sourcecode} + \ac{etc}. +\end{sourcecode} +there won't be two dots printed. + +The command \cs{acspace} is used already in the definition of the first +appearance of a macro. Let's say you're a German chemist and you have +\begin{sourcecode} + \DeclareAcronym{PU}{ + long = Polyurethan , + long-plural = e + } +\end{sourcecode} +and you use it the first time like this: +\begin{sourcecode} + \ac{PU}-Hartschaum +\end{sourcecode} +then according to German orthography and typesetting rules this should be +printed as +\begin{center} + \enquote{Polyurethan(PU)-Hartschaum} +\end{center} +\ie, with \emph{no} space between long and short form. This is exactly what +happens it you say +\begin{sourcecode} + \acsetup{activate-trailing-tokens = {dash,babel-hyphen}} +\end{sourcecode} +in the preamble. + +\section{About Page Ranges} +If you enable the \option{page-style} option \acro\ adds page numbers to the list +of acronyms. In version~0.\versionstar{} it would add a page reference for an +acronym in the list of acronyms that used \cs*{pageref} to refer to the first +appearance of an acronym. This is retained using \keyis{pages}{first}. +Version~1.0 uses a different approach that doesn't use a label but instead +will list \emph{all} pages an acronym appeared on. With \pkg{hyperref} the +pages are referenced using \cs*{hyperpage}. + +There are some options that control how this list will be typeset, e.g., +\option{following-page}, \option{next-pages} or the option \option{page-style} +itself. It is important to mention that the page list will always take at +least two compilation runs until changes in the options or the actual page +numbers affect it. This is due to the fact that the updated sequence is first +written to the \code{aux} file and only read in during the next run. + +\section{Dividing Your Document Into Pieces -- Creating Local + Lists}\label{sec:divid-your-docum} + +\acro\sinceversion{2.4} introduces the concept of \emph{barriers} which can +divide the document into parts. It is possible to create lists of only those +acronyms used between two such barriers. +\begin{commands} + \command{acbarrier} + Sets a barrier at the point of use in the document. The begin and the end + of the document mark implicit barriers. +\end{commands} +\begin{options} + \keybool{use-barriers}\Default{false} + \sinceversion{2.5}If you want to use barriers and local lists you have to + activate the feature first. This should be set in the preamble in order + to work reliably. Make sure to watch out for log file messages asking you + to rerun. + \keybool{reset-at-barriers}\Default{false} + If this option is set to \code{true} \cs{acbarrier} implicitly calls + \cs{acresetall}. + \keybool{local-to-barriers}\Default{false} + This option can \emph{only} be used as option to the \cs{printacronyms} + command. It then prints a list of only the acronyms of the current + \enquote{barrier group}. +\end{options} + +\begin{example} + \acbarrier + \printacronyms[local-to-barriers] + \ac{ctan} and \ac{lppl} + \acbarrier +\end{example} + +\section{Language Support} +\acro\ detects if packages \pkg{babel}~\cite{pkg:babel} or +\pkg{polyglossia}~\cite{pkg:babel} are being loaded and tries to adapt certain +strings to match the chosen language. However, due to my limited language +knowledge only a few translations are provided. I'll show how the English +translations are defined so you can add the translations to your preamble if +needed. Even better would be you'd send me a short email to +\mailto{contact@mychemistry.eu} with the appropriate translations for your +language and I'll add them to \acro. + +\begin{sourcecode} + \DeclareTranslation{English}{acronym-list-name}{Acronyms} + \DeclareTranslation{English}{acronym-page-name}{p.} + \DeclareTranslation{English}{acronym-pages-name}{pp.} + \DeclareTranslation{English}{acronym-next-page}{f.} + \DeclareTranslation{English}{acronym-next-pages}{ff.} +\end{sourcecode} + +\section{hyperref Support} +The option \keyis{hyperref}{true} adds internal links from all short (or +alternative) forms to their respective list entries. Of course this only +works if you have loaded the \pkg{hyperref} package in your preamble. You +should use this option with care: if you don't use \cs{printacronyms} anywhere +this option will result in loads of \pkg{hyperref} warnings. Also printing +several lists can result in warnings if don't clearly separate the lists into +different classes. If an acronym appears in more than one list there will +also be more than one hypertarget for this acronym. + +Using \pkg{hyperref} will also add \cs*{hyperpage} to the page numbers in the +list (provided they are displayed in the style chosen). Like with an index +the references will thus not point to the acronyms directly but to the page +they're on. + +\section{Defining Own Acronym Macros}\label{sec:defining-own-acronym} + +The commands\sinceversion{2.0} explained in +section~\vref{sec:using-acronyms-comm} have all been defined with a dedicated +command -- there is a family of dedicated commands, actually: +\begin{commands} + \command{NewAcroCommand}[\marg{cs}\marg{code}] + Defines a new \acro\ acronym command \meta{cs}. This sets up the + necessary framework needed by acronym commands and defines \meta{cs} with + an optional star argument and a mandatory argument for the acronym id + using \pkg{xparse}'s \cs*{NewDocumentCommand}. Inside \meta{code} one can + refer to the \acs{id} \meta{id} with \code{\#1}. + \command{RenewAcroCommand}[\marg{cs}\marg{code}] + Defines a new \acro\ acronym command \meta{cs}. This sets up the + necessary framework needed by acronym commands and defines \meta{cs} with + an optional star argument and a mandatory argument for the acronym id + using \pkg{xparse}'s \cs*{RenewDocumentCommand}. Inside \meta{code} one + can refer to the \acs{id} \meta{id} with \code{\#1}. + \command{DeclareAcroCommand}[\marg{cs}\marg{code}] + Defines a new \acro\ acronym command \meta{cs}. This sets up the + necessary framework needed by acronym commands and defines \meta{cs} with + an optional star argument and a mandatory argument for the acronym id + using \pkg{xparse}'s \cs*{DeclareDocumentCommand}. Inside \meta{code} one + can refer to the \acs{id} \meta{id} with \code{\#1}. + \command{ProvideAcroCommand}[\marg{cs}\marg{code}] + Defines a new \acro\ acronym command \meta{cs}. This sets up the + necessary framework needed by acronym commands and defines \meta{cs} with + an optional star argument and a mandatory argument for the acronym id + using \pkg{xparse}'s \cs*{ProvideDocumentCommand}. Inside \meta{code} one + can refer to the \acs{id} \meta{id} with \code{\#1}. +\end{commands} + +Inside these macros one can use a number of low-level expl3 +commands\footnote{Which is why you need to use them inside an expl3 + programming environment. This means in the preamble surround the + definitions with \cs*{ExplSyntaxOn} and \cs*{ExplSyntaxOff}.}. + +\paragraph{Acronym fetching commands} +\begin{commands} + \command*{acro_use:n}[ \marg{id}] + Fetches the acronym using either the first or the short form depending on + earlier uses. + \command*{acro_short:n}[ \marg{id}] + Fetches the short form of the acronym. + \command*{acro_long:n}[ \marg{id}] + Fetches the long form of the acronym. + \command*{acro_alt:n}[ \marg{id}] + Fetches the alternative short form of the acronym. + \command*{acro_foreign:n}[ \marg{id}] + Fetches the foreign property of the acronym if available. + \command*{acro_extra:n}[ \marg{id}] + Fetches the extra property of the acronym if available. +\end{commands} + +\paragraph{Acronym setup commands} +\begin{commands} + \command*{acro_first_upper:} + \acro\ setup command which tells the macros above that we want to + uppercase the first letter of the long version. Should be used + \emph{before} one of the acronym fetching commands. + \command*{acro_plural:} + \acro\ setup command which tells the macros above that we want to use + plural forms. Should be used \emph{before} one of the acronym fetching + commands. + \command*{acro_indefinite:} + \acro\ setup command which tells the macros above that we want to add the + indefinite article. Should be used \emph{before} one of the acronym + fetching commands. + \command*{acro_cite:} + \acro\ setup command which tells the macros above that we want to add the + citation in any case independent of the option \option{cite}. Should be + used \emph{before} one of the acronym fetching commands. + \command*{acro_no_cite:} + \acro\ setup command which tells the macros above that we want to have no + citation independent of the option \option{cite}. Should be used + \emph{before} one of the acronym fetching commands. + \command*{acro_index:} + \acro\ setup command which tells the macros above that we want to add an + index entry in any case independent of the option \option{index}. Should + be used \emph{before} one of the acronym fetching commands. + \command*{acro_reset_specials:} + This\sinceversion{2.0b} macro is called implicitly by \cs{NewAcroCommand} + and \cs{NewPseudoAcroCommand}. If you plan to define an \acro\ command by + yourself using \cs*{NewDocumentCommand} this should be the first macro + after \verbcode+\acro_begin:+. It ensures that in nested acronyms the + inner acronyms don't inherit indefinite articles, uppercasing, + endings\ldots +\end{commands} + +\paragraph{Additional macros for further uses} +\begin{commands} + \command*{acro_begin:} + When an acronym macro is defined \enquote{by hand}, \ie, \emph{not using + \cs{NewAcroCommand}} then this must be the first macro in the code. + \emph{Must have a matching \cs*{acro_end:}}. + \command*{acro_end:} + When an acronym macro is defined \enquote{by hand}, \ie, \emph{not using + \cs{NewAcroCommand}} then this must be the last macro in the code. + \emph{Must have a matching \cs*{acro_begin:}}. + \command*{acro_check_and_mark_if:nn}[ \marg{boolean expression} \marg{id}] + Checks if the acronym with the \acs{id} \meta{id} exists and marks it as + used when \meta{boolean} expression evaluates to \code{true}. This macro + is used inside \cs{NewAcroCommand} and friends implicitly. + \command*{acro_check_acronym:nn}[ \marg{id} \Marg{true|false}] + Checks if the acronym with the \acs{id} \meta{id} exists and marks it as + used if \code{true} or doesn't. This macro is used inside + \cs*{acro_check_and_mark_if:nn}. + \command*{acro_use_acronym:n}[ \Marg{true|false}] + Tell \cs*{acro_use:n} and similar commands wether to mark the acronym as + used or not. This macro is used inside \cs*{acro_check_acronym:nn}. If + this macro is used explicitly it should be used before \cs*{acro_use:n} + (or a similar command) otherwise it has no effect. An acronym marked as + used cannot be unmarked. + \command*{acro_mark_as_used:n}[ \marg{id}] + Explicitly use the acronym with the \acs{id} \meta{id}. This is the expl3 + macro applied to all entries in \cs{acuse}. + \expandable\command*{acro_if_acronym_used:n}[\TF\ \marg{id} \marg{true} + \marg{false}] + The code-level version of \cs{acifused}. This macro is expandable. + \command*{acro_for_all_acronyms_do:n}[ \marg{code}] + Loops over all acronyms known when the macro is used. Inside of + \meta{code} you can refer to the \acs{id} \meta{id} of an acronym with + \verbcode+#1+. + \command*{acro_barrier:} + The code-level version of \cs{acbarrier}. + \command*{acro_switch_off:} + The\sinceversion{2.6} expl3 version of \cs{acswitchoff}. + \command*{acro_switch_on:} + The\sinceversion{2.6} expl3 version of \cs{acswitchon}. + \command*{acro_add_action:n}[ \marg{code}] + Adds\sinceversion{2.7} code to \cs*{acro_get:n}. Inside of \meta{code} + you can refer to the \ac{id} of the acronym with \verbcode+#1+. + The \cs*{acro_get:n} command is called the first macro that is called by + \cs*{acro_use:n} which for example enables conditionals to test for + certain acronym properties. + \command*{acro_property_get:nn}[\TF\ \marg{id} \marg{property} \marg{true} + \marg{false}] + Fetches\changedversion{2.11} the property \meta{property} of the acronym + \meta{id} and stores it in a tokenlist variable + \cs*{l__acro_\meta{property}_tl} where all dashes in the property names + are replaced with underscores. \meta{true} is placed in the input stream + if the property had been set, \meta{false} otherwise. + \command*{acro_property_get:nn}[\marg{id} \marg{property}] + Like\changedversion{2.11} \cs*{acro_property_get:nn}\TF, but without the + \meta{true} and \meta{false} arguments. + \command*{acro_property_if_set:nn}[\TF\ \marg{id} \marg{property} \marg{true} + \marg{false}] + Checks\changedversion{2.11} if the property \meta{property} of the acronym + \meta{id} is set and places \meta{true} is in the input stream if yes and + \meta{false} otherwise. +\end{commands} + +\paragraph{Examples} +The usage of above macros is best explained with a few examples. The +following definition is done by \acro: +\begin{sourcecode} + \NewAcroCommand \ac { \acro_use:n {#1} } +\end{sourcecode} +An equivalent definition for \cs{ac} would be +\begin{sourcecode} + \NewDocumentCommand \ac {sm} + { + \acro_begin: + \acro_reset_specials: + \acro_check_and_mark_if:nn {#1} {#2} + \acro_use:n {#2} + \acro_end: + } +\end{sourcecode} +which should explain what the actual framework is which \cs{NewAcroCommand} +adds. + +Other definitions by \acro\ are for example the following ones: +\begin{sourcecode} + \NewAcroCommand \Ac + { + \acro_first_upper: + \acro_use:n {#1} + } + \NewAcroCommand \iac + { + \acro_indefinite: + \acro_use:n {#1} + } + \NewAcroCommand \acp + { + \acro_plural: + \acro_use:n {#1} + } + \NewAcroCommand \Acp + { + \acro_plural: + \acro_first_upper: + \acro_use:n {#1} + } + \NewAcroCommand \Aclp + { + \acro_plural: + \acro_first_upper: + \acro_long:n {#1} + } +\end{sourcecode} + +\section{About Plural Forms, Possessive Forms and Similar Constructs -- the + Concept of Endings}\label{sec:about-plural-forms} + +\acro\ has a concept of \emph{endings}. All of \acro's plural options are +defined by saying +\begin{sourcecode} + \ProvideAcroEnding {plural} {s} {s} +\end{sourcecode} +The command's syntax and what it does is as follows: +\begin{commands} + \command{ProvideAcroEnding}[\marg{name}\marg{short default}\marg{long default}] + This macro defines the options + \begin{itemize} + \item \option*{\meta{name}-ending}, + \item \option*{short-\meta{name}-ending}, + \item \option*{alt-\meta{name}-ending}, + \item \option*{long-\meta{name}-ending} and + \item \option*{foreign-\meta{name}-ending}. + \end{itemize} + It also defines the acronym properties + \begin{itemize} + \item \property*{short-\meta{name}}, + \item \property*{short-\meta{name}-form}, + \item \property*{alt-\meta{name}}, + \item \property*{alt-\meta{name}-form}, + \item \property*{long-\meta{name}}, + \item \property*{long-\meta{name}-form}, + \item \property*{foreign-\meta{name}} and + \item \property*{foreign-\meta{name}-form}. + \end{itemize} + Additionally it defines a setup macro as + described in section~\vref{sec:defining-own-acronym}, + \cs*{acro_\meta{name}:}. If \meta{name} contains a \code{-} (dash) it is + replaced by \code{\_} before \cs*{acro_\meta{name}:} is built. So if you + choose \code{my-name} the corresponding macro is named + \cs*{acro_my_name:}. If you use any other non-letters you are on your + own. \changedversion{2.4b}If you use the command with the same \meta{name} + a second time the command only resets the defaults. + + Note that you \emph{must use \cs{ProvideAcroEnding} before any acronym + definition}! +\end{commands} + +This could be used together with the macros described in +section~\vref{sec:defining-own-acronym} for adding support for possessive +forms: +\begin{example} + \ExplSyntaxOn + % this now only works because I've used the same already in the preamble so + % it does nothing here: + \ProvideAcroEnding {possessive} {'s} {'s} + + \ProvideAcroCommand \acg + { + \acro_possessive: + \acro_use:n {#1} + } + \ExplSyntaxOff + The \acg{cd} booklet says\ldots +\end{example} + +Please note that different endings are cumulative which you probably want to +avoid! Imagine a macro +\begin{sourcecode} + \NewAcroCommand \acgp + { + \acro_possessive: + \acro_plural: + \acro_use:n {#1} + } +\end{sourcecode} +This would give \enquote{\ac{cd}s's} instead of \enquote{\ac{cd}s'}. To solve +this you might want to consider +\begin{sourcecode} + \ProvideAcroEnding {possessive-singular} {'s} {'s} + \ProvideAcroEnding {possessive-plural} {s'} {s'} +\end{sourcecode} + +\section{More on Customization}\label{sec:more-custom} +\subsection{Background Information} +Several of \acro's objects are customized using templates. For each of these +objects it is possible to define own templates\footnote{This requires some +knowledge of \pkg{xtemplate} and expl3. Plans are to provide a documented +interface for users of \acro{} in the future.}. Possibly more interesting: it +is easily possible to define further instances of an object using a certain +template. How this works is explained in the following sections. However, the +basics are always the same. There is a command +\begin{commands} + \command*{DeclareAcro\meta{object + type}Style}[\marg{name}\marg{template}\marg{options}] + which allows to define a new style (\ie, instance) for the object + \meta{object type} using the template \marg{template}. +\end{commands} + +\subsection{Lists}\label{sec:lists} +\subsubsection{Own List Style} + +The different existing list styles are all built from four different +templates, \code{list}, \code{list-of}, \code{table} and \code{extra-table}. +Those templates are defined with the help of the \pkg{xtemplate} +package (from~\cite{bnd:l3packages}). Each of these templates has a few +options which are described in table~\vref{tab:list-templates}. New list +styles now are defined via the following macro: + +\begin{commands} + \command{DeclareAcroListStyle}[\marg{name}\marg{template}\marg{options}] + Declares a new \acro\ list style \meta{name}. \meta{name} will be the + value which can be chosen in the option \option{list-style}. + \meta{template} is the name of the template to be used by the style. + Available templates are listed in table~\ref{tab:list-templates}. + \meta{options} are the option settings for the corresponding template. +\end{commands} + +\begin{table} + \centering + \caption{Available List Templates and Their Options}\label{tab:list-templates} + \begin{tabular}{*{4}{>{\ttfamily}l}} + \toprule + \normalfont\bfseries Template & \normalfont\bfseries Option & + \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ + \midrule + list & list & tokenlist & description \\ + & foreign-sep & tokenlist & \cs*{space} \\ + & reverse & boolean & false \\ + & before & tokenlist \\ + & after & tokenlist \\ + \midrule + list-of & style & tokenlist & toc \\ + & foreign-sep & tokenlist & \cs*{space} \\ + & reverse & boolean & false \\ + & before & tokenlist \\ + & after & tokenlist \\ + \midrule + table & table & tokenlist & tabular \\ + & table-spec & tokenlist & lp\{.7\cs*{linewidth}\} \\ + & foreign-sep & tokenlist & \cs*{space} \\ + & reverse & boolean & false \\ + & before & tokenlist \\ + & after & tokenlist \\ + \midrule + extra-table & table & tokenlist & tabular \\ + & table-spec & tokenlist & llll \\ + & foreign-sep & tokenlist & \cs*{space} \\ + & reverse & boolean & false \\ + & before & tokenlist \\ + & after & tokenlist \\ + \bottomrule + \end{tabular} +\end{table} + +For defining new styles you need some information on what the different +templates and options do: +\begin{itemize} + \item The option \code{list} of the \code{list} template sets the list + environment. This must be a classic \LaTeX\ list where items are listed + with \cs*{item}. In those lists short entries will always be fed as + optional argument to \cs*{item}: \\ + \code{\cs*{item}[\meta{short}]\meta{long}\meta{extra}\meta{page}} + \item The template \code{list-of} simulates a table of contents or a list of + figures. This can be chosen by setting the option \code{style} to either + \code{toc} or \code{lof}. + \item The template \code{table} typesets the list in a table with two + columns: \\ + \code{\meta{short} \& \meta{long}\meta{extra}\meta{page} + \cs*{tabularnewline}} + \item The template \code{extra-table} typesets the list in a table with four + columns: \\ + \code{\meta{short} \& \meta{long} \& \meta{extra} \& \meta{page} + \cs*{tabularnewline}} + \item The option \code{foreign-sep} is the code inserted between long form + and foreign entry (if a foreign entry is present). + \item The options \code{before} and \code{after} are inserted directly + before and after the complete list. + \item The option \code{reverse} switches the place of \meta{long} with + \meta{extra}. + \item The option \code{table-spec} sets the column types for the table + templates. It must correspond to the number of columns the corresponding + template uses. +\end{itemize} + +As an example let's define a style \code{longtabu} which uses the corresponding +table environment from the package \pkg{tabu}~\cite{pkg:tabu}: + +\begin{sourcecode} + \usepackage{tabu,longtable} + \DeclareAcroListStyle{longtabu}{table}{ + table = longtabu , + table-spec = @{}>{\bfseries}lX@{} + } + \acsetup{list-style=longtabu} +\end{sourcecode} + +As another example let's define a new list with the help of the \pkg{enumitem} +package~\cite{pkg:enumitem}: + +\begin{sourcecode} + % preamble: + % \usepackage{enumitem} + \newlist{acronyms}{description}{1} + \newcommand*\addcolon[1]{#1:} + \setlist[acronyms]{ + labelwidth = 3em, + leftmargin = 3.5em, + noitemsep, + itemindent = 0pt, + font=\addcolon} + \DeclareAcroListStyle{mystyle}{list}{ list = acronyms } + \acsetup{ list-style = mystyle } +\end{sourcecode} +This would look as follows: +\newlist{acronyms}{description}{1} +\newcommand*\addcolon[1]{#1:} +\setlist[acronyms]{ + labelwidth=3em, + leftmargin=3.5em, + noitemsep, + itemindent=0pt, + font=\addcolon} +\DeclareAcroListStyle{mystyle}{list}{ list = acronyms } +\acsetup{list-style=mystyle,hyperref=false} +\printacronyms + +\subsubsection{Own List Heading Command} + +With the option \option{list-heading} you can choose which command prints the +heading of the list. If you need a different choice than what's already +provided you can use the following command to define a new option: +\begin{commands} + \command{DeclareAcroListHeading}[\marg{name}\marg{control sequence}] + Defines a new value \meta{name} for the option \option{list-heading}. + \meta{control sequence} must be a control sequence which takes one + mandatory argument. +\end{commands} +As an example here is how the value \code{section} is defined: +\begin{sourcecode} + \DeclareAcroListHeading{section}{\section} +\end{sourcecode} + +\subsection{First Styles} +The first styles define how an acronym is typeset when it is used for the +first time. It is set with the option \option{first-style}. Legal values for +this option are defined with the following command: +\begin{commands} + \command{DeclareAcroFirstStyle}[\marg{name}\marg{template}\marg{options}] + Declares a new \acro\ first style \meta{name}. \meta{name} will be the + value which can be chosen in the option \option{first-style}. + \meta{template} is the name of the template to be used by the style. + Available templates are listed in table~\ref{tab:first-templates}. + \meta{options} are the option settings for the corresponding template. +\end{commands} + +Here are two examples of the already available styles and how they are +defined: +\begin{sourcecode} + \DeclareAcroFirstStyle{short}{inline}{ + only-short = true , + brackets = false + } + \DeclareAcroFirstStyle{sidenote-reversed}{note}{ + note-command = \sidenote{#1} , + reversed = true + } +\end{sourcecode} + +\begin{table}[!h] + \centering + \caption{Available First Style Templates and Their Options}\label{tab:first-templates} + \begin{tabular}{*{4}{>{\ttfamily}l}} + \toprule + \normalfont\bfseries Template & \normalfont\bfseries Option & + \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ + \midrule + inline & brackets & boolean & true \\ + & brackets-type & tokenlist & () \\ + & only-short & boolean & false \\ + & only-long & boolean & false \\ + & reversed & boolean & false \\ + & between & tokenlist \\ + & foreign-sep & tokenlist & ,\textasciitilde \\ + \midrule + note & use-note & boolean & true \\ + & note-command & function & \cs*{footnote}\Marg{\#1} \\ + & reversed & boolean & false \\ + & foreign-sep & tokenlist & ,\textasciitilde \\ + \bottomrule + \end{tabular} +\end{table} + +\subsection{Extra Styles} +The extra styles define how the extra information of an acronym is typeset in +the list. It is set with the option \option{extra-style}. Legal values for +this option are defined with the following command: +\begin{commands} + \command{DeclareAcroExtraStyle}[\marg{name}\marg{template}\marg{options}] + Declares a new \acro\ extra style \meta{name}. \meta{name} will be the + value which can be chosen in the option \option{extra-style}. + \meta{template} is the name of the template to be used by the style. + Available templates are listed in table~\ref{tab:extra-templates}. + \meta{options} are the option settings for the corresponding template. +\end{commands} + +Here are two examples of the already available styles and how they are +defined: +\begin{sourcecode} + \DeclareAcroExtraStyle{default}{inline}{ + brackets = false , + punct = true , + punct-symbol = . + } + \DeclareAcroExtraStyle{paren}{inline}{ + brackets = true , + punct = true , + punct-symbol = + } +\end{sourcecode} + +\begin{table} + \centering + \caption{Available Extra Style Templates and Their Options}\label{tab:extra-templates} + \begin{tabular}{*{4}{>{\ttfamily}l}} + \toprule + \normalfont\bfseries Template & \normalfont\bfseries Option & + \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ + \midrule + inline & punct & boolean & true \\ + & punct-symbol & tokenlist & , \\ + & brackets & boolean & true \\ + & brackets-type & tokenlist & () \\ + \bottomrule + \end{tabular} +\end{table} + +\subsection{Page Number Styles} +The page number styles define how the page numbers where acronyms have been +used are typeset in the list. It is set with the option \option{page-style}. +Legal values for this option are defined with the following command: +\begin{commands} + \command{DeclareAcroPageStyle}[\marg{name}\marg{template}\marg{options}] + Declares a new \acro\ extra style \meta{name}. \meta{name} will be the + value which can be chosen in the option \option{page-style}. + \meta{template} is the name of the template to be used by the style. + Available templates are listed in table~\ref{tab:page-templates}. + \meta{options} are the option settings for the corresponding template. +\end{commands} + +Here are two examples of the already available styles and how they are +defined: +\begin{sourcecode} + \DeclareAcroPageStyle{default}{inline}{ + punct = true , + punct-symbol = . + } + \DeclareAcroPageStyle{paren}{inline}{ + brackets=true , + punct-symbol = ~ + } +\end{sourcecode} + +\begin{table} + \centering + \caption{Available Page Number Style Templates and Their + Options}\label{tab:page-templates} + \begin{tabular}{*{3}{>{\ttfamily}l}>{\ttfamily}p{.25\linewidth}} + \toprule + \normalfont\bfseries Template & \normalfont\bfseries Option & + \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ + \midrule + inline & display & boolean & true \\ + & punct & boolean & false \\ + & punct-symbol & tokenlist & , \\ + & brackets & boolean & false \\ + & brackets-type & tokenlist & () \\ + & space & skip & .333333em plus .166666em minus + .111111em \\ + \bottomrule + \end{tabular} +\end{table} + +\subsection{Configuration Files} +If\sinceversion{2.2} you repeatedly have the same setup and definitions for +\acro\ in your preamble\footnote{For example defining new endings, \acro{} + commands, list styles, \ldots} you might want to place those in a +configuration file. If \acro\ finds a file named \code{acro.cfg} present it +inputs it at the end of the package. The only thing to be aware of is that +this file is input like a package which means that \code{@} is treated as a +letter (category code~11). + +\appendix + +\acsetup{ + list-style = description , + list-heading = section , + list-name = All Acronyms Used in this Documentation , + page-style = comma , + following-pages* = true , + extra-style = comma +} + +\printacronyms + +\printbibliography + +\end{document} diff --git a/macros/latex/contrib/acro/acro.definitions.tex b/macros/latex/contrib/acro/acro.definitions.tex new file mode 100644 index 0000000000..61c781a269 --- /dev/null +++ b/macros/latex/contrib/acro/acro.definitions.tex @@ -0,0 +1,574 @@ +% -------------------------------------------------------------------------- +% the ACRO package +% +% Typeset Acronyms +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://bitbucket.org/cgnieder/acro/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2011--2020 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +% The acro package consists of the files +% - acro.sty, acro.definitions.tex, acro.cfg +% - acro-manual.tex, acro-manual.pdf, acro-manual.cls +% - acro.history, README +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +\ExplSyntaxOn + +% document commands: +\NewDocumentCommand \DeclareAcronym {mm} + { \acro_declare_acronym:nn {#1} {#2} } + +\NewDocumentCommand \acsetup { m } + { + \tl_if_blank:nF {#1} + { \keys_set:nn {acro} {#1} } + \ignorespaces + } + +\NewDocumentCommand \ProvideAcroEnding {mmm} + { \acro_provide_ending:nnn {#1} {#2} {#3} } + +\NewDocumentCommand \AcroRegisterTrailing {mm} + { \acro_register_trailing_token:Nn #1 {#2} } + +\NewDocumentCommand \DeclareAcroTranslation {mm} + { \acro_declare_translation:nn {#1} {#2} } + +\DeclareExpandableDocumentCommand \acifused { m } + { \acro_if_acronym_used:nTF {#1} } + +\NewDocumentCommand \acresetall {} + { \acro_reset_all: } + +\NewDocumentCommand \acuseall {} + { \acro_mark_all_as_used: } + +\NewDocumentCommand \acreset { > { \SplitList {,} } m } + { \ProcessList {#1} { \acro_reset:n } \ignorespaces } + +\NewDocumentCommand \acuse { > { \SplitList {,} } m } + { \ProcessList {#1} { \acro_mark_as_used:n } \ignorespaces } + +\NewDocumentCommand \acfirstupper {m} + { \acro_first_upper_case:n {#1} } + +\NewExpandableDocumentCommand \aciffirst {+m+m} + { \bool_if:NTF \l__acro_first_instance_bool {#1} {#2} } + +\NewDocumentCommand \acdot {} { \acro_dot: } +\NewDocumentCommand \acspace {} { \acro_space: } + +\NewDocumentCommand \acbarrier {} + { \acro_barrier: } + +\NewDocumentCommand \acswitchoff {} + { \acro_switch_off: } + +\NewDocumentCommand \acswitchon {} + { \acro_switch_on: } + +\NewDocumentCommand \printacronyms { O{} } + { \acro_print_acronyms:n {#1} } + +% -------------------------------------------------------------------------- +% styles +% #1: name +% #2: template +% #3: settings +\NewDocumentCommand \DeclareAcroFirstStyle {mmm} + { \acro_declare_first_style:nnn {#1} {#2} {#3} } + +\NewDocumentCommand \DeclareAcroExtraStyle {mmm} + { \acro_declare_extra_style:nnn {#1} {#2} {#3} } + +\NewDocumentCommand \DeclareAcroPageStyle {mmm} + { \acro_declare_page_style:nnn {#1} {#2} {#3} } + +\NewDocumentCommand \DeclareAcroListHeading {mm} + { \acro_declare_list_heading:nn {#1} {#2} } + +\NewDocumentCommand \DeclareAcroListStyle {mmm} + { \acro_declare_list_style:nnn {#1} {#2} {#3} } + +% -------------------------------------------------------------------------- +% endings: +\ProvideAcroEnding {plural} {s} {s} + +% -------------------------------------------------------------------------- +% use acronyms: +% automatic: +\NewAcroCommand \ac + { \acro_use:n {#1} } + +\NewAcroCommand \Ac + { + \acro_first_upper: + \acro_use:n {#1} + } + +\NewAcroCommand \iac + { + \acro_indefinite: + \acro_use:n {#1} + } + +\NewAcroCommand \Iac + { + \acro_first_upper: + \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 \acsingle + { + \acro_get:n {#1} + \acro_single:n {#1} + } + +\NewAcroCommand \acpsingle + { + \acro_get:n {#1} + \acro_plural: + \acro_single:n {#1} + } + +\NewAcroCommand \Acsingle + { + \acro_get:n {#1} + \acro_first_upper: + \acro_single:n {#1} + } + +\NewAcroCommand \Acpsingle + { + \acro_get:n {#1} + \acro_first_upper: + \acro_plural: + \acro_single:n {#1} + } + +% short: +\NewAcroCommand \acs + { \acro_short:n {#1} } + +\NewAcroCommand \Acs + { + \acro_first_upper: + \acro_short:n {#1} + } + +\NewAcroCommand \iacs + { + \acro_indefinite: + \acro_short:n {#1} + } + +\NewAcroCommand \Iacs + { + \acro_first_upper: + \acro_indefinite: + \acro_short:n {#1} + } + +\NewAcroCommand \acsp + { + \acro_plural: + \acro_short:n {#1} + } + +\NewAcroCommand \Acsp + { + \acro_first_upper: + \acro_plural: + \acro_short:n {#1} + } + +% alt: +\NewAcroCommand \aca + { \acro_alt:n {#1} } + +\NewAcroCommand \Aca + { + \acro_first_upper: + \acro_alt:n {#1} + } + +\NewAcroCommand \iaca + { + \acro_indefinite: + \acro_alt:n {#1} + } + +\NewAcroCommand \Iaca + { + \acro_first_upper: + \acro_indefinite: + \acro_alt:n {#1} + } + +\NewAcroCommand \acap + { + \acro_plural: + \acro_alt:n {#1} + } + +\NewAcroCommand \Acap + { + \acro_first_upper: + \acro_plural: + \acro_alt:n {#1} + } + +% long: +\NewAcroCommand \acl + { \acro_long:n {#1} } + +\NewAcroCommand \Acl + { + \acro_first_upper: + \acro_long:n {#1} + } + +\NewAcroCommand \iacl + { + \acro_indefinite: + \acro_long:n {#1} + } + +\NewAcroCommand \Iacl + { + \acro_first_upper: + \acro_indefinite: + \acro_long:n {#1} + } + +\NewAcroCommand \aclp + { + \acro_plural: + \acro_long:n {#1} + } + +\NewAcroCommand \Aclp + { + \acro_plural: + \acro_first_upper: + \acro_long:n {#1} + } + +% first: +\NewAcroCommand \acf + { \acro_first:n {#1} } + +\NewAcroCommand \Acf + { + \acro_first_upper: + \acro_first:n {#1} + } + +\NewAcroCommand \iacf + { + \acro_indefinite: + \acro_first:n {#1} + } + +\NewAcroCommand \Iacf + { + \acro_first_upper: + \acro_indefinite: + \acro_first:n {#1} + } + +\NewAcroCommand \acfp + { + \acro_plural: + \acro_first:n {#1} + } + +\NewAcroCommand \Acfp + { + \acro_plural: + \acro_first_upper: + \acro_first:n {#1} + } + +% first-like: +\NewPseudoAcroCommand \acflike + { \acro_first_like:nn {#1} {#2} } + +\NewPseudoAcroCommand \iacflike + { + \acro_indefinite: + \acro_first_like:nn {#1} {#2} + } + +\NewPseudoAcroCommand \Iacflike + { + \acro_first_upper: + \acro_indefinite: + \acro_first_like:nn {#1} {#2} + } + +\NewPseudoAcroCommand \acfplike + { + \acro_plural: + \acro_first_like:nn {#1} {#2} + } + +% -------------------------------------------------------------------------- +% first appearance styles: +\DeclareAcroFirstStyle {default} {inline} + { } + +\DeclareAcroFirstStyle {reversed} {inline} + { reversed = true } + +\DeclareAcroFirstStyle {short} {inline} + { + only-short = true , + brackets = false + } + +\DeclareAcroFirstStyle {long} {inline} + { + only-long = true , + brackets = false + } + +\DeclareAcroFirstStyle {square} {inline} + { brackets-type = [] } + +\DeclareAcroFirstStyle {plain} {inline} + { + brackets = false , + between = -- + } + +\DeclareAcroFirstStyle {plain-reversed} {inline} + { + brackets = false , + between = -- , + reversed = true + } + +\DeclareAcroFirstStyle {footnote} {note} + { } + +\DeclareAcroFirstStyle {footnote-reversed} {note} + { reversed = true } + +\DeclareAcroFirstStyle {sidenote} {note} + { note-command = \sidenote {#1} } + +\DeclareAcroFirstStyle {sidenote-reversed} {note} + { + note-command = \sidenote {#1} , + reversed = true + } + +\DeclareAcroFirstStyle {empty} {note} + { use-note = false } + +% -------------------------------------------------------------------------- +% extra info appearance styles: +\DeclareAcroExtraStyle {default} {inline} + { + brackets = false , + punct = true , + punct-symbol = . + } + +\DeclareAcroExtraStyle {plain} {inline} + { + brackets = false , + punct = true , + punct-symbol = + } + +\DeclareAcroExtraStyle {paren} {inline} + { + brackets = true , + punct = true , + punct-symbol = + } + +\DeclareAcroExtraStyle {bracket} {inline} + { + brackets = true , + punct = true , + punct-symbol = , + brackets-type = [] + } + +\DeclareAcroExtraStyle {comma} {inline} + { + punct = true, + punct-symbol = {,} , + brackets = false + } + +% -------------------------------------------------------------------------- +% page number appearance styles: +\DeclareAcroPageStyle {default} {inline} + { + punct = true , + punct-symbol = . + } + +\DeclareAcroPageStyle {plain} {inline} + { punct = false } + +\DeclareAcroPageStyle {comma} {inline} + { punct = true } + +\DeclareAcroPageStyle {paren} {inline} + { + brackets=true , + punct-symbol = ~ + } + +\DeclareAcroPageStyle {none} {inline} + { display = false } + +% -------------------------------------------------------------------------- +% list heading styles: +\DeclareAcroListHeading {part} {\part} +\DeclareAcroListHeading {part*} {\part*} +\DeclareAcroListHeading {chapter} {\chapter} +\DeclareAcroListHeading {chapter*} {\chapter*} +\DeclareAcroListHeading {addchap} {\addchap} +\DeclareAcroListHeading {section} {\section} +\DeclareAcroListHeading {section*} {\section*} +\DeclareAcroListHeading {addsec} {\addsec} +\DeclareAcroListHeading {subsection} {\subsection} +\DeclareAcroListHeading {subsection*} {\subsection*} +\DeclareAcroListHeading {subsubsection} {\subsubsection} +\DeclareAcroListHeading {subsubsection*} {\subsubsection*} +\DeclareAcroListHeading {none} {\use_none:n} + +% -------------------------------------------------------------------------- +% list styles: +\DeclareAcroListStyle {description} {list} + { } + +\DeclareAcroListStyle {toc} {list-of} + { } + +\DeclareAcroListStyle {lof} {list-of} + { style = lof } + +\DeclareAcroListStyle {tabular} {table} + { table = tabular } + +\DeclareAcroListStyle {longtable} {table} + { table = longtable } + +\DeclareAcroListStyle {extra-tabular} {extra-table} + { table = tabular } + +\DeclareAcroListStyle {extra-longtable} {extra-table} + { table = longtable } + +\DeclareAcroListStyle {extra-tabular-rev} {extra-table} + { + table = tabular , + reverse = true + } + +\DeclareAcroListStyle {extra-longtable-rev} {extra-table} + { + table = longtable , + reverse = true + } + +% -------------------------------------------------------------------------- +% register some tokens to be checked for: +\AcroRegisterTrailing . {dot} +\AcroRegisterTrailing - {dash} +\AcroRegisterTrailing \babelhyphen {babel-hyphen} + +\acsetup { activate-trailing-tokens = dot } + +% -------------------------------------------------------------------------- +% translations: +% list name +\DeclareAcroTranslation {acronym-list-name} + { + Fallback = Acronyms , + English = Acronyms , + French = Acronymes , + German = Abk\"urzungen , + Italian = Acronimi , + Portuguese = Acr\'onimos , + Spanish = Siglas , + Catalan = Sigles , + Turkish = K\i saltmalar + } + +% page name +\DeclareAcroTranslation {acronym-page-name} + { + Fallback = p. , + English = p. , + German = S. , + Portuguese = p. + } + +% pages name +\DeclareAcroTranslation {acronym-pages-name} + { + Fallback = pp. , + English = pp. , + German = S. , + Portuguese = pp. + } + +% following page +\DeclareAcroTranslation {acronym-next-page} + { + Fallback = f. , + English = f. , + German = f. , + Portuguese = s. + } + +% following pages +\DeclareAcroTranslation {acronym-next-pages} + { + Fallback = ff. , + English = ff. , + German = ff. , + Portuguese = ss. + } + +\file_input_stop: diff --git a/macros/latex/contrib/acro/acro.history b/macros/latex/contrib/acro/acro.history index b20f53427a..d6aa883d6d 100644 --- a/macros/latex/contrib/acro/acro.history +++ b/macros/latex/contrib/acro/acro.history @@ -1,33 +1,35 @@ -% -------------------------------------------------------------------------- -% the ACRO package -% -% Typeset Acronyms -% -% -------------------------------------------------------------------------- -% Clemens Niederberger -% Web: https://bitbucket.org/cgnieder/acro/ -% E-Mail: contact@mychemistry.eu -% -------------------------------------------------------------------------- -% Copyright 2011--2019 Clemens Niederberger -% -% This work may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.3 -% of this license or (at your option) any later version. -% The latest version of this license is in -% http://www.latex-project.org/lppl.txt -% and version 1.3 or later is part of all distributions of LaTeX -% version 2005/12/01 or later. -% -% This work has the LPPL maintenance status `maintained'. -% -% The Current Maintainer of this work is Clemens Niederberger. -% -------------------------------------------------------------------------- -% The acro package consists of the files -% - acro.sty, acro_en.tex, acro_en.pdf, README -% -------------------------------------------------------------------------- -% If you have any ideas, questions, suggestions or bugs to report, please -% feel free to contact me. -% -------------------------------------------------------------------------- +-------------------------------------------------------------------------- +the ACRO package + + Typeset Acronyms + +-------------------------------------------------------------------------- +Clemens Niederberger +Web: https://bitbucket.org/cgnieder/acro/ +E-Mail: contact@mychemistry.eu +-------------------------------------------------------------------------- +Copyright 2011--2020 Clemens Niederberger + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is Clemens Niederberger. +-------------------------------------------------------------------------- +The acro package consists of the files +- acro.sty, acro.definitions.tex, acro.cfg +- acro-manual.tex, acro-manual.pdf, acro-manual.cls +- acro.history, README +-------------------------------------------------------------------------- +If you have any ideas, questions, suggestions or bugs to report, please +feel free to contact me. +-------------------------------------------------------------------------- 2012/06/22 v0.1 - first public release 2012/06/23 v0.1a - bug fix, added `strict' and `macros' option and creation of shortcut macros @@ -270,3 +272,11 @@ 2019/12/30 v2.10d - fix issue #76 - fix issue #141 - fix issue #143 +2020/01/11 v2.11 - new commands \acpsingle and \Acpsingle + - fix issues with optional arguments of the `cite' property + - new properties `before-citation' and `after-citation' + - new options `config-file-name' and `config-file-extension' + - new option `case-sensitive' + - rename the manual file and use a dedicated class for the + manual + - prefer lazy boolean evaluation when possible diff --git a/macros/latex/contrib/acro/acro.sty b/macros/latex/contrib/acro/acro.sty index 03d0121d5f..98425268c1 100644 --- a/macros/latex/contrib/acro/acro.sty +++ b/macros/latex/contrib/acro/acro.sty @@ -8,7 +8,7 @@ % Web: https://bitbucket.org/cgnieder/acro/ % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2011--2019 Clemens Niederberger +% Copyright 2011--2020 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -23,17 +23,39 @@ % The Current Maintainer of this work is Clemens Niederberger. % -------------------------------------------------------------------------- % The acro package consists of the files -% - acro.sty, acro_en.tex, acro_en.pdf, acro.history, README +% - acro.sty, acro.definitions.tex, acro.cfg +% - acro-manual.tex, acro-manual.pdf, acro-manual.cls +% - acro.history, README % -------------------------------------------------------------------------- % If you have any ideas, questions, suggestions or bugs to report, please % feel free to contact me. % -------------------------------------------------------------------------- -\RequirePackage{expl3,xparse,l3keys2e,xtemplate,etoolbox} +\RequirePackage{expl3,xparse,xtemplate,l3keys2e} +\RequirePackage{etoolbox} % for the document hooks + +\ExplSyntaxOn + +\tl_const:Nn \c_acro_date_tl {2020/01/11} +\tl_const:Nn \c_acro_version_major_number_tl {2} +\tl_const:Nn \c_acro_version_minor_number_tl {11} +\tl_const:Nn \c_acro_version_subrelease_tl {} +\tl_const:Nx \c_acro_version_number_tl + { + \c_acro_version_major_number_tl . + \c_acro_version_minor_number_tl + } +\tl_const:Nx \c_acro_version_tl + { + \c_acro_version_number_tl + \c_acro_version_subrelease_tl + } +\tl_const:Nn \c_acro_info_tl {Typeset~ Acronyms} + \ProvidesExplPackage {acro} - {2019/12/30} - {2.10d} - {Typeset Acronyms} + {\c_acro_date_tl} + {\c_acro_version_tl} + {\c_acro_info_tl} % -------------------------------------------------------------------------- % warning and error messages: @@ -107,6 +129,195 @@ package!~ Please~ check~ your~ installation. } +% -------------------------------------------------------------------------- +% temporary variables +\tl_new:N \l__acro_tmpa_tl +\tl_new:N \l__acro_tmpb_tl +\tl_new:N \l__acro_tmpc_tl +\prop_new:N \l__acro_tmpa_prop +\prop_new:N \l__acro_tmpb_prop +\seq_new:N \l__acro_tmpa_seq +\seq_new:N \l__acro_tmpb_seq +\int_new:N \l__acro_tmpa_int +\int_new:N \l__acro_tmpb_int +\int_new:N \l__acro_tmpc_int +\int_new:N \l__acro_tmpd_int + +% -------------------------------------------------------------------------- +% variants of kernel commands +\cs_generate_variant:Nn \quark_if_no_value:nTF {V} +\cs_generate_variant:Nn \tl_put_right:Nn {NV,Nv} +\cs_generate_variant:Nn \tl_if_eq:nnT {V} +\cs_generate_variant:Nn \tl_if_eq:nnF {V} +\cs_generate_variant:Nn \seq_use:Nnnn {c} +\cs_generate_variant:Nn \seq_gset_split:Nnn {c} +\cs_generate_variant:Nn \seq_set_split:Nnn {NnV} +\cs_generate_variant:Nn \seq_if_in:NnT {NV} +\cs_generate_variant:Nn \seq_if_in:NnTF {Ne} +\cs_generate_variant:Nn \prop_put:Nnn {NnV,cnx,cnv} +\cs_generate_variant:Nn \prop_get:NnNTF {cnc} +\cs_generate_variant:Nn \prop_get:NnNF {cn,cnc} +\cs_generate_variant:Nn \prop_get:NnN {cnc} +\cs_generate_variant:Nn \cs_generate_variant:Nn {c} +\cs_generate_variant:Nn \str_case:nn {V} + +% -------------------------------------------------------------------------- +% variables: +\bool_new:N \l__acro_acc_supp_bool +\bool_new:N \l__acro_addto_index_bool +\bool_new:N \l__acro_capitalize_list_bool +\bool_new:N \g__acro_case_sensitive_bool +\bool_new:N \l__acro_citation_all_bool +\bool_new:N \l__acro_citation_first_bool +\bool_set_true:N \l__acro_citation_first_bool +\bool_new:N \l__acro_create_macros_bool +\bool_new:N \l__acro_custom_alt_format_bool +\bool_new:N \l__acro_custom_long_format_bool +\bool_new:N \l__acro_custom_short_format_bool +\bool_new:N \l__acro_extra_punct_bool +\bool_new:N \l__acro_extra_use_brackets_bool +\bool_new:N \g__acro_first_acronym_declared_bool +\bool_new:N \l__acro_first_instance_bool +\bool_new:N \l__acro_first_only_short_bool +\bool_new:N \l__acro_first_only_long_bool +\bool_new:N \l__acro_first_reversed_bool +\bool_new:N \l__acro_first_switched_bool +\bool_new:N \l__acro_first_use_brackets_bool +\bool_new:N \l__acro_first_upper_bool +\bool_new:N \l__acro_following_page_bool +\bool_new:N \l__acro_following_pages_bool +\bool_new:N \l__acro_foreign_bool +\bool_set_true:N \l__acro_foreign_bool +\bool_new:N \l__acro_group_citation_bool +\bool_new:N \l__acro_hyperref_loaded_bool +\bool_new:N \l__acro_hyperref_use_bool +\bool_new:N \l__acro_include_endings_format_bool +\bool_new:N \l__acro_indefinite_bool +\bool_new:N \l__acro_in_list_bool +\bool_new:N \l__acro_is_included_bool +\bool_new:N \l__acro_is_excluded_bool +\bool_new:N \l__acro_list_all_pages_bool +\bool_set_true:N \l__acro_list_all_pages_bool +\bool_new:N \l__acro_list_reverse_long_extra_bool +\bool_new:N \l__acro_log_acronyms_bool +\bool_new:N \l__acro_log_acronyms_verbose_bool +\bool_new:N \l__acro_mark_as_used_bool +\bool_new:N \g__acro_mark_first_as_used_bool +\bool_new:N \l__acro_override_list_format_bool +\bool_new:N \l__acro_page_brackets_bool +\bool_new:N \l__acro_page_display_bool +\bool_new:N \l__acro_page_punct_bool +\bool_new:N \l__acro_place_label_bool +\bool_new:N \l__acro_print_only_used_bool +\bool_set_true:N \l__acro_print_only_used_bool +\bool_new:N \g__acro_rerun_bool +\bool_new:N \g__acro_reset_at_barrier_bool +\bool_new:N \l__acro_silence_bool +\bool_new:N \l__acro_single_use_bool +\bool_new:N \l__acro_sort_bool +\bool_set_true:N \l__acro_sort_bool +\bool_new:N \l__acro_strict_bool +\bool_new:N \l__acro_trailing_tokens_bool +\bool_new:N \l__acro_tooltip_bool +\bool_new:N \l__acro_tooltip_inside_bool +\bool_new:N \l__acro_upper_indefinite_bool +\bool_new:N \l__acro_upper_short_bool +\bool_new:N \l__acro_use_acronyms_bool +\bool_set_true:N \l__acro_use_acronyms_bool +\bool_new:N \l__acro_use_barrier_bool +\bool_new:N \g__acro_use_barriers_bool +\bool_new:N \l__acro_use_ending_form_bool +\bool_new:N \l__acro_use_note_bool +\bool_new:N \l__acro_xspace_bool + +\str_new:N \l__acro_current_id_str + +\tl_new:N \l__acro_list_entries_tl +\tl_new:N \l__acro_endings_tl +\tl_new:N \l__acro_trailing_tokens_tl +\tl_new:N \l__acro_included_classes_tl +\tl_new:N \l__acro_excluded_classes_tl +\tl_new:N \l__acro_ignore_tl +\tl_new:N \l__acro_default_indefinite_tl +\tl_set:Nn \l__acro_default_indefinite_tl {a} +\tl_new:N \l__acro_foreign_sep_tl +\tl_new:N \l__acro_extra_instance_tl +\tl_set:Nn \l__acro_extra_instance_tl {default} +\tl_new:N \l__acro_page_instance_tl +\tl_set:Nn \l__acro_page_instance_tl {none} +\tl_new:N \l__acro_page_name_tl +\tl_new:N \l__acro_pages_name_tl +\tl_new:N \l__acro_next_page_tl +\tl_new:N \l__acro_next_pages_tl +\tl_new:N \l__acro_list_instance_tl +\tl_set:Nn \l__acro_list_instance_tl {description} +\tl_new:N \l__acro_list_type_tl +\tl_new:N \l__acro_list_heading_cmd_tl +\tl_set:Nn \l__acro_list_heading_cmd_tl {section*} +\tl_new:N \l__acro_list_name_tl +\tl_new:N \l__acro_list_before_tl +\tl_new:N \l__acro_list_after_tl +\tl_new:N \l__acro_custom_short_format_tl +\tl_new:N \l__acro_first_between_tl +\tl_new:N \l__acro_citation_connect_tl +\tl_new:N \l__acro_between_group_connect_citation_tl +\tl_new:N \l__acro_extra_brackets_tl +\tl_new:N \l__acro_extra_punct_tl +\tl_new:N \l__acro_first_brackets_tl +\tl_new:N \l__acro_page_punct_tl +\tl_new:N \l__acro_page_brackets_tl +\tl_new:N \l__acro_last_page_tl +\tl_new:N \l__acro_current_page_tl +\tl_new:N \l__acro_list_table_tl +\tl_new:N \l__acro_list_table_spec_tl +\tl_new:N \l__acro_acc_supp_tl +\tl_new:N \l__acro_acc_supp_options_tl +\tl_new:N \l__acro_label_prefix_tl +\tl_set:Nn \l__acro_label_prefix_tl {ac:} +\tl_new:N \l__acro_index_short_tl +\tl_new:N \l__acro_first_instance_tl +\tl_set:Nn \l__acro_first_instance_tl {default} +\tl_new:N \l__acro_short_tl +\tl_new:N \l__acro_short_format_tl +\tl_new:N \l__acro_list_short_format_tl +\tl_new:N \l__acro_alt_tl +\tl_new:N \l__acro_alt_format_tl +\tl_new:N \l__acro_long_tl +\tl_new:N \l__acro_long_format_tl +\tl_new:N \l__acro_list_long_format_tl +\tl_new:N \l__acro_single_form_tl +\tl_set:Nn \l__acro_single_form_tl {long} +\tl_new:N \l__acro_extra_format_tl +\tl_new:N \l__acro_foreign_format_tl +\tl_new:N \l__acro_foreign_list_format_tl +\tl_set:Nn \l__acro_foreign_list_format_tl { \acroenparen } +\tl_new:N \l__acro_index_format_tl + +\skip_new:N \l__acro_page_space_skip + +\dim_new:N \l__acro_short_width_dim +\dim_set:Nn \l__acro_short_width_dim {3em} + +\int_new:N \g__acro_barrier_int + +\seq_new:N \l__acro_endings_seq +\seq_new:N \l__acro_actions_seq +\seq_new:N \g__acro_declared_acronyms_seq + +\prop_new:N \l__acro_citation_prop +\prop_new:N \l__acro_citation_pre_prop +\prop_new:N \l__acro_citation_post_prop +\prop_new:N \l__acro_pdfstring_alt_prop +\prop_new:N \l__acro_pdfstring_short_prop +\prop_new:N \g__acro_properties_prop +\prop_new:N \l__acro_trailing_tokens_prop +\prop_new:N \l__acro_trailing_actions_prop +\prop_new:N \l__acro_list_styles_prop +\prop_new:N \l__acro_list_headings_prop +\prop_new:N \l__acro_first_styles_prop +\prop_new:N \l__acro_extra_styles_prop +\prop_new:N \l__acro_page_styles_prop + % -------------------------------------------------------------------------- % logging: \prg_new_conditional:Npnn \acro_if_log: {p,T,F,TF} @@ -116,9 +327,6 @@ { \prg_return_false: } } -\bool_new:N \l__acro_log_acronyms_bool -\bool_new:N \l__acro_log_acronyms_verbose_bool - \keys_define:nn {acro} { log .choice: , @@ -138,7 +346,7 @@ \cs_new:Npn \__acro_write_log:nn #1#2 { \ \ \ #1 ~ = ~ {#2} } \cs_new:Npn \__acro_write_log_property:nnn #1#2#3 - { \__acro_write_log:nn {#2} { \__acro_get_property:nn {#3} {#1} } } + { \__acro_write_log:nn {#2} { \__acro_property_get:nn {#3} {#1} } } \cs_new:Npn \__acro_ending_log_entry:nn #1#2 { @@ -159,10 +367,10 @@ | ~ \msg_info_text:n {acro}~ --~ defining~ new~ acronym: \\ | \__acro_write_log:nn {ID} {#1} \\ | \__acro_write_log_property:nnn {#1} {short} {short} \\ - | \__acro_write_log_property:nnn {#1}{long} {long} \\ - | \__acro_write_log_property:nnn {#1}{alt} {alt} \\ - | \__acro_write_log_property:nnn {#1}{sort} {sort} \\ - | \__acro_write_log_property:nnn {#1}{class} {class} \\ + | \__acro_write_log_property:nnn {#1} {long} {long} \\ + | \__acro_write_log_property:nnn {#1} {alt} {alt} \\ + | \__acro_write_log_property:nnn {#1} {sort} {sort} \\ + | \__acro_write_log_property:nnn {#1} {class} {class} \\ | \__acro_write_log_property:nnn {#1} {list} {list} \\ | \__acro_write_log_property:nnn {#1} {extra} {extra} \\ | \__acro_write_log_property:nnn {#1} {foreign} {foreign} \\ @@ -183,6 +391,8 @@ | \__acro_write_log_property:nnn {#1} {foreign-lang} {foreign_lang} \\ | \\ | \__acro_write_log_property:nnn {#1} {cite} {citation} \\ + | \__acro_write_log_property:nnn {#1} {before-citation} {before_citation} \\ + | \__acro_write_log_property:nnn {#1} {after-citation} {after_citation} \\ | \__acro_write_log_property:nnn {#1} {index} {index} \\ | \__acro_write_log_property:nnn {#1} {index-sort} {index_sort} \\ | \\ @@ -207,7 +417,6 @@ | \__acro_write_log_property:nnn {#1} {list} {list} \\ | \__acro_write_log_property:nnn {#1} {extra} {extra} \\ | \__acro_write_log_property:nnn {#1} {foreign} {foreign} \\ - | \__acro_write_log_property:nnn {#1} {pdfstring} {pdfstring} \\ | \__acro_write_log_property:nnn {#1} {cite} {citation} \\ ================================================= } @@ -273,172 +482,6 @@ } } -% -------------------------------------------------------------------------- -% temporary variables -\tl_new:N \l__acro_tmpa_tl -\tl_new:N \l__acro_tmpb_tl -\tl_new:N \l__acro_tmpc_tl -\prop_new:N \l__acro_tmpa_prop -\prop_new:N \l__acro_tmpb_prop -\seq_new:N \l__acro_tmpa_seq -\seq_new:N \l__acro_tmpb_seq -\int_new:N \l__acro_tmpa_int -\int_new:N \l__acro_tmpb_int -\int_new:N \l__acro_tmpc_int -\int_new:N \l__acro_tmpd_int - -% -------------------------------------------------------------------------- -% variants of kernel commands -\cs_generate_variant:Nn \quark_if_no_value:nTF { V } -\cs_generate_variant:Nn \tl_put_right:Nn { NV, Nv } -\cs_generate_variant:Nn \tl_if_eq:nnT { V } -\cs_generate_variant:Nn \tl_if_eq:nnF { V } -\cs_generate_variant:Nn \seq_use:Nnnn { c } -\cs_generate_variant:Nn \seq_gset_split:Nnn { c } -\cs_generate_variant:Nn \seq_set_split:Nnn { NnV } -\cs_generate_variant:Nn \seq_if_in:NnT { NV } -\cs_generate_variant:Nn \prop_put:Nnn { NnV, cnx, cnv } -\cs_generate_variant:Nn \prop_get:NnNTF { cnc } -\cs_generate_variant:Nn \prop_get:NnNF { cn, cnc } -\cs_generate_variant:Nn \prop_get:NnN { cnc } -\cs_generate_variant:Nn \cs_generate_variant:Nn { c } -\cs_generate_variant:Nn \str_case:nn { V } - -% -------------------------------------------------------------------------- -% variables: -\bool_new:N \l__acro_silence_bool -\bool_new:N \l__acro_mark_as_used_bool -\bool_new:N \g__acro_mark_first_as_used_bool -\bool_new:N \l__acro_use_single_bool -\bool_new:N \l__acro_print_only_used_bool -\bool_set_true:N \l__acro_print_only_used_bool -\bool_new:N \l__acro_hyperref_loaded_bool -\bool_new:N \l__acro_use_hyperref_bool -\bool_new:N \l__acro_xspace_bool -\bool_new:N \l__acro_custom_short_format_bool -\bool_new:N \l__acro_custom_alt_format_bool -\bool_new:N \l__acro_custom_long_format_bool -\bool_new:N \l__acro_override_list_format_bool -\bool_new:N \l__acro_strict_bool -\bool_new:N \l__acro_create_macros_bool -\bool_new:N \l__acro_first_upper_bool -\bool_new:N \l__acro_upper_short_bool -\bool_new:N \l__acro_indefinite_bool -\bool_new:N \l__acro_upper_indefinite_bool -\bool_new:N \l__acro_foreign_bool -\bool_set_true:N \l__acro_foreign_bool -\bool_new:N \l__acro_sort_bool -\bool_set_true:N \l__acro_sort_bool -\bool_new:N \l__acro_capitalize_list_bool -\bool_new:N \l__acro_citation_all_bool -\bool_new:N \l__acro_citation_first_bool -\bool_set_true:N \l__acro_citation_first_bool -\bool_new:N \l__acro_group_citation_bool -\bool_new:N \l__acro_acc_supp_bool -\bool_new:N \l__acro_tooltip_bool -\bool_new:N \l__acro_inside_tooltip_bool -\bool_new:N \l__acro_following_page_bool -\bool_new:N \l__acro_following_pages_bool -\bool_new:N \l__acro_addto_index_bool -\bool_new:N \l__acro_is_excluded_bool -\bool_new:N \l__acro_is_included_bool -\bool_new:N \l__acro_page_punct_bool -\bool_new:N \l__acro_page_brackets_bool -\bool_new:N \l__acro_page_display_bool -\bool_new:N \l__acro_new_page_numbering_bool -\bool_new:N \l__acro_first_use_brackets_bool -\bool_new:N \l__acro_first_only_short_bool -\bool_new:N \l__acro_first_only_long_bool -\bool_new:N \l__acro_first_reversed_bool -\bool_new:N \l__acro_first_switched_bool -\bool_new:N \l__acro_use_note_bool -\bool_new:N \l__acro_extra_punct_bool -\bool_new:N \l__acro_extra_use_brackets_bool -\bool_new:N \l__acro_in_list_bool -\bool_new:N \l__acro_place_label_bool -\bool_new:N \l__acro_list_all_pages_bool -\bool_set_true:N \l__acro_list_all_pages_bool -\bool_new:N \g__acro_first_acronym_declared_bool -\bool_new:N \l__acro_include_endings_format_bool -\bool_new:N \l__acro_list_reverse_long_extra_bool -\bool_new:N \l__acro_use_acronyms_bool -\bool_set_true:N \l__acro_use_acronyms_bool - -\tl_new:N \l__acro_ignore_tl -\tl_new:N \l__acro_default_indefinite_tl -\tl_set:Nn \l__acro_default_indefinite_tl {a} -\tl_new:N \l__acro_foreign_sep_tl -\tl_new:N \l__acro_extra_instance_tl -\tl_set:Nn \l__acro_extra_instance_tl {default} -\tl_new:N \l__acro_page_instance_tl -\tl_set:Nn \l__acro_page_instance_tl {none} -\tl_new:N \l__acro_page_name_tl -\tl_new:N \l__acro_pages_name_tl -\tl_new:N \l__acro_next_page_tl -\tl_new:N \l__acro_next_pages_tl -\tl_new:N \l__acro_list_instance_tl -\tl_set:Nn \l__acro_list_instance_tl {description} -\tl_new:N \l__acro_list_type_tl -% \tl_new:N \l__acro_list_tl -\tl_new:N \l__acro_list_heading_cmd_tl -\tl_set:Nn \l__acro_list_heading_cmd_tl {section*} -\tl_new:N \l__acro_list_name_tl -\tl_new:N \l__acro_list_before_tl -\tl_new:N \l__acro_list_after_tl -\tl_new:N \l__acro_custom_short_format_tl -\tl_new:N \l__acro_first_between_tl -\tl_new:N \l__acro_citation_connect_tl -\tl_new:N \l__acro_between_group_connect_citation_tl -\tl_new:N \l__acro_extra_brackets_tl -\tl_new:N \l__acro_extra_punct_tl -\tl_new:N \l__acro_first_brackets_tl -\tl_new:N \l__acro_page_punct_tl -\tl_new:N \l__acro_page_brackets_tl -\tl_new:N \l__acro_last_page_tl -\tl_new:N \l__acro_current_page_tl -\tl_new:N \l__acro_list_table_tl -\tl_new:N \l__acro_list_table_spec_tl -\tl_new:N \l__acro_acc_supp_tl -\tl_new:N \l__acro_acc_supp_options_tl -\tl_new:N \l__acro_label_prefix_tl -\tl_set:Nn \l__acro_label_prefix_tl { ac: } -\tl_new:N \l__acro_index_short_tl -\tl_new:N \l__acro_first_instance_tl -\tl_set:Nn \l__acro_first_instance_tl {default} - -\tl_new:N \l__acro_short_tl -\tl_new:N \l__acro_short_format_tl -\tl_new:N \l__acro_list_short_format_tl - -\tl_new:N \l__acro_alt_tl -\tl_new:N \l__acro_alt_format_tl - -\tl_new:N \l__acro_long_tl -\tl_new:N \l__acro_list_long_format_tl - -\tl_new:N \l__acro_single_form_tl -\tl_set:Nn \l__acro_single_form_tl {long} - -\tl_new:N \l__acro_extra_format_tl - -\tl_new:N \l__acro_foreign_format_tl -\tl_new:N \l__acro_foreign_list_format_tl -\tl_set:Nn \l__acro_foreign_list_format_tl { \acroenparen } - -\tl_new:N \l__acro_index_format_tl - - -\skip_new:N \l__acro_page_space_skip - -\dim_new:N \l__acro_short_width_dim -\dim_set:Nn \l__acro_short_width_dim {3em} - -\prop_new:N \l__acro_list_styles_prop -\prop_new:N \l__acro_list_headings_prop -\prop_new:N \l__acro_first_styles_prop -\prop_new:N \l__acro_extra_styles_prop -\prop_new:N \l__acro_page_styles_prop - % -------------------------------------------------------------------------- % small commands for use at various places \cs_new:Npn \acro_no_break: { \tex_penalty:D 10000 \scan_stop: } @@ -450,10 +493,13 @@ \cs_new_eq:NN \acro_first_upper_case:n \__acro_first_upper_case:n -\NewDocumentCommand \acfirstupper {m} - { \acro_first_upper_case:n {#1} } - % -------------------------------------------------------------------------- +\tl_new:N \l_acro_config_file_name_tl +\tl_new:N \l_acro_config_file_extension_tl + +\tl_set:Nn \l_acro_config_file_name_tl {acro} +\tl_set:Nn \l_acro_config_file_extension_tl {cfg} + % options: \keys_define:nn {acro} { @@ -463,6 +509,10 @@ messages / loud .code:n = \bool_set_false:N \l__acro_silence_bool , messages .value_required:n = true , + config-file-name .tl_set:N = \l_acro_config_file_name_tl , + config-file-name .initial:n = acro , + config-file-extension .tl_set:N = \l_acro_config_file_extension_tl , + config-file-extension .initial:n = cfg , accsupp .bool_set:N = \l__acro_acc_supp_bool , accsupp-options .tl_set:N = \l__acro_acc_supp_options_tl , tooltip .bool_set:N = \l__acro_tooltip_bool , @@ -472,6 +522,8 @@ xspace .bool_set:N = \l__acro_xspace_bool , % xspace .code:n = \acro_option_deprecated:nn {xspace} {} , strict .bool_set:N = \l__acro_strict_bool , + case-sensitive .bool_set:N = \g__acro_case_sensitive_bool , + case-sensitive .initial:n = true , sort .bool_set:N = \l__acro_sort_bool , short-format .code:n = \tl_set:Nn \l__acro_short_format_tl {#1} @@ -506,7 +558,7 @@ override-list-format .initial:n = true , extra-format .tl_set:N = \l__acro_extra_format_tl , extra-format .value_required:n = true , - single .bool_set:N = \l__acro_use_single_bool , + single .bool_set:N = \l__acro_single_use_bool , single-form .tl_set:N = \l__acro_single_form_tl , single-form .value_required:n = true , first-style .code:n = \acro_set_first_style:n {#1} , @@ -547,7 +599,7 @@ list-heading .value_required:n = true , list-name .tl_set:N = \l__acro_list_name_tl , list-name .value_required:n = true , - hyperref .bool_set:N = \l__acro_use_hyperref_bool , + hyperref .bool_set:N = \l__acro_hyperref_use_bool , only-used .bool_set:N = \l__acro_print_only_used_bool , mark-as-used .choice: , mark-as-used / first .code:n = @@ -603,11 +655,6 @@ { \cs_new:Npn \acro_xspace: {} } } -% -------------------------------------------------------------------------- -% setup command: -\NewDocumentCommand \acsetup { m } - { \keys_set:nn {acro} {#1} \ignorespaces } - % -------------------------------------------------------------------------- % we use xtemplate for different object types and with a different number of % arguments; let's declare functions for usage later so we don't have to @@ -633,7 +680,7 @@ \cs_new_protected:Npn \acro_first_instance:nn #1#2 { - \acro_if_property:nnTF {#1} {first-style} + \acro_property_if_set:nnTF {#1} {first-style} { \tl_set_eq:NN \l__acro_tmpa_tl @@ -663,7 +710,9 @@ \cs_new_protected:Npn \acro_activate_hyperref_support: { - \bool_if:nT { \l__acro_hyperref_loaded_bool && \l__acro_use_hyperref_bool } + \bool_lazy_and:nnT + { \l__acro_hyperref_loaded_bool } + { \l__acro_hyperref_use_bool } { \sys_if_engine_xetex:TF { @@ -680,8 +729,9 @@ % #2: text \cs_new_protected:Npn \__acro_make_link:nn #1#2 { - \bool_if:nTF - { \l__acro_use_hyperref_bool && \l__acro_hyperref_loaded_bool } + \bool_lazy_and:nnTF + { \l__acro_hyperref_use_bool } + { \l__acro_hyperref_loaded_bool } { \acro_hyper_link:nn {#1} { \phantom {#2} } \acro_if_is_single:nTF {#1} @@ -690,7 +740,6 @@ } {#2} } -\cs_generate_variant:Nn \__acro_make_link:Nnn {NnV} \cs_new:Npn \acro_color_link:n #1 { @@ -730,22 +779,18 @@ \str_case:nn {#1} { {long} { - \bool_if:nT - { - \l__acro_first_only_long_bool || - !\l__acro_first_only_short_bool - } + \bool_lazy_or:nnT + { \l__acro_first_only_long_bool } + { !\l__acro_first_only_short_bool } { \acro_write_indefinite:nn {#2} {long} \acro_write_expanded:nnn {#2} {first-long} {#3} } } {short} { - \bool_if:nT - { - !\l__acro_first_only_long_bool || - \l__acro_first_only_short_bool - } + \bool_lazy_or:nnT + { !\l__acro_first_only_long_bool } + { \l__acro_first_only_short_bool } { \acro_soft_upper: \acro_write_indefinite:nn {#2} {short} @@ -758,11 +803,9 @@ \cs_new_protected:Npn \__acro_open_bracket: { - \bool_if:nT - { - !\l__acro_first_only_long_bool && - !\l__acro_first_only_short_bool - } + \bool_lazy_and:nnT + { !\l__acro_first_only_long_bool } + { !\l__acro_first_only_short_bool } { \acro_space: \tl_if_blank:VF \l__acro_first_between_tl @@ -777,11 +820,11 @@ \cs_new_protected:Npn \__acro_close_bracket: { - \bool_if:nT + \bool_lazy_all:nT { - \l__acro_first_use_brackets_bool && - !\l__acro_first_only_short_bool && - !\l__acro_first_only_long_bool + { \l__acro_first_use_brackets_bool } + { !\l__acro_first_only_short_bool } + { !\l__acro_first_only_long_bool } } { \tl_tail:N \l__acro_first_brackets_tl } } @@ -794,11 +837,9 @@ \str_case:nn {#1} { {long} { - \bool_if:nT - { - \l__acro_first_only_long_bool || - !\l__acro_first_only_short_bool - } + \bool_lazy_or:nnT + { \l__acro_first_only_long_bool } + { !\l__acro_first_only_short_bool } { \group_begin: \bool_set_false:N \l__acro_first_upper_bool @@ -807,11 +848,9 @@ } } {short} { - \bool_if:nT - { - !\l__acro_first_only_long_bool || - \l__acro_first_only_short_bool - } + \bool_lazy_or:nnT + { !\l__acro_first_only_long_bool } + { \l__acro_first_only_short_bool } { \group_begin: \bool_set_false:N \l__acro_first_upper_bool @@ -825,11 +864,11 @@ % #1: id \cs_new_protected:Npn \__acro_foreign_sep:n #1 { - \bool_if:nT + \bool_lazy_all:nT { - \l__acro_foreign_bool && - !\l__acro_first_only_short_bool && - !\l__acro_first_only_long_bool + { \l__acro_foreign_bool } + { !\l__acro_first_only_short_bool } + { !\l__acro_first_only_long_bool } } { \acro_if_foreign:nT {#1} { \tl_use:N \l__acro_foreign_sep_tl } } } @@ -839,11 +878,11 @@ { \acro_if_foreign:nT {#1} { - \bool_if:nT + \bool_lazy_all:nT { - \l__acro_foreign_bool && - !\l__acro_first_only_short_bool && - !\l__acro_first_only_long_bool + { \l__acro_foreign_bool } + { !\l__acro_first_only_short_bool } + { !\l__acro_first_only_long_bool } } { \acro_write_foreign:n {#1} @@ -861,9 +900,9 @@ \cs_new_protected:Npn \__acro_finalize_first:n #1 { \bool_if:NF \l__acro_group_citation_bool - { \acro_cite_if:nn { \l__acro_citation_first_bool } {#1} } - \acro_index_if:nn { \l__acro_addto_index_bool } {#1} - \acro_get_property:nnT {#1} {post} + { \acro_cite_if:Nn \l__acro_citation_first_bool {#1} } + \acro_index_if:Nn \l__acro_addto_index_bool {#1} + \acro_property_get:nnT {#1} {post} { \tl_use:N \l__acro_post_tl } } @@ -919,11 +958,6 @@ \__acro_finalize_first:n {#1} } } - -\bool_new:N \l__acro_first_instance_bool - -\NewExpandableDocumentCommand \aciffirst {+m+m} - { \bool_if:NTF \l__acro_first_instance_bool {#1} {#2} } % template for footnotes, sidenotes, ... \cs_new:Npn \__acro_note_command:n #1 {#1} @@ -983,12 +1017,6 @@ \prop_put:Nnn \l__acro_first_styles_prop {#1} {#2} } -% #1: name -% #2: template -% #3: settings -\NewDocumentCommand \DeclareAcroFirstStyle {mmm} - { \acro_declare_first_style:nnn {#1} {#2} {#3} } - % set a list style \cs_new_protected:Npn \acro_set_first_style:n #1 { @@ -1046,12 +1074,6 @@ \prop_put:Nnn \l__acro_etxra_styles_prop {#1} {#2} } -% #1: name -% #2: template -% #3: settings -\NewDocumentCommand \DeclareAcroExtraStyle {mmm} - { \acro_declare_extra_style:nnn {#1} {#2} {#3} } - % set an extra style \cs_new_protected:Npn \acro_set_extra_style:n #1 { @@ -1191,13 +1213,14 @@ { \acro_get_abspage_from:N \l__acro_last_page_tl } \int_set:Nn \l__acro_tmpd_int { \acro_get_page_number_from:N \l__acro_last_page_tl } - \bool_if:nTF + \bool_lazy_and:nnTF { \int_compare_p:nNn { \l__acro_tmpa_int - \l__acro_tmpc_int } = { \l__acro_tmpb_int - \l__acro_tmpd_int } - && + } + { \int_compare_p:nNn { \l__acro_tmpb_int - \l__acro_tmpd_int } = {1} } @@ -1243,7 +1266,7 @@ \seq_put_right:Nn #1 {#3} } } -\cs_generate_variant:Nn \acro_determine_page_ranges:NNn { NNV } +\cs_generate_variant:Nn \acro_determine_page_ranges:NNn {NNV} % -------------------------------------------------------------------------- \DeclareObjectType {acro-page-number} {1} @@ -1291,12 +1314,6 @@ \prop_put:Nnn \l__acro_page_styles_prop {#1} {#2} } -% #1: name -% #2: template -% #3: settings -\NewDocumentCommand \DeclareAcroPageStyle {mmm} - { \acro_declare_page_style:nnn {#1} {#2} {#3} } - % set a page style \cs_new_protected:Npn \acro_set_page_style:n #1 { @@ -1348,12 +1365,7 @@ } \cs_new_protected:Npn \__acro_set_list_heading:n #1 - { - \tl_set:Nn \l__acro_list_heading_cmd_tl {#1} - % \prop_get:NnN \l__acro_list_headings_prop - % {#1} - % \l__acro_list_heading_cmd_tl - } + { \tl_set:Nn \l__acro_list_heading_cmd_tl {#1} } \cs_new_protected:Npn \acro_declare_list_heading:nn #1#2 { @@ -1362,9 +1374,6 @@ { name-format = #2 {##1} } } -\NewDocumentCommand \DeclareAcroListHeading {mm} - { \acro_declare_list_heading:nn {#1} {#2} } - % -------------------------------------------------------------------------- % typesetting the acronym list \DeclareObjectType {acro-list} {2} @@ -1376,11 +1385,11 @@ \bool_set_false:N \l__acro_is_excluded_bool \tl_if_blank:nF {#2} { - \clist_map_inline:nn {#2} + \acro_property_get:nnT {#1} {class} { - \prop_get:NnNT \l__acro_class_prop {#1} \l__acro_tmpa_tl + \seq_set_split:NnV \l__acro_tmpa_seq {,} \l__acro_class_tl + \clist_map_inline:nn {#2} { - \seq_set_split:NnV \l__acro_tmpa_seq {,} \l__acro_tmpa_tl \seq_if_in:NnT \l__acro_tmpa_seq {##1} { \bool_set_true:N \l__acro_is_excluded_bool } } @@ -1399,11 +1408,11 @@ \tl_if_blank:nTF {#2} { \bool_set_true:N \l__acro_is_included_bool } { - \clist_map_inline:nn {#2} + \acro_property_get:nnT {#1} {class} { - \prop_get:NnNT \l__acro_class_prop {#1} \l__acro_tmpa_tl + \seq_set_split:NnV \l__acro_tmpa_seq {,} \l__acro_class_tl + \clist_map_inline:nn {#2} { - \seq_set_split:NnV \l__acro_tmpa_seq {,} \l__acro_tmpa_tl \seq_if_in:NnT \l__acro_tmpa_seq {##1} { \bool_set_true:N \l__acro_is_included_bool } } @@ -1425,14 +1434,12 @@ \acro_acc_supp:nn {#1} { - \bool_if:nTF - { - \l__acro_custom_short_format_bool && - \l__acro_override_list_format_bool - } + \bool_lazy_and:nnTF + { \l__acro_custom_short_format_bool } + { \l__acro_override_list_format_bool } { \l__acro_custom_short_format_tl } { \l__acro_list_short_format_tl } - { \__acro_get_property:nn {short} {#1} } + { \__acro_property_get:nn {short} {#1} } } } \group_end: @@ -1447,30 +1454,30 @@ \acro_write_long:Vf \l__acro_list_long_format_tl { \prop_if_in:NnTF \l__acro_list_prop {#1} - { \__acro_get_property:nn {list} {#1} } - { \__acro_get_property:nn {long} {#1} } + { \__acro_property_get:nn {list} {#1} } + { \__acro_property_get:nn {long} {#1} } } \group_end: \bool_if:NT \l__acro_foreign_bool { \acro_get_foreign:n {#1} } - \acro_cite_if:nn { \l__acro_citation_all_bool } {#1} + \acro_cite_if:Nn \l__acro_citation_all_bool {#1} } % #1: id \cs_new_protected:Npn \__acro_list_entry_extra:n #1 { - \prop_get:NnNT \l__acro_extra_prop {#1} \l__acro_tmpa_tl + \acro_property_get:nnT {#1} {extra} { \acro_extra_instance:VV \l__acro_extra_instance_tl - \l__acro_tmpa_tl + \l__acro_extra_tl } } % #1: id \cs_new_protected:Npn \__acro_list_entry_page:n #1 { - \bool_if:nT { \cs_if_exist_p:c { acro@#1@once } } + \cs_if_exist:cT {acro@#1@once} { \acro_page_number_instance:Vn \l__acro_page_instance_tl @@ -1490,7 +1497,7 @@ {extra} { \__acro_list_entry_extra:n {#2} } {page} { \__acro_list_entry_page:n {#2} } } - { \__acro_get_property:nn {#1} {#2} } + { \__acro_property_get:nn {#1} {#2} } } % this macro may/should be redefined in templates: @@ -1513,20 +1520,31 @@ % #3: excluded classes \prg_new_protected_conditional:Npnn \acro_if_entry:nnn #1#2#3 {T,F,TF} { - \bool_if:nTF + \bool_lazy_or:nnTF { - \bool_if_p:c { g__acro_#1_in_list_bool } && - ( - ( \l__acro_use_single_bool && \cs_if_exist_p:c { acro@#1@twice } ) - || - ( - !\l__acro_use_single_bool && - \cs_if_exist_p:c { acro@#1@once } && - \l__acro_print_only_used_bool - ) - ) - || - ( !\l__acro_use_single_bool && !\l__acro_print_only_used_bool ) + \bool_lazy_and_p:nn + { !\l__acro_single_use_bool } + { !\l__acro_print_only_used_bool } + } + { + \bool_lazy_and_p:nn + { \bool_if_p:c {g__acro_#1_in_list_bool} } + { + \bool_lazy_or_p:nn + { + \bool_lazy_and_p:nn + { \l__acro_single_use_bool } + { \cs_if_exist_p:c {acro@#1@twice} } + } + { + \bool_lazy_all_p:n + { + { !\l__acro_single_use_bool } + { \cs_if_exist_p:c {acro@#1@once} } + { \l__acro_print_only_used_bool } + } + } + } } { \acro_if_is_excluded:nnTF {#1} {#3} @@ -1534,8 +1552,9 @@ { \acro_if_is_included:nnTF {#1} {#2} { - \bool_if:nTF - { \g__acro_use_barriers_bool && \l__acro_use_barrier_bool } + \bool_lazy_and:nnTF + { \g__acro_use_barriers_bool } + { \l__acro_use_barrier_bool } { \acro_if_in_barrier:nxTF {#1} { \int_use:N \g__acro_barrier_int } @@ -1550,8 +1569,6 @@ { \prg_return_false: } } -\tl_new:N \l__acro_list_entries_tl - % this macro is used in templates for fetching all items to be printed; it % collects all entries in a tl which then is used where needed % @@ -1815,12 +1832,6 @@ \prop_put:Nnn \l__acro_list_styles_prop {#1} {#2} } -% #1: name -% #2: template -% #3: settings -\NewDocumentCommand \DeclareAcroListStyle {mmm} - { \acro_declare_list_style:nnn {#1} {#2} {#3} } - % set a list style \cs_new_protected:Npn \acro_set_list_style:n #1 { @@ -1841,6 +1852,28 @@ \prop_get:NnN \l__acro_list_styles_prop {#1} \l__acro_list_type_tl } +% -------------------------------------------------------------------------- +% case insensitivity of the ID: +\cs_new:Npn \acro_case_insensitive:n #1 + { + \bool_if:NTF \g__acro_case_sensitive_bool + { \tl_to_str:n {#1} } + { \str_lower_case:n {#1} } + } + +\cs_new_protected:Npn \acro_protected_case_insensitive:n #1 + { \acro_case_insensitive:n {#1} } + +\cs_new:Npn \acro_case_insensitive:Nn #1#2 + { \exp_args:Ne #1 { \acro_case_insensitive:n {#2} } } + +\cs_new:Npn \acro_case_insensitive:Nnn #1#2#3 + { \exp_args:Ne #1 { \acro_case_insensitive:n {#2} } {#3} } + +\cs_new_protected:Npn \acro_case_insensitive_command:Nnnn #1#2#3#4 + { \exp_args:Nnnx #1 {#2} {#3} { \acro_case_insensitive:n {#4} } } +\cs_generate_variant:Nn \acro_case_insensitive_command:Nnnn {c} + % -------------------------------------------------------------------------- % automatic typesetting, the internals of \ac: % #1: id @@ -1879,7 +1912,7 @@ \acro_single_form:nV {#1} \l__acro_single_form_tl \acro_after:n {#1} } - + % #1: ID % #2: long|first| \cs_new_protected:Npn \acro_single_form:nn #1#2 @@ -1935,8 +1968,9 @@ \prg_new_conditional:Npnn \acro_if_is_single:n #1 { p,T,TF } { - \bool_if:nTF - { !\l__acro_use_single_bool || \cs_if_exist_p:c { acro@#1@twice } } + \bool_lazy_or:nnTF + { !\l__acro_single_use_bool } + { \cs_if_exist_p:c {acro@#1@twice} } { \prg_return_false: } { \prg_return_true: } } @@ -1946,11 +1980,10 @@ % -------------------------------------------------------------------------- % some helpers we'll need more often: -\seq_new:N \g__acro_declared_acronyms_seq - \prg_new_conditional:Npnn \acro_if_defined:n #1 {p,T,F,TF} { - \seq_if_in:NnTF \g__acro_declared_acronyms_seq {#1} + \seq_if_in:NeTF \g__acro_declared_acronyms_seq + { \acro_case_insensitive:n {#1} } { \prg_return_true: } { \prg_return_false: } } @@ -1965,14 +1998,14 @@ % name is needed % #1: property % #2: id -\cs_new:Npn \__acro_get_property:nn #1#2 +\cs_new:Npn \__acro_property_get:nn #1#2 { \prop_item:cn {l__acro_#1_prop} {#2} } % #1: id % #2: property % #3: set case % #4: not set case -\prg_new_protected_conditional:Npnn \acro_get_property:nn #1#2 {T,F,TF} +\prg_new_protected_conditional:Npnn \acro_property_get:nn #1#2 {T,F,TF} { \tl_set:Nn \l__acro_tmpa_tl {#2} \tl_replace_all:Nnn \l__acro_tmpa_tl {-} {_} @@ -1984,32 +2017,14 @@ { \prg_return_false: } } -\cs_new_protected:Npn \acro_get_property:nn #1#2 - { \acro_get_property:nnTF {#1} {#2} {} {} } -\cs_generate_variant:Nn \acro_get_property:nn {V} - -% #1: id -% #2: property -% #3: set case -% #4: not set case -\prg_new_protected_conditional:Npnn \acro_if_property:nn #1#2 {T,F,TF} - { - \tl_set:Nn \l__acro_tmpa_tl {#2} - \tl_replace_all:Nnn \l__acro_tmpa_tl {-} {_} - \prop_if_in:cnTF - {l__acro_ \l__acro_tmpa_tl _prop} - {#1} - { \prg_return_true: } - { \prg_return_false: } - } - -\seq_new:N \l__acro_actions_seq +\cs_new_protected:Npn \acro_property_get:nn #1#2 + { \acro_property_get:nnTF {#1} {#2} {} {} } +\cs_generate_variant:Nn \acro_property_get:nn {V} % within this command one can refer to the current id with `#1' \cs_new_protected:Npn \acro_add_action:n #1 { \seq_put_right:Nn \l__acro_actions_seq {#1} } -\tl_new:N \l_acro_current_id_tl \cs_new_protected:Npn \__acro_get_actions:n #1 { \seq_map_inline:Nn \l__acro_actions_seq @@ -2024,52 +2039,57 @@ \bool_if:NF \l__acro_in_list_bool { \leavevmode } \acro_activate_hyperref_support: % short: - \prop_get:NnNF \l__acro_short_prop {#1} \l__acro_short_tl {} - % \__acro_make_link:NnV \l__acro_short_tl {#1} \l__acro_tmpa_tl + \acro_property_get:nn {#1} {short} % alt: - \prop_get:NnNF \l__acro_alt_prop {#1} \l__acro_alt_tl - % { \__acro_make_link:NnV \l__acro_alt_tl {#1} \l__acro_tmpa_tl } + \acro_property_get:nnF {#1} {alt} { \tl_set_eq:NN \l__acro_alt_tl \l__acro_short_tl } % long: - \acro_get_property:nn {#1} {long} + \acro_property_get:nn {#1} {long} % foreign: - \acro_get_property:nn {#1} {foreign} + \acro_property_get:nn {#1} {foreign} % foreign-lang: - \acro_get_property:nn {#1} {foreign-lang} + \acro_property_get:nn {#1} {foreign-lang} % extra: - \acro_get_property:nn {#1} {extra} + \acro_property_get:nn {#1} {extra} % single: - \acro_get_property:nn {#1} {single} + \acro_property_get:nn {#1} {single} % first-style: - \acro_get_property:nn {#1} {first-style} + \acro_property_get:nn {#1} {first-style} % formatting - \prop_get:NnNTF \l__acro_long_format_prop {#1} - \l__acro_custom_long_format_tl - { \bool_set_true:N \l__acro_custom_long_format_bool } + \acro_property_get:nnTF {#1} {long-format} + { + \tl_set_eq:NN \l__acro_custom_long_format_tl \l__acro_long_format_tl + \bool_set_true:N \l__acro_custom_long_format_bool + } { \bool_set_false:N \l__acro_custom_long_format_bool } - \acro_get_property:nn {#1} {first-long-format} - \prop_get:NnNTF \l__acro_format_prop {#1} \l__acro_custom_short_format_tl - { \bool_set_true:N \l__acro_custom_short_format_bool } + \acro_property_get:nn {#1} {first-long-format} + \acro_property_get:nnTF {#1} {format} + { + \tl_set_eq:NN \l__acro_custom_short_format_tl \l__acro_format_tl + \bool_set_true:N \l__acro_custom_short_format_bool + } { \bool_set_false:N \l__acro_custom_short_format_bool } - \prop_get:NnNTF \l__acro_alt_format_prop {#1} \l__acro_custom_alt_format_tl - { \bool_set_true:N \l__acro_custom_alt_format_bool } + \acro_property_get:nnTF {#1} {alt-format} + { + \tl_set_eq:NN \l__acro_custom_alt_format_tl \l__acro_alt_format_tl + \bool_set_true:N \l__acro_custom_alt_format_bool + } { \bool_set_false:N \l__acro_custom_alt_format_bool } - \acro_get_property:nn {#1} {single-format} + \acro_property_get:nn {#1} {single-format} \acro_for_endings_do:n { \bool_if:cT {l__acro_##1_bool} { \__acro_set_ending_for:nnn {##1} {#1} {long} } } - \acro_get_property:nnF {#1} {long-post} + \acro_property_get:nnF {#1} {long-post} { \tl_clear:N \l__acro_long_post_tl } - \acro_get_property:nnT {#1} {long-pre} + \acro_property_get:nnT {#1} {long-pre} { \tl_put_left:NV \l__acro_long_tl \l__acro_long_pre_tl } \__acro_get_actions:n {#1} } % -------------------------------------------------------------------------- % plural endings and similar concepts: -\seq_new:N \l__acro_endings_seq \cs_new_protected:Npn \acro_for_endings_do:n #1 { \seq_map_inline:Nn \l__acro_endings_seq {#1} } @@ -2087,10 +2107,6 @@ } } -\tl_new:N \l__acro_endings_tl - -\bool_new:N \l__acro_use_ending_form_bool - % this does nothing if a non-existent ending (#1) or non-existent form (#3) is % input % #1: ending @@ -2121,12 +2137,9 @@ { \acro_if_ending_form_exist:nnT {##1} {#2} { - \bool_if:nT - { - \use:c { c_ \prop_item:cn {l__acro_#2_##1_form_prop} {#1} _bool } - && - \use:c {l__acro_##1_bool} - } + \bool_lazy_and:nnT + { \use:c {l__acro_##1_bool} } + { \use:c { c_ \prop_item:cn {l__acro_#2_##1_form_prop} {#1} _bool } } { \prop_get:cncF {l__acro_#2_##1_prop} {#1} {l__acro_#2_tl} {} } } } @@ -2389,26 +2402,22 @@ } } -\NewDocumentCommand \ProvideAcroEnding {mmm} - { \acro_provide_ending:nnn {#1} {#2} {#3} } - % -------------------------------------------------------------------------- % enable us to know if the acronym is used only once and provide a different % style for that: \prg_new_protected_conditional:Npnn \acro_is_used:n #1 { T,F,TF } { \acro_record_barrier:n {#1} - \bool_if:nTF + \bool_lazy_and:nnTF + { \bool_if_p:c {g__acro_#1_used_bool} } { - \bool_if_p:c { g__acro_#1_used_bool } && - ( - ( - \bool_if_p:c { g__acro_#1_first_use_bool } && - \g__acro_mark_first_as_used_bool - ) - || - ! \g__acro_mark_first_as_used_bool - ) + \bool_lazy_or_p:nn + { + \bool_lazy_and_p:nn + { \bool_if_p:c {g__acro_#1_first_use_bool} } + { \g__acro_mark_first_as_used_bool } + } + { !\g__acro_mark_first_as_used_bool } } { \bool_if:NTF \l__acro_mark_as_used_bool @@ -2430,11 +2439,9 @@ { \thepage } { \arabic {page} } { \arabic {abspage} } - \bool_if:nT - { - !\bool_if_p:c { g__acro_#1_label_bool } && - \l__acro_place_label_bool - } + \bool_lazy_and:nnT + { !\bool_if_p:c {g__acro_#1_label_bool} } + { \l__acro_place_label_bool } { \bool_gset_true:c { g__acro_#1_label_bool } \label{\l__acro_label_prefix_tl #1} @@ -2454,11 +2461,11 @@ \cs_new_protected:Npn \__acro_aux_file:Nnnnn #1#2#3#4#5 { \iow_shipout:Nn \@auxout { #1 {#2} {#3} {#4} {#5} } } -\cs_generate_variant:Nn \__acro_aux_file:Nnnnn { Nxxxx } +\cs_generate_variant:Nn \__acro_aux_file:Nnnnn {Nxxxx} \cs_new_protected:Npn \__acro_aux_file_now:n #1 { \iow_now:Nn \@auxout {#1} } -\cs_generate_variant:Nn \__acro_aux_file_now:n { x } +\cs_generate_variant:Nn \__acro_aux_file_now:n {x} % -------------------------------------------------------------------------- % the commands for the auxiliary file: @@ -2482,8 +2489,6 @@ \cs_new_protected:Npn \acro@pages #1#2 { \tl_gset:cn {g__acro_#1_recorded_pages_tl} {#2} } -\bool_new:N \g__acro_rerun_bool - \cs_new_protected:Npn \acro@rerun@check { \bool_if:NT \g__acro_rerun_bool @@ -2567,14 +2572,13 @@ { \__acro_typeset:nn {short} { - \bool_if:nTF - { \l__acro_first_upper_bool } + \bool_if:NTF \l__acro_first_upper_bool { \exp_not:N \__acro_first_upper_case:n { \exp_not:n {#2} } } { \exp_not:n {#2} } } } } -\cs_generate_variant:Nn \acro_write_short:nn { nV , nv } +\cs_generate_variant:Nn \acro_write_short:nn {nV,nv} % typeset the alternative form: % #1: ID @@ -2585,14 +2589,15 @@ { \__acro_typeset:nn {alt} { - \bool_if:nTF - { \l__acro_first_upper_bool && \l__acro_upper_short_bool } + \bool_lazy_and:nnTF + { \l__acro_first_upper_bool } + { \l__acro_upper_short_bool } { \exp_not:N \__acro_first_upper_case:n { \exp_not:n {#2} } } { \exp_not:n {#2} } } } } -\cs_generate_variant:Nn \acro_write_alt:nn { nV , nv } +\cs_generate_variant:Nn \acro_write_alt:nn {nV,nv} % typeset a long form: % TODO: rethink the formatting mechanism @@ -2612,16 +2617,13 @@ } } } -\cs_generate_variant:Nn \acro_write_long:nn { VV,Vo,Vf,V,v,vv } +\cs_generate_variant:Nn \acro_write_long:nn {VV,Vo,Vf,V,v,vv} \prg_new_conditional:Npnn \acro_if_foreign:n #1 {T,F,TF} { - \bool_if:nTF - { - \l__acro_foreign_bool - && - \prop_if_in_p:Nn \l__acro_foreign_prop {#1} - } + \bool_lazy_and:nnTF + { \l__acro_foreign_bool } + { \prop_if_in_p:Nn \l__acro_foreign_prop {#1} } { \prg_return_true: } { \prg_return_false: } } @@ -2648,7 +2650,7 @@ { \acro_if_foreign:nT {#1} { - \prop_get:NnNT \l__acro_foreign_prop {#1} \l__acro_foreign_tl + \acro_property_get:nnT {#1} {foreign} { \group_begin: \tl_use:N \l__acro_foreign_format_tl @@ -2666,10 +2668,9 @@ \cs_new_protected:Npn \acro_get_foreign:n #1 { - \prop_if_in:NnT \l__acro_foreign_prop {#1} + \acro_property_get:nnT {#1} {foreign} { \tl_use:N \l__acro_foreign_sep_tl - \prop_get:NnN \l__acro_foreign_prop {#1} \l__acro_foreign_tl \group_begin: \tl_use:N \l__acro_foreign_list_format_tl { @@ -2713,7 +2714,7 @@ \tl_if_in:nnT {#2} {long} { \l__acro_long_post_tl } } -\cs_generate_variant:Nn \acro_write_expanded:nnn { nnV } +\cs_generate_variant:Nn \acro_write_expanded:nnn {nnV} % #1: ID % #2: long|first-long|list-long|extra @@ -2732,9 +2733,9 @@ % #1: id \cs_new_protected:Npn \acro_after:n #1 { - \acro_cite_if:nn { \l__acro_citation_all_bool } {#1} - \acro_index_if:nn { \l__acro_addto_index_bool } {#1} - \acro_get_property:nnT {#1} {post} + \acro_cite_if:Nn \l__acro_citation_all_bool {#1} + \acro_index_if:Nn \l__acro_addto_index_bool {#1} + \acro_property_get:nnT {#1} {post} { \tl_use:N \l__acro_post_tl } } @@ -2833,8 +2834,8 @@ % ---------------------------------------------------------------------------- % citations: -\cs_new:Npn \__acro_citation_cmd:w { \cite } %{} -\cs_new:Npn \__acro_group_citation_cmd:w { \cite } %{} +\cs_new:Npn \__acro_citation_cmd:w { \cite } +\cs_new:Npn \__acro_group_citation_cmd:w { \cite } % #1 pre % #2 post @@ -2845,14 +2846,16 @@ { \__acro_citation_cmd:w {#3} } { \quark_if_no_value:nTF {#2} - { \__acro_citation_cmd:w [ #1 ] {#3} } - { \__acro_citation_cmd:w [ #1 ] [ #2 ] {#3} } + { \__acro_citation_cmd:w [#1] {#3} } + { \__acro_citation_cmd:w [#1] [#2] {#3} } } } -\cs_generate_variant:Nn \__acro_cite:nnn { VVV } +\cs_generate_variant:Nn \__acro_cite:nnn {VVV} \cs_new_protected:Npn \acro_cite:n #1 { + \acro_property_get:nnT {#1} {before-citation} + { \acro_no_break: \l__acro_before_citation_tl } \prop_get:NnNT \l__acro_citation_prop {#1} \l__acro_tmpa_tl { \prop_get:NnN \l__acro_citation_pre_prop {#1} \l__acro_tmpb_tl @@ -2864,6 +2867,8 @@ \l__acro_tmpc_tl \l__acro_tmpa_tl } + \acro_property_get:nnT {#1} {after-citation} + { \acro_no_break: \l__acro_after_citation_tl } } \cs_new_protected:Npn \acro_group_cite:n #1 @@ -2873,18 +2878,18 @@ \tl_set_eq:NN \l__acro_citation_connect_tl \l__acro_between_group_connect_citation_tl - \acro_cite_if:nn { \l__acro_citation_first_bool } {#1} + \acro_cite_if:Nn \l__acro_citation_first_bool {#1} \group_end: } -\cs_new_protected:Npn \acro_cite_if:nn #1#2 - { \bool_if:nT {#1} { \acro_cite:n {#2} } } +\cs_new_protected:Npn \acro_cite_if:Nn #1#2 + { \bool_if:NT #1 { \acro_cite:n {#2} } } % ---------------------------------------------------------------------------- % indexing: -\cs_new_protected:Npn \acro_index_if:nn #1#2 +\cs_new_protected:Npn \acro_index_if:Nn #1#2 { - \bool_if:nT { (#1) && \l__acro_mark_as_used_bool } + \bool_lazy_and:nnT {#1} { \l__acro_mark_as_used_bool } { \prop_get:NnN \l__acro_index_cmd_prop {#2} \l__acro_tmpa_tl \prop_get:NnN \l__acro_index_sort_prop {#2} \l__acro_tmpb_tl @@ -2920,7 +2925,7 @@ } { \__acro_index_cmd:n {#4} } } -\cs_generate_variant:Nn \__acro_index:nnnn { VnVV } +\cs_generate_variant:Nn \__acro_index:nnnn {VnVV} % ---------------------------------------------------------------------------- % accessability support @@ -2951,7 +2956,7 @@ #3 \EndAccSupp { } } -\cs_generate_variant:Nn \acro_do_acc_supp:nnn { VV } +\cs_generate_variant:Nn \acro_do_acc_supp:nnn {VV} \AtEndPreamble { @@ -2976,20 +2981,20 @@ % #3: tool tip text \cs_new_protected:Npn \acro_write_tooltip:nnn #1#2#3 { - \prop_get:NnNTF \l__acro_tooltip_prop {#1} \l__acro_tmpa_tl - { \__acro_check_tooltip:nV {#2} \l__acro_tmpa_tl } + \acro_property_get:nnTF {#1} {tooltip} + { \__acro_check_tooltip:nV {#2} \l__acro_tooltip_tl } { \__acro_check_tooltip:nn {#2} {#3} } } -\cs_generate_variant:Nn \acro_write_tooltip:nnn { nnV } +\cs_generate_variant:Nn \acro_write_tooltip:nnn {nnV} % #1: printed text % #2: tool tip text \cs_new_protected:Npn \__acro_check_tooltip:nn #1#2 { - \bool_if:NTF \l__acro_inside_tooltip_bool + \bool_if:NTF \l__acro_tooltip_inside_bool {#1} { - \bool_set_true:N \l__acro_inside_tooltip_bool + \bool_set_true:N \l__acro_tooltip_inside_bool \__acro_tooltip_cmd:nn {#1} {#2} } } @@ -3109,10 +3114,6 @@ % -------------------------------------------------------------------------- % trailing tokens and what to do when present -\prop_new:N \l__acro_trailing_tokens_prop -\prop_new:N \l__acro_trailing_actions_prop -\bool_new:N \l__acro_trailing_tokens_bool -\tl_new:N \l__acro_trailing_tokens_tl \cs_new_protected:Npn \acro_new_trailing_token:n #1 { \bool_new:c {l__acro_trailing_#1_bool} } @@ -3131,9 +3132,6 @@ { \acro_activate_trailing_action:n {#2} } \acro_new_trailing_token:n {#2} } - -\NewDocumentCommand \AcroRegisterTrailing {mm} - { \acro_register_trailing_token:Nn #1 {#2} } \cs_new_protected:Npn \acro_for_all_trailing_tokens_do:n #1 { \prop_map_inline:Nn \l__acro_trailing_tokens_prop {#1} } @@ -3203,9 +3201,6 @@ \cs_new_protected:Npn \acro_space: { \acro_if_trailing_tokens:nF {dash,babel-hyphen} { \c_space_tl } } - -\NewDocumentCommand \acdot {} { \acro_dot: } -\NewDocumentCommand \acspace {} { \acro_space: } % --------------------------------------------------------------------------- % reset outputs, they'll behave like the first time again (!not like the _only_ @@ -3237,41 +3232,19 @@ \cs_new_protected:Npn \acro_mark_all_as_used: { \acro_for_all_acronyms_do:n { \acro_mark_as_used:n {##1} } } -\DeclareExpandableDocumentCommand \acifused { m } - { \acro_if_acronym_used:nTF {#1} } - \prg_new_conditional:Npnn \acro_if_acronym_used:n #1 { p,T,F,TF } { - \bool_if:nTF - { - \bool_if_p:c { g__acro_#1_used_bool } && - ( !\acro_if_is_single_p:n {#1} ) - } + \bool_lazy_and:nnTF + { \bool_if_p:c {g__acro_#1_used_bool} } + { !\acro_if_is_single_p:n {#1} } { \prg_return_true: } { \prg_return_false: } } -\NewDocumentCommand \acresetall {} - { \acro_reset_all: } - -\NewDocumentCommand \acuseall {} - { \acro_mark_all_as_used: } - -\NewDocumentCommand \acreset { > { \SplitList { , } } m } - { \ProcessList {#1} { \acro_reset:n } \ignorespaces } - -\NewDocumentCommand \acuse { > { \SplitList { , } } m } - { \ProcessList {#1} { \acro_mark_as_used:n } \ignorespaces } - % -------------------------------------------------------------------------- % acronym barriers: allow local lists of only those acronyms used between two % barriers -\int_new:N \g__acro_barrier_int -\bool_new:N \g__acro_use_barriers_bool -\bool_new:N \g__acro_reset_at_barrier_bool -\bool_new:N \l__acro_use_barrier_bool - \keys_define:nn {acro} { use-barriers .bool_gset:N = \g__acro_use_barriers_bool , @@ -3287,9 +3260,6 @@ { \acro_reset_all: } } -\NewDocumentCommand \acbarrier {} - { \acro_barrier: } - \cs_new_protected:Npn \acro_check_barriers:n #1 { \bool_if:NT \g__acro_use_barriers_bool @@ -3358,9 +3328,6 @@ \bool_set_false:N \l__acro_indefinite_bool \bool_set_false:N \l__acro_first_upper_bool \bool_set_false:N \l__acro_upper_indefinite_bool - % \bool_set_false:N \l__acro_citation_all_bool - % \bool_set_false:N \l__acro_citation_first_bool - % \bool_set_false:N \l__acro_addto_index_bool \acro_for_endings_do:n { \bool_set_false:c {l__acro_##1_bool} } } @@ -3376,8 +3343,7 @@ % #2: ID \cs_new_protected:Npn \acro_check_and_mark_if:nn #1#2 { - \bool_if:nTF - { (#1) || !\l__acro_use_acronyms_bool } + \bool_lazy_or:nnTF {#1} { !\l__acro_use_acronyms_bool } { \acro_check_acronym:nn {#2} {false} } { \acro_check_acronym:nn {#2} {true} } } @@ -3388,12 +3354,6 @@ \cs_new_protected:Npn \acro_switch_on: { \bool_set_true:N \l__acro_use_acronyms_bool } -\NewDocumentCommand \acswitchoff {} - { \acro_switch_off: } - -\NewDocumentCommand \acswitchon {} - { \acro_switch_on: } - % commands for (re)defining \ac-like macros: \cs_new_protected:Npn \acro_define_new_acro_command:NN #1#2 { @@ -3401,19 +3361,29 @@ % #2: definition where `#1' refers to the ID \cs_new_protected:Npn #1 ##1##2 { - \cs_set:Npn \__acro_tmp_command:n ####1 {##2} - \exp_args:NNnx #2 ##1 {sO{}m} + \cs_set:Npn \__acro_tmp:n ####1 {##2} + \cs_new_protected:cpx + {acro_ \__acro_remove_backslash:N ##1 :nnn} ####1####2####3 { \acro_begin: \acro_reset_specials: - \keys_set:nn {acro} {########2} - \acro_check_and_mark_if:nn {########1} {########3} - \exp_not:o { \__acro_tmp_command:n {####3} } + \exp_not:N \tl_if_blank:nF {####2} { \keys_set:nn {acro} {####2} } + \acro_check_and_mark_if:nn {####1} {####3} + \__acro_tmp:n {####3} \acro_end: } + #2 ##1 {sO{}m} + { + \acro_case_insensitive_command:cnnn + {acro_ \__acro_remove_backslash:N ##1 :nnn} + {####1} + {####2} + {####3} + } } } \cs_generate_variant:Nn \acro_define_new_acro_command:NN {cc} +\cs_generate_variant:Nn \acro_check_and_mark_if:nn {nx} % commands for (re)defining \acflike-like macros: \cs_new_protected:Npn \acro_define_new_acro_pseudo_command:NN #1#2 @@ -3422,15 +3392,24 @@ % #2: definition where `#1' refers to the ID and `#2' to the pseudo long form \cs_new_protected:Npn #1 ##1##2 { - \cs_set:Npn \__acro_tmp_command:nn ####1####2 {##2} - \exp_args:NNnx #2 ##1 {smm} + \cs_set:Npn \__acro_tmp:nn ####1####2 {##2} + \cs_new_protected:cpx + {acro_ \__acro_remove_backslash:N ##1 :nnn} ####1####2####3 { \acro_begin: \acro_reset_specials: - \acro_check_and_mark_if:nn {########1} {########2} - \exp_not:o { \__acro_tmp_command:nn {####2} {####3} } + \acro_check_and_mark_if:nn {####1} {####3} + \__acro_tmp:nn {####3} {####2} \acro_end: } + #2 ##1 {smm} + { + \acro_case_insensitive_command:cnnn + {acro_ \__acro_remove_backslash:N ##1 :nnn} + {####1} + {####3} + {####2} + } } } \cs_generate_variant:Nn \acro_define_new_acro_pseudo_command:NN {cc} @@ -3594,10 +3573,6 @@ } {} } -% -------------------------------------------------------------------------- -% additional variables: -\tl_new:N \l__acro_current_property_tl - % -------------------------------------------------------------------------- % key and order checking \msg_new:nnn {acro} {no-id} @@ -3627,36 +3602,47 @@ % #2: property \cs_new_protected:Npn \__acro_property_check:nn #1#2 { - \tl_if_blank:VT \l__acro_current_property_tl + \str_if_empty:NT \l__acro_current_id_str { \acro_serious_message:n {no-id} } \str_if_eq:nnF {#2} {short} { - \bool_if:cF { l__acro_#1_short_set_bool } + \acro_property_if_set:nnF {#1} {short} { - \keys_set:nn { acro / declare-acronym } { short = {#1} } + \keys_set:nn {acro/declare-acronym} { short = {#1} } \acro_harmless_message:nn {substitute-short} {#1} } } - % \bool_new:c { l__acro_#1_#2_set_bool } - \bool_set_true:c { l__acro_#1_#2_set_bool } + \acro_property_mark_set:nn {#1} {#2} } \cs_new_protected:Npn \__acro_first_property_check:nn #1#2 { - \cs_if_exist:cTF { l__acro_#1_short_set_bool } + \cs_if_exist:cTF {l__acro_#1_short_set_bool} { - \bool_if:cT { l__acro_#1_short_set_bool } + \acro_property_if_set:nnT {#1} {short} { \acro_serious_message:nnn {doubled-property} {#1} {#2} } } - { - \bool_new:c { l__acro_#1_short_set_bool } - \bool_set_true:c { l__acro_#1_short_set_bool } - } + { \bool_new:c {l__acro_#1_short_set_bool} } + \acro_property_mark_set:nn {#1} {short} + } + +% #1: ID +% #2: property +\prg_new_conditional:Npnn \acro_property_if_set:nn #1#2 {T,F,TF} + { + \bool_if:cTF {l__acro_#1_#2_set_bool} + { \prg_return_true: } + { \prg_return_false: } } +% #1: ID +% #2: property +\cs_new_protected:Npn \acro_property_mark_set:nn #1#2 + { \bool_set_true:c { l__acro_#1_#2_set_bool } } +\cs_generate_variant:Nn \acro_property_mark_set:nn {V} + % -------------------------------------------------------------------------- % the internal property selection functions for \DeclareAcronym: -\prop_new:N \g__acro_properties_prop \cs_new_protected:Npn \acro_for_properties_do:n { \prop_map_inline:Nn \g__acro_properties_prop } @@ -3667,14 +3653,14 @@ \cs_new_protected:Npn \acro_declare_property_generic:nnn #1#2#3 { \prop_clear_new:c {l__acro_#1_prop} + \tl_clear_new:c {l__acro_#1_tl} \cs_new_protected:cpn {__acro_declare_#1:nn} ##1##2 {#3} \cs_generate_variant:cn {__acro_declare_#1:nn} {V} - % \bool_new:c {l__acro_ \l__acro_current_property_tl _#1_set_bool} \keys_define:nn {acro/declare-acronym} { #2 .code:n = - \use:c {__acro_declare_#1:Vn} \l__acro_current_property_tl {##1} - \bool_set_true:c {l__acro_ \l__acro_current_property_tl _#2_set_bool} + \use:c {__acro_declare_#1:Vn} \l__acro_current_id_str {##1} + \acro_property_mark_set:Vn \l__acro_current_id_str {#2} } \prop_gput:Nnn \g__acro_properties_prop {#2} {#1} } @@ -3696,13 +3682,12 @@ % #2: property name \cs_new_protected:Npn \acro_declare_property:nn #1#2 { \acro_declare_property:nnn {#1} {#2} {} } -\cs_generate_variant:Nn \acro_declare_property:nn { V } +\cs_generate_variant:Nn \acro_declare_property:nn {V} -\cs_new_protected:Npn \acro_declare_simple_property:n #1 +\cs_new_protected:Npn \acro_declare_property_simple:n #1 { \tl_set:Nn \l__acro_tmpa_tl {#1} \tl_replace_all:Nnn \l__acro_tmpa_tl {-} {_} - \tl_clear_new:c {l__acro_ \l__acro_tmpa_tl _tl} \acro_declare_property:Vn \l__acro_tmpa_tl {#1} } @@ -3754,42 +3739,42 @@ \acro_for_endings_do:n { \prop_put:cnn {l__acro_long_##1_form_prop} {#1} {false} - \bool_if:cF {l__acro_#1_long-##1_set_bool} + \acro_property_if_set:nnF {#1} {long-##1} { \prop_put:cnv {l__acro_long_##1_prop} {#1} {l__acro_default_long_##1_tl} } \prop_put:cnn {l__acro_foreign_##1_form_prop} {#1} {false} - \bool_if:cF {l__acro_#1_foreign-##1_set_bool} + \acro_property_if_set:nnF {#1} {foreign-##1} { \prop_put:cnv {l__acro_foreign_##1_prop} {#1} {l__acro_default_foreign_##1_tl} } } } -\acro_declare_simple_property:n {first-style} +\acro_declare_property_simple:n {first-style} % list: -\acro_declare_simple_property:n {list} +\acro_declare_property_simple:n {list} % defines `short-plural', `long-plural' and `long-plural-form' as well as the % options `plural-ending', `short-plural-ending' and `long-plural-ending': % \ProvideAcroEnding {plural} {s} {s} % short indefinite article: -\acro_declare_simple_property:n {short-indefinite} +\acro_declare_property_simple:n {short-indefinite} % long indefinite article: -\acro_declare_simple_property:n {long-indefinite} +\acro_declare_property_simple:n {long-indefinite} % pre long: -\acro_declare_simple_property:n {long-pre} +\acro_declare_property_simple:n {long-pre} % post long: -\acro_declare_simple_property:n {long-post} +\acro_declare_property_simple:n {long-post} % post: -\acro_declare_simple_property:n {post} +\acro_declare_property_simple:n {post} % sort: \acro_declare_property:nnn {sort} {sort} { - \bool_if:cF { l__acro_#1_index-sort_set_bool } + \acro_property_if_set:nnF {#1} {index-sort} { \prop_put:Nnn \l__acro_index_sort_prop {#1} {#2} } } @@ -3803,36 +3788,35 @@ \cs_set_protected:Npn \acro_alt_error:n #1 { - \bool_if:cF {l__acro_#1_alt_set_bool} + \acro_property_if_set:nnF {#1} {alt} { \acro_harmless_message:nn {no-alternative} {#1} } } % alt. indefinite article: -\acro_declare_simple_property:n {alt-indefinite} +\acro_declare_property_simple:n {alt-indefinite} % foreign: -\acro_declare_simple_property:n {foreign} +\acro_declare_property_simple:n {foreign} % foreign-lang: -\acro_declare_simple_property:n {foreign-lang} +\acro_declare_property_simple:n {foreign-lang} % format: -\acro_declare_simple_property:n {format} +\acro_declare_property_simple:n {format} % short format: \acro_declare_property_alias:nn {short-format} {format} % alt format: -\acro_declare_simple_property:n {alt-format} +\acro_declare_property_simple:n {alt-format} % long format: -\acro_declare_simple_property:n {long-format} +\acro_declare_property_simple:n {long-format} % first long format: -\acro_declare_simple_property:n {first-long-format} +\acro_declare_property_simple:n {first-long-format} % pdfstring -- currently needs to be done `by hand': -\prop_new:N \l__acro_pdfstring_short_prop \cs_new_protected:Npn \__acro_declare_pdfstring:nw #1#2/#3/#4 \acro_stop: { \__acro_property_check:nn {#1} {pdfstring} @@ -3850,17 +3834,17 @@ } } } -\cs_generate_variant:Nn \__acro_declare_pdfstring:nw { V } -\keys_define:nn { acro / declare-acronym } +\cs_generate_variant:Nn \__acro_declare_pdfstring:nw {V} + +\keys_define:nn {acro/declare-acronym} { pdfstring .code:n = - \__acro_declare_pdfstring:Vw \l__acro_current_property_tl #1 // \acro_stop: , + \__acro_declare_pdfstring:Vw \l__acro_current_id_str #1 // \acro_stop: } -\prop_new:N \l__acro_pdfstring_alt_prop \cs_new_protected:Npn \__acro_declare_pdfstring_alt:nw #1#2/#3/#4 \acro_stop: { - \__acro_property_check:nn {#1} { pdfstring-alt } + \__acro_property_check:nn {#1} {pdfstring-alt} \prop_put:Nnn \l__acro_pdfstring_alt_prop {#1} {#2} \acro_for_endings_do:n { @@ -3872,70 +3856,87 @@ { \prop_put:cnn {l__acro_pdfstring_alt_##1_prop} {#1} {#2#3} } } } -\cs_generate_variant:Nn \__acro_declare_pdfstring_alt:nw { V } -\keys_define:nn { acro / declare-acronym } +\cs_generate_variant:Nn \__acro_declare_pdfstring_alt:nw {V} + +\keys_define:nn {acro/declare-acronym} { pdfstring-alt .code:n = - \__acro_declare_pdfstring_alt:Vw \l__acro_current_property_tl #1 // \acro_stop: , + \__acro_declare_pdfstring_alt:Vw \l__acro_current_id_str #1 // \acro_stop: } % class: -\acro_declare_simple_property:n {class} +\acro_declare_property_simple:n {class} % extra information: -\acro_declare_simple_property:n {extra} +\acro_declare_property_simple:n {extra} % single appearances: -\acro_declare_simple_property:n {single} +\acro_declare_property_simple:n {single} % single format: -\acro_declare_simple_property:n {single-format} +\acro_declare_property_simple:n {single-format} % acc supp: \acro_declare_property:nn {acc_supp} {accsupp} % tooltip: -\acro_declare_simple_property:n {tooltip} +\acro_declare_property_simple:n {tooltip} -% citation -- currently needs to be done `by hand': -\prop_new:N \l__acro_citation_prop -\prop_new:N \l__acro_citation_pre_prop -\prop_new:N \l__acro_citation_post_prop +% before-citation: +\acro_declare_property_simple:n {before-citation} + +% after-citation: +\acro_declare_property_simple:n {after-citation} + +% citation -- this needs a bit more work: \cs_new_protected:Npn \__acro_declare_citation:nw #1#2[#3]#4[#5]#6#7 \acro_stop: { - % no options: #1: ID, #2: property, #3 is blank - % 1 option: #1: ID, #4: property, #3: option, #5 is blank + % no options: #1: ID, #2: property, #7 is blank + % 1 option: #1: ID, #4: property, #3: option, #5: \q_no_value % 2 options: #1: ID: #6: property, #3: first option, #5: second option - \tl_if_blank:nF { #2#4#6 } + \tl_if_blank:nTF {#7} { - \tl_if_empty:nTF {#3} - { \__acro_declare_citation_aux:nnnn {#1} { } { } {#2} } + \__acro_declare_citation_aux:nnnn {#1} + { \q_no_value } + { \q_no_value } + {#2} + } + { + \quark_if_no_value:nTF {#5} { - \tl_if_empty:nTF {#5} - { \__acro_declare_citation_aux:nnnn {#1} {#3} { } {#4} } - { \__acro_declare_citation_aux:nnnn {#1} {#3} {#5} {#6} } + \__acro_declare_citation_aux:nnnx {#1} + { \q_no_value } + {#3} + { \tl_head:n {#4} } } + { \__acro_declare_citation_aux:nnnn {#1} {#3} {#5} {#6} } } } -\cs_generate_variant:Nn \__acro_declare_citation:nw { V } +\cs_generate_variant:Nn \__acro_declare_citation:nw {V} -\keys_define:nn { acro / declare-acronym } +\keys_define:nn {acro/declare-acronym} { cite .code:n = \__acro_declare_citation:Vw - \l__acro_current_property_tl #1 [][] \scan_stop: \acro_stop: + \l__acro_current_id_str #1 [\q_no_value][\q_no_value] \scan_stop: \acro_stop: } - +\prop_gput:Nnn \g__acro_properties_prop {cite} {cite} + +% #1: ID +% #2: pre +% #3: post +% #4: citation key \cs_new_protected:Npn \__acro_declare_citation_aux:nnnn #1#2#3#4 { \__acro_property_check:nn {#1} {cite} \prop_put:Nnn \l__acro_citation_prop {#1} {#4} - \tl_if_empty:nF {#2} + \quark_if_no_value:nF {#2} { \prop_put:Nnn \l__acro_citation_pre_prop {#1} {#2} } - \tl_if_empty:nF {#3} + \quark_if_no_value:nF {#3} { \prop_put:Nnn \l__acro_citation_post_prop {#1} {#3} } } - +\cs_generate_variant:Nn \__acro_declare_citation_aux:nnnn {nnnx} + % TODO: % add index entries, by default \index{@} % index: overwrite default @ entry completely @@ -3949,13 +3950,13 @@ % TeX code after an acronym is typeset % index: -\acro_declare_simple_property:n {index} +\acro_declare_property_simple:n {index} % index-sort: -\acro_declare_simple_property:n {index-sort} +\acro_declare_property_simple:n {index-sort} % index-cmd: -\acro_declare_simple_property:n {index-cmd} +\acro_declare_property_simple:n {index-cmd} % -------------------------------------------------------------------------- % acronym macros: @@ -3976,13 +3977,16 @@ % -------------------------------------------------------------------------- % internal acronym declaring function: \cs_new_protected:Npn \acro_declare_acronym:nn #1#2 + { \acro_case_insensitive:Nnn \__acro_declare_acronym:nn {#1} {#2} } + +\cs_new_protected:Npn \__acro_declare_acronym:nn #1#2 { \seq_gput_right:Nn \g__acro_declared_acronyms_seq {#1} \bool_gset_true:N \g__acro_first_acronym_declared_bool - \tl_set:Nn \l__acro_current_property_tl {#1} + \str_set:Nn \l__acro_current_id_str {#1} \acro_for_properties_do:n - { \bool_new:c {l__acro_#1_##1_set_bool} } - \keys_set:nn { acro / declare-acronym } {#2} + { \bool_new:c {l__acro_ \l__acro_current_id_str _##1_set_bool} } + \keys_set:nn {acro/declare-acronym} {#2} \bool_new:c {g__acro_#1_first_use_bool} \bool_new:c {g__acro_#1_used_bool} \bool_new:c {g__acro_#1_label_bool} @@ -3993,27 +3997,20 @@ { \bool_gset_true:c {g__acro_#1_in_list_bool} } \__acro_create_page_records:n {#1} \__acro_define_acronym_macro:n {#1} - \tl_clear:N \l__acro_current_property_tl - \bool_if:cF {l__acro_#1_short_set_bool} + \str_clear:N \l__acro_current_id_str + \acro_property_if_set:nnF {#1} {short} { \acro_serious_message:nnn {missing} {#1} {short} } - \bool_if:cF {l__acro_#1_long_set_bool} + \acro_property_if_set:nnF {#1} {long} { \acro_serious_message:nnn {missing} {#1} {long} } \__acro_log_acronym:n {#1} } -% -------------------------------------------------------------------------- -% the user command: -\NewDocumentCommand \DeclareAcronym {mm} - { \acro_declare_acronym:nn {#1} {#2} } - + % -------------------------------------------------------------------------- % print the list: % #1: list of classes % #2: list of excluded classes -\tl_new:N \l__acro_included_classes_tl -\tl_new:N \l__acro_excluded_classes_tl - -\keys_define:nn { acro / print-acronyms } +\keys_define:nn {acro/print-acronyms} { include-classes .tl_set:N = \l__acro_included_classes_tl , exclude-classes .tl_set:N = \l__acro_excluded_classes_tl , @@ -4032,7 +4029,8 @@ \cs_set:Npn \@noitemerr {} \tl_clear:N \l__acro_included_classes_tl \tl_clear:N \l__acro_excluded_classes_tl - \keys_set:nn { acro / print-acronyms } {#1} + \tl_if_blank:nF {#1} + { \keys_set:nn {acro/print-acronyms} {#1} } \__acro_aux_file_now:n { \acro@print@list } \bool_if:NT \l__acro_sort_bool { \acro_sort_prop:NN \l__acro_short_prop \l__acro_sort_prop } @@ -4050,9 +4048,6 @@ \group_end: } -\NewDocumentCommand \printacronyms { O{} } - { \acro_print_acronyms:n {#1} } - % -------------------------------------------------------------------------- % language support \RequirePackage {translations} @@ -4088,10 +4083,6 @@ } } -\NewDocumentCommand \DeclareAcroTranslation {mm} - { \acro_declare_translation:nn {#1} {#2} } -\@onlypreamble \DeclareAcroTranslation - % tokenlists using the translations: \tl_set:Nn \l__acro_list_name_tl { \GetTranslation {acronym-list-name} } \tl_set:Nn \l__acro_page_name_tl { \GetTranslation {acronym-page-name}\@\, } @@ -4101,478 +4092,27 @@ % -------------------------------------------------------------------------- % definition file: -% \tl_const:Nn \c_acro_definition_file_name_tl {acro} -% \tl_const:Nn \c_acro_definition_file_extension_tl {def} - -% \file_if_exist:nTF -% { \c_acro_definition_file_name_tl .\c_acro_definition_file_extension_tl } -% { -% \@onefilewithoptions -% {\c_acro_definition_file_name_tl} [] [] -% \c_acro_definition_file_extension_tl -% } -% { \acro_serious_message:n {definitions-missing} } - - -% -------------------------------------------------------------------------- -% first appearance styles: -\DeclareAcroFirstStyle {default} {inline} - { } - -\DeclareAcroFirstStyle {reversed} {inline} - { reversed = true } - -\DeclareAcroFirstStyle {short} {inline} - { - only-short = true , - brackets = false - } - -\DeclareAcroFirstStyle {long} {inline} - { - only-long = true , - brackets = false - } - -\DeclareAcroFirstStyle {square} {inline} - { brackets-type = [] } - -\DeclareAcroFirstStyle {plain} {inline} - { - brackets = false , - between = -- - } - -\DeclareAcroFirstStyle {plain-reversed} {inline} - { - brackets = false , - between = -- , - reversed = true - } - -\DeclareAcroFirstStyle {footnote} {note} - { } - -\DeclareAcroFirstStyle {footnote-reversed} {note} - { reversed = true } - -\DeclareAcroFirstStyle {sidenote} {note} - { note-command = \sidenote {#1} } - -\DeclareAcroFirstStyle {sidenote-reversed} {note} - { - note-command = \sidenote {#1} , - reversed = true - } - -\DeclareAcroFirstStyle {empty} {note} - { use-note = false } - -% -------------------------------------------------------------------------- -% extra info appearance styles: -\DeclareAcroExtraStyle {default} {inline} - { - brackets = false , - punct = true , - punct-symbol = . - } - -\DeclareAcroExtraStyle {plain} {inline} - { - brackets = false , - punct = true , - punct-symbol = - } - -\DeclareAcroExtraStyle {paren} {inline} - { - brackets = true , - punct = true , - punct-symbol = - } - -\DeclareAcroExtraStyle {bracket} {inline} - { - brackets = true , - punct = true , - punct-symbol = , - brackets-type = [] - } - -\DeclareAcroExtraStyle {comma} {inline} - { - punct = true, - punct-symbol = {,} , - brackets = false - } - -% -------------------------------------------------------------------------- -% page number appearance styles: -\DeclareAcroPageStyle {default} {inline} - { - punct = true , - punct-symbol = . - } - -\DeclareAcroPageStyle {plain} {inline} - { punct = false } - -\DeclareAcroPageStyle {comma} {inline} - { punct = true } - -\DeclareAcroPageStyle {paren} {inline} - { - brackets=true , - punct-symbol = ~ - } - -\DeclareAcroPageStyle {none} {inline} - { display = false } - -% -------------------------------------------------------------------------- -% list heading styles: -\DeclareAcroListHeading {part} {\part} -\DeclareAcroListHeading {part*} {\part*} -\DeclareAcroListHeading {chapter} {\chapter} -\DeclareAcroListHeading {chapter*} {\chapter*} -\DeclareAcroListHeading {addchap} {\addchap} -\DeclareAcroListHeading {section} {\section} -\DeclareAcroListHeading {section*} {\section*} -\DeclareAcroListHeading {addsec} {\addsec} -\DeclareAcroListHeading {subsection} {\subsection} -\DeclareAcroListHeading {subsection*} {\subsection*} -\DeclareAcroListHeading {subsubsection} {\subsubsection} -\DeclareAcroListHeading {subsubsection*} {\subsubsection*} -\DeclareAcroListHeading {none} {\use_none:n} - -% -------------------------------------------------------------------------- -% list styles: -\DeclareAcroListStyle {description} {list} - { } - -\DeclareAcroListStyle {toc} {list-of} - { } - -\DeclareAcroListStyle {lof} {list-of} - { style = lof } - -\DeclareAcroListStyle {tabular} {table} - { table = tabular } - -\DeclareAcroListStyle {longtable} {table} - { table = longtable } +\tl_const:Nn \c_acro_definition_file_name_tl {acro.definitions} +\tl_const:Nn \c_acro_definition_file_extension_tl {tex} -\DeclareAcroListStyle {extra-tabular} {extra-table} - { table = tabular } - -\DeclareAcroListStyle {extra-longtable} {extra-table} - { table = longtable } - -\DeclareAcroListStyle {extra-tabular-rev} {extra-table} - { - table = tabular , - reverse = true - } - -\DeclareAcroListStyle {extra-longtable-rev} {extra-table} - { - table = longtable , - reverse = true - } - -% -------------------------------------------------------------------------- -% register some tokens to be checked for: -\AcroRegisterTrailing . {dot} -\AcroRegisterTrailing - {dash} -\AcroRegisterTrailing \babelhyphen {babel-hyphen} - -\keys_set:nn {acro} { activate-trailing-tokens = dot } - -% -------------------------------------------------------------------------- -% the user commands -% automatic: -\NewAcroCommand \ac - { \acro_use:n {#1} } - -\NewAcroCommand \Ac - { - \acro_first_upper: - \acro_use:n {#1} - } - -\NewAcroCommand \iac - { - \acro_indefinite: - \acro_use:n {#1} - } - -\NewAcroCommand \Iac - { - \acro_first_upper: - \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 \acsingle - { - \acro_get:n {#1} - \acro_single:n {#1} - } - -\NewAcroCommand \Acsingle - { - \acro_get:n {#1} - \acro_first_upper: - \acro_single:n {#1} - } - -% short: -\NewAcroCommand \acs - { \acro_short:n {#1} } - -\NewAcroCommand \Acs - { - \acro_first_upper: - \acro_short:n {#1} - } - -\NewAcroCommand \iacs - { - \acro_indefinite: - \acro_short:n {#1} - } - -\NewAcroCommand \Iacs - { - \acro_first_upper: - \acro_indefinite: - \acro_short:n {#1} - } - -\NewAcroCommand \acsp - { - \acro_plural: - \acro_short:n {#1} - } - -\NewAcroCommand \Acsp - { - \acro_first_upper: - \acro_plural: - \acro_short:n {#1} - } - -% alt: -\NewAcroCommand \aca - { \acro_alt:n {#1} } - -\NewAcroCommand \Aca - { - \acro_first_upper: - \acro_alt:n {#1} - } - -\NewAcroCommand \iaca - { - \acro_indefinite: - \acro_alt:n {#1} - } - -\NewAcroCommand \Iaca - { - \acro_first_upper: - \acro_indefinite: - \acro_alt:n {#1} - } - -\NewAcroCommand \acap - { - \acro_plural: - \acro_alt:n {#1} - } - -\NewAcroCommand \Acap - { - \acro_first_upper: - \acro_plural: - \acro_alt:n {#1} - } - -% long: -\NewAcroCommand \acl - { \acro_long:n {#1} } - -\NewAcroCommand \Acl - { - \acro_first_upper: - \acro_long:n {#1} - } - -\NewAcroCommand \iacl - { - \acro_indefinite: - \acro_long:n {#1} - } - -\NewAcroCommand \Iacl - { - \acro_first_upper: - \acro_indefinite: - \acro_long:n {#1} - } - -\NewAcroCommand \aclp - { - \acro_plural: - \acro_long:n {#1} - } - -\NewAcroCommand \Aclp - { - \acro_plural: - \acro_first_upper: - \acro_long:n {#1} - } - -% first: -\NewAcroCommand \acf - { \acro_first:n {#1} } - -\NewAcroCommand \Acf - { - \acro_first_upper: - \acro_first:n {#1} - } - -\NewAcroCommand \iacf - { - \acro_indefinite: - \acro_first:n {#1} - } - -\NewAcroCommand \Iacf - { - \acro_first_upper: - \acro_indefinite: - \acro_first:n {#1} - } - -\NewAcroCommand \acfp +\file_if_exist:nTF + { \c_acro_definition_file_name_tl .\c_acro_definition_file_extension_tl } { - \acro_plural: - \acro_first:n {#1} - } - -\NewAcroCommand \Acfp - { - \acro_plural: - \acro_first_upper: - \acro_first:n {#1} - } - -% first-like: -\NewPseudoAcroCommand \acflike - { \acro_first_like:nn {#1} {#2} } - -\NewPseudoAcroCommand \iacflike - { - \acro_indefinite: - \acro_first_like:nn {#1} {#2} - } - -\NewPseudoAcroCommand \Iacflike - { - \acro_first_upper: - \acro_indefinite: - \acro_first_like:nn {#1} {#2} - } - -\NewPseudoAcroCommand \acfplike - { - \acro_plural: - \acro_first_like:nn {#1} {#2} - } - -% -------------------------------------------------------------------------- -% endings: -\ProvideAcroEnding {plural} {s} {s} - -% -------------------------------------------------------------------------- -% translations: -% list name -\DeclareAcroTranslation {acronym-list-name} - { - Fallback = Acronyms , - English = Acronyms , - French = Acronymes , - German = Abk\"urzungen , - Italian = Acronimi , - Portuguese = Acr\'onimos , - Spanish = Siglas , - Catalan = Sigles , - Turkish = K\i saltmalar - } - -% page name -\DeclareAcroTranslation {acronym-page-name} - { - Fallback = p. , - English = p. , - German = S. , - Portuguese = p. - } - -% pages name -\DeclareAcroTranslation {acronym-pages-name} - { - Fallback = pp. , - English = pp. , - German = S. , - Portuguese = pp. - } - -% following page -\DeclareAcroTranslation {acronym-next-page} - { - Fallback = f. , - English = f. , - German = f. , - Portuguese = s. - } - -% following pages -\DeclareAcroTranslation {acronym-next-pages} - { - Fallback = ff. , - English = ff. , - German = ff. , - Portuguese = ss. + \@onefilewithoptions + {\c_acro_definition_file_name_tl} [] [] + \c_acro_definition_file_extension_tl } + { \acro_serious_message:n {definitions-missing} } % -------------------------------------------------------------------------- % allow for a configuration file: -\tl_const:Nn \c_acro_config_file_name_tl {acro} -\tl_const:Nn \c_acro_config_file_extension_tl {cfg} \file_if_exist:nT - { \c_acro_config_file_name_tl .\c_acro_config_file_extension_tl } + { \l_acro_config_file_name_tl . \l_acro_config_file_extension_tl } { \@onefilewithoptions - {\c_acro_config_file_name_tl} [] [] - \c_acro_config_file_extension_tl + {\l_acro_config_file_name_tl} [] [] + \l_acro_config_file_extension_tl } \file_input_stop: diff --git a/macros/latex/contrib/acro/acro_en.pdf b/macros/latex/contrib/acro/acro_en.pdf deleted file mode 100644 index eee6eaed49..0000000000 Binary files a/macros/latex/contrib/acro/acro_en.pdf and /dev/null differ diff --git a/macros/latex/contrib/acro/acro_en.tex b/macros/latex/contrib/acro/acro_en.tex deleted file mode 100644 index 9aaea47d3c..0000000000 --- a/macros/latex/contrib/acro/acro_en.tex +++ /dev/null @@ -1,2185 +0,0 @@ -% arara: pdflatex: { interaction: nonstopmode } -% arara: biber -% arara: pdflatex: { interaction: nonstopmode } -% arara: pdflatex: { interaction: nonstopmode } -% !arara: pdflatex: { interaction: nonstopmode } -% -------------------------------------------------------------------------- -% the ACRO package -% -% Typeset Acronyms -% -% -------------------------------------------------------------------------- -% Clemens Niederberger -% Web: http://www.mychemsitry.eu/forums/forum/acro/ -% E-Mail: contact@mychemistry.eu -% -------------------------------------------------------------------------- -% Copyright 2011--2019 Clemens Niederberger -% -% This work may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.3 -% of this license or (at your option) any later version. -% The latest version of this license is in -% http://www.latex-project.org/lppl.txt -% and version 1.3 or later is part of all distributions of LaTeX -% version 2005/12/01 or later. -% -% This work has the LPPL maintenance status `maintained'. -% -% The Current Maintainer of this work is Clemens Niederberger. -% -------------------------------------------------------------------------- -% The acro package consists of the files -% - acro.sty, acro_en.tex, acro_en.pdf, README -% -------------------------------------------------------------------------- -% If you have any ideas, questions, suggestions or bugs to report, please -% feel free to contact me. -% -------------------------------------------------------------------------- -\documentclass[load-preamble+]{cnltx-doc} - -\usepackage[utf8]{inputenc} -\usepackage[single,macros,accsupp,index]{acro} -\setcnltx{ - package = {acro} , - info = {Typeset Acronyms and other Abbreviations} , - authors = Clemens Niederberger , - email = contact@mychemistry.eu , - url = https://bitbucket.org/cgnieder/acro/ , - abstract = {% - \acro\ allows you to define and use abbreviations in a simple way. - Abbreviations can be divided into different classes of abbreviations. - Lists of abbreviations can be created (also of separate classes of - abbreviations) and printed wherever you want the lists to appear.\par - \acro\ provides an option \option{single} which ignores abbreviations that - are used only once in the whole document.\par - As an experimental feature \acro\ also offers the option \option{sort} which - automatically sorts the list created by \cs{printacronyms}.\par - \acro\ also has the feature of creating \emph{local} lists - } , - add-cmds = { - ac, Ac, aca, Aca, acap, Acap, acbarrier, acdot, acf, Acf, acflike, acg, - acfp, Acfp, acfplike, aciftrailing, acl, Acl, aclp, Aclp, acp, Acp, - AcroRegisterTrailing, acs, Acs, acsingle, Acsingle, acsp, Acsp, acspace, - acreset, acresetall, acsetup, - DeclareAcroCommand, DeclareAcronym, DeclareAcroExtraStyle, - DeclareAcroFirstStyle, DeclareAcroListHeading, - DeclareAcroListStyle, DeclareAcroPageStyle, DeclarePseudoAcroCommand, - iac, Iac, iaca, Iaca, iacs, Iacs, iacl, Iacl, iacf, Iacf, iacflike, - Iacflike, - NewAcroCommand, NewPseudoAcroCommand, - printacronyms, - ProvideAcroCommand, ProvideAcroEnding, ProvidePseudoAcroCommand, - RenewAcroCommand, RenewPseudoAcroCommand - } , - add-silent-cmds = { - addcolon, DeclareInstance, babelhyphen, ExplSyntaxOff, ExplSyntaxOn, nato, - NewDocumentCommand, newlist, ny, setlist - } , - index-setup = { level = \section , headers={\indexname}{\indexname} } -} - -\acsetup{ - use-barriers = true , - hyperref = true , - log -} - -\usepackage{varioref} - -\defbibheading{bibliography}{\section{References}} - -\usepackage{csquotes} - -\usepackage[biblatex]{embrac}[2012/06/29] -\ChangeEmph{[}[,.02em]{]}[.055em,-.08em] -\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] - -\usepackage{filecontents} - -\addbibresource{\jobname.bib} -\begin{filecontents}{\jobname.bib} -@online{wikipedia, - author = {Wikipedia}, - title = {Acronym and initialism}, - urldate = {2012-06-21}, - url = {http://en.wikipedia.org/wiki/Acronyms}, - year = {2012} -} -@online{NewYork, - author = {Wikipedia}, - title = {New York City}, - urldate = {2012-09-27}, - url = {http://en.wikipedia.org/wiki/New_York_City}, - year = {2012} -} -@manual{interface3, - author = {{The \LaTeX3 Project Team}} , - shorthand = {L3P} , - sortname = {LaTeX3 Project Team} , - title = {The \LaTeX3 Interfaces} , - date = {2015-09-06} , - url = {http://mirrors.ctan.org/macros/latex/contrib/l3kernel/interface3.pdf} -} -\end{filecontents} - -% additional packages: -\usepackage{longtable,array,booktabs,enumitem,amssymb} - -\newcommand*\wikipedia{%\libertineGlyph{W.alt}\kern-.055em -\textsc{Wikipedia}} -\newcommand*\h[1]{\textcolor{cnltx}{\textbf{#1}}} - -\ProvideAcroEnding {possessive} {'s} {'s} - -% declare acronyms -\DeclareAcronym{cd} - { - short = cd , - long = Compact Disc , - short-format = \scshape - } -\let\ctan\relax -\DeclareAcronym{ctan} - { - short = ctan , - long = Comprehensive \TeX\ Archive Network , - format = \scshape , - pdfstring = CTAN , - accsupp = CTAN - } -\def\ctan{\acs{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 - } -\let\lppl\relax -\DeclareAcronym{lppl} - { - short = lppl , - long = \LaTeX\ Project Public License , - format = \scshape , - pdfstring = LPPL , - accsupp = LPPL , - index-cmd = \csname @gobble\endcsname - } -\def\lppl{\acs{lppl}} -\DeclareAcronym{MP} - { - short = MP , - long = Member of Parliament , - long-plural-form = Members of Parliament - } -\DeclareAcronym{nato} - { - short = nato , - long = North Atlantic Treaty Organization , - extra = \emph{deutsch}: Organisation des Nordatlantikvertrags , - short-format = \scshape - } -\DeclareAcronym{ny} - { - short = NY , - short-plural = , - long = New York , - long-plural = , - class = city , - cite = NewYork - } -\DeclareAcronym{ot} - { - short = ot , - long = Other Test , - short-format = \scshape - } -\DeclareAcronym{pdf} - { - short = pdf , - long = Portable Document Format , - format = \scshape , - pdfstring = PDF , - accsupp = PDF - } -\DeclareAcronym{sw} - { - short = SW , - long = Sammelwerk , - long-plural = e - } -\DeclareAcronym{test} - { - short = ST , - long = Some Test - } -\DeclareAcronym{tex.sx} - { - short = \TeX.sx , - sort = TeX.sx , - long = \TeX{} StackExchange - } -\DeclareAcronym{ufo}{ - short = UFO , - long = unidentified flying object , - long-indefinite = an -} - - -\makeatletter -\protected\def\@versionstar{\raisebox{-.25em}{*}} -\newcommand\versionstar{\texorpdfstring{\@versionstar}{*}} -\makeatother - -\newcommand*\latin{\textit} - -\makeatletter -\newcommand*\TF{\textcolor{red}{\uline{\code{\textcolor{cs}{\textit{TF}}}}}} -\renewenvironment{commands} - {% - \cnltx@set@catcode_{12}% - \let\command\cnltx@command - \cnltxlist - } - {\endcnltxlist} -\makeatother - -\newcommand*\mailto[1]{\texttt{\href{mailto:#1}{#1}}} - -\begin{document} -\section{Licence and Requirements} -\license - -\acro\ loads and needs the following packages: -\pkg{expl3}\footnote{\CTANurl{l3kernel}}, \pkg{xparse}, \pkg{xtemplate}, -\pkg{l3keys2e}\footnote{\CTANurl{l3packages}}, -\pkg{zref-abspage}\footnote{\CTANurl{oberdiek}} and -\needpackage{translations}~\cite{pkg:translations}. - - - -\section{Basics} -\subsection{Creating New Acronyms} -Acronyms are created with the command \cs{DeclareAcronym}. -\begin{commands} - \command{DeclareAcronym}[\marg{id}\marg{list of keys}] - The basic command for declaring an acronym. -\end{commands} -This command understands a number of keys which are listed below. Some of -them are not described immediately but at appropriate places in the -documentation. -\begin{options} - %% short - \keyval{short}{text}\Default! - The short form of the acronym. This option is required: an acronym must - have a short form. If this is set it \emph{must} be set as first option! - If another option is set first and notices the \option{short} option - missing it assumes that the \acs{id} should be used as short version and - sets it accordingly. A warning will be written to the log then. - %% long - \keyval{long}{text}\Default! - The long form of the acronym. This option is required: an acronym must - have a description. - %% short-plural - \keyval{short-plural}{text}\Default{s} - The plural ending appended to the short form. - %% short-plural-form - \keyval{short-plural-form}{text} - The\sinceversion{2.0} plural short form of the acronym; replaces the short - form when used instead of appending the plural ending. - %% long-plural - \keyval{long-plural}{text}\Default{s} - The plural ending appended to the long form. - %% long-plural-form - \keyval{long-plural-form}{text} - Plural long form of the acronym; replaces the long form when used - instead of appending the plural ending. - %% alt-plural - \keyval{alt-plural}{text}\Default{s} - The\sinceversion{2.0} plural ending appended to the alternative form. - %% alt-plural-form - \keyval{alt-plural-form}{text} - The\sinceversion{2.0} plural alternative form of the acronym; replaces the - alternative form when used instead of appending the plural ending. - %% foreign-plural - \keyval{foreign-plural}{text}\Default{s} - The\sinceversion{2.9} plural ending appended to the foreign form. - %% foreign-plural-form - \keyval{foreign-plural-form}{text} - Plural\sinceversion{2.9} lforeign form of the acronym; replaces the - foreign form when used instead of appending the plural ending. - %% list - \keyval{list}{text} - If specified this will be written in the list as description instead of - the long form. - %% short-indefinite - \keyval{short-indefinite}{text}\Default{a} - Indefinite article for the short form. - %% long-indefinite - \keyval{long-indefinite}{text}\Default{a} - Indefinite article for the long form. - %% long-pre - \keyval{long-pre}{text} - \meta{text} is prepended to the long form in the text but not in the list - of acronyms. - %% long-post - \keyval{long-post}{text} - \meta{text} is appended to the long form in the text but not in the list - of acronyms. - %% long-post - \keyval{post}{text} - \meta{text}\sinceversion{2.8} is appended to the acronym in the text but - not in the list of acronyms. - %% alt - \keyval{alt}{text} - Alternative short form. - %% alt-indefinite - \keyval{alt-indefinite}{text}\Default{a} - Indefinite article for the alternative form. - %% extra - \keyval{extra}{text} - Extra information to be added in the list of acronyms. - %% foreign - \keyval{foreign}{original long form} - Can be useful when dealing with acronyms in foreign languages, see - section~\vref{ssec:foreign} for details. - %% foreign-lang - \keyval{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 - \keyval{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 - \keyval{sort}{text} - If used the acronym will be sorted according to this key instead of its - \acs{id}. - %% class - \keyval{class}{csv list} - The\changedversion{2.4} class(es) the acronym belongs to. - %% cite - \keylit{cite}{\oarg{prenote}\oarg{postnote}\marg{citation keys}} - A citation that is printed to the acronym according to an option explained - later. - %% short-format - \keyval{short-format}{\TeX{} code} - The format used for the short form of the acronym. - %% long-format - \keyval{long-format}{\TeX{} code} - The format used for the long form of the acronym. - %% short-format - \keyval{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 - \keyval{first-long-format}{\TeX{} code} - The format used for the first long form of the acronym as set with \cs{ac}, - \cs{acf} or \cs{acflike} and their uppercase, plural and indefinite forms. - %% single-format - \keyval{single-format}{\TeX{} code} - \sinceversion{2.3}The format used for the acronym if the acronym is only - used a single time. - %% first-style - \keychoice{first-style}{default,empty,square,short,long,reversed,footnote,sidenote,% - footnote-reversed,sidenote-reversed} - \sinceversion{2.3}The style of the first appearance of the acronym, see - also section~\ref{sec:opti-regard-acronyms}. - %% pdfstring - \keylit{pdfstring}{\meta{text}/\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 - \keyval{accsupp}{text} - Sets the \code{ActualText} key as presented by the \pkg{accsupp} package - for the acronym. - %% tooltip - \keyval{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 - \keyval{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 \option{sort} key. This key allows to set an individual - sorting option for the index. See section~\vref{ssec:index} for details. - %% index - \keyval{index}{text} - This key allows to overwrite the automatic index entry with an arbitrary - one. See section~\vref{ssec:index} for details. - %% index-cmd - \keyval{index-cmd}{control sequence} - This key let's you set an individual index creating command for this - acronym. It should be a command that takes one mandatory argument. See - section~\vref{ssec:index} for details. -\end{options} - -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 \option{short} key \emph{must} -always be the \emph{first} key that is set. -\begin{sourcecode} - % preamble: - \DeclareAcronym{test}{ - short = ST , - long = Some Test - } -\end{sourcecode} -This creates the acronym ``\acs{test}'' with the \acs{id} ``test'' and the -long form ``\acl{test}.'' - -The \option{format} key allows you to choose a specific format for the short -form of an acronym: -\begin{sourcecode} - % preamble: - \DeclareAcronym{ot}{ - short = ot , - long = Other Test , - short-format = \scshape - } -\end{sourcecode} -The short form now looks like this: \acs{ot}. - -The \option{cite} key needs a bit explaining. It expects arguments like the -standard \cs*{cite} command, \latin{i.e.}, two optional arguments setting the -\meta{prenote} and \meta{postnote} and one mandatory argument setting the -citation key. -\begin{sourcecode} - % preamble: - \DeclareAcronym{ny}{ - short = NY , - short-plural = , - long = New York , - long-plural = , - cite = {NewYork} - } -\end{sourcecode} - -\begin{sourcecode}[sourcecode-options={style=cnltx-bibtex}] - % bib file for use with biber/biblatex: - @online{NewYork, - author = {Wikipedia}, - title = {New York City}, - urldate = {2012-09-27}, - url = {http://en.wikipedia.org/wiki/New_York_City}, - year = {2012} - } -\end{sourcecode} -The first appearance now looks as follows\footnote{The appearance of the - citation of course depends on the citation style you're using.}: \acf{ny}. - -\subsection{Logging of Acronyms} -When you activate \acro's option\sinceversion{2.5} \option{log} \acro' writes -information about the acronyms it defines to the log file. -\begin{options} - \keychoice{log}{\default{true},false,silent,verbose}\Default{false} - When set to \code{true}/\code{silent} \acro{} writes the main properties - of an acronym to the log file. When set to \code{verbose} \acro' writes - \emph{all} properties of an acronym to the log file. -\end{options} - -This is an example of the logging info with \keyis{log}{true} or -\keyis{log}{silent}. -\begin{sourcecode} - ================================================= - | Package acro Info -- defining new acronym: - | ID = {jpg} - | short = {JPEG} - | long = {Joint Photographic Experts Group} - | alt = {JPG} - | sort = {jpeg} - | class = {} - | list = {} - | extra = {} - | foreign = {} - | pdfstring = {} - | cite = {} - ================================================= -\end{sourcecode} - -\subsection{Using the Acronyms -- the Commands}\label{sec:using-acronyms-comm} -Acronyms are used with one of the following commands: -\begin{commands} - %% - \command{ac}[\sarg\marg{id}] - basic command; the first output is different from subsequent ones. - \command{Ac}[\sarg\marg{id}] - same as \cs{ac} but capitalizes the first letter. Obeys the option - \option{uppercase-short}. - %% - \command{acs}[\sarg\marg{id}] - \h{s}hort form; the actual acronym. - \command{Acs}[\sarg\marg{id}] - same\sinceversion{2.10} as \cs{acs} but capitalizes the first letter. - %% - \command{acl}[\sarg\marg{id}] - \h{l}ong form; the meaning of the acronym. - \command{Acl}[\sarg\marg{id}] - same as \cs{acl} but capitalizes first letter. - %% - \command{aca}[\sarg\marg{id}] - \h{a}lternative short form as specified in the \option{alt} key of - \cs{DeclareAcronym}; if it hasn't been specified this is identical to - \cs{acs}. - \command{Aca}[\sarg\marg{id}] - same\sinceversion{2.10} as \cs{aca} but capitalizes the first letter. - %% - \command{acf}[\sarg\marg{id}] - first form; output like the first time \cs{ac} is output. - \command{Acf}[\sarg\marg{id}] - same as \cs{acf} but capitalizes first letter. Obeys the option - \option{uppercase-short}. - %% - \command{acp}[\sarg\marg{id}] - \h{p}lural form of \cs{ac}; - \command{Acp}[\sarg\marg{id}] - same as \cs{acp} but capitalizes first letter. Obeys the option - \option{uppercase-short}. - %% - \command{acsp}[\sarg\marg{id}] - plural form of \cs{acs}; - \command{Acsp}[\sarg\marg{id}] - same\sinceversion{2.10} as \cs{acsp} but capitalizes the first letter. - %% - \command{aclp}[\sarg\marg{id}] - plural form of \cs{acl}; - \command{Aclp}[\sarg\marg{id}] - same as \cs{aclp} but capitalizes first letter. - %% - \command{acap}[\sarg\marg{id}] - plural form of \cs{aca}; - \command{Acap}[\sarg\marg{id}] - same\sinceversion{2.10} as \cs{acap} but capitalizes the first letter. - %% - \command{acfp}[\sarg\marg{id}] - plural form of \cs{acf}; - \command{Acfp}[\sarg\marg{id}] - same as \cs{acfp} but capitalizes first letter of the long form. Obeys - the option \option{uppercase-short}. -\end{commands} -If an acronym is used the first time with \cs{ac} its output is different from -subsequent uses. To be clear on this: the first time! If the acronym has -been used with \emph{any} of the output commands before it is \emph{not} the -first time any more. - -If you use the starred variant an acronym will not be marked as used. This -proves useful if an acronym is typeset in a section title, for example, since -then the appearance in the table of contents won't mark it as used. - -\begin{example}[side-by-side] - % preamble: - % \DeclareAcronym{cd}{ - % short = cd , - % long = Compact Disc , - % short-format = \scshape - % } - first time: \ac{cd} \\ - second time: \ac{cd} \\ - short: \acs{cd} \\ - alternative: \aca{cd} \\ - first again: \acf{cd} \\ - long: \acl{cd} \\ - short plural: \acsp{cd} \\ - long plural: \aclp{cd} -\end{example} - -\subsection{Plural Forms} -If an acronym is defined in the standard way \acro\ uses an `s' that's appended -to both the short and the long form when one of the plural commands is used. -However, that is not always the best solution. For one thing not all acronyms -may have a plural form. Second, the plural form especially of the long forms -may be formed differently. And third, other languages can have other plural -endings. - -For these reasons \cs{DeclareAcronym} can get the following keys: -\begin{options} - \keyval{short-plural}{text}\Default{s} - The plural ending of the short form. - \keyval{long-plural}{text}\Default{s} - The plural ending of the long form. - \keyval{long-plural-form}{text} - An alternative plural form for the long form. -\end{options} -These keys are optional. If they're not used, the default setting is -\code{s}. If you use \option{long-plural-form} the long form will be replaced -by the specified plural form when necessary. - -Suppose we define the following acronyms: -\begin{sourcecode} - \DeclareAcronym{cd}{ - short = cd , - long = Compact Disc , - short-format = \scshape - } - \DeclareAcronym{ny}{ - short = NY , - short-plural = , - long = New York , - long-plural = - } - \DeclareAcronym{sw}{ - short = SW , - long = Sammelwerk , - long-plural = e - } - \DeclareAcronym{MP}{ - short = MP , - long = Member of Parliament , - long-plural-form = Members of Parliament - } -\end{sourcecode} -These acronyms now have the following plural appearances: -\begin{example}[side-by-side] - \acsp{cd}, \aclp{cd} \\ - \acsp{ny}, \aclp{ny} \\ - \acsp{sw}, \aclp{sw} \\ - \acsp{MP}, \aclp{MP} -\end{example} - -In the default setting the format of the long or short form is not extended to -the plural ending which might look strange if you choose bold weight as -format, for example. In this case you can tell \acro\ to extend the format. -\begin{options} - \keybool{format-include-endings}\Default{false} - Tell\sinceversion{2.8} \acro\ to use the format of the base form for the - endings, too. -\end{options} -For a more general view on endings please read section -\vref{sec:about-plural-forms}. - -\subsection{Alternative Short Forms} -For some acronyms it might be useful to have alternative forms. For this -\cs{DeclareAcronym} has another key: -\begin{options} - \keyval{alt}{text} - Alternative short form. -\end{options} -\begin{example} - % preamble: - % \DeclareAcronym{jpg}{ - % short = JPEG , - % sort = jpeg , - % alt = JPG , - % long = Joint Photographic Experts Group - % } - default: \acs{jpg} \\ - alt.: \aca{jpg} -\end{example} -The alternative form uses the same plural ending as the default short form and -is formatted in the same way. - -\subsection{Extra Information for the List Entry} -Of course you can print a list of acronyms where their meaning is explained. -Sometimes it can be useful to add additional information there. This is done -with another key to \cs{DeclareAcronym}: -\begin{options} - \keyval{extra}{text} - Additional information for the list of acronyms. -\end{options} -These information will only be displayed in the list. See -section~\vref{sec:print_lists} for the impact of the following example. - -\begin{example} - % preamble: - % \DeclareAcronym{nato}{ - % short = nato , - % long = North Atlantic Treaty Organization , - % extra = \textit{deutsch}: Organisation des Nordatlantikvertrags , - % short-format = \scshape - % } - The \ac{nato} is an intergovernmental military alliance based on the - North Atlantic Treaty which was signed on 4~April 1949. \ac{nato} - headquarters are in Brussels, Belgium, one of the 28 member states - across North America and Europe, the newest of which, Albania and - Croatia, joined in April 2009. -\end{example} - -\subsection{Foreign Language Acronyms}\label{ssec:foreign} -I repeatedly read the wish for being able to add translations to acronyms when -the acronyms stem from another language than the document language, -\latin{i.e.}, something like the following in a German document: -\begin{example}[side-by-side] - \ac{ecu}\\ - \ac{ecu} -\end{example} -That's why I decided to add the following properties: -\begin{options} - \keyval{foreign}{original long form} - A description for an acronym originating in another language than the - document language. - \keyval{foreign-lang}{language} - \sinceversion{2.3}The \pkg{babel}~\cite{pkg:babel} or - \pkg{polyglossia}~\cite{pkg:polyglossia} language of the foreign form. - This language is used to wrap the entry with - \cs*{foreignlanguage}\marg{language}. -\end{options} - -Here is the definition of the above mentioned \ac{ecu} acronym: -\begin{sourcecode} - \DeclareAcronym{ecu}{ - short = ECU , - long = Steuerger\"at , - foreign = Electronic Control Unit , - foreign-lang = english - } -\end{sourcecode} -As you have seen this adds the \option{foreign} entry to the first appearance -of an acronym. It is also added in parentheses to the list of acronyms after -the \option{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 keys \option{short-indefinite}, \option{alt-indefinite} and -\option{long-indefinite} whose default is \code{a}. For every lowercase -singular command two alternatives exist, preceded by \code{i} and \code{I}, -respectively, which output the lowercase and uppercase version of the -corresponding indefinite article. - -\begin{example} - % preamble: - % \DeclareAcronym{ufo}{ - % short = UFO , - % long = unidentified flying object , - % long-indefinite = an - % } - \Iac{ufo}; \iacs{ufo}; \iacl{ufo} -\end{example} - -\subsection{Uppercasing} -\begin{commands} - \command{acfirstupper}[\marg{token list}] - This command uppercases the first token in \meta{token list}. The - command is less powerful than \cs{makefirstuc} that is provided by the - \pkg{mfirstuc} package~\cite{pkg:mfirstuc} but it is expandable. Obvious - downsides are for example that it does not uppercase accented letters. -\end{commands} -The following options control the behaviour of the uppercasing commands: -\begin{options} - \keyval{uc-cmd}{control sequence}\Default{\cs{acfirstupper}} - The command that is used to capitalize the first word in the \cs{Ac} and - the like commands. You can change it to another one like for example - \cs*{makefirstuc}\footnote{from the \pkg{mfirstuc} package} or - \cs*{MakeTextUppercase}\footnote{from the \pkg*{textcase} package}. - %% - \keybool{uppercase-short}\Default{true} - If\sinceversion{2.10} set to \code{true} commands like \cs{Ac} or \cs{Acp} - will uppercase the first letter of the short form. Commands like \cs{Acs} - or \cs{Acsp} will uppercase the short form in any case. -\end{options} - -\subsection{Simulating the First Appearance}\label{sec:simul-first-appe} -Users told me\footnote{Well -- one, to be precise ;)} that there are cases -when it might be useful to have the the acronym typeset according to the -\option{first-style} but with another text than the long form. For such cases -\acro\ offers the following commands. -\begin{commands} - \command{acflike}[\sarg\marg{id}\marg{instead of long form}] - Write some alternative long form for acronym with \acs{id} \meta{id} as if - it were the first time the acronym was used. - \command{acfplike}[\sarg\marg{id}\marg{instead of long form}] - Plural form of \cs{acflike}. -\end{commands} - -\begin{example}[side-by-side] - \acsetup{first-style=footnote} - \acflike{ny}{the big apple} -\end{example} - -The plural ending in \cs{acfplike} is only appended to the short form. It -makes no sense to append it to the text that is inserted manually anyway. -Note that whatever text you're inserting might be gobbled depending on the -\option{first-style} you're using. - -\subsection{Fetching the Single Appearance} -There\sinceversion{2.3} are macros that fetch the \emph{single} appearance of -an acronym even if it has been used more than once and the \option{single} -option is active. -\begin{commands} - \command{acsingle}[\sarg\marg{id}] - Write acronym as if it were used only a single time. - \command{Acsingle}[\sarg\marg{id}] - Uppercase form of \cs{acsingle}. -\end{commands} - -\begin{example}[side-by-side] - \acsingle{ny} -\end{example} - -\subsection{Using Classes} -The acronyms of \acro\ can be divided into different classes. This doesn't -change the output but allows different acronym lists, see -section~\vref{sec:print_lists}. For this \cs{DeclareAcronym} has an additional -key: -\begin{options} - \keyval{class}{csv list} - Associated\changedversion{2.4} class(es) for an acronym. -\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}) -\end{example} - -\subsection{Reset or Mark as Used, Test if Acronym Has Been Used} - -If you want for some reason to fool \acro\ into thinking that an acronym is -used for the first time you can call one of these commands: -\begin{commands} - \command{acreset}[\marg{comma separated list of ids}] - This will reset a used acronym such that the next use of \cs{ac} will - again print it as if it were used the first time. This will \emph{not} - remove an acronym from being printed in the list if it actually \emph{has} - been used before. - \command{acresetall} - Reset all acronyms. - \command{acifused}[\marg{id}\marg{true}\marg{false}] - This command tests if the acronym with \ac{id} \meta{id} has already been - used and either puts \code{true} or \code{false} in the input stream. - \command{aciffirst}[\marg{true}\marg{false}] - To\sinceversion{2.8} be used inside of acronym definitions in order to - test if we are inside the first instance of the acronym or not. -\end{commands} -\begin{example}[side-by-side] - \acreset{ny}\ac{ny} -\end{example} -Beware that both commands act \emph{globally}! There are also commands that -effectively do the opposite of \cs{acreset}, \latin{i.e.}, mark acronyms as -used: -\begin{commands} - \command{acuse}[\marg{comma separated list of ids}] - This has the same effect as if an acronym had been used twice, that is, - further uses of \cs{ac} will print the short form and the acronym will in - any case be printed in the list (as long as its class is not excluded). - \command{acuseall} - Mark all acronyms as used. -\end{commands} -Then there are two further commands related to using acronyms: -\begin{commands} - \command{acswitchoff} - This\sinceversion{2.6} command is for patching in certain situations. For - example some table environments like \env*{tabularx} or \env*{tabu} pass - their content two or more times for determining the width of the table - columns. Those can be patched to add \cs{acswitchoff} to their trial - phase. - \command{acswitchon} - Effectively\sinceversion{2.6} the opposite of \cs{acswitchoff} -- this - command should probably never be needed. -\end{commands} - -\subsection{\cs*{ac} and Friends in \acs*{pdf} Bookmarks, Accessibility - Support, Tooltips} -\subsubsection{\acs*{pdf} Bookmarks} -\acro's commands usually are not expandable which means they'd leave unallowed -tokens in \acs{pdf} bookmarks. \pkg{hyperref} offers \cs*{texorpdfstring} to -circumvent that issue manually but that isn't really a nice solution. What's -the point of having macros to get output for you if you have to specify it -manually after all? - -That is why \acro\ offers a preliminary solution for this. In a bookmark -every \cs{ac} like command falls back to a simple text string typesetting what -\cs{acs} would do (or \cs{acsp} for plural forms). These text strings both -can accessed manually and can be modified to an output reserved for \acs{pdf} -bookmarks. - -\begin{commands} - \command{acpdfstring}[\marg{id}] - Access the text string used in \acs{pdf} bookmarks. - \command{acpdfstringplural}[\marg{id}] - Access the plural form of the text string used in \acs{pdf} bookmarks. -\end{commands} -\begin{options} - \keylit{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{options} - -For example the \acs{pdf} acronym used in the title for this section is defined -as follows: -\begin{sourcecode} - \DeclareAcronym{pdf}{ - short = pdf , - long = Portable Document Format , - format = \scshape , - pdfstring = PDF , - accsupp = PDF - } -\end{sourcecode} - -\subsubsection{Accessibility Support} - -The last example also demonstrates the \option{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 \option{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{options} - \keyval{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{options} - -\subsubsection{Tooltips} - -The idea of a tooltip is to have some text shown when you hover with the -mouse over the short form of an acronym. This is only available in some -\acs{pdf} viewers, though. On possibility for such tooltips is loading the -\pkg{pdfcomment} package~\cite{pkg:pdfcomment} and using its \cs*{pdftooltip} -macro. - -\begin{options} - \keybool{tooltip}\Default{false} - This\sinceversion{2.1} options loads the \pkg{pdfcomment} package and sets - the command for creating tooltips to \cs*{pdftooltip}. - \keyval{tooltip-cmd}{control sequence}\Default{\cs*{@firstoftwo}} - This\sinceversion{2.1} allows users using another macro for tooltips -- - maybe one provided by another package or some own macro. It needs to be a - macro with two mandatory arguments, the first being the string typeset in - the \acs{pdf}, the second being the tooltip description text. -\end{options} - -For using this with acronyms they have a property \option{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 \option{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 \option{sort} key has been set, -\code{\meta{index-sort}@\meta{short}} if the \option{index-sort} has been set, -or \meta{index} if the key \option{index} has been set for the specific -acronym. The short versions appearing there are formatted according to the -chosen format of the corresponding acronym, of course. - -This document demonstrates the feature. You can find every acronym that has -been declared in the index. In order to allow flexibility the indexing -command can be chosen both globally via package option and individually for -every acronym. This would allow to add acronyms to a specific index if more -than one index is used, for example with help of the \pkg*{imakeidx} package. - -I'm not yet convinced this is a feature many people if anyone needs and if -they do if it is flexible enough. If you have any thoughts on this I'd -appreciate an email. - -\section{Printing the List}\label{sec:print_lists} -Printing the whole list of acronyms is easy: just place \cs{printacronyms} -where ever you want the list to be. -\begin{commands} - \command{printacronyms}[\oarg{options}] - Print the list of acronyms. -\end{commands} -The commands takes a few options, namely the following ones: -\begin{options} - \keyval{include-classes}{list of classes} - Takes a comma-separated list of the classes of acronyms that should be in - the list. - \keyval{exclude-classes}{list of classes} - Takes a comma-separated list of the classes of acronyms that should - \emph{not} be in the list. \emph{Note that this list overwrites any - entries in \option{include-classes}!} If a class is both included and - excluded then the corresponding acronyms will not be added to the list. - \keyval{name}{name of the list} - sets the name for the list. - \keyval{heading}{sectioning command without leading backslash}% - \Default{section*} - Sets the sectioning command for the heading of the list. A special value - is \code{none} which suppresses the heading. - \keybool{sort}\Default{true} - Set sorting for this list only. - \keybool{local-to-barriers}\Default{false} - This\sinceversion{2.4} option can be used to create a list of only the - acronyms of the current \enquote{barrier group}, see - section~\ref{sec:divid-your-docum}. -\end{options} -\begin{example} - \acsetup{extra-style=comma} - \printacronyms[exclude-classes=city] - - \printacronyms[include-classes=city,name={City Acronyms}] -\end{example} - -You can see that the default layout is a \code{description} list with a -\cs*{section}\sarg\ title. Both can be changed, see -section~\vref{sec:customization}. - -The command \cs{printacronyms} needs two \LaTeX{} runs. This is a precaution -to avoid error messages with a possibly empty list. But since almost all -documents need at least two runs and often are compiled much more often than -that, this fact shouldn't cause too much inconvenience. - -\section{Options and Customization}\label{sec:customization} -\subsection{General Options} -There are a few options which change the general behaviour of \acro. -\default{Underlined} values are used if no value is given. -\begin{options} - %% - % \keychoice{version}{0,1}\Default{1} - % Provide backwards compatibility for documents set with \acro\ in a version - % prior to v1.0. - %% - \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. - %% - \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 \option{foreign} option 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 \option{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} - -All options of this and the following sections can be set via the setup command: -\begin{commands} - \command{acsetup}[\marg{options}] - Set up \acro\ anywhere in the document. Or separate package loading from - setup. -\end{commands} -They might work as package options as well but \emph{I do not recommend it}. - -\begin{example} - % with \acsetup{macros} - we could have used these before: \nato, \ny -\end{example} - -\subsection{Options Regarding Acronyms}\label{sec:opti-regard-acronyms} -The options described in this section all influence the layout of one of the -possible output forms of the acronyms. -\begin{options} - %% - \keyval{short-format}{format}\Default - Sets a format for all short forms. For example - \keyis{short-format}{\cs*{scshape}} would print all short forms in small - caps. - %% - \keyval{long-format}{format}\Default - The same for the long forms. - %% - \keyval{foreign-format}{format}\Default - The format for the \option{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 \option{foreign} entry - as it appears in the list. This may be code that ends with a macro that - takes a mandatory argument. - %% - \keyval{extra-format}{format}\Default - The same for the extra information. - %% - \keychoice{first-style}{default,empty,square,short,long,reversed,footnote,sidenote,% - footnote-reversed,sidenote-reversed}\Default{default} - The basic style of the first appearance of an acronym. The value - \code{sidenote} needs the command \cs*{sidenote} to be defined (for - example by the \pkg*{sidenotes} package). - %% - \keychoice{extra-style}{default,plain,comma,paren,bracket}\Default{default} - Defines the way the extra information is printed in the list. - %% - \keylit{plural-ending}{\meta{short}/\meta{long}}\Default{s/s} - \changedversion{2.4b}With this option the default plural ending can be - set. The appended \meta{long} ending is optional. If you leave it - (\emph{and} the \code{/}) the \meta{short} ending is used for both short - and long versions. -\end{options} - -\begin{example}[side-by-side] - % (Keep in mind that we're in - % a minipage here!) - \acsetup{first-style=empty} - empty: \acf{ny} \\ - \acsetup{first-style=footnote} - footnote: \acf{ny} \\ - \acsetup{first-style=square} - square: \acf{ny} \\ - \acsetup{first-style=short} - short: \acf{ny} \\ - \acsetup{first-style=long} - long: \acf{ny} \\ - \acsetup{first-style=reversed} - reversed: \acf{ny} \\ - \acsetup{ - first-style = footnote-reversed - } - footnote-reversed: \acf{ny} -\end{example} - -\subsection{Options Regarding the List} -\begin{options} - %% - \keychoice{page-style}{none,plain,comma,paren}\Default{none} - If this option is set to a value other than \code{none} the page numbers - of the an acronym appeared on are printed in the list. Please note that - this is an experimental feature and might fail in quite a number of cases. - If you notice anything please send me an email! - %% - \keychoice{pages}{all,first}\Default{all} - If the option \option{page-style} has any value other than \code{none} - this option determines wether all usages of the acronyms are listed or - only the first time. Implicitly sets \keyis{label}{true}. - %% - \keyval{page-name}{page name}\Default{p.\cs*{@}\cs*{,}} - The ``name'' of the page label. This is automatically translated to the - active language. However for the time being there are many translations - missing, yet. Please notify me if you find your language missing. - %% - \keyval{pages-name}{page name plural}\Default{pp.\cs*{@}\cs*{,}} - The ``name'' of the page label when there are more than one page. This is - automatically translated to the active language. However for the time - being there are many translations missing, yet. Please notify me if you - find your language missing. - %% - \keybool{following-page}\Default{false} - If set to \code{true} a page range in the list of acronyms that consists - of two pages will be written by the first page and an appended - \code{f}. This depends on the option \option{next-page}. - %% - \keybool{following-pages}\Default{false} - If set to \code{true} a page range in the list of acronyms that set - consists of more than two pages will be written by the first page and an - appended \code{ff}. This depends on the option \option{next-pages}. - %% - \keybool{following-pages*}\Default{false} - \sinceversion{2.5}If set to \code{true} this sets both options - \keyis{following-page}{true} and \keyis{following-pages}{true}. - \code{false} sets \keyis{following-page}{false} and - \keyis{following-pages}{false}. - %% - \keyval{next-page}{text}\Default{\cs*{,}f.\cs*{@}} - Appended to a page number when \option{following-page} is set to - \code{true} and the range is only 2 pages long. This is automatically - translated to the active language. However, for the time being there are - many translations missing, yet. Please notify me if you find your - language missing. - %% - \keyval{next-pages}{text}\Default{\cs*{,}ff.\cs*{@}} - Appended to a page number when \option{following-pages} is set to - \code{true} and the range is more than 2 pages long. This is - automatically translated to the active language. However, for the time - being there are many translations missing, yet. Please notify me if you - find your language missing. - %% - \keychoice{list-style}{description,lof,longtable,extra-longtable,% - extra-longtable-rev,extra-tabular,extra-tabular-rev,tabular,toc}% - \Default{description} - \changedversion{2.2}Choose with which style the list of acronyms should be - typeset. If you choose \meta{longtable}, \code{extra-longtable} or - \code{extra-longtable-rev} you have to load the - \pkg{longtable}~\cite{pkg:longtable} package in your preamble. The values - \code{extra-\meta{something}} put the extra information in a column of it - own. \emph{Be aware that per default \emph{all} \code{extra-table} styles - only use \code{l} columns. Since acronym descriptions can easily get - longer that a line you should probably define your own style if you want - to use them.} See section~\vref{sec:lists} for details. - %% - \keychoice{list-heading}{chapter,chapter*,section,section*,subsection,% - subsection*,subsubsection,subsubsection*,addchap,addsec,none}% - \Default{section*} - \changedversion{2.0}The heading type of the list. The last two only work - with a \KOMAScript{} class that also defines the appropriate command. A - special value is \code{none} which suppresses the heading. - %% - \keyval{list-name}{list name}\Default{Acronyms} - The name of the list. This is what's written in the list-heading. This - is automatically translated to the active language. However, for the time - being there are many translations missing, yet. Please notify me if you - find your language missing. - %% - \keybool{list-caps}\Default{false} - Print the first letters of the long form capitalized. -\end{options} - -\section{Trailing Tokens and Special Action} - -\acro\ has the possibility\sinceversion{2.0} to look ahead for certain tokens -and switch a boolean if it finds them. Per default \acro\ knows about three -tokens: the \enquote{\code{dot}} (\code{.}), the \enquote{\code{dash}} -(\code{-}) and the \enquote{\code{babel-hyphen}} (\cs*{babelhyphen}). - -A token is made known to \acro\ with the following macro: -\begin{commands} - \command{AcroRegisterTrailing}[\meta{token}\marg{name}] - This registers the token \meta{token} so \acro\ looks if it follows - directly after an acronym macro. \meta{name} is the internal name for - this token. -\end{commands} -The \acro\ package already registers the above mentioned tokens: -\begin{sourcecode} - \AcroRegisterTrailing . {dot} - \AcroRegisterTrailing - {dash} - \AcroRegisterTrailing \babelhyphen {babel-hyphen} -\end{sourcecode} - -If a token is registered it doesn't mean that \acro\ looks for it. The token -must first be activated for this: -\begin{options} - \keyval{activate-trailing-tokens}{csv list of token names} - Tell \acro\ to look for trailing tokens. This is done by giving a csv - list of the internal \emph{names} of the tokens. Per default only - \code{dot} is activated. - \keyval{deactivate-trailing-tokens}{csv list of token names} - Tell \acro\ not to look for trailing tokens. This is done by giving a csv - list of the internal \emph{names} of the tokens. -\end{options} - -All of the above on its own does nothing visible. However: inside of an -acronym, \ie, for example inside the long or the short form it can be tested -for those trailing tokens: -\begin{commands} - \command{aciftrailing}[\marg{csv list of token - names}\marg{true}\marg{false}] - Check if one of the tokens listed in \meta{csv list of token names} is - following and either place \meta{true} or \meta{false} in the input - stream. -\end{commands} -\acro\ uses this to define to further macros: -\begin{commands} - \command{acdot} Inserts a \code{.} if no \code{dot} follows. - \command{acspace} Inserts a \cs*{space} if no \code{dash} or - \code{babel-hyphen} follows. -\end{commands} -The definitions are equivalent\footnote{Not \emph{quite}: \acro's definitions - are engine protected.} to the following code: -\begin{sourcecode} - \newcommand*\acdot{\aciftrailing{dot}{}{.\@}} - \newcommand*\acspace{\aciftrailing{dash,babel-hyphen}{}{\space}} -\end{sourcecode} - -This could be used to define an acronym as follows: -\begin{sourcecode} - \DeclareAcronym{etc}{ - short = {\textit{etc}\acdot} , - long = {\textit{et cetera}} , - short-plural = , long-plural = - } -\end{sourcecode} -If now you somewhere use -\begin{sourcecode} - \ac{etc}. -\end{sourcecode} -there won't be two dots printed. - -The command \cs{acspace} is used already in the definition of the first -appearance of a macro. Let's say you're a German chemist and you have -\begin{sourcecode} - \DeclareAcronym{PU}{ - long = Polyurethan , - long-plural = e - } -\end{sourcecode} -and you use it the first time like this: -\begin{sourcecode} - \ac{PU}-Hartschaum -\end{sourcecode} -then according to German orthography and typesetting rules this should be -printed as -\begin{center} - \enquote{Polyurethan(PU)-Hartschaum} -\end{center} -\ie, with \emph{no} space between long and short form. This is exactly what -happens it you say -\begin{sourcecode} - \acsetup{activate-trailing-tokens = {dash,babel-hyphen}} -\end{sourcecode} -in the preamble. - -\section{About Page Ranges} -If you enable the \option{page-style} option \acro\ adds page numbers to the list -of acronyms. In version~0.\versionstar{} it would add a page reference for an -acronym in the list of acronyms that used \cs*{pageref} to refer to the first -appearance of an acronym. This is retained using \keyis{pages}{first}. -Version~1.0 uses a different approach that doesn't use a label but instead -will list \emph{all} pages an acronym appeared on. With \pkg{hyperref} the -pages are referenced using \cs*{hyperpage}. - -There are some options that control how this list will be typeset, e.g., -\option{following-page}, \option{next-pages} or the option \option{page-style} -itself. It is important to mention that the page list will always take at -least two compilation runs until changes in the options or the actual page -numbers affect it. This is due to the fact that the updated sequence is first -written to the \code{aux} file and only read in during the next run. - -\section{Dividing Your Document Into Pieces -- Creating Local - Lists}\label{sec:divid-your-docum} - -\acro\sinceversion{2.4} introduces the concept of \emph{barriers} which can -divide the document into parts. It is possible to create lists of only those -acronyms used between two such barriers. -\begin{commands} - \command{acbarrier} - Sets a barrier at the point of use in the document. The begin and the end - of the document mark implicit barriers. -\end{commands} -\begin{options} - \keybool{use-barriers}\Default{false} - \sinceversion{2.5}If you want to use barriers and local lists you have to - activate the feature first. This should be set in the preamble in order - to work reliably. Make sure to watch out for log file messages asking you - to rerun. - \keybool{reset-at-barriers}\Default{false} - If this option is set to \code{true} \cs{acbarrier} implicitly calls - \cs{acresetall}. - \keybool{local-to-barriers}\Default{false} - This option can \emph{only} be used as option to the \cs{printacronyms} - command. It then prints a list of only the acronyms of the current - \enquote{barrier group}. -\end{options} - -\begin{example} - \acbarrier - \printacronyms[local-to-barriers] - \ac{ctan} and \ac{lppl} - \acbarrier -\end{example} - -\section{Language Support} -\acro\ detects if packages \pkg{babel}~\cite{pkg:babel} or -\pkg{polyglossia}~\cite{pkg:babel} are being loaded and tries to adapt certain -strings to match the chosen language. However, due to my limited language -knowledge only a few translations are provided. I'll show how the English -translations are defined so you can add the translations to your preamble if -needed. Even better would be you'd send me a short email to -\mailto{contact@mychemistry.eu} with the appropriate translations for your -language and I'll add them to \acro. - -\begin{sourcecode} - \DeclareTranslation{English}{acronym-list-name}{Acronyms} - \DeclareTranslation{English}{acronym-page-name}{p.} - \DeclareTranslation{English}{acronym-pages-name}{pp.} - \DeclareTranslation{English}{acronym-next-page}{f.} - \DeclareTranslation{English}{acronym-next-pages}{ff.} -\end{sourcecode} - -\section{hyperref Support} -The option \keyis{hyperref}{true} adds internal links from all short (or -alternative) forms to their respective list entries. Of course this only -works if you have loaded the \pkg{hyperref} package in your preamble. You -should use this option with care: if you don't use \cs{printacronyms} anywhere -this option will result in loads of \pkg{hyperref} warnings. Also printing -several lists can result in warnings if don't clearly separate the lists into -different classes. If an acronym appears in more than one list there will -also be more than one hypertarget for this acronym. - -Using \pkg{hyperref} will also add \cs*{hyperpage} to the page numbers in the -list (provided they are displayed in the style chosen). Like with an index -the references will thus not point to the acronyms directly but to the page -they're on. - -\section{Defining Own Acronym Macros}\label{sec:defining-own-acronym} - -The commands\sinceversion{2.0} explained in -section~\vref{sec:using-acronyms-comm} have all been defined with a dedicated -command -- there is a family of dedicated commands, actually: -\begin{commands} - \command{NewAcroCommand}[\marg{cs}\marg{code}] - Defines a new \acro\ acronym command \meta{cs}. This sets up the - necessary framework needed by acronym commands and defines \meta{cs} with - an optional star argument and a mandatory argument for the acronym id - using \pkg{xparse}'s \cs*{NewDocumentCommand}. Inside \meta{code} one can - refer to the \acs{id} \meta{id} with \code{\#1}. - \command{RenewAcroCommand}[\marg{cs}\marg{code}] - Defines a new \acro\ acronym command \meta{cs}. This sets up the - necessary framework needed by acronym commands and defines \meta{cs} with - an optional star argument and a mandatory argument for the acronym id - using \pkg{xparse}'s \cs*{RenewDocumentCommand}. Inside \meta{code} one - can refer to the \acs{id} \meta{id} with \code{\#1}. - \command{DeclareAcroCommand}[\marg{cs}\marg{code}] - Defines a new \acro\ acronym command \meta{cs}. This sets up the - necessary framework needed by acronym commands and defines \meta{cs} with - an optional star argument and a mandatory argument for the acronym id - using \pkg{xparse}'s \cs*{DeclareDocumentCommand}. Inside \meta{code} one - can refer to the \acs{id} \meta{id} with \code{\#1}. - \command{ProvideAcroCommand}[\marg{cs}\marg{code}] - Defines a new \acro\ acronym command \meta{cs}. This sets up the - necessary framework needed by acronym commands and defines \meta{cs} with - an optional star argument and a mandatory argument for the acronym id - using \pkg{xparse}'s \cs*{ProvideDocumentCommand}. Inside \meta{code} one - can refer to the \acs{id} \meta{id} with \code{\#1}. -\end{commands} - -Inside these macros one can use a number of low-level expl3 -commands\footnote{Which is why you need to use them inside an expl3 - programming environment. This means in the preamble surround the - definitions with \cs*{ExplSyntaxOn} and \cs*{ExplSyntaxOff}.}. - -\paragraph{Acronym fetching commands} -\begin{commands} - \command*{acro_use:n}[ \marg{id}] - Fetches the acronym using either the first or the short form depending on - earlier uses. - \command*{acro_short:n}[ \marg{id}] - Fetches the short form of the acronym. - \command*{acro_long:n}[ \marg{id}] - Fetches the long form of the acronym. - \command*{acro_alt:n}[ \marg{id}] - Fetches the alternative short form of the acronym. - \command*{acro_foreign:n}[ \marg{id}] - Fetches the foreign property of the acronym if available. - \command*{acro_extra:n}[ \marg{id}] - Fetches the extra property of the acronym if available. -\end{commands} - -\paragraph{Acronym setup commands} -\begin{commands} - \command*{acro_first_upper:} - \acro\ setup command which tells the macros above that we want to - uppercase the first letter of the long version. Should be used - \emph{before} one of the acronym fetching commands. - \command*{acro_plural:} - \acro\ setup command which tells the macros above that we want to use - plural forms. Should be used \emph{before} one of the acronym fetching - commands. - \command*{acro_indefinite:} - \acro\ setup command which tells the macros above that we want to add the - indefinite article. Should be used \emph{before} one of the acronym - fetching commands. - \command*{acro_cite:} - \acro\ setup command which tells the macros above that we want to add the - citation in any case independent of the option \option{cite}. Should be - used \emph{before} one of the acronym fetching commands. - \command*{acro_no_cite:} - \acro\ setup command which tells the macros above that we want to have no - citation independent of the option \option{cite}. Should be used - \emph{before} one of the acronym fetching commands. - \command*{acro_index:} - \acro\ setup command which tells the macros above that we want to add an - index entry in any case independent of the option \option{index}. Should - be used \emph{before} one of the acronym fetching commands. - \command*{acro_reset_specials:} - This\sinceversion{2.0b} macro is called implicitly by \cs{NewAcroCommand} - and \cs{NewPseudoAcroCommand}. If you plan to define an \acro\ command by - yourself using \cs*{NewDocumentCommand} this should be the first macro - after \verbcode+\acro_begin:+. It ensures that in nested acronyms the - inner acronyms don't inherit indefinite articles, uppercasing, - endings\ldots -\end{commands} - -\paragraph{Additional macros for further uses} -\begin{commands} - \command*{acro_begin:} - When an acronym macro is defined \enquote{by hand}, \ie, \emph{not using - \cs{NewAcroCommand}} then this must be the first macro in the code. - \emph{Must have a matching \cs*{acro_end:}}. - \command*{acro_end:} - When an acronym macro is defined \enquote{by hand}, \ie, \emph{not using - \cs{NewAcroCommand}} then this must be the last macro in the code. - \emph{Must have a matching \cs*{acro_begin:}}. - \command*{acro_check_and_mark_if:nn}[ \marg{boolean expression} \marg{id}] - Checks if the acronym with the \acs{id} \meta{id} exists and marks it as - used when \meta{boolean} expression evaluates to \code{true}. This macro - is used inside \cs{NewAcroCommand} and friends implicitly. - \command*{acro_check_acronym:nn}[ \marg{id} \Marg{true|false}] - Checks if the acronym with the \acs{id} \meta{id} exists and marks it as - used if \code{true} or doesn't. This macro is used inside - \cs*{acro_check_and_mark_if:nn}. - \command*{acro_use_acronym:n}[ \Marg{true|false}] - Tell \cs*{acro_use:n} and similar commands wether to mark the acronym as - used or not. This macro is used inside \cs*{acro_check_acronym:nn}. If - this macro is used explicitly it should be used before \cs*{acro_use:n} - (or a similar command) otherwise it has no effect. An acronym marked as - used cannot be unmarked. - \command*{acro_mark_as_used:n}[ \marg{id}] - Explicitly use the acronym with the \acs{id} \meta{id}. This is the expl3 - macro applied to all entries in \cs{acuse}. - \expandable\command*{acro_if_acronym_used:n}[\TF\ \marg{id} \marg{true} - \marg{false}] - The code-level version of \cs{acifused}. This macro is expandable. - \command*{acro_for_all_acronyms_do:n}[ \marg{code}] - Loops over all acronyms known when the macro is used. Inside of - \meta{code} you can refer to the \acs{id} \meta{id} of an acronym with - \verbcode+#1+. - \command*{acro_barrier:} - The code-level version of \cs{acbarrier}. - \command*{acro_switch_off:} - The\sinceversion{2.6} expl3 version of \cs{acswitchoff}. - \command*{acro_switch_on:} - The\sinceversion{2.6} expl3 version of \cs{acswitchon}. - \command*{acro_add_action:n}[ \marg{code}] - Adds\sinceversion{2.7} code to \cs*{acro_get:n}. Inside of \meta{code} - you can refer to the \ac{id} of the acronym with \verbcode+#1+. - The \cs*{acro_get:n} command is called the first macro that is called by - \cs*{acro_use:n} which for example enables conditionals to test for - certain acronym properties. - \command*{acro_get_property:nn}[\TF\ \marg{id} \marg{property} \marg{true} - \marg{false}] - Fetches\sinceversion{2.7} 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_get_property:nn}[\marg{id} \marg{property}] - Like\sinceversion{2.7} \cs*{acro_get_property:nn}\TF, but without the - \meta{true} and \meta{false} arguments. - \command*{acro_if_property:nn}[\TF\ \marg{id} \marg{property} \marg{true} - \marg{false}] - Checks\sinceversion{2.7} if the property \meta{property} of the acronym - \meta{id} is set and places \meta{true} is in the input stream if yes and - \meta{false} otherwise. -\end{commands} - -\paragraph{Examples} -The usage of above macros is best explained with a few examples. The -following definition is done by \acro: -\begin{sourcecode} - \NewAcroCommand \ac { \acro_use:n {#1} } -\end{sourcecode} -An equivalent definition for \cs{ac} would be -\begin{sourcecode} - \NewDocumentCommand \ac {sm} - { - \acro_begin: - \acro_reset_specials: - \acro_check_and_mark_if:nn {#1} {#2} - \acro_use:n {#2} - \acro_end: - } -\end{sourcecode} -which should explain what the actual framework is which \cs{NewAcroCommand} -adds. - -Other definitions by \acro\ are for example the following ones: -\begin{sourcecode} - \NewAcroCommand \Ac - { - \acro_first_upper: - \acro_use:n {#1} - } - \NewAcroCommand \iac - { - \acro_indefinite: - \acro_use:n {#1} - } - \NewAcroCommand \acp - { - \acro_plural: - \acro_use:n {#1} - } - \NewAcroCommand \Acp - { - \acro_plural: - \acro_first_upper: - \acro_use:n {#1} - } - \NewAcroCommand \Aclp - { - \acro_plural: - \acro_first_upper: - \acro_long:n {#1} - } -\end{sourcecode} - -\section{About Plural Forms, Possessive Forms and Similar Constructs -- the - Concept of Endings}\label{sec:about-plural-forms} - -\acro\ has a concept of \emph{endings}. All of \acro's plural options are -defined by saying -\begin{sourcecode} - \ProvideAcroEnding {plural} {s} {s} -\end{sourcecode} -The command's syntax and what it does is as follows: -\begin{commands} - \command{ProvideAcroEnding}[\marg{name}\marg{short default}\marg{long default}] - This macro defines the options - \begin{itemize} - \item \option*{\meta{name}-ending}, - \item \option*{short-\meta{name}-ending}, - \item \option*{alt-\meta{name}-ending}, - \item \option*{long-\meta{name}-ending} and - \item \option*{foreign-\meta{name}-ending}. - \end{itemize} - It also defines the acronym properties - \begin{itemize} - \item \option*{short-\meta{name}}, - \item \option*{short-\meta{name}-form}, - \item \option*{alt-\meta{name}}, - \item \option*{alt-\meta{name}-form}, - \item \option*{long-\meta{name}}, - \item \option*{long-\meta{name}-form}, - \item \option*{foreign-\meta{name}} and - \item \option*{foreign-\meta{name}-form}. - \end{itemize} - Additionally it defines a setup macro as - described in section~\vref{sec:defining-own-acronym}, - \cs*{acro_\meta{name}:}. If \meta{name} contains a \code{-} (dash) it is - replaced by \code{\_} before \cs*{acro_\meta{name}:} is built. So if you - choose \code{my-name} the corresponding macro is named - \cs*{acro_my_name:}. If you use any other non-letters you are on your - own. \changedversion{2.4b}If you use the command with the same \meta{name} - a second time the command only resets the defaults. - - Note that you \emph{must use \cs{ProvideAcroEnding} before any acronym - definition}! -\end{commands} - -This could be used together with the macros described in -section~\vref{sec:defining-own-acronym} for adding support for possessive -forms: -\begin{example} - \ExplSyntaxOn - % this now only works because I've used the same already in the preamble so - % it does nothing here: - \ProvideAcroEnding {possessive} {'s} {'s} - - \ProvideAcroCommand \acg - { - \acro_possessive: - \acro_use:n {#1} - } - \ExplSyntaxOff - The \acg{cd} booklet says\ldots -\end{example} - -Please note that different endings are cumulative which you probably want to -avoid! Imagine a macro -\begin{sourcecode} - \NewAcroCommand \acgp - { - \acro_possessive: - \acro_plural: - \acro_use:n {#1} - } -\end{sourcecode} -This would give \enquote{\ac{cd}s's} instead of \enquote{\ac{cd}s'}. To solve -this you might want to consider -\begin{sourcecode} - \ProvideAcroEnding {possessive-singular} {'s} {'s} - \ProvideAcroEnding {possessive-plural} {s'} {s'} -\end{sourcecode} - -\section{More on Customization}\label{sec:more-custom} -\subsection{Background Information} -Several of \acro's objects are customized using templates. For each of these -objects it is possible to define own templates\footnote{This requires some -knowledge of \pkg{xtemplate} and expl3. Plans are to provide a documented -interface for users of \acro{} in the future.}. Possibly more interesting: it -is easily possible to define further instances of an object using a certain -template. How this works is explained in the following sections. However, the -basics are always the same. There is a command -\begin{commands} - \command*{DeclareAcro\meta{object - type}Style}[\marg{name}\marg{template}\marg{options}] - which allows to define a new style (\ie, instance) for the object - \meta{object type} using the template \marg{template}. -\end{commands} - -\subsection{Lists}\label{sec:lists} -\subsubsection{Own List Style} - -The different existing list styles are all built from four different -templates, \code{list}, \code{list-of}, \code{table} and \code{extra-table}. -Those templates are defined with the help of the \pkg{xtemplate} -package (from~\cite{bnd:l3packages}). Each of these templates has a few -options which are described in table~\vref{tab:list-templates}. New list -styles now are defined via the following macro: - -\begin{commands} - \command{DeclareAcroListStyle}[\marg{name}\marg{template}\marg{options}] - Declares a new \acro\ list style \meta{name}. \meta{name} will be the - value which can be chosen in the option \option{list-style}. - \meta{template} is the name of the template to be used by the style. - Available templates are listed in table~\ref{tab:list-templates}. - \meta{options} are the option settings for the corresponding template. -\end{commands} - -\begin{table}[hbp] - \centering - \caption{Available List Templates and Their Options}\label{tab:list-templates} - \begin{tabular}{*{4}{>{\ttfamily}l}} - \toprule - \normalfont\bfseries Template & \normalfont\bfseries Option & - \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ - \midrule - list & list & tokenlist & description \\ - & foreign-sep & tokenlist & \cs*{space} \\ - & reverse & boolean & false \\ - & before & tokenlist \\ - & after & tokenlist \\ - \midrule - list-of & style & tokenlist & toc \\ - & foreign-sep & tokenlist & \cs*{space} \\ - & reverse & boolean & false \\ - & before & tokenlist \\ - & after & tokenlist \\ - \midrule - table & table & tokenlist & tabular \\ - & table-spec & tokenlist & lp\{.7\cs*{linewidth}\} \\ - & foreign-sep & tokenlist & \cs*{space} \\ - & reverse & boolean & false \\ - & before & tokenlist \\ - & after & tokenlist \\ - \midrule - extra-table & table & tokenlist & tabular \\ - & table-spec & tokenlist & llll \\ - & foreign-sep & tokenlist & \cs*{space} \\ - & reverse & boolean & false \\ - & before & tokenlist \\ - & after & tokenlist \\ - \bottomrule - \end{tabular} -\end{table} - -For defining new styles you need some information on what the different -templates and options do: -\begin{itemize} - \item The option \code{list} of the \code{list} template sets the list - environment. This must be a classic \LaTeX\ list where items are listed - with \cs*{item}. In those lists short entries will always be fed as - optional argument to \cs*{item}: \\ - \code{\cs*{item}[\meta{short}]\meta{long}\meta{extra}\meta{page}} - \item The template \code{list-of} simulates a table of contents or a list of - figures. This can be chosen by setting the option \code{style} to either - \code{toc} or \code{lof}. - \item The template \code{table} typesets the list in a table with two - columns: \\ - \code{\meta{short} \& \meta{long}\meta{extra}\meta{page} - \cs*{tabularnewline}} - \item The template \code{extra-table} typesets the list in a table with four - columns: \\ - \code{\meta{short} \& \meta{long} \& \meta{extra} \& \meta{page} - \cs*{tabularnewline}} - \item The option \code{foreign-sep} is the code inserted between long form - and foreign entry (if a foreign entry is present). - \item The options \code{before} and \code{after} are inserted directly - before and after the complete list. - \item The option \code{reverse} switches the place of \meta{long} with - \meta{extra}. - \item The option \code{table-spec} sets the column types for the table - templates. It must correspond to the number of columns the corresponding - template uses. -\end{itemize} - -As an example let's define a style \code{longtabu} which uses the corresponding -table environment from the package \pkg{tabu}~\cite{pkg:tabu}: - -\begin{sourcecode} - \usepackage{tabu,longtable} - \DeclareAcroListStyle{longtabu}{table}{ - table = longtabu , - table-spec = @{}>{\bfseries}lX@{} - } - \acsetup{list-style=longtabu} -\end{sourcecode} - -As another example let's define a new list with the help of the \pkg{enumitem} -package~\cite{pkg:enumitem}: - -\begin{sourcecode} - % preamble: - % \usepackage{enumitem} - \newlist{acronyms}{description}{1} - \newcommand*\addcolon[1]{#1:} - \setlist[acronyms]{ - labelwidth = 3em, - leftmargin = 3.5em, - noitemsep, - itemindent = 0pt, - font=\addcolon} - \DeclareAcroListStyle{mystyle}{list}{ list = acronyms } - \acsetup{ list-style = mystyle } -\end{sourcecode} -This would look as follows: -\newlist{acronyms}{description}{1} -\newcommand*\addcolon[1]{#1:} -\setlist[acronyms]{ - labelwidth=3em, - leftmargin=3.5em, - noitemsep, - itemindent=0pt, - font=\addcolon} -\DeclareAcroListStyle{mystyle}{list}{ list = acronyms } -\acsetup{list-style=mystyle,hyperref=false} -\printacronyms - -\subsubsection{Own List Heading Command} - -With the option \option{list-heading} you can choose which command prints the -heading of the list. If you need a different choice than what's already -provided you can use the following command to define a new option: -\begin{commands} - \command{DeclareAcroListHeading}[\marg{name}\marg{control sequence}] - Defines a new value \meta{name} for the option \option{list-heading}. - \meta{control sequence} must be a control sequence which takes one - mandatory argument. -\end{commands} -As an example here is how the value \code{section} is defined: -\begin{sourcecode} - \DeclareAcroListHeading{section}{\section} -\end{sourcecode} - -\subsection{First Styles} -The first styles define how an acronym is typeset when it is used for the -first time. It is set with the option \option{first-style}. Legal values for -this option are defined with the following command: -\begin{commands} - \command{DeclareAcroFirstStyle}[\marg{name}\marg{template}\marg{options}] - Declares a new \acro\ first style \meta{name}. \meta{name} will be the - value which can be chosen in the option \option{first-style}. - \meta{template} is the name of the template to be used by the style. - Available templates are listed in table~\ref{tab:first-templates}. - \meta{options} are the option settings for the corresponding template. -\end{commands} - -Here are two examples of the already available styles and how they are -defined: -\begin{sourcecode} - \DeclareAcroFirstStyle{short}{inline}{ - only-short = true , - brackets = false - } - \DeclareAcroFirstStyle{sidenote-reversed}{note}{ - note-command = \sidenote{#1} , - reversed = true - } -\end{sourcecode} - -\begin{table}[hbp] - \centering - \caption{Available First Style Templates and Their Options}\label{tab:first-templates} - \begin{tabular}{*{4}{>{\ttfamily}l}} - \toprule - \normalfont\bfseries Template & \normalfont\bfseries Option & - \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ - \midrule - inline & brackets & boolean & true \\ - & brackets-type & tokenlist & () \\ - & only-short & boolean & false \\ - & only-long & boolean & false \\ - & reversed & boolean & false \\ - & between & tokenlist \\ - & foreign-sep & tokenlist & ,\textasciitilde \\ - \midrule - note & use-note & boolean & true \\ - & note-command & function & \cs*{footnote}\Marg{\#1} \\ - & reversed & boolean & false \\ - & foreign-sep & tokenlist & ,\textasciitilde \\ - \bottomrule - \end{tabular} -\end{table} - -\subsection{Extra Styles} -The extra styles define how the extra information of an acronym is typeset in -the list. It is set with the option \option{extra-style}. Legal values for -this option are defined with the following command: -\begin{commands} - \command{DeclareAcroExtraStyle}[\marg{name}\marg{template}\marg{options}] - Declares a new \acro\ extra style \meta{name}. \meta{name} will be the - value which can be chosen in the option \option{extra-style}. - \meta{template} is the name of the template to be used by the style. - Available templates are listed in table~\ref{tab:extra-templates}. - \meta{options} are the option settings for the corresponding template. -\end{commands} - -Here are two examples of the already available styles and how they are -defined: -\begin{sourcecode} - \DeclareAcroExtraStyle{default}{inline}{ - brackets = false , - punct = true , - punct-symbol = . - } - \DeclareAcroExtraStyle{paren}{inline}{ - brackets = true , - punct = true , - punct-symbol = - } -\end{sourcecode} - -\begin{table} - \centering - \caption{Available Extra Style Templates and Their Options}\label{tab:extra-templates} - \begin{tabular}{*{4}{>{\ttfamily}l}} - \toprule - \normalfont\bfseries Template & \normalfont\bfseries Option & - \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ - \midrule - inline & punct & boolean & true \\ - & punct-symbol & tokenlist & , \\ - & brackets & boolean & true \\ - & brackets-type & tokenlist & () \\ - \bottomrule - \end{tabular} -\end{table} - -\subsection{Page Number Styles} -The page number styles define how the page numbers where acronyms have been -used are typeset in the list. It is set with the option \option{page-style}. -Legal values for this option are defined with the following command: -\begin{commands} - \command{DeclareAcroPageStyle}[\marg{name}\marg{template}\marg{options}] - Declares a new \acro\ extra style \meta{name}. \meta{name} will be the - value which can be chosen in the option \option{page-style}. - \meta{template} is the name of the template to be used by the style. - Available templates are listed in table~\ref{tab:page-templates}. - \meta{options} are the option settings for the corresponding template. -\end{commands} - -Here are two examples of the already available styles and how they are -defined: -\begin{sourcecode} - \DeclareAcroPageStyle{default}{inline}{ - punct = true , - punct-symbol = . - } - \DeclareAcroPageStyle{paren}{inline}{ - brackets=true , - punct-symbol = ~ - } -\end{sourcecode} - -\begin{table}[hbp] - \centering - \caption{Available Page Number Style Templates and Their - Options}\label{tab:page-templates} - \begin{tabular}{*{3}{>{\ttfamily}l}>{\ttfamily}p{.25\linewidth}} - \toprule - \normalfont\bfseries Template & \normalfont\bfseries Option & - \normalfont\bfseries Option Type & \normalfont\bfseries Default \\ - \midrule - inline & display & boolean & true \\ - & punct & boolean & false \\ - & punct-symbol & tokenlist & , \\ - & brackets & boolean & false \\ - & brackets-type & tokenlist & () \\ - & space & skip & .333333em plus .166666em minus - .111111em \\ - \bottomrule - \end{tabular} -\end{table} - -\subsection{Configuration Files} -If\sinceversion{2.2} you repeatedly have the same setup and definitions for -\acro\ in your preamble\footnote{For example defining new endings, \acro{} - commands, list styles, \ldots} you might want to place those in a -configuration file. If \acro\ finds a file named \code{acro.cfg} present it -inputs it at the end of the package. The only thing to be aware of is that -this file is input like a package which means that \code{@} is treated as a -letter (category code~11). - -\appendix - -\acsetup{ - list-style = description , - list-heading = section , - list-name = All Acronyms Used in this Documentation , - page-style = comma , - following-pages* = true , - extra-style = comma -} - -\printacronyms - -\end{document} diff --git a/macros/latex/contrib/acro/example_one.tex b/macros/latex/contrib/acro/example_one.tex index 40b3d5fce4..3af86f5c33 100644 --- a/macros/latex/contrib/acro/example_one.tex +++ b/macros/latex/contrib/acro/example_one.tex @@ -2,7 +2,6 @@ % arara: pdflatex \documentclass{scrartcl} \usepackage[T1]{fontenc} -\usepackage[utf8]{inputenc} \usepackage[ngerman]{babel} \usepackage{acro} \acsetup{ @@ -80,7 +79,7 @@ zweites Mal: \ac{ecm} \ac{F} -% alle außer der Klasse 'physics' auflisten: +% % alle außer der Klasse 'physics' auflisten: \printacronyms[exclude-classes=physics, name=Abkürzungsverzeichnis] % nur die Klasse 'physics' auflisten: diff --git a/macros/latex/contrib/acro/example_two.tex b/macros/latex/contrib/acro/example_two.tex index f99d853a5f..7b188dc324 100644 --- a/macros/latex/contrib/acro/example_two.tex +++ b/macros/latex/contrib/acro/example_two.tex @@ -1,10 +1,9 @@ % arara: pdflatex % arara: pdflatex -% this file is an adapted version of acrotest.tex shipped out with the `acronym' -% package +% this file is an adapted version of acrotest.tex shipped out +% with the `acronym' package \documentclass{article} \usepackage[T1]{fontenc} -\usepackage[utf8]{inputenc} \usepackage[english]{babel} \usepackage[colorlinks]{hyperref} \usepackage{acro} -- cgit v1.2.3