Debian Codegraph @

texmf-dist/source/latex/acroterm/acroterm.dtx

raw
1 % \iffalse
2 %
3 %<*internal>
4 \begingroup
5 %</internal>
6 %<*batchfile>
7 \input docstrip.tex
8 \keepsilent
9 \preamble
10
11 The Acroterm package
12
13 Copyright (C) 2010 by Jakob Voss
14
15 Distributable under the LaTeX Project Public License,
16 version 1.3c or higher (your choice). The latest version of
17 this license is at: http://www.latex-project.org/lppl.txt
18
19 This work is "maintained" (as per LPPL maintenance status)
20 by Jakob Voss.
21
22 This work consists of the file acroterm.dtx
23 and the derived files acroterm.sty,
24 acroterm.ins, and
25 acroterm.pdf.
26
27 \endpreamble
28 \askforoverwritefalse
29 \generate{\file{acroterm.sty}{\from{acroterm.dtx}{package}}}
30 %</batchfile>
31 %<batchfile>\endbatchfile
32 %<*internal>
33 \generate{\file{acroterm.ins}{\from{acroterm.dtx}{batchfile}}}
34 \def\tmpa{plain}
35 \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
36 \endgroup
37 %</internal>
38 %
39 % \begin{macrocode}
40 %<*driver>
41 \ProvidesFile{acroterm.dtx}
42 %</driver>
43 %<package>\ProvidesPackage{acroterm}
44 %<*package>
45 [2010/11/19 v0.1 Manage and index acronyms and terms]
46 %</package>
47 % \end{macrocode}
48 %
49 %<*driver>
50 \documentclass{ltxdoc}
51 \usepackage{acroterm}
52 \usepackage[
53 pdfborder={0 0 0},colorlinks,
54 linkcolor=blue, citecolor=green, urlcolor=magenta
55 ]{hyperref}
56 \newcommand*\pkg[1]{\texttt{#1}}
57 \setlength\parindent{0pt}
58 \begin{document}
59 \DocInput{\jobname.dtx}
60 \end{document}
61 %</driver>
62 %
63 % \fi
64 %
65 % \errorcontextlines=999
66 %
67 % \GetFileInfo{\jobname.sty}
68 %
69 % \title{The \pkg{\jobname} package}
70 % \author{Jakob Voss}
71 % \date{\filedate ~ \fileversion}
72 %
73 % \maketitle
74 % \tableofcontents
75 % \setlength\parskip{7pt}
76 %
77 % \section{Introduction}
78 %
79 % There are several packages to manage acronyms in \TeX. CTAN lists at least
80 % \pkg{acronym},\footnote{%
81 % \url{http://www.ctan.org/tex-archive/macros/latex/contrib/acronym/}}
82 % \pkg{acromake},\footnote{%
83 % \url{http://www.ctan.org/tex-archive/macros/latex/contrib/acromake/}},
84 % \pkg{glosstex},\footnote{%
85 % \url{http://www.ctan.org/tex-archive/support/glosstex/}} and
86 % \pkg{glossary}.\footnote{%
87 % \url{http://www.ctan.org/tex-archive/macros/latex/contrib/glossary/}}
88 % These packages let you define acronyms, that can be expanded automatically.
89 % But you rarely control when to expand, and defining acronyms can be annoying.
90 % The \pkg{\jobname} package lets you naturally use acronyms and technical
91 % terms in you document. You can mark up acronyms (\verb|\acro|) and terms
92 % (\verb|\term|) as such, to get them formatted consistently and to include
93 % them in an index. In addition you can connect acronyms and terms that
94 % belong together. You fully control, where a term is used in full form,
95 % and where it is used as acronym. Tracking the first ocurrence of a term
96 % is not the primary goal of this package, but may implemented in a later
97 % version.
98 %
99 % The current version of this package is a developer version that still depends
100 % on the packages \pkg{splitidx} and \pkg{hyperref}. Please load \pkg{acroterm}
101 % between the two.
102 %
103 % A small example is included in this package in file \verb|example.tex|.
104 %
105 % \section{Description}
106 %
107 % Essentially, this package provides four macros to mark terms, acronyms, and both:
108 %
109 % \begin{tabular}{lcl}
110 % \verb|\acro{SNAFU}| & $\longrightarrow$ & \acro{SNAFU} \\
111 % \verb|\term{Potrzebie}| & $\longrightarrow$ & \term{Potrzebie} \\
112 % \verb|\tacro{Do it yourself}{DIY}| & $\longrightarrow$ & \tacro{Do it yourself}{DIY} \\
113 % \verb|\aterm{DIY}{Do it yourself}| & $\longrightarrow$ & \aterm{DIY}{Do it yourself} \\
114 % \end{tabular}
115 %
116 % And, after definition of an acronym like above:
117 %
118 % ~~\verb|\acroexpand{DIY}|~~$\longrightarrow$~~Do it yourself
119 %
120 % The macros \verb|\term| and \verb|\acro| simply set some text as term or
121 % as acronym. \verb|\tacro| and \verb|\aterm| mark a term together with its
122 % acronym or vice versa. In all cases, terms and acronyms are put into a
123 % special index that can be used later. Layout can be controlled globally.
124 %
125 % \verb|\term| and \verb|\tacro| support an optional parameter for indexing.
126 % With
127 %
128 % ~~\verb|\term[Potrzebie System of Weights and Measures]{Potrzebie System}|
129 %
130 % the term `Potrzebie System of Weights and Measures' is included in the index
131 % but `\term[Potrzebie System of Weights and Measures]{Potrzebie System}`
132 % is printed in the text. In the same way
133 %
134 % ~~\verb|\tacro[Gang of Four (Patterns)]{Gang of Four}{GoF}|
135 %
136 % prints `\tacro[Gang of Four (Patterns)]{Gang of Four}{GoF}` but indexes
137 % `Gang of Four (Patterns)'.
138 %
139 % Each command has an emphasizing variant that starts with an uppercase letter:
140 %
141 % \begin{tabular}{lcl}
142 % \verb|\Acro{SNAFU}| & $\longrightarrow$ & \Acro{SNAFU} \\
143 % \verb|\Term{Potrzebie}| & $\longrightarrow$ & \Term{Potrzebie} \\
144 % \verb|\Tacro{Do it yourself}{DIY}| & $\longrightarrow$ & \Tacro{Do it yourself}{DIY} \\
145 % \verb|\Aterm{DIY}{Do it yourself}| & $\longrightarrow$ & \Aterm{DIY}{Do it yourself} \\
146 % \end{tabular}
147 %
148 % \newpage
149 % \section{Implementation}
150 %\iffalse
151 %<*package>
152 %\fi
153 % The current version of \pkg{\jobname} depends on \pkg{splitidx} for index
154 % generation. This dependency may be removed in a future version.
155 %
156 % \begin{macrocode}
157 \RequirePackage{splitidx}[2009/02/18 v1.1a]
158 \RequirePackage{xifthen}
159 % \end{macrocode}
160 %
161 % \subsection*{Styles}
162 %
163 % The following commands are used to simply print acronyms and terms.
164 % They do not index but only format the arguments. You can redefine them
165 % to change layout of acronyms and terms. The uppercase variant is used
166 % for emphasizing.
167 %
168 % \begin{macro}{\acrostyle}
169 % print an acronym in normal form
170 % \begin{macro}{\Acrostyle}
171 % print an acronym in emphasized form
172 % \begin{macrocode}
173 \newcommand{\Acrostyle}[1]{#1}
174 \newcommand{\acrostyle}[1]{\textsc{\lowercase{#1}}}
175 % \end{macrocode}
176 % \end{macro}
177 % \end{macro}
178 %
179 % \begin{macro}{\termstyle}
180 % print a term in normal form
181 % \begin{macro}{\Termstyle}
182 % print a term in emphasized form
183 % \begin{macrocode}
184 \newcommand{\termstyle}[1]{#1}
185 \newcommand{\Termstyle}[1]{\textit{#1}}
186 % \end{macrocode}
187 % \end{macro}
188 % \end{macro}
189 %
190 % \begin{macro}{\tacrostyle}
191 % print a term and its acronym in normal form
192 % \begin{macro}{\Tacrostyle}
193 % print a term and its acronym in emphasized form
194 % \begin{macrocode}
195 \newcommand{\tacrostyle}[2]{\termstyle{#1} (\acrostyle{#2})}
196 \newcommand{\Tacrostyle}[2]{\Termstyle{#1} (\acrostyle{#2})}
197 % \end{macrocode}
198 % \end{macro}
199 % \end{macro}
200 %
201 % \begin{macro}{\atermstyle}
202 % print an acronym and its term in normal form
203 % \begin{macro}{\Atermstyle}
204 % print an acronym and its term in emphasized form
205 % \begin{macrocode}
206 \newcommand{\atermstyle}[2]{\acrostyle{#1} (\termstyle{#2})}
207 \newcommand{\Atermstyle}[2]{\acrostyle{#1} (\termstyle{#2})}
208 % \end{macrocode}
209 % \end{macro}
210 % \end{macro}
211 %
212 % \begin{macro}{\acroindexstyle}
213 % print an acronym as index entry.
214 % \begin{macrocode}
215 \newcommand{\acroindexstyle}[1]{#1\acroexpand[ --- ]{#1}}
216 % \end{macrocode}
217 % \end{macro}
218 %
219 % \subsection*{Internal macros}
220 %
221 % \begin{macro}{\provideacronym}
222 % Connects an acronym (that must only contain letters) with a term.
223 % No output or index entry is generated. In most cases you do not
224 % need to explicitly use this macro.
225 % \begin{macrocode}
226 \newcommand{\provideacronym}[2]{% TODO: detect redefinitions
227 \expandafter\providecommand\expandafter{%
228 \csname acronymlong#1\endcsname}{#2}%
229 }
230 % \end{macrocode}
231 % \end{macro}
232 %
233 % \subsection*{Index generation}
234 %
235 % The following hack is required hack to mix hyperref and formatted page numbers.
236 % It may be changed because \verb|\bfhref| may already have been defined.
237 % \begin{macrocode}
238 \newcommand{\bfhref}[1]{\textbf{\hyperpage{#1}}}
239 % \end{macrocode}
240 %
241 % And some code for index generation (also to be fixed).
242 %
243 % \begin{macrocode}
244 \newcommand{\acro@define}[2]{% #1: long term, #2: acronym
245 \sindex[idx]{#1|see{\acrostyle{#2}}}% TODO: acronyms in general index?
246 \@ifundefined{acronymlong#2}{%
247 \provideacronym{#2}{#1}}{}%
248 \sindex[acronym]{#2@\acroindexstyle{#2}|bfhref}%
249 }
250 % \end{macrocode}
251
252 % \begin{macro}{\acroexpand}
253 % print the expanded form (that is the term) of an acronym, if defined.
254 % The optional first parameter is prepended only on success.
255 % \begin{macrocode}
256 \newcommand{\acroexpand}[2][]{%
257 \@ifundefined{acronymlong#2}{}{%
258 #1\csname acronymlong#2\endcsname}%
259 }
260 % \end{macrocode}
261 % \end{macro}
262 %
263 % \subsection*{Main macros}
264 %
265 % \begin{macro}{\term}
266 % marks a term in normal form. Parameters: \verb|[INDEX]{TERM}|
267 % \begin{macrocode}
268 \newcommand{\term}[2][]{%
269 \ifthenelse{\isempty{#1}}%
270 {\sindex[idx]{#2}}{\sindex[idx]{#1}}%
271 \termstyle{#2}}
272 % \end{macrocode}
273 % \end{macro}
274 %
275 % \begin{macro}{\Term}
276 % marks a term in emphasized form. Parameters: \verb|[INDEX]{TERM}|
277 % \begin{macrocode}
278 \newcommand\Term[2][]{%
279 \ifthenelse{\isempty{#1}}%
280 {\sindex[idx]{#2|bfhref}}%
281 {\sindex[idx]{#1|bfhref}}%
282 \Termstyle{#2}%
283 }
284 % \end{macrocode}
285 % \end{macro}
286 %
287 % \begin{macro}{\acro}
288 % marks an acronym in normal form. Parameters: \verb|{ACRO}|
289 % \begin{macrocode}
290 \newcommand{\acro}[1]{%
291 \acrostyle{#1}%
292 {\sindex[acronym]{#1@\acroindexstyle{#1}}}%
293 }
294 % \end{macrocode}
295 % \end{macro}
296 %
297 % \begin{macro}{\Acro}
298 % marks an acronym in emphasized form. Parameters: \verb|{ACRO}|
299 % \begin{macrocode}
300 \newcommand{\Acro}[1]{%
301 \Acrostyle{#1}%
302 {\sindex[acronym]{#1@\acroindexstyle{#1}}}%
303 }
304 % \end{macrocode}
305 % \end{macro}
306 %
307 % \begin{macro}{\tacro}
308 % Parameters: \verb|[INDEX]{TERM}{ACRO}|
309 % \begin{macrocode}
310 \newcommand{\tacro}[3][]{%
311 \ifthenelse{\isempty{#1}}%
312 {\acro@define{#2}{#3}}{\acro@define{#1}{#3}}% TODO: not define?
313 \tacrostyle{#2}{#3}}
314 % \end{macrocode}
315 % \end{macro}
316 %
317 % \begin{macro}{\Tacro}
318 % Parameters: \verb|[INDEX]{TERM}{ACRO}|
319 % \begin{macrocode}
320 \newcommand{\Tacro}[3][]{%
321 \ifthenelse{\isempty{#1}}%
322 {\acro@define{#2}{#3}}{\acro@define{#1}{#3}}%
323 \Tacrostyle{#2}{#3}}
324 % \end{macrocode}
325 % \end{macro}
326 %
327 % \begin{macro}{\aterm}
328 % Parameters: \verb|{ACRO}{TERM}|
329 % \begin{macrocode}
330 \newcommand{\aterm}[2]{%
331 \acro@define{#2}{#1}% TODO: not define but only use?
332 \atermstyle{#1}{#2}}
333 % \end{macrocode}
334 % \end{macro}
335 %
336 % \begin{macro}{\Aterm}
337 % Parameters: \verb|{ACRO}{TERM}|
338 % \begin{macrocode}
339 \newcommand{\Aterm}[2]{%
340 \acro@define{#2}{#1}%
341 \Atermstyle{#1}{#2}}
342 % \end{macrocode}
343 % \end{macro}
344 %
345 % \subsection*{Bugs and missing features}
346 % Index generation may need to be fixed. We also want to discover multiple
347 % definitions of an acronom with different terms. Should terms, that
348 % are used without acronym, occurr in the acronym index? Version 1.0
349 % sure needs to support other index generators.
350 %
351 % See the section on `Auxiliary macros for name indexing directives'
352 % in biblatex source code for hints on including macros in the index.
353 %
354 % The latest development version of this package can be found at
355 % \url{https://github.com/nichtich/acroterm}.
356 %
357 %\iffalse
358 %</package>
359 %\fi
360 %
361 % \Finale
362 %
363 % \typeout{*************************************************************}
364 % \typeout{*}
365 % \typeout{* To finish the installation you have to move the following}
366 % \typeout{* file into a directory searched by LaTeX:}
367 % \typeout{*}
368 % \typeout{* \space\space\space acroterm.sty}
369 % \typeout{*}
370 % \typeout{*************************************************************}
371 %
372 \endinput