Debian Codegraph @

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

raw
1 % \iffalse
2 %<*internal>
3 \begingroup
4 \input docstrip.tex
5 \keepsilent
6 \usedir{tex/latex/indextools}
7 \preamble
8 ___________________________________________________________
9 The indextools package for LaTeX
10 Copyright (C) 2010-2013 Enrico Gregorio
11 Copyright (C) 2014-* Maïeul Roquette
12 All rights reserved
13
14 License information appended
15
16 \endpreamble
17 \postamble
18
19 Copyright 2010--2013 Enrico Gregorio <Enrico dot Gregorio at univr dot it>
20
21 Copyright 2014 Maïeul Rouquette <maieul at maieul dot net>
22
23 Distributable under the LaTeX Project Public License,
24 version 1.3c or higher (your choice). The latest version of
25 this license is at: http://www.latex-project.org/lppl.txt
26
27 This work is "author-maintained"
28
29 This work consists of this file indextools.dtx, a README file
30 and the derived files indextools.sty and indextools.pdf.
31
32 \endpostamble
33 \askforoverwritefalse
34
35 \generate{\file{indextools.sty}{\from{indextools.dtx}{package}}}
36
37 \def\tmpa{plain}
38 \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
39 \endgroup
40 %</internal>
41 %
42 %<*driver>
43 \ProvidesFile{indextools.dtx}%
44 %</driver>
45 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
46 %<package>\ProvidesPackage{indextools}%
47 %<*package>
48 [2023/10/14 v1.7.0 Package for typesetting indices in a synchronous mode]
49 %</package>
50 %<*driver>
51 \documentclass{ltxdoc}
52 \def\prog#1{\textsf{\slshape#1}}
53 \def\progpdflatex{\textsf{(\textsl{pdf})\textsl{latex}}}
54 \def\eTeX{\mbox{$\varepsilon$-\TeX}}
55 \def\Kvalue#1{\textsf{\textsl{#1}}}
56 \def\pack#1{\textsf{#1}}
57 \def\class#1{\textsf{\itshape#1}}
58 \def\opz#1{\texttt{#1}}
59 \usepackage{multicol}
60 \usepackage[colorlinks]{hyperref}
61 \usepackage[T1]{fontenc}
62 \usepackage[utf8]{inputenc}
63 \usepackage[english]{babel}
64 \usepackage{textcomp,metalogo,booktabs}
65 \begin{document}
66 \frenchspacing
67 \makeatletter
68 \GetFileInfo{indextools.dtx}% dtx extension required
69 \title{The package \pack{indextools}\thanks{Version number \fileversion; last
70 revision \filedate.}}
71 \author{Maïeul Rouquette\thanks{\texttt{maieul at maieul dot net}} \\ from Enrico Gregorio's work}
72 \date{}
73 \maketitle
74 \begin{multicols}{2}
75 \tableofcontents
76 \end{multicols}
77 \smallskip
78 \RecordChanges
79 \DocInput{indextools.dtx}
80 \end{document}
81 %</driver>
82 % \fi
83 % \CheckSum{903}
84 %
85 % \changes{v1.0}{2010/07/10}{First public version}
86 % \changes{v1.0a}{2010/07/12}{Small bug correction}
87 % \changes{v1.1}{2012/05/09}{Fixed compatibility with \pack{memoir}}
88 % \changes{v1.1}{2012/05/09}{Modified interaction with Lua\TeX}
89 % \changes{v1.1a}{2012/09/07}{Fixed bug with possibly defined \cs{directlua}}
90 % \changes{v1.2}{2012/08/31}{made package compatible with showidx}
91 % \changes{v1.2}{2012/08/31}{made package compatible with fancyhdr}
92 % \changes{v1.2}{2012/08/31}{added index processing engine option truexindy}
93 % \changes{v1.2c}{2012/10/02}{Fixed regression}
94 % \changes{v1.2d}{2012/10/06}{Fixed bugs with index internal names}
95 % \changes{v1.2e}{2012/10/22}{Fixed bug with showidx simulated by memoir}
96 % \changes{v1.3}{2013/07/11}{Added internal so as to cooperate in a better
97 % way with eledmac (by Maïeul Rouquette)}
98 % \changes{v1.4}{2015/01/23}{Compatibility with bidi. Fork from imakeidx. New name indextools}
99 % \changes{v1.5}{2015/11/15}{New option `afterindex'}
100 % \changes{v1.5}{2015/11/15}{New option `innote'}
101 % \changes{v1.5}{2015/11/15}{New option `notenumber'}
102 % \changes{v1.5.1}{2015/11/22}{Fix bug with options `notenumber' and `innote' when using \cs{index} without optional argument}
103 % \changes{v1.6.0}{2023/10/10}{Add compatibility with upmendex sorting engine}
104 % \changes{v1.7.0}{2023/10/04}{Add compatibility with xindex sorting engine}
105 %
106 % \begin{abstract}
107 % This package is a fork of the \pack{imakeidx} package. The original authors
108 % of \pack{imakeidx} were Claudio Beccari and Enrico Gregorio; the first author withdrew his availability as a maintainer in 2013. The second author declined
109 % some upgrade suggestions to remove some incompatibilities with certain
110 % packages that are particularly important with critical editions dealing with
111 % languages that are being written from right to left.
112 % Therefore this fork, named \pack{indextools}, was created by Maïeul Rouquette,
113 % who acknowledges the work of the two preceding authors thanking them for the
114 % excellent package they created; nevertheless this fork was necessary in order
115 % to let other users benefit from its functionalities very useful in the field
116 % of humanities.
117 %
118 % We hope that one day, only one package will be provided.
119 % The differences with the \pack{imakedix} are:
120 % \begin{itemize}
121 % \item the name;
122 % \item the compatibility with package \pack{bidi};
123 % \item this documentation.
124 % \end{itemize}
125 % This package replaces and extends the functionalities of \pack{imakeidx},
126 % therefore it MUST not be loaded at the same time as \pack{imakeidx}. Some
127 % controls are implemented to avoid these situations; if loading of
128 % \pack{indextools} is required after \pack{imakeidx} is already loaded,
129 % it does not get loaded; at the same time, if it gets loaded, it sets a
130 % suitable macro so that \pack{imakeidx} can't be loaded after
131 % \pack{indextools}.
132 %
133 % This package exploits the |\write18| facility of modern \TeX\ system
134 % distributions that allows to run system commands while typesetting a
135 % document written with the \LaTeX{} mark up. By so doing, the index
136 % or indices, that are usually typeset at the very end of the
137 % document, are possibly split and sorted so as to include them in the
138 % document itself. This process has some minor limitations: it's
139 % impossible to start an index before all other pages have been
140 % ejected.
141 %
142 % For support, please open issues on:\\[1ex]
143 % \makebox[\linewidth]{\url{https://github.com/maieul/indextools}}
144 % \end{abstract}
145 %
146 % \section{Introduction}
147 % It's been some years now that the typesetting engine of the \TeX\
148 % system is just \prog{pdftex}; the original Knuthian \prog{tex} is
149 % still corrected by D.\,E.~Knuth himself, but is frozen, according to
150 % his will; it is still distributed by every \TeX\ distribution, but
151 % in practice \prog{pdftex}, \prog{xetex} or \prog{luatex} are the most used
152 % interpreters and typesetting engines of most macro packages.
153 %
154 % This program \prog{pdftex} was originally born with the facility of
155 % producing either a pdf output file, as its name suggests, or a dvi
156 % file. Since then it has been enriched with many upgrades, also with
157 % regard to the evolution of the PDF language itself. It also
158 % incorporates the extensions of \eTeX\ and has the ability to open a
159 % shell so as to run system commands with their arguments. The same
160 % is true for \prog{xetex} and \prog{luatex}.
161 %
162 % This facility, since the \TeX~Live 2010 distribution, is official,
163 % but is sort of restricted, in the sense that the \TeX\ system
164 % configuration file contains a list of ``safe'' system commands that
165 % can be run by \prog{pdftex}; presently the only program relevant for
166 % this package is \prog{makeindex}. This precaution is necessary in
167 % order to avoid running malicious code. Other programs can be run,
168 % though, but it's necessary to expressly tell \prog{pdftex} that it
169 % can do so; this authorisation is given by means of a suitable
170 % program option, as explained below.
171 %
172 % This package will exploit this facility in order to run a perl
173 % script that is capable of splitting a raw index file into different
174 % chunks and to run the \prog{makeindex} or \prog{xindy} \TeX\ system
175 % programs so as to sort and format the index entries according to a
176 % specified index style file. Once the shell is terminated, the
177 % typesetting program resumes its work and possibly prints the various
178 % formatted indices produced in previous steps. In this way the document
179 % indices are always synchronous with their document and no further
180 % typesetting runs are necessary.
181 %
182 % In order to reach this goal, it is necessary that at least the
183 % restricted |write18| facility is enabled; if the \TeX\ distribution
184 % in use does not enable this restricted feature by default, it
185 % is necessary to enable the typesetting engine to run such facility;
186 % depending on the distribution and the shell editor that is being
187 % used to work on a specific document, it is necessary to add
188 % \texttt{-\/-shell-escape} (or \texttt{-\/-enable-write18} for MiK\TeX)
189 % to the command with which the typesetting program is launched,
190 % possibly through the shell editor. This applies to all three
191 % \prog{pdftex}, \prog{xetex}, and \prog{luatex} typesetting engines.
192 %
193 % {\medskip\footnotesize If Lua\LaTeX{} is used and \prog{luatex} is
194 % version 0.42 to 0.66, it's impossible to distinguish whether the
195 % restricted shell escape is active or not, so the automatic procedure
196 % will be tried anyway, unless disabled with the \texttt{noautomatic}
197 % package option. With version 0.68 or later, the behaviour is the same
198 % as with the other engines.\par}
199 %
200 %
201 %\section{Package usage}
202 % This package is invoked as usual by means of a \cs{usepackage} command:
203 % \begin{flushleft}
204 % \cs{usepackage}\oarg{options}\texttt{\{indextools\}}
205 % \end{flushleft}
206 %
207 % The available \meta{options} consist in a comma separated list of
208 % the following options:
209 % \begin{description}\def\Item[#1]{\item[\normalfont\ttfamily#1]}
210 % \Item[makeindex] in order to use the \prog{makeindex} sorting and
211 % formatting engine; this option is the default and is mutually
212 % exclusive with the three next options.
213 % \Item[xindy] in order to use the \prog{xindy} sorting and formatting
214 % engine; \texttt{texindy} is an alias for \texttt{xindy} and actually
215 % it's the script \prog{texindy} which is called by this package.
216 % Nevertheless if the real \prog{xindy} is desired, in order to avoid
217 % the settings made up by \prog{texindy}, so as to add \prog{xindy}
218 % the command line specific settings, it is possible to specify the
219 % option \texttt{truexindy}; the user is then responsible to set up
220 % the \prog{xindy} engine with the suitable command line options.
221 % \Item[upmendex] in order tu use the \prog{upmendex} sorting and formatting engine.
222 % \Item[xindex] in order tu use the \prog{xindex} sorting and formatting engine.
223 % \Item[noautomatic] disables the automatic splitting of the raw
224 % index files and running of the system programs; this option might
225 % be used to save time when one knows for sure that the index files
226 % are already OK and do not need to be refreshed. Actually the time
227 % spent in splitting, sorting and formatting is so short that this
228 % option might be useful only when very lengthy indices are being
229 % processed.
230 % \Item[nonewpage] inhibits the new page command to be issued when
231 % using an article type document class and multiple indices are being
232 % typeset. We don't see why someone would use multiple indices in an
233 % article (except possibly for package documentations, which usually
234 % provide a macro index and a list of changes).
235 % \Item[quiet] suppresses all messages about manual index processing.
236 % \Item[original] uses the class-provided \texttt{theindex}
237 % environment for typesetting the indices; it is implicitly set if the
238 % document class option \texttt{twocolumn} has been specified.
239 % \Item[afterindex] allows to use \cs{index} command after \cs{printindex}.
240 % If this case, the index will be printed only on the secund run.
241 % \Item[innote] adds a mark for content indexed in note. The standard mark is an italic `n' added after the page number. You can redefine the \cs{innote} command to modify the standard mark.
242 % The default value is:\\
243 % \begin{verbatim}
244 % \providecommand{\innote}[1]{#1\textit{n}}
245 % \end{verbatim}
246 % \Item[notenumber] adds the note number for content indexed in note. The standard marks is a `n.' followed by the note number.
247 % You can redefine \cs{innotenumber} to modify the standard mark.
248 % The default value is:\\
249 % \begin{verbatim}
250 % \providecommand{\innotenumber}[2]{#2n.~#1}
251 % \end{verbatim}
252 % \Item[splitindex] calls the \prog{splitindex} script by Markus Kohm,
253 % which is included in every \TeX~Live distribution since 2009. With
254 % this option all index entries, which are written in one raw index
255 % file, are successively split into all the requested index files;
256 % in this way there is virtually no limit on the number of indices
257 % that is possible to create for a particular document.
258 % \end{description}
259 %
260 % The last described option deserves an explanation. \LaTeX\ can
261 % write on a limited number of files during a run, and some of these
262 % \emph{output streams} are already reserved (among these: aux files,
263 % toc files, lof files, lot files, plus several other ones). When more than
264 % one index is produced, there's the risk to run off the number of
265 % writable files, because normally \pack{indextools} reserves an output
266 % stream for each index. So the \texttt{splitindex} option comes to
267 % rescue: with it only \emph{one} raw index file is written out. At the
268 % first \cs{printindex} command, the program \prog{splitindex} is
269 % called; it splits the large index file into as many parts as the
270 % number of requested indices; after this, \prog{makeindex} or
271 % \prog{xindy} can do their job. In this way only one output stream is
272 % needed during the \LaTeX\ run.
273 %
274 % When should you apply this option, then? With one index it's
275 % useless, you should begin to consider it for two or more indices and
276 % definitely use it if you get the error message
277 % \begin{verbatim}
278 % ! No room for a new \write
279 % \end{verbatim}
280 % Apart from this case, with or without it, the results are the
281 % same. See section~\ref{sec:wrong} to see what files are written
282 % during the \LaTeX\ run with or without the option.
283 %
284 % \section{Specific package commands}
285 % As it is customary when just one index is produced, the standard
286 % \LaTeX\ facilities, i.e.\ the commands \cs{makeindex}, \cs{index},
287 % and \cs{printindex} must be used. This package redefines them so as
288 % to produce multiple indices and defines some other commands. The first three
289 % of the following commands may be used only in the preamble.
290 % \begin{description}\def\Item[#1]{\item[\normalfont\ttfamily\cs{#1}]}
291 % \Item[makeindex] with the syntax:\\[1ex]
292 % \cs{makeindex}\oarg{key-values}\\[1ex]
293 % where \meta{key-values} is a comma separated list of key-value
294 % assignments of the form: \texttt{key=value}; the available
295 % keys are the following:
296 % \begin{description}\def\Item[#1]{\item[\normalfont\sffamily\textsl{#1}]}
297 % \Item[name] is the symbolic name for an index; if this key is not
298 % specified, it defaults to the value of the \cs{jobname} control
299 % sequence, in other words the name of the current main \texttt{.tex}
300 % file, i.e., the file that |\input|s and/or |\include|s all the files
301 % of the complete document. This symbolic name is necessary only when
302 % doing multiple indices and is used with the \cs{index}
303 % command to point to the right index.\\*
304 % Example: \texttt{name=nameidx}
305 % \Item[title] is the title that is typeset at the beginning of the
306 % specific index; if not specified, the \cs{indexname} value is
307 % used.\\* Example: \texttt{title=Index of names}.
308 % \Item[program] is the name of the system program that is used to
309 % sort and format an index; valid choices are \prog{makeindex} ;
310 % \prog{xindy}, or \prog{texindy}, plus \prog{truexindy} ; \prog{upmendex} ; \prog{xindex}. If not
311 % specified the program specified among the package options is used.
312 % If no option is specified, \prog{makeindex} is used. In order to
313 % use \prog{xindy}, it's necessary to call \prog{pdflatex} with
314 % the shell escape command line option.\\* Example: \texttt{program=xindy}.
315 % \Item[options] is the list of options to be passed to the sorting
316 % and formatting program; this list is a balanced text of program
317 % options, separated with the syntax required by the sorting and
318 % formatting program. For example, in order to use a different
319 % \prog{makeindex} sorting and formatting style \pack{mystyle.ist} and
320 % avoiding any message in the screen output, write \texttt{options=-s
321 % mystyle}.
322 % \Item[noautomatic] is a boolean key that defaults to \texttt{false};
323 % you can set it to \texttt{true} by simply listing its key in the
324 % key-value list, without necessarily specifying the \texttt{=true}
325 % part. If specified the index sorting program won't be called during
326 % the typesetting run for this particular index.
327 % \Item[intoc] is a boolean variable that defaults to \texttt{false};
328 % if you want to set it \texttt{true} you must simply list this key in
329 % the key-value list, with no need of specifying the \texttt{=true}
330 % part. By setting this key to \texttt{true} an entry for this
331 % particular index is put in the table of contents.
332 % \Item[columns] accepts an integer representing the number of columns
333 % in the index; this is silently ignored if the \texttt{original} or
334 % the \texttt{twocolumn} options are set; the number can even
335 % be~$1$.\\* Example: \texttt{columns=3}
336 % \Item[columnsep] accepts a dimension representing the separation
337 % between index columns; the default is $35$\,pt as in the standard
338 % classes.\\* Example: \texttt{columnsep=15pt}
339 % \Item[columnseprule] is a boolean option; if it is set, a rule will appear
340 % between the index columns.
341 % \end{description}
342 % \Item[indexsetup] with the syntax:\\[1ex]
343 % \cs{indexsetup}\marg{key-values}\\[1ex]
344 % where again \meta{key-values} is a comma separated list of \texttt{key=value}
345 % assignments; the available keys are:
346 % \begin{description}\def\Item[#1]{\item[\normalfont\sffamily\textsl{#1}]}
347 % \Item[level] whose acceptable values are sectioning commands such as
348 % \cs{chapter} or \cs{chapter*}. Actually any command with an argument
349 % will do and will receive the index title as its argument. The
350 % default is \cs{chapter*} or, if the class doesn't provide chapters,
351 % \cs{section*}. If you specify |\chapter| so as to override the default
352 % starred command |\chapter*|, the index title goes directly to the table
353 % of contents; in this case do not specify the \texttt{intoc} option.
354 % ^^A
355 % \Item[toclevel] whose acceptable value is a sectioning command
356 % \emph{name} such as \texttt{section} to indicate the level at which
357 % we want the indices appear in the table of contents.
358 % ^^A
359 % \Item[noclearpage] is a boolean option; when set, no \cs{clearpage}
360 % will be issued between indices. You might want to set it in order to
361 % have a `chapter of indices'; in this case you are responsible for
362 % setting the right value of the above keys. For example
363 %\begin{verbatim}
364 % \indexsetup{level=\section*,toclevel=section,noclearpage}
365 % ...
366 % \chapter*{Indices}
367 % \printindex
368 % \printindex[names]
369 % \printindex[objects]
370 %\end{verbatim}
371 % See more on this subject in section~\ref{sec:hints}
372 % ^^A
373 % \Item[firstpagestyle] whose acceptable value is a page style, default
374 % \texttt{plain}. You might want to set it to \texttt{empty} or some
375 % other page style defined by the class or by yourself. This keyword
376 % is disabled when the package \pack{fancyhdr} is loaded; any definition
377 % or choice of page styles must be done before typesetting the indices.
378 % ^^A
379 % \Item[headers] which takes two values: the left and right marks. You
380 % might want to use this for disabling automatic uppercasing, by
381 % saying, for example, |headers={\indexname}{\indexname}|; notice that
382 % these values should always be a pair of balanced braced texts.
383 % Don't use these keys if you use \pack{fancyhdr}.
384 % ^^A
385 % \Item[othercode] whose acceptable value is arbitrary \TeX\ code that
386 % will be executed at the beginning of index entries typesetting. For
387 % example you might want to change here the setting of \cs{parskip}.
388 % \end{description}
389 % ^^A
390 % \Item[splitindexoptions] must have as its argument the command line
391 % option to \prog{splitindex}; this might be necessary on some
392 % systems. The default is |-m ""|, because we want it only for
393 % splitting the large index file into its components which are later
394 % processed by this package. See the \prog{splitindex} documentation
395 % for other options.
396 % ^^A
397 % \Item[index] with the syntax:\\[1ex]
398 % \cs{index}\oarg{name}\marg{entry}\\[1ex]
399 % inserts \meta{entry} in the raw index file named \meta{name}; if only
400 % one raw index file is being built in order to split it in different index
401 % files by means of \prog{splitindex}, the \meta{entry} is listed in the
402 % specific slit index file with name \meta{name}; if no name is specified,
403 % this \meta{entry} is added to the default index with name
404 % \cs{jobname}. The \meta{entry} should be written according to the
405 % particular syntax of the sorting and formatting program.
406 % ^^A
407 % \Item[indexprologue] with the syntax:\\*[1ex]
408 % \cs{indexprologue}\oarg{spacing}\marg{text}\\[1ex]
409 % is used to define some \meta{text} to go between the index header and the
410 % entries; the \meta{spacing} should be a vertical space command such
411 % as |\vspace{36pt}| (default is \cs{bigskip}), controlling the
412 % spacing between the prologue and the index proper. The command
413 % affects only the next index produced by \cs{printindex} and is best
414 % placed just before this command. Please read ahead for further
415 % information on the use of this command.
416 % ^^A
417 % \Item[printindex] with the syntax:\\*[1ex]
418 % \cs{printindex}\oarg{name}\\[1ex]
419 % is used to typeset the particular index named \meta{name}; if no
420 % optional argument is specified, the default index with name
421 % \cs{jobname.ind} is typeset. Actually this command activates all
422 % the mechanism of closing the output to the raw index file, shelling
423 % out, possibly calling the \prog{splitindex} script in order to
424 % divide the single raw file generated by the typesetting engine into
425 % distinct raw files according to the default or specified
426 % \meta{name}s for each index, calling the sorting and
427 % formatting program on each of these split raw files (unless
428 % inhibited by a \Kvalue{noautomatic} option; in which case a warning
429 % is issued in order to remember the typesetter that this particular
430 % index has not been processed), producing the sorted and formatted
431 % \texttt{.ind} files, and eventually inputs and typesets these
432 % formatted files. \ Deep breath.
433 % \end{description}
434 %
435 % Let's see an example. The sequence of commands
436 %\begin{verbatim}
437 % ...
438 % \usepackage{indextools}
439 % ...
440 % \makeindex[title=Concept index]
441 % \makeindex[name=persons,title=Index of names,columns=3]
442 % ...
443 % \begin{document}
444 % ...
445 % ...relativity\index{relativity}...
446 % ...
447 % ... Einstein\index[persons]{Einstein, Albert}...
448 % ...
449 % And this is the end of the story.
450 %
451 % \printindex
452 %
453 % \indexprologue{\small In this index you'll find only
454 % famous people's names}
455 % \printindex[persons]
456 % \end{document}
457 %\end{verbatim}
458 % will produce two indices. Entries for either index must be typed as
459 % shown above. The prologue will be printed (full text width) only
460 % in the ``Index of names'', which will be typeset in three columns.
461 %
462 % When the \texttt{original} option is set, maybe implicitly because
463 % of \texttt{twocolumn}, \cs{indexsetup} and the keys
464 % \Kvalue{columns}, \Kvalue{columnsep} and \Kvalue{columnseprule} for
465 % \cs{makeindex} have no effect. Please read more on this matter further~on.
466 %
467 % \section{If something goes wrong}\label{sec:wrong}
468 % Since \pack{indextools} relies on good cooperation between package
469 % options and command line options for the \LaTeX\ run, in some cases
470 % it may happen that the indices are not correctly built or built at
471 % all.
472 %
473 % If you use only \prog{makeindex} and \TeX~Live 2010 or later, then
474 % you shouldn't need anything special, since \prog{makeindex} is among
475 % the safe programs allowed to be called during a \LaTeX\ run, be it
476 % \prog{latex}, \prog{pdflatex}, \prog{xelatex}, or \prog{lualatex}.
477 %
478 % When the options \texttt{splitindex}, \texttt{xindy},
479 % \texttt{texindy} or \texttt{truexindy} are specified (globally or
480 % locally), the \LaTeX\ run should be called with the unrestricted
481 % \texttt{-\/-shell-escape} (which is \texttt{-\/-enable-write18} for
482 % MiK\TeX) typesetting program option or the \texttt{noautomatic}
483 % option should be specified when loading \pack{indextools}.
484 %
485 % Let's look at a couple of examples. In both we suppose that the
486 % document \texttt{mybook.tex} defines two indices through
487 %\begin{verbatim}
488 % \makeindex[...]
489 % \makeindex[name=secondary,...]
490 %\end{verbatim}
491 % where |...| denotes possible options excluding \texttt{name}.
492 %
493 % First of all we examine the case when \pack{indextools} is called
494 % \emph{without} \texttt{splitindex}. Two files called
495 % \texttt{mybook.idx} and \texttt{secondary.idx} will be written
496 % during the \LaTeX\ run. At the corresponding \cs{printindex}
497 % command, \prog{makeindex} will act on each of them producing the files
498 % \texttt{mybook.ind}, \texttt{mybook.ilg}, \texttt{secondary.ind} and
499 % \texttt{secondary.ilg}. The \texttt{.ind} files contain the relevant
500 % \texttt{theindex} environments with alphabetised entries, while in
501 % the \texttt{.ilg} files \prog{makeindex} will write its log. You can
502 % check in \texttt{mybook.log} whether the \prog{makeindex} run has
503 % been executed by searching for a line
504 %\begin{verbatim}
505 % runsystem(makeindex <...>)...executed
506 %\end{verbatim}
507 % where |<...>| stands for the rest of the command line in the
508 % particular case. If this line is not present, then \prog{makeindex}
509 % has not been called; this happens when you didn't specify the shell
510 % escape command line option for the \LaTeX\ run or the restricted
511 % shell escape is not active; also, of course, if you set the
512 % \texttt{noautomatic} option for the index.
513 %
514 % {\tolerance=9999
515 % When using \prog{splitindex}, the situation is different. During the
516 % \LaTeX\ run, only a large index file called \texttt{mybook.idx} file
517 % gets written; the first \cs{printindex} command will call
518 % \prog{splitindex} (unrestricted shell escape \emph{must} be active),
519 % which will produce the two partial index files \texttt{mybook-mybook.idx}
520 % and \texttt{mybook-secondary.idx}. These two files will be processed by
521 % \prog{makeindex} producing the four files \texttt{mybook-mybook.ind},
522 % \texttt{mybook-mybook.ilg}, \texttt{mybook-secondary.ind} and
523 % \texttt{mybook-secondary.ilg}.
524 % The line
525 %\begin{verbatim}
526 % runsystem(splitindex <...>)...executed
527 %\end{verbatim}
528 % in \texttt{mybook.log} will tell that the splitting has been done
529 % (see later on if this doesn't seem true). In table~\ref{tab:files} you
530 % can see what files are produced when the first two lines are in the
531 % preamble.\par}
532 %
533 % \begin{table}[tp]
534 % \centering\begingroup\ttfamily
535 % \begin{tabular}{rll}
536 % \toprule
537 % \multicolumn{3}{c}{\ttfamily\cs{makeindex}\hphantom{[name=secondary]}}\\
538 % \multicolumn{3}{c}{\ttfamily\cs{makeindex}[name=secondary]}\\
539 % \midrule
540 % \addlinespace
541 % &\normalfont without \texttt{splitindex} &
542 % \normalfont with \texttt{splitindex} \\
543 % \cmidrule(lr){2-2} \cmidrule(lr){3-3}
544 % \addlinespace
545 % \normalfont(at \cs{begin}\texttt{\{document\}})\\
546 % \addlinespace
547 % &mybook.idx & mybook.idx \\
548 % &secondary.idx \\
549 % \addlinespace
550 % \normalfont(at \cs{printindex})\\
551 % \addlinespace
552 % &mybook.ind & mybook-mybook.idx \\
553 % &mybook.ilg & mybook-secondary.idx\\
554 % &secondary.ind & mybook-mybook.ind\\
555 % &secondary.ilg & mybook-mybook.ilg\\
556 % & & mybook-secondary.ind \\
557 % & & mybook-secondary.ilg \\
558 % \bottomrule
559 % \end{tabular}\endgroup
560 % \caption{Files written during a \LaTeX\ run}\label{tab:files}
561 % \end{table}
562 %
563 % Everything is the same when using \prog{texindy} for alphabetising,
564 % except that, by default, it doesn't write \texttt{.ilg} files. If
565 % you want them, add |options=-t |\meta{name}|.ilg| to the relevant
566 % \cs{makeindex} command, in our example it should be
567 %\begin{verbatim}
568 % \makeindex[...,options=-t mybook.ilg]
569 % \makeindex[name=secondary,...,options=-t secondary.ilg]
570 %\end{verbatim}
571 % The name of the \texttt{.ilg} file \emph{must} be specified.
572 % Remember, though, that \prog{xindy} \texttt{.ilg} files may turn out
573 % to be very large.
574 %
575 % When something different from expected appears to take place, check
576 % also the time stamps of the produced files; if they are older than
577 % \texttt{mybook.log}, it means that they have not been written in the
578 % last run. The most common case is that you forgot to activate the shell
579 % escape feature (which is not necessary with \TeX~Live 2010 or later,
580 % provided you use only \prog{makeindex}).
581 %
582 % Another cause of malfunction might be a wrong option passed to
583 % \prog{makeindex}, \prog{texindy} or \prog{splitindex}. For example,
584 % if you specify a style option for \prog{makeindex} such as
585 % |options=-s mystyle.ist| and the style file is missing or its name
586 % is mistyped, the run of \prog{makeindex} will result in
587 % \texttt{mybook.log}, but it will be aborted and the \TeX\ program
588 % has no control over this process. In this case the \texttt{.ilg} and
589 % \texttt{.ind} files will not be produced and you can spot the
590 % problem by checking the time stamps. On some systems a message such as
591 %\begin{verbatim}
592 % Index file mystyle.ist not found
593 % Usage: makeindex [-ilqrcgLT] [-s sty] [-o ind] [-t log] [-p num]
594 %\end{verbatim}
595 % may appear on the screen, but often this window gets closed before
596 % you realize you have a problem. The time stamp is the best clue to
597 % detect such problems.
598 %
599 % Shell hackers may be able to redirect the \texttt{stderr} stream to
600 % a file, but this requires skills that can't be explained here,
601 % because they require tens of different tricks, depending on what
602 % method is used to start a \LaTeX\ run. From the command line,
603 % assuming \prog{bash}, it would be something like
604 %\begin{verbatim}
605 % pdflatex --shell-escape mybook.tex 2>latex-errors
606 %\end{verbatim}
607 % If shell hackers know a way to access the exit status of the called
608 % program, we'd be glad to implement a supplementary check.
609 %
610 % \section{Hints}\label{sec:hints}
611 % Actually this package reaches two goals: (\textit{a})~it typesets
612 % the indices of a specific document in just one run, and
613 % (\textit{b})~it lets the author\slash typesetter produce
614 % documents with multiple indices.
615 %
616 % \subsection{Conflicts}
617 %
618 % \subsubsection{Two columm typesetting and index prologue}
619 % As it has been already mentioned, it is possible to use the command
620 % |\indexprologue| to write some text before the index proper gets typeset;
621 % an optional space may be used in place of the default one-line spacing
622 % between the index title, the prologue and the index body.
623 %
624 % This facility relies on a particular feature of the |multicols|
625 % environment, that \pack{indextools} uses to instruct the typesetting
626 % program to typeset the index with a specified number of balanced columns.
627 % The choice of |multicols| has been made because it balances the
628 % columns in the last page; the declaration |\twocolum| does not
629 % perform the same way, and, if used, it makes |\printindex| typeset
630 % the index in two-column mode with an unbalanced last column.
631 %
632 % In the previous sections it has been clearly stated that any
633 % configuration of the way \pack{indextools} typesets the indices
634 % is bypassed if the option \opz{original} has been specified
635 % either explicitly or implicitly. It is implicitly specified
636 % if the option \opz{twocolumn} is specified in the class
637 % declaration statement.
638 %
639 % Why? Because if two column typesetting is desired for the whole
640 % document, it is not clear if the index has to be typeset in one
641 % column within each column of the document, or if it should be
642 % typeset in two column mode after a |\onecolumn| command is being
643 % issued; the results are not the same: with the former method the
644 % columns remain unbalanced, while the latter has balanced columns.
645 % Furthermore the |\onecolum| command forces a page break; without
646 % the |\onecolumn| command if the index is treated as a chapter,
647 % there is a page break, while if it is configured to be typeset
648 % as a section there is no forced page break. With this plethora
649 % of combinations we decided to avoid any configuration of the
650 % index typesetting and left the decision to the user. This
651 % requires the user to practice some ingenuity in order to obtain
652 % what he expects.
653 %
654 % First of all the user shall not specify the \opz{twocolumn}
655 % option to the class. Secondly the user asks for the use of
656 % \pack{indextools} and sets up the single or multiple |\makindex|
657 % commands. thirdly he loads all other packages required for his
658 % document; possibly he uses also \pack{geometry} in order to
659 % specify a specific page layout. He shall specify the |\twocolumn|
660 % declaration after the above has been completed, in any case
661 % after the \pack{indextools} package has been loaded and the single
662 % or multiple |\makeindex| commands are configured.
663 %
664 % A good example might be this one:
665 %\begin{verbatim}
666 %\documentclass[a4paper,11pt]{book}
667 %\usepackage{indextools}
668 %\indexsetup{level=\section*,toclevel=section,noclearpage}
669 %\makeindex[title=Index of places,columns=1]
670 %\twocolumn
671 %\usepackage[T1]{fontenc}
672 %\usepackage{lmodern}
673 %\usepackage[italian,english]{babel}
674 %\usepackage[utf8]{inputenc}
675 %\usepackage[a4paper,margin={1in,1in},binding=3mm]{geometry}
676 %\usepackage[english]{varioref}
677 %\usepackage[hang]{caption}
678 %\begin{document}
679 %...
680 %\indexprologue{This index lists all the residences where Lady Esther
681 %lived during the time span described in the book.}
682 %\printindex
683 %\end{document}
684 %\end{verbatim}
685 % In this way the index is typeset as a ``section'', not as a
686 % ``chapter'', in one column mode within the two column document
687 % style; the indicated prologue is typeset between the index
688 % title ``Index of places'' and the start of the index proper.
689 %
690 % On the opposite the following code:
691 %\begin{verbatim}
692 %\documentclass[a4paper,11pt]{book}
693 %\usepackage{indextools}
694 %\makeindex[title=Index of places,columns=2]
695 %\twocolumn
696 %\usepackage[T1]{fontenc}
697 %\usepackage{lmodern}
698 %\usepackage[italian,english]{babel}
699 %\usepackage[utf8]{inputenc}
700 %\usepackage[a4paper,margin={1in,1in},binding=3mm]{geometry}
701 %\usepackage[english]{varioref}
702 %\usepackage[hang]{caption}
703 %\begin{document}
704 %...
705 %\onecolumn
706 %\indexprologue{This index lists all the residences where Lady Esther
707 %lived during the time span described in the book.}
708 %\printindex
709 %\end{document}
710 %\end{verbatim}
711 % produces an index typeset as a ``chapter'', starting on a new page;
712 % it is typeset in two balanced columns. The prologue is typeset where it should.
713 % The ingenious reader can experiment mixing the various settings
714 % used in these two examples in order to find out what benefits or
715 % disadvantages one can obtain with settings that are not physically
716 % impossible, but that may be aesthetically conflicting with one another.
717
718 % \subsubsection{Class \class{memoir}}
719 %
720 % The first public version of this package was not compatible with the
721 % \pack{memoir} class. Since version 1.1 it is; however, one has to
722 % keep in mind that all index processing is done with the methods of
723 % the present package, and \emph{not} with \pack{memoir}'s; however
724 % the syntax used is the same and there should be no problem. There is
725 % an interaction between \pack{memoir} and \pack{showidx} that required
726 % special attention. See below about using \pack{showidx}.
727 %
728 % \subsubsection{Package \pack{showidx}}
729 %
730 % Up to version 1.1 this package did not allow to use it together with
731 % the \pack{showidx} package; now it is, provided that \pack{showidx}
732 % is loaded \emph{before} \pack{indextools}. See below more information
733 % on using \pack{showidx}.
734 %
735 % \subsubsection{Package \pack{fancyhdr}}
736 %
737 % When using package \pack{fancyhdr} some inconveniences did show up;
738 % now we believe we have detected the causes and we implemented the
739 % necessary corrections\footnote{Thanks to Maïeul Rouquette who, before
740 % creating this fork, spotted the problems and suggested some patches.}.
741 %
742 % \subsubsection{Package \pack{combine}}
743 %
744 % Apparently there might be some conflicts with package \pack{combine},
745 % because this package redefines the contents of |\jobname|; we tried
746 % to control this behaviour, and made the necessary patches, but it is still
747 % necessary to load this package \pack{indextools} \emph{before} package
748 % \pack{combine}.
749 %
750 %
751 % \subsection{Package \pack{bidi}}
752 % A strange conflict was discovered between packages \pack{imakeidx} and
753 % \pack{bidi}, in order to let \pack{hyperref} redefine some
754 % internal macros so as to have index hyperlinks properly executed.
755 % This implies that the ``index'' package be loaded before \pack{hyperref};
756 % on the opposite \pack{bidi} (for bidirectional writing, needed for
757 % typesetting Arabic and Hebrew scripts, among other ones) \emph{must}
758 % be loaded after \pack{hyperref} and redefines some hyper commands
759 % that have influence on the indexing package; therefore after loading
760 % \pack{bidi} the previous redefinitions are lost. A solution was found
761 % by modifying the definition of the environment |theindex| and delaying
762 % its definition to the execution of |\begin{document}|. This is the main
763 % reason of this fork so that \pack{indextools} may be loaded, as most
764 % packages normally do, before \pack{hyperref}.
765 %
766 %\subsection{Index layout customisation}
767 % If you redefine yourself the \texttt{theindex} environment, please
768 % remember not to number the chapter or section that introduces the
769 % index if you ask for the \Kvalue{intoc} option; either use the
770 % commands \cs{chapter*} or the \cs{section*} respectively and the
771 % \Kvalue{intoc} option or don't use this option and redefine your
772 % \texttt{theindex} environment with numbered chapter or section
773 % commands, that will put the index titles directly into the table of
774 % contents. See below the effect of the |\backmatter| declaration.
775 % You may use the \pack{idxlayout} package by Thomas Titz,
776 % which offers many functions for index typesetting customisation and
777 % is compatible with our package; remember to load \pack{idxlayout}
778 % after \pack{indextools}. This package has a similar function to our
779 % \cs{indexprologue}, called \cs{setindexprenote}; however
780 % \pack{idxlayout} doesn't reset the index prologue, which must be
781 % declared anew or disabled with \cs{noindexprenote} before the next
782 % \cs{printindex} command. In any case take into serious consideration
783 % what is being said hereafter about customisation.
784 %
785 % \subsection{Index page customisation}
786 % The same, more or less, holds true if you customise your headings;
787 % \pack{indextools} can deal with standard settings, but it generally
788 % cannot deal with personal styles and customisations. This is why
789 % if you load \pack{fancyhdr}, some of the |\indexsetup| settings may be
790 % disabled.
791
792 % When you make any kind of customisation, remember that there are
793 % several classes, or personal settings, or features that may render your
794 % customisation very difficult to handle. Typically:
795 %\begin{itemize}
796 % \item There are classes where the normal usable highest sectioning
797 % command, disregarding |\part|, is not |\chapter|, but |\section|; for
798 % example classes \class{article}, \class{scrartcl}.
799 %\item Sectioning commands come in two varieties: starred and unstarred;
800 % the former ones are not numbered and do not produce any entry in the
801 % headings and in the table of contents; the latter ones may behave
802 % differently according to the next item.
803 % \item There are some classes (for example \class{book},
804 % \class{scrbook}, \class{menoir},\dots) that have the special
805 % ``sectioning'' declarations |\frontmatter|, |\mainmatter|, and
806 % |\backmatter| which modify how the unstarred sectioning commands behave for
807 % what concerns the heading and the table of contents entries.
808 %
809 % For what concerns indices, these are generally typeset at the document
810 % end. This means that the |\backmatter| declaration may be in force;
811 % in this case unstarred sectioning commands are not numbered but they
812 % produce normal headings and table of contents entries.
813 %\item Heading entries are used by the output routine paging algorithm
814 % in such a way as to extract the left or the right part from suitable
815 % ``marks''; for the even (left) pages the required information is
816 % extracted from the |\topmark| or |\firstmark|, while for the odd (right)
817 % pages they are extracted from the |\botmark|. Generally speaking,
818 % the even page heading refers to |\leftmark| and odd page headings
819 % refer to |\rightmark|; these are the two commands that extract the
820 % correct part from the suitable marks. But when you use the
821 % \Kvalue{headers} option value, you specify two brace balanced strings that
822 % are loaded through |\markboth| as the left and right part of the
823 % current mark.
824 % \item The contents of the marks may be very varied; they are generally
825 % made up of two brace balanced strings, which in turn may contain other
826 % brace balanced strings that may be used in different ways by the selected page
827 % style and by the page style definitions of the macros |\chaptermarks|,
828 % |\sectionmarks|, and |\subsectionmarks| that may interfere with personal
829 % customisations.
830 % \item Remember also that things change in an obvious way when one side
831 % typesetting is chosen; all pages are treated as if they were odd ones;
832 % therefore any customisation must take into account also this aspect.
833 %\end{itemize}
834 %
835 % The above list has not been written down for discouraging customisations
836 % of any kind: simply it recalls what must be taken care of in order to
837 % create one's customisation in a proper way.
838 %
839 % The above list explains why we disabled the commands tied to the
840 % |\indexsetup| keys \Kvalue{headings} and \Kvalue{firstpagestyle} when
841 % package \pack{fancydr} is being used; you may even set up these keys,
842 % but if the \pack{fancyhdr} package has been loaded, we disable their
843 % action; this implies that any fancy customisation must be done before
844 % starting to print any index.
845 %
846 % The \Kvalue{intoc} option must also be used with care, as well as the starred
847 % or unstarred sectioning commands for the \Kvalue{level} and
848 % \Kvalue{toclevel} option values. They must be chosen according to what the
849 % possible |\backmatter| declaration sets up, in order to avoid double
850 % entries in the table of contents; the |\backmatter| settings may also
851 % influence the way heading information is being used, and this makes it
852 % even more stringent to set up any index page style customisation
853 % before starting to print any index.
854 %
855 % Therefore if by chance you get double entries into the table of contents,
856 % eliminate the \Kvalue{intoc} option from your calls; your class,
857 % packages, and settings are already taking care of it.
858
859 % The package \pack{tocbibind} should be loaded with the \Kvalue{noindex}
860 % option, otherwise it would interfere with our redefinition of
861 % \texttt{theindex}.
862 %
863 % If you redefine your \texttt{theindex} environment by means of other
864 % packages, pay attention that these redefine a real \texttt{theindex}
865 % environment with this very name; if they create an environment with
866 % a different name, \pack{indextools} can't take care of the indices
867 % production (in particular the \TeX\ system program \prog{makeindex}
868 % creates a sorted and formatted \texttt{.ind} file that refers
869 % explicitly to the \texttt{theindex} environment), and it can't take
870 % care of the table of contents entry and of the position of the hyper
871 % link anchors needed to navigate your document by means of hyper
872 % links.
873 %
874 % \subsection{Index location customisation}
875 %
876 % Some packages might want to use the facilities of \emph{indextools}
877 % to offer customised index commands, where the entry location is not
878 % expressed by a page number, but by an other reference value (for
879 % example: line number, entry number, etc.).
880 %
881 % These packages may use the low-level command \cs{indtl@wrindexentry}
882 % which takes three arguments:
883 % \begin{enumerate}
884 % \item The index name.
885 % \item The entry.
886 % \item The location number.
887 % \end{enumerate}
888 % For example \verb+\indtl@wrindexentry{names}{Charles}{26}+ adds to
889 % the index \verb+names+ the value \verb+Charles+ with the location
890 % reference \verb+26+.
891 %
892 % In simpler words, the new command \cs{indtl@wrindexentry} is of interest
893 % mainly to package and class authors; it is not to be used by the
894 % ``normal'' user, who, on the opposite, if interested in referencing
895 % the index entries on some location counter different from the page one,
896 % is urged to refer to the classes and packages that implement this
897 % facility; \pack{eledmac} should be one of these packages. Matter of
898 % fact this addition to the \pack{indextools} package was contributed
899 % by Maïeul Rouquette, the author and maintainer of \pack{eledmac}.
900 %
901 % \subsection{Using the \textsf{showidx} package}
902 % If you want to make use of the \pack{showidx} facilities, remember
903 % to load that package \emph{before} \pack{indextools}; remember also
904 % to disable or comment out the call to \pack{showidx} when you
905 % typeset the final version of your document. This constraint is due
906 % to the fact that \pack{showidx} redefines several internal commands,
907 % some of which have to receive the \pack{indextools} definition in order
908 % to perform as described in this documentation.
909
910 % At the same time if the \pack{memoir} class is being used, remember that
911 % this class simulates the \pack{showidx} package and has its own commands
912 % to enable or disable the printing of the index entries into the margin
913 % of the document; the default setting is with the |\hideindexmarks|
914 % command in force; but if the user wants to write his index entries in
915 % the margin he has to issue the declaration |\showindexmarks| just after
916 % begin document, in any case before the part of the source file(s) he
917 % wants to be marked with the index entries in the margin.
918 %
919 % \subsection{Index List sectioning customisation}
920 % Use freely the options and the key values in order to reach the
921 % desired results, but you are advised to prepare in advance the
922 % styles for composing the various indices in a proper way; for
923 % example, if you use a titled style for the index, where the index
924 % sections are distinguished with a bold face title or alphabetic
925 % letter, you have to set up a \texttt{.ist} file, such as
926 % \texttt{myindexstyle.ist}, made up like this:
927 %\begin{verbatim}
928 % headings_flag 1
929 % heading_prefix "\\par\\penalty-50\\textbf{"
930 % heading_suffix "}\\\\\*\~\\\\\*"
931 % symhead_positive "Symbols"
932 % symhead_negative "symbols"
933 % numhead_positive "Numbers"
934 % numhead_negative "numbers"
935 % delim_0 ",\~"
936 %\end{verbatim}
937 % where the numeric and non alphabetic entries have different
938 % titles. But, say, you are making also an index where the entries are
939 % file names, and for some names only the extension is entered; the
940 % extensions start with a dot, so the sorting program will sort these
941 % names at the beginning of the sorted index file, but you won't like
942 % to have a title such as ``Symbols''; you probably prefer to have a title
943 % such as ``Extensions''; therefore you have to prepare a different
944 % index style file, such as this one:
945 %\begin{verbatim}
946 % headings_flag 1
947 % heading_prefix "\\par\\penalty-50\\textbf{"
948 % heading_suffix "}\\\\\*\~\\\\\*"
949 % symhead_positive "Extensions"
950 % symhead_negative "extensions"
951 % numhead_positive "Numbers"
952 % numhead_negative "numbers"
953 % delim_0 ",\~"
954 %\end{verbatim}
955 %
956 % This done, besides requiring the use of this package, you have to
957 % declare the \cs{makeindex} command with the necessary options; pay a
958 % particular attention to the options that involve the index symbolic
959 % name, the index title, the index style, the fact that the index
960 % titles shall appear in the table of contents, and if you are
961 % preparing an e-book, you probably would like to hyper link both the
962 % page numbers and the index titles to the proper locations.
963 % The typesetting program will do everything for you but be careful
964 % not to confuse it with illogical index entries.
965 %
966 % Especially with multiple indices it is important that you are
967 % consistent in putting the right information in the right index and
968 % with a consistent mark-up. Define yourself appropriate macros so
969 % that, for example, personal names are consistently typeset, say, in
970 % caps and small caps and are entered into a specific index; you may
971 % even create one command to typeset the name in the document and
972 % replicate the same name in the index.
973 %
974 % Of course there is no program that can decide at your place what and
975 % where to index each piece of information; this is a task for
976 % humans. Soooooo\dots
977 % \begin{center} HAPPY \TeX{}ING!\end{center}
978 %
979 % \StopEventually{\PrintChanges}
980 % \section{Implementation}
981 % The heading to the file is in common with the documentation file,
982 % and has already been taken care of. But we require the
983 % \pack{xkeyval} package, in order to handle the key-value lists.
984 %
985 % Notice that in order to create a specific name space so as to avoid
986 % possible conflicts with other packages, all the commands defined in
987 % this package are prefixed with the string \texttt{indtl@}.
988 %\iffalse
989 %<*package>
990 %\fi
991 % \begin{macrocode}
992 \RequirePackage{xkeyval}
993 % \end{macrocode}
994 %
995 % We define the various options and their defaults. After
996 % \cs{ProcessOptions}, we set anyway the \texttt{original} option if
997 % the document class has been given the \texttt{twocolumn} option,
998 % which is incompatible with \pack{multicol}. We define also an
999 % internal alias for |\immediate\write18|, a rudimentary check for the
1000 % typesetting engine and a macro for modifying the command line call
1001 % to \prog{splitindex}. The \pack{xpatch} is requested; at the moment
1002 % none if its features are used, but it calls \pack{etoolbox}, whose
1003 % facilities are used here; while future extensions will benefit from
1004 % the extended patched commands, that strongly enrich the performances
1005 % of the main package \pack{etoolbox}.
1006 % \changes{v1.1a}{2012/09/07}{Fixed bug with possibly defined
1007 % \cs{directlua}; now we leave the check to \pack{ifluatex}; using
1008 % also \pack{ifxetex} for symmetry.}
1009 % \begin{macrocode}
1010 \DeclareOption{xindy}{\def\indtl@progdefault{texindy}}
1011 \DeclareOption{texindy}{\def\indtl@progdefault{texindy}}
1012 \DeclareOption{truexindy}{\def\indtl@progdefault{truexindy}}
1013 \DeclareOption{makeindex}{\def\indtl@progdefault{makeindex}}
1014 \DeclareOption{upmendex}{\def\indtl@progdefault{upmendex}}
1015 \DeclareOption{xindex}{\def\indtl@progdefault{xindex}}
1016 \newif\ifindtl@disableautomatic
1017 \DeclareOption{noautomatic}{\indtl@disableautomatictrue}
1018 \newif\ifindtl@nonewpage
1019 \DeclareOption{nonewpage}{%
1020 \indtl@nonewpagetrue\indtl@disableautomatictrue
1021 }
1022 \newif\ifindtl@splitindex
1023 \DeclareOption{splitindex}{\indtl@splitindextrue}
1024 \newif\ifindtl@original
1025 \DeclareOption{original}{\indtl@originaltrue}
1026 \DeclareOption{quiet}{\AtEndOfPackage{%
1027 \let\indtl@finalmessage\@gobble
1028 \let\indtl@splitindexmessage\relax}}
1029 \newif\ifindtl@afterindex
1030 \DeclareOption{afterindex}{\indtl@afterindextrue}
1031
1032 \newif\ifindtl@innote
1033 \DeclareOption{innote}{\indtl@innotetrue}
1034
1035 \newif\ifindtl@notenumber
1036 \DeclareOption{notenumber}{\indtl@notenumbertrue}
1037
1038 \ExecuteOptions{makeindex}
1039 \ProcessOptions\relax
1040
1041 \if@twocolumn\indtl@originaltrue\fi
1042 \def\indtl@exec{\immediate\write18}
1043 \def\indtl@engine{(pdf)latex}
1044 \RequirePackage{ifxetex,ifluatex}
1045 \ifxetex\def\indtl@engine{xelatex}\fi
1046 \ifluatex % luatex doesn't have \(pdf)shellescape
1047 \def\indtl@engine{lualatex}
1048 \ifnum\luatexversion<68
1049 \chardef\indtl@shellescape\@ne % no way to know the value
1050 \else
1051 \RequirePackage{pdftexcmds} % provides \pdf@shellescape
1052 \chardef\indtl@shellescape\pdf@shellescape
1053 \fi
1054 \let\indtl@exec\pdf@system
1055 \fi
1056 \RequirePackage{xpatch}
1057 \edef\indtl@splitindexoptions{-m \string"\string"}
1058 \def\splitindexoptions#1{\g@addto@macro\indtl@splitindexoptions{ #1}}
1059 \@onlypreamble\splitindexoptions
1060 % \end{macrocode}
1061 %
1062 % \subsection{Incompatibilities and emulation}
1063 %
1064 % While experimenting we found out that some classes or packages are
1065 % either incompatible with this one, or must be faked in order to
1066 % pretend they have been loaded.
1067 %
1068 % There is a serious incompatibility with the \pack{memoir} class. In
1069 % facts \pack{memoir} puts all index entries in the main \texttt{.aux}
1070 % file and extracts them to the various raw index files at
1071 % |\end{document}| time. This means that no raw index file output
1072 % stream has been defined, and therefore this package can't close it;
1073 % moreover it can't typeset the indices before |\end{document}|
1074 % because they are not yet available. Therefore if \pack{memoir} is
1075 % the active class, we will hijack its index mechanism replacing it
1076 % with ours.
1077 %
1078 % On the opposite we pretend that package \pack{makeidx} or package
1079 % \pack{multind} have been loaded, so that \pack{hyperref} can play
1080 % with their commands, that are substantially the same as those used
1081 % here. By so doing those packages are inhibited from being loaded
1082 % after this one.
1083 % We do the same with the forked original \pack{imakeidx} package
1084 % so that if \pack{imakeidx} is loaded before, \pack{indextools} is
1085 % not loaded, but an error message is issued; otherwise we fake the
1086 % fact that \pack{imakeidx} has already been loaded so that it does
1087 % not get reloaded.
1088 % \begin{macrocode}
1089 \@namedef{[email protected]}{3000/12/31}
1090 \@ifpackageloaded{multind}
1091 {\PackageError{indextools}{Incompatible package `multind' loaded}
1092 {This package is incompatible with multind, don't load both.%
1093 \MessageBreak\@ehc}}
1094 {\@namedef{[email protected]}{3000/12/31}}
1095
1096 \@ifpackageloaded{imakeidx}
1097 {\PackageError{indextools}{Incompatible package `imakeidx' loaded}
1098 {This package is incompatible with imakeidx, don't load both.%
1099 \MessageBreak\@ehc}}
1100 {\@namedef{[email protected]}{3000/12/31}}
1101 % \end{macrocode}
1102 % At the same time we redefine some commands defined by \pack{makeidx}
1103 % and we define the default English names for the \cs{see} and
1104 % \cs{seealso} commands. We use \cs{providecommand} so that, if
1105 % \pack{makeidx} has already been loaded, we do not redefine things
1106 % that have already been defined.
1107 % \begin{macrocode}
1108 \providecommand*\see[2]{\emph{\seename} #1}
1109 \providecommand*\seealso[2]{\emph{\alsoname} #1}
1110 \providecommand*\seename{see}
1111 \providecommand*\alsoname{seeupmendex also}
1112 % \end{macrocode}
1113 %
1114 % \subsection{\cs{makeindex}}
1115 %
1116 % From here on, some commands are duplicated; this depends on the
1117 % fact that the behavior must be different when using \prog{splitindex} or
1118 % not. The memory occupied by the useless commands will be cleared at the
1119 % end of package.
1120 % \begin{macrocode}
1121 \providecommand*\makeindex{} % to use \renewcommand safely
1122 \renewcommand{\makeindex}[1][]{\indtl@makeindex{#1}}
1123 % \@onlypreamble\makeindex % Already in latex.ltx
1124 % \end{macrocode}
1125 % This package implementation of \cs{makeindex} sets default values
1126 % for the keys, then evaluates its argument (which is the optional
1127 % argument to \cs{makeindex}) and calls two other macros. After that
1128 % we have to reset the defaults.
1129 % \begin{macrocode}
1130 \def\indtl@makeindex#1{%
1131 \edef\indtl@name{\jobname}%
1132 \edef\indtl@jobname{\jobname}%
1133 \def\indtl@title{\indexname}%
1134 \edef\indtl@program{\indtl@progdefault}%
1135 \let\indtl@options\space
1136 \KV@indtl@noautomaticfalse\KV@indtl@intocfalse
1137 \setkeys{indtl}{#1}%
1138 \ifindtl@splitindex\KV@indtl@noautomaticfalse\fi
1139 \indtl@build\indtl@name
1140 \indtl@startidx\indtl@name
1141 \indtl@resetdefaults
1142 }
1143 % \end{macrocode}
1144 %
1145 % Here are the keys. As usual, the \texttt{indtl@} prefix is used to
1146 % distinguish anything that is being defined in this package, even the
1147 % keys.
1148 % \begin{macrocode}
1149 \define@key{indtl}{name}{\def\indtl@name{#1}}
1150 \define@key{indtl}{title}{\def\indtl@title{#1}}
1151 \define@choicekey{indtl}{program}[\indtl@val\indtl@nr]
1152 {makeindex,xindy,texindy,truexindy,upmendex,xindex}{%
1153 \ifcase\indtl@nr\relax
1154 \def\indtl@program{makeindex}%
1155 \or
1156 \def\indtl@program{texindy}%
1157 \or
1158 \def\indtl@program{texindy}%
1159 \or
1160 \def\indtl@program{xindy}%
1161 \or
1162 \def\indtl@program{upmendex}%
1163 \or
1164 \def\indtl@program{xindex}%
1165 \fi}
1166 \define@key{indtl}{options}{\def\indtl@options{ #1 }}
1167 \define@boolkey{indtl}{noautomatic}[true]{}
1168 \define@boolkey{indtl}{intoc}[true]{}
1169 \define@key{indtl}{columns}{\def\indtl@columns{#1}}
1170 \define@key{indtl}{columnsep}{\def\indtl@columnsep{#1}}
1171 \define@boolkey{indtl}{columnseprule}[true]{}
1172 \def\indtl@resetdefaults{%
1173 \def\indtl@options{ }%
1174 \def\indtl@columns{2}\def\indtl@columnsep{35\p@}%
1175 \KV@indtl@columnseprulefalse
1176 \KV@indtl@intocfalse\KV@indtl@noautomaticfalse}
1177 \indtl@resetdefaults
1178 % \end{macrocode}
1179 %
1180 % The control sequence \cs{indtl@build} defines a control sequence to
1181 % hold the setup for an index to be used when the index is sorted and
1182 % printed
1183 % \begin{macrocode}
1184 \def\indtl@build#1{%
1185 \toks@{}%
1186 \indtl@dokey\indtl@title
1187 \indtl@dokey\indtl@program
1188 \indtl@dokey\indtl@options
1189 \indtl@dokey\indtl@columns
1190 \indtl@dokey\indtl@columnsep
1191 \ifKV@indtl@noautomatic
1192 \addto@hook\toks@{\KV@indtl@noautomatictrue}%
1193 \else
1194 \addto@hook\toks@{\KV@indtl@noautomaticfalse}%
1195 \fi
1196 \ifKV@indtl@intoc
1197 \addto@hook\toks@{\KV@indtl@intoctrue}%
1198 \else
1199 \addto@hook\toks@{\KV@indtl@intocfalse}%
1200 \fi
1201 \ifKV@indtl@columnseprule
1202 \addto@hook\toks@{\KV@indtl@columnsepruletrue}%
1203 \else
1204 \addto@hook\toks@{\KV@indtl@columnseprulefalse}%
1205 \fi
1206 \expandafter\edef\csname indtl@set@#1\endcsname{\the\toks@}%
1207 }
1208 % \end{macrocode}
1209 % Comand \cs{indtl@dokey} receives as argument the text of the values
1210 % assigned to certain keys, and adds them to the options token list.
1211 % \begin{macrocode}
1212 \def\indtl@dokey#1{%
1213 \expandafter\addto@hook\expandafter\toks@\expandafter{%
1214 \expandafter\def\expandafter#1\expandafter{#1}}}
1215 % \end{macrocode}
1216 %
1217 % Command \cs{indtl@startidx} defines the output stream(s); the macro
1218 % with suffix \texttt{split} is used when \Kvalue{splitindex} is not
1219 % enabled, the one with suffix \texttt{unique} is used otherwise. In
1220 % the case of many indices, the symbolic name for an index named
1221 % `pippo' is \cs{pippo@idxfile} corresponding to the file
1222 % \texttt{pippo.idx}. When \Kvalue{splitindex} is enabled, the only
1223 % output stream is called \cs{@indexfile} as in standard \LaTeX,
1224 % corresponding to \cs{jobname.idx}.
1225 % \begin{macrocode}
1226 \def\indtl@startidxsplit#1{%
1227 \if@filesw
1228 \def\index{\@bsphack
1229 \@ifnextchar [{\@index}{\@index[\indtl@jobname]}}
1230 \expandafter\newwrite\csname #1@idxfile\endcsname
1231 \immediate\openout \csname #1@idxfile\endcsname #1.idx\relax
1232 \typeout{Writing index file #1.idx}%
1233 \fi}
1234 % \end{macrocode}
1235 % We define a switch which is set to true when a \cs{makeindex} command is given:
1236 % with \Kvalue{splitindex} we open only one stream.
1237 % \begin{macrocode}
1238 \newif\ifindtl@startedidx
1239 \def\indtl@startidxunique#1{%
1240 \if@filesw
1241 \ifindtl@startedidx\else
1242 \newwrite\@indexfile
1243 \immediate\openout\@indexfile\[email protected]%
1244 \global\indtl@startedidxtrue
1245 \fi
1246 \def\index{\@bsphack
1247 \@ifnextchar [{\@index}{\@index[\indtl@jobname]}}
1248 \expandafter\let\csname #1@idxfile\endcsname\@empty
1249 \typeout{Started index file #1}%
1250 \fi}
1251 % \end{macrocode}
1252 %
1253 % \subsection{\cs{index}}
1254 %
1255 % Provide a default definition for \cs{index}; when a \cs{makeindex}
1256 % command is given and \LaTeX\ is writing on auxiliary files,
1257 % \cs{index} will be redefined, as seen before. When index files are
1258 % written, \cs{index} always calls \cs{@index}. Some code is borrowed
1259 % from \pack{memoir.cls}, but heavily modified. We want \cs{@wrindex}
1260 % to be defined with two arguments, so that \pack{hyperref} can hook
1261 % into it just like it does with the similar commands defined by the
1262 % old packages \pack{multind} and \pack{index}.
1263 % \begin{macrocode}
1264 \renewcommand{\index}[2][]{\@bsphack\@esphack}
1265 \def\@index[#1]{%
1266 \@ifundefined{#1@idxfile}%
1267 {\PackageWarning{indextools}{Undefined index file `#1'}%
1268 \begingroup
1269 \@sanitize
1270 \indtl@nowrindex}%
1271 {\edef\@idxfile{#1}%
1272 \begingroup
1273 \@sanitize
1274 \@wrindex\@idxfile}}
1275 \def\indtl@nowrindex#1{\endgroup\@esphack}
1276 % \end{macrocode}
1277 %
1278 % Command \cs{@wrindex} must be duplicated; we have to call it the same as
1279 % usual in order to support \pack{hyperref}. But the real name will be given
1280 % at the end. We have to define a switch to allow the use of the
1281 % \pack{showidx} facilities. We define also a helper macro so as to do the
1282 % right thing so as to show the index file name to which a certain index
1283 % entry is going to be written; the idea is to prefix the index entry with
1284 % the actual name of the specific index, except in the case or the default
1285 % index, where the name is set to |\jobname|. Since the control sequence is
1286 % a primitive command, its value cannot be directly compared in the |\ifx|
1287 % sense to the current macro represented by argument |#1|. Therefore we need
1288 % a further helper control sequence |\indtl@jobname| that contains the value
1289 % assigned to |\jobname|.
1290 %
1291 % We must also take care of the case where the user wants to print the index
1292 % entries in the margin while working on the document. This implies testing
1293 % for the package \pack{showidx} being already loaded; but this is not
1294 % sufficient, because the \pack{memoir} class simulates the \pack{showidx}
1295 % package and the test would result to be true even if the user did not load
1296 % that package, but uses the \pack{memoir} class.
1297 %
1298 % Therefore we use the same boolean used by \pack{memoir}, testing in advance
1299 % so as not redefining it; then we use it to let the \pack{showidx} true or
1300 % simulated macros do their job, but we also take care of resetting the switch
1301 % default value to false at begin document time if the \pack{memoir} class is
1302 % being used.
1303 %
1304 %
1305 % \begin{macrocode}
1306 \@ifundefined{showindexmarks}{\newif\ifshowindexmark}{}
1307 \@ifpackageloaded{showidx}{\showindexmarktrue}{\showindexmarkfalse}
1308 \newcommand\indtl@showidxentry[2]{%
1309 \ifshowindexmark
1310 \@showidx{\ifdefequal{\indtl@jobname}{#1}{}{[#1]\space}#2}%
1311 \fi}
1312 \newcommand\indtl@wrindexentrysplit[3]{%
1313 \expandafter\protected@write\csname#1@idxfile\endcsname{}%
1314 {\string\indexentry{#2}{#3}}%
1315 }
1316 \newcommand\indtl@wrindexentryunique[3]{%
1317 \protected@write\@indexfile{}%
1318 {\string\indexentry[#1]{#2}{#3}}%
1319 }
1320 \def\indtl@wrindexsplit#1#2{%
1321 \indtl@wrindexentrysplit{#1}{#2}{\thepage}%
1322 \endgroup\indtl@showidxentry{#1}{#2}%
1323 \@esphack%
1324 }
1325 \def\indtl@wrindexunique#1#2{%
1326 \indtl@wrindexentryunique{#1}{#2}{\thepage}%
1327 \endgroup\indtl@showidxentry{#1}{#2}%
1328 \@esphack%
1329 }
1330 % \end{macrocode}
1331 %
1332 % \subsection{\cs{printindex}}
1333 %
1334 % Compilation of the indices is disabled if \texttt{-shell-escape} has
1335 % not been given or the restricted mode is not active; in this case we
1336 % emit a warning. \XeTeX{} has \cs{shellescape} instead of
1337 % \cs{pdfshellescape}, so we take care of this (hoping that users or
1338 % packages don't define a \cs{shellescape} command). In any case we
1339 % define an internal version of this command. In the case of
1340 % \prog{luatex} we can't emit the proper messages if \prog{luatex} is
1341 % not version 0.68 or later. The conditional
1342 % \cs{ifKV@indtl@noautomatic} is defined by \cs{define@boolkey} above.
1343 %
1344 % \begin{macrocode}
1345 \def\indtl@shellwarn{}
1346 \ifdefined\indtl@shellescape % luatex
1347 \else
1348 \@ifundefined{shellescape}
1349 {\let\indtl@shellescape\pdfshellescape} % pdftex
1350 {\let\indtl@shellescape\shellescape} % xetex
1351 \fi
1352 \ifnum\indtl@shellescape=\z@
1353 \let\KV@indtl@noautomaticfalse\KV@indtl@noautomatictrue
1354 \KV@indtl@noautomatictrue
1355 \def\indtl@shellwarn{\MessageBreak or call \indtl@engine\space with
1356 -shell-escape}
1357 \fi
1358 % \end{macrocode}
1359 % Do the same if \Kvalue{noautomatic} has been given as an option.
1360 % \begin{macrocode}
1361 \ifindtl@disableautomatic
1362 \let\KV@indtl@noautomaticfalse\KV@indtl@noautomatictrue
1363 \KV@indtl@noautomatictrue
1364 \fi
1365 % \end{macrocode}
1366 %
1367 % Now we set up the \texttt{theindex} environment. If the
1368 % \texttt{original} option is set, we simply patch the class
1369 % definition in order to call the macro that does the work related to
1370 % the table of contents. Otherwise we define a new \texttt{theindex}
1371 % environment, based on the standard, but using, if the number of
1372 % columns is greater than one, the \texttt{multicols} environment.
1373 % Users needing a different setup can use the \cs{indexsetup} command.
1374 % Before doing so, though, we need to disable certain features if the
1375 % package \pack{fancyhdr} is loaded sometimes before the
1376 % |\begin{document| statement, be it before or after loading
1377 % \pack{indextools}. If that package is loaded we have to patch the
1378 % definition of the environment |theindex|, because its default
1379 % commands interfere with those defined here that work perfectly
1380 % when \pack{fancyhdr} is not loaded. This patching could be defined
1381 % further on, but if it remains close to what has to be patched, it's
1382 % easier to understand it's operation.
1383 %
1384 % We make this redefinition at the begining of the document, to
1385 % prevent redefinition by other packages, like \pack{bidi}. This
1386 % point is where \pack{indextools} and \pack{imakeidx} diverge.
1387 % \begin{macrocode}
1388 \newif\ifindtl@fancyhdr
1389 \AtBeginDocument{%
1390 \@ifpackageloaded{fancyhdr}{\indtl@fancyhdrtrue}{\indtl@fancyhdrfalse}%
1391 \ifindtl@original
1392 \expandafter\def\expandafter\theindex\expandafter{\expandafter
1393 \indtl@maybeaddtotoc\theindex}
1394 \else
1395 \renewenvironment{theindex}
1396 {\indtl@maybeaddtotoc
1397 \indtl@indexlevel{\indexname}%
1398 \ifindtl@fancyhdr\else%
1399 \indtl@indexheaders%
1400 \thispagestyle{\indtl@firstpagestyle}%
1401 \fi%
1402 \ifnum\indtl@columns>\@ne
1403 \columnsep \indtl@columnsep
1404 \ifx\indtl@idxprologue\relax
1405 \begin{multicols}{\indtl@columns}
1406 \else
1407 \begin{multicols}{\indtl@columns}[\indtl@idxprologue]
1408 \fi
1409 \else
1410 \indtl@idxprologue
1411 \fi
1412 \global\let\indtl@idxprologue\relax
1413 \parindent\z@
1414 \parskip\z@ \@plus .3\p@\relax
1415 \columnseprule \ifKV@[email protected]\p@\else\z@\fi
1416 \raggedright
1417 \let\item\@idxitem
1418 \indtl@othercode}
1419 {\ifnum\indtl@columns>\@ne\end{multicols}\fi
1420 }
1421 \fi
1422 }
1423 \ifindtl@original
1424 \else
1425 \global\let\indtl@idxprologue\relax
1426 \RequirePackage{multicol}
1427 \fi
1428 % \end{macrocode}
1429 % The command \cs{indexsetup} may be used to customize some aspects of
1430 % index formatting.
1431 % \begin{macrocode}
1432 \def\indtl@indexlevel{%
1433 \@ifundefined{chapter}{\section}{\chapter}*}
1434 \define@key{indtlindex}{level}{\def\indtl@indexlevel{#1}}
1435 \def\indtl@toclevel{%
1436 \@ifundefined{chapter}{section}{chapter}}
1437 \define@key{indtlindex}{toclevel}{\def\indtl@toclevel{#1}}
1438 \define@boolkey{indtlindex}{noclearpage}[true]{\let\indtl@clearpage\relax}
1439 \def\indtl@indexheaders{%
1440 \@mkboth{\MakeUppercase\indexname}{\MakeUppercase\indexname}}
1441 \define@key{indtlindex}{headers}{\def\indtl@indexheaders{\markboth#1}}
1442 \def\indtl@firstpagestyle{plain}
1443 \define@key{indtlindex}{firstpagestyle}{\def\indtl@firstpagestyle{#1}}
1444 \let\indtl@othercode\relax
1445 \define@key{indtlindex}{othercode}{\def\indtl@othercode{#1}}
1446 \newcommand{\indexsetup}[1]{%
1447 \ifindtl@original\else\setkeys{indtlindex}{#1}\fi}
1448 \@onlypreamble\indexsetup
1449 % \end{macrocode}
1450 %
1451 % The command \cs{indexprologue} sets the internal version which is
1452 % always \cs{let} to \cs{relax} during |\begin{theindex}|.
1453 % \begin{macrocode}
1454 \newcommand{\indexprologue}[2][\bigskip]{%
1455 \long\gdef\indtl@idxprologue{{#2\par}#1}}
1456 % \end{macrocode}
1457 %
1458 % Now we provide the relevant \cs{printindex} macros by transferring
1459 % the real job to a secondary macro \cs{indtl@putindex} after due
1460 % checks and messages.
1461 % \begin{macrocode}
1462 \providecommand*{\printindex}{}
1463 \renewcommand*{\printindex}[1][\indtl@jobname]{%
1464 \@ifundefined{#1@idxfile}{\indtl@error{#1}}{\indtl@putindex{#1}}}
1465
1466 \def\indtl@error#1{%
1467 \def\@tempa{#1}\def\@tempb{\indtl@jobname}%
1468 \ifx\@tempa\@tempb
1469 \let\indtl@optarg\@empty
1470 \else
1471 \def\indtl@optarg{[#1]}%
1472 \fi
1473 \PackageError{indextools}
1474 {Misplaced \protect\printindex\indtl@optarg}
1475 {You are not making this index, as no appropriate
1476 \protect\makeindex\MessageBreak
1477 command has been issued in the preamble.}}
1478 % \end{macrocode}
1479 %
1480 % We define a command to do a \cs{cleardoublepage} if the option
1481 % \Kvalue{openright} is active (in classes where \Kvalue{twoside} is
1482 % meaningful). In case \cs{chapter} is defined but not
1483 % \cs{if@openright}, we assume that the class wants ``open right''.
1484 % \begin{macrocode}
1485 \def\indtl@clearpage{%
1486 \@ifundefined{chapter}
1487 {\clearpage} % article and similar classes
1488 {\@ifundefined{if@openright}
1489 {\cleardoublepage}
1490 {\if@openright
1491 \cleardoublepage
1492 \else
1493 \clearpage
1494 \fi}
1495 }}
1496 % \end{macrocode}
1497 %
1498 % We need a helper macro to do a check in order to avoid a loop and
1499 % the hook where to insert the table of contents related stuff.
1500 % \begin{macrocode}
1501 \def\indtl@check@indexname{\indexname}
1502 \providecommand*\indtl@maybeaddtotoc{}
1503 % \end{macrocode}
1504 % Two helper macros for preparing the final messages to the user.
1505 % \begin{macrocode}
1506 \def\indtl@finalmessage#1{%
1507 \expandafter\edef\csname indtl@message#1\endcsname
1508 {\indtl@program\indtl@options#1.idx}
1509 \AtEndDocument{\PackageWarning{indextools}{%
1510 Remember to run \indtl@engine\space again after calling\MessageBreak
1511 `\@nameuse{indtl@message#1}'\indtl@shellwarn\@gobble}}}
1512 \def\indtl@splitindexmessage{%
1513 \AtEndDocument{\PackageWarningNoLine{indextools}{%
1514 Remember to run \indtl@engine\space again after calling\MessageBreak
1515 `splitindex' and processing the indices\indtl@shellwarn}}}
1516 % \end{macrocode}
1517 %
1518 % Here is a helper macro for deciding whether to call the external
1519 % utility or to issue a final message. In \cs{indtl@makeindexname} we
1520 % put the name of the only program allowed by default
1521 % (\prog{makeindex}). If the list is updated, we can supplement the
1522 % list here, maybe defining a list macro; for now this is
1523 % sufficient. The temporary switch \cs{if@tempswa} is set to true if
1524 % automatic processing is possible, so that the main macro can take
1525 % the appropriate action.
1526 % \begin{macrocode}
1527 \def\indtl@makeindexname{makeindex}
1528 \def\indtl@decide{%
1529 \@tempswafalse
1530 \ifindtl@splitindex % splitindex is not "safe"
1531 \ifnum\indtl@shellescape=\@ne\@tempswatrue\fi
1532 \else
1533 \ifx\indtl@program\indtl@makeindexname % nor is texindy
1534 \ifnum\indtl@shellescape=\tw@\@tempswatrue\fi
1535 \fi
1536 \ifnum\indtl@shellescape=\@ne\@tempswatrue\fi
1537 \fi
1538 \ifKV@indtl@noautomatic
1539 \@tempswafalse
1540 \fi}
1541 % \end{macrocode}
1542 % We define a macro that close a specified index file and run in.
1543 % \begin{macrocode}
1544 \newcommand{\indtl@closeandrundidxsplit}[1]{%
1545 \immediate\closeout\csname #1@idxfile\endcsname
1546 \let\indtl@indexname\indexname % keep \indexname
1547 \@nameuse{indtl@set@#1}\indtl@decide
1548 \if@tempswa % we can call the external program
1549 \indtl@exec{\indtl@program\indtl@options#1.idx}%
1550 \else
1551 \indtl@finalmessage{#1}%
1552 \fi
1553 }
1554 % \end{macrocode}
1555 % We define a macro that close the general index file and run in.
1556 % \begin{macrocode}
1557 \newcommand{\indtl@closeandrundidxunique}{%
1558 \immediate\closeout\@indexfile
1559 \indtl@exec{splitindex \indtl@splitindexoptions\space\[email protected]}%
1560 \global\indtl@splitdonetrue
1561 }
1562 % \end{macrocode}
1563 % We now define the main macro that puts the specified index file into
1564 % the document and possibly orders to add the index title to the
1565 % table of contents. It is duplicated as usual. The argument |#1| is
1566 % the specific symbolic name of the index. In particular if the
1567 % \Kvalue{intoc} option has been specified, the hook
1568 % \cs{indtl@maybeaddtotoc} is defined in such a way that the relevant
1569 % information is added to the \texttt{toc} file. The
1570 % \cs{phantomsection} command is necessary when using \pack{hyperref};
1571 % here it is hidden as argument to \cs{@nameuse}, so it is equivalent
1572 % to \cs{relax} and does nothing if \pack{hyperref} has not been
1573 % loaded.
1574 % \begin{macrocode}
1575 \def\indtl@putindexsplit#1{%
1576 \ifindtl@nonewpage\else
1577 \indtl@clearpage
1578 \fi
1579 \ifindtl@afterindex%
1580 \AtEndDocument{%
1581 \indtl@clearpage%
1582 \indtl@closeandrundidxsplit{#1}%
1583 \indltl@afterindexMessage%
1584 }%
1585 \else%
1586 \indtl@closeandrundidxsplit{#1}%
1587 \fi
1588 \ifKV@indtl@intoc
1589 \def\indtl@maybeaddtotoc{\@nameuse{phantomsection}%
1590 \addcontentsline{toc}{\indtl@toclevel}{\indtl@title}}%
1591 \else
1592 \def\indtl@maybeaddtotoc{}%
1593 \fi
1594 \ifx\indtl@title\indtl@check@indexname\else
1595 \def\indexname{\indtl@title}%
1596 \fi
1597 \@input@{#1.ind}
1598 \let\indexname\indtl@indexname % restore \indexname
1599 }
1600
1601 \newif\ifindtl@splitdone
1602 \def\indtl@putindexunique#1{%
1603 \ifindtl@nonewpage\else
1604 \indtl@clearpage
1605 \fi
1606 \let\indtl@indexname\indexname % keep \indexname
1607 \@nameuse{indtl@set@#1}\indtl@decide
1608 \if@tempswa % we can call the external program
1609 \ifindtl@splitdone\else
1610 \ifindtl@afterindex
1611 \AtEndDocument{%
1612 \indtl@clearpage%
1613 \indtl@closeandrundidxunique%
1614 \indltl@afterindexMessage%
1615 }
1616 \else
1617 \indtl@closeandrundidxunique
1618 \fi
1619 \fi
1620 \else
1621 \ifindtl@splitdone\else
1622 \indtl@splitindexmessage\global\indtl@splitdonetrue
1623 \fi
1624 \fi
1625 \if@tempswa % we can call the external program
1626 \indtl@exec{\indtl@program\indtl@options\indtl@jobname-#1.idx}%
1627 \fi
1628 \ifKV@indtl@intoc
1629 \def\indtl@maybeaddtotoc{\@nameuse{phantomsection}%
1630 \addcontentsline{toc}{\indtl@toclevel}{\indtl@title}}%
1631 \else
1632 \def\indtl@maybeaddtotoc{}%
1633 \fi
1634 \ifx\indtl@title\indtl@check@indexname\else
1635 \def\indexname{\indtl@title}%
1636 \fi
1637 \@input@{\indtl@jobname-#1.ind}
1638 \let\indexname\indtl@indexname % restore \indexname
1639 }
1640 % \end{macrocode}
1641 % A warning message when using `afterindex' option.
1642 % \begin{macrocode}
1643 \newcommand{\indltl@afterindexMessage}{%
1644 \PackageWarning{indextools}{You use the `afterindex' option.
1645 \MessageBreak That means you use \string\index\space commands after \string\printindex\space command.
1646 \MessageBreak Consequently, the index may be not ok at the first run.
1647 }%
1648 }
1649 % \end{macrocode}
1650 % \subsection{`innote' and `notenumber' options}
1651 %
1652 % If the `innote' option is enabled, we modify the standard index command when we are in a note, in order to insert the \verb+|innote+ in the \verb+.idx+ file.
1653 % \begin{macrocode}
1654
1655 \AtBeginDocument{%
1656 \ifindtl@innote%
1657 \RequirePackage{letltxmacro}
1658 \LetLtxMacro\orig@@index\index
1659 \pretocmd{\@footnotetext}{\let\index\nindex}{}{}
1660 \apptocmd{\@footnotetext}{\let\index\orig@@index}{}{}
1661
1662 \fi%
1663 % \end{macrocode}
1664 % The same is true if the `notnumber' option is enabled.
1665 % \begin{macrocode}
1666 \ifindtl@notenumber%
1667 \RequirePackage{letltxmacro}
1668 \LetLtxMacro\orig@@index\index
1669 \pretocmd{\@footnotetext}{\let\index\nnumberindex}{}{}
1670 \apptocmd{\@footnotetext}{\let\index\orig@@index}{}{}
1671 \fi%
1672 % \end{macrocode}
1673 % \begin{macrocode}
1674 % And now, the command, defines in any case, but only at the begin of documents, because people can have defined them in the preamble.
1675 \newcommand\nnumberindex[2][\indtl@jobname]{\orig@@index[#1]{#2|innotenumber{\thefootnote}}}
1676 \newcommand\nindex[2][\indtl@jobname]{\orig@@index[#1]{#2|innote}}
1677 \providecommand{\innotenumber}[2]{#2n.~#1}
1678 \providecommand{\innote}[1]{#1\textit{n}}
1679 }
1680 % \end{macrcocode}
1681 % \subsection{Final decisions}
1682 %
1683 % At this point, we choose the meaning of the relevant commands,
1684 % reclaiming the space occupied by the discarded ones
1685 % \begin{macrocode}
1686 \ifindtl@splitindex
1687 \let\indtl@startidx\indtl@startidxunique
1688 \let\@wrindex\indtl@wrindexunique
1689 \let\indtl@putindex\indtl@putindexunique
1690 \let\indtl@wrindexentry\indtl@wrindexentryunique
1691 \let\indtl@startidxsplit\@undefined
1692 \let\indtl@wrindexsplit\@undefined
1693 \let\indtl@putindexsplit\@undefined
1694 \else
1695 \let\indtl@startidx\indtl@startidxsplit
1696 \let\@wrindex\indtl@wrindexsplit
1697 \let\indtl@putindex\indtl@putindexsplit
1698 \let\indtl@wrindexentry\indtl@wrindexentrysplit
1699 \let\indtl@startidxunique\@undefined
1700 \let\indtl@wrindexunique\@undefined
1701 \let\indtl@putindexunique\@undefined
1702 \fi
1703 % \end{macrocode}
1704 % To end the code, we deal with \pack{memoir}:
1705 % \begin{macrocode}
1706 \@ifclassloaded{memoir}{\let\@wrindexm@m\@wrindex
1707 \AtBeginDocument{\hideindexmarks}}{}
1708 % \end{macrocode}
1709 %\iffalse
1710 %</package>
1711 %\fi
1712 % The end.
1713 % \Finale