path: root/Master/texmf-dist/source/latex/splitindex/splitidx.dtx

% \CheckSum{625}
% \iffalse
% ======================================================================
% splitidx.dtx
% Copyright (c) Markus Kohm, 2002-2013
%
% $Id: splitidx.dtx,v 1.8 2013-04-04 13:59:54 mjk Exp $
%
% This file is part of the SplitIndex bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% The list of all files belongig to the SplitIndex bundle is given in
% in the file `manifest.txt'. Files generated by means of unpacking the
% distribution (using, for example, the docstrip program) or by means
% of compiling them from a source file, for example, from splitindex.c
% or splitindex.java may be distributed at the distributor's discretion.
% However if they are distributed then a copy of the SplitIndex bundle
% must be distributed together with them.
%
% The list of derived (unpacked or compiled) files belongig to the 
% distribution and covered by LPPL is defined by the unpacking scripts 
% (with extension .ins) and the installation script (with name 
% install.sh) which are part of the distribution.
%
% Two often ignorred clauses from LPPL 1.3c you should not ignore:
% ----------------------------------------------------------------
% 2. You may distribute a complete, unmodified copy of the Work as you
%    received it.  Distribution of only part of the Work is considered
%    modification of the Work, and no right to distribute such a Derived
%    Work may be assumed under the terms of this clause.
% 3. You may distribute a Compiled Work that has been generated from a
%    complete, unmodified copy of the Work as distributed under Clause 2
%    above, as long as that Compiled Work is distributed in such a way that
%    the recipients may install the Compiled Work on their system exactly
%    as it would have been installed if they generated a Compiled Work
%    directly from the Work.
% ======================================================================
%
%<*dtx>
% \fi
\ProvidesFile{splitidx.dtx}[%
% \iffalse
%</dtx>
%<driver>\ProvidesFile{splitidx.drv}[%
%<package>\ProvidesPackage{splitidx}[%
% \fi
 2013/04/04 v1.2 multiple indices for LaTeX]
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{color,alltt}
\usepackage{hypdoc}
\DeclareRobustCommand*{\Prompt}{{\color{green}\textbf{\$}}}
\DeclareRobustCommand*{\Package}[1]{\textsf{#1}}
\DeclareRobustCommand*{\Class}[1]{\textsf{#1}}
\DeclareRobustCommand*{\Program}[1]{\textsf{#1}}
\DeclareRobustCommand*{\File}[1]{\texttt{#1}}
\DeclareRobustCommand*{\Cmdline}[1]{\texttt{#1}}
\providecommand*{\url}{\texttt}
\makeatletter
\providecommand*{\Autoref}[1]{%
  \@ifundefined{hyperref}{Section~\ref{#1}}{%
    \hyperref[#1]{Section~\ref*{#1}}%
  }%
}%
\makeatother
\CodelineIndex 
\RecordChanges
\EnableCrossrefs
\GetFileInfo{splitidx.dtx} 
\title{Creating More Than One Index Using \Package{splitidx} And
  \Program{SplitIndex}\thanks{This file is version \fileversion{} of file
    \File{\filename}. Nevertheless it should be stable.}}
\author{Markus Kohm\thanks{Markus Kohm \textless komascript\textcircled{\tiny
      at}gmx.info\textgreater}\ \thanks{Many thanks to Michael Palmer who
    improved the English user manual of the \Program{SplitIndex}.}}
\date{\filedate}
\begin{document}
\maketitle
\begin{abstract}
  With \Package{makeidx}, there's a standard package in \LaTeX{} to create one
  index for each document. But sometimes more than one index is needed. There
  are different packages with different solutions and different problems to
  generate multiple indices. \Package{splitidx} implements another solution to
  this problem. In addition, \Package{splitidx} also lets you customize the
  typesetting and appearance of these indices, as well as the formatting of
  individual index entries.
\end{abstract}
\tableofcontents
\DocInput{splitidx.dtx}
\end{document}
%</driver>
% \fi
%
% \DoNotIndex{\DeclareOption,\AtEndOfPackage,\renewcommand,\g@addto@macro}
% \DoNotIndex{\renewcommand,\ProcessOptions,\relax,\newcommand,\emph}
% \DoNotIndex{\providecommand,\@bsphack,\@esphack,\@sanitize,\typeout}
% \DoNotIndex{\begingroup,\endgroup,\jobname,\ifx,\else,\fi,\expandafter}
% \DoNotIndex{\csname,\endcsname,\protected@write,\AtBeginDocument}
% \DoNotIndex{\ifHy@hyperindex,\@indexfile,\thepage,\Hy@temp@A}
% \DoNotIndex{\HyInd@ParenLeft,\HyInd@ParenRight,\string,\@ifstar,\@input@}
% \DoNotIndex{\@ifnextchar,\edef,\let,\@empty,\@for,\@tempa,\xdef,\def}
% \DoNotIndex{\catcode,\lowercase,\do,\@ifundefined,\PackageError}
% \DoNotIndex{\MessageBreak,\gdef,\@namedef,\setcounter,\@gobble.\-,\\}
% \DoNotIndex{\@onlypreamble,\@tempb,\@wrindex,\immediate,\newif,\newwrite}
% \DoNotIndex{\openout,\@gobble}
%
% \changes{v1.2}{2013/04/04}{several improvements of the user manual by
%   Michael Palmer}
%
% \section{Introduction}
% \label{sec:intro}
%
% Standard \LaTeX\ provides for only a single document index. To produce such
% an index, one usually loads \Package{makeidx} and marks up index entries in
% the document using the \cs{index} command. When the document is processed
% with \LaTeX, the \cs{index} commands from the document are written as
% \cs{indexentry} commands to the raw index file
% ``\File{\cs{jobname}.idx}''. The raw index file is then processed with
% \Program{MakeIndex} or another auxiliary program like \Program{xindy}, which
% will produce a sorted index file named ``\File{\cs{jobname}.ind}''. This
% file is then included at the end of the document using the \cs{printindex}
% command.\footnote{For further details, read \protect\cite{makeindex} and
% e.g.\ \protect\cite{makeindexmanual}.}
%
% The \Package{splitidx} package extends this process to permit the creation
% of multiple indices. Separate indices are declared and given unique shortcut
% identifiers with the \cs{newindex} command. In the document, individual
% index entries are marked up and assigned to specific indices with the
% \cs{sindex} command. For each of the declared indices, a separate
% \File{.idx} file is generated, each of which is post-processed into a
% separate \File{.ind} file. These \File{.ind} files are then included in the
% document using a modified version of the \cs{printindex} command.
%
% The process outlined thus far resembles that of other multi-index packages
% such as \Package{multind}. The most straightforward way to implement this
% scheme, which is the one used by package \Package{multind} and others, is to
% directly write a separate \File{.idx} file for each declared index when
% processing the document with \LaTeX, and then to separately post-process
% each \File{.idx} file with \Program{MakeIndex}. However, this approach can
% run into technical limitations. \TeX{} can have no more than 16 files open
% for writing at any one time. Several of these file handles are required by
% \LaTeX{} itself for other purposes, such as cross references, the table of
% contents, and possibly others, depending on the structure of your
% document. Therefore, if you need a large number of separate indices, the
% limited number of available file handles may become a problem. The
% \Package{splitidx} package provides a solution to this problem.
%
% If the number of indices can be accommodated within the number of available
% file handles, you can use \Package{splitidx} with the package option
% \texttt{split}. Then, \Package{splitidx} will directly write multiple raw
% index files, that is, it will behave according to the scheme just
% described. On the other hand, if the number of indices exceeds the number of
% available file handles, you can request \Package{splitidx} to write all
% index entries to a single intermediate index file, which must then be
% post-processed in order to obtain the separate raw index files. The
% post-processing of the intermediate file is done with the
% \Program{SplitIndex} program, which exists in several different
% implementations (see below). This behavior of \Package{splitidx} is
% activated by omitting option \texttt{split}, that is, it is the package's
% default behavior.
%
% In addition to the construction of separate indices, \Package{splitidx} also
% offers help with customizing the typesetting and appearance of these
% indices, as well as the formatting of individual index entries.
%
%
% \section{The \protect\Program{SplitIndex} program}
% \label{sec:splitindex.program}
%
% \subsection{Purpose}
%
% While the number of files \TeX{} can open for writing is limited, using
% multiple indices is normally limited too. As already mentioned in
% \autoref{sec:intro} this limitation may be neutralized using a single
% intermediate index file, that will be split into several raw index files by
% an external post-processor: \Program{SplitIndex}.
%
%
% \subsection{Implementation}
%
% The program has been implemented in five different languages, as follows:
%
% \begin{description}
% \item[\Program{splitindex.pl}] This is written in perl. You need a perl
%   interpreter to run it. If you are a Unix user, you have a perl interpreter
%   and you can call \Program{splitindex.pl} like you would call a binary
%   program or a shell script from your shell. This is the reference
%   implementation. I prefer to use this, because it was the first, the
%   easiest and the shortest to be written.
% \item[\Program{splitindex.java}] This is written using Sun Java~1.4.1. I
%   wrote it because Java is everywhere and may be installed everywhere and a
%   lot of people are able to understand Java source files. Nevertheless
%   There's no longer a precompiled version of this in the main distribution.
%   But you may download it from the repository at
%   \url{http://sarovar.org/plugins/scmcvs/cvsweb.php/binaries/?cvsroot=splitindex}
% \item[\Program{splitindex.c}:] This is a C source of \Program{splitindex}.
%   I wrote the
%   C version because a lot of people like to have a binary and most software
%   authors understand C, and some people want fast binaries instead of slow
%   Java byte code\,---\,even, if the Java program is fast
%   enough. Nevertheless, there are no longer binaries of generated from this
%   source in the main distribution. But you may download some from the
%   repository at
%   \url{http://sarovar.org/plugins/scmcvs/cvsweb.php/binaries/?cvsroot=splitindex}
% \item[\Program{splitindex.tex}:] This is a \TeX{} version of the
%   program. Yes, you are right: it is a program written in \TeX{}. It has not
%   the whole functionality of the other programs (see \autoref{TeX}), but
%   it is system-independent and you don't need to install any other program
%   like perl or Sun Java 1.4. It is not impossible to fix all the
%   disadvantages of this program\,---\,but it isn't easy and much more work
%   than all the other programs.
% \changes{v1.2}{2013/04/04}{new \TeX Lua implementation of
%   \Program{SplitIndex}}
% \item[\Program{splitindex.tlu}:] This is a new \TeX Lua version of the
%   program. It is platform independent like the perl script. Note, that the
%   syntax for regular expressions in Lua differs from the perl syntax, if you
%   use it instead of the perl version. Distributors should prefere the perl
%   version, if they also provide perl for the installation platform.
% \end{description}
% With the exception of the \TeX{} version, all of these programs are also
% able to call the index processor on each of the resulting raw index files.
%
% And where is the lisp, the smalltalk, the prolog, the \dots{} version of
% \Program{splitindex}? Hey, five languages are enough for me! If you need one
% more, write it!
%
%
% \section{Using the \Package{splitidx} package}
% \label{package}
%
% \subsection{Setup}
%
% You can use \Package{splitidx} as a drop-in-replacement for
% \Package{makeidx}. If you do so, you just have to replace
% \begin{verbatim}
%   \usepackage{makeidx}
% \end{verbatim}\vspace{-\baselineskip}
% by
% \begin{verbatim}
%   \usepackage{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
%
% \DescribeMacro{\makeindex}
% To activate index generation, you can use \cs{makeindex}, which is declared
% by the \LaTeX{} kernel.
% You can also load the package with the option
% \texttt{makeindex}:
% \begin{verbatim}
%   \usepackage[makeindex]{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
% which is almost the same like:
% \begin{verbatim}
%   \usepackage{splitidx}\makeindex
% \end{verbatim}\vspace{-\baselineskip}
%
% Other package options are available. The effect of the \texttt{split} option
% was already described in \autoref{sec:intro}; further options are
% discussed below.
%
% \DescribeMacro{\newindex}
% If you want to generate more than one index without shortcut, you should
% declare this using \cs{newindex} with syntax:
% \begin{quote}
%   \cs{newindex}\oarg{index name}\marg{shortcut}.
% \end{quote}
% The mandatory argument \meta{shortcut} is used to distinguish the different
% indices. See description of \cs{sindex} for more information about this. The
% optional argument \meta{index name} is the name of the index. This is also
% the default heading of this index used by the macros \cs{printindex} and
% \cs{printsubindex} (see below). If you omit \meta{index name}, the shortcut 
% will be used as index name.
%
% While it is always good practice to declare all index explicitly in the
% preamble of the document, this \emph{must} be done if you also use the
% package option \texttt{split}. In this case, the \cs{newindex} command opens
% a raw index file to write to for each declared index. As the only exception,
% the raw index file for the index entries with the default shortcut
% (\texttt{idx}) will be created automatically. As noted above, the number of
% index files that you can create in this way is limited, which is due to the
% limited number of output streams provided by \TeX{}. If you exceed this
% number, not only the \cs{newindex} macro itself may result in an error, but
% also \cs{tableofcontents}, \cs{listoffigures}, \cs{listoftables} and any
% other command that implicitly allocates an output stream.
%
% A unique shortcut declared with \cs{newindex} to refer to a specific
% index becomes part of the filenames of the corresponding \File{.idx} and
% \File{.ind} files. Therefore, when you choose a shortcut, make sure that you
% only use characters or symbols in the \meta{shortcut} that are allowed in
% filenames. On file systems that treat file names as case-insensitive, you
% should not mix uppercase and lowercase letters. For maximum portability and
% minimum hassle, it is best to always use only lowercase letters.
% 
% \subsection{Marking up index entries}
%
% \DescribeMacro{\index}%^^A
% After loading the \Package{splitidx} package, you may use the \cs{index}
% command to mark up index entries in your manuscript as usual. You can find
% the description of the argument and features of this command in reference
% \cite{makeindex}. The \Program{splitindex} program (see
% \autoref{program}) will put all index entries that were produced with
% \cs{index} into the same raw index file, which is tagged with the unique
% shortcut ``\texttt{idx}''; that is, the \cs{index} command does \emph{not}
% allow you to assign index entries to separate indices. However, the
% \texttt{useindex} option allows you to change this behavior; this is
% discussed below.
%
% \DescribeMacro{\sindex}%^^A
% The \Package{splitidx} package also defines the command \cs{sindex} with the
% syntax:
% \begin{quote}
%   \cs{sindex}\oarg{shortcut}\marg{index-entry}
% \end{quote}
% The \cs{sindex} command is \Package{splitidx}' mechanism for placing
% individual index entries into specific indices. The target index is
% identified by passing its unique shortcut, as declared with \cs{newindex},
% in the optional argument to \cs{sindex}. If not given, the shortcut defaults
% to ``\texttt{idx}'', which should therefore be used to identify some sort of
% general index.
%
% If you like, you may also request that \cs{index} should be an alias 
% for \cs{sindex}. To do so, you use the package
% option \texttt{useindex}, e.g.:
% \begin{verbatim}
%   \usepackage[useindex]{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
% This may be useful when using packages like \textsf{jurabib} that expect
% \cs{index} to be the index command.
%
% \subsection{Suppressing multiple index generation}
%
% Under some unfortunate circumstances, for example when working with a
% publisher that enforces a rigid document format, it may be necessary to
% merge the separate indices back into a single index. In this case, it is
% \emph{not} necessary to strip out all the individually marked up index
% identifiers. Instead, you may load the \Package{splitidx} package with the
% \texttt{allintoone} option:
%
% \begin{verbatim}
%   \usepackage[allintoone]{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
% or
% \begin{verbatim}
%   \usepackage[allintoone,makeindex]{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
% With this option, \Package{splitidx} will do the stripping for you, that is,
% \cs{sindex}\oarg{shortcut}\linebreak[1]\marg{indexentry} will be substituted
% with \cs{index}\marg{indexentry} during \LaTeX\ processing.
%
% \emph{Note: Currently only one of the options \texttt{allintoone} and
%   \texttt{useindex} can be used at same time. If you try to use both,
%   \texttt{useindex} will be disabled! This may result in many error
%   messages!}
%
% \subsection{Customizing index entries}
%
% \DescribeMacro{\AtWriteToIndex}%^^A
% \Package{splitidx} uses \cs{protected@write} to write the index entries to
% its output files. The \cs{AtWriteToIndex} macro lets you execute a piece of
% code each time an index is written to a specific index. Usage:
% \begin{quote}
%   \cs{AtWriteToIndex}\marg{shortcut}\marg{code}
% \end{quote}
% This may be useful if you want your index entries to reference not the page
% number but some other counter instead. For example, in order to make each
% index entry in the general index (identified by the \texttt{idx} shortcut)
% point to the corresponding section number, you would write
% \begin{verbatim}
%   \AtWriteToIndex{idx}{\let\thepage\thesection}
% \end{verbatim}
% Note that this will work only if the shortcut of the index is given
% explicitly in each marked-up index entry; for example,
% \begin{verbatim}
% \sindex[idx]{Roller blades}
% \end{verbatim}\vspace{-\baselineskip}
% instead of 
% \begin{verbatim}
% \sindex{Roller blades}
% \end{verbatim}\vspace{-\baselineskip}
% Note, if you want to use command \cs{index} instead of \cs{sindex}, you
% should also use the package option \texttt{useindex}; without it, command
% \cs{index} will still write the page number to the index.
%
% The \cs{AtWriteToIndex} command may be used only in the document preamble.
%
% \DescribeMacro{\AtNextWriteToIndex}%^^A
% Sometimes it may be useful to execute some commands only for writing a
% single index entry. To do so, you may use
% \begin{quote} 
% \cs{AtNextWriteToIndex}\marg{shortcut}\marg{commands} 
% \end{quote} 
% instead of \cs{AtWriteToIndex}.
%
%\subsection{Automatic custom index commands}
%
% Some people do not like to write \cs{sindex[foo]}\marg{entry}. They want to
% write \cs{foo}\marg{entry}. For these people, the package option
% `\texttt{idxcommands}' has been implemented. This option defines a command
% with the name of the \meta{shortcut} for each declared index. If you use
% this option, you'll get an error if a command with this name is already
% defined.  Also note that if you are using this option, the characters of the
% shortcuts must be letters.
%
% \subsection{Preventing premature expansion of index entries}
%
% \DescribeMacro{\newprotectedindex}%^^A
% When using the standard index package \textsf{makeidx}, the \LaTeX{} kernel
% command \cs{index} may expand its argument. The kernel uses \cs{@sanitize}
% to avoid expansion in some cases. But this fails if the argument was already
% read by another macro. So if you define a macro that reads its argument,
% does something with it and then writes it to the index, this may expand the
% argument. For illustration, try the following:
% \begin{verbatim}
%  \documentclass{article}
%  \usepackage{ngerman}
%  \usepackage{makeidx}\makeindex
%  \newcommand*{\Test}[1]{#1\index{#1}}
%  \begin{document}
%  \Test{"Anderung}
%  "Anderung\index{"Anderung}
%  \end{document}
% \end{verbatim}\vspace{-\baselineskip}
% This will result in two entries in the \texttt{.idx} file:
% \begin{verbatim}
%   \indexentry{\active@dq  \dq@prtct{A}nderung}{1}
%   \indexentry{"Anderung}{1}
% \end{verbatim}\vspace{-\baselineskip}
% The first one is something expanded that is not wanted. Package
% \textsf{splitindx} behaves the same way by default. But if you use
% \cs{newprotectedindex} to define a new index, it uses a trick to avoid
% expansion. If all indices should behave like this, you may simply use the
% package option \texttt{protected}.
% \begin{verbatim}
%  \documentclass{article}
%  \usepackage{ngerman}
%  \usepackage[protected,useindex,makeindex]{makeidx}
%  \newcommand*{\Test}[1]{#1\index{#1}}
%  \begin{document}
%  \Test{"Anderung}
%  "Anderung\index{"Anderung}
%  \end{document}
% \end{verbatim}\vspace{-\baselineskip}
% Will result in two entries at the \texttt{.idx} file:
% \begin{verbatim}
%   \indexentry{"Anderung}{1}
%   \indexentry{"Anderung}{1}
% \end{verbatim}\vspace{-\baselineskip}
% If you want to know more about the trick, see the command
% \cs{@onelevel@sanitize} in the \LaTeX{} kernel documentation,
% \texttt{source2e}.
%
% \subsection{Including the generated indices in your document}
%
% \DescribeMacro{\printindex}%^^A
% \changes{v0.2a}{2003/01/05}{fix of documentation bug}%^^A
% The \cs{printindex} command is used to print one index or all indices that
% are declared using \cs{newindex}. How it behaves depends on the syntax you
% are using.
%
% Used like this:
% \begin{quote}
%   \cs{printindex}\oarg{shortcut}\oarg{index name}
% \end{quote}
% the index file with the optional shortcut will be included and printed, with
% the optional \meta{index name} being used as the title. If \meta{index name}
% is omitted, the default index name declared with \cs{newindex} will be used
% instead. If this name was omitted as well, the shortcut itself will be used
% as the title.
%
% If both optional arguments, \meta{shortcut} and \meta{index name}, are
% omitted, and you are using simply
% \begin{quote}
%   \cs{printindex}
% \end{quote}
% this command behaves like \cs{printindex} from package
% \Package{makeidx}. You should not use this if you are using multiple
% indices.
%
% You may also print all indices that were declared using \cs{newindex} at
% once. Use the syntax:
% \begin{quote}
%   \cs{printindex*}
% \end{quote}
% to do so. The indices will be printed in the order you declared them using
% \cs{newindex}.
%
% \subsection{Typesetting the generated indices}
%
% \cs{printindex} uses the default index output of the class and the index
% processor you are using. Usually, this will be \texttt{theindex}
% environment, but it doesn't have to be this way. Note, however, that
% \cs{printindex} expects the name of the index to be contained in the
% \cs{indexname} macro; otherwise, it will fail to typeset the index
% name.\footnote{This would be a failure of the class, not of the
% \Package{splitidx} package. I don't know of any class with this failure.}
%
% \DescribeMacro{\printsubindex}%^^A
% The \cs{printsubindex} command is analogous to \cs{printindex}, but it
% performs some redefinitions before printing the index, as follows:
% \begin{itemize}
% \item demote the index heading level by 1, that is, format the index title
%   using \cs{section*} instead of \cs{chapter*} with classes that define
%   \cs{chapter} (such as \texttt{book} and \texttt{report}), and using
%   \cs{subsection*} instead of \cs{section*} with classes that don't define
%   \cs{chapter} (such as \texttt{article});
% \item deactivate \cs{onecolumn}, \cs{twocolumn} and \cs{clearpage},
%   \cs{cleardoublepage} that are otherwise used to start a new page in each
%   index,
% \item change the mark mechanism to use \cs{markright} instead of
%   \cs{markboth} for setting up the running headers.
% \end{itemize}
% Using this macro, you can print multiple indices in one chapter, if you are
% using a class with \cs{chapter}, or in one section, if you are using a class
% without \cs{chapter}.
%
%
% \DescribeMacro{\setindexpreamble}%^^A
% If you are using a KOMA-Script class, you'll know this command. Package
% \Package{splitidx} redefines this command as follows:
% \begin{quote}
%   \cs{setindexpreamble}\oarg{shortcut}\marg{preamble}
% \end{quote}
% This allows you to define a separate preamble for each index. Note: Package
% \Package{splitidx} doesn't print the preamble itself. Instead, before
% typesetting an index with a given shortcut using \cs{printindex} or
% \cs{printsubindex}, it assigns the user-defined preamble for this shortcut
% to the internal macro \cs{index@preamble}. At the user level, its value can
% be accessed with the \cs{useindexpreamble} macro (see below).
%
% \DescribeMacro{\useindexpreamble}%^^A
% If you are defining your own index environment or if you extend the existing
% \texttt{theindex} environment using \cs{extendtheindex} or otherwise, you
% can use \cs{useindexpreamble} to retrieve the preamble previously defined
% for the current index using \cs{setindexpreamble}:
% \begin{quote}
% \cs{useindexpreamble}\oarg{additional commands}
% \end{quote}
% This macro is not limited to the KOMA-Script classes; it can also be used
% e.g.\ with the standard classes. The commands passed in the optional
% argument \meta{additional commands} are only used if the preamble for the
% current index is defined and not empty. Authors of wrapper classes may use
% this, e.g.\ to add additional vertical spaces after the index preamble if
% and only if an index preamble will be printed.
%
% \DescribeMacro{\indexshortcut}%^^A
% The macro \cs{indexshortcut} is only defined within the body of
% \cs{printindex} and \cs{printsubindex}. It expands to the shortcut of the
% specific index that is being printed. It may be useful when defining your
% own index environment or extending the \texttt{theindex} environment using
% e.g.\ \cs{extendtheindex}.
%
%
% \DescribeMacro{\extendtheindex}%^^A
% Most classes define the environment \texttt{theindex} to be used for
% printing the index. Using \cs{extendtheindex} with this syntax:
% \begin{quote}
% \cs{extendtheindex}\marg{before begin}\marg{after begin}^^A
% \marg{before end}\mbox{\marg{after end}}
% \end{quote}
% you may extend this environment. The commands passed in \meta{before begin}
% are inserted in \cs{begin\{theindex\}} just after starting the group but
% before the existing code defined for this code block. The commands passed in
% \meta{after begin} are inserted after \cs{begin\{theindex\}}. Analogously,
% the commands passed in \meta{before end} are inserted before
% \cs{end\{theindex\}}, while those passed in \meta{after end} are used within
% \cs{end\{theindex\}} just after ending the index but just before ending the
% group.
%
%
% \subsection{Examples}
% \label{examples}
%
% Let's see how you may get more than one index. The text of the example is
% silly, so don't think about the text, think about the usage of
% \Package{splitidx}.
%
% \begin{flushleft}\ttfamily
% \cs{documentclass}\{article\} \percentchar \textit{ We use \Class{article}
%   class \dots}\\
% \cs{usepackage}\{splitidx\} \percentchar \textit{ \dots\ and the
%   \Package{splitidx} package}\\
% \cs{makeindex} \percentchar \textit{ And we want index generation}\\
% ~\\
% \percentchar \textit{ We define 4 indices:}\\
% \cs{newindex}[General Index]\{idx\} \percentchar \textit{ Name and shortcut
%   of the 1st index}\\
% \cs{newindex}[Index of Animals]\{ani\} \percentchar \textit{ \dots\ 2nd
%   index}\\
% \cs{newindex}[Index of Fruits]\{fru\} \percentchar \textit{ \dots\ 3rd
%   index}\\ 
% \cs{newindex}[Index of Vegetables]\{veg\} \percentchar \textit{ \dots\ 4th
%   index}\\
% ~\\
% \cs{begin}\{document\}\\
% Apples\cs{sindex}[fru]\{apple\} \percentchar \textit{ an entry to
%   }fru\texttt{ index}\\
% and oranges\cs{sindex}[fru]\{orange\} \percentchar \textit{ an entry to
%   }fru\texttt{ index}\\
% are fruits\cs{sindex}\{fruits\}.\ \percentchar \textit{ an implicit entry
% to }idx\textit{ index}\\
% Tomatoes\cs{sindex}[veg]\{tomato\} \percentchar \textit{ an entry to
% }veg\textit{ index}\\
% are\\
% vegetables\cs{index}\{vegetables\}.\ \percentchar \textit{ an implicit
%   entry to }idx\textit{ index}\\
% Cats\cs{sindex}[ani]\{cat\} \percentchar \textit{ an entry to
% }ani\textit{ index}\\
% are animals\cs{sindex}[idx]\{animals\}.\ \percentchar \textit{ an explicite
%   entry to }idx\textit{ index}\\
% ~\\
% \cs{printindex*} \percentchar \textit{ print all indices}\\
% \cs{end}\{document\}
% \end{flushleft}
% After processing the file above with \LaTeX{} you'll get a raw index file
% with following contents:
% \begin{verbatim}
% \indexentry[fru]{apple}{1}
% \indexentry[fru]{orange}{1}
% \indexentry{fruits}{1}
% \indexentry[veg]{tomato}{1}
% \indexentry{vegetables}{1}
% \indexentry[ani]{cat}{1}
% \indexentry[idx]{animals}{1}
% \end{verbatim}\vspace{-\baselineskip}
% \Autoref{program} explains how to convert this intermediate file into
% separate raw index files and index files. In the above example, all four
% index files are input with a single \cs{printindex*} command. Each file will
% produce a single section that start on a new page. The section headings
% ``General Index'', ``Index of Animals'', ``Index of Fruits'' and ``Index of
% Vegetables'' will be printed in onecolumn mode, followed by the index
% entries printed in twocolumn mode.
%
% Maybe you would like to format all indices as subsections within one
% section. You can do this by replacing the \cs{printindex*} command in the
% example above with the following:
% \begin{flushleft}\ttfamily
% \cs{twocolumn}[\percentchar\textit{ set the title onecolumn}\\
% \ \cs{section*}\{Indices\} \percentchar\textit{ the section with the
% indices}\percentchar\\
% \ \cs{markboth}\{Indices\}\{Indices\} \percentchar\textit{ setting up the
% running headline }\percentchar\\
% ]\percentchar\textit{ but the indices twocolumn}\\
% \cs{printsubindex*} \percentchar\textit{ print all indices}
% \end{flushleft}
% Note that I've used \cs{printsubindex*} instead of \cs{printindex*} in this
% modified example.
%
% We now turn to the running headers for the index pages. If you are using
% page style \texttt{plain}, which is default at \Class{article} class, the
% running headers are empty, so you don't need to set them up. However, if
% you're using page style \texttt{headings} for your index pages and the
% \cs{section*} command to format the headings of the several indices, you
% should set up the running headers to match the current index titles. If you
% are using a KOMA-Script class, you can use \cs{addsec} or \cs{addsec*}
% instead of \cs{section*} to format the index titles, in which case you will
% not need to manually update the running headers.
%
% Maybe you want the general index to be the section, while the other indices
% should be subsections of the general index. You might then try to replace
% the code above with the following:
% \begin{flushleft}\ttfamily
% \percentchar\textit{\#\#\#\#\# This will not do the thing you wanted!
%   \#\#\#\#\#}\\
% \cs{printindex}[idx] \percentchar\textit{ print index }idx\textit{ as
%   section}\\
% \cs{printsubindex}[ani] \percentchar\textit{ print index }ani\textit{ as
%   subsection}\\
% \cs{printsubindex}[fru] \percentchar\textit{ print index }fru\textit{ as
%   subsection}\\
% \cs{printsubindex}[veg] \percentchar\textit{ print index }veg\textit{ as
%   subsection}\\
% \end{flushleft}
% But this will result in a twocolumn section containing the general index
% (identified by \texttt{idx}) and three onecolumn subsections containing the
% other indices, and a page break after the general index. Why is this?
% \LaTeX\ will switch to twocolumn mode as it enters the \texttt{theindex}
% environment (which is created by the \cs{printindex} command) and will
% revert to onecolumn mode when it exits \texttt{theindex}. If twocolumn mode
% was active before \cs{printindex}, a \cs{clearpage} command will be issued
% at the end of \texttt{theindex}. So what's the solution? Remembering the
% \cs{extendtheindex} command, you can write:
% \begin{flushleft}\ttfamily
%   \cs{begingroup} \percentchar\textit{ keep the following extension local to
%   this
%   group}\\
%   \ \cs{extendtheindex}\percentchar \textit{ some changes of
% }theindex\textit{ environment}\\
%   \ \ \{\}\percentchar\textit{ no change before beginning}\\
%   \ \ \{\}\percentchar\textit{ no change after beginning}\\
%   \ \ \{\cs{let}\cs{onecolumn}\cs{relax} \percentchar\textit{ deactivate
%   \cs{onecolumn} before ending}\\
%   \ \ \ \cs{let}\cs{clearpage}\cs{relax} \percentchar\textit{ deactivate
%   \cs{clearpage} before ending}\\
%   \ \ \}\percentchar \textit{ changes before ending}\\
%   \ \ \{\}\percentchar\textit{ no change after ending}\\
%   \ \cs{printindex}[idx] \percentchar\textit{ print index }idx\textit{ as
%   section}\\
%   \cs{endgroup} \percentchar\textit{ end group with extended
% }theindex\textit{
%   environment}\\
%   \cs{printsubindex}[ani] \percentchar\textit{ print index }ani\textit{ as
%   subsection}\\
%   \cs{printsubindex}[fru] \percentchar\textit{ print index }fru\textit{ as
%   subsection}\\
%   \cs{printsubindex}[veg] \percentchar\textit{ print index }veg\textit{ as
%   subsection}\\
%   \cs{onecolumn} \percentchar\textit{ finish the indices}
% \end{flushleft}
% With this extension, the whole index will be set in twocolumn mode, with no
% page break before the first subsection. However, you have to switch back to
% onecolumn mode manually at the end of the indices.
%
% The example above may be modified as follows to obtain a onecolumn index:
% \begin{flushleft}\ttfamily
% \cs{begingroup} \percentchar\textit{ hold following extension local to this
%   group}\\
% \ \cs{makeatletter} \percentchar\textit{ allow }@\textit{ at macro names}\\
% \ \cs{extendtheindex}\percentchar \textit{ some changes of
%   }theindex\textit{ environment}\\
% \ \ \{\cs{let}\cs{twocolumn}\cs{@firstoptofone} \percentchar\textit{
%   deactivate \cs{twocolumn}}\\
% \ \ \ \cs{let}\cs{onecolumn}\cs{@firstoptofone} \percentchar\textit{
%   deactivate \cs{twocolumn}}\\
% \ \ \ \cs{let}\cs{clearpage}\cs{relax} \percentchar\textit{ deactivate
%   \cs{clearpage}}\\
% \ \ \}\percentchar \textit{ changes before beginning}\\ 
% \ \ \{\}\percentchar\textit{ no change after beginning}\\
% \ \ \{\}\percentchar\textit{ no change before ending}\\
% \ \ \{\}\percentchar\textit{ no change after ending}\\
% \ \cs{makeatother} \percentchar\textit{ deactivate \cs{makeatletter}}\\
% \ \cs{printindex} \percentchar\textit{ print index}\\
% \cs{endgroup} \percentchar\textit{ end group with extended }theindex\textit{
%   environment}
% \end{flushleft}
% This not only works with splitted indices but also with one
% single index.
%
% I hope that these examples were useful to understand how to format indices
% using \Package{splitidx}. The next section will show you how to generate
% separate indices from a single intermediate index file.
%
%
% \subsection{Splitting intermediate index files}
% \label{program}
% 
% Most commonly, it will be sufficient to call one of the \Program{splitindex}
% programs with one parameter, the name of the intermediate index file. This
% will split the intermediate file into several raw index files, and then call
% \Program{MakeIndex} on each of these. The program \Program{splitindex} can
% be instructed to use another index processor such as \Program{xindy}, or to
% pass additional options along to the index processor, e.g.\ ``\Cmdline{-g}''
% to use German sorting with \Program{MakeIndex}. While it may be a rare need,
% it is also possible to modify the parsing of the intermediate index file and
% the generation of the filenames and contents of the resulting raw index
% files.
%
% The names of the options and the syntax of the Arguments is same at all of
% the programs except \Program{splitindex.tex} (see
% \autoref{TeX}): \begin{description}\setlength{\labelsep}{1em}
% \item[\texttt{--help}]
% \item[{\makebox[1.2em][l]{\texttt{-h}}}]\vspace{-2\itemsep}
%   Show information about usage, options and arguments and terminate without
%   processing an index file.
% \item[\texttt{--makeindex} \meta{program name}]~
% \item[\texttt{-m} \meta{program name}]\vspace{-2\itemsep}
%   Call \meta{program name}
%   instead of \Program{makeindex} to process each generated raw index
%   file. You may set this variable to an empty value. How this may be done
%   depends on the shell, which you are using. Using bash you may achieve an
%   empty value using \texttt{""} or \texttt{''}. An empty value means that
%   no index processor will be called on the generated raw index files. 
% \item[\texttt{--identify} \meta{regular expression}]~
% \item[\texttt{-i} \meta{regular expression}]\vspace{-2\itemsep} Uses
%   \meta{regular expression} to identify the index shortcut and the contents
%   of the raw index file with this shortcut in the intermediate file. The
%   default value is: ``\verb|^(\\indexentry)\[([^]]*)\](.*)$|'' for all but
%   \Program{splitindex.tlu}. This means:
%   \begin{description}
%   \item[{\makebox[1em][l]{\texttt{\textasciicircum}}}]
%     Search from beginning of the line.
%   \item[\texttt{(\string\\indexentry)}]~\par 
%     Search for ``\verb|\indexentry|'' and
%     set group 1 to this.
%   \item[{\makebox[1em][l]{\texttt{\string\[}}}]
%     Search for ``\verb|[|'' and ignore it.
%   \item[\texttt{([\textasciicircum]]*)}]~\par
%     Search for any character which is not ``]'' and set group 2 to this.
%   \item[{\makebox[1em][l]{\texttt{\string\]}}}]
%     Search for ``\verb|]|'' and ignore it.
%   \item[\texttt{(.*)\$}]~\par
%     Search for all characters till end of line and set group 3 to these.
%   \end{description}
%   The \meta{regular expression} is POSIX~1003.2 compatible.
%   For \Program{splitindex.tlu} the default is:
%   ``\verb|^(\\indexentry)%[([^]]*)%](.*)$|''.
% \item[\texttt{--resultis} \meta{pattern}]~
% \item[\texttt{-r} \meta{pattern}]\vspace{-2\itemsep} Set the lines, which
%   are written to the generated raw index files after identification (see
%   option \texttt{--identify}) to \meta{pattern}. Each
%   \texttt{\$}\meta{digit} at \meta{pattern} will be replaced by the
%   corresponding group, e.g. \verb|$1| will be replaced by the first group
%   (see \texttt{--identify}). The default is: ``\verb|$1$3|'' for all but
%   \Program{splitindex.tlu} resp. ``\verb|%1%3|'' for
%   \Program{splitindex.tlu}, which means: contents of group 1 and group 3.
%
%   If the \meta{regular expression} of option \texttt{--identify} doesn't
%   match a line at the raw index file the line itself will be written.
% \item[\texttt{--suffixis} \meta{pattern}]~
% \item[\texttt{-s} \meta{pattern}]\vspace{-2\itemsep} Set the suffix of the
%   names of the generated raw index files after identification (see option
%   \texttt{--identify}) to \meta{pattern}. Each \texttt{\$}\meta{digit} at
%   \meta{pattern} will be replaced by the corresponding group, e.g. \verb|$1|
%   will be replaced by the first group (see \texttt{--identify}). The default
%   is: ``\verb|-$2|'' resp. ``\verb|-%2|'', which means:
%   character `\texttt{-}' followed by contents of group 2.
%
%   If the \meta{regular expression} of option \texttt{--identify} doesn't
%   match a line at the raw index file, all groups will be set to
%   ``\texttt{idx}''.
% \item[\texttt{--verbose}]
% \item[{\makebox[1.2em][l]{\texttt{-v}}}]\vspace{-2\itemsep}
%   Increase verbosity by one. More verbose means: tell the user more about,
%   what the program is doing.
% \item[\texttt{--version}]
% \item[{\makebox[1.2em][l]{\texttt{-V}}}]\vspace{-2\itemsep}
%   Show information about program version and terminate without processing a
%   index file.
% \end{description}
%
% Some of the binaries compiled from the C source won't understand the long
% option names (\texttt{--makeindex}, \texttt{--identify} \dots). In this case
% you'd have to use the alternative short option names (\texttt{-m},
% \texttt{-i} \dots).
%
% The first non-option-argument in the command line is used  as the name of the 
% intermediate index file to be processed. All arguments that follow the
% argument ``\texttt{--}'' are interpreted as non-option arguments. All but
% the first non-option-arguments will be passed to the index processor.
%
% You will find some examples in the following subsections.
%
%
% \subsection{Using \Program{splitindex.pl}}
% \label{perl}
%
% This is the reference implementation. Let's use an example to demonstrate
% its use.  If you have the following \LaTeX{} file ``\File{allabout.tex}'':
% \begin{verbatim}
%  \documentclass{article}
%  \usepackage[makeindex]{splitidx}
%  \begin{document}
%    Apples\sindex[fru]{apple} and oranges\sindex[fru]{orange} are 
%    fruits\sindex{fruits}.
%    Tomatos\sindex[veg]{tomato} are vegetables\sindex{vegetables}.
%    Cats\sindex[ani]{cat} are animals\sindex[idx]{animals}.
%  \end{document}
% \end{verbatim}\vspace{-\baselineskip}
% this generates the intermediate index file ``File{allabout.idx}'':
% \begin{verbatim}
%  \indexentry[fru]{apple}{1}
%  \indexentry[fru]{orange}{1}
%  \indexentry{fruits}{1}
%  \indexentry[veg]{tomato}{1}
%  \indexentry{vegetables}{1}
%  \indexentry[ani]{cat}{1}
%  \indexentry[idx]{animals}{1}
% \end{verbatim}\vspace{-\baselineskip}
% 
% This file can't be processed by an index processor like
% \Program{MakeIndex}. In order to split this intermediate file into several
% raw index files and run the default index processor, you do the following
% call (the \Prompt{} is a symbol for the shell prompt):
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl allabout.idx|
% \end{quote}
% You may omit the extension ``\File{.idx}'':
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl allabout|
% \end{quote}
% Both commands will result in a file \File{allabout-fru.idx}:
% \begin{verbatim}
%  \indexentry[fru]{apple}{1}
%  \indexentry[fru]{orange}{1}
% \end{verbatim}\vspace{-\baselineskip}
% a file \File{allabout-idx.idx}
% \begin{verbatim}
%  \indexentry{fruits}{1}
%  \indexentry{vegetables}{1}
%  \indexentry{animals}
% \end{verbatim}\vspace{-\baselineskip}
% a file \File{allabout-veg.idx}:
% \begin{verbatim}
%  \indexentry[veg]{tomato}{1}
% \end{verbatim}\vspace{-\baselineskip}
% and a file \File{allabout-ani.idx}:
% \begin{verbatim}
%  \indexentry[ani]{cat}{1}
% \end{verbatim}\vspace{-\baselineskip}
% After generation of these files, it calls the default index processor using
% the command lines:
% \begin{verbatim}
%  makeindex allabout-fru.idx
%  makeindex allabout-idx.odx
%  makeindex allabout-veg.idx
%  makeindex allabout-ani.idx
% \end{verbatim}\vspace{-\baselineskip}
% \begin{sloppypar}\noindent
% These calls create the index files \File{allabout-fru.ind},
% \File{allabout-idx.ind}, \File{allabout-veg.ind} and
% \File{allabout-ani.ind}, which can be loaded into the document using
% e.g.\ \cs{printindex} from package \Package{splitidx}.
% \end{sloppypar}
%
% If you don't want \Program{splitindex} to call any index processor, use
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl -m "" allabout|
% \end{quote}
% instead of the shell command above.
%
% You may obtain the same files as above using (it's one input line not two
% as shown here):
% \begin{quote}\raggedright
%   \Prompt{}\verb|splitindex.pl -i '^\\indexentry\[([^]]*)\](.*)$'|
%   \verb|-s '-$1'| \verb|-r '\\indexentry$2' allabout|
% \end{quote}
% 
% If you want \Program{splitindex} to call \Program{makeindex} with the
% additional option ``\verb|-s foo.ist|'' to make it use the MakeIndex style
% file \File{foo.ist}, you can do so as follows:
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl allabout -- -s foo.ist|
% \end{quote}
% As you can see ``\verb|--|'' is used to prevent \Program{splitindex} from
% interpreting ``\verb|-s foo.ist|'' as option ``\verb|--suffixis foo.ist|''.
% All  \Program{splitindex} options must be put before ``\verb|--|'', but you
% can put the raw file argument ``\verb|allabout|'' after that:
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl -- allabout -s foo.ist|
% \end{quote}
%
% If you want so use the index processor \Program{xindy} instead of default
% index processor \Program{MakeIndex}, you can use this call:
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl -m xindy allabout|
% \end{quote}
% If \Program{xindy} is not in your standard \texttt{PATH}, you may set the
% whole path:
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl -m /home/me/bin/xindy allabout|
% \end{quote}
% With most perl implementations, the perl module \verb|Getopt::Long| allows to
% put options after no-option-arguments. So you may also write:
% \begin{quote}
%   \Prompt{}\verb|splitindex.pl allabout -m /home/me/bin/xindy|
% \end{quote}
% with the same result.
%
%
% \subsection{Using \Program{splitindex.jar}}
% \label{Java}
%
% This implementation should also be portable. If you are not using Sun
% Java~1.4.1 or higher, you may try to recompile this using the shell command:
% \begin{quote}
%  \Prompt{}\verb|javac splitindex.java|
% \end{quote}
% This should result in a new \File{splitindex.class}. But it will fail
% e.g. with Sun Java 1.3, because regular expressions are needed, which are
% not available in Sun Java 1.3.
%
% The call of \Program{splitindex.class} is almost the same as shown for
% \autoref{perl} for \Program{splitindex.pl}, but you have to replace
% ``\verb|splitindex.pl|'' by ``\verb|java splitindex|''. So the last example
% from \autoref{perl} becomes:
% \begin{quote}
%   \Prompt{}\verb|java splitindex allabout -m /home/me/bin/xindy|
% \end{quote}
%
%
% \subsection{Using \Program{splitindex} or \Program{splitindex.exe}}
% \label{C}
%
% The Linux program \Program{splitindex} was compiled using glibc, so it works
% the same as \Program{splitindex.pl} and you may use not only:
% \begin{quote}
%   \Prompt{}\verb|splitindex -m /home/me/bin/xindy allabout|
% \end{quote}
% but also:
% \begin{quote}
%   \Prompt{}\verb|splitindex allabout -m /home/me/bin/xindy|
% \end{quote}
%
% But the CygWin program \Program{splitindex.exe} was compiled using a
% CygWin library. Because of this, all options must be put before the first
% non-option argument. So you have to use:
% \begin{quote}
%   \Prompt{}\verb|splitindex.exe -m /home/me/bin/xindy allabout|
% \end{quote}
% With:
% \begin{quote}
%   \Prompt{}\verb|splitindex.exe allabout -m /home/me/bin/xindy|
% \end{quote}
% the argument ``\verb|-m /home/me/bin/xindy|'' will be passed to the default
% index processor \Program{MakeIndex}!
%
% You need the CygWin-DLL \File{cygwin1.dll} to run
% \Program{splitindex.exe}. If you haven't already installed it, you may
% download the DLL from \url{http://cygwin.com/snapshots}. You need
% \Program{bzip2}, which can be found at \url{http://source.redhat.com/bzip2},
% to decompress it. Alternatively, you may use \url{http://cygwin.com/setup.exe}
% to download and install a minimal CygWin environment.
%
% The Linux-i386-ELF binary \Program{splitindex} was compiled and linked
% using:
% \begin{quote}\raggedright
%  \Prompt{}\verb|gcc -O3 -Wall -osplitindex splitindex.c|\\
%  \Prompt{}\verb|strip splitindex|\\
% \end{quote}
% The \Program{gcc} was:
% \begin{verbatim}
% gcc (GCC) 3.2
% Copyright (C) 2002 Free Software Foundation, Inc.
% \end{verbatim}\vspace{-\baselineskip}
% The used \Program{glibc} is version 2.1.
%
% If you compile another binary e.g. for BSD, please contact me, so we may put
% the new binary into the distribution or can build another binary
% distribution.
%
%
% \subsection{Using \Program{splitindex.tex}}
% \label{TeX}
%
% The \TeX{} or \LaTeX{} program \Program{splitindex.tex} doesn't know any
% options or arguments. The number of files that it can generate is limited
% to to number of \TeX's free write handles. If there are any other lines than
% ``\verb|\indexentry|''-lines in the raw index file, running
% \Program{splitindex.tex} will result in an error.
%
% You may use \Program{splitindex.tex} interactively:
% \begin{quote}
%  \Prompt{}\verb|tex splitindex|
% \end{quote}
% or
% \begin{quote}
%  \Prompt{}\verb|latex splitindex|
% \end{quote}
% If you do so, you will be asked for the name of the raw index file. You have
% to omit the extension ``\File{.idx}'' answering that question.
%
% You may also use the \Program{splitindex.tex} not interactively, e.g. if you
% are working with a batch. To do so you have to define macro \cs{IDX} to the
% name of the raw index file without the extension ``\texttt{.idx}''. So the
% first example of \autoref{perl} would become:
% \begin{quote}
%  \Prompt{}\verb|tex \def\IDX{allabout}\input splitindex|
% \end{quote}
% You may also use \LaTeX{} instead of \TeX:
% \begin{quote}
%  \Prompt{}\verb|latex \def\IDX{allabout}\input splitindex|
% \end{quote}
%
% The current version of \Program{splitindex.tex} doesn't call any index
% processor. But maybe a future version will be able to do so.
%
% \StopEventually{^^A
% \begin{thebibliography}{99}
% \bibitem{makeindex} \textsc{Leslie Lamport}: \textit{MakeIndex: An Index
%     Processor For \LaTeX}, 17 February 1987
% \bibitem{makeindexmanual} \textsc{Pehong Chen}, \textsc{Rick P. C. Rodgers}:
%   \textit{MAKEINDEX(1L)}, Manual page, 10 December 1991
% \end{thebibliography}
% \PrintIndex\PrintChanges}
%
%
\subsection{Merging Indices}
%
%
% Now you should know how to use package \Package{splitidx} and the
% \Program{SplitIndex} programs to split the index. But what about combining
% two or more indices to one, e.g. you want vegetables and fruits in the
% same index? Try this:
% \begin{flushleft}\ttfamily
% \cs{documentclass}\{article\} \percentchar \textit{ We use \Class{article}
%   class \dots}\\
% \cs{usepackage}\{splitidx\} \percentchar \textit{ \dots\ and the
%   \Package{splitidx} package}\\
% \cs{makeindex} \percentchar \textit{ And we want index generation}\\
% ~\\
% \percentchar \textit{ We define 4 indices:}\\
% \cs{newindex}[General Index]\{idx\} \percentchar \textit{ Name and shortcut
%   of the 1st index}\\
% \cs{newindex}[Index of Animals]\{ani\} \percentchar \textit{ \dots\ 2nd
%   index}\\
% \cs{newindex}[Index of Fruits And Vegetables]\{fru\} \percentchar
% \textit{ \dots\ 3rd
%   index}\\ 
% ~\\
% \cs{begin}\{document\}\\
% Apples\cs{sindex}[fru]\{apple\} \percentchar \textit{ an entry to
%   }fru\texttt{ index}\\
% and oranges\cs{sindex}[fru]\{orange\} \percentchar \textit{ an entry to
%   }fru\texttt{ index}\\
% are fruits\cs{sindex}\{fruits\}.\ \percentchar \textit{ an implicit entry
% to }idx\textit{ index}\\
% Tomatoes\cs{sindex}[veg]\{tomato\} \percentchar \textit{ an entry to
% }veg\textit{ index}\\
% are\\
% vegetables\cs{index}\{vegetables\}.\ \percentchar \textit{ an implicit
%   entry to }idx\textit{ index}\\
% Cats\cs{sindex}[ani]\{cat\} \percentchar \textit{ an entry to
% }ani\textit{ index}\\
% are animals\cs{sindex}[idx]\{animals\}.\ \percentchar \textit{ an explicite
%   entry to }idx\textit{ index}\\
% ~\\
% \cs{printindex*} \percentchar \textit{ print all indices}\\
% \cs{end}\{document\}
% \end{flushleft}
% And do the following call after splitting the index using
% \Program{SplitIndex}:
% \begin{quote}\raggedright
%  \Prompt{}\verb|makeindex allabout-veg.idx allabout-fru.idx|\\
% \end{quote}
% Alternatively you can concatenate \File{allabout-fru.idx} to
% \File{allabout-veg.idx} before running the index processor on
% \File{allabout-veg.idx}.
%
%
%
% \section{Implementation of \Package{splitidx}}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \subsection{Options}
%
% The first option is used to activate index generation.
%    \begin{macrocode}
\DeclareOption{makeindex}{\AtEndOfPackage{\makeindex}}
%    \end{macrocode}
%
% \changes{v0.9}{2006/05/07}{new option \texttt{useindex}}
% With option \texttt{useindex} the original command \cs{index} behaves like
% \cs{sindex}.
%    \begin{macrocode}
\DeclareOption{useindex}{%
  \def\@se@nd@xc@d@{\let\index\sindex}%
  \AtEndOfPackage{\@se@nd@xc@d@}%
}
\let\@se@nd@xc@d@\relax
%    \end{macrocode}
%
% There is also an option to make \cs{sindex} ignores the optional argument
% and behaves like \cs{index}.%^^A
% \changes{v1.2}{2013/04/04}{new option `allintoone'}%^^A
% \changes{v1.2}{2013/04/04}{option `allatone' deprecated}%^^A
%    \begin{macrocode}
\DeclareOption{allatone}{%
  \PackageWarning{splitidx}{Option `allatone' deprecated!\MessageBreak
    You should replace it by `allintoone'}%
  \ifx\@se@nd@xc@d@\relax\else
    \PackageInfo{splitidx}{option `allatone' overwrites option `useindex'}%
    \let\@se@nd@xc@d@\relax
  \fi
  \AtEndOfPackage{%
    \renewcommand*{\sindex}[1][]{\index}%
    \g@addto@macro\makeindex{\renewcommand*{\sindex}[1][]{\index}}%
  }%
}
\DeclareOption{allintoone}{%
  \ifx\@se@nd@xc@d@\relax\else
    \PackageInfo{splitidx}{option `allintoone' overwrites option `useindex'}%
    \let\@se@nd@xc@d@\relax
  \fi
  \AtEndOfPackage{%
    \renewcommand*{\sindex}[1][]{\index}%
    \g@addto@macro\makeindex{\renewcommand*{\sindex}[1][]{\index}}%
  }%
}
%    \end{macrocode}
%
% \changes{v0.9}{2006/05/07}{new option \texttt{protected}}
% Do not expand index arguments.
%    \begin{macrocode}
\newif\if@verbindex\@verbindexfalse
\DeclareOption{protected}{\@verbindextrue}
%    \end{macrocode}
%
% \changes{v0.2}{2002/11/15}{new option \texttt{idxcommands}}
% With option \texttt{idxcommands} every \cs{newindex} also defines a new index
% command.
%    \begin{macrocode}
\newif\if@newidxcmd\@newidxcmdfalse
\DeclareOption{idxcommands}{\@newidxcmdtrue}
%    \end{macrocode}
%
% \changes{v0.2}{2002/11/15}{new option \texttt{split}}
% With option \texttt{split} each index uses its own index file.
%    \begin{macrocode}
\newif\if@splitidx\@splitidxfalse
\DeclareOption{split}{\@splitidxtrue}
%    \end{macrocode}
%
% Processing the options
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
%
%
% \subsection{Setting an Index Entry}
%
% \begin{macro}{\see}
% \begin{macro}{\seealso}
% \begin{macro}{\seename}
% \begin{macro}{\alsoname}
% These are four standard macros, which are also defined at
% \Package{makeidx}. Hey, these definitions are stolen from \Package{makeidx}!
% No, no, I'm not a bad guy, read ``\File{legal.txt}'', which comes with
% \Package{makeidx}.
%    \begin{macrocode}
\newcommand*\see[2]{\emph{\seename} #1}
\providecommand*\seealso[2]{\emph{\alsoname} #1}
\providecommand\seename{see}
\providecommand*\alsoname{see also}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\sindex}
% \begin{macro}{\@wrsindex}
%   \changes{v0.9}{2006/03/07}{optionally do not expand the index argument}
% \begin{macro}{\@@wrsindex}
% This works similar to original \cs{index} but uses a splitted index. So it
% allows an optional argument.
%    \begin{macrocode}
\newcommand*{\sindex}[2][]{%
}
\g@addto@macro\makeindex{%
  \renewcommand*{\sindex}{%
    \@bsphack\begingroup
    \@sanitize
    \@wrsindex
  }%
  \typeout{Using splitted index at \jobname.idx}%
  \@se@nd@xc@d@
}
%    \end{macrocode}
% At the following \cs{@@wrsindex} is used as a hook. If it is defines, it is
% used to write out the index entry. This hook may be used from
% e.g. \Package{hyperref} to add \verb|hyperpage| to the font selection of the
% page number. This only works with \verb+encap |+.
%   \changes{v1.0}{2006/07/30}{one level expansion of \cs{\@tempa} for
%     hyperref hook}
%    \begin{macrocode}
\newcommand*{\@wrsindex}[2][]{%
  \ifx\relax#1\relax
    \if@splitidx
      \@wrsindex[idx]{#2}%
    \else
      \def\@tempa{#2}%
      \if@verbindex\@onelevel@sanitize\@tempa\fi
      \@wrindex{\@tempa}%
    \fi
  \else
    \def\@tempa{#2}%
    \csname index@#1@hook\endcsname
    \expandafter\ifx\csname @@wrsindex\endcsname\relax
      \@@@wrsindex{#1}{{\@tempa}{\thepage}}%
    \else
      \def\@tempb{\@@wrsindex{#1}}%
      \expandafter\@tempb\@tempa||\\%
    \fi
    \endgroup
    \@esphack
  \fi
}
\newcommand*{\@@@wrsindex}[2]{%
  \begingroup
    \if@splitidx
      \expandafter\ifx\csname @indexfile@#1\endcsname\relax
        \PackageError{splitidx}{%
          Index entry for not existing index%
        }{%
          You've tried to set an index to index `#1', without
          defining\MessageBreak
          that index before using \string\newindex.\MessageBreak
          This is only allowed, if you are not using package option
          `split'.%
        }%
      \else
        \expandafter\protected@write\csname @indexfile@#1\endcsname{%
          \csname index@#1@writehook\endcsname
          \csname index@#1@writehook@once\endcsname
        }{%
          \string\indexentry#2%
        }%
      \fi
    \else
      \protected@write\@indexfile{%
        \csname index@#1@writehook\endcsname
        \csname index@#1@writehook@once\endcsname
      }{%
        \string\indexentry[#1]#2%
      }%
    \fi
  \endgroup
}
%    \end{macrocode}
% If \Package{hyperref} was loaded at \cs{begin\{document\}} and
% \Package{hyperref}-option \texttt{hyperindex} isn't disabled, and the hook
% is not used, define it:
%    \begin{macrocode}
\AtBeginDocument{%
  \begingroup\expandafter\expandafter\expandafter\endgroup
  \expandafter\ifx\csname ifHy@hyperindex\endcsname\relax
  \else
    \csname ifHy@hyperindex\endcsname
      \expandafter\ifx\csname @@wrsindex\endcsname\relax
        \def\@@wrsindex#1#2|#3|#4\\{%
          \ifx\\#3\\%
            \@@@wrsindex{#1}{{#2|hyperpage}{\thepage}}%
          \else
            \def\Hy@temp@A{#3}%
            \ifx\Hy@temp@A\HyInd@ParenLeft
              \@@@wrsindex{#1}{{#2|#3hyperpage}{\thepage}}%
            \else
              \ifx\Hy@temp@A\HyInd@ParenRight
                \@@@wrsindex{#1}{{#2|#3hyperpage}{\thepage}}%
              \else
                \@@@wrsindex{#1}{{#2|#3}{\thepage}}%
              \fi
            \fi
          \fi
        }%
      \fi
    \csname fi\endcsname
  \fi
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\AtWriteToIndex}
%   \changes{v1.1}{2009/02/26}{New}
%   Add commands to the write hook.
%    \begin{macrocode}
\newcommand*{\AtWriteToIndex}[1]{%
  \expandafter\ifx\csname index@#1@writehook\endcsname\relax
    \expandafter\let\csname index@#1@writehook\endcsname\@empty
  \fi
  \expandafter\g@addto@macro\csname index@#1@writehook\endcsname
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\AtNextWriteToIndex}
%   \changes{v1.1}{2009/02/26}{New}
% Like \cs{AtWriteToIndex} only once.
%    \begin{macrocode}
\newcommand*{\AtNextWriteToIndex}[1]{%
  \expandafter\ifx\csname index@#1@writehook@once\endcsname\relax
    \expandafter\gdef\csname index@#1@writehook@once\endcsname{%
      \expandafter\global\expandafter\let\expandafter
      \csname index@#1@writehook@once\endcsname\relax
    }%
  \fi
  \expandafter\g@addto@macro\csname index@#1@writehook@once\endcsname
}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Printing One Or More Indices}
%
% \begin{macro}{\printindex}
% \begin{macro}{\printindex*}
% This is used to print an index in the normal way. In most cases this uses
% |theindex| environment, but it need not.
%    \begin{macrocode}
\newcommand*{\printindex}{%
%    \end{macrocode}
% The command may be called in the star version, which prints all defined
% indices. This is same as \cs{printindices}.
%    \begin{macrocode}
  \@ifstar {%
    \begingroup
      \let\printindex@@endhook=\printindex@endhook
      \let\printindex@endhook=\relax
      \printindices%
      \csname printindex@@endhook\endcsname
    \endgroup
  }{%
%    \end{macrocode}
% It may also be called with optional arguments to print one of the indices:
%    \begin{macrocode}
    \@ifnextchar [\@printindex%] brace check comment
%    \end{macrocode}
% Or it is called without any parameter and so it is same as at
% \Package{makeidx} package:
%    \begin{macrocode}
    {%
      \@input@{\jobname.ind}%
      \csname printindex@endhook\endcsname
    }%
  }%
}
%    \end{macrocode}
% \begin{macro}{\@printindex}
% This is used to print one of the indices. The optional (here obligatory)
% argument is the shortcut of the index.
%    \begin{macrocode}
\newcommand*{\@printindex}{}
\def\@printindex[#1]{%
%    \end{macrocode}
% There can be one more optional argument, which is the title of the index. If
% not, the default title \cs{index@\meta{shortcut}@name} is used.
%    \begin{macrocode}
  \@ifnextchar [%
  {\@@printindex[{#1}]}%
  {\@@printindex[{#1}][\csname index@#1@name\endcsname]}%
}
%    \end{macrocode}
% \begin{macro}{\@@pintindex}
% \changes{v0.2}{2002/11/15}{with option \texttt{split} general index has no
%   suffix}
% We use the default environment to print one of the indices, but we redefine
% \cs{indexname} to the title of the wanted index, \cs{indexshortcut} to the
% shortcut of the wanted index and \cs{index@preamble} to the preamble of the
% wanted index. We do this in a group so it is local.
%    \begin{macrocode}
\newcommand*{\@@printindex}{}
\def\@@printindex[#1][#2]{%
  \begingroup
    \edef\indexshortcut{#1}%
    \def\indexname{#2}%
    \let\index@preamble\relax
    \expandafter\let\expandafter\index@preamble
    \csname index@\indexshortcut @preamble\endcsname
    \if@splitidx
      \def\@tempa{idx}\def\@tempb{#1}%
      \ifx\@tempa\@tempb\let\@indexsuffix\@gobble\fi
    \fi
    \@input@{\jobname\@indexsuffix{#1}.ind}%
  \endgroup
  \csname printindex@endhook\endcsname
}
%    \end{macrocode}
% \begin{macro}{\@indexsuffix}
% This generated the suffix from the shortcut. You may redefine this
% function, if you need. I`m using a trick here, to define the macro with
% proper catcodes but not to define it global. You may also use
% \cs{@firstofone} instead of \cs{lowercase}.
%    \begin{macrocode}
\begingroup
\catcode`\-12
\lowercase{\endgroup
  \newcommand*{\@indexsuffix}[1]{-#1}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\printindices}
% This is used to print all defined indices in the order of their definition
% and with their default titles. If the list is empty, is behaves like
% \cs{printindex} without star and optional arguments.
%    \begin{macrocode}
\newcommand*{\printindices}{%
  \ifx\@indices\@empty
    \printindex
  \else
    \begingroup
      \@for\@tempa:=\@indices\do{%
        \expandafter\printindex\expandafter[\@tempa]%
      }%
    \endgroup
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newindex}
% \changes{v0.2}{2002/11/15}{optional definition of index-shortcut-command}
% \changes{v0.2}{2002/11/15}{optional opening a new index file}
% The definition of a new index has an obligatory argument, the shortcut for
% this index, and an optional argument, the name of this index. If you omit
% the optional argument the shortcut is used for the default name if the
% index. The definition will be done global!
%    \begin{macrocode}
\newcommand*{\newindex}[2][\relax]{%
  \@ifundefined{index@#2@name}{%
    \if@verbindex
      \expandafter\gdef\csname index@#2@hook\endcsname{%
        \@onelevel@sanitize\@tempa
      }%
    \else
      \expandafter\gdef\csname index@#2@hook\endcsname{}%
    \fi
    \ifx\@indices\@empty
      \xdef\@indices{#2}%
    \else
      \xdef\@indices{\@indices,#2}%
    \fi
    \ifx \relax#1
      \expandafter\xdef\csname index@#2@name\endcsname{#2}%
    \else
      \expandafter\xdef\csname index@#2@name\endcsname{#1}%
    \fi
    \if@newidxcmd
      \expandafter\newcommand\expandafter*\csname #2\endcsname{}%
      \expandafter\gdef\csname #2\endcsname{%
        \sindex[#2]%
      }%
    \fi
    \if@splitidx
      \def\@tempa{#2}\def\@tempb{idx}%
      \ifx\@tempa\@tempb
        \global\let\@indexfile@idx=\@indexfile
      \else
        \expandafter\newwrite\csname @indexfile@#2\endcsname
        \expandafter\immediate\expandafter\openout
        \csname @indexfile@#2\endcsname=\jobname-#2.idx
      \fi
    \fi
  }{%
%    \end{macrocode}
% If the index is already defined, an error occurs:
%    \begin{macrocode}
    \PackageError{splitidx}{%
      index `#2' already defined%
    }{%
      You have already defined an index with shortcut `#2'.\MessageBreak
      You can't define a new index with the same shortcut. If you'll continue
      \MessageBreak
      The new definition will be ignored.%
    }%
  }%
}
\if@splitidx
  \@onlypreamble\newindex
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newprotectedindex}
%   \changes{v0.9}{2006/07/03}{new command}
% Same like \cs{newindex} but always define an index with protected arguments.
%    \begin{macrocode}
\newcommand*{\newprotectedindex}[2][\relax]{%
  \begingroup\@verbindextrue\newindex[{#1}]{#2}\endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@indices}
% This macro stores a list of the index shortcuts. This is needed by
% e.g. \cs{printindices} and build by \cs{newindex}.
%    \begin{macrocode}
\newcommand*{\@indices}{}
\gdef\@indices{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\extendtheindex}
% Extend \verb|theindex| by some macros called before starting the index,
% after starting the index, before stopping the index and after stopping the
% index. This may be used to change index behaviour. One additional change is
% done, which may be useful: before the index \cs{index@preamble} is set to
% \cs{index@\meta{shortcut}@preamble}.
%    \begin{macrocode}
\newcommand{\extendtheindex}[4]{%
  \begingroup\expandafter\expandafter\expandafter\endgroup
  \expandafter\ifx\csname splitindex@theindex\endcsname\relax
    \let\splitindex@theindex=\theindex
    \let\endsplitindex@theindex=\endtheindex
  \fi
  \renewcommand*{\theindex}{%
    #1\splitindex@theindex #2%
  }%
  \renewcommand*{\endtheindex}{%
    #3\endsplitindex@theindex #4%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\setindexpreamble}
% Set one of the splitted index preambles or the original one.
%    \begin{macrocode}
\newcommand{\splitindex@setip}{}
\let\splitindex@setip\setindexpreamble
\let\setindexpreamble\relax
\newcommand{\setindexpreamble}[2][]{%
  \ifx \relax#1\relax
    \begingroup\expandafter\expandafter\expandafter\endgroup
    \expandafter\ifx\csname splitindex@setip\endcsname\relax
      \@namedef{index@preamble}{#2}%
    \else
      \splitindex@setip{#2}%
    \fi
  \else
    \@namedef{index@#1@preamble}{#2}%
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\useindexpreamble}
% Use the index preamble and optional add additional information after it, if
% it exists and if it is not empty:
%    \begin{macrocode}
\newcommand{\useindexpreamble}[1][]{%
  \begingroup\expandafter\expandafter\expandafter\endgroup
  \expandafter\ifx\csname index@preamble\endcsname\relax\else
    \ifx\index@preamble\@empty\else
      \index@preamble #1%
    \fi
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\printsubindex}
% \begin{macro}{\printsubindex*}
% Works like \cs{printindex} but changes some macros before to level down the
% headings at the index generation.
%    \begin{macrocode}
\newcommand*{\printsubindex}{%
  \begingroup
    \begingroup\expandafter\expandafter\expandafter\endgroup
    \expandafter\ifx\csname chapter\endcsname\relax
      \let\section\subsection
      \begingroup\expandafter\expandafter\expandafter\endgroup
      \expandafter\ifx\csname addsec\endcsname\relax\else
        \def\addsec{\setcounter{secnumdepth}{0}\subsection}%
      \fi
    \else
      \let\chapter\section
      \def\@makeschapterhead{\section*}
      \let\@makechapterhead\section
      \begingroup\expandafter\expandafter\expandafter\endgroup
      \expandafter\ifx\csname addchap\endcsname\relax\else
        \let\addchap\addsec
      \fi
    \fi
%    \end{macrocode}
% Also, \cs{onecolumn} and \cs{twocolumn} and even \cs{clearpage} must be
% disabled. The macros \cs{onecolumn} and \cs{twocolumn} cannot be let
% \cs{relax} because the have an optional argument which must be used.
%    \begin{macrocode}
    \let\onecolumn\@firstoptofone
    \let\twocolumn\@firstoptofone
    \let\clearpage\relax
    \let\cleardoublepage\relax
%    \end{macrocode}
% And the mark mechanism must also use one down:
%    \begin{macrocode}
    \def\markboth{\expandafter\markright\@gobble}%
    \ifx\@mkboth\@gobble\else\let\@mkboth\markboth\fi
%    \end{macrocode}
% And the page style shouldn't change too:
%    \begin{macrocode}
    \let\thispagestyle\@gobble
%    \end{macrocode}
% Now, using \cs{printindex} enables all of it's features:
%    \begin{macrocode}
    \let\printindex@endhook=\endgroup
    \printindex    
}
%    \end{macrocode}
% \begin{macro}{\@firstoptofone}
% Read the optional argument and do it.
%    \begin{macrocode}
\providecommand{\@firstoptofone}[1][]{#1}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
\endinput
%
% end of file `splitindex.dtx'
%%% Local Variables:
%%% mode: doctex
%%% TeX-master: t
%%% End: