summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/acroterm/acroterm.dtx
blob: 8795deca90d91a403189753c0fd9d9a33f93a3d6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
% \iffalse
%
%<*internal>
\begingroup
%</internal>
%<*batchfile>
\input docstrip.tex
\keepsilent
\preamble

The Acroterm package

Copyright (C) 2010 by Jakob Voss

Distributable under the LaTeX Project Public License,
version 1.3c or higher (your choice). The latest version of
this license is at: http://www.latex-project.org/lppl.txt

This work is "maintained" (as per LPPL maintenance status)
by Jakob Voss.

This work consists of the file  acroterm.dtx
          and the derived files acroterm.sty,
                                acroterm.ins, and
                                acroterm.pdf.

\endpreamble
\askforoverwritefalse
\generate{\file{acroterm.sty}{\from{acroterm.dtx}{package}}}
%</batchfile>
%<batchfile>\endbatchfile
%<*internal>
\generate{\file{acroterm.ins}{\from{acroterm.dtx}{batchfile}}}
\def\tmpa{plain}
\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
\endgroup
%</internal>
%
%    \begin{macrocode}
%<*driver>
\ProvidesFile{acroterm.dtx}
%</driver>
%<package>\ProvidesPackage{acroterm}
%<*package>
  [2010/11/19 v0.1 Manage and index acronyms and terms]
