diff options
author | Karl Berry <karl@freefriends.org> | 2013-04-05 23:29:43 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-04-05 23:29:43 +0000 |
commit | 10e6cd9ce34c0ec20d007ebe6ce8fca9783b7309 (patch) | |
tree | b5978aff26fa2650ca7cf9040bfb7c6c408ddd9b /Master/texmf-dist/source/latex/splitindex/splitidx.dtx | |
parent | 26b44194fa3622fa961f40a0d62fb3cacaa5cbc9 (diff) |
splitindex (5apr13)
git-svn-id: svn://tug.org/texlive/trunk@29688 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/splitindex/splitidx.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/splitindex/splitidx.dtx | 942 |
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}} |