% \iffalse
%<*internal>
\begingroup
\input docstrip.tex
\keepsilent
\usedir{tex/latex/imakeidx}
\preamble
  ___________________________________________________________
  The imakeidx package for LaTeX
  Copyright (C) 2010-2013 Enrico Gregorio
  All rights reserved

  License information appended

\endpreamble
\postamble

Copyright 2010--2013 Enrico Gregorio <Enrico dot Gregorio at univr dot it>

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

This work is "author-maintained"

This work consists of this file imakeidx.dtx, a README file
and the derived files imakeidx.sty and imakeidx.pdf.

\endpostamble
\askforoverwritefalse

\generate{\file{imakeidx.sty}{\from{imakeidx.dtx}{package}}}

\def\tmpa{plain}
\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
\endgroup
%</internal>
%
%<*driver>
\ProvidesFile{imakeidx.dtx}%
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{imakeidx}%
%<*package>
   [2013/07/11 v1.3a Package for typesetting indices in a synchronous mode]
%</package>
%<*driver>
\documentclass{ltxdoc}
\def\prog#1{\textsf{\slshape#1}}
\def\progpdflatex{\textsf{(\textsl{pdf})\textsl{latex}}}
\def\eTeX{\mbox{$\varepsilon$-\TeX}}
\def\Kvalue#1{\textsf{\textsl{#1}}}
\def\pack#1{\textsf{#1}}
\def\class#1{\textsf{\itshape#1}}
\def\opz#1{\texttt{#1}}
\usepackage{multicol}
\usepackage[colorlinks]{hyperref}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{textcomp,metalogo,booktabs}
\begin{document}
\frenchspacing
\makeatletter
\GetFileInfo{imakeidx.dtx}% dtx extension required
\title{The package \pack{imakeidx}\thanks{Version number \fileversion; last
 revision \filedate.}}
