From 526cc7551dd98b7743fa098d4da55b2c747de1f6 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 2 Dec 2012 23:19:00 +0000 Subject: acro (2dec12) git-svn-id: svn://tug.org/texlive/trunk@28420 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/acro/README | 4 +- Master/texmf-dist/doc/latex/acro/acro_en.pdf | Bin 534088 -> 459831 bytes Master/texmf-dist/doc/latex/acro/acro_en.tex | 141 ++++++++++++++++++--------- 3 files changed, 99 insertions(+), 46 deletions(-) (limited to 'Master/texmf-dist/doc') 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 Binary files a/Master/texmf-dist/doc/latex/acro/acro_en.pdf and b/Master/texmf-dist/doc/latex/acro/acro_en.pdf 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}*{}\ma{,}\oa{}\ma{,}\ma{}\oa{} \verb+% can be used only in preamble+ \Befehl{DeclareAcronymFormat}{}\ma{} \verb+% can be used only in preamble+ \Befehl{DeclareAcronymCitation}{}\oa{
}\oa{}\ma{}
    \verb+% can be used only in preamble+
+ \Befehl{DeclareAcronymPDFString}{}\ma{,}
+   \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{} 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}*{} 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{}
+   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{acl};
+ \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.
 \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}{}\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}{}\sinceversion{0.5}
+\end{beschreibung}
 
 \subsection{Labels}\secidx[labels]{Additional Commands}
 The first usage of an acronym sets a label \verb+\label{ac:}+, 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}{} access the text string used in \acs{pdf} bookmarks.
+ \befehl{acpdfstringplural}{} access the plural form of the text string used
+   in \acs{pdf} bookmarks.
+ \Befehl{DeclareAcronymPDFString}{}\ma{,} \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}{}\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}{}\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}
 
-- 
cgit v1.2.3