%</package>
%    \end{macrocode}
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{acroterm}
\usepackage[
  pdfborder={0 0 0},colorlinks,
  linkcolor=blue, citecolor=green, urlcolor=magenta
]{hyperref}
\newcommand*\pkg[1]{\texttt{#1}}
\setlength\parindent{0pt}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
%
% \fi
%
% \errorcontextlines=999
%
% \GetFileInfo{\jobname.sty}
%
% \title{The \pkg{\jobname} package}
% \author{Jakob Voss}
% \date{\filedate ~ \fileversion}
%
% \maketitle
% \tableofcontents
% \setlength\parskip{7pt}
%
% \section{Introduction}
%
% There are several packages to manage acronyms in \TeX. CTAN lists at least
% \pkg{acronym},\footnote{%
% \url{http://www.ctan.org/tex-archive/macros/latex/contrib/acronym/}}
% \pkg{acromake},\footnote{%
% \url{http://www.ctan.org/tex-archive/macros/latex/contrib/acromake/}},
% \pkg{glosstex},\footnote{%
% \url{http://www.ctan.org/tex-archive/support/glosstex/}} and
% \pkg{glossary}.\footnote{%
% \url{http://www.ctan.org/tex-archive/macros/latex/contrib/glossary/}} 
% These packages let you define acronyms, that can be expanded automatically.
% But you rarely control when to expand, and defining acronyms can be annoying.
% The \pkg{\jobname} package lets you naturally use acronyms and technical 
% terms in you document. You can mark up acronyms (\verb|\acro|) and terms 
% (\verb|\term|) as such, to get them formatted consistently and to include
% them in an index. In addition you can connect acronyms and terms that 
% belong together. You fully control,  where a term is used in full form, 
% and where it is used as acronym. Tracking the first ocurrence of a term
% is not the primary goal of this package, but may implemented in a later
% version.
%
% The current version of this package is a developer version that still depends
% on the packages \pkg{splitidx} and \pkg{hyperref}. Please load \pkg{acroterm}
% between the two.
%
% A small example is included in this package in file \verb|example.tex|.
%
% \section{Description}
%
% Essentially, this package provides four macros to mark terms, acronyms, and both:
%
% \begin{tabular}{lcl}
%   \verb|\acro{SNAFU}|     & $\longrightarrow$ & \acro{SNAFU}  \\
%   \verb|\term{Potrzebie}| & $\longrightarrow$ & \term{Potrzebie} \\
%   \verb|\tacro{Do it yourself}{DIY}| & $\longrightarrow$ & \tacro{Do it yourself}{DIY} \\
%   \verb|\aterm{DIY}{Do it yourself}| & $\longrightarrow$ & \aterm{DIY}{Do it yourself} \\
% \end{tabular}
%
% And, after definition of an acronym like above:
%
% ~~\verb|\acroexpand{DIY}|~~$\longrightarrow$~~Do it yourself
%
% The macros \verb|\term| and \verb|\acro| simply set some text as term or
% as acronym. \verb|\tacro| and \verb|\aterm| mark a term together with its
% acronym or vice versa. In all cases, terms and acronyms are put into a 
% special index that can be used later. Layout can be controlled globally.
%
% \verb|\term| and \verb|\tacro| support an optional parameter for indexing.
% With
%
% ~~\verb|\term[Potrzebie System of Weights and Measures]{Potrzebie System}|
%    
% the term `Potrzebie System of Weights and Measures' is included in the index
% but `\term[Potrzebie System of Weights and Measures]{Potrzebie System}`
% is printed in the text. In the same way
%
% ~~\verb|\tacro[Gang of Four (Patterns)]{Gang of Four}{GoF}|
%
% prints `\tacro[Gang of Four (Patterns)]{Gang of Four}{GoF}` but indexes
% `Gang of Four (Patterns)'.
%
% Each command has an emphasizing variant that starts with an uppercase letter:
%
% \begin{tabular}{lcl}
%   \verb|\Acro{SNAFU}|     & $\longrightarrow$ & \Acro{SNAFU}  \\
%   \verb|\Term{Potrzebie}| & $\longrightarrow$ & \Term{Potrzebie} \\
%   \verb|\Tacro{Do it yourself}{DIY}| & $\longrightarrow$ & \Tacro{Do it yourself}{DIY} \\
%   \verb|\Aterm{DIY}{Do it yourself}| & $\longrightarrow$ & \Aterm{DIY}{Do it yourself} \\
% \end{tabular}
%
% \newpage
% \section{Implementation}
%\iffalse
%<*package>
%\fi
% The current version of \pkg{\jobname} depends on \pkg{splitidx} for index
% generation. This dependency may be removed in a future version.
%
%    \begin{macrocode}
\RequirePackage{splitidx}[2009/02/18 v1.1a]
\RequirePackage{xifthen}
%    \end{macrocode}
%
% \subsection*{Styles}
%
% The following commands are used to simply print acronyms and terms. 
% They do not index but only format the arguments. You can redefine them 
% to change layout of acronyms and terms. The uppercase variant is used 
% for emphasizing. 
%
% \begin{macro}{\acrostyle}
% print an acronym in normal form 
% \begin{macro}{\Acrostyle}
% print an acronym in emphasized form
%    \begin{macrocode}
\newcommand{\Acrostyle}[1]{#1} 
\newcommand{\acrostyle}[1]{\textsc{\lowercase{#1}}} 
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\termstyle}
% print a term in normal form
% \begin{macro}{\Termstyle}
% print a term in emphasized form
%    \begin{macrocode}
\newcommand{\termstyle}[1]{#1} 
\newcommand{\Termstyle}[1]{\textit{#1}} 
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\tacrostyle}
% print a term and its acronym in normal form
% \begin{macro}{\Tacrostyle}
% print a term and its acronym in emphasized form
%    \begin{macrocode}
\newcommand{\tacrostyle}[2]{\termstyle{#1} (\acrostyle{#2})} 
\newcommand{\Tacrostyle}[2]{\Termstyle{#1} (\acrostyle{#2})} 
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\atermstyle}
% print an acronym and its term in normal form
% \begin{macro}{\Atermstyle}
% print an acronym and its term in emphasized form
%    \begin{macrocode}
\newcommand{\atermstyle}[2]{\acrostyle{#1} (\termstyle{#2})} 
\newcommand{\Atermstyle}[2]{\acrostyle{#1} (\termstyle{#2})} 
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\acroindexstyle}
% print an acronym as index entry.
%    \begin{macrocode}
\newcommand{\acroindexstyle}[1]{#1\acroexpand[ --- ]{#1}} 
%    \end{macrocode}
% \end{macro}
%
% \subsection*{Internal macros}
%
% \begin{macro}{\provideacronym}
% Connects an acronym (that must only contain letters) with a term.
% No output or index entry is generated. In most cases you do not
% need to explicitly use this macro.
%    \begin{macrocode}
\newcommand{\provideacronym}[2]{% TODO: detect redefinitions
  \expandafter\providecommand\expandafter{%
  \csname acronymlong#1\endcsname}{#2}%
}
%    \end{macrocode}
% \end{macro}
%
% \subsection*{Index generation}
%
% The following hack is required hack to mix hyperref and formatted page numbers.
% It may be changed because \verb|\bfhref| may already have been defined.
%    \begin{macrocode}
\newcommand{\bfhref}[1]{\textbf{\hyperpage{#1}}}
%    \end{macrocode}
%
% And some code for index generation (also to be fixed).
%
%    \begin{macrocode}
\newcommand{\acro@define}[2]{% #1: long term, #2: acronym
  \sindex[idx]{#1|see{\acrostyle{#2}}}% TODO: acronyms in general index?
  \@ifundefined{acronymlong#2}{%
    \provideacronym{#2}{#1}}{}%
  \sindex[acronym]{#2@\acroindexstyle{#2}|bfhref}%
}
%    \end{macrocode}

% \begin{macro}{\acroexpand}
% print the expanded form (that is the term) of an acronym, if defined.
% The optional first parameter is prepended only on success.
%    \begin{macrocode}
\newcommand{\acroexpand}[2][]{%
  \@ifundefined{acronymlong#2}{}{%
  #1\csname acronymlong#2\endcsname}%
}
%    \end{macrocode}
% \end{macro}
%
% \subsection*{Main macros}
%
% \begin{macro}{\term}
% marks a term in normal form. Parameters: \verb|[INDEX]{TERM}|
%    \begin{macrocode}
\newcommand{\term}[2][]{%
  \ifthenelse{\isempty{#1}}%
  {\sindex[idx]{#2}}{\sindex[idx]{#1}}%
  \termstyle{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Term}
% marks a term in emphasized form. Parameters: \verb|[INDEX]{TERM}|
%    \begin{macrocode}
\newcommand\Term[2][]{%
  \ifthenelse{\isempty{#1}}%
  {\sindex[idx]{#2|bfhref}}%
  {\sindex[idx]{#1|bfhref}}%
  \Termstyle{#2}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\acro}
% marks an acronym in normal form. Parameters: \verb|{ACRO}|
%    \begin{macrocode}
\newcommand{\acro}[1]{%
  \acrostyle{#1}%
  {\sindex[acronym]{#1@\acroindexstyle{#1}}}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Acro}
% marks an acronym in emphasized form. Parameters: \verb|{ACRO}|
%    \begin{macrocode}
\newcommand{\Acro}[1]{%
  \Acrostyle{#1}%
  {\sindex[acronym]{#1@\acroindexstyle{#1}}}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tacro}
% Parameters: \verb|[INDEX]{TERM}{ACRO}|
%    \begin{macrocode}
\newcommand{\tacro}[3][]{%
  \ifthenelse{\isempty{#1}}%
  {\acro@define{#2}{#3}}{\acro@define{#1}{#3}}% TODO: not define?
  \tacrostyle{#2}{#3}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Tacro}
% Parameters: \verb|[INDEX]{TERM}{ACRO}|
%    \begin{macrocode}
\newcommand{\Tacro}[3][]{%
  \ifthenelse{\isempty{#1}}%
  {\acro@define{#2}{#3}}{\acro@define{#1}{#3}}%
  \Tacrostyle{#2}{#3}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\aterm}
% Parameters: \verb|{ACRO}{TERM}|
%    \begin{macrocode}
\newcommand{\aterm}[2]{%
  \acro@define{#2}{#1}% TODO: not define but only use?
  \atermstyle{#1}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Aterm}
% Parameters: \verb|{ACRO}{TERM}|
%    \begin{macrocode}
\newcommand{\Aterm}[2]{%
  \acro@define{#2}{#1}%
  \Atermstyle{#1}{#2}}
%    \end{macrocode}
% \end{macro}
%
% \subsection*{Bugs and missing features}
% Index generation may need to be fixed. We also want to discover multiple
% definitions of an acronom with different terms. Should terms, that
% are used without acronym, occurr in the acronym index? Version 1.0
% sure needs to support other index generators.
% 
% See the section on `Auxiliary macros for name indexing directives'
% in biblatex source code for hints on including macros in the index.
%
% The latest development version of this package can be found at
% \url{https://github.com/nichtich/acroterm}.
%
%\iffalse
%</package>
%\fi
%
% \Finale
%
% \typeout{*************************************************************}
% \typeout{*}
% \typeout{* To finish the installation you have to move the following}
% \typeout{* file into a directory searched by LaTeX:}
% \typeout{*}
% \typeout{* \space\space\space acroterm.sty}
% \typeout{*}
% \typeout{*************************************************************}
%
\endinput