summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-12-02 23:19:00 +0000
committerKarl Berry <karl@freefriends.org>2012-12-02 23:19:00 +0000
commit526cc7551dd98b7743fa098d4da55b2c747de1f6 (patch)
treed759320d3d46682439a9267b43d629bba9f99b75 /Master/texmf-dist/doc
parent0ec319f636ce648c5fa688a7ca8be2dd44c3a8ee (diff)
acro (2dec12)
git-svn-id: svn://tug.org/texlive/trunk@28420 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/acro/README4
-rw-r--r--Master/texmf-dist/doc/latex/acro/acro_en.pdfbin534088 -> 459831 bytes
-rw-r--r--Master/texmf-dist/doc/latex/acro/acro_en.tex141
3 files changed, 99 insertions, 46 deletions
diff --git a/Master/texmf-dist/doc/latex/acro/README b/Master/texmf-dist/doc/latex/acro/README
index b7b055f2500..9e15f1da87a 100644
--- a/Master/texmf-dist/doc/latex/acro/README
+++ b/Master/texmf-dist/doc/latex/acro/README
@@ -1,9 +1,9 @@
--------------------------------------------------------------------------
-the ACRO package v0.4a
+the ACRO package v0.5
Typeset Acronyms
-2012/10/07
+2012/11/30
--------------------------------------------------------------------------
Clemens Niederberger
Web: https://bitbucket.org/cgnieder/acro/
diff --git a/Master/texmf-dist/doc/latex/acro/acro_en.pdf b/Master/texmf-dist/doc/latex/acro/acro_en.pdf
index deb39439ed4..abb090fe4bd 100644
--- a/Master/texmf-dist/doc/latex/acro/acro_en.pdf
+++ b/Master/texmf-dist/doc/latex/acro/acro_en.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/acro/acro_en.tex b/Master/texmf-dist/doc/latex/acro/acro_en.tex
index 37749ff72b9..a2d59b21066 100644
--- a/Master/texmf-dist/doc/latex/acro/acro_en.tex
+++ b/Master/texmf-dist/doc/latex/acro/acro_en.tex
@@ -63,25 +63,12 @@
\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
\addcmds{
- ac,
- aca,
- acap,
- acf,
- acfp,
- acl,
- aclp,
- acp,
- acresetall,
- DeclareAcronymFormat,
- acs,
- acsetup,
- acsp,
+ ac,aca,acap,acf,acfp,acl,aclp,acp,acreset,acresetall,acs,acsetup,acsp,
addcolon,
- nato,
- DeclareAcronym,
+ DeclareAcronym,DeclareAcronymCitation,DeclareAcronymFormat,
+ DeclareAcronymPDFString,
linewidth,
- newlist,
- ny,
+ nato,newlist,ny,
printacronyms,
setlist
}
@@ -203,6 +190,9 @@
\DeclareAcronymCitation{ny}{NewYork}
\DeclareAcronym{ot}{ot}{Other Test}
\DeclareAcronymFormat{ot}{\scshape}
+\DeclareAcronym{pdf}{pdf}{Portable Document Format}
+ \DeclareAcronymFormat{pdf}{\scshape}
+ \DeclareAcronymPDFString{pdf}{PDF}
\DeclareAcronym{sw}{SW}{Sammelwerk,e}
\DeclareAcronym{test}{ST}{Some Test}
\DeclareAcronym{texse}{\{TeX\}.SE}{\TeX\ StackExchange}
@@ -210,6 +200,23 @@
\usepackage{imakeidx}
\makeindex[columns=3,options={-sl \jobname.ist},intoc]
+\usepackage{marginnote}
+\makeatletter
+\newcommand*\sinceversion[1]{%
+ \@bsphack
+ \marginnote{%
+ \footnotesize\sffamily\RaggedRight
+ \textcolor{black!75}{Introduced in version~#1}}%
+ \@esphack}
+\newcommand*\changedversion[1]{%
+ \@bsphack
+ \marginnote{%
+ \footnotesize\sffamily\RaggedRight
+ \textcolor{black!75}{Changed in version~#1}}%
+ \@esphack}
+\renewcommand*\cnpkgdoctriangle{}
+\makeatother
+
\begin{document}
\section{Licence and Requirements}
Permission is granted to copy, distribute and/or modify this software under the
@@ -253,14 +260,16 @@ some macros have the same name and meaning\footnote{\emph{Not} in the sense of
\section{Basics}\secidx{Basics}
\subsection{Creating New Acronyms}\secidx[new acronyms]{Basics}
-Acronyms are created with the command \cmd{DeclareAcronym} that can only be used in
-the preamble.
+Acronyms are created with the command \cmd{DeclareAcronym} that can only be used
+in the preamble.
\begin{beschreibung}
\Befehl{DeclareAcronym}*{<id>}\ma{<short>,<pl>}\oa{<alt.>}\ma{<long>,<pl>}\ma{<extra>}\oa{<class>}
\verb+% can be used only in preamble+
\Befehl{DeclareAcronymFormat}{<id>}\ma{<format>} \verb+% can be used only in preamble+
\Befehl{DeclareAcronymCitation}{<id>}\oa{<pre>}\oa{<post>}\ma{<cite keys>}
\verb+% can be used only in preamble+
+ \Befehl{DeclareAcronymPDFString}{<id>}\ma{<pdf entry>,<plural ending>}
+ \verb+% can be used only in preamble+
\end{beschreibung}
Although \cmd{DeclareAcronym} has quite a number of arguments. In the simplest
case you'll only need three:
@@ -302,29 +311,39 @@ of course depends on the citation style you're using.}: \acf{ny}.
\subsection{Using the Acronyms -- the Commands}\secidx[using acronyms]{Basics}
Acronyms are used with with one of the following commands:
\begin{beschreibung}
- \befehl{ac} basic command; the first output is different from subsequent ones.
- \befehl{Ac} same as \cmd{ac} but capitalizes the first letter of the long form.
- \befehl{acs} \h{s}hort form; the actual acronym.
- \befehl{acl} \h{l}ong form; the meaning of the acronym.
- \befehl{Acl} same as \cmd{acl} but capitalizes first letter.
- \befehl{aca} \h{a}lternative short form as specified in the \oa{<short>} argument
- of \cmd{DeclareAcronym}; if it hasn't been specified this is identical to \cmd{acs}.
- \befehl{acf} first form; output like the first time \cmd{ac} is output.
- \befehl{Acf} same as \cmd{acf} but capitalizes first letter of the long form.
- \befehl{acp} \h{p}lural form of \cmd{ac};
- \befehl{Acp} same as \cmd{acp} but capitalizes first letter of the long form.
- \befehl{acsp} plural form of \cmd{acs};
- \befehl{aclp} plural form of \cmd{acp};
- \befehl{Aclp} same as \cmd{aclp} but capitalizes first letter.
- \befehl{acap} plural form of \cmd{aca};
- \befehl{acfp} plural form of \cmd{acf};
- \befehl{Acfp} same as \cmd{acfp} but capitalizes first letter of the long form.
+ \befehl{ac}*{<id>} basic command; the first output is different from subsequent
+ ones.
+ \befehl{Ac}*{<id>} same as \cmd{ac} but capitalizes the first letter of the
+ long form.
+ \befehl{acs}*{<id>} \h{s}hort form; the actual acronym.
+ \befehl{acl}*{<id>} \h{l}ong form; the meaning of the acronym.
+ \befehl{Acl}*{<id>} same as \cmd{acl} but capitalizes first letter.
+ \befehl{aca}*{<id>} \h{a}lternative short form as specified in the \oa{<short>}
+ argument of \cmd{DeclareAcronym}; if it hasn't been specified this is
+ identical to \cmd{acs}.
+ \befehl{acf}*{<id>} first form; output like the first time \cmd{ac} is output.
+ \befehl{Acf}*{<id>} same as \cmd{acf} but capitalizes first letter of the long
+ form.
+ \befehl{acp}*{<id>} \h{p}lural form of \cmd{ac};
+ \befehl{Acp}*{<id>} same as \cmd{acp} but capitalizes first letter of the long
+ form.
+ \befehl{acsp}*{<id>} plural form of \cmd{acs};
+ \befehl{aclp}*{<id>} plural form of \cmd{acl};
+ \befehl{Aclp}*{<id>} same as \cmd{aclp} but capitalizes first letter.
+ \befehl{acap}*{<id>} plural form of \cmd{aca};
+ \befehl{acfp}*{<id>} plural form of \cmd{acf};
+ \befehl{Acfp}*{<id>} same as \cmd{acfp} but capitalizes first letter of the
+ long form.
\end{beschreibung}
If an acronym is used the first time with \cmd{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.
+\sinceversion{0.5}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{beispiel}
% preamble: \DeclareAcronym{cd}{cd}{Compact Disc}
% \DeclareAcronymFormat{cd}{\scshape}
@@ -422,23 +441,57 @@ 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.
-\subsection{Resetting}\secidx[resetting]{Additional Commands}
+\subsection{Reset or Mark as Used}\secidx[resetting]{Additional Commands}
If you want for some reason to fool \acro into thinking that an acronym is used
-for the first time you can call this command:
+for the first time you can call one of these commands:
\begin{beschreibung}
+ \Befehl{acreset}{<comma separated list of ids>}\sinceversion{0.5}
\Befehl{acresetall}
\end{beschreibung}
\begin{beispiel}
- \acresetall
- \ac{ny}
+ \acreset{ny}\ac{ny}
\end{beispiel}
-Beware that this command acts \emph{globally} and effects \emph{all} acronyms!
+Beware that both commands act \emph{globally}! There is also one command that
+effectively is the opposite of \cmd{acreset}, i.e., it marks an acronym as used:
+\begin{beschreibung}
+ \Befehl{acuse}{<comma separated list of ids>}\sinceversion{0.5}
+\end{beschreibung}
\subsection{Labels}\secidx[labels]{Additional Commands}
The first usage of an acronym sets a label \verb+\label{ac:<id>}+, regardless
which command has been used to typeset it. This label is used to create the page
numbers in the list (see section~\ref{sec:print_lists} for details) but can also
be used for other references if needed.
+
+\subsection{\cmd{ac} and Friends in \acs*{pdf} Bookmarks}
+\noindent\sinceversion{0.5}\acro's commands usually are not expandable which
+means they'd leave unallowed tokens in \acs{pdf} bookmarks. \paket{hyperref}
+offers \cmd{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
+\cmd{ac} like command falls back to a simple text string typesetting what \cmd{acs}
+would do (or \cmd{acsp} for plural forms). These text strings both can accessed
+manually and can be modified to an output reserved for \acs{pdf} bookmarks.
+
+\begin{beschreibung}
+ \befehl{acpdfstring}{<id>} access the text string used in \acs{pdf} bookmarks.
+ \befehl{acpdfstringplural}{<id>} access the plural form of the text string used
+ in \acs{pdf} bookmarks.
+ \Befehl{DeclareAcronymPDFString}{<id>}\ma{<pdf entry>,<plural ending>} \cnpkgdocarrow\
+ declare a custom text string for \acs{pdf} bookmarks.
+\end{beschreibung}
+
+For example the \acs{pdf} acronym used in the title for this section is defined
+as follows:
+\begin{beispiel}[code only]
+ \DeclareAcronym{pdf}{pdf}{Portable Document File}
+ \DeclareAcronymFormat{pdf}{\scshape}
+ \DeclareAcronymPDFString{pdf}{PDF}
+\end{beispiel}
+
+
\secidx*{Additional Commands}
\section{Printing the List}\label{sec:print_lists}\secidx{Printing the List}
@@ -506,8 +559,8 @@ There are a few options which change the general behaviour of \acro.
%%
\Option{cite-cmd}{<cmd>}\Default{\cmd*{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 \paket{biblatex}'s
- \cmd*{footcite}.
+ command that takes the cite key as argument is valid, for example \paket*{biblatex}'s%
+ \footnote{\CTANurl{biblatex}} \cmd*{footcite}.
%%
\Option{cite-space}{<code>}\Default{\cmd*{nobreakspace}}
Depending on the citation command in use a space should be inserted before the
@@ -529,7 +582,7 @@ options or via the setup command:
\end{beschreibung}
\begin{beispiel}
- % with \acsetup{macros}; remember I used \acresetall before
+ % with \acsetup{macros}
we could have used these before: \nato, \ny
\end{beispiel}