Debian Codegraph @

texmf-dist/source/latex/splitindex/splitidx.dtx

raw
1 % \CheckSum{626}
2 % \iffalse
3 % ======================================================================
4 % splitidx.dtx
5 % Copyright (c) Markus Kohm, 2002-2016
6 %
7 % $Id: splitidx.dtx 4 2016-02-18 10:13:32Z mjk $
8 %
9 % This file is part of the SplitIndex bundle.
10 %
11 % This work may be distributed and/or modified under the conditions of
12 % the LaTeX Project Public License, version 1.3c of the license.
13 % The latest version of this license is in
14 % http://www.latex-project.org/lppl.txt
15 % and version 1.3c or later is part of all distributions of LaTeX
16 % version 2005/12/01 or later and of this work.
17 %
18 % This work has the LPPL maintenance status "maintained".
19 %
20 % The Current Maintainer and author of this work is Markus Kohm.
21 %
22 % The list of all files belongig to the SplitIndex bundle is given in
23 % in the file `manifest.txt'. Files generated by means of unpacking the
24 % distribution (using, for example, the docstrip program) or by means
25 % of compiling them from a source file, for example, from splitindex.c
26 % or splitindex.java may be distributed at the distributor's discretion.
27 % However if they are distributed then a copy of the SplitIndex bundle
28 % must be distributed together with them.
29 %
30 % The list of derived (unpacked or compiled) files belongig to the
31 % distribution and covered by LPPL is defined by the unpacking scripts
32 % (with extension .ins) and the installation script (with name
33 % install.sh) which are part of the distribution.
34 %
35 % Two often ignorred clauses from LPPL 1.3c you should not ignore:
36 % ----------------------------------------------------------------
37 % 2. You may distribute a complete, unmodified copy of the Work as you
38 % received it. Distribution of only part of the Work is considered
39 % modification of the Work, and no right to distribute such a Derived
40 % Work may be assumed under the terms of this clause.
41 % 3. You may distribute a Compiled Work that has been generated from a
42 % complete, unmodified copy of the Work as distributed under Clause 2
43 % above, as long as that Compiled Work is distributed in such a way that
44 % the recipients may install the Compiled Work on their system exactly
45 % as it would have been installed if they generated a Compiled Work
46 % directly from the Work.
47 % ======================================================================
48 %
49 %<*dtx>
50 % \fi
51 \ProvidesFile{splitidx.dtx}[%
52 % \iffalse
53 %</dtx>
54 %<driver>\ProvidesFile{splitidx.drv}[%
55 %<package>\ProvidesPackage{splitidx}[%
56 % \fi
57 2016/02/18 v1.2c multiple indices for LaTeX]
58 % \iffalse
59 %<*driver>
60 \documentclass{ltxdoc}
61 \usepackage{color,alltt}
62 \usepackage{hypdoc}
63 \DeclareRobustCommand*{\Prompt}{{\color{green}\textbf{\$}}}
64 \DeclareRobustCommand*{\Package}[1]{\textsf{#1}}
65 \DeclareRobustCommand*{\Class}[1]{\textsf{#1}}
66 \DeclareRobustCommand*{\Program}[1]{\textsf{#1}}
67 \DeclareRobustCommand*{\File}[1]{\texttt{#1}}
68 \DeclareRobustCommand*{\Cmdline}[1]{\texttt{#1}}
69 \providecommand*{\url}{\texttt}
70 \makeatletter
71 \providecommand*{\Autoref}[1]{%
72 \@ifundefined{hyperref}{Section~\ref{#1}}{%
73 \hyperref[#1]{Section~\ref*{#1}}%
74 }%
75 }%
76 \makeatother
77 \CodelineIndex
78 \RecordChanges
79 \EnableCrossrefs
80 \GetFileInfo{splitidx.dtx}
81 \title{Creating More Than One Index Using \Package{splitidx} And
82 \Program{SplitIndex}\thanks{This file is version \fileversion{} of file
83 \File{\filename}. Nevertheless it should be stable.}}
84 \author{Markus Kohm\thanks{Markus Kohm \textless komascript\textcircled{\tiny
85 at}gmx.info\textgreater}\ \thanks{Many thanks to Michael Palmer who
86 improved the English user manual of the \Program{SplitIndex}.}}
87 \date{\filedate}
88 \begin{document}
89 \maketitle
90 \begin{abstract}
91 With \Package{makeidx}, there's a standard package in \LaTeX{} to create one
92 index for each document. But sometimes more than one index is needed. There
93 are different packages with different solutions and different problems to
94 generate multiple indices. \Package{splitidx} implements another solution to
95 this problem. In addition, \Package{splitidx} also lets you customize the
96 typesetting and appearance of these indices, as well as the formatting of
97 individual index entries.
98 \end{abstract}
99 \tableofcontents
100 \DocInput{splitidx.dtx}
101 \end{document}
102 %</driver>
103 % \fi
104 %
105 % \DoNotIndex{\DeclareOption,\AtEndOfPackage,\renewcommand,\g@addto@macro}
106 % \DoNotIndex{\renewcommand,\ProcessOptions,\relax,\newcommand,\emph}
107 % \DoNotIndex{\providecommand,\@bsphack,\@esphack,\@sanitize,\typeout}
108 % \DoNotIndex{\begingroup,\endgroup,\jobname,\ifx,\else,\fi,\expandafter}
109 % \DoNotIndex{\csname,\endcsname,\protected@write,\AtBeginDocument}
110 % \DoNotIndex{\ifHy@hyperindex,\@indexfile,\thepage,\Hy@temp@A}
111 % \DoNotIndex{\HyInd@ParenLeft,\HyInd@ParenRight,\string,\@ifstar,\@input@}
112 % \DoNotIndex{\@ifnextchar,\edef,\let,\@empty,\@for,\@tempa,\xdef,\def}
113 % \DoNotIndex{\catcode,\lowercase,\do,\@ifundefined,\PackageError}
114 % \DoNotIndex{\MessageBreak,\gdef,\@namedef,\setcounter,\@gobble.\-,\\}
115 % \DoNotIndex{\@onlypreamble,\@tempb,\@wrindex,\immediate,\newif,\newwrite}
116 % \DoNotIndex{\openout,\@gobble}
117 %
118 % \changes{v1.2}{2013/04/04}{several improvements of the user manual by
119 % Michael Palmer}
120 %
121 % \section{Introduction}
122 % \label{sec:intro}
123 %
124 % Standard \LaTeX\ provides for only a single document index. To produce such
125 % an index, one usually loads \Package{makeidx} and marks up index entries in
126 % the document using the \cs{index} command. When the document is processed
127 % with \LaTeX, the \cs{index} commands from the document are written as
128 % \cs{indexentry} commands to the raw index file
129 % ``\File{\cs{jobname}.idx}''. The raw index file is then processed with
130 % \Program{MakeIndex} or another auxiliary program like \Program{xindy}, which
131 % will produce a sorted index file named ``\File{\cs{jobname}.ind}''. This
132 % file is then included at the end of the document using the \cs{printindex}
133 % command.\footnote{For further details, read \protect\cite{makeindex} and
134 % e.g.\ \protect\cite{makeindexmanual}.}
135 %
136 % The \Package{splitidx} package extends this process to permit the creation
137 % of multiple indices. Separate indices are declared and given unique shortcut
138 % identifiers with the \cs{newindex} command. In the document, individual
139 % index entries are marked up and assigned to specific indices with the
140 % \cs{sindex} command. For each of the declared indices, a separate
141 % \File{.idx} file is generated, each of which is post-processed into a
142 % separate \File{.ind} file. These \File{.ind} files are then included in the
143 % document using a modified version of the \cs{printindex} command.
144 %
145 % The process outlined thus far resembles that of other multi-index packages
146 % such as \Package{multind}. The most straightforward way to implement this
147 % scheme, which is the one used by package \Package{multind} and others, is to
148 % directly write a separate \File{.idx} file for each declared index when
149 % processing the document with \LaTeX, and then to separately post-process
150 % each \File{.idx} file with \Program{MakeIndex}. However, this approach can
151 % run into technical limitations. \TeX{} can have no more than 16 files open
152 % for writing at any one time. Several of these file handles are required by
153 % \LaTeX{} itself for other purposes, such as cross references, the table of
154 % contents, and possibly others, depending on the structure of your
155 % document. Therefore, if you need a large number of separate indices, the
156 % limited number of available file handles may become a problem. The
157 % \Package{splitidx} package provides a solution to this problem.
158 %
159 % If the number of indices can be accommodated within the number of available
160 % file handles, you can use \Package{splitidx} with the package option
161 % \texttt{split}. Then, \Package{splitidx} will directly write multiple raw
162 % index files, that is, it will behave according to the scheme just
163 % described. On the other hand, if the number of indices exceeds the number of
164 % available file handles, you can request \Package{splitidx} to write all
165 % index entries to a single intermediate index file, which must then be
166 % post-processed in order to obtain the separate raw index files. The
167 % post-processing of the intermediate file is done with the
168 % \Program{SplitIndex} program, which exists in several different
169 % implementations (see below). This behavior of \Package{splitidx} is
170 % activated by omitting option \texttt{split}, that is, it is the package's
171 % default behavior.
172 %
173 % In addition to the construction of separate indices, \Package{splitidx} also
174 % offers help with customizing the typesetting and appearance of these
175 % indices, as well as the formatting of individual index entries.
176 %
177 %
178 % \section{The \protect\Program{SplitIndex} program}
179 % \label{sec:splitindex.program}
180 %
181 % \subsection{Purpose}
182 %
183 % While the number of files \TeX{} can open for writing is limited, using
184 % multiple indices is normally limited too. As already mentioned in
185 % \autoref{sec:intro} this limitation may be neutralized using a single
186 % intermediate index file, that will be split into several raw index files by
187 % an external post-processor: \Program{SplitIndex}.
188 %
189 %
190 % \subsection{Implementation}
191 %
192 % The program has been implemented in five different languages, as follows:
193 %
194 % \begin{description}
195 % \item[\Program{splitindex.pl}] This is written in perl. You need a perl
196 % interpreter to run it. If you are a Unix user, you have a perl interpreter
197 % and you can call \Program{splitindex.pl} like you would call a binary
198 % program or a shell script from your shell. This is the reference
199 % implementation. I prefer to use this, because it was the first, the
200 % easiest and the shortest to be written.
201 % \item[\Program{splitindex.java}] This is written using Sun Java~1.4.1. I
202 % wrote it because Java is everywhere and may be installed everywhere and a
203 % lot of people are able to understand Java source files. Nevertheless
204 % There's no longer a precompiled version of this in the main distribution.
205 % But you may download it from the repository at
206 % \url{http://sarovar.org/plugins/scmcvs/cvsweb.php/binaries/?cvsroot=splitindex}
207 % \item[\Program{splitindex.c}:] This is a C source of \Program{splitindex}.
208 % I wrote the
209 % C version because a lot of people like to have a binary and most software
210 % authors understand C, and some people want fast binaries instead of slow
211 % Java byte code\,---\,even, if the Java program is fast
212 % enough. Nevertheless, there are no longer binaries of generated from this
213 % source in the main distribution.
214 % \item[\Program{splitindex.tex}:] This is a \TeX{} version of the
215 % program. Yes, you are right: it is a program written in \TeX{}. It has not
216 % the whole functionality of the other programs (see \autoref{TeX}), but
217 % it is system-independent and you don't need to install any other program
218 % like perl or Sun Java 1.4. It is not impossible to fix all the
219 % disadvantages of this program\,---\,but it isn't easy and much more work
220 % than all the other programs.
221 % \changes{v1.2}{2013/04/04}{new \TeX Lua implementation of
222 % \Program{SplitIndex}}
223 % \item[\Program{splitindex.tlu}:] This is a new \TeX Lua version of the
224 % program. It is platform independent like the perl script. Note, that the
225 % syntax for regular expressions in Lua differs from the perl syntax, if you
226 % use it instead of the perl version. Distributors should prefere the perl
227 % version, if they also provide perl for the installation platform.
228 % \end{description}
229 % With the exception of the \TeX{} version, all of these programs are also
230 % able to call the index processor on each of the resulting raw index files.
231 %
232 % And where is the lisp, the smalltalk, the prolog, the \dots{} version of
233 % \Program{splitindex}? Hey, five languages are enough for me! If you need one
234 % more, write it!
235 %
236 %
237 % \section{Using the \Package{splitidx} package}
238 % \label{package}
239 %
240 % \subsection{Setup}
241 %
242 % You can use \Package{splitidx} as a drop-in-replacement for
243 % \Package{makeidx}. If you do so, you just have to replace
244 % \begin{verbatim}
245 % \usepackage{makeidx}
246 % \end{verbatim}\vspace{-\baselineskip}
247 % by
248 % \begin{verbatim}
249 % \usepackage{splitidx}
250 % \end{verbatim}\vspace{-\baselineskip}
251 %
252 % \DescribeMacro{\makeindex}
253 % To activate index generation, you can use \cs{makeindex}, which is declared
254 % by the \LaTeX{} kernel.
255 % You can also load the package with the option
256 % \texttt{makeindex}:
257 % \begin{verbatim}
258 % \usepackage[makeindex]{splitidx}
259 % \end{verbatim}\vspace{-\baselineskip}
260 % which is almost the same like:
261 % \begin{verbatim}
262 % \usepackage{splitidx}\makeindex
263 % \end{verbatim}\vspace{-\baselineskip}
264 %
265 % Other package options are available. The effect of the \texttt{split} option
266 % was already described in \autoref{sec:intro}; further options are
267 % discussed below.
268 %
269 % \DescribeMacro{\newindex}
270 % If you want to generate more than one index without shortcut, you should
271 % declare this using \cs{newindex} with syntax:
272 % \begin{quote}
273 % \cs{newindex}\oarg{index name}\marg{shortcut}.
274 % \end{quote}
275 % The mandatory argument \meta{shortcut} is used to distinguish the different
276 % indices. See description of \cs{sindex} for more information about this. The
277 % optional argument \meta{index name} is the name of the index. This is also
278 % the default heading of this index used by the macros \cs{printindex} and
279 % \cs{printsubindex} (see below). If you omit \meta{index name}, the shortcut
280 % will be used as index name.
281 %
282 % While it is always good practice to declare all index explicitly in the
283 % preamble of the document, this \emph{must} be done if you also use the
284 % package option \texttt{split}. In this case, the \cs{newindex} command opens
285 % a raw index file to write to for each declared index. As the only exception,
286 % the raw index file for the index entries with the default shortcut
287 % (\texttt{idx}) will be created automatically. As noted above, the number of
288 % index files that you can create in this way is limited, which is due to the
289 % limited number of output streams provided by \TeX{}. If you exceed this
290 % number, not only the \cs{newindex} macro itself may result in an error, but
291 % also \cs{tableofcontents}, \cs{listoffigures}, \cs{listoftables} and any
292 % other command that implicitly allocates an output stream.
293 %
294 % A unique shortcut declared with \cs{newindex} to refer to a specific
295 % index becomes part of the filenames of the corresponding \File{.idx} and
296 % \File{.ind} files. Therefore, when you choose a shortcut, make sure that you
297 % only use characters or symbols in the \meta{shortcut} that are allowed in
298 % filenames. On file systems that treat file names as case-insensitive, you
299 % should not mix uppercase and lowercase letters. For maximum portability and
300 % minimum hassle, it is best to always use only lowercase letters.
301 %
302 % \subsection{Marking up index entries}
303 %
304 % \DescribeMacro{\index}%^^A
305 % After loading the \Package{splitidx} package, you may use the \cs{index}
306 % command to mark up index entries in your manuscript as usual. You can find
307 % the description of the argument and features of this command in reference
308 % \cite{makeindex}. The \Program{splitindex} program (see
309 % \autoref{program}) will put all index entries that were produced with
310 % \cs{index} into the same raw index file, which is tagged with the unique
311 % shortcut ``\texttt{idx}''; that is, the \cs{index} command does \emph{not}
312 % allow you to assign index entries to separate indices. However, the
313 % \texttt{useindex} option allows you to change this behavior; this is
314 % discussed below.
315 %
316 % \DescribeMacro{\sindex}%^^A
317 % The \Package{splitidx} package also defines the command \cs{sindex} with the
318 % syntax:
319 % \begin{quote}
320 % \cs{sindex}\oarg{shortcut}\marg{index-entry}
321 % \end{quote}
322 % The \cs{sindex} command is \Package{splitidx}' mechanism for placing
323 % individual index entries into specific indices. The target index is
324 % identified by passing its unique shortcut, as declared with \cs{newindex},
325 % in the optional argument to \cs{sindex}. If not given, the shortcut defaults
326 % to ``\texttt{idx}'', which should therefore be used to identify some sort of
327 % general index.
328 %
329 % If you like, you may also request that \cs{index} should be an alias
330 % for \cs{sindex}. To do so, you use the package
331 % option \texttt{useindex}, e.g.:
332 % \begin{verbatim}
333 % \usepackage[useindex]{splitidx}
334 % \end{verbatim}\vspace{-\baselineskip}
335 % This may be useful when using packages like \textsf{jurabib} that expect
336 % \cs{index} to be the index command.
337 %
338 % \subsection{Suppressing multiple index generation}
339 %
340 % Under some unfortunate circumstances, for example when working with a
341 % publisher that enforces a rigid document format, it may be necessary to
342 % merge the separate indices back into a single index. In this case, it is
343 % \emph{not} necessary to strip out all the individually marked up index
344 % identifiers. Instead, you may load the \Package{splitidx} package with the
345 % \texttt{allintoone} option:
346 %
347 % \begin{verbatim}
348 % \usepackage[allintoone]{splitidx}
349 % \end{verbatim}\vspace{-\baselineskip}
350 % or
351 % \begin{verbatim}
352 % \usepackage[allintoone,makeindex]{splitidx}
353 % \end{verbatim}\vspace{-\baselineskip}
354 % With this option, \Package{splitidx} will do the stripping for you, that is,
355 % \cs{sindex}\oarg{shortcut}\linebreak[1]\marg{indexentry} will be substituted
356 % with \cs{index}\marg{indexentry} during \LaTeX\ processing.
357 %
358 % \emph{Note: Currently only one of the options \texttt{allintoone} and
359 % \texttt{useindex} can be used at same time. If you try to use both,
360 % \texttt{useindex} will be disabled! This may result in many error
361 % messages!}
362 %
363 % \subsection{Customizing index entries}
364 %
365 % \DescribeMacro{\AtWriteToIndex}%^^A
366 % \Package{splitidx} uses \cs{protected@write} to write the index entries to
367 % its output files. The \cs{AtWriteToIndex} macro lets you execute a piece of
368 % code each time an index is written to a specific index. Usage:
369 % \begin{quote}
370 % \cs{AtWriteToIndex}\marg{shortcut}\marg{code}
371 % \end{quote}
372 % This may be useful if you want your index entries to reference not the page
373 % number but some other counter instead. For example, in order to make each
374 % index entry in the general index (identified by the \texttt{idx} shortcut)
375 % point to the corresponding section number, you would write
376 % \begin{verbatim}
377 % \AtWriteToIndex{idx}{\let\thepage\thesection}
378 % \end{verbatim}
379 % Note that this will work only if the shortcut of the index is given
380 % explicitly in each marked-up index entry; for example,
381 % \begin{verbatim}
382 % \sindex[idx]{Roller blades}
383 % \end{verbatim}\vspace{-\baselineskip}
384 % instead of
385 % \begin{verbatim}
386 % \sindex{Roller blades}
387 % \end{verbatim}\vspace{-\baselineskip}
388 % Note, if you want to use command \cs{index} instead of \cs{sindex}, you
389 % should also use the package option \texttt{useindex}; without it, command
390 % \cs{index} will still write the page number to the index.
391 %
392 % The \cs{AtWriteToIndex} command may be used only in the document preamble.
393 %
394 % \DescribeMacro{\AtNextWriteToIndex}%^^A
395 % Sometimes it may be useful to execute some commands only for writing a
396 % single index entry. To do so, you may use
397 % \begin{quote}
398 % \cs{AtNextWriteToIndex}\marg{shortcut}\marg{commands}
399 % \end{quote}
400 % instead of \cs{AtWriteToIndex}.
401 %
402 %\subsection{Automatic custom index commands}
403 %
404 % Some people do not like to write \cs{sindex[foo]}\marg{entry}. They want to
405 % write \cs{foo}\marg{entry}. For these people, the package option
406 % `\texttt{idxcommands}' has been implemented. This option defines a command
407 % with the name of the \meta{shortcut} for each declared index. If you use
408 % this option, you'll get an error if a command with this name is already
409 % defined. Also note that if you are using this option, the characters of the
410 % shortcuts must be letters.
411 %
412 % \subsection{Preventing premature expansion of index entries}
413 %
414 % \DescribeMacro{\newprotectedindex}%^^A
415 % When using the standard index package \textsf{makeidx}, the \LaTeX{} kernel
416 % command \cs{index} may expand its argument. The kernel uses \cs{@sanitize}
417 % to avoid expansion in some cases. But this fails if the argument was already
418 % read by another macro. So if you define a macro that reads its argument,
419 % does something with it and then writes it to the index, this may expand the
420 % argument. For illustration, try the following:
421 % \begin{verbatim}
422 % \documentclass{article}
423 % \usepackage{ngerman}
424 % \usepackage{makeidx}\makeindex
425 % \newcommand*{\Test}[1]{#1\index{#1}}
426 % \begin{document}
427 % \Test{"Anderung}
428 % "Anderung\index{"Anderung}
429 % \end{document}
430 % \end{verbatim}\vspace{-\baselineskip}
431 % This will result in two entries in the \texttt{.idx} file:
432 % \begin{verbatim}
433 % \indexentry{\active@dq \dq@prtct{A}nderung}{1}
434 % \indexentry{"Anderung}{1}
435 % \end{verbatim}\vspace{-\baselineskip}
436 % The first one is something expanded that is not wanted. Package
437 % \textsf{splitindx} behaves the same way by default. But if you use
438 % \cs{newprotectedindex} to define a new index, it uses a trick to avoid
439 % expansion. If all indices should behave like this, you may simply use the
440 % package option \texttt{protected}.
441 % \begin{verbatim}
442 % \documentclass{article}
443 % \usepackage{ngerman}
444 % \usepackage[protected,useindex,makeindex]{splitidx}
445 % \newcommand*{\Test}[1]{#1\index{#1}}
446 % \begin{document}
447 % \Test{"Anderung}
448 % "Anderung\index{"Anderung}
449 % \end{document}
450 % \end{verbatim}\vspace{-\baselineskip}
451 % Will result in two entries at the \texttt{.idx} file:
452 % \begin{verbatim}
453 % \indexentry{"Anderung}{1}
454 % \indexentry{"Anderung}{1}
455 % \end{verbatim}\vspace{-\baselineskip}
456 % If you want to know more about the trick, see the command
457 % \cs{@onelevel@sanitize} in the \LaTeX{} kernel documentation,
458 % \texttt{source2e}.
459 %
460 % \subsection{Including the generated indices in your document}
461 %
462 % \DescribeMacro{\printindex}%^^A
463 % \changes{v0.2a}{2003/01/05}{fix of documentation bug}%^^A
464 % The \cs{printindex} command is used to print one index or all indices that
465 % are declared using \cs{newindex}. How it behaves depends on the syntax you
466 % are using.
467 %
468 % Used like this:
469 % \begin{quote}
470 % \cs{printindex}\oarg{shortcut}\oarg{index name}
471 % \end{quote}
472 % the index file with the optional shortcut will be included and printed, with
473 % the optional \meta{index name} being used as the title. If \meta{index name}
474 % is omitted, the default index name declared with \cs{newindex} will be used
475 % instead. If this name was omitted as well, the shortcut itself will be used
476 % as the title.
477 %
478 % If both optional arguments, \meta{shortcut} and \meta{index name}, are
479 % omitted, and you are using simply
480 % \begin{quote}
481 % \cs{printindex}
482 % \end{quote}
483 % this command behaves like \cs{printindex} from package
484 % \Package{makeidx}. You should not use this if you are using multiple
485 % indices.
486 %
487 % You may also print all indices that were declared using \cs{newindex} at
488 % once. Use the syntax:
489 % \begin{quote}
490 % \cs{printindex*}
491 % \end{quote}
492 % to do so. The indices will be printed in the order you declared them using
493 % \cs{newindex}.
494 %
495 % \subsection{Typesetting the generated indices}
496 %
497 % \cs{printindex} uses the default index output of the class and the index
498 % processor you are using. Usually, this will be \texttt{theindex}
499 % environment, but it doesn't have to be this way. Note, however, that
500 % \cs{printindex} expects the name of the index to be contained in the
501 % \cs{indexname} macro; otherwise, it will fail to typeset the index
502 % name.\footnote{This would be a failure of the class or used package, not of
503 % the \Package{splitidx} package. I don't know of any class with this failure,
504 % but package \Package{tcolorbox}'s library \File{documentation} does use
505 % \cs{kvtcb@text@index} instead of \cs{indexname}. Since version~1.2c
506 % \Package{splitidx} therefore also redefines \cs{kvtcb@text@index} locally.}
507 %
508 % \DescribeMacro{\printsubindex}%^^A
509 % The \cs{printsubindex} command is analogous to \cs{printindex}, but it
510 % performs some redefinitions before printing the index, as follows:
511 % \begin{itemize}
512 % \item demote the index heading level by 1, that is, format the index title
513 % using \cs{section*} instead of \cs{chapter*} with classes that define
514 % \cs{chapter} (such as \texttt{book} and \texttt{report}), and using
515 % \cs{subsection*} instead of \cs{section*} with classes that don't define
516 % \cs{chapter} (such as \texttt{article});
517 % \item deactivate \cs{onecolumn}, \cs{twocolumn} and \cs{clearpage},
518 % \cs{cleardoublepage} that are otherwise used to start a new page in each
519 % index,
520 % \item change the mark mechanism to use \cs{markright} instead of
521 % \cs{markboth} for setting up the running headers.
522 % \end{itemize}
523 % Using this macro, you can print multiple indices in one chapter, if you are
524 % using a class with \cs{chapter}, or in one section, if you are using a class
525 % without \cs{chapter}.
526 %
527 %
528 % \DescribeMacro{\setindexpreamble}%^^A
529 % If you are using a KOMA-Script class, you'll know this command. Package
530 % \Package{splitidx} redefines this command as follows:
531 % \begin{quote}
532 % \cs{setindexpreamble}\oarg{shortcut}\marg{preamble}
533 % \end{quote}
534 % This allows you to define a separate preamble for each index. Note: Package
535 % \Package{splitidx} doesn't print the preamble itself. Instead, before
536 % typesetting an index with a given shortcut using \cs{printindex} or
537 % \cs{printsubindex}, it assigns the user-defined preamble for this shortcut
538 % to the internal macro \cs{index@preamble}. At the user level, its value can
539 % be accessed with the \cs{useindexpreamble} macro (see below).
540 %
541 % \DescribeMacro{\useindexpreamble}%^^A
542 % If you are defining your own index environment or if you extend the existing
543 % \texttt{theindex} environment using \cs{extendtheindex} or otherwise, you
544 % can use \cs{useindexpreamble} to retrieve the preamble previously defined
545 % for the current index using \cs{setindexpreamble}:
546 % \begin{quote}
547 % \cs{useindexpreamble}\oarg{additional commands}
548 % \end{quote}
549 % This macro is not limited to the KOMA-Script classes; it can also be used
550 % e.g.\ with the standard classes. The commands passed in the optional
551 % argument \meta{additional commands} are only used if the preamble for the
552 % current index is defined and not empty. Authors of wrapper classes may use
553 % this, e.g.\ to add additional vertical spaces after the index preamble if
554 % and only if an index preamble will be printed.
555 %
556 % \DescribeMacro{\indexshortcut}%^^A
557 % The macro \cs{indexshortcut} is only defined within the body of
558 % \cs{printindex} and \cs{printsubindex}. It expands to the shortcut of the
559 % specific index that is being printed. It may be useful when defining your
560 % own index environment or extending the \texttt{theindex} environment using
561 % e.g.\ \cs{extendtheindex}.
562 %
563 %
564 % \DescribeMacro{\extendtheindex}%^^A
565 % Most classes define the environment \texttt{theindex} to be used for
566 % printing the index. Using \cs{extendtheindex} with this syntax:
567 % \begin{quote}
568 % \cs{extendtheindex}\marg{before begin}\marg{after begin}^^A
569 % \marg{before end}\mbox{\marg{after end}}
570 % \end{quote}
571 % you may extend this environment. The commands passed in \meta{before begin}
572 % are inserted in \cs{begin\{theindex\}} just after starting the group but
573 % before the existing code defined for this code block. The commands passed in
574 % \meta{after begin} are inserted after \cs{begin\{theindex\}}. Analogously,
575 % the commands passed in \meta{before end} are inserted before
576 % \cs{end\{theindex\}}, while those passed in \meta{after end} are used within
577 % \cs{end\{theindex\}} just after ending the index but just before ending the
578 % group.
579 %
580 %
581 % \subsection{Examples}
582 % \label{examples}
583 %
584 % Let's see how you may get more than one index. The text of the example is
585 % silly, so don't think about the text, think about the usage of
586 % \Package{splitidx}.
587 %
588 % \begin{flushleft}\ttfamily
589 % \cs{documentclass}\{article\} \percentchar \textit{ We use \Class{article}
590 % class \dots}\\
591 % \cs{usepackage}\{splitidx\} \percentchar \textit{ \dots\ and the
592 % \Package{splitidx} package}\\
593 % \cs{makeindex} \percentchar \textit{ And we want index generation}\\
594 % ~\\
595 % \percentchar \textit{ We define 4 indices:}\\
596 % \cs{newindex}[General Index]\{idx\} \percentchar \textit{ Name and shortcut
597 % of the 1st index}\\
598 % \cs{newindex}[Index of Animals]\{ani\} \percentchar \textit{ \dots\ 2nd
599 % index}\\
600 % \cs{newindex}[Index of Fruits]\{fru\} \percentchar \textit{ \dots\ 3rd
601 % index}\\
602 % \cs{newindex}[Index of Vegetables]\{veg\} \percentchar \textit{ \dots\ 4th
603 % index}\\
604 % ~\\
605 % \cs{begin}\{document\}\\
606 % Apples\cs{sindex}[fru]\{apple\} \percentchar \textit{ an entry to
607 % }fru\texttt{ index}\\
608 % and oranges\cs{sindex}[fru]\{orange\} \percentchar \textit{ an entry to
609 % }fru\texttt{ index}\\
610 % are fruits\cs{sindex}\{fruits\}.\ \percentchar \textit{ an implicit entry
611 % to }idx\textit{ index}\\
612 % Tomatoes\cs{sindex}[veg]\{tomato\} \percentchar \textit{ an entry to
613 % }veg\textit{ index}\\
614 % are\\
615 % vegetables\cs{index}\{vegetables\}.\ \percentchar \textit{ an implicit
616 % entry to }idx\textit{ index}\\
617 % Cats\cs{sindex}[ani]\{cat\} \percentchar \textit{ an entry to
618 % }ani\textit{ index}\\
619 % are animals\cs{sindex}[idx]\{animals\}.\ \percentchar \textit{ an explicite
620 % entry to }idx\textit{ index}\\
621 % ~\\
622 % \cs{printindex*} \percentchar \textit{ print all indices}\\
623 % \cs{end}\{document\}
624 % \end{flushleft}
625 % After processing the file above with \LaTeX{} you'll get a raw index file
626 % with following contents:
627 % \begin{verbatim}
628 % \indexentry[fru]{apple}{1}
629 % \indexentry[fru]{orange}{1}
630 % \indexentry{fruits}{1}
631 % \indexentry[veg]{tomato}{1}
632 % \indexentry{vegetables}{1}
633 % \indexentry[ani]{cat}{1}
634 % \indexentry[idx]{animals}{1}
635 % \end{verbatim}\vspace{-\baselineskip}
636 % \Autoref{program} explains how to convert this intermediate file into
637 % separate raw index files and index files. In the above example, all four
638 % index files are input with a single \cs{printindex*} command. Each file will
639 % produce a single section that start on a new page. The section headings
640 % ``General Index'', ``Index of Animals'', ``Index of Fruits'' and ``Index of
641 % Vegetables'' will be printed in onecolumn mode, followed by the index
642 % entries printed in twocolumn mode.
643 %
644 % Maybe you would like to format all indices as subsections within one
645 % section. You can do this by replacing the \cs{printindex*} command in the
646 % example above with the following:
647 % \begin{flushleft}\ttfamily
648 % \cs{twocolumn}[\percentchar\textit{ set the title onecolumn}\\
649 % \ \cs{section*}\{Indices\} \percentchar\textit{ the section with the
650 % indices}\percentchar\\
651 % \ \cs{markboth}\{Indices\}\{Indices\} \percentchar\textit{ setting up the
652 % running headline }\percentchar\\
653 % ]\percentchar\textit{ but the indices twocolumn}\\
654 % \cs{printsubindex*} \percentchar\textit{ print all indices}
655 % \end{flushleft}
656 % Note that I've used \cs{printsubindex*} instead of \cs{printindex*} in this
657 % modified example.
658 %
659 % We now turn to the running headers for the index pages. If you are using
660 % page style \texttt{plain}, which is default at \Class{article} class, the
661 % running headers are empty, so you don't need to set them up. However, if
662 % you're using page style \texttt{headings} for your index pages and the
663 % \cs{section*} command to format the headings of the several indices, you
664 % should set up the running headers to match the current index titles. If you
665 % are using a KOMA-Script class, you can use \cs{addsec} or \cs{addsec*}
666 % instead of \cs{section*} to format the index titles, in which case you will
667 % not need to manually update the running headers.
668 %
669 % Maybe you want the general index to be the section, while the other indices
670 % should be subsections of the general index. You might then try to replace
671 % the code above with the following:
672 % \begin{flushleft}\ttfamily
673 % \percentchar\textit{\#\#\#\#\# This will not do the thing you wanted!
674 % \#\#\#\#\#}\\
675 % \cs{printindex}[idx] \percentchar\textit{ print index }idx\textit{ as
676 % section}\\
677 % \cs{printsubindex}[ani] \percentchar\textit{ print index }ani\textit{ as
678 % subsection}\\
679 % \cs{printsubindex}[fru] \percentchar\textit{ print index }fru\textit{ as
680 % subsection}\\
681 % \cs{printsubindex}[veg] \percentchar\textit{ print index }veg\textit{ as
682 % subsection}\\
683 % \end{flushleft}
684 % But this will result in a twocolumn section containing the general index
685 % (identified by \texttt{idx}) and three onecolumn subsections containing the
686 % other indices, and a page break after the general index. Why is this?
687 % \LaTeX\ will switch to twocolumn mode as it enters the \texttt{theindex}
688 % environment (which is created by the \cs{printindex} command) and will
689 % revert to onecolumn mode when it exits \texttt{theindex}. If twocolumn mode
690 % was active before \cs{printindex}, a \cs{clearpage} command will be issued
691 % at the end of \texttt{theindex}. So what's the solution? Remembering the
692 % \cs{extendtheindex} command, you can write:
693 % \begin{flushleft}\ttfamily
694 % \cs{begingroup} \percentchar\textit{ keep the following extension local to
695 % this
696 % group}\\
697 % \ \cs{extendtheindex}\percentchar \textit{ some changes of
698 % }theindex\textit{ environment}\\
699 % \ \ \{\}\percentchar\textit{ no change before beginning}\\
700 % \ \ \{\}\percentchar\textit{ no change after beginning}\\
701 % \ \ \{\cs{let}\cs{onecolumn}\cs{relax} \percentchar\textit{ deactivate
702 % \cs{onecolumn} before ending}\\
703 % \ \ \ \cs{let}\cs{clearpage}\cs{relax} \percentchar\textit{ deactivate
704 % \cs{clearpage} before ending}\\
705 % \ \ \}\percentchar \textit{ changes before ending}\\
706 % \ \ \{\}\percentchar\textit{ no change after ending}\\
707 % \ \cs{printindex}[idx] \percentchar\textit{ print index }idx\textit{ as
708 % section}\\
709 % \cs{endgroup} \percentchar\textit{ end group with extended
710 % }theindex\textit{
711 % environment}\\
712 % \cs{printsubindex}[ani] \percentchar\textit{ print index }ani\textit{ as
713 % subsection}\\
714 % \cs{printsubindex}[fru] \percentchar\textit{ print index }fru\textit{ as
715 % subsection}\\
716 % \cs{printsubindex}[veg] \percentchar\textit{ print index }veg\textit{ as
717 % subsection}\\
718 % \cs{onecolumn} \percentchar\textit{ finish the indices}
719 % \end{flushleft}
720 % With this extension, the whole index will be set in twocolumn mode, with no
721 % page break before the first subsection. However, you have to switch back to
722 % onecolumn mode manually at the end of the indices.
723 %
724 % The example above may be modified as follows to obtain a onecolumn index:
725 % \begin{flushleft}\ttfamily
726 % \cs{begingroup} \percentchar\textit{ hold following extension local to this
727 % group}\\
728 % \ \cs{makeatletter} \percentchar\textit{ allow }@\textit{ at macro names}\\
729 % \ \cs{extendtheindex}\percentchar \textit{ some changes of
730 % }theindex\textit{ environment}\\
731 % \ \ \{\cs{let}\cs{twocolumn}\cs{@firstoptofone} \percentchar\textit{
732 % deactivate \cs{twocolumn}}\\
733 % \ \ \ \cs{let}\cs{onecolumn}\cs{@firstoptofone} \percentchar\textit{
734 % deactivate \cs{twocolumn}}\\
735 % \ \ \ \cs{let}\cs{clearpage}\cs{relax} \percentchar\textit{ deactivate
736 % \cs{clearpage}}\\
737 % \ \ \}\percentchar \textit{ changes before beginning}\\
738 % \ \ \{\}\percentchar\textit{ no change after beginning}\\
739 % \ \ \{\}\percentchar\textit{ no change before ending}\\
740 % \ \ \{\}\percentchar\textit{ no change after ending}\\
741 % \ \cs{makeatother} \percentchar\textit{ deactivate \cs{makeatletter}}\\
742 % \ \cs{printindex} \percentchar\textit{ print index}\\
743 % \cs{endgroup} \percentchar\textit{ end group with extended }theindex\textit{
744 % environment}
745 % \end{flushleft}
746 % This not only works with splitted indices but also with one
747 % single index.
748 %
749 % I hope that these examples were useful to understand how to format indices
750 % using \Package{splitidx}. The next section will show you how to generate
751 % separate indices from a single intermediate index file.
752 %
753 %
754 % \subsection{Splitting intermediate index files}
755 % \label{program}
756 %
757 % Most commonly, it will be sufficient to call one of the \Program{splitindex}
758 % programs with one parameter, the name of the intermediate index file. This
759 % will split the intermediate file into several raw index files, and then call
760 % \Program{MakeIndex} on each of these. The program \Program{splitindex} can
761 % be instructed to use another index processor such as \Program{xindy}, or to
762 % pass additional options along to the index processor, e.g.\ ``\Cmdline{-g}''
763 % to use German sorting with \Program{MakeIndex}. While it may be a rare need,
764 % it is also possible to modify the parsing of the intermediate index file and
765 % the generation of the filenames and contents of the resulting raw index
766 % files.
767 %
768 % The names of the options and the syntax of the Arguments is same at all of
769 % the programs except \Program{splitindex.tex} (see
770 % \autoref{TeX}): \begin{description}\setlength{\labelsep}{1em}
771 % \item[\texttt{--help}]
772 % \item[{\makebox[1.2em][l]{\texttt{-h}}}]\vspace{-2\itemsep}
773 % Show information about usage, options and arguments and terminate without
774 % processing an index file.
775 % \item[\texttt{--makeindex} \meta{program name}]~
776 % \item[\texttt{-m} \meta{program name}]\vspace{-2\itemsep}
777 % Call \meta{program name}
778 % instead of \Program{makeindex} to process each generated raw index
779 % file. You may set this variable to an empty value. How this may be done
780 % depends on the shell, which you are using. Using bash you may achieve an
781 % empty value using \texttt{""} or \texttt{''}. An empty value means that
782 % no index processor will be called on the generated raw index files.
783 % \item[\texttt{--identify} \meta{regular expression}]~
784 % \item[\texttt{-i} \meta{regular expression}]\vspace{-2\itemsep} Uses
785 % \meta{regular expression} to identify the index shortcut and the contents
786 % of the raw index file with this shortcut in the intermediate file. The
787 % default value is: ``\verb|^(\\indexentry)\[([^]]*)\](.*)$|'' for all but
788 % \Program{splitindex.tlu}. This means:
789 % \begin{description}
790 % \item[{\makebox[1em][l]{\texttt{\textasciicircum}}}]
791 % Search from beginning of the line.
792 % \item[\texttt{(\string\\indexentry)}]~\par
793 % Search for ``\verb|\indexentry|'' and
794 % set group 1 to this.
795 % \item[{\makebox[1em][l]{\texttt{\string\[}}}]
796 % Search for ``\verb|[|'' and ignore it.
797 % \item[\texttt{([\textasciicircum]]*)}]~\par
798 % Search for any character which is not ``]'' and set group 2 to this.
799 % \item[{\makebox[1em][l]{\texttt{\string\]}}}]
800 % Search for ``\verb|]|'' and ignore it.
801 % \item[\texttt{(.*)\$}]~\par
802 % Search for all characters till end of line and set group 3 to these.
803 % \end{description}
804 % The \meta{regular expression} is POSIX~1003.2 compatible.
805 % For \Program{splitindex.tlu} the default is:
806 % ``\verb|^(\\indexentry)%[([^]]*)%](.*)$|''.
807 % \item[\texttt{--resultis} \meta{pattern}]~
808 % \item[\texttt{-r} \meta{pattern}]\vspace{-2\itemsep} Set the lines, which
809 % are written to the generated raw index files after identification (see
810 % option \texttt{--identify}) to \meta{pattern}. Each
811 % \texttt{\$}\meta{digit} at \meta{pattern} will be replaced by the
812 % corresponding group, e.g. \verb|$1| will be replaced by the first group
813 % (see \texttt{--identify}). The default is: ``\verb|$1$3|'' for all but
814 % \Program{splitindex.tlu} resp. ``\verb|%1%3|'' for
815 % \Program{splitindex.tlu}, which means: contents of group 1 and group 3.
816 %
817 % If the \meta{regular expression} of option \texttt{--identify} doesn't
818 % match a line at the raw index file the line itself will be written.
819 % \item[\texttt{--suffixis} \meta{pattern}]~
820 % \item[\texttt{-s} \meta{pattern}]\vspace{-2\itemsep} Set the suffix of the
821 % names of the generated raw index files after identification (see option
822 % \texttt{--identify}) to \meta{pattern}. Each \texttt{\$}\meta{digit} at
823 % \meta{pattern} will be replaced by the corresponding group, e.g. \verb|$1|
824 % will be replaced by the first group (see \texttt{--identify}). The default
825 % is: ``\verb|-$2|'' resp. ``\verb|-%2|'', which means:
826 % character `\texttt{-}' followed by contents of group 2.
827 %
828 % If the \meta{regular expression} of option \texttt{--identify} doesn't
829 % match a line at the raw index file, all groups will be set to
830 % ``\texttt{idx}''.
831 % \item[\texttt{--verbose}]
832 % \item[{\makebox[1.2em][l]{\texttt{-v}}}]\vspace{-2\itemsep}
833 % Increase verbosity by one. More verbose means: tell the user more about,
834 % what the program is doing.
835 % \item[\texttt{--version}]
836 % \item[{\makebox[1.2em][l]{\texttt{-V}}}]\vspace{-2\itemsep}
837 % Show information about program version and terminate without processing a
838 % index file.
839 % \end{description}
840 %
841 % Some of the binaries compiled from the C source won't understand the long
842 % option names (\texttt{--makeindex}, \texttt{--identify} \dots). In this case
843 % you'd have to use the alternative short option names (\texttt{-m},
844 % \texttt{-i} \dots).
845 %
846 % The first non-option-argument in the command line is used as the name of the
847 % intermediate index file to be processed. All arguments that follow the
848 % argument ``\texttt{--}'' are interpreted as non-option arguments. All but
849 % the first non-option-arguments will be passed to the index processor.
850 %
851 % You will find some examples in the following subsections.
852 %
853 %
854 % \subsection{Using \Program{splitindex.pl}}
855 % \label{perl}
856 %
857 % This is the reference implementation. Let's use an example to demonstrate
858 % its use. If you have the following \LaTeX{} file ``\File{allabout.tex}'':
859 % \begin{verbatim}
860 % \documentclass{article}
861 % \usepackage[makeindex]{splitidx}
862 % \begin{document}
863 % Apples\sindex[fru]{apple} and oranges\sindex[fru]{orange} are
864 % fruits\sindex{fruits}.
865 % Tomatos\sindex[veg]{tomato} are vegetables\sindex{vegetables}.
866 % Cats\sindex[ani]{cat} are animals\sindex[idx]{animals}.
867 % \end{document}
868 % \end{verbatim}\vspace{-\baselineskip}
869 % this generates the intermediate index file ``File{allabout.idx}'':
870 % \begin{verbatim}
871 % \indexentry[fru]{apple}{1}
872 % \indexentry[fru]{orange}{1}
873 % \indexentry{fruits}{1}
874 % \indexentry[veg]{tomato}{1}
875 % \indexentry{vegetables}{1}
876 % \indexentry[ani]{cat}{1}
877 % \indexentry[idx]{animals}{1}
878 % \end{verbatim}\vspace{-\baselineskip}
879 %
880 % This file can't be processed by an index processor like
881 % \Program{MakeIndex}. In order to split this intermediate file into several
882 % raw index files and run the default index processor, you do the following
883 % call (the \Prompt{} is a symbol for the shell prompt):
884 % \begin{quote}
885 % \Prompt{}\verb|splitindex.pl allabout.idx|
886 % \end{quote}
887 % You may omit the extension ``\File{.idx}'':
888 % \begin{quote}
889 % \Prompt{}\verb|splitindex.pl allabout|
890 % \end{quote}
891 % Both commands will result in a file \File{allabout-fru.idx}:
892 % \begin{verbatim}
893 % \indexentry[fru]{apple}{1}
894 % \indexentry[fru]{orange}{1}
895 % \end{verbatim}\vspace{-\baselineskip}
896 % a file \File{allabout-idx.idx}
897 % \begin{verbatim}
898 % \indexentry{fruits}{1}
899 % \indexentry{vegetables}{1}
900 % \indexentry{animals}
901 % \end{verbatim}\vspace{-\baselineskip}
902 % a file \File{allabout-veg.idx}:
903 % \begin{verbatim}
904 % \indexentry[veg]{tomato}{1}
905 % \end{verbatim}\vspace{-\baselineskip}
906 % and a file \File{allabout-ani.idx}:
907 % \begin{verbatim}
908 % \indexentry[ani]{cat}{1}
909 % \end{verbatim}\vspace{-\baselineskip}
910 % After generation of these files, it calls the default index processor using
911 % the command lines:
912 % \begin{verbatim}
913 % makeindex allabout-fru.idx
914 % makeindex allabout-idx.odx
915 % makeindex allabout-veg.idx
916 % makeindex allabout-ani.idx
917 % \end{verbatim}\vspace{-\baselineskip}
918 % \begin{sloppypar}\noindent
919 % These calls create the index files \File{allabout-fru.ind},
920 % \File{allabout-idx.ind}, \File{allabout-veg.ind} and
921 % \File{allabout-ani.ind}, which can be loaded into the document using
922 % e.g.\ \cs{printindex} from package \Package{splitidx}.
923 % \end{sloppypar}
924 %
925 % If you don't want \Program{splitindex} to call any index processor, use
926 % \begin{quote}
927 % \Prompt{}\verb|splitindex.pl -m "" allabout|
928 % \end{quote}
929 % instead of the shell command above.
930 %
931 % You may obtain the same files as above using (it's one input line not two
932 % as shown here):
933 % \begin{quote}\raggedright
934 % \Prompt{}\verb|splitindex.pl -i '^\\indexentry\[([^]]*)\](.*)$'|
935 % \verb|-s '-$1'| \verb|-r '\\indexentry$2' allabout|
936 % \end{quote}
937 %
938 % If you want \Program{splitindex} to call \Program{makeindex} with the
939 % additional option ``\verb|-s foo.ist|'' to make it use the MakeIndex style
940 % file \File{foo.ist}, you can do so as follows:
941 % \begin{quote}
942 % \Prompt{}\verb|splitindex.pl allabout -- -s foo.ist|
943 % \end{quote}
944 % As you can see ``\verb|--|'' is used to prevent \Program{splitindex} from
945 % interpreting ``\verb|-s foo.ist|'' as option ``\verb|--suffixis foo.ist|''.
946 % All \Program{splitindex} options must be put before ``\verb|--|'', but you
947 % can put the raw file argument ``\verb|allabout|'' after that:
948 % \begin{quote}
949 % \Prompt{}\verb|splitindex.pl -- allabout -s foo.ist|
950 % \end{quote}
951 %
952 % If you want so use the index processor \Program{xindy} instead of default
953 % index processor \Program{MakeIndex}, you can use this call:
954 % \begin{quote}
955 % \Prompt{}\verb|splitindex.pl -m xindy allabout|
956 % \end{quote}
957 % If \Program{xindy} is not in your standard \texttt{PATH}, you may set the
958 % whole path:
959 % \begin{quote}
960 % \Prompt{}\verb|splitindex.pl -m /home/me/bin/xindy allabout|
961 % \end{quote}
962 % With most perl implementations, the perl module \verb|Getopt::Long| allows to
963 % put options after no-option-arguments. So you may also write:
964 % \begin{quote}
965 % \Prompt{}\verb|splitindex.pl allabout -m /home/me/bin/xindy|
966 % \end{quote}
967 % with the same result.
968 %
969 %
970 % \subsection{Using \Program{splitindex.jar}}
971 % \label{Java}
972 %
973 % This implementation should also be portable. If you are not using Sun
974 % Java~1.4.1 or higher, you may try to recompile this using the shell command:
975 % \begin{quote}
976 % \Prompt{}\verb|javac splitindex.java|
977 % \end{quote}
978 % This should result in a new \File{splitindex.class}. But it will fail
979 % e.g. with Sun Java 1.3, because regular expressions are needed, which are
980 % not available in Sun Java 1.3.
981 %
982 % The call of \Program{splitindex.class} is almost the same as shown for
983 % \autoref{perl} for \Program{splitindex.pl}, but you have to replace
984 % ``\verb|splitindex.pl|'' by ``\verb|java splitindex|''. So the last example
985 % from \autoref{perl} becomes:
986 % \begin{quote}
987 % \Prompt{}\verb|java splitindex allabout -m /home/me/bin/xindy|
988 % \end{quote}
989 %
990 %
991 % \subsection{Using \Program{splitindex.tex}}
992 % \label{TeX}
993 %
994 % The \TeX{} or \LaTeX{} program \Program{splitindex.tex} doesn't know any
995 % options or arguments. The number of files that it can generate is limited
996 % to to number of \TeX's free write handles. If there are any other lines than
997 % ``\verb|\indexentry|''-lines in the raw index file, running
998 % \Program{splitindex.tex} will result in an error.
999 %
1000 % You may use \Program{splitindex.tex} interactively:
1001 % \begin{quote}
1002 % \Prompt{}\verb|tex splitindex|
1003 % \end{quote}
1004 % or
1005 % \begin{quote}
1006 % \Prompt{}\verb|latex splitindex|
1007 % \end{quote}
1008 % If you do so, you will be asked for the name of the raw index file. You have
1009 % to omit the extension ``\File{.idx}'' answering that question.
1010 %
1011 % You may also use the \Program{splitindex.tex} not interactively, e.g. if you
1012 % are working with a batch. To do so you have to define macro \cs{IDX} to the
1013 % name of the raw index file without the extension ``\texttt{.idx}''. So the
1014 % first example of \autoref{perl} would become:
1015 % \begin{quote}
1016 % \Prompt{}\verb|tex \def\IDX{allabout}\input splitindex|
1017 % \end{quote}
1018 % You may also use \LaTeX{} instead of \TeX:
1019 % \begin{quote}
1020 % \Prompt{}\verb|latex \def\IDX{allabout}\input splitindex|
1021 % \end{quote}
1022 %
1023 % The current version of \Program{splitindex.tex} doesn't call any index
1024 % processor. But maybe a future version will be able to do so.
1025 %
1026 % \StopEventually{^^A
1027 % \begin{thebibliography}{99}
1028 % \bibitem{makeindex} \textsc{Leslie Lamport}: \textit{MakeIndex: An Index
1029 % Processor For \LaTeX}, 17 February 1987
1030 % \bibitem{makeindexmanual} \textsc{Pehong Chen}, \textsc{Rick P. C. Rodgers}:
1031 % \textit{MAKEINDEX(1L)}, Manual page, 10 December 1991
1032 % \end{thebibliography}
1033 % \PrintIndex\PrintChanges}
1034 %
1035 %
1036 % \subsection{Merging Indices}
1037 %
1038 % Now you should know how to use package \Package{splitidx} and the
1039 % \Program{SplitIndex} programs to split the index. But what about combining
1040 % two or more indices to one, e.g. you want vegetables and fruits in the
1041 % same index? Try this:
1042 % \begin{flushleft}\ttfamily
1043 % \cs{documentclass}\{article\} \percentchar \textit{ We use \Class{article}
1044 % class \dots}\\
1045 % \cs{usepackage}\{splitidx\} \percentchar \textit{ \dots\ and the
1046 % \Package{splitidx} package}\\
1047 % \cs{makeindex} \percentchar \textit{ And we want index generation}\\
1048 % ~\\
1049 % \percentchar \textit{ We define 4 indices:}\\
1050 % \cs{newindex}[General Index]\{idx\} \percentchar \textit{ Name and shortcut
1051 % of the 1st index}\\
1052 % \cs{newindex}[Index of Animals]\{ani\} \percentchar \textit{ \dots\ 2nd
1053 % index}\\
1054 % \cs{newindex}[Index of Fruits And Vegetables]\{fru\} \percentchar
1055 % \textit{ \dots\ 3rd
1056 % index}\\
1057 % ~\\
1058 % \cs{begin}\{document\}\\
1059 % Apples\cs{sindex}[fru]\{apple\} \percentchar \textit{ an entry to
1060 % }fru\texttt{ index}\\
1061 % and oranges\cs{sindex}[fru]\{orange\} \percentchar \textit{ an entry to
1062 % }fru\texttt{ index}\\
1063 % are fruits\cs{sindex}\{fruits\}.\ \percentchar \textit{ an implicit entry
1064 % to }idx\textit{ index}\\
1065 % Tomatoes\cs{sindex}[veg]\{tomato\} \percentchar \textit{ an entry to
1066 % }veg\textit{ index}\\
1067 % are\\
1068 % vegetables\cs{index}\{vegetables\}.\ \percentchar \textit{ an implicit
1069 % entry to }idx\textit{ index}\\
1070 % Cats\cs{sindex}[ani]\{cat\} \percentchar \textit{ an entry to
1071 % }ani\textit{ index}\\
1072 % are animals\cs{sindex}[idx]\{animals\}.\ \percentchar \textit{ an explicite
1073 % entry to }idx\textit{ index}\\
1074 % ~\\
1075 % \cs{printindex*} \percentchar \textit{ print all indices}\\
1076 % \cs{end}\{document\}
1077 % \end{flushleft}
1078 % And do the following call after splitting the index using
1079 % \Program{SplitIndex}:
1080 % \begin{quote}\raggedright
1081 % \Prompt{}\verb|makeindex allabout-veg.idx allabout-fru.idx|\\
1082 % \end{quote}
1083 % Alternatively you can concatenate \File{allabout-fru.idx} to
1084 % \File{allabout-veg.idx} before running the index processor on
1085 % \File{allabout-veg.idx}.
1086 %
1087 %
1088 %
1089 % \section{Implementation of \Package{splitidx}}
1090 %
1091 % \begin{macrocode}
1092 %<*package>
1093 % \end{macrocode}
1094 %
1095 % \subsection{Options}
1096 %
1097 % The first option is used to activate index generation.
1098 % \begin{macrocode}
1099 \DeclareOption{makeindex}{\AtEndOfPackage{\makeindex}}
1100 % \end{macrocode}
1101 %
1102 % \changes{v0.9}{2006/05/07}{new option \texttt{useindex}}
1103 % With option \texttt{useindex} the original command \cs{index} behaves like
1104 % \cs{sindex}.
1105 % \begin{macrocode}
1106 \DeclareOption{useindex}{%
1107 \def\@se@nd@xc@d@{\let\index\sindex}%
1108 \AtEndOfPackage{\@se@nd@xc@d@}%
1109 }
1110 \let\@se@nd@xc@d@\relax
1111 % \end{macrocode}
1112 %
1113 % There is also an option to make \cs{sindex} ignores the optional argument
1114 % and behaves like \cs{index}.%^^A
1115 % \changes{v1.2}{2013/04/04}{new option `allintoone'}%^^A
1116 % \changes{v1.2}{2013/04/04}{option `allatone' deprecated}%^^A
1117 % \begin{macrocode}
1118 \DeclareOption{allatone}{%
1119 \PackageWarning{splitidx}{Option `allatone' deprecated!\MessageBreak
1120 You should replace it by `allintoone'}%
1121 \ifx\@se@nd@xc@d@\relax\else
1122 \PackageInfo{splitidx}{option `allatone' overwrites option `useindex'}%
1123 \let\@se@nd@xc@d@\relax
1124 \fi
1125 \AtEndOfPackage{%
1126 \renewcommand*{\sindex}[1][]{\index}%
1127 \g@addto@macro\makeindex{\renewcommand*{\sindex}[1][]{\index}}%
1128 }%
1129 }
1130 \DeclareOption{allintoone}{%
1131 \ifx\@se@nd@xc@d@\relax\else
1132 \PackageInfo{splitidx}{option `allintoone' overwrites option `useindex'}%
1133 \let\@se@nd@xc@d@\relax
1134 \fi
1135 \AtEndOfPackage{%
1136 \renewcommand*{\sindex}[1][]{\index}%
1137 \g@addto@macro\makeindex{\renewcommand*{\sindex}[1][]{\index}}%
1138 }%
1139 }
1140 % \end{macrocode}
1141 %
1142 % \changes{v0.9}{2006/05/07}{new option \texttt{protected}}
1143 % Do not expand index arguments.
1144 % \begin{macrocode}
1145 \newif\if@verbindex\@verbindexfalse
1146 \DeclareOption{protected}{\@verbindextrue}
1147 % \end{macrocode}
1148 %
1149 % \changes{v0.2}{2002/11/15}{new option \texttt{idxcommands}}
1150 % With option \texttt{idxcommands} every \cs{newindex} also defines a new index
1151 % command.
1152 % \begin{macrocode}
1153 \newif\if@newidxcmd\@newidxcmdfalse
1154 \DeclareOption{idxcommands}{\@newidxcmdtrue}
1155 % \end{macrocode}
1156 %
1157 % \changes{v0.2}{2002/11/15}{new option \texttt{split}}
1158 % With option \texttt{split} each index uses its own index file.
1159 % \begin{macrocode}
1160 \newif\if@splitidx\@splitidxfalse
1161 \DeclareOption{split}{\@splitidxtrue}
1162 % \end{macrocode}
1163 %
1164 % Processing the options
1165 % \begin{macrocode}
1166 \ProcessOptions\relax
1167 % \end{macrocode}
1168 %
1169 %
1170 % \subsection{Setting an Index Entry}
1171 %
1172 % \begin{macro}{\see}
1173 % \begin{macro}{\seealso}
1174 % \begin{macro}{\seename}
1175 % \begin{macro}{\alsoname}
1176 % These are four standard macros, which are also defined at
1177 % \Package{makeidx}. Hey, these definitions are stolen from \Package{makeidx}!
1178 % No, no, I'm not a bad guy, read ``\File{legal.txt}'', which comes with
1179 % \Package{makeidx}.
1180 % \begin{macrocode}
1181 \newcommand*\see[2]{\emph{\seename} #1}
1182 \providecommand*\seealso[2]{\emph{\alsoname} #1}
1183 \providecommand\seename{see}
1184 \providecommand*\alsoname{see also}
1185 % \end{macrocode}
1186 % \end{macro}
1187 % \end{macro}
1188 % \end{macro}
1189 % \end{macro}
1190 %
1191 % \begin{macro}{\sindex}
1192 % \begin{macro}{\@wrsindex}
1193 % \changes{v0.9}{2006/03/07}{optionally do not expand the index argument}
1194 % \begin{macro}{\@@wrsindex}
1195 % This works similar to original \cs{index} but uses a splitted index. So it
1196 % allows an optional argument.
1197 % \begin{macrocode}
1198 \newcommand*{\sindex}[2][]{%
1199 }
1200 \g@addto@macro\makeindex{%
1201 \renewcommand*{\sindex}{%
1202 \@bsphack\begingroup
1203 \@sanitize
1204 \@wrsindex
1205 }%
1206 \typeout{Using splitted index at \jobname.idx}%
1207 \@se@nd@xc@d@
1208 }
1209 % \end{macrocode}
1210 % At the following \cs{@@wrsindex} is used as a hook. If it is defines, it is
1211 % used to write out the index entry. This hook may be used from
1212 % e.g. \Package{hyperref} to add \verb|hyperpage| to the font selection of the
1213 % page number. This only works with \verb+encap |+.
1214 % \changes{v1.0}{2006/07/30}{one level expansion of \cs{\@tempa} for
1215 % hyperref hook}
1216 % \begin{macrocode}
1217 \newcommand*{\@wrsindex}[2][]{%
1218 \ifx\relax#1\relax
1219 \if@splitidx
1220 \@wrsindex[idx]{#2}%
1221 \else
1222 \def\@tempa{#2}%
1223 \if@verbindex\@onelevel@sanitize\@tempa\fi
1224 \@wrindex{\@tempa}%
1225 \fi
1226 \else
1227 \def\@tempa{#2}%
1228 \csname index@#1@hook\endcsname
1229 \expandafter\ifx\csname @@wrsindex\endcsname\relax
1230 \@@@wrsindex{#1}{{\@tempa}{\thepage}}%
1231 \else
1232 \def\@tempb{\@@wrsindex{#1}}%
1233 \expandafter\@tempb\@tempa||\\%
1234 \fi
1235 \endgroup
1236 \@esphack
1237 \fi
1238 }
1239 \newcommand*{\@@@wrsindex}[2]{%
1240 \begingroup
1241 \if@splitidx
1242 \expandafter\ifx\csname @indexfile@#1\endcsname\relax
1243 \PackageError{splitidx}{%
1244 Index entry for not existing index%
1245 }{%
1246 You've tried to set an index to index `#1', without
1247 defining\MessageBreak
1248 that index before using \string\newindex.\MessageBreak
1249 This is only allowed, if you are not using package option
1250 `split'.%
1251 }%
1252 \else
1253 \expandafter\protected@write\csname @indexfile@#1\endcsname{%
1254 \csname index@#1@writehook\endcsname
1255 \csname index@#1@writehook@once\endcsname
1256 }{%
1257 \string\indexentry#2%
1258 }%
1259 \fi
1260 \else
1261 \protected@write\@indexfile{%
1262 \csname index@#1@writehook\endcsname
1263 \csname index@#1@writehook@once\endcsname
1264 }{%
1265 \string\indexentry[#1]#2%
1266 }%
1267 \fi
1268 \endgroup
1269 }
1270 % \end{macrocode}
1271 % If \Package{hyperref} was loaded at \cs{begin\{document\}} and
1272 % \Package{hyperref}-option \texttt{hyperindex} isn't disabled, and the hook
1273 % is not used, define it:
1274 % \changes{v1.2b}{2014/04/08}{\cs{ifHy@hyperindex} test changed}
1275 % \begin{macrocode}
1276 \AtBeginDocument{%
1277 \begingroup\expandafter\expandafter\expandafter\endgroup
1278 \expandafter\ifx\csname ifHy@hyperindex\endcsname\relax
1279 \else
1280 \expandafter\ifx\csname ifHy@hyperindex\expandafter\endcsname
1281 \csname iftrue\endcsname
1282 \@ifundefined{@@wrsindex}{%
1283 \def\@@wrsindex#1#2|#3|#4\\{%
1284 \ifx\\#3\\%
1285 \@@@wrsindex{#1}{{#2|hyperpage}{\thepage}}%
1286 \else
1287 \def\Hy@temp@A{#3}%
1288 \ifx\Hy@temp@A\HyInd@ParenLeft
1289 \@@@wrsindex{#1}{{#2|#3hyperpage}{\thepage}}%
1290 \else
1291 \ifx\Hy@temp@A\HyInd@ParenRight
1292 \@@@wrsindex{#1}{{#2|#3hyperpage}{\thepage}}%
1293 \else
1294 \@@@wrsindex{#1}{{#2|#3}{\thepage}}%
1295 \fi
1296 \fi
1297 \fi
1298 }%
1299 }{}%
1300 \fi
1301 \fi
1302 }
1303 % \end{macrocode}
1304 % \end{macro}
1305 % \end{macro}
1306 % \end{macro}
1307 %
1308 % \begin{macro}{\AtWriteToIndex}
1309 % \changes{v1.1}{2009/02/26}{New}
1310 % Add commands to the write hook.
1311 % \begin{macrocode}
1312 \newcommand*{\AtWriteToIndex}[1]{%
1313 \expandafter\ifx\csname index@#1@writehook\endcsname\relax
1314 \expandafter\let\csname index@#1@writehook\endcsname\@empty
1315 \fi
1316 \expandafter\g@addto@macro\csname index@#1@writehook\endcsname
1317 }
1318 % \end{macrocode}
1319 % \end{macro}
1320 % \begin{macro}{\AtNextWriteToIndex}
1321 % \changes{v1.1}{2009/02/26}{New}
1322 % Like \cs{AtWriteToIndex} only once.
1323 % \begin{macrocode}
1324 \newcommand*{\AtNextWriteToIndex}[1]{%
1325 \expandafter\ifx\csname index@#1@writehook@once\endcsname\relax
1326 \expandafter\gdef\csname index@#1@writehook@once\endcsname{%
1327 \expandafter\global\expandafter\let\expandafter
1328 \csname index@#1@writehook@once\endcsname\relax
1329 }%
1330 \fi
1331 \expandafter\g@addto@macro\csname index@#1@writehook@once\endcsname
1332 }
1333 % \end{macrocode}
1334 % \end{macro}
1335 %
1336 %
1337 % \subsection{Printing One Or More Indices}
1338 %
1339 % \begin{macro}{\printindex}
1340 % \begin{macro}{\printindex*}
1341 % This is used to print an index in the normal way. In most cases this uses
1342 % |theindex| environment, but it need not.
1343 % \begin{macrocode}
1344 \newcommand*{\printindex}{%
1345 % \end{macrocode}
1346 % The command may be called in the star version, which prints all defined
1347 % indices. This is same as \cs{printindices}.
1348 % \begin{macrocode}
1349 \@ifstar {%
1350 \begingroup
1351 \let\printindex@@endhook=\printindex@endhook
1352 \let\printindex@endhook=\relax
1353 \printindices%
1354 \csname printindex@@endhook\endcsname
1355 \endgroup
1356 }{%
1357 % \end{macrocode}
1358 % It may also be called with optional arguments to print one of the indices:
1359 % \begin{macrocode}
1360 \@ifnextchar [\@printindex%] brace check comment
1361 % \end{macrocode}
1362 % Or it is called without any parameter and so it is same as at
1363 % \Package{makeidx} package:
1364 % \begin{macrocode}
1365 {%
1366 \@input@{\jobname.ind}%
1367 \csname printindex@endhook\endcsname
1368 }%
1369 }%
1370 }
1371 % \end{macrocode}
1372 % \begin{macro}{\@printindex}
1373 % This is used to print one of the indices. The optional (here obligatory)
1374 % argument is the shortcut of the index.
1375 % \begin{macrocode}
1376 \newcommand*{\@printindex}{}
1377 \def\@printindex[#1]{%
1378 % \end{macrocode}
1379 % There can be one more optional argument, which is the title of the index. If
1380 % not, the default title \cs{index@\meta{shortcut}@name} is used.
1381 % \begin{macrocode}
1382 \@ifnextchar [%
1383 {\@@printindex[{#1}]}%
1384 {\@@printindex[{#1}][\csname index@#1@name\endcsname]}%
1385 }
1386 % \end{macrocode}
1387 % \begin{macro}{\@@pintindex}
1388 % \changes{v0.2}{2002/11/15}{with option \texttt{split} general index has no
1389 % suffix}
1390 % We use the default environment to print one of the indices, but we redefine
1391 % \cs{indexname} to the title of the wanted index, \cs{indexshortcut} to the
1392 % shortcut of the wanted index and \cs{index@preamble} to the preamble of the
1393 % wanted index. We do this in a group so it is local.
1394 % \begin{macrocode}
1395 \newcommand*{\@@printindex}{}
1396 \def\@@printindex[#1][#2]{%
1397 \begingroup
1398 \edef\indexshortcut{#1}%
1399 \def\indexname{#2}%
1400 % \end{macrocode}
1401 % \changes{v1.2c}{2016/02/18}{workaround for \Package{tcolorbox} library
1402 % \File{documentation}}^^A
1403 % The \Package{tcolorbox} library \File{documentation} uses
1404 % \cs{kvtcb@text@index} instead of \cs{indexname}. So we also redefine this
1405 % command.
1406 % \begin{macrocode}
1407 \def\kvtcb@text@index{#2}%
1408 \let\index@preamble\relax
1409 \expandafter\let\expandafter\index@preamble
1410 \csname index@\indexshortcut @preamble\endcsname
1411 \if@splitidx
1412 \def\@tempa{idx}\def\@tempb{#1}%
1413 \ifx\@tempa\@tempb\let\@indexsuffix\@gobble\fi
1414 \fi
1415 \@input@{\jobname\@indexsuffix{#1}.ind}%
1416 \endgroup
1417 \csname printindex@endhook\endcsname
1418 }
1419 % \end{macrocode}
1420 % \begin{macro}{\@indexsuffix}
1421 % This generated the suffix from the shortcut. You may redefine this
1422 % function, if you need. I`m using a trick here, to define the macro with
1423 % proper catcodes but not to define it global. You may also use
1424 % \cs{@firstofone} instead of \cs{lowercase}.
1425 % \begin{macrocode}
1426 \begingroup
1427 \catcode`\-12
1428 \lowercase{\endgroup
1429 \newcommand*{\@indexsuffix}[1]{-#1}%
1430 }
1431 % \end{macrocode}
1432 % \end{macro}
1433 % \end{macro}
1434 % \end{macro}
1435 % \end{macro}
1436 % \end{macro}
1437 %
1438 % \begin{macro}{\printindices}
1439 % This is used to print all defined indices in the order of their definition
1440 % and with their default titles. If the list is empty, is behaves like
1441 % \cs{printindex} without star and optional arguments.
1442 % \begin{macrocode}
1443 \newcommand*{\printindices}{%
1444 \ifx\@indices\@empty
1445 \printindex
1446 \else
1447 \begingroup
1448 \@for\@tempa:=\@indices\do{%
1449 \expandafter\printindex\expandafter[\@tempa]%
1450 }%
1451 \endgroup
1452 \fi
1453 }
1454 % \end{macrocode}
1455 % \end{macro}
1456 %
1457 % \begin{macro}{\newindex}
1458 % \changes{v0.2}{2002/11/15}{optional definition of index-shortcut-command}
1459 % \changes{v0.2}{2002/11/15}{optional opening a new index file}
1460 % The definition of a new index has an obligatory argument, the shortcut for
1461 % this index, and an optional argument, the name of this index. If you omit
1462 % the optional argument the shortcut is used for the default name if the
1463 % index. The definition will be done global!
1464 % \begin{macrocode}
1465 \newcommand*{\newindex}[2][\relax]{%
1466 \@ifundefined{index@#2@name}{%
1467 \if@verbindex
1468 \expandafter\gdef\csname index@#2@hook\endcsname{%
1469 \@onelevel@sanitize\@tempa
1470 }%
1471 \else
1472 \expandafter\gdef\csname index@#2@hook\endcsname{}%
1473 \fi
1474 \ifx\@indices\@empty
1475 \xdef\@indices{#2}%
1476 \else
1477 \xdef\@indices{\@indices,#2}%
1478 \fi
1479 \ifx \relax#1
1480 \expandafter\xdef\csname index@#2@name\endcsname{#2}%
1481 \else
1482 \expandafter\xdef\csname index@#2@name\endcsname{#1}%
1483 \fi
1484 \if@newidxcmd
1485 \expandafter\newcommand\expandafter*\csname #2\endcsname{}%
1486 \expandafter\gdef\csname #2\endcsname{%
1487 \sindex[#2]%
1488 }%
1489 \fi
1490 \if@splitidx
1491 \def\@tempa{#2}\def\@tempb{idx}%
1492 \ifx\@tempa\@tempb
1493 \global\let\@indexfile@idx=\@indexfile
1494 \else
1495 \expandafter\newwrite\csname @indexfile@#2\endcsname
1496 \expandafter\immediate\expandafter\openout
1497 \csname @indexfile@#2\endcsname=\jobname-#2.idx
1498 \fi
1499 \fi
1500 }{%
1501 % \end{macrocode}
1502 % If the index is already defined, an error occurs:
1503 % \begin{macrocode}
1504 \PackageError{splitidx}{%
1505 index `#2' already defined%
1506 }{%
1507 You have already defined an index with shortcut `#2'.\MessageBreak
1508 You can't define a new index with the same shortcut. If you'll continue
1509 \MessageBreak
1510 The new definition will be ignored.%
1511 }%
1512 }%
1513 }
1514 \if@splitidx
1515 \@onlypreamble\newindex
1516 \fi
1517 % \end{macrocode}
1518 % \end{macro}
1519 %
1520 % \begin{macro}{\newprotectedindex}
1521 % \changes{v0.9}{2006/07/03}{new command}
1522 % Same like \cs{newindex} but always define an index with protected arguments.
1523 % \begin{macrocode}
1524 \newcommand*{\newprotectedindex}[2][\relax]{%
1525 \begingroup\@verbindextrue\newindex[{#1}]{#2}\endgroup
1526 }
1527 % \end{macrocode}
1528 % \end{macro}
1529 %
1530 % \begin{macro}{\@indices}
1531 % This macro stores a list of the index shortcuts. This is needed by
1532 % e.g. \cs{printindices} and build by \cs{newindex}.
1533 % \begin{macrocode}
1534 \newcommand*{\@indices}{}
1535 \gdef\@indices{}
1536 % \end{macrocode}
1537 % \end{macro}
1538 %
1539 % \begin{macro}{\extendtheindex}
1540 % Extend \verb|theindex| by some macros called before starting the index,
1541 % after starting the index, before stopping the index and after stopping the
1542 % index. This may be used to change index behaviour. One additional change is
1543 % done, which may be useful: before the index \cs{index@preamble} is set to
1544 % \cs{index@\meta{shortcut}@preamble}.
1545 % \begin{macrocode}
1546 \newcommand{\extendtheindex}[4]{%
1547 \begingroup\expandafter\expandafter\expandafter\endgroup
1548 \expandafter\ifx\csname splitindex@theindex\endcsname\relax
1549 \let\splitindex@theindex=\theindex
1550 \let\endsplitindex@theindex=\endtheindex
1551 \fi
1552 \renewcommand*{\theindex}{%
1553 #1\splitindex@theindex #2%
1554 }%
1555 \renewcommand*{\endtheindex}{%
1556 #3\endsplitindex@theindex #4%
1557 }%
1558 }
1559 % \end{macrocode}
1560 % \end{macro}
1561 %
1562 % \begin{macro}{\setindexpreamble}
1563 % Set one of the splitted index preambles or the original one.
1564 % \begin{macrocode}
1565 \newcommand{\splitindex@setip}{}
1566 \let\splitindex@setip\setindexpreamble
1567 \let\setindexpreamble\relax
1568 \newcommand{\setindexpreamble}[2][]{%
1569 \ifx \relax#1\relax
1570 \begingroup\expandafter\expandafter\expandafter\endgroup
1571 \expandafter\ifx\csname splitindex@setip\endcsname\relax
1572 \@namedef{index@preamble}{#2}%
1573 \else
1574 \splitindex@setip{#2}%
1575 \fi
1576 \else
1577 \@namedef{index@#1@preamble}{#2}%
1578 \fi
1579 }
1580 % \end{macrocode}
1581 % \end{macro}
1582 %
1583 % \begin{macro}{\useindexpreamble}
1584 % Use the index preamble and optional add additional information after it, if
1585 % it exists and if it is not empty:
1586 % \begin{macrocode}
1587 \newcommand{\useindexpreamble}[1][]{%
1588 \begingroup\expandafter\expandafter\expandafter\endgroup
1589 \expandafter\ifx\csname index@preamble\endcsname\relax\else
1590 \ifx\index@preamble\@empty\else
1591 \index@preamble #1%
1592 \fi
1593 \fi
1594 }
1595 % \end{macrocode}
1596 % \end{macro}
1597 %
1598 % \begin{macro}{\printsubindex}
1599 % \begin{macro}{\printsubindex*}
1600 % Works like \cs{printindex} but changes some macros before to level down the
1601 % headings at the index generation.
1602 % \begin{macrocode}
1603 \newcommand*{\printsubindex}{%
1604 \begingroup
1605 \begingroup\expandafter\expandafter\expandafter\endgroup
1606 \expandafter\ifx\csname chapter\endcsname\relax
1607 \let\section\subsection
1608 \begingroup\expandafter\expandafter\expandafter\endgroup
1609 \expandafter\ifx\csname addsec\endcsname\relax\else
1610 \def\addsec{\setcounter{secnumdepth}{0}\subsection}%
1611 \fi
1612 \else
1613 \let\chapter\section
1614 \def\@makeschapterhead{\section*}
1615 \let\@makechapterhead\section
1616 \begingroup\expandafter\expandafter\expandafter\endgroup
1617 \expandafter\ifx\csname addchap\endcsname\relax\else
1618 \let\addchap\addsec
1619 \fi
1620 \fi
1621 % \end{macrocode}
1622 % Also, \cs{onecolumn} and \cs{twocolumn} and even \cs{clearpage} must be
1623 % disabled. The macros \cs{onecolumn} and \cs{twocolumn} cannot be let
1624 % \cs{relax} because the have an optional argument which must be used.
1625 % \begin{macrocode}
1626 \let\onecolumn\@firstoptofone
1627 \let\twocolumn\@firstoptofone
1628 \let\clearpage\relax
1629 \let\cleardoublepage\relax
1630 % \end{macrocode}
1631 % And the mark mechanism must also use one down:
1632 % \begin{macrocode}
1633 \def\markboth{\expandafter\markright\@gobble}%
1634 \ifx\@mkboth\@gobble\else\let\@mkboth\markboth\fi
1635 % \end{macrocode}
1636 % And the page style shouldn't change too:
1637 % \begin{macrocode}
1638 \let\thispagestyle\@gobble
1639 % \end{macrocode}
1640 % Now, using \cs{printindex} enables all of it's features:
1641 % \begin{macrocode}
1642 \let\printindex@endhook=\endgroup
1643 \printindex
1644 }
1645 % \end{macrocode}
1646 % \begin{macro}{\@firstoptofone}
1647 % Read the optional argument and do it.
1648 % \begin{macrocode}
1649 \providecommand{\@firstoptofone}[1][]{#1}
1650 % \end{macrocode}
1651 % \end{macro}
1652 % \end{macro}
1653 % \end{macro}
1654 %
1655 % \begin{macrocode}
1656 %</package>
1657 % \end{macrocode}
1658 %
1659 % \Finale
1660 %
1661 \endinput
1662 %
1663 % end of file `splitindex.dtx'
1664 %%% Local Variables:
1665 %%% mode: doctex
1666 %%% TeX-master: t
1667 %%% End: