acro (3oct15)

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

3 files changed, 240 insertions, 102 deletions

diff --git a/Master/texmf-dist/doc/latex/acro/README b/Master/texmf-dist/doc/latex/acro/README
index ad3168fceb1..557dbb68264 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.1
+the ACRO package v2.2
 
   Typeset Acronyms
 
-2015/09/05
+2015/10/03
 --------------------------------------------------------------------------
 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 ee81c0b7230..94ef7a2f76b 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 e0f90fe47a0..fae8f17880d 100644
--- a/Master/texmf-dist/doc/latex/acro/acro_en.tex
+++ b/Master/texmf-dist/doc/latex/acro/acro_en.tex
@@ -1,5 +1,5 @@
 % arara: pdflatex
-% arara: biber
+% !arara: biber
 % arara: pdflatex
 % arara: pdflatex
 % !arara: pdflatex
@@ -56,8 +56,8 @@
       acfplike, aciftrailing, acl, Acl, aclp, Aclp, acp, Acp,
       AcroRegisterTrailing, acs, Acs, acsp, Acsp, acspace, acreset, 
       acresetall, acsetup,
-    DeclareAcroCommand, DeclareAcronym, DeclareAcronymCitation,
-      DeclareAcronymFormat, DeclareAcronymPDFString, DeclarePseudoAcroCommand,
+    DeclareAcroCommand, DeclareAcronym, DeclareAcroListHeading,
+      DeclareAcroListStyle, DeclarePseudoAcroCommand,
     iac, Iac, iaca, Iaca, iacs, Iacs, iacl, Iacl, iacf, Iacf, iacflike,
       Iacflike,
     NewAcroCommand, NewPseudoAcroCommand,
@@ -74,6 +74,8 @@
 
 \acsetup{hyperref}
 
+\usepackage{varioref}
+
 \defbibheading{bibliography}{\section{References}}
 
 \usepackage{csquotes}
@@ -100,6 +102,14 @@
   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:
