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.dtx942
1 files changed, 533 insertions, 409 deletions
diff --git a/Master/texmf-dist/source/latex/splitindex/splitidx.dtx b/Master/texmf-dist/source/latex/splitindex/splitidx.dtx
index a0bae1a464e..1829476baee 100644
--- a/Master/texmf-dist/source/latex/splitindex/splitidx.dtx
+++ b/Master/texmf-dist/source/latex/splitindex/splitidx.dtx
@@ -1,10 +1,10 @@
-% \CheckSum{604}
+% \CheckSum{625}
% \iffalse
% ======================================================================
% splitidx.dtx
-% Copyright (c) Markus Kohm, 2002-2009
+% Copyright (c) Markus Kohm, 2002-2013
%
-% $Id: splitidx.dtx,v 1.6 2009-03-20 14:55:11 mjk Exp $
+% $Id: splitidx.dtx,v 1.8 2013-04-04 13:59:54 mjk Exp $
%
% This file is part of the SplitIndex bundle.
%
@@ -15,7 +15,7 @@
% 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".
+% This work has the LPPL maintenance status "maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
@@ -54,18 +54,26 @@
%<driver>\ProvidesFile{splitidx.drv}[%
%<package>\ProvidesPackage{splitidx}[%
% \fi
- 2009/02/28 v1.1a multiple indices for LaTeX]
+ 2013/04/04 v1.2 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
+\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
@@ -73,15 +81,20 @@
\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}}
+\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 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.
+ 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}
@@ -102,97 +115,134 @@
% \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:
%
-% 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
+% implementation. I prefer 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
+% \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 section~\ref{TeX}), but
-% it is system independent and you don't need to install a other program
+% 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 program.
+% 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}
-% 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.
+% 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, four languages are enough for me! If you need one
+% \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}
%
-% \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:
+% 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}
@@ -202,9 +252,9 @@
% \end{verbatim}\vspace{-\baselineskip}
%
% \DescribeMacro{\makeindex}
-% To activate index generation you may use \cs{makeindex}, which is declared
+% To activate index generation, you can use \cs{makeindex}, which is declared
% by the \LaTeX{} kernel.
-% You may also load the package with option
+% You can also load the package with the option
% \texttt{makeindex}:
% \begin{verbatim}
% \usepackage[makeindex]{splitidx}
@@ -214,133 +264,162 @@
% \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}''.
+% 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{\sindex}
+% \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}
-% 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:
+% 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[allatone]{splitidx}
+% \usepackage[useindex]{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
-% or
+% 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[allatone,makeindex]{splitidx}
+% \usepackage[allintoone]{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.:
+% or
% \begin{verbatim}
-% \usepackage[useindex]{splitidx}
+% \usepackage[allintoone,makeindex]{splitidx}
% \end{verbatim}\vspace{-\baselineskip}
-% This may be usefull using packages like \textsf{jurabib} that expects
-% \cs{index} to be the index command.
+% 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{allatone} and
-% \texttt{useindex} can be used at same time. If you are using both
+% \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!}
%
-% \DescribeMacro{\AtWriteToIndex}
+% \subsection{Customizing index entries}
+%
+% \DescribeMacro{\AtWriteToIndex}%^^A
% \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
+% 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{commands}
+% \cs{AtWriteToIndex}\marg{shortcut}\marg{code}
% \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
+% 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}
-% 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}.
+% 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.
%
-% \subsection{Printing an index}
+% The \cs{AtWriteToIndex} command may be used only in the document preamble.
%
-% \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.
+% \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 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:
+% 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}
@@ -351,15 +430,15 @@
% "Anderung\index{"Anderung}
% \end{document}
% \end{verbatim}\vspace{-\baselineskip}
-% This will result in two entries at the \texttt{.idx} file:
+% 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 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
+% \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}
@@ -376,112 +455,124 @@
% \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,
+% 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}
-% \changes{v0.2a}{2003/01/05}{fix of documentation bug}
-% The \cs{printindex} command is used to print one index or all indices, which
+% \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.
%
-% With syntax
+% Used like this:
% \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
+% 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}
-% it behaves like \cs{printindex} from package \Package{makeidx}. You should
-% not use this, if you are using \cs{sindex} with optional argument.
+% 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, which were declared using \cs{newindex}. Use
-% syntax:
+% 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}.
%
-% \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.
+% \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}
-% The \cs{printsubindex} command behaves like \cs{printindex} with same syntax
-% but it does some redefinitions before printing the index, to:
+% \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 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 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} 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.
+% \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 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}.
+% 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}
+% \DescribeMacro{\setindexpreamble}%^^A
% If you are using a KOMA-Script class, you'll know this command. Package
-% \Package{splitidx} redefines this command to syntax:
+% \Package{splitidx} redefines this command as follows:
% \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:
+% 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}
+% \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}
+% 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 syntax
+% 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}}
+% \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
+% 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.
%
@@ -541,37 +632,42 @@
% \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:
+% \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\\
+% indices}\percentchar\\
% \ \cs{markboth}\{Indices\}\{Indices\} \percentchar\textit{ setting up the
-% running headline }\percentchar\\
+% 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.
+% 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. Maybe you'll try to replace the
-% above by the following:
+% 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!
% \#\#\#\#\#}\\
@@ -584,44 +680,47 @@
% \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:
+% 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{ hold following extension local to this
+% \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{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{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
+% \ \ \}\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
+% \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
+% \cs{printsubindex}[fru] \percentchar\textit{ print index }fru\textit{ as
% subsection}\\
-% \cs{printsubindex}[veg] \percentchar\textit{ print index }veg\textit{ as
+% \cs{printsubindex}[veg] \percentchar\textit{ print index }veg\textit{ as
% subsection}\\
-% \cs{onecolumn} \percentchar\textit{ finish the indices}
+% \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.
+% 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, if you want a onecolumn index:
+% 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}\\
@@ -643,47 +742,49 @@
% \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
+% This not only works with splitted indices but 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.
+% 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.
%
%
-% \section{Splitting the index}
+% \subsection{Splitting intermediate index files}
% \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.
+%
+% 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 section~\ref{TeX}):
-% \begin{description}\setlength{\labelsep}{1em}
+% 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 a index file.
+% 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 e.g. using \texttt{""} or \texttt{''}. An empty value means:
-% Don't call an index processor.
+% 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 short cut and the contents of the
-% raw index file with this shortcut. The default value is:
-% ``\verb|^(\\indexentry)\[([^]]*)\](.*)$|''. This means:
+% \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.
@@ -700,27 +801,30 @@
% 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|'', which means: contents of group 1 and group 3.
+% \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|'', which means:
+% \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{--ifentify} doesn't
+% 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}]
@@ -732,23 +836,25 @@
% 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.
+% 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).
%
-% You will find some examples at the following subsections.
+% 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,
-% how it works. If you have following \LaTeX{} file ``\File{allabout.tex}'':
+% 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}
@@ -759,7 +865,7 @@
% Cats\sindex[ani]{cat} are animals\sindex[idx]{animals}.
% \end{document}
% \end{verbatim}\vspace{-\baselineskip}
-% this generates a file ``File{allabout.idx}'':
+% this generates the intermediate index file ``File{allabout.idx}'':
% \begin{verbatim}
% \indexentry[fru]{apple}{1}
% \indexentry[fru]{orange}{1}
@@ -770,10 +876,10 @@
% \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):
+% 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}
@@ -808,10 +914,12 @@
% makeindex allabout-veg.idx
% makeindex allabout-ani.idx
% \end{verbatim}\vspace{-\baselineskip}
-% These calls create the raw index files \File{allabout-fru.ind},
+% \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 to the document using
-% e.g. \cs{printindex} from package \Package{splitidx}.
+% \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}
@@ -819,37 +927,38 @@
% \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):
+% 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 additional
-% options ``\verb|-s foo.ist|'' to use the MakeIndex style file
-% \File{foo.ist}, you can do this call:
+%
+% 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 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
+% 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 index processor \Program{xindy} instead of default index
-% processor \Program{MakeIndex} you can do this call:
+% 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 this is not at the standard \texttt{PATH} you may set the whole path:
+% 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 perl module \verb|Getopt::Long| allows to
+% 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|
@@ -860,19 +969,19 @@
% \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:
+% 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 at Sun Java 1.3.
+% not available in 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
+% 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 section~\ref{perl} becomes:
+% from \autoref{perl} becomes:
% \begin{quote}
% \Prompt{}\verb|java splitindex allabout -m /home/me/bin/xindy|
% \end{quote}
@@ -882,7 +991,7 @@
% \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:
+% 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}
@@ -892,24 +1001,24 @@
% \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:
+% 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}
-% At:
+% With:
% \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
+% 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. You may use \url{http://cygwin.com/setup.exe} to download
-% and install a minimal CygWin environment alternatively.
+% 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:
@@ -933,12 +1042,12 @@
% \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
+% 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} interactive:
+% You may use \Program{splitindex.tex} interactively:
% \begin{quote}
% \Prompt{}\verb|tex splitindex|
% \end{quote}
@@ -949,10 +1058,10 @@
% 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
+% 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 extension ``\texttt{.idx}''. So the first
-% example of section~\ref{perl} would become:
+% 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}
@@ -962,7 +1071,7 @@
% \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.
+% processor. But maybe a future version will be able to do so.
%
% \StopEventually{^^A
% \begin{thebibliography}{99}
@@ -974,11 +1083,12 @@
% \PrintIndex\PrintChanges}
%
%
-% \section{Combining Indices}
+\subsection{Merging Indices}
+%
%
-% Now you should know, how to use package \Package{splitidx} and the
+% 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
+% 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}
@@ -1051,10 +1161,14 @@
\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}.
+% 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
@@ -1064,6 +1178,16 @@
\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}}