acro (26mar16)

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

3 files changed, 75 insertions, 29 deletions

diff --git a/Master/texmf-dist/doc/latex/acro/README b/Master/texmf-dist/doc/latex/acro/README
index d20ee643b21..3bd7c774078 100644
--- a/Master/texmf-dist/doc/latex/acro/README
+++ b/Master/texmf-dist/doc/latex/acro/README
@@ -1,9 +1,9 @@
 --------------------------------------------------------------------------
-the ACRO package v2.3
+the ACRO package v2.4
 
   Typeset Acronyms
 
-2016/03/14
+2016/03/25
 --------------------------------------------------------------------------
 Clemens Niederberger
 Web:    http://www.mychemistry.eu/forums/forum/acro/
diff --git a/Master/texmf-dist/doc/latex/acro/acro_en.pdf b/Master/texmf-dist/doc/latex/acro/acro_en.pdf
index 5012ce361e9..c3d29648871 100644
--- a/Master/texmf-dist/doc/latex/acro/acro_en.pdf
+++ b/Master/texmf-dist/doc/latex/acro/acro_en.pdf
diff --git a/Master/texmf-dist/doc/latex/acro/acro_en.tex b/Master/texmf-dist/doc/latex/acro/acro_en.tex
index 102da540681..f9a0ac9cb5c 100644
--- a/Master/texmf-dist/doc/latex/acro/acro_en.tex
+++ b/Master/texmf-dist/doc/latex/acro/acro_en.tex
@@ -1,6 +1,6 @@
-% arara: pdflatex
-% arara: biber
-% arara: pdflatex
+% !arara: pdflatex
+% !arara: biber
+% !arara: pdflatex
 % arara: pdflatex
 % arara: pdflatex
 % --------------------------------------------------------------------------
@@ -52,10 +52,10 @@
     automatically sorts the list created by \cs{printacronyms}.%
   } ,
   add-cmds = {
-    ac, Ac, aca, Aca, acap, Acap, acdot, acf, Acf, acflike, acg, acfp, Acfp, 
-      acfplike, aciftrailing, acl, Acl, aclp, Aclp, acp, Acp,
-      AcroRegisterTrailing, acs, Acs, acsp, Acsp, acspace, acreset, 
-      acresetall, acsetup,
+    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, DeclareAcroListHeading,
       DeclareAcroListStyle, DeclarePseudoAcroCommand,
     iac, Iac, iaca, Iaca, iacs, Iacs, iacl, Iacl, iacf, Iacf, iacflike,
@@ -299,6 +299,8 @@
   {\endcnltxlist}
 \makeatother
 
+\newcommand*\mailto[1]{\texttt{\href{mailto:#1}{#1}}}
+
 \begin{document}
 \section{Licence and Requirements}
 \license
@@ -442,8 +444,8 @@ documentation.
     if used the acronym will be sorted according to this key instead of its
     \acs{id}.
   %% class
-  \keyval{class}{text}
-    the class the acronym belongs to.
+  \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
@@ -792,12 +794,11 @@ corresponding indefinite article.
      accented letters.
 \end{commands}
 
-\subsection{Simulating the First Appearance}
-\noindent\sinceversion{1.2}%
-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.
+\subsection{Simulating the First Appearance}\label{sec:simul-first-appe}
+Users\sinceversion{1.2} 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
@@ -816,19 +817,35 @@ 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}{text}
-    Associated class for an acronym.
+  \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.
+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:
@@ -1016,17 +1033,17 @@ The commands takes a few options, namely the following ones:
     list.  A special value is \code{none} which suppresses the heading.
   \keybool{sort}\Default{true}
     \sinceversion{1.3}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{sourcecode}
+\begin{example}
   \acsetup{extra-style=comma}
   \printacronyms[exclude-classes=city]
  
   \printacronyms[include-classes=city,name={City Acronyms}]
-\end{sourcecode}
-\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
@@ -1454,6 +1471,33 @@ 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{local-to-barriers}\Default{false}
+    This option can be used as option to the \cs{printacronyms} command to
+    create 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}
+\begin{options}
+  \keybool{reset-at-barriers}\Default{false}
+    If this option is set to \code{true} \cs{acbarrier} implicitly calls
+    \cs{acresetall}.
+\end{options}
 
 \section{Language Support}
 \acro\ detects if packages \pkg{babel}~\cite{pkg:babel} or
@@ -1461,9 +1505,9 @@ written to the \code{aux} file and only read in during the next run.
 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 at
-\href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu} with the
-appropriate translations for your language and I'll add them to \acro.
+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}
@@ -1611,6 +1655,8 @@ commands\footnote{Which is why you need to use them inside an expl3
     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}.
 \end{commands}
 
 \paragraph{Examples}