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