summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/splitindex/splitidx.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/splitindex/splitidx.dtx')
-rw-r--r--Master/texmf-dist/source/latex/splitindex/splitidx.dtx1584
1 files changed, 1584 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/splitindex/splitidx.dtx b/Master/texmf-dist/source/latex/splitindex/splitidx.dtx
new file mode 100644
index 00000000000..a0bae1a464e
--- /dev/null
+++ b/Master/texmf-dist/source/latex/splitindex/splitidx.dtx
@@ -0,0 +1,1584 @@
+% \CheckSum{604}
+% \iffalse
+% ======================================================================
+% splitidx.dtx
+% Copyright (c) Markus Kohm, 2002-2009
+%
+% $Id: splitidx.dtx,v 1.6 2009-03-20 14:55:11 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 "author-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
+ 2009/02/28 v1.1a multiple indices for LaTeX]
+% \iffalse
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{color,alltt}
+\newcommand*{\Prompt}{{\color{green}\textbf{\$}}}
+\newcommand*{\Package}{}\let\Package\textsf
+\newcommand*{\Class}{}\let\Class\textsf
+\newcommand*{\Program}{}\let\Program\textsf
+\newcommand*{\File}{}\let\File\texttt
+\newcommand*{\Cmdline}{}\let\Cmdline\texttt
+\providecommand*{\url}{\texttt}
+\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}}
+\date{\filedate}
+\begin{document}
+\maketitle
+\begin{abstract}
+ With \Package{makeidx} there's a standard package at \LaTeX{} to create
+ one index to each document. But some times more than one index is
+ needed. There are different packages with different solutions and different
+ problems to achieve multiple indices. Here is one more.
+\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}
+%
+% \section{Introduction}
+%
+% First of all you have to know how index generation normally would be
+% done. Read \cite{makeindex} and e.g. \cite{makeindexmanual} if you
+% don't.
+%
+% Generally you load a package e.g. \Package{makeidx}, put \cs{index} commands
+% into your document, which are written as \cs{indexentry} commands to the raw
+% index file ``\File{\cs{jobname}.idx}''. Then you call an \emph{index
+% processor} like \Program{MakeIndex} or \Program{xindy}, which generates a
+% sorted index file ``\File{\cs{jobname}.ind}''. This will be included with a
+% command like \cs{printindex} at the end of your document.
+%
+% Most packages, which allows more than one index, open more than one raw
+% index file. Each of these files costs a write file handle. \TeX{} has only
+% 16 of these. \LaTeX{} itself needs some of these for e.g. \File{.aux},
+% \File{.toc}, \File{.lot}, \File{.lof} and maybe other more or less temporary
+% files depends on what you are doing. With package option \texttt{split}
+% package \Package{splitidx} works like those packages.
+%
+% Without option \texttt{split} the \Package{splitidx} package needs only one
+% raw index file like \Package{makeidx} would. This one raw index files
+% contains all the index entries for all the indices you defined. But to do so
+% \Package{splitidx} and the index processor need help. Before calling the
+% index processor the one raw index file has to be splitted into multiple raw
+% index files. Each of these contains the index entries of one index. This
+% splitting can be done with the \Program{splitindex} program.
+%
+% There is not only one \Program{SplitIndex} program, there are
+% \Program{SplitIndex} programs in different programming languages:
+% \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 prefers to use this\,---\,because it was the first, the
+% easiest and the shortest to be written.
+% \item[\Program{splitindex.jar}] This is written using Sun Java 1.4.1. You
+% can find the source at \File{splitindex.java}. I wrote it, because Java is
+% everywhere and may be installed everywhere and a lot of people are able to
+% understand Java source files. But if you don't have Sun Java 1.4 the start
+% of this program will result in errors\,---\,e.g.
+% \begin{quote}
+% \texttt{Exception in thread "main" java.util.zip.ZipException: No such
+% file or directory}
+% \end{quote}
+% if you try to start it with Sun Java 1.3.
+% \item[\Program{splitindex-Linux-i386}] This is a Linux-i386-ELF binary from
+% the C source file \File{splitindex.c}. It will be renamed to
+% \Program{splitindex} during installation, if you are using Linux-i386. At
+% section~\ref{C} you find a introduction in how to compile
+% \File{splitindex.c} yourself e.g. if you are using Linux-PPC. I wrote the
+% C source, 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 bit code\,---\,even, if the Java program is fast enough.
+% \item[\Program{splitindex-OpenBSD-i386}] This is a OpenBSD-i386 binary from
+% the C source file \File{splitindex.c}. It will be renamed to
+% \Program{splitindex} during installation, if you are using
+% OpenBSD-i386. It is almost the same like
+% \Program{splitindex-Linux-i386}\,---\,but it doesn't understand long
+% option names.
+% \item[\Program{splitindex.exe}] This is a CygWin binary from the C source
+% file \File{splitindex.c}. A CygWin binary is a Windows (Win32) binary
+% using the CygWin DLL. At section~\ref{C} you find a introduction in how to
+% use a CygWin binary without installing a whole CygWin
+% environment\,---\,nevertheless it is nice to have a almost complete
+% CygWin.
+% \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 section~\ref{TeX}), but
+% it is system independent and you don't need to install a 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 program.
+% \end{description}
+% Without the \TeX{} version of \Program{splitindex} all of these programs are
+% also able to call the index processor after creating the raw index files.
+%
+% And where is the lisp, the smalltalk, the prolog, the \dots{} version of
+% \Program{splitindex}? Hey, four languages are enough for me! If you need one
+% more, write it!
+%
+%
+% \section{Using the \Package{splitidx} package}
+% \label{package}
+%
+%
+% \subsection{Generating a raw index}
+%
+% You may 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 may use \cs{makeindex}, which is declared
+% by the \LaTeX{} kernel.
+% You may also load the package with 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}
+%
+% \DescribeMacro{\index}
+% After loading the package you may use command \cs{index}. You can find the
+% description of the argument and features of this command at
+% \cite{makeindex}. The \Program{splitindex} programs (see
+% section~\ref{program}) put all index entries, which are produced with
+% \cs{index} to the index with shortcut ``\texttt{idx}''.
+%
+% \DescribeMacro{\sindex}
+% The \Package{splitidx} package also defines the command \cs{sindex} with the
+% syntax:
+% \begin{quote}
+% \cs{sindex}\oarg{shortcut}\marg{index-entry}
+% \end{quote}
+% to be used to put an index
+% entry into the index with the optional given shortcut. If you omit optional
+% \meta{shortcut} the shortcut ``\texttt{idx}'' will be used.
+% If you use \cs{sindex} you need to split the raw index file into several raw
+% index files, before generating the index with an index processor like
+% \Program{MakeIndex}. See section~\ref{program} for more information about
+% splitting the raw index file.
+%
+% The shortcut is used not only to distinguish between the different
+% indices. It is also used as part of the name of the raw index file generated
+% by a \Program{splitindex} program (see section~\ref{program}) and the
+% corresponding index file generated by an index processor like
+% \Program{MakeIndex} (see \cite{makeindexmanual}). So you should not use
+% characters or symbols at \meta{shortcut} which are not allowed at
+% filenames. At file systems, which are not case sensitive, you should not mix
+% upper and lower case letters. Best would be, if you'll use only lower case
+% letters.
+%
+% Under some unfortunate circumstances you may be forced to put all your index
+% entries back to one index. The easiest way to do this without changing all
+% \cs{sindex} commands into \cs{index} commands is the package option
+% \texttt{allatone}. If you load the package with:
+% \begin{verbatim}
+% \usepackage[allatone]{splitidx}
+% \end{verbatim}\vspace{-\baselineskip}
+% or
+% \begin{verbatim}
+% \usepackage[allatone,makeindex]{splitidx}
+% \end{verbatim}\vspace{-\baselineskip}
+% \cs{sindex}\oarg{shortcut}\marg{indexentry} will result in
+% \cs{index}\marg{indexentry}.
+%
+% If you like, you may also declare that \cs{index} should be the same
+% like command \cs{sindex}. In this case, you may use package
+% option \texttt{useindex}, e.g.:
+% \begin{verbatim}
+% \usepackage[useindex]{splitidx}
+% \end{verbatim}\vspace{-\baselineskip}
+% This may be usefull using packages like \textsf{jurabib} that expects
+% \cs{index} to be the index command.
+%
+% \emph{Note: Currently only one of the options \texttt{allatone} and
+% \texttt{useindex} can be used at same time. If you are using both
+% \texttt{useindex} will be disabled! This may result in many error
+% messages!}
+%
+% \DescribeMacro{\AtWriteToIndex}
+% \Package{splitidx} uses \cs{protected@write} to write the index entries to
+% the raw index files. The second argument of \cs{protected@write} will be
+% executed immediatly before writing to the raw index file. With
+% \begin{quote}
+% \cs{AtWriteToIndex}\marg{shortcut}\marg{commands}
+% \end{quote}
+% you may add \marg{commands} to this argument. This may be usefull,
+% if you do not want to reference the page number but another counter. You
+% may, e.g., use
+% \begin{verbatim}
+% \AtWriteToIndex{idx}{\let\thepage\thesection}
+% \end{verbatim}
+% to write the current section number instead of the page number to the main
+% index. But be carefull: If you do not use option \texttt{useindex}, command
+% \cs{index} will still write the page number to the index. This may be used
+% only at the document preamble.
+%
+% \DescribeMacro{\AtNextWriteToIndex}
+% Somethimes it may be usefull to have the same like \cs{AtWriteToIndex} only
+% for the next write. So you may use
+% \begin{quote}
+% \cs{AtNextWriteToIndex}\marg{shortcut}\marg{commands}
+% \end{quote}
+% instead of using \cs{AtWriteToIndex}.
+%
+% \subsection{Printing an index}
+%
+% \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 from \cs{printindex} and
+% \cs{printsubindex}. If you omit \meta{index name} the shortcut will be used
+% as index name.
+%
+% Some people do not like to call an extra program like
+% \Program{splitindex}. For those the package option \texttt{split} has been
+% implemented. With this option \Package{splitidx} opens a new file for each
+% index, which is declared using \cs{newindex}. If you are using this option,
+% you have to declare all indices you want to use at the preamble of your
+% document. This also uses the default \File{idx} file for index entries to
+% index with shortcut \texttt{idx}. The number of index files, you can open is
+% limited, if you are using this option. This is because of the limitation of
+% output streams \TeX{} provides. With this option not only \cs{newindex} may
+% result in an error but also \cs{tableofcontents}, \cs{listoffigures},
+% \cs{listoftables} and each other command, which allocates an output stream.
+%
+% Some people do not like to write \cs{sindex[foo]}\marg{entry}. They want to
+% write \cs{foo}\marg{entry}. For those of you the package option
+% `\texttt{idxcommands}' has been implemented. This defines a command with the
+% name of the \meta{shortcut} for each declared index. If you are using this
+% option, you'll get an error, if a shortcut is the name of an already defined
+% command. And if you are using this option, the characters of the shortcuts
+% must be letters.
+%
+% \DescribeMacro{\newprotectedindex}
+% Using standard index package \textsf{makeidx} the \LaTeX{} kernel command
+% \cs{index} may expand the argument of \cs{index}. The kernel uses
+% \cs{@santize} to avoid this in some cases. But this fails, if the argument
+% was already read e.g. by another macro. So if you define a macro, that reads
+% an argument, does something with the argument and write it to the index this
+% may expand the argument. Try 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 at 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 same by default. But if you are using
+% \cs{newprotectedindex} to define a new index, it uses a trick so avoid
+% expansion. If all indices should behave like this, you may simply use
+% 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 command
+% \cs{@onelevel@sanitize} at the \LaTeX{} kernel documentation,
+% \texttt{source2e}.
+%
+%
+% \DescribeMacro{\printindex}
+% \changes{v0.2a}{2003/01/05}{fix of documentation bug}
+% The \cs{printindex} command is used to print one index or all indices, which
+% are declared using \cs{newindex}. How it behaves depends on the syntax you
+% are using.
+%
+% With syntax
+% \begin{quote}
+% \cs{printindex}\oarg{shortcut}\oarg{index name}
+% \end{quote}
+% the index file with the optional shortcut will be loaded and titled with
+% optional given index name. If \meta{index name} is omitted the default index
+% name declared with \cs{newindex} will be used.
+%
+% If the both optional arguments, \meta{shortcut} and \meta{index name}, are
+% omitted and you are using simply
+% \begin{quote}
+% \cs{printindex}
+% \end{quote}
+% it behaves like \cs{printindex} from package \Package{makeidx}. You should
+% not use this, if you are using \cs{sindex} with optional argument.
+%
+% You may also print all indices, which were declared using \cs{newindex}. Use
+% syntax:
+% \begin{quote}
+% \cs{printindex*}
+% \end{quote}
+% to do so. The indices will be printed in the order you declared them using
+% \cs{newindex}.
+%
+% \cs{printindex} uses the default index output of the class and the
+% index processor you are using. Most this will be \texttt{theindex}
+% environment, but it needn't. But \cs{printindex} will fail to set the name
+% of the index if \cs{indexname} isn't use to print the name of the
+% index. This would be a failure of the class not of the \Package{splitidx}
+% package. I don't know any class with this failure.
+%
+%
+% \DescribeMacro{\printsubindex}
+% The \cs{printsubindex} command behaves like \cs{printindex} with same syntax
+% but it does some redefinitions before printing the index, to:
+% \begin{itemize}
+% \item use \cs{section} instead of \cs{chapter} level at classes, which have
+% \cs{chapter} and \cs{subsection} instead of \cs{section} level at classes,
+% which haven't \cs{chapter},
+% \item deactivate \cs{onecolumn}, \cs{twocolumn} and \cs{clearpage},
+% \cs{cleardoublepage} to start a new page at each index,
+% \item change the mark mechanism not to use \cs{markboth} but \cs{markright}
+% for setting up the running headline.
+% \end{itemize}
+% Using this you can print multiple indices at one chapter, if you are using a
+% class with \cs{chapter}, or at one section, if you are using a class without
+% \cs{chapter}.
+%
+%
+% \DescribeMacro{\setindexpreamble}
+% If you are using a KOMA-Script class, you'll know this command. Package
+% \Package{splitidx} redefines this command to syntax:
+% \begin{quote}
+% \cs{setindexpreamble}\oarg{shortcut}\marg{preamble}
+% \end{quote}
+% So you can define a preamble for each index. Note: Package
+% \Package{splitidx} doesn't print the preamble itself. But it lets
+% \cs{index@preamble} to be the preamble of the index with the actual
+% shortcut, before printing an index using \cs{printindex} or
+% \cs{printsubindex}.
+%
+%
+% \DescribeMacro{\useindexpreamble}
+% If you are defining your own index environment or if you extend
+% \texttt{theindex} environment using e.g. \cs{extendtheindex}, you may use
+% \cs{useindexpreamble} with syntax:
+% \begin{quote}
+% \cs{useindexpreamble}\oarg{additional commands}
+% \end{quote}
+% to print the preamble of the actual index, which was set using
+% \cs{setindexpreamble}. This is not related to the KOMA-Script classes, it
+% can also be used e.g. with the standard classes. The commands from optional
+% argument \meta{additional commands} are only used, if the preamble is
+% defined and not empty.
+%
+%
+% \DescribeMacro{\indexshortcut}
+% The macro \cs{indexshortcut} is only defined at \cs{printindex} and
+% \cs{printsubindex}. It expands to the shortcut of the actual index. So you
+% may use it at your own index environment or extending the \texttt{theindex}
+% environment using e.g. \cs{extendtheindex}.
+%
+%
+% \DescribeMacro{\extendtheindex}
+% Most classes define the environment \texttt{theindex} to be used for
+% printing the index. Using \cs{extendtheindex} with 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 command. The commands from \meta{before begin} are used
+% at \cs{begin\{theindex\}} just after starting the group but before starting
+% the index. The commands from \meta{after begin} are used after
+% \cs{begin\{theindex\}}. The commands from \meta{before end} are used before
+% \cs{end\{theindex\}}. The commands from \meta{after end} are used at
+% \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}
+% Section~\ref{program} shows, how you can process this raw index file to get
+% several raw index files and several index files. You will get four index
+% files. Each of it will be input with the single \cs{printindex*} command at
+% the example above. Each will produce a single section starting on an new
+% page with one column section headings ``General Index'', ``Index of
+% Animals'', ``Index of Fruits'' and ``Index of Vegetables''. Each index is
+% printed in twocolumn mode.
+%
+% Maybe you would like to have all indices being subsections at one
+% section. You can do this, if you replace the \cs{printindex*} command at the
+% example above by 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*} at this
+% modification. You don't need to setup the running headline, if you are using
+% page style \texttt{plain}, which is default at \Class{article} class. But if
+% you're using page style \texttt{headings} you should do this, if you are
+% using \cs{section*}. If you are using a KOMA-Script class, you can use
+% \cs{addsec} or \cs{addsec*} instead of \cs{section*} to not need manual
+% updating of the running headline.
+%
+% Maybe you want the general index to be the section, while the other indices
+% should be subsections of the general index. Maybe you'll try to replace the
+% above by 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 with general index \texttt{idx}
+% and three onecolumn subsections with the other indices and a page break
+% after the general index. Why? At the end of \texttt{theindex} environment of
+% \cs{printindex} the onecolumn mode, which was valid before \cs{printindex}
+% will be restored. If twocolumn mode was valid before \cs{printindex} a
+% \cs{clearpage} command will be included 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{ hold 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 twocolumn with no page break
+% before the first subsection. But you have to switch back to onecolumn mode
+% manually at the end of the indices.
+%
+% The example above may be modified, if you want 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 index. You may use this also with one
+% single index.
+%
+% I hope, that these examples were useful to understand, how to use
+% \Package{splitidx}. Next section will show you, how to generate the indices
+% from a single raw index.
+%
+%
+% \section{Splitting the index}
+% \label{program}
+%
+% At most you'll call one of the \Program{splitindex} programs with one
+% parameter, the name of the raw index file, to split the raw index file into
+% several raw index files and call the index processor
+% \Program{MakeIndex}. Some of you will also set options to use another index
+% processor e.g. \Program{xindy} or to set some options of the index processor
+% e.g. ``\Cmdline{-g}'' to use German sorting with \Program{MakeIndex}. Only
+% few of you will also change the parsing of the raw index file and the
+% generation if the filenames and contents of the several new 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 section~\ref{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 a 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 e.g. using \texttt{""} or \texttt{''}. An empty value means:
+% Don't call an index processor.
+% \item[\texttt{--identify} \meta{regular expression}]~
+% \item[\texttt{-i} \meta{regular expression}]\vspace{-2\itemsep}
+% Uses \meta{regular
+% expression} to identify the index short cut and the contents of the
+% raw index file with this shortcut. The default value is:
+% ``\verb|^(\\indexentry)\[([^]]*)\](.*)$|''. 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.
+% \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|'', 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|'', which means:
+% character `\texttt{-}' followed by contents of group 2.
+%
+% If the \meta{regular expression} of option \texttt{--ifentify} 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}
+% The OpenBSD binary \Program{splitindex-OpenBSD-i386} doesn't understand the
+% long option names (\texttt{--makeindex}, \texttt{--identify} \dots). But you
+% can use the alternative short option names (\texttt{-m}, \texttt{-i} \dots).
+%
+% The first no-option-argument at the command line is the name if the raw
+% index file, which has to be processed. All arguments, which follow the
+% argument ``\texttt{--}'' are interpreted as no-optional-arguments. All but
+% the first no-option-arguments will be passed to the index processor.
+%
+% You will find some examples at the following subsections.
+%
+%
+% \subsection{Using \Program{splitindex.pl}}
+% \label{perl}
+%
+% This is the reference implementation. Let's use an example to demonstrate,
+% how it works. If you have 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 a 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 a index processor like
+% \Program{MakeIndex}. If you want so split these raw index file into several
+% 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}
+% These calls create the raw index files \File{allabout-fru.ind},
+% \File{allabout-idx.ind}, \File{allabout-veg.ind} and
+% \File{allabout-ani.ind}, which can be loaded to the document using
+% e.g. \cs{printindex} from package \Package{splitidx}.
+%
+% 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 achieve the same files like above using (it's one input line not two
+% like 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 additional
+% options ``\verb|-s foo.ist|'' to use the MakeIndex style file
+% \File{foo.ist}, you can do this call:
+% \begin{quote}
+% \Prompt{}\verb|splitindex.pl allabout -- -s foo.ist|
+% \end{quote}
+% As you see ``\verb|--|'' is used to tell \Program{splitindex} to not
+% interprete ``\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 index processor \Program{xindy} instead of default index
+% processor \Program{MakeIndex} you can do this call:
+% \begin{quote}
+% \Prompt{}\verb|splitindex.pl -m xindy allabout|
+% \end{quote}
+% If this is not at the 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 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 should also be portable. If you are not using Sun Java 1.4.1 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 at Sun Java 1.3.
+%
+% The call of \Program{splitindex.class} is almost the same like shown at
+% section~\ref{perl} for \Program{splitindex.pl}, but you have to replace
+% ``\verb|splitindex.pl|'' by ``\verb|java splitindex|''. So the last example
+% from section~\ref{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
+% same like \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
+% no-option-argument. So you have to use:
+% \begin{quote}
+% \Prompt{}\verb|splitindex.exe -m /home/me/bin/xindy allabout|
+% \end{quote}
+% At:
+% \begin{quote}
+% \Prompt{}\verb|splitindex.exe allabout -m /home/me/bin/xindy|
+% \end{quote}
+% the arguments ``\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. You may use \url{http://cygwin.com/setup.exe} to download
+% and install a minimal CygWin environment alternatively.
+%
+% 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. It number of files, which can be generated, is limited
+% to to number of \TeX's free write handles. If there are other lines than
+% ``\verb|\indexentry|''-lines at the raw index file, running
+% \Program{splitindex.tex} will result in an error.
+%
+% You may use \Program{splitindex.tex} interactive:
+% \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 interactive 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 extension ``\texttt{.idx}''. So the first
+% example of section~\ref{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 in future a 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}
+%
+%
+% \section{Combining 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 don't 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}.
+% \begin{macrocode}
+\DeclareOption{allatone}{%
+ \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}}%
+ }%
+}
+% \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:
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-20 09:21:33 +0000