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