Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2019 by Richard Zach <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{keyindex.sty}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}
23 %<package>\ProvidesPackage{keyindex}
24 %<*package>
25 [2019/04/05 1.0 Index entries by key lookup]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{keyindex}
31 \usepackage[hidelinks]{hyperref}
32 \CodelineIndex
33 \RecordChanges
34 \begin{document}
35 \DocInput{keyindex.dtx}
36 \PrintChanges
37 \end{document}
38 %</driver>
39 % \fi
40 %
41 % \CheckSum{61}
42 %
43 % \CharacterTable
44 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
45 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
46 % Digits \0\1\2\3\4\5\6\7\8\9
47 % Exclamation \! Double quote \" Hash (number) \#
48 % Dollar \$ Percent \% Ampersand \&
49 % Acute accent \' Left paren \( Right paren \)
50 % Asterisk \* Plus \+ Comma \,
51 % Minus \- Point \. Solidus \/
52 % Colon \: Semicolon \; Less than \<
53 % Equals \= Greater than \> Question mark \?
54 % Commercial at \@ Left bracket \[ Backslash \\
55 % Right bracket \] Circumflex \^ Underscore \_
56 % Grave accent \` Left brace \{ Vertical bar \|
57 % Right brace \} Tilde \~}
58 %
59 %
60 % \changes{v1.0}{2019/04/05}{Initial version}
61 %
62 % \GetFileInfo{keyindex.sty}
63 %
64 % \DoNotIndex{\newcommand,\newenvironment}
65 %
66 % \title{The \textsf{keyindex} package\thanks{This document
67 % corresponds to \textsf{keyindex}~\fileversion, dated \filedate.}}
68 % \author{\href{http://richardzach.org/}{Richard Zach}}
69 % \date{}
70 %
71 % \maketitle
72 %
73 % \section{Introduction}
74 %
75 % The |keyindex| package provides functionality for producing an index
76 % without directly entering index entries into the text using the
77 % |\index| command, but instead by looking up short keys and printing a
78 % predefined string in the main text and adding a corresponding index
79 % entry. The standard use case is the production of an index of names:
80 % Rather than having to write in the text, e.g.,
81 % ``|Einstein\index{Einstein, Albert}|'' every time, write
82 % ``|\keyindex{Einstein}|,'' which produces ``Einstein'' in the text
83 % and an index entry under ``Einstein, Albert''. Of course, the
84 % correct index entries must be collected somewhere.
85 %
86 % The package distribution also includes a bash script |makenameindex|
87 % which produces a key index file for use with |keyindex| from a text
88 % file with entries of the form
89 % \begin{quote}
90 % \meta{last name}, \meta{first name}\\
91 % \meta{key}\verb+|+\meta{last name}, \meta{first name}\\
92 % \meta{key}\verb+@+\meta{indexentry}
93 % \end{quote}
94 %
95 % \section{Interactions}
96 %
97 % |keyindex| requires the |ifthen| package.
98 %
99 % \section{Usage}
100 %
101 % \DescribeMacro{\keyindex}
102 % |\keyindex|\oarg{index option}\marg{key}
103 % prints the text associated with index key \meta{key} (using the hooks
104 % |\keyindexformat| and |\missingkeyindexformat|) followed by an index
105 % entry for \meta{key}. The
106 % index entry is generated using the hook |\keyindexcommand| and the
107 % optional argument \meta{index option} is added to the argument of
108 % |\keyindexcommand| after a \verb+|+. For instance,
109 % |\keyindex[(]{Einstein}| might produce the same as \begin{center}
110 % \verb+Einstein\index{Einstein, Albert|(}+.\end{center}
111 % \DescribeMacro{\keyindexprint}
112 % \DescribeMacro{\keyindexonly}
113 % |\keyindexprint|\marg{key} prints only the text corresponding to
114 % \meta{key}, but doesn't add anything to the index.
115 % |\keyindexonly|\marg{key}\oarg{index option} only adds the index entry
116 % but doesn't print anything in the text.
117 %
118 % \DescribeMacro{\keyindexfile} |\keyindexfile|\marg{file} will load
119 % the index key definitions from \meta{file}|.kix|, which is assumed to
120 % contain only a list of lines of the form \begin{center}|\keyindexentry|
121 % \marg{key}\marg{print text}\marg{index text}\end{center}
122 % If it is not called, |keyindex| will use
123 % |\jobname.kix| as default. This must be used in the preamble.
124 %
125 % \DescribeMacro{\keyindexformat}
126 % \DescribeMacro{\missingkeyindexformat}
127 % \DescribeMacro{\keyindexcommand}
128 % These are hooks to carry out the formatting in the text of the text
129 % corresponding to an index entry, or adding the entry to the index.
130 % They can be redefined using |\renewcommand|. By default,
131 % |\keyindexformat|\marg{text} just adds \meta{text} to the document,
132 % |\missingkeyindexformat|\marg{text} adds |\textbf|\marg{text}, and
133 % |\keyindexcommand|\marg{text} issues |\index|\marg{text}.
134 % \StopEventually{}
135 % \section{Implementation}
136 % \subsection{Setup}
137 % \begin{macrocode}
138 \RequirePackage{ifthen}
139 % \end{macrocode}
140 % |\keyindexfile| sets |\@keyindexfile| to its argument; we set
141 % |\@keyindexfile| to default to |\jobname.kix|
142 % \begin{macrocode}
143 \newcommand*{\keyindexfile}[1]{%
144 \renewcommand*{\@keyindexfile}{#1}}
145 \newcommand*{\@keyindexfile}{\jobname.kix}
146 % \end{macrocode}
147 % |\keyindexformat| formats index text;
148 % default: just prints argument.
149 % \begin{macrocode}
150 \newcommand*{\keyindexformat}[1]{#1}
151 % \end{macrocode}
152 % |\missingkeyindexformat| prints index key when not defined;
153 % by default, |\textbf|.
154 % \begin{macrocode}
155 \newcommand*{\missingkeyindexformat}[1]{%
156 \textbf{#1}}
157 % \end{macrocode}
158 % |\keyindexcommand|\marg{index text} adds \marg{index text} to the
159 % index; by default, it does |\index|\marg{index text} but can be redefined.
160 % \begin{macrocode}
161 \newcommand*{\keyindexcommand}[1]{\index{#1}}
162 % \end{macrocode}
163 % At the beginning of the document, we read the index key definition file
164 % \begin{macrocode}
165 \AtBeginDocument{%
166 \InputIfFileExists{\@keyindexfile}{%
167 \PackageInfo{keyindex}{Using index key definition file
168 \@keyindexfile.}}{%
169 \PackageWarning{keyindex}{No index key definition file
170 \@keyindexfile!}}}
171 % \end{macrocode}
172 % |\keyindex|\oarg{index option}\marg{key} prints text for key \meta{key}, and indexes it (with
173 % \verb+|+\meta{index option}, if present). Printing is done by |\keyindexprint|,
174 % indexing by |\keyindexonly|. If the key is undefined, we issue a
175 % warning and print the key (using |\missingkeyindexformat|), not its replacement text.
176 % \begin{macrocode}
177 \newcommand*{\keyindexprint}[1]{\@ifundefined{kix@e@\detokenize{#1}}{%
178 \PackageWarning{keyindex}{Index key \detokenize{#1}
179 undefined}%
180 \missingkeyindexformat{#1}}{%
181 \keyindexformat{\@nameuse{kix@e@\detokenize{#1}}}}}
182 \newcommand*{\keyindexonly}[2][]{\@ifundefined{kix@e@\detokenize{#2}}{%
183 \PackageWarning{keyindex}{Index key \detokenize{#2}
184 undefined}}{%
185 \ifthenelse{\equal{#1}{}}{%
186 \keyindexcommand{\@nameuse{kix@i@\detokenize{#2}}}}{%
187 \keyindexcommand{\@nameuse{kix@i@\detokenize{#2}}|#1}}}}
188 \newcommand{\keyindex}[2][]{\keyindexprint{#2}\keyindexonly[#1]{#2}}
189 % \end{macrocode}
190 % The file |\@keyindexfile| must contain lines of the form
191 % |\keyindexentry|\marg{key}\marg{text}\marg{index entry}. It is read at
192 % the beginning of the document and for each key, defines commands
193 % |\kix@e@|\meta{key} and |\kix@i@|\meta{key} which evaluate to \meta{text}
194 % and \meta{index entry}, respectively. Duplicate definitions are
195 % ignored but generate a warning.
196 % \begin{macrocode}
197 \newcommand*{\keyindexentry}[3]{%
198 \@ifundefined{kix@e@\detokenize{#1}}{%
199 \@namedef{kix@e@\detokenize{#1}}{#2}%
200 \@namedef{kix@i@\detokenize{#1}}{#3}}{%
201 \PackageWarning{keyindex}{Duplicate definition for keyindex key
202 \detokenize{#1} ignored}}}
203 % \end{macrocode}
204 % \Finale
205 % \PrintChanges
206 \endinput