@@ -109,6 +119,51 @@
 \textsc{Wikipedia}}
 \newcommand*\h[1]{\textcolor{cnltx}{\textbf{#1}}}
 
+\makeatletter
+\def\cnltx@bash@listings@style{
+  language         = bash,
+  basicstyle       = {\sourceformat\color{black}},
+  % numbers          = left,
+  % numberstyle      = \tiny,
+  xleftmargin      = 1em,
+  numbersep        = .75em,
+  gobble           = \cnltx@gobble ,
+  columns          = fullflexible,
+  literate         =
+    {ä}{{\"a}}1
+    {ö}{{\"o}}1
+    {ü}{{\"u}}1
+    {Ä}{{\"A}}1
+    {Ö}{{\"O}}1
+    {Ü}{{\"U}}1
+    {ß}{{\ss}}1 ,
+  breaklines       = true,
+  keepspaces       = true,
+  breakindent      = 1em,
+  commentstyle     = \color{comment},
+  keywordstyle     = \color{black}\bfseries ,
+  stringstyle      = \color{black} ,
+  showstringspaces = false ,
+  morekeywords     = texdoc
+}
+
+\cnltx@expandargs(nx)\lstdefinestyle
+  {bash}
+  {\expandonce\cnltx@bash@listings@style}
+
+\newcommand*\prompt{}
+\patchcmd\lst@NewLine
+  {\hbox{}}% search
+  {\hbox{}\prompt}% replace
+  {}% success
+  {}% failure
+\newsourcecodeenv[
+  code-only,
+  sourcecode-options={style=bash},
+  pre-code=\def\prompt{\textasciitilde\space\$\space}
+]{bash}
+\makeatother
+
 \ProvideAcroEnding {possessive} {'s} {'s}
 
 % declare acronyms
@@ -367,7 +422,7 @@ documentation.
   %% foreign
   \keyval{foreign}{original long form}
     \sinceversion{1.3}can be useful when dealing with acronyms in foreign
-    languages, see section~\ref{ssec:foreign} for details.
+    languages, see section~\vref{ssec:foreign} for details.
   %% sort
   \keyval{sort}{text}
     if used the acronym will be sorted according to this key instead of its
@@ -410,16 +465,16 @@ documentation.
     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~\ref{ssec:index} for details.
+    section~\vref{ssec:index} for details.
   %% index
   \keyval{index}{text}
     \sinceversion{1.1}This key allows to overwrite the automatic index entry
-    with an arbitrary one.  See section~\ref{ssec:index} for details.
+    with an arbitrary one.  See section~\vref{ssec:index} for details.
  %% index-cmd
   \keyval{index-cmd}{control sequence}
     \sinceversion{1.1}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~\ref{ssec:index} for details.
+    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
@@ -622,7 +677,7 @@ with another key to \cs{DeclareAcronym}:
     Additional information for the list of acronyms.
 \end{options}
 These information will only be displayed in the list.  See
-section~\ref{sec:print_lists} for the impact of the following example.
+section~\vref{sec:print_lists} for the impact of the following example.
 
 \begin{example}
   % preamble:
@@ -735,7 +790,7 @@ Note that whatever text you're inserting might be gobbled depending on the
 \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~\ref{sec:print_lists}.  For this \cs{DeclareAcronym} has an additional
+section~\vref{sec:print_lists}.  For this \cs{DeclareAcronym} has an additional
 key:
 \begin{options}
   \keyval{class}{text}
@@ -946,7 +1001,7 @@ The commands takes a few options, namely the following ones:
 
 You can see that the default layout is a \code{description} list with a
 \cs*{section}\sarg\ title.  Both can be changed, see
-section~\ref{sec:customization}.
+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
@@ -1221,21 +1276,21 @@ possible output forms of the acronyms.
     being there are many translations missing, yet.  Please notify me if you
     find your language missing.
   %%
-  \keychoice{list-type}{table|\meta{list}}\Default{description}
-    This option let's you choose how the list is printed.  \meta{list} can be
-    any valid list like \env{itemize} or \env{description}.
-  %%
-  \keychoice{list-style}{list,tabular,longtable,extra-tabular,extra-longtable,%
-    extra-tabular-rev,extra-longtable-rev}\Default{list}
-    If you choose \keyis{list-type}{table} you have to specify which kind of
-    table should be used.  If you choose \code{longtable},
-    \code{extra-longtable} or \code{extra-longtable-rev} you have to load
-    \pkg{longtable} in your preamble.  The values \code{extra-longtable} and
-    \code{extra-longtable-rev} put the extra information in a column of its
-    own.
+  \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:more-list-cust} for details.
   %%
   \keychoice{list-heading}{chapter,chapter*,section,section*,subsection,%
-    subsection*,subsubsection,subsubsection*,addchap,addsec,none}\null
+    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
@@ -1247,51 +1302,9 @@ possible output forms of the acronyms.
     being there are many translations missing, yet.  Please notify me if you
     find your language missing.
   %%
-  \keyval{list-table-width}{dimension}\Default{.7\cs*{columnwidth}}
-    This has only an effect if you chose \key{list-type}{table}.  The
-    \emph{second} column (or the third if you choose one of the \code{-rev}
-    styles) of the table is a \code{p} column whose width can be specified
-    with this option.
-  %%
   \keybool{list-caps}\Default{false}
     Print the first letters of the long form capitalized.
- \end{options}
-  
-If you for example have loaded \pkg{enumitem} you can define a custom list for
-the acronym list:
-\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}
-  \acsetup{list-type=acronyms,hyperref=false,extra-style=comma}
-  \printacronyms
-\end{sourcecode}
-\newlist{acronyms}{description}{1}
-\newcommand*\addcolon[1]{#1:}
-\setlist[acronyms]{
-  labelwidth=3em,
-  leftmargin=3.5em,
-  noitemsep,
-  itemindent=0pt,
-  font=\addcolon}
-\acsetup{list-type=acronyms,extra-style=comma}
-\printacronyms
-
-\subsection{Other Heading Command}
-If you want a \option{list-heading} which is not yet provided you can add your
-own option:
-\begin{sourcecode}
-  \DeclareInstance{acro-title}{myname}{sectioning}
-    { name-format = command that uses #1 }
-\end{sourcecode}
-After that you could use \keyis{list-heading}{myname}.
+\end{options}
 
 \section{Trailing Tokens and Special Action}
 
@@ -1326,9 +1339,9 @@ must first be activated for this:
     list of the internal \emph{names} of the tokens.
 \end{options}
 
-All 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 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}]
@@ -1342,9 +1355,10 @@ trailing options:
   \command{acspace} Inserts a \cs*{space} if no \code{dash} or
     \code{babel-hyphen} follows.
 \end{commands}
-The definitions are equivalent to the following code:
+The definitions are equivalent\footnote{Not \emph{quite}: \acro's definitions
+  are engine protected.} to the following code:
 \begin{sourcecode}
-  \newcommand*\acdot{\aciftrailing{dot}{}{.}}
+  \newcommand*\acdot{\aciftrailing{dot}{}{.\@}}
   \newcommand*\acspace{\aciftrailing{dash,babel-hyphen}{}{\space}}
 \end{sourcecode}
 
@@ -1438,7 +1452,7 @@ they're on.
 \section{Defining Own Acronym Macros}\label{sec:defining-own-acronym}
 
 The commands\sinceversion{2.0}\sinceversion{2.0}\sinceversion{2.0} explained in
-section~\ref{sec:using-acronyms-comm} have all been defined with a dedicated
+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}]
@@ -1639,7 +1653,7 @@ The command's syntax and what it does is as follows:
       \item \option*{long-\meta{name}-form}.
     \end{itemize}
     Additionally it defines a setup macro as
-    described in section~\ref{sec:defining-own-acronym},
+    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
@@ -1651,7 +1665,7 @@ The command's syntax and what it does is as follows:
 \end{commands}
 
 This could be used together with the macros described in
-section~\ref{sec:defining-own-acronym} for adding support for possessive
+section~\vref{sec:defining-own-acronym} for adding support for possessive
 forms:
 \begin{example}
   \ExplSyntaxOn
@@ -1659,7 +1673,7 @@ forms:
   % it does nothing here:
   \ProvideAcroEnding {possessive} {'s} {'s}
 
-  \NewAcroCommand \acg
+  \ProvideAcroCommand \acg
     {
       \acro_possessive:
       \acro_use:n {#1}
@@ -1685,38 +1699,162 @@ this you might want to consider
     \ProvideAcroEnding {possessive-plural}   {s'} {s'}
 \end{sourcecode}
 
-\appendix
+\section{More on List Customization}\label{sec:more-list-cust}
+\subsection{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 styles 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}:
 
-\section{All Acronyms Used in this Documentation}\label{sec:documentation_acronyms}
 \begin{sourcecode}
-  \acsetup{
-    list-type    = table,
-    list-style   = longtable,
-    list-heading = subsection*,
-    extra-style  = comma,
-    page-ref     = comma
+  \usepackage{tabu,longtable}
+  \DeclareAcroListStyle{longtabu}{table}{
+    table = longtabu ,
+    table-spec = @{}>{\bfseries}lX@{}
   }
-  \printacronyms[name=All Acronyms]
+  \acsetup{list-style=longtabu}
 \end{sourcecode}
-\acsetup{
-  list-type    = table,
-  list-style   = longtable,
-  list-heading = subsection*,
-  extra-style  = comma,
-  page-ref     = comma
-}
-\printacronyms[name=All Acronyms]
+
+As another example let's define a new list with the help of the \pkg{enumitem}
+package~\cite{pkg:enumitem}:
 
 \begin{sourcecode}
-  \acsetup{
-    list-type    = table,
-    list-style   = longtable,
-    list-heading = subsection*,
-    page-ref     = comma
-  }
-  \printacronyms[include-classes=city,name=City Acronyms]
+  % 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
+
+\subsection{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}
-\printacronyms[include-classes=city,name=City Acronyms]
+
+\section{Configuration Files}
+If\sinceversion{2.2} you repeatedly have the same setup and definitions for
+\acro\ in your preamble 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 letterhas (category
+code~12).
+
+\appendix
+
+\section{All Acronyms Used in this Documentation}\label{sec:documentation_acronyms}
+\printacronyms[name=All Acronyms,heading=none]
 
 \end{document}