\author{Enrico Gregorio\thanks{\texttt{Enrico dot Gregorio at univr dot it}}}
\date{}
\maketitle
\begin{multicols}{2}
\tableofcontents
\end{multicols}
\smallskip
\RecordChanges
\DocInput{imakeidx.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{797}
%
% \changes{v1.0}{2010/07/10}{First public version}
% \changes{v1.0a}{2010/07/12}{Small bug correction}
% \changes{v1.1}{2012/05/09}{Fixed compatibility with \pack{memoir}}
% \changes{v1.1}{2012/05/09}{Modified interaction with Lua\TeX}
% \changes{v1.1a}{2012/09/07}{Fixed bug with possibly defined \cs{directlua}}
% \changes{v1.2}{2012/08/31}{made package compatible with showidx}
% \changes{v1.2}{2012/08/31}{made package compatible with fancyhdr}
% \changes{v1.2}{2012/08/31}{added index processing engine option truexindy}
% \changes{v1.2c}{2012/10/02}{Fixed regression}
% \changes{v1.2d}{2012/10/06}{Fixed bugs with index internal names}
% \changes{v1.2e}{2012/10/22}{Fixed bug with showidx simulated by memoir}
% \changes{v1.3}{2013/07/11 }{Added internal so as to cooperate in a better
% way with eledmac (by Maieul Roquette}
%
% \begin{abstract}
% This package exploits the |\write18| facility of modern \TeX\ system
% distributions that allows to run system commands while typesetting a
% document written with the \LaTeX{} mark up.  By so doing, the index
% or indices, that are usually typeset at the very end of the
% document, are possibly split and sorted so as to include them in the
% document itself. This process has some minor limitations: it's
% impossible to start an index before all other pages have been
% ejected and to have the automatic run of the index sorting program.
% \end{abstract}
%
% \section{Introduction}
% It's been some years now that the typesetting engine of the \TeX\
% system is just \prog{pdftex}; the original Knuthian \prog{tex} is
% still corrected by D.\,E.~Knuth himself, but is frozen, according to
% his will; it is still distributed by every \TeX\ distribution, but
% in practice only \prog{pdftex}, \prog{xetex} or \prog{luatex} are
% used as the interpreter of every macro package and the true
% typesetter engine.
%
% This program \prog{pdftex} was originally born with the facility of
% producing either a pdf output file, as its name suggests, or a dvi
% file. Since then it has been enriched with many upgrades, also with
% regard to the evolution of the PDF language itself. It also
% incorporates the extensions of \eTeX\ and has the ability to open a
% shell so as to call system commands with their arguments. The same
% is true for \prog{xetex} and \prog{luatex}.
% 
% This facility, since the \TeX~Live 2010 distribution, is official,
% but is sort of restricted, in the sense that the \TeX\ system
% configuration file contains a list of ``safe'' system commands that
% can be run by \prog{pdftex}; presently the only program relevant for
% this package is \prog{makeindex}. This precaution is necessary in
% order to avoid running malicious code. Other programs can be run,
% though, but it's necessary to expressly tell \prog{pdftex} that it
% can do so; this authorization is given by means of a suitable
% program option, as explained below.
%
% This package will exploit this facility in order to run a perl
% script that is capable of splitting a raw index file into different
% chunks and to run the \prog{makeindex} or \prog{xindy} \TeX\ system
% programs so as to sort and format the index entries according to a
% specified index style file. Once the shell is terminated, the
% typesetting program resumes its work and possibly prints the various
% formatted indices produced in previous steps. In this way the document
% indices are always synchronous with their document and no further
% typesetting runs are necessary.
%
% In order to reach this goal, it is necessary that at least the
% restricted |write18| facility is enabled; if the \TeX\ distribution
% in use does not enable this restricted feature by default, it
% is necessary to enable the typesetting engine to run such facility;
% depending on the distribution and the shell editor that is being
% used to work on a specific document, it is necessary to add
% \texttt{-shell-escape} (or \texttt{-\/-enable-write18} for MiK\TeX)
% to the command with which the typesetting program is launched,
% possibly through the shell editor. This applies to all three
% \prog{pdftex}, \prog{xetex}, and \prog{luatex} typesetting engines.
%
% {\medskip\footnotesize If Lua\LaTeX{} is used and \prog{luatex} is
% version 0.42 to 0.66, it's impossible to distinguish whether the
% restricted shell escape is active or not, so the automatic procedure
% will be tried anyway, unless disabled with the \texttt{noautomatic}
% package option. With version 0.68 or later, the behavior is the same
% as with the other engines.\par}
%
%
%\section{Package usage}
% This package is invoked as usual by means of a \cs{usepackage} command:
% \begin{flushleft}
% \cs{usepackage}\oarg{options}\texttt{\{imakeidx\}}
% \end{flushleft}
%
% The available \meta{options} consist in a comma separated list of
% the following options:
% \begin{description}\def\Item[#1]{\item[\normalfont\ttfamily#1]}
% \Item[makeindex] in order to use the \prog{makeindex} sorting an
% formatting engine; this option is the default and is mutually
% exclusive with the next option.
% \Item[xindy] in order to use the \prog{xindy} sorting and formatting
% engine; \texttt{texindy} is an alias for \texttt{xindy} and actually
% it's the script \prog{texindy} which is called by this package.
% Nevertheless if the real \prog{xindy} is desired, in order to avoid
% the settings made up by \prog{texindy}, so as to add \prog{xindy}
% the command line specific settings, it is possible to specify the
% option \texttt{truexindy}; the user is then responsible to set up
% the \prog{xindy} engine with the suitable command line options.
% \Item[noautomatic] disables the automatic splitting of the raw
% index files and running of the system programs; this option might
% be used to save time when one knows for sure that the index files
% are already OK and do not need to be refreshed. Actually the time
% spent in splitting, sorting and formatting is so short that this
% option might be useful only when very lengthy indices are being
% processed.
% \Item[nonewpage] inhibits the new page command to be issued when
% using an article type document class and multiple indices are being
% typeset. We don't see why someone would use multiple indices in an
% article (except possibly for package documentations, which usually
% provide a macro index and a list of changes).
% \Item[quiet] suppresses all messages about manual index
% processing.
% \Item[original] uses the class-provided \texttt{theindex}
% environment for typesetting the indices; it is implicitly set if the
% document class option \texttt{twocolumn} has been specified.
% \Item[splitindex] calls the \prog{splitindex} script by Markus Kohm,
% which is included in every \TeX~Live distribution since 2009. With
% this option all index entries, which are written in one raw index
% file, are successively split into all the requested index files;
% in this way there is virtually no limit on the number of indices
% that is possible to create for a particular document.
% \end{description}
%
% The last described option deserves an explanation. \LaTeX{} can
% write on a limited number of files during a run, and some of these
% \emph{output streams} are already reserved (among these: aux files,
% toc files, lof files, lot files, plus several other ones). When more than
% one index is produced, there's the risk to run off the number of
% writable files, because normally \pack{imakeidx} reserves an output
% stream for each index.  So the \texttt{splitindex} option comes to
% rescue: with it only \emph{one} raw index file is written. At the
% first \cs{printindex} command, the program \prog{splitindex} is
% called; it splits the large index file into as many parts as the
% number of requested indices; after this, \prog{makeindex} (or
% \prog{xindy}) can do its job. In this way only one output stream is
% needed during the \LaTeX{} run.
%
% When should you apply this option, then? With one index it's
% useless, you should begin to consider it for two or more indices and
% definitely use it if you get the error
% \begin{verbatim}
% ! No room for a new \write
% \end{verbatim}
% Apart from this case, with or without it, the results are the
% same. See section~\ref{sec:wrong} to see what files are written
% during the \LaTeX{} run with or without the option.
%
% \section{Specific package commands}
% As it is customary when just one index is produced, the standard
% \LaTeX\ facilities, i.e.\ the commands \cs{makeindex}, \cs{index},
% and \cs{printindex} must be used. This package redefines them so as
% to produce multiple indices and defines some others. The first three
% of the following commands may be used only in the preamble.
% \begin{description}\def\Item[#1]{\item[\normalfont\ttfamily\cs{#1}]}
% \Item[makeindex] with the syntax:\\[1ex]
% \cs{makeindex}\oarg{key-values}\\[1ex]
% where \meta{key-values} is a comma separated list of key-value
% assignments of the form: \texttt{key=value}; the available
% keys are the following:
% \begin{description}\def\Item[#1]{\item[\normalfont\sffamily\textsl{#1}]}
% \Item[name] is the symbolic name for an index; if this key is not
% specified, it defaults to the value of the \cs{jobname} control
% sequence, in other words the name of the current main \texttt{.tex}
% file, i.e., the file that |\input|s and/or |\include|s all the files
% of the complete document. This symbolic name is necessary only when
% doing multiple indices and is used with the \cs{index}
% command to point to the right index.\\*
% Example: \texttt{name=nameidx}
% \Item[title] is the title that is typeset at the beginning of the
% specific index; if not specified, the \cs{indexname} value is
% used.\\* Example: \texttt{title=Index of names}.
% \Item[program] is the name of the system program that is used to
% sort and format an index; valid choices are \prog{makeindex},
% \prog{xindy}, or \prog{texindy}, plus \prog{truexindy}. If not
% specified the program specified among the package options is used.
% If no option is specified, \prog{makeindex} is used. In order to
% use \prog{xindy}, it's necessary to call \progpdflatex{} with
% the shell escape command line option.\\* Example: \texttt{program=xindy}.
% \Item[options] is the list of options to be passed to the sorting
% and formatting program; this list is a balanced text of program
% options, separated with the syntax required by the sorting and
% formatting program. For example, in order to use a different
% \prog{makeindex} sorting and formatting style \pack{mystyle.ist} and
% avoiding any message in the screen output, write \texttt{options=-s
% mystyle}.
% \Item[noautomatic] is a boolean key that defaults to \texttt{false};
% you can set it to \texttt{true} by simply listing its key in the
% key-value list, without necessarily specifying the \texttt{=true}
% part. If specified the index sorting program won't be called during
% the typesetting run for this particular index.
% \Item[intoc] is a boolean variable that defaults to \texttt{false};
% if you want to set it \texttt{true} you must simply list this key in
% the key-value list, with no need of specifying the \texttt{=true}
% part. By setting this key to \texttt{true} an entry for this
% particular index is put in the table of contents.
% \Item[columns] accepts an integer representing the number of columns
% in the index; this is silently ignored if the \texttt{original} or
% the \texttt{twocolumn} options are set; the number can even
% be~$1$.\\* Example: \texttt{columns=3}
% \Item[columnsep] accepts a dimension representing the separation
% between index columns; the default is $35$\,pt as in the standard
% classes.\\* Example: \texttt{columnsep=15pt}
% \Item[columnseprule] is boolean; if it is set, a rule will appear
% between the index columns.
% \end{description}
% \Item[indexsetup] with the syntax:\\[1ex]
% \cs{indexsetup}\marg{key-values}\\[1ex]
% where again \meta{key-values} is a comma separated list of \texttt{key=value}
% assignments; the available keys are:
% \begin{description}\def\Item[#1]{\item[\normalfont\sffamily\textsl{#1}]}
% \Item[level] which takes as value a sectioning command such as
% \cs{chapter} or \cs{chapter*}. Actually any command with an argument
% will do and will receive the index title as its argument. The
% default is \cs{chapter*} or, if the class doesn't provide chapters,
% \cs{section*}. If you specify |\caption| so as to override the default
% |\chapter*|, the index title goes directly to the table of contents;
% in this case do not specify the \texttt{intoc} option.
% \Item[toclevel] which takes as value a sectioning command
% \emph{name} such as \texttt{section} to indicate the level at which
% we want the indices appear in the table of contents.
% \Item[noclearpage] is a boolean option; when set, no \cs{clearpage}
% will be issued between indices. You might want to set it in order to
% have a `chapter of indices'; in this case you are responsible for
% setting the right value of the above keys. For example
%\begin{verbatim}
% \indexsetup{level=\section*,toclevel=section,noclearpage}
% ...
% \chapter*{Indices}
% \printindex
% \printindex[names]
% \printindex[objects]
%\end{verbatim}
% See more on this subject in section~\ref{sec:hints}
% \Item[firstpagestyle] which takes as value a page style, default
% \texttt{plain}. You might want to set it to \texttt{empty} or some
% other page style defined by the class or by yourselves. This keyword
% is disabled when the package \pack{fancyhdr} is loaded; any definition
% or choice of page styles must be done before typesetting the indices. 
% \Item[headers] which takes two values: the left and right marks. You
% might want to use this for disabling automatic uppercasing, by
% saying, for example, |headers={\indexname}{\indexname}|; notice that
% these values should always be a pair of balanced braced texts.
% Don't use these keys if you use \pack{fancyhdr}.
% \Item[othercode] which takes as value arbitrary \TeX{} code that
% will be executed at the beginning of index entries typesetting. For
% example you might want to change here the setting of \cs{parskip}.
% \end{description}
% \Item[splitindexoptions] must have as its argument the command line
% option to \prog{splitindex}; this might be necessary on some
% systems. The default is |-m ""|, because we want it only for
% splitting the large index file into its components which are later
% processed by this package.
% \Item[index] with the syntax:\\[1ex]
% \cs{index}\oarg{name}\marg{entry}\\[1ex]
% inserts \meta{entry} into the raw index file(s); upon splitting it in
% different files, this particular entry is listed in the specific
% index file with name \meta{name}; if no name is specified, this
% \meta{entry} is added to the default index with name
% \cs{jobname}. The \meta{entry} should be written according to the
% particular syntax of the sorting and formatting program.
% \Item[indexprologue] with the syntax:\\*[1ex]
% \cs{indexprologue}\oarg{spacing}\marg{text}\\[1ex]
% is used to define some text to go between the index header and the
% entries; the \meta{spacing} should be a vertical space command such
% as |\vspace{36pt}| (default is \cs{bigskip}), controlling the
% spacing between the prologue and the index proper. The command
% affects only the next index produced by \cs{printindex} and is best
% placed just before this command. Please read ahead for further
% information on the use of tho command.
% \Item[printindex] with the syntax:\\*[1ex]
% \cs{printindex}\oarg{name}\\[1ex]
% is used to typeset the particular index named \meta{name}; if no
% optional argument is specified, the default index with name
% \cs{jobname.ind} is typeset.  Actually this command activates all
% the mechanism of closing the output to the raw index file, shelling
% out, possibly calling the \prog{splitindex} script in order to
% divide the single raw file generated by the typesetting engine into
% distinct raw files according to the default or specified
% \meta{name}s for each index, calling the sorting and
% formatting program on each of these split raw files (unless
% inhibited by a \Kvalue{noautomatic} option; in which case a warning
% is issued in order to remember the typesetter that this particular
% index has not been processed), producing the sorted and formatted
% \texttt{.ind} files, and eventually inputs and typesets these
% formatted files. \ Deep breath.
% \end{description}
%
% Let's see an example. The sequence of commands
%\begin{verbatim}
% ...
% \usepackage{imakeidx}
% ...
% \makeindex[title=Concept index]
% \makeindex[name=persons,title=Index of names,columns=3]
% ...
% \begin{document}
% ...
% ...relativity\index{relativity}...
% ...
% ... Einstein\index[persons]{Einstein, Albert}...
% ...
% And this is the end of the story.
%
% \printindex
%
% \indexprologue{\small In this index you'll find only
%   famous people's names}
% \printindex[persons]
% \end{document}
%\end{verbatim}
% will produce two indices. Entries for either index must be typed as
% shown above.  The prologue will be printed (full text width) only
% in the ``Index of names'', which will be typeset in three columns.
%
% When the \texttt{original} option is set, maybe implicitly because
% of \texttt{twocolumn}, \cs{indexsetup} and the keys
% \Kvalue{columns}, \Kvalue{columnsep} and \Kvalue{columnseprule} for
% \cs{makeindex} have no effect. Please read more on this matter further~on.
%
% \section{If something goes wrong}\label{sec:wrong}
% Since \pack{imakeidx} relies on good cooperation between package
% options and command line options for the \LaTeX{} run, in some cases
% it may happen that the indices are not correctly built or built at
% all.
%
% If you use only \prog{makeindex} and \TeX~Live 2010 or later, then
% you shouldn't need anything special, since \prog{makeindex} is among
% the safe programs allowed to be called during a \LaTeX{} run, be it
% \prog{latex}, \prog{pdflatex}, \prog{xelatex}, or \prog{lualatex}.
% When the options \texttt{splitindex}, \texttt{xindy},
% \texttt{texindy} or \texttt{truexindy} are specified (globally or
% locally), the \LaTeX{} run should be called with the unrestricted
% \texttt{-shell-escape} (which is \texttt{--enable-write18} for
% MiK\TeX) typesetting program  option or the \texttt{noautomatic}
% option should be specified when loading \pack{imakeidx}.
% 
% Let's look at a couple of examples. In both we suppose that the
% document \texttt{mybook.tex} defines two indices through
%\begin{verbatim}
% \makeindex[...]
% \makeindex[name=secondary,...]
%\end{verbatim}
% where |...| denotes possible options excluding \texttt{name}.
%
% First of all we examine the case when \pack{imakeidx} is called
% \emph{without} \texttt{splitindex}. Two files called
% \texttt{mybook.idx} and \texttt{secondary.idx} will be written
% during the \LaTeX{} run. At the corresponding \cs{printindex}
% command, \prog{makeindex} will act on each of them producing the files
% \texttt{mybook.ind}, \texttt{mybook.ilg}, \texttt{secondary.ind} and
% \texttt{secondary.ilg}. The \texttt{.ind} files contain the relevant
% \texttt{theindex} environments with alphabetized entries, while in
% the \texttt{.ilg} files \prog{makeindex} will write its log. You can
% check in \texttt{mybook.log} whether the \prog{makeindex} run has
% been executed by searching for a line
%\begin{verbatim}
% runsystem(makeindex <...>)...executed
%\end{verbatim}
% where |<...>| stands for the rest of the command line in the
% particular case. If this line is not present, then \prog{makeindex}
% has not been called; this happens when you didn't specify the shell
% escape command line option for the \LaTeX{} run or the restricted
% shell escape is not active; also, of course, if you set the
% \texttt{noautomatic} option for the index.
%
% {\tolerance=9999
% When using \prog{splitindex}, the situation is different. During the
% \LaTeX{} run, only a large index file called \texttt{mybook.idx} file
% gets written; the first \cs{printindex} command will call
% \prog{splitindex} (unrestricted shell escape \emph{must} be active),
% which will produce the two partial index files \texttt{mybook-mybook.idx}
% and \texttt{mybook-secondary.idx}. These two files will be processed by
% \prog{makeindex} producing the four files \texttt{mybook-mybook.ind},
% \texttt{mybook-mybook.ilg}, \texttt{mybook-secondary.ind} and
% \texttt{mybook-secondary.ilg}.
% The line
%\begin{verbatim}
% runsystem(splitindex <...>)...executed
%\end{verbatim}
% in \texttt{mybook.log} will tell that the splitting has been done
% (see later on if this doesn't seem true). In table~\ref{tab:files} you
% can see what files are produced when the first two lines are in the
% preamble.\par}
%
% \begin{table}[tp]
% \centering\begingroup\ttfamily
% \begin{tabular}{rll}
% \toprule
% \multicolumn{3}{c}{\ttfamily\cs{makeindex}\hphantom{[name=secondary]}}\\
% \multicolumn{3}{c}{\ttfamily\cs{makeindex}[name=secondary]}\\
% \midrule
% \addlinespace
% &\normalfont without \texttt{splitindex} &
% \normalfont with \texttt{splitindex} \\
% \cmidrule(lr){2-2} \cmidrule(lr){3-3}
% \addlinespace
% \normalfont(at \cs{begin}\texttt{\{document\}})\\
% \addlinespace
% &mybook.idx & mybook.idx \\
% &secondary.idx  \\
% \addlinespace
% \normalfont(at \cs{printindex})\\
% \addlinespace
% &mybook.ind    & mybook-mybook.idx \\
% &mybook.ilg    &  mybook-secondary.idx\\
% &secondary.ind & mybook-mybook.ind\\
% &secondary.ilg & mybook-mybook.ilg\\
% &              & mybook-secondary.ind \\
% &              & mybook-secondary.ilg \\
% \bottomrule
% \end{tabular}\endgroup
% \caption{Files written during a \LaTeX{} run}\label{tab:files}
% \end{table}
%
% Everything is the same when using \prog{texindy} for alphabetizing,
% except that, by default, it doesn't write \texttt{.ilg} files. If
% you want them, add |options=-t|\meta{name}|.ilg| to the relevant
% \cs{makeindex} command, in our example it should be
%\begin{verbatim}
% \makeindex[...,options=-t mybook.ilg]
% \makeindex[name=secondary,...,options=-t secondary.ilg]
%\end{verbatim}
% The name of the \texttt{.ilg} file \emph{must} be specified.
% Remember, though, that \prog{xindy} \texttt{.ilg} files may turn out
% to be very large.
%
% When something different from expected appears to take place, check
% also the time stamps of the produced files; if they are older than
% \texttt{mybook.log}, it means that they have not been written in the
% last run. The most common case is that you forgot to activate the shell
% escape feature (which is not necessary with \TeX~Live 2010 or later,
% provided you use only \prog{makeindex}).
%
% Another cause of malfunction might be a wrong option passed to
% \prog{makeindex}, \prog{texindy} or \prog{splitindex}. For example,
% if you specify a style option for \prog{makeindex} such as
% |options=-s mystyle.ist| and the style file is missing or its name
% is mistyped, the run of \prog{makeindex} will result in
% \texttt{mybook.log}, but it will be aborted and the \TeX{} program
% has no control over this process. In this case the \texttt{.ilg} and
% \texttt{.ind} files will not be produced and you can spot the
% problem by checking the time stamps. On some systems a message such as
%\begin{verbatim}
% Index file mystyle.ist not found
% Usage: makeindex [-ilqrcgLT] [-s sty] [-o ind] [-t log] [-p num]
%\end{verbatim}
% may appear on the screen, but often this window gets closed before
% you realize you have a problem. The time stamp is the best clue to
% detect such problems.
%
% Shell hackers may be able to redirect the \texttt{stderr} stream to
% a file, but this requires skills that can't be explained here,
% because they require tens of different tricks, depending on what
% method is used to start a \LaTeX{} run. From the command line,
% assuming \prog{bash}, it would be something like
%\begin{verbatim}
% pdflatex -shell-escape mybook.tex 2>latex-errors
%\end{verbatim}
% If shell hackers know a way to access the exit status of the called
% program, we'd be glad to implement a supplementary check.
%
% ^^A G
% \section{Hints}\label{sec:hints}
% Actually this package reaches two goals: (\textit{a})~it typesets
% the indices of a specific document in just one run, and
% (\textit{b})~it lets the author\slash typesetter produce
% documents with multiple indices.
%
% \subsection{Conflicts}
%
% \subsection{Two columm typesetting and index prologue}
% As it has been already mentioned, it is possible to use the command
% |\indexprologue| to write some text before the index proper gets typeset;
% an optional space may be used in place of the default one-line spacing
% between the index title, the prologue and the index body.
% 
% This facility relies on a particular feature of the |multicols|
% environment, that \pack{imakeidx} uses to instruct the typesetting
% program to typeset the index with a specified number of balanced columns.
% The choice of |multicols| has been made because it balances the
% columns in the last page; the declaration |\twocolum| does not
% perform the same way, and, if used, it makes |\printindex| typeset
% the index in two-column mode with an unbalanced last column.
%
% In the previous sections it has been clearly stated that any
% configuration of the way \pack{imakeidx} typesets the indices
% is bypassed if the option \opz{original} has been specified
% either explicitly or implicitly. It is implicitly specified
% if the option \opz{twocolumn} is specified in the class
% declaration statement.
% Why? Because if two column typesetting is desired for the whole
% document, it is not clear if the index has to be typeset in one
% column within each column of the document, or if it should be
% typeset in two column mode after a |\onecolumn| command is being
% issued; the results are not the same: with the former method the
% columns remain unbalanced, while the latter has balanced columns.
% Furthermore the |\onecolum| command forces a page break; without
% the |\onecolumn| command if the index is treated as a  chapter,
% there is a page break, while if it is configured to be typeset
% as a section there is no forced page brake. With this plethora
% of combinations we decided to avoid any configuration of the
% index typesetting and left the decision to the user. This
% requires the user to practice some ingenuity in order to obtain
% what he expects.
%
% First of all the user shall not specify the \opz{twocolumn}
% option to the class. Secondly the user asks for the use of
% \pack{imakeidx} and sets up the single or multiple |\makindex|
% commands. thirdly he loads all other packages required for his
% document; possibly he uses also \pack{geometry} in order to
% specify a specific page layout. He shall specify the |\twocolumn|
% declaration after the above has been completed, in any case
% after the \pack{imakeidx} package has been loaded and the single
% or multiple |\makeindex| commands are configured.
%
% A good example might be this one:
%\begin{verbatim}
%\documentclass[a4paper,11pt]{book}
%\usepackage{imakeidx}
%\indexsetup{level=\section*,toclevel=section,noclearpage}
%\makeindex[title=Index of places,columns=1]
%\twocolumn
%\usepackage[T1]{fontenc}
%\usepackage{lmodern}
%\usepackage[italian,english]{babel}
%\usepackage[utf8]{inputenc}
%\usepackage[a4paper,margin={1in,1in},binding=3mm]{geometry}
%\usepackage[english]{varioref}
%\usepackage[hang]{caption}
%\begin{document}
%...
%\indexprologue{This index lists all the residences where Lady Esther
%lived during the time span described in the book.}
%\printindex
%\end{document}
%\end{verbatim}
% In this way the index is typeset as a ``section'', not as a
% ``chapter'', in one column mode within the two column document
% style; the indicated prologue is typeset between the index
% title ``Index of places'' and the start of the index proper.
%
% On the opposite the following code:
%\begin{verbatim}
%\documentclass[a4paper,11pt]{book}
%\usepackage{imakeidx}
%\makeindex[title=Index of places,columns=2]
%\twocolumn
%\usepackage[T1]{fontenc}
%\usepackage{lmodern}
%\usepackage[italian,english]{babel}
%\usepackage[utf8]{inputenc}
%\usepackage[a4paper,margin={1in,1in},binding=3mm]{geometry}
%\usepackage[english]{varioref}
%\usepackage[hang]{caption}
%\begin{document}
%...
%\onecolumn
%\indexprologue{This index lists all the residences where Lady Esther
%lived during the time span described in the book.}
%\printindex
%\end{document}
%\end{verbatim}
% produces an index typeset as a ``chapter'', starting on a new page;
% it is typeset in two balanced columns. The prologue is typeset where it should.
% The ingenious reader can experiment mixing the various settings
% used in these two examples in order to find out what benefits or
% disadvantages one can obtain with settings that are not physically
% impossible, but that may be aesthetically conflicting with one another.

% \subsubsection{Class \class{memoir}}
%
% The first public version of this package was not compatible with the
% \pack{memoir} class. Since version 1.1 it is; however, one has to
% keep in mind that all index processing is done with the methods of
% the present package, and \emph{not} with \pack{memoir}'s; however
% the syntax used is the same and there should be no problem. There is
% an interaction between \pack{memoir} and \pack{showidx} that required
% special attention. See below about using \pack{showidx}.
%
% \subsubsection{Package \pack{showidx}} 
%
% Up to version 1.1 this package did not allow to use it together with the \pack{showidx}
% package; now it is, provided that \pack{showidx} is loaded \emph{before} \pack{imakeidx}.
% See below more information on using \pack{showidx}.
%
% \subsubsection{Package \pack{fancyhdr}}
% 
% When using package \pack{fancyhdr} some inconveniences did show up; now we believe
% we have detected the causes and we implemented the necessary corrections\footnote{Thanks
% to Maïeul Rouquette, who spotted the problems and also suggested some patches.}.
%
% \subsubsection{Package \pack{combine}}
%
% Apparently there might be some conflicts with package \pack{combine}, because this
% package redefines the contents of |\jobname|; we tried to control this behavior,
% and made the necessary patches, but it is still necessary to load this
% package \pack{imakeidx} \emph{before} package \pack{combine}.
%
% \subsubsection{Package \pack{ledmac}}
%
% Some users reported some conflicts with package \pack{ledmac}; in order to mark
% with an italic `n' the pages where the reference was made in one of the footnotes,
% it is necessary to use the package \pack{etoolbox} and its command |\pretocmd|;
% actually it is not necessary to load \pack{etoolbox}, because this \pack{imakeidx}
% provides for it:
%\begin{verbatim}
%...
%\usepackage{letltxmacro}
%\usepackage{imakeidx}
%...
%\makeatletter
%\LetLtxMacro\orig@@index\index
%\let\orig@@index\index
%\newcommand\nindex[1]{\orig@@index{#1|innote}}
%\newcommand\innote[1]{#1\textit{n}}
%...
%\makeindex[...] 
%...
%\AtBeginDocument{%
%    \pretocommand{\@footnotetext}{\let\index\nindex}{}{}
%}
%\end{verbatim}
% We did not apply this patch directly because we tried to avoid possible conflicts
% that might show up when loading other packages. Therefore we simply show what
% to do in case it might be necessary.

%
%\subsection{Index layout customization}
% If you redefine yourself the \texttt{theindex} environment, please
% remember not to number the chapter or section that introduces the
% index if you ask for the \Kvalue{intoc} option; either use the
% commands \cs{chapter*} or the \cs{section*} respectively and the
% \Kvalue{intoc} option or don't use this option and redefine your
% \texttt{theindex} environment with numbered chapter or section
% commands, that will put the index titles directly into the table of
% contents. See below the effect of the |\backmatter| declaration.
% You may use the \pack{idxlayout} package by Thomas Titz,
% which offers many functions for index typesetting customization and
% is compatible with our package; remember to load \pack{idxlayout}
% after \pack{imakeidx}. This package has a similar function to our
% \cs{indexprologue}, called \cs{setindexprenote}; however
% \pack{idxlayout} doesn't reset the index prologue, which must be
% declared anew or disabled with \cs{noindexprenote} before the next
% \cs{printindex} command. In any case take into serious consideration
% what is being said hereafter about customizations.
%
% \subsection{Index page customization}
% The same, more or less, holds true if you customize your headings;
% \pack{imakeidx} can deal with standard settings, but it generally
% cannot deal with personal stylings and customizations. This is why
% if you load \pack{fancyhdr}, some of the |\indexsetup| settings may be
% disabled.

% When you make any kind of customization, remember that there are
% several classes, or personal settings, or features that may render your
% customization very difficult to handle. Typically:
%^^A
%\begin{itemize}
% \item There are classes where the normal usable highest sectioning
% command, disregarding |\part|, is not |\chapter|, but |\section|; for
% example classes \class{article}, \class{scrartcl}.
%^^A
%\item Sectioning commands come in two varieties: starred and unstarred;
% the former ones are not numbered and do not produce any entry in the
% headings and in the table of contents; the latter ones may  behave
% differently according to the next item.
%^^A
% \item There are some classes (for example \class{book},
% \class{scrbook}, \class{menoir},\dots) that have the special
% ``sectioning'' declarations |\frontmatter|, |\mainmatter|, and
% |\backmatter| modify how the unstarred sectioning commands behave for
% what concerns the heading and the table of contents entries.
%
% For what concerns indices, these are generally typeset at the document
% end. This means that the |\backmatter| declaration may be in force;
% in this case unstarred sectioning commands are not numbered but they
% produce normal headings and table of contents entries.
%^^A
%\item Heading entries are used by the output routine paging algorithm
% in such a way as to extract the left or the right part from suitable
% ``marks''; for the even (left) pages the required information is
% extracted from the |\topmark| or |\firstmark|, while for the odd (right)
% pages they are extracted from the |\botmark|. Generally speaking,
% the even page heading refers to |\leftmark| and odd page headings
% refer to |\rightmark|; these are the two commands that extract the
% correct part from the suitable marks. But when you use the
% \Kvalue{headers} option value, you specify two brace balanced strings that
% are loaded through |\markboth| as the left and right part of the
% current mark.
%^^A
% \item The contents of the marks may be very varied; they are generally
% made up of two brace balanced strings, which in turn may contain other
% brace balanced strings that may be used in different ways by the selected page
% style and by the page style definitions of the macros |\chaptermarks|,
% |\sectionmarks|, and |\subsectionmarks| that may interfere with personal
% customizations.
%^^A
% \item Remember also that things change in an obvious way when one side
% typesetting is chosen; all pages are treated as if they were odd ones;
% therefore any customization must take into account also this aspect.
%\end{itemize}
%
% The above list has not been written down for discouraging customizations
% of any kind: simply it recalls what must be taken care of in order to
% create one's customization in a proper way.
%
% The above list explains why we disabled the commands tied to the
% |\indexsetup| keys \Kvalue{headings} and \Kvalue{firstpagestyle} when
% package \pack{fancydr} is being used; you may even set up these keys,
% but if the \pack{fancyhdr} package has been loaded, we disable their
% action; this implies that any fancy customization must be done before
% starting to print any index.
%
% The \Kvalue{intoc} option must also be used with care, as well as the starred
% or unstarred sectioning commands for the \Kvalue{level} and
% \Kvalue{toclevel} option values. They must be chosen according to what the
% possible |\backmatter| declaration sets up, in order to avoid double
% entries in the table of contents; the |\backmatter| settings may also
% influence the way heading information is being used, and this makes it
% even more stringent to set up any index page style customization
% before starting to print any index.
%
% Therefore if by chance you get double entries into the table of contents,
% eliminate the \Kvalue{intoc} option from your calls; your class,
% packages, and settings are already taking care of it. 

% The package \pack{tocbibind} should be loaded with the \Kvalue{noindex}
% option, otherwise it would interfere with our redefinition of
% \texttt{theindex}.
%
% If you redefine your \texttt{theindex} environment by means of other
% packages, pay attention that these redefine a real \texttt{theindex}
% environment with this very name; if they create an environment with
% a different name, \pack{imakeidx} can't take care of the indices
% production (in particular the \TeX\ system program \prog{makeindex}
% creates a sorted and formatted \texttt{.ind} file that refers
% explicitly to the \texttt{theindex} environment), and it can't take
% care of the table of contents entry and of the position of the hyper
% link anchors needed to navigate your document by means of hyper
% links.
%
% \subsection{Index location customization}
%
% Some packages might want to use the facilities of \emph{imakeidx} to offer customized 
% index commands, where the entry location is not expressed by a page number, 
% but by an other reference value (for example: line number, entry number, etc.).
%
% These packages may use the low-level command \cs{imki@wrindexentry} which takes three arguments:
% \begin{enumerate}
% 	\item The index name.
% 	\item The entry.
% 	\item The location number.
% \end{enumerate}
% For example \verb+\imki@wrindexentry{names}{Charles}{26}+ adds to the index \verb+names+
% the value \verb+Charles+ with the location reference \verb+26+.
%
% In simpler words, the new command \cs{imki@wrindexentry} is of interest mainly to package
% and class authors; it is not to be used by the ``normal'' user, who, on the opposite,
% if interested in referencing the index entries on some location counter different
% from the page one, is urged to refer to the classes and packages that implement this
% facility; \pack{eledmac} should be one of these packages. Matter of fact this addition
% to the \pack{imakeidx} package was contributed by Maïeul Roquette, the author
% and maintainer of \pack{eledmac}, and we thank him very much,
%
% \subsection{Using the \textsf{showidx} package}
% If you want to make use of the \pack{showidx} facilities, remember
% to load that package \emph{before} \pack{imakeidx}; remember also
% to disable or comment out the call to \pack{showidx} when you
% typeset the final version of your document. This constraint is due
% to the fact that \pack{showidx} redefines several internal commands,
% some of which have to receive the \pack{imakeidx} definition in order
% to perform as described in this documentation.

% At the same time if the \pack{memoir} class is being used, remember that this class
% simulates the \pack{showidx} package and has its own commands to enable or
% disable the printing of the index entries into the margin of the document;
% the default setting is with the |\hideindexmarks| command in force; but if
% the user wants to write his index entries in the margin he has to issue the
% declaration |\showindexmarks| just after begin document, in any case before
% the part of the source file(s) he wants to be marked with the index entries
% in the margin.
%
% \subsection{Index List sectioning customization}
% Use freely the options and the key values in order to reach the
% desired results, but you are advised to prepare in advance the
% styles for composing the various indices in a proper way; for
% example, if you use a titled style for the index, where the index
% sections are distinguished with a bold face title or alphabetic
% letter, you have to set up a \texttt{.ist} file, such as
% \texttt{myindexstyle.ist}, made up like this:
%\begin{verbatim}
%	headings_flag 1
%	heading_prefix   "\\par\\penalty-50\\textbf{"
%	heading_suffix   "}\\\\\*\~\\\\\*"
%	symhead_positive "Symbols"
%	symhead_negative "symbols"
%	numhead_positive "Numbers"
%	numhead_negative "numbers"
%	delim_0 ",\~"
%\end{verbatim}
% where the numeric and non alphabetic entries have different
% titles. But, say, you are making also an index where the entries are
% file names, and for some names only the extension is entered; the
% extensions start with a dot, so the sorting program will sort these
% names at the beginning of the sorted index file, but you won't like
% to have  a title such as ``Symbols''; you probably prefer to have a title
% such as ``Extensions''; therefore you have to prepare a different
% index style file, such as this one:
%\begin{verbatim}
%	headings_flag 1
%	heading_prefix   "\\par\\penalty-50\\textbf{"
%	heading_suffix   "}\\\\\*\~\\\\\*"
%	symhead_positive "Extensions"
%	symhead_negative "extensions"
%	numhead_positive "Numbers"
%	numhead_negative "numbers"
%	delim_0 ",\~"
%\end{verbatim}
%
% This done, besides requiring the use of this package, you have to
% declare the \cs{makeindex} command with the necessary options; pay a
% particular attention to the options that involve the index symbolic
% name, the index title, the index style, the fact that the index
% titles shall appear in the table of contents, and if you are
% preparing an e-book, you probably would like to hyper link both the
% page numbers and the index titles to the proper locations.
% The typesetting program will do everything for you but be careful
% not to confuse it with illogical index entries.
%
% Especially with multiple indices it is important that you are
% consistent in putting the right information in the right index and
% with a consistent mark-up. Define yourself appropriate macros so
% that, for example, personal names are consistently typeset, say, in
% caps and small caps and are entered into a specific index; you may
% even create one command to typeset the name in the document and
% replicate the same name in the index.
%
% Of course there is no program that can decide at your place what and
% where to index each piece of information; this is a task for
% humans. Soooooo\dots
% \begin{center} HAPPY \TeX{}ING!\end{center}
%
% \StopEventually{\PrintChanges}
% \section{Implementation}
% The heading to the file is in common with the documentation file,
% and has already been taken care of. But we require the
% \pack{xkeyval} package, in order to handle the key-value lists.
%
% Notice that in order to create a specific name space so as to avoid
% possible conflicts with other packages, all the commands defined in
% this package are prefixed with the string \texttt{imki@}.
%\iffalse
%<*package>
%\fi
%    \begin{macrocode}
\RequirePackage{xkeyval}
%    \end{macrocode}
%
% We define the various options and their defaults. After
% \cs{ProcessOptions}, we set anyway the \texttt{original} option if
% the document class has been given the \texttt{twocolumn} option,
% which is incompatible with \pack{multicol}. We define also an
% internal alias for |\immediate\write18|, a rudimentary check for the
% typesetting engine and a macro for modifying the command line call
% to \prog{splitindex}. The \pack{xpatch} is requested; at the moment
% none if its features are used, but it calls \pack{etoolbox}, whose
% facilities are used here; while future extensions will benefit from
% the extended patched commands, that strongly enrich the performances
% of the main package \pack{etoolbox}.
% \changes{v1.1a}{2012/09/07}{Fixed bug with possibly defined
% \cs{directlua}; now we leave the check to \pack{ifluatex}; using
% also \pack{ifxetex} for symmetry.}
%    \begin{macrocode}
\DeclareOption{xindy}{\def\imki@progdefault{texindy}}
\DeclareOption{texindy}{\def\imki@progdefault{texindy}}
\DeclareOption{truexindy}{\def\imki@progdefault{truexindy}}
\DeclareOption{makeindex}{\def\imki@progdefault{makeindex}}
\newif\ifimki@disableautomatic
\DeclareOption{noautomatic}{\imki@disableautomatictrue}
\newif\ifimki@nonewpage
\DeclareOption{nonewpage}{%
  \imki@nonewpagetrue\imki@disableautomatictrue
}
\newif\ifimki@splitindex
\DeclareOption{splitindex}{\imki@splitindextrue}
\newif\ifimki@original
\DeclareOption{original}{\imki@originaltrue}
\DeclareOption{quiet}{\AtEndOfPackage{%
  \let\imki@finalmessage\@gobble
  \let\imki@splitindexmessage\relax}}
\ExecuteOptions{makeindex}
\ProcessOptions\relax

\if@twocolumn\imki@originaltrue\fi
\def\imki@exec{\immediate\write18}
\def\imki@engine{(pdf)latex}
\RequirePackage{ifxetex,ifluatex}
\ifxetex\def\imki@engine{xelatex}\fi
\ifluatex % luatex doesn't have \(pdf)shellescape
 \def\imki@engine{lualatex}
  \ifnum\luatexversion<68
    \chardef\imki@shellescape\@ne % no way to know the value
  \else
    \RequirePackage{pdftexcmds} % provides \pdf@shellescape
    \chardef\imki@shellescape\pdf@shellescape
  \fi
  \let\imki@exec\pdf@system
\fi
\RequirePackage{xpatch}
\edef\imki@splitindexoptions{-m \string"\string"}
\def\splitindexoptions#1{\g@addto@macro\imki@splitindexoptions{ #1}}
\@onlypreamble\splitindexoptions
%    \end{macrocode}
%
% ^^A A - incompatibilities and emulation
%
% While experimenting we found out that some classes or packages are
% either incompatible with this one, or must be faked in order to
% pretend they have been loaded.
%
% There is a serious incompatibility with the \pack{memoir} class.  In
% facts \pack{memoir} puts all index entries in the main \texttt{.aux}
% file and extracts them to the various raw index files at
% |\end{document}| time. This means that no raw index file output
% stream has been defined, and therefore this package can't close it;
% moreover it can't typeset the indices before |\end{document}|
% because they are not yet available. Therefore if \pack{memoir} is
% the active class, we will hijack its index mechanism replacing it
% with ours.
%
% On the opposite we pretend that package \pack{makeidx} or package
% \pack{multind} have been loaded, so that \pack{hyperref} can play
% with their commands, that are substantially the same as those used
% here. By so doing those packages are inhibited from being loaded
% after this one.
%    \begin{macrocode}
\@namedef{ver@makeidx.sty}{3000/12/31}
\@ifpackageloaded{multind}
  {\PackageError{imakeidx}{Incompatible package `multind' loaded}
    {This package is incompatible with multind, don't load both.%
     \MessageBreak\@ehc}}
  {\@namedef{ver@multind.sty}{3000/12/31}}
%    \end{macrocode}
% At the same time we redefine some commands defined by \pack{makeidx}
% and we define the default English names for the \cs{see} and
% \cs{seealso} commands. We use \cs{providecommand} so that, if
% \pack{makeidx} has already been loaded, we do not redefine things
% that have already been defined.
%    \begin{macrocode}
\providecommand*\see[2]{\emph{\seename} #1}
\providecommand*\seealso[2]{\emph{\alsoname} #1}
\providecommand*\seename{see}
\providecommand*\alsoname{see also}
%    \end{macrocode}
%
% ^^A C - \makeindex
%
% From here on, some commands are duplicated; this depends on the
% fact that the behavior must be different when using \prog{splitindex} or
% not. The memory occupied by the useless commands will be cleared at the 
% end of package.
%    \begin{macrocode}
\providecommand*\makeindex{} % to use \renewcommand safely
\renewcommand{\makeindex}[1][]{\imki@makeindex{#1}}
% \@onlypreamble\makeindex % Already in latex.ltx
%    \end{macrocode}
% This package implementation of \cs{makeindex} sets default values
% for the keys, then evaluates its argument (which is the optional
% argument to \cs{makeindex}) and calls two other macros. After that
% we have to reset the defaults.
%    \begin{macrocode}
\def\imki@makeindex#1{%
  \edef\imki@name{\jobname}%
  \edef\imki@jobname{\jobname}%
  \def\imki@title{\indexname}%
  \edef\imki@program{\imki@progdefault}%
  \let\imki@options\space
  \KV@imki@noautomaticfalse\KV@imki@intocfalse
  \setkeys{imki}{#1}%
  \ifimki@splitindex\KV@imki@noautomaticfalse\fi
  \imki@build\imki@name
  \imki@startidx\imki@name
  \imki@resetdefaults
}
%    \end{macrocode}
%
% Here are the keys. As usual, the \texttt{imki@} prefix is used to
% distinguish anything that is being defined in this package, even the
% keys.
%    \begin{macrocode}
\define@key{imki}{name}{\def\imki@name{#1}}
\define@key{imki}{title}{\def\imki@title{#1}}
\define@choicekey{imki}{program}[\imki@val\imki@nr]
  {makeindex,xindy,texindy,truexindy}{%
    \ifcase\imki@nr\relax
      \def\imki@program{makeindex}%
    \or
      \def\imki@program{texindy}%
    \or
      \def\imki@program{texindy}%
    \or
      \def\imki@program{xindy}%
    \fi}
\define@key{imki}{options}{\def\imki@options{ #1 }}
\define@boolkey{imki}{noautomatic}[true]{}
\define@boolkey{imki}{intoc}[true]{}
\define@key{imki}{columns}{\def\imki@columns{#1}}
\define@key{imki}{columnsep}{\def\imki@columnsep{#1}}
\define@boolkey{imki}{columnseprule}[true]{}
\def\imki@resetdefaults{%
  \def\imki@options{ }%
  \def\imki@columns{2}\def\imki@columnsep{35\p@}%
  \KV@imki@columnseprulefalse
  \KV@imki@intocfalse\KV@imki@noautomaticfalse}
\imki@resetdefaults
%    \end{macrocode}
%
% The control sequence \cs{imki@build} defines a control sequence to
% hold the setup for an index to be used when the index is sorted and
% printed
%    \begin{macrocode}
\def\imki@build#1{%
  \toks@{}%
  \imki@dokey\imki@title
  \imki@dokey\imki@program
  \imki@dokey\imki@options
  \imki@dokey\imki@columns
  \imki@dokey\imki@columnsep
  \ifKV@imki@noautomatic
    \addto@hook\toks@{\KV@imki@noautomatictrue}%
  \else
    \addto@hook\toks@{\KV@imki@noautomaticfalse}%
  \fi
  \ifKV@imki@intoc
    \addto@hook\toks@{\KV@imki@intoctrue}%
  \else
    \addto@hook\toks@{\KV@imki@intocfalse}%
  \fi
  \ifKV@imki@columnseprule
    \addto@hook\toks@{\KV@imki@columnsepruletrue}%
  \else
    \addto@hook\toks@{\KV@imki@columnseprulefalse}%
  \fi
  \expandafter\edef\csname imki@set@#1\endcsname{\the\toks@}%
}
%    \end{macrocode}
% Comand \cs{imki@dokey} receives as argument the text of the values
% assigned to certain keys, and adds them to the options token list.
%    \begin{macrocode}
\def\imki@dokey#1{%
  \expandafter\addto@hook\expandafter\toks@\expandafter{%
    \expandafter\def\expandafter#1\expandafter{#1}}}
%    \end{macrocode}
%
% Command \cs{imki@startidx} defines the output stream(s); the macro
% with suffix \texttt{split} is used when \Kvalue{splitindex} is not
% enabled, the one with suffix \texttt{unique} is used otherwise.  In
% the case of many indices, the symbolic name for an index named
% `pippo' is \cs{pippo@idxfile} corresponding to the file
% \texttt{pippo.idx}. When \Kvalue{splitindex} is enabled, the only
% output stream is called \cs{@indexfile} as in standard \LaTeX,
% corresponding to \cs{jobname.idx}.
%    \begin{macrocode}
\def\imki@startidxsplit#1{%
  \if@filesw
    \def\index{\@bsphack
      \@ifnextchar [{\@index}{\@index[\imki@jobname]}}
    \expandafter\newwrite\csname #1@idxfile\endcsname
    \immediate\openout \csname #1@idxfile\endcsname #1.idx\relax
    \typeout{Writing index file #1.idx}%
  \fi}
%    \end{macrocode}
% We define a switch which is set to true when a \cs{makeindex} command is given:
% with \Kvalue{splitindex} we open only one stream.
%    \begin{macrocode}
\newif\ifimki@startedidx
\def\imki@startidxunique#1{%
  \if@filesw
    \ifimki@startedidx\else
      \newwrite\@indexfile
      \immediate\openout\@indexfile\imki@jobname.idx%
      \global\imki@startedidxtrue
    \fi
    \def\index{\@bsphack
      \@ifnextchar [{\@index}{\@index[\imki@jobname]}}
    \expandafter\let\csname #1@idxfile\endcsname\@empty
    \typeout{Started index file #1}%
 \fi}
%    \end{macrocode}
%
% ^^A D - \index 
%
% Provide a default definition for \cs{index}; when a \cs{makeindex}
% command is given and \LaTeX\ is writing on auxiliary files,
% \cs{index} will be redefined, as seen before. When index files are
% written, \cs{index} always calls \cs{@index}. Some code is borrowed
% from \pack{memoir.cls}, but heavily modified. We want \cs{@wrindex}
% to be defined with two arguments, so that \pack{hyperref} can hook
% into it just like it does with the similar commands defined by the
% old packages \pack{multind} and \pack{index}.
%    \begin{macrocode}
\renewcommand{\index}[2][]{\@bsphack\@esphack}
\def\@index[#1]{%
  \@ifundefined{#1@idxfile}%
  {\PackageWarning{imakeidx}{Undefined index file `#1'}%
   \begingroup
   \@sanitize
   \imki@nowrindex}%
  {\edef\@idxfile{#1}%
   \begingroup
   \@sanitize
   \@wrindex\@idxfile}}
\def\imki@nowrindex#1{\endgroup\@esphack}
%    \end{macrocode}
%
% Command \cs{@wrindex} must be duplicated; we have to call it the same as usual in order
% to support \pack{hyperref}. But the real name will be given at the end. We have to
% define a switch to allow the use of the \pack{showidx} facilities. We define also a
% helper macro so as to do the right thing so as to show the index file name to which
% a certain index entry is going to be written; the idea is to prefix the index entry
% with the actual name of the specific index, except in the case or the default index,
% where the name is set to |\jobname|. Since the control sequence is a primitive
% command, its value cannot be directly compared in the |\ifx| sense to the current
% macro represented by argument |#1|. Therefore we need a further helper control
% sequence |\imki@jobname| that contains the value assigned to |\jobname|.
% We must also take care of the case where the user wants to print the index entries
% in the margin while working on the document. This implies testing for the package
% \pack{showidx} being already loaded;  but this is not sufficient, because the
% \pack{memoir} class simulates the \pack{showidx} package and the test would result
% to be true even if the user did not load thet package, but uses the \pack{memoir} class.
% Therefore we use the same boolean used by \pack{memoir}, testing in advance so as not
% defining it twice; then we use it to let the \pack{showidx} true or simulated macros do
% their job, but we also take care of resetting the switch default value to
% false at begin document time if the \pack{memoir} class is being used. 
%
%
%    \begin{macrocode}
\@ifundefined{showindexmarks}{\newif\ifshowindexmark}{}
\@ifpackageloaded{showidx}{\showindexmarktrue}{\showindexmarkfalse}
\newcommand\imki@showidxentry[2]{%
  \ifshowindexmark
    \@showidx{\ifdefequal{\imki@jobname}{#1}{}{[#1]\space}#2}%
  \fi}
\newcommand\imki@wrindexentrysplit[3]{%
  \expandafter\protected@write\csname#1@idxfile\endcsname{}%
    {\string\indexentry{#2}{#3}}%
}
\newcommand\imki@wrindexentryunique[3]{%
  \protected@write\@indexfile{}%
    {\string\indexentry[#1]{#2}{#3}}%
}
\def\imki@wrindexsplit#1#2{%
	\imki@wrindexentrysplit{#1}{#2}{\thepage}%
	\endgroup\imki@showidxentry{#1}{#2}%
  \@esphack%
}
\def\imki@wrindexunique#1#2{%
	\imki@wrindexentryunique{#1}{#2}{\thepage}%
	\endgroup\imki@showidxentry{#1}{#2}%
  \@esphack%
  }
%    \end{macrocode}
%
% ^^A E - \printindex
%
% Compilation of the indices is disabled if \texttt{-shell-escape} has
% not been given or the restricted mode is not active; in this case we
% emit a warning. \XeTeX{} has \cs{shellescape} instead of
% \cs{pdfshellescape}, so we take care of this (hoping that users or
% packages don't define a \cs{shellescape} command). In any case we
% define an internal version of this command. In the case of
% \prog{luatex} we can't emit the proper messages if \prog{luatex} is
% not version 0.68 or later. The conditional
% \cs{ifKV@imki@noautomatic} is defined by \cs{define@boolkey} above.
%
%    \begin{macrocode}
\def\imki@shellwarn{}
\ifdefined\imki@shellescape % luatex
\else
  \@ifundefined{shellescape}
    {\let\imki@shellescape\pdfshellescape} % pdftex
    {\let\imki@shellescape\shellescape} % xetex
\fi
\ifnum\imki@shellescape=\z@
  \let\KV@imki@noautomaticfalse\KV@imki@noautomatictrue
  \KV@imki@noautomatictrue
  \def\imki@shellwarn{\MessageBreak or call \imki@engine\space with
    -shell-escape}
\fi
%    \end{macrocode}
% Do the same if \Kvalue{noautomatic} has been given as an option.
%    \begin{macrocode}
\ifimki@disableautomatic
  \let\KV@imki@noautomaticfalse\KV@imki@noautomatictrue
  \KV@imki@noautomatictrue
\fi
%    \end{macrocode}
%
% Now we set up the \texttt{theindex} environment. If the
% \texttt{original} option is set, we simply patch the class
% definition in order to call the macro that does the work related to
% the table of contents. Otherwise we define a new \texttt{theindex}
% environment, based on the standard, but using, if the number of
% columns is greater than one, the \texttt{multicols} environment.
% Users needing a different setup can use the \cs{indexsetup} command.
% Before doing so, though, we need to disable certain features if the
% package \pack{fancyhdr} is loaded sometimes before the
% |\begin{document| statement, be it before or after loading
% \pack{imakeidx}. If that package is loaded we have to patch the
% definition of the environment |theindex|, because its default
% commands interfere with those defined here that work perfectly
% when \pack{fancyhdr} is not loaded. This patching could be defined
% further on, but if it stay close to what has to be patched, it's
% easier to understand it's operation.
%    \begin{macrocode}
\newif\ifimki@fancyhdr
\AtBeginDocument{%
  \@ifpackageloaded{fancyhdr}{\imki@fancyhdrtrue}{\imki@fancyhdrfalse}%
  \ifimki@fancyhdr
    \patchcmd{\theindex}{\imki@indexheaders}{\relax}{}{}%
    \patchcmd{\theindex}{\thispagestyle}{\@gobble}{}{}%
  \fi
}
%     
\ifimki@original
 \expandafter\def\expandafter\theindex\expandafter{\expandafter
    \imki@maybeaddtotoc\theindex}
\else
  \global\let\imki@idxprologue\relax
  \RequirePackage{multicol}
  \renewenvironment{theindex}
    {\imki@maybeaddtotoc
     \imki@indexlevel{\indexname}\imki@indexheaders
     \thispagestyle{\imki@firstpagestyle}%
     \ifnum\imki@columns>\@ne
       \columnsep \imki@columnsep
       \ifx\imki@idxprologue\relax
         \begin{multicols}{\imki@columns}
       \else
         \begin{multicols}{\imki@columns}[\imki@idxprologue]
       \fi
     \else
       \imki@idxprologue
     \fi
     \global\let\imki@idxprologue\relax
     \parindent\z@
     \parskip\z@ \@plus .3\p@\relax
     \columnseprule \ifKV@imki@columnseprule.4\p@\else\z@\fi
     \raggedright
     \let\item\@idxitem
     \imki@othercode}
    {\ifnum\imki@columns>\@ne\end{multicols}\fi
}
\fi
%    \end{macrocode}
%
% The command \cs{indexsetup} may be used to customize some aspects of
% index formatting.
%    \begin{macrocode}
\def\imki@indexlevel{%
  \@ifundefined{chapter}{\section}{\chapter}*}
\define@key{imkiindex}{level}{\def\imki@indexlevel{#1}}
\def\imki@toclevel{%
  \@ifundefined{chapter}{section}{chapter}}
\define@key{imkiindex}{toclevel}{\def\imki@toclevel{#1}}
\define@boolkey{imkiindex}{noclearpage}[true]{\let\imki@clearpage\relax}
\def\imki@indexheaders{%
  \@mkboth{\MakeUppercase\indexname}{\MakeUppercase\indexname}}
\define@key{imkiindex}{headers}{\def\imki@indexheaders{\markboth#1}}
\def\imki@firstpagestyle{plain}
\define@key{imkiindex}{firstpagestyle}{\def\imki@firstpagestyle{#1}}
\let\imki@othercode\relax
\define@key{imkiindex}{othercode}{\def\imki@othercode{#1}}
\newcommand{\indexsetup}[1]{%
  \ifimki@original\else\setkeys{imkiindex}{#1}\fi}
\@onlypreamble\indexsetup
%    \end{macrocode}
%
% The command \cs{indexprologue} sets the internal version which is
% always \cs{let} to \cs{relax} during |\begin{theindex}|.
%    \begin{macrocode}
\newcommand{\indexprologue}[2][\bigskip]{%
  \long\gdef\imki@idxprologue{{#2\par}#1}}
%    \end{macrocode}
%
% Now we provide the relevant \cs{printindex} macros by transferring
% the real job to a secondary macro \cs{imki@putindex} after due
% checks and messages.
%    \begin{macrocode}
\providecommand*{\printindex}{}
\renewcommand*{\printindex}[1][\imki@jobname]{%
  \@ifundefined{#1@idxfile}{\imki@error{#1}}{\imki@putindex{#1}}}

\def\imki@error#1{%
  \def\@tempa{#1}\def\@tempb{\imki@jobname}%
  \ifx\@tempa\@tempb
    \let\imki@optarg\@empty
  \else
    \def\imki@optarg{[#1]}%
  \fi
  \PackageError{imakeidx}
    {Misplaced \protect\printindex\imki@optarg}
    {You are not making this index, as no appropriate
     \protect\makeindex\MessageBreak
     command has been issued in the preamble.}}
%    \end{macrocode}
%
% We define a command to do a \cs{cleardoublepage} if the option
% \Kvalue{openright} is active (in classes where \Kvalue{twoside} is
% meaningful).  In case \cs{chapter} is defined but not
% \cs{if@openright}, we assume that the class wants ``open right''.
%    \begin{macrocode}
\def\imki@clearpage{%
  \@ifundefined{chapter}
    {\clearpage} % article and similar classes
    {\@ifundefined{if@openright}
       {\cleardoublepage}
       {\if@openright
          \cleardoublepage
        \else
          \clearpage
       \fi}
    }}
%    \end{macrocode}
%
% We need a helper macro to do a check in order to avoid a loop and
% the hook where to insert the table of contents related stuff.
%    \begin{macrocode}
\def\imki@check@indexname{\indexname}
\providecommand*\imki@maybeaddtotoc{}
%    \end{macrocode}
% Two helper macros for preparing the final messages to the user.
%    \begin{macrocode}
\def\imki@finalmessage#1{%
  \expandafter\edef\csname imki@message#1\endcsname
    {\imki@program\imki@options#1.idx}
  \AtEndDocument{\PackageWarning{imakeidx}{%
    Remember to run \imki@engine\space again after calling\MessageBreak
    `\@nameuse{imki@message#1}'\imki@shellwarn\@gobble}}}
\def\imki@splitindexmessage{%
  \AtEndDocument{\PackageWarningNoLine{imakeidx}{%
    Remember to run \imki@engine\space again after calling\MessageBreak
    `splitindex' and processing the indices\imki@shellwarn}}}
%    \end{macrocode}
%
% Here is a helper macro for deciding whether to call the external
% utility or to issue a final message. In \cs{imki@makeindexname} we
% put the name of the only program allowed by default
% (\prog{makeindex}). If the list is updated, we can supplement the
% list here, maybe defining a list macro; for now this is
% sufficient. The temporary switch \cs{if@tempswa} is set to true if
% automatic processing is possible, so that the main macro can take
% the appropriate action.
%    \begin{macrocode}
\def\imki@makeindexname{makeindex}
\def\imki@decide{%
  \@tempswafalse
  \ifimki@splitindex % splitindex is not "safe"
    \ifnum\imki@shellescape=\@ne\@tempswatrue\fi
  \else
    \ifx\imki@program\imki@makeindexname % nor is texindy
      \ifnum\imki@shellescape=\tw@\@tempswatrue\fi
    \fi
    \ifnum\imki@shellescape=\@ne\@tempswatrue\fi
  \fi
  \ifKV@imki@noautomatic
    \@tempswafalse
  \fi}
%    \end{macrocode}
% We now define the main macro that puts the specified index file into
% the document and possibly orders to add the index title to the
% table of contents. It is duplicated as usual. The argument |#1| is
% the specific symbolic name of the index.  In particular if the
% \Kvalue{intoc} option has been specified, the hook
% \cs{imki@maybeaddtotoc} is defined in such a way that the relevant
% information is added to the \texttt{toc} file. The
% \cs{phantomsection} command is necessary when using \pack{hyperref};
% here it is hidden as argument to \cs{@nameuse}, so it is equivalent
% to \cs{relax} and does nothing if \pack{hyperref} has not been
% loaded.
%    \begin{macrocode}
\def\imki@putindexsplit#1{%
  \ifimki@nonewpage\else
    \imki@clearpage
  \fi
  \immediate\closeout\csname #1@idxfile\endcsname
  \let\imki@indexname\indexname % keep \indexname
  \@nameuse{imki@set@#1}\imki@decide
  \if@tempswa % we can call the external program
    \imki@exec{\imki@program\imki@options#1.idx}%
  \else
    \imki@finalmessage{#1}%
  \fi
  \ifKV@imki@intoc
    \def\imki@maybeaddtotoc{\@nameuse{phantomsection}%
      \addcontentsline{toc}{\imki@toclevel}{\imki@title}}%
  \else
    \def\imki@maybeaddtotoc{}%
  \fi
  \ifx\imki@title\imki@check@indexname\else
    \def\indexname{\imki@title}%
  \fi
  \@input@{#1.ind}
  \let\indexname\imki@indexname % restore \indexname
}

\newif\ifimki@splitdone
\def\imki@putindexunique#1{%
  \ifimki@nonewpage\else
    \imki@clearpage
  \fi
  \let\imki@indexname\indexname % keep \indexname
  \@nameuse{imki@set@#1}\imki@decide
  \if@tempswa % we can call the external program
    \ifimki@splitdone\else
      \immediate\closeout\@indexfile
      \imki@exec{splitindex \imki@splitindexoptions\space\imki@jobname.idx}%
      \global\imki@splitdonetrue
    \fi
  \else
    \ifimki@splitdone\else
      \imki@splitindexmessage\global\imki@splitdonetrue
    \fi
  \fi
  \if@tempswa % we can call the external program
    \imki@exec{\imki@program\imki@options\imki@jobname-#1.idx}%
  \fi
  \ifKV@imki@intoc
    \def\imki@maybeaddtotoc{\@nameuse{phantomsection}%
      \addcontentsline{toc}{\imki@toclevel}{\imki@title}}%
  \else
    \def\imki@maybeaddtotoc{}%
  \fi
  \ifx\imki@title\imki@check@indexname\else
    \def\indexname{\imki@title}%
  \fi
  \@input@{\imki@jobname-#1.ind}
  \let\indexname\imki@indexname % restore \indexname
}
%    \end{macrocode}
%
% ^^A F - Final decisions
%
% At this point, we choose the meaning of the relevant commands,
% reclaiming the space occupied by the discarded ones
%    \begin{macrocode}
\ifimki@splitindex
  \let\imki@startidx\imki@startidxunique
  \let\@wrindex\imki@wrindexunique
  \let\imki@putindex\imki@putindexunique
  \let\imki@wrindexentry\imki@wrindexentryunique
  \let\imki@startidxsplit\@undefined
  \let\imki@wrindexsplit\@undefined
  \let\imki@putindexsplit\@undefined
\else
  \let\imki@startidx\imki@startidxsplit
  \let\@wrindex\imki@wrindexsplit
  \let\imki@putindex\imki@putindexsplit
  \let\imki@wrindexentry\imki@wrindexentrysplit
  \let\imki@startidxunique\@undefined
  \let\imki@wrindexunique\@undefined
  \let\imki@putindexunique\@undefined
\fi
%    \end{macrocode}
% To end the code, we deal with \pack{memoir}:
%    \begin{macrocode}
\@ifclassloaded{memoir}{\let\@wrindexm@m\@wrindex
   \AtBeginDocument{\hideindexmarks}}{}
%    \end{macrocode}
%\iffalse
%</package>
%\fi
% The end.
% \Finale
