path: root/Master/texmf-dist/source/latex/xdoc/docindex.dtx

% \CheckSum{893}
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{xdoc2}

\makeatletter
\NewMacroEnvironment{templatetype}{\XD@grab@harmless\relax}{1}%
   {\MacroFont#1\ \normalfont type}%
   {\XDMainIndex{\LevelSorted{#1}{\texttt{#1} template type}}}%
   {{#1}{\texttt{#1} template type}}%
   {}%
\NewMacroEnvironment*{template}{%
   \XD@grab@harmless\relax\XD@grab@harmless\relax
}{2}%
   {\XDParToMargin{\MacroFont #1\textnormal{\slash}#2 \normalfont
       template}}%
   {\XDMainIndex{
      \LevelSorted{#1}{\texttt{#1} template type}%
      \LevelSorted{#2}{\texttt{#2} template}%
   }}%
   {{#1/#2}{\texttt{#1}\slash\texttt{#2} template}}%
   {\def\XD@template@sort{%
      \LevelSorted{#1}{\texttt{#1} template type}%
      \LevelSorted{#2}{\texttt{#2} template}%
   }}%
\NewMacroEnvironment*{instance}{%
   \XD@grab@harmless\relax\XD@grab@harmless\relax
}{2}%
   {\XDParToMargin{\MacroFont #1\textnormal{\slash}#2 \normalfont
       instance}}%
   {\XDMainIndex{
      \LevelSorted{#1}{\texttt{#1} template type}%
      \LevelSorted{#2}{\texttt{#2} instance}%
   }}%
   {{#1/#2}{\texttt{#1}\slash\texttt{#2} instance}}%
   {}%
\NewMacroEnvironment*{collectioninstance}{%
   \XD@grab@harmless\relax\XD@grab@harmless\relax\XD@grab@harmless\relax
}{3}%
   {\XDParToMargin{\MacroFont #2\textnormal{\slash}#3 \normalfont
      instance (\texttt{#1} collection)}}%
   {\XDMainIndex{
      \LevelSorted{#2}{\texttt{#2} template type}%
      \LevelSorted{#3}{\texttt{#3} instance}%
      \LevelSorted{#1}{\texttt{#1} collection}%
   }}%
   {{#2/#3/#1}%
    {\texttt{#2}\slash\texttt{#3} instance (\texttt{#1} collection)}}%
   {}%
\@namedef{XD@harmless\string\break}{%
   \toks@=\expandafter{\the\toks@ \protect\nolinebreak[3]}%
   \XD@harmless@
}
\newcommand\keyvalitem[2]{%
   \item[#1 (#2)%
      \IndexEntry{\XD@template@sort
         \LevelSorted{#1}{\textit{#1} keyval (#2)}%
      }{usage}{\thepage}%
   ]%
}
\newcommand{\xrefoff}{\scan@allowedfalse}
\newcommand{\xrefon}{\scan@allowedtrue}
\makeatother

\newenvironment{syntax}{%
   \let\\=\break
   \list{}{%
      \setlength\topsep{\medskipamount}%
      \setlength\partopsep{0pt}%
      \setlength\itemsep{0pt plus 1pt}%
      \setlength\parsep{\itemsep}%
      \setlength\leftmargin{3em}%
      \setlength\listparindent{1em}%
      \setlength\itemindent{-2em}%
      \setlength\labelwidth{0pt}%
      \setlength\labelsep{0pt}%
      \csname @endparpenalty\endcsname=500
      \def\makelabel##1{\mbox{\meta{##1}${}\longrightarrow{}$}}%
   }%
   \addtolength\rightskip{0pt plus 1fil}%
   \linepenalty=300%
}{\endlist}
\newcommand\branch{\({}\mid{}\)\ignorespaces}

\DeclareRobustCommand{\package}[1]{\textsf{#1}}
\DeclareRobustCommand{\program}[1]{\textsf{#1}}
\DeclareRobustCommand\LaTeXplus{\LaTeXe$*$}

\DoNotIndex{\addvspace,\@backslashchar,\begin,\begingroup,\bgroup}
\DoNotIndex{\csname,\DeclareInstance,\DeclareOption}
\DoNotIndex{\DeclareTemplate,\DeclareTemplateType,\def}
\DoNotIndex{\DoParameterAssignments,\edef,\egroup,\@eha}
\DoNotIndex{\@empty,\end,\endcsname,\endgroup,\endinput,\expandafter}
\DoNotIndex{\@firstofone,\@firstoftwo,\global,\@gobble,\hb@xt@,\hfil}
\DoNotIndex{\hsize,\hspace,\IfNoValueTF,\@ifpackageloaded}
\DoNotIndex{\@ifpackagewith,\@ifundefined,\ignorespaces,\@input@}
\DoNotIndex{\jobname,\leftskip,\let,\MessageBreak,\@namedef,\@ne}
\DoNotIndex{\NeedsTeXFormat,\newcommand,\nobreak,\@nobreakfalse}
\DoNotIndex{\nopagebreak,\normalsize,\NoValue,\number,\outer}
\DoNotIndex{\p@,\PackageError,\PackageInfo,\PackageWarningNoLine}
\DoNotIndex{\pagestyle,\par,\parfillskip,\parindent,\parskip}
\DoNotIndex{\@plus,\ProcessOptions,\protect,\protected@edef}
\DoNotIndex{\providecommand,\ProvidesPackage,\relax,\renewcommand}
\DoNotIndex{\RequirePackage,\rightskip,\romannumeral,\@secondoftwo}
\DoNotIndex{\small,\space,\textbf,\thispagestyle,\thr@@,\tw@}
\DoNotIndex{\vadjust,\vspace,\z@,\z@skip}
\DoNotIndex{\iffalse,\ifnum,\ifx,\else,\fi} % \fi \fi
\DoNotIndexBy{@}
\DoNotIndexBy{DI@}

\CodelineIndex
\EnableCrossrefs
\RecordChanges
\setcounter{IndexColumns}{2}
\setcounter{StandardModuleDepth}{2}


\begin{document}
\DocInput{docindex.dtx}
\PrintChanges
\PrintIndex
\end{document}
%</driver>
% \fi
% 
% \title{The \package{docindex} package}
% \author{Lars Hellstr\"om}
% \date{8 July 2003}
% \maketitle
% 
% \begin{abstract}
%   The \package{docindex} package implements template-based formatting 
%   of indices and lists of changes\slash glossaries. In addition to this, 
%   the control structures employed also provide for a couple of new 
%   features, such as automatic collapsing of trivial index levels.
% \end{abstract}
% 
% \tableofcontents
% 
% 
% \section{Introduction}
% 
% In automatically generated indices with multi-level entries, such as the 
% list of changes of a \package{doc} document, it often happens that some 
% entries are uniquely identified by their primary level sort keys, 
% although there are sort keys and text for additional levels. If then 
% the formatting is designed for entries that are uniquely identified 
% only when their secondary or tertiary sort keys are considered, one 
% ends up with a couple of entries that look rather peculiar (building 
% a tree which never branches) and usually take up much more space than 
% they need to. The remedy for this is of course to make the formatting 
% smart enough to recognise this situation when it occurs and flexible 
% enough to format the text is a more suitable manner.
% 
% An example of this is that if a document contains the index 
% entries\footnote{I'm using the default \program{makeindex} 
% metacharacters in these examples, but the style file provided for 
% this package actually uses the same metacharacters as those style files 
% provided by the \package{doc} package---hence the `\package{doc}' 
% in `\package{docindex}'. }
% \begin{quote}
%   |\index{Bernoulli!Jacob}\index{Bernoulli!Johann}|
% \end{quote}
% then it is probably reasonable to format this as
% \begin{quote}
%   Bernoulli,\\
%   \vadjust{}\quad Jacob\\
%   \vadjust{}\quad Johann
% \end{quote}
% but if the index entries instead were
% \begin{quote}
%   |\index{Jacobi!Carl}\index{Bernoulli!Jacob}|
% \end{quote}
% then it is probably better to format this as
% \begin{quote}
%   Bernoulli, Jacob\\
%   Jacobi, Carl
% \end{quote}
% than as
% \begin{quote}
%   Bernoulli,\\
%   \vadjust{}\quad Jacob\\
%   Jacobi,\\
%   \vadjust{}\quad Carl
% \end{quote}
% 
% The \program{makeindex} program has some features in this direction, 
% but they only allow dependence on the previous item in the index, not 
% the next item, which is what you need to know when deciding whether 
% `Jacob' should go on the same line as `Bernoulli'. Therefore 
% \package{docindex} pretty much ignores these features in 
% \program{makeindex} and instead sees to that each command that is to 
% typeset an index item knows what kind of items were before and after it.
% 
% Another reason for writing this package was to try out the template  
% mechanisms as provided by the \LaTeXplus\ \package{template} 
% package.\footnote{\LaTeXplus\ is the name of the \LaTeX\ version after 
% \LaTeXe. Rather than being a completely different kernel\slash format, 
% \LaTeXplus\ is (will be) implemented as a collection of \LaTeXe\ 
% packages which replace parts of the kernel. More information and 
% package code can be found on the \LaTeX-project website~^^A
% \cite{LaTeX-project}.} My impression is that this experiment turned 
% out strikingly well. I have always found the more layout-oriented 
% aspects of \TeX\ programming a bit cumbersome, but the separation of 
% layout details from control structures that becomes natural when 
% employing template mechanisms seems to have made it much easier. I'm 
% not sure why this is so, but it could be as simple as that the layout 
% settings are no longer diluted in the control structures. In any 
% case, I would recommend people creating new \LaTeXe\ packages to 
% employ template mechanisms in at least the initial development 
% versions of the package, for the following reasons: (i) it reduces the 
% work of updating the package for \LaTeXplus, (ii) it furthers the 
% development of \LaTeXplus, and (iii) it might actually become a 
% better package.
% 
% A third reason for writing the \package{docindex} package was to get 
% the \LaTeX\ document ``back in control'' of how the index is formatted. 
% Certainly it is the document which has the final say about what 
% the command in the \texttt{.ind} file actually do, but the traditional 
% \program{makeindex} style files that are used place severe restrictions 
% on the formatting of the index simply because they control where the 
% commands are put. \package{docindex} tries to reduce these 
% restrictions by making all texts in the index arguments of commands. 
% Certainly there is a lot more that could be done in this direction---in 
% particular, the (page) numbers in the index could be coded as a 
% |\do|-type list rather than as an explicitly comma-separated list as is 
% done now---but what is in \package{docindex} at the moment seems to 
% satisfy all my current needs.
% 
% 
% \section{Usage}
% 
% \subsection{Straightforward usage}
% 
% To make use of the \package{docindex} package in formatting the index 
% and list of changes of a \package{doc}-type \LaTeX\ document, you must 
% do the following:
% \begin{enumerate}
%   \item Load the \package{docindex} package (or probably 
%     rather the \package{docidx2e} package---see below).
%   \item Make sure that the index entries does not use any commands, 
%     such as |\verb|, that rely on changing catcodes or otherwise 
%     need to be executed before the entire entry text has been 
%     tokenized.
%   \item Generate the \texttt{.ind} and \texttt{.gls} files using 
%      \texttt{docindex.ist} as style file for \program{make\-index}.
% \end{enumerate}
% (Item~2 may seem like a monumental task if one considers what the 
% indices of \package{doc} documents traditionally looks like---there's 
% a  |\verb| for every macro name in the index---but it is really not 
% that bad. \package{docindex} loads the \package{xdoc} package~^^A
% \cite{xdoc} which redefines \texttt{macro}, the cross-referencing 
% mechanism, etc.\ so that the index entries generated by these no 
% longer uses |\verb|. What is left for you to deal with are merely 
% the possible uses of |\verb| in explicit |\index| or |\SortIndex| 
% commands.)
% 
% What advantages are there then for the normal user in having 
% \package{docindex} formatting the index and list of changes, as 
% opposed to using the default mechanisms in the \package{doc} package? 
% I can only think of two: the index or list of changes may be typeset in 
% a single column and the same \program{makeindex} style file can be 
% used for both index and list of changes. Neither advantage is 
% significant. Instead the advantage of \package{docindex} lies in that 
% it becomes much simpler to change the formatting, which is rather an 
% advantage for advanced users which have special needs, and 
% in particular one can do this without having to supply e.g.\ extra 
% \program{makeindex} style files.
% 
% Another important point is that what you will want to use is probably 
% not the \LaTeXplus\ \package{docindex} package, but the ``downgraded'' 
% \LaTeXe\ version \package{docidx2e}, as the former uses the 
% \package{galley2} package which currently wrecks pretty much all 
% justification in all existing document classes. \package{docidx2e} 
% provides the same features as \package{docindex}, but configuring it 
% is somewhat more cumbersome since \package{template} won't do most of 
% the coding for you. It is however rather straightforward to convert 
% a definition using the \package{docindex} package to something which 
% achieves the same results with the \package{docidx2e} package.
% 
% 
% \subsection{Multiple indices}
% 
% The \package{docindex} package makes it comparatively simple to 
% include several indices in the same document: all one has to do is 
% use an instance or template of type \texttt{docindex} for each index 
% one wishes to typeset. The syntax for using such an instance is
% \begin{quote}
%   |\UseInstance{docindex}|\marg{instance}\marg{prologue}^^A
%   \marg{epilogue}
% \end{quote}
% The \meta{prologue} and \meta{epilogue} are texts which will be 
% printed just before and after the index, respectively, and either may 
% be empty. The text for the index itself is read from another file, 
% the name and extentsion of which are specified by the instance. The 
% \texttt{std} template prints the \meta{prologue} and \meta{epilogue} 
% in one-column mode, whereas the index itself can be printed in one- or 
% multicolumn mode (the default is three columns).
% 
% The \package{doc} commands |\PrintIndex| and |\PrintGlossary| are 
% redefined to be
% \begin{quote}
%   |\UseInstance{docindex}{index}{\index@prologue}{}|
% \end{quote}
% and 
% \begin{quote}
%   |\UseInstance{docindex}{changes}{\glossary@prologue}{}|
% \end{quote}
% respectively. The \texttt{index} and \texttt{changes} instances of 
% type \texttt{docindex} give the same formatting as the \package{doc} 
% defaults. (The \package{docidx2e} definitions even use the 
% \package{doc} package parameters where applicable, but in 
% \package{docindex} it is much simpler to redefine the instance from 
% scratch.)
% 
% The format of the sorted index files (\texttt{.ind}, \texttt{.gls}, 
% etc.) that a \texttt{docindex} instance inputs is rather complicated 
% and I would suggest that the generation of these files is left to the 
% \program{makeindex} program, but the complete syntax is described in 
% Subsection~\ref{Ssec:ist}. The syntax of the unsorted index files 
% (\texttt{.idx}, \texttt{.glo}, etc.) is simpler; there are only a few 
% things that are different from the index files of the \package{doc} 
% package.
% 
% The foremost difference is that the index entries should begin not 
% with |\indexentry| or |\glossaryentry|, but with |\docindexentry|. The 
% \package{xdoc} package provides hooks with which one can change these 
% texts in entries generated using the |\index| and |\glossary| commands 
% (as well as higher-level commands built on these, such as the 
% |\SortIndex| and |\changes| commands) and \package{docindex} will use 
% these hooks unless it gets passed the \describeoption{oldkeywords}
% \texttt{oldkeywords} option. If you are creating a third unsorted 
% index file then you will have to make sure that the command for writing 
% to that file uses |\docindexentry| in the right place.
% 
% The other difference concerns the composite page numbers. The string 
% which separates the parts of a composite page number is not a 
% hyphen `|-|', but the string `|\+|'. (The |\+| command is locally 
% defined for the typesetting of each index by the \texttt{docindex} 
% template being used, and the default is to typeset a hyphen.) Again 
% the \package{xdoc} package provides a hook for this, and this hook is 
% used by \package{docindex} unless it gets passed the 
% \texttt{oldkeywords} option.
% 
% It also deserves to be listed which the metacharacters are that are 
% the same as in \package{doc} indices. The level separator is `|>|', 
% the sort~key\slash item~text separator is `|=|', and the quote 
% character is `|!|'. All other \program{makeindex} metacharacter 
% parameters have their default values.
% 
% 
% 
% \subsection{Configuration}
% 
% Configuration of the layout provided by the \package{docindex} 
% package is primarily done by redefining the \texttt{index} and 
% \texttt{changes} instances of type \texttt{docindex}, since these are 
% the instances that are used by the |\PrintIndex| and |\PrintChanges| 
% commands.
% 
% The index in the \texttt{source2e.tex} file (the main driver for the 
% \LaTeXe\ source) differs from the default in three respects: it is set 
% in two columns rather than three, there is no seperator character 
% between the parts of a composite page number, and the pagestyle is set 
% to \texttt{docindex} during the index. This is set up by the 
% redefinition
%\begin{verbatim}
%\DeclareInstance{docindex}{index}{std}{
%   columns=2, page-compositor={}, pagestyle=docindex
%}
%\end{verbatim}
% (There are however also some changes of parameters related to 
% linebreaking; more on that in connection to configuration of the 
% \texttt{changes} instance below.)
% 
% Another kind of modification can be found in the \package{tclldoc} 
% package~\cite{tclldoc}. Here the primary level in the index is used for 
% names of procedures and variables, whereas the secondary level for the 
% namespace of the same (the same name may have different definitions 
% in different namespaces). If there is only one namespace for a given 
% name then it is probably overkill to format them as two different 
% index items, but better to join them. This can be achieved through 
% the redefinition
%\begin{verbatim}
%\DeclareInstance{docindex}{index}{std}{%
%   item1=fixed-r1a, item2=aloneaccept2
%}%
%\end{verbatim}
% An item handled by the \texttt{fixed-r1a} instance (of type 
% \texttt{indexitem}) always tries to join with the following item but 
% rejects to join with the preceeding one. An item handled by the 
% \texttt{aloneaccept2} instance accepts to join with the preceeding 
% item if neither that nor the following item is a secondary level item. 
% Thus an item for a name will join with the following item for a 
% namespace if there is only one such item. As the reader no doubt 
% realises, this also solves the problem with the Bernoullis that was 
% described in the introduction.
% 
% \pagebreak[1]
% 
% As for configuring the list of changes formatting, it is instructive 
% to start by considering its default definition:
%\begin{verbatim}
%\DeclareInstance{docindex}{changes}{std}{
%   file-extension = gls,
%   item2 = fixed-r2a-nocomma,
%   item3 = fixed-a3r,
%   columns = 2, 
%   letter-format = ,
%   letter-skip = 0pt
%}
%\end{verbatim}
% In the list of changes a secondary level item (which contains the name 
% of the macro or whatever which was changed) is joined with the 
% following tertiary level item (which details the change that was made). 
% There are two columns and letter groups are not given any special 
% formatting.
% 
% The definition of \texttt{changes} that would be used for 
% \texttt{source2e.tex} differs from the above in only one keyval, 
% namely \textit{body-setup}, but that contains quite a lot of material. 
% To begin with there is the default |\small| which selects the font. 
% Then there is a |\makeatletter| which is needed because some |\changes| 
% entries in the \LaTeX\ sources include commands (e.g.~|\TeX|) that 
% (when written to file) expand to other commands whose names include the 
% |@| character. If these are to be tokenized correctly, |@| must be a 
% letter when the \texttt{.gls} file is being inputted. Last, but not 
% least, there is a modification of the linebreaking parameters:
%\begin{verbatim}
%\UseTemplate{linebreak}{TeX}{
%\end{verbatim}
% The file \texttt{source2e.tex} explicitly sets \textit{hbadness} and 
% \textit{hfuzz} to make \TeX\ shut up about over- and underfull hboxes.
%\begin{verbatim}
%   hbadness=10000, hfuzz=\maxdimen,
%\end{verbatim}
% In addition to this, there are a couple of parameters that are set by 
% the \texttt{multicols} environment to values quite different from the 
% defaults of the \texttt{TeX} template and thus must be set too. Here 
% they are shown with their default values. The value of 
% \textit{emergency\-stretch} could probably be increased.
%\begin{verbatim}
%   pretolerance=-1, tolerance=9999, emergencystretch=8pt
%}
%\end{verbatim}
% Summing that up, we arrive at the following definition of the
% \texttt{changes} instance for \texttt{source2e.tex}.
%\begin{verbatim}
%\DeclareInstance{docindex}{changes}{std}{
%   file-extension = gls,
%   item2 = fixed-r2a-nocomma,
%   item3 = fixed-a3r,
%   columns = 2, 
%   letter-format = ,
%   letter-skip = 0pt,
%   body-setup = \small\makeatletter
%      \UseTemplate{linebreak}{TeX}{
%         hbadness=10000, hfuzz=\maxdimen,
%         pretolerance=-1, tolerance=9999, emergencystretch=8pt
%      }
%}
%\end{verbatim}
% 
% Another example can be found in the \package{fisource} 
% package\footnote{It should probably rather be made a document class, 
% but I haven't found it that necessary to change that aspect of it.}^^A
% ~(v\,2.10 or later), which sets up formatting for the \program{fontinst} 
% source. There the list of changes should be set in one column, with 
% items from the tertiary level being joined with their parent 
% secondary level items iff the tertiary item is the only one having 
% that particular parent item. This is achieved through the definition
%\begin{verbatim}
%\DeclareInstance{docindex}{changes}{std}{%
%    file-extension = gls,
%    item2 = fixed-r2a-nocomma,
%    item3 = aloneaccept3,
%    columns = 1,
%    letter-format = {},
%    letter-skip = 0pt
% }
%\end{verbatim}
% where the difference to the default definition is in the values for 
% the \textit{item3} and \textit{columns} keys.
% 
% For details on what they various keys mean, see the declaration of 
% the \texttt{std} template of type \texttt{docindex} on 
% page~\pageref{docindex:std}.
% 
% With the \package{docidx2e} package, configuration follows the same 
% logic, even though it is much more technical as one has to define 
% the instances without the help of a template. The default instance 
% definitions for the \package{docidx2e} package are the
% \begin{quote}
%   |\@namedef{TP@I{}{docindex}{index}}#1#2{|\dots|}|\\
%   |\@namedef{TP@I{}{docindex}{changes}}#1#2{|\dots|}|
% \end{quote}
% that begin on pages~\pageref{p:index-instance} 
% and~\pageref{p:changes-instance} respectively.
% 
% 
% 
% 
% 
% \StopEventually{
% %    \begin{thebibliography}{9}
%    \bibitem{xindex}
%      Achim Blumensath: \textit{The \package{xindex} package};
%      \textsc{http:}/\slash 
%      \texttt{www-mgi.\nolinebreak[3]informatik.\nolinebreak[3]^^A
%      rwth-aachen.de}\slash \texttt{\textasciitilde blume}/.
%    \bibitem{makeindex-paper}
%      Pehong Chen, Michael A. Harrison:
%      \textit{Index Preparation and Processing},
%      Software: practice \& experience, vol. \textbf{19}, no. 9 (1988),
%      897--915; 
%      Computer Science Tech. Report 87/347, University of California,
%      Berkeley, March 1987;
%      \textsc{ctan:}\discretionary{}{}{\thinspace}\texttt{indexing}^^A
%      \slash\texttt{makeindex}\slash\texttt{paper}\slash
%      \texttt{ind.tex}.
%    \bibitem{tclldoc}
%      Lars Hellstr\"om: 
%      \textit{The \package{tclldoc} package and class},
%      v\,2.20 or newer;
%      \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%      \texttt{latex}\slash \texttt{contrib}\slash 
%      \texttt{tclldoc}\slash \texttt{tclldoc.dtx}. 
%      Note: At the time of writing, this has not yet been uploaded 
%      to CTAN.
%    \bibitem{xdoc}
%      Lars Hellstr\"om:
%      \textit{The \package{xdoc} package --- experimental 
%        reimplementations of features from \package{doc}, 
%        second~prototype}, 2000--2003;
%      \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
%      \texttt{latex}\slash \texttt{contrib}\slash \texttt{xdoc}\slash
%      \texttt{xdoc2.dtx}.
%    \bibitem{xindy}
%      Roger Kehr: 
%      \textit{\program{xindy} --- A Flexible Indexing System};
%      \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{indexing}^^A
%      \slash\texttt{xindy}/.
%    \bibitem{LaTeX-project}
%      The \LaTeX3 Project: \textit{The \LaTeX\ Project Home Page};
%      \textsc{http:}/\slash\texttt{www.latex-project.org}/.
%    \bibitem{multicol}
%      Frank Mittelbach: \textit{An environment for multicolumn output};
%      \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
%      \texttt{latex}\slash \texttt{required}\slash \texttt{tools}\slash
%      \texttt{multicol.dtx}.
%    \bibitem{doc}
%      Frank Mittelbach, B.~Hamilton Kelly, Andrew Mills, Dave Love, and 
%      Joachim \mbox{Schrod}: \textit{The \package{doc} and 
%      \package{shortvrb} Packages}, The \LaTeX3 Project; ^^A , 1993~ff. 
%      \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%      \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}.
%    \end{thebibliography}
% }
% 
% 
% 
% 
% \section{Implementation}
% 
% \subsection{\package{docstrip} modules}
% 
% This file contains a number of \package{docstrip} module directives, 
% and many of these guard code that is not going to be used. In part 
% this mirrors the development of the code (and may get cleared up 
% eventually), but most of this duplication has to do with making the 
% code work in many different set-ups (some of which involve other 
% packages whose interface is rapidly changing).
% 
% The modules which control \LaTeX\ code are:
% \begin{description}
%   \item[\textsf{pkg}]
%     Main guard for code that is to end up in some \LaTeX\ package.
%   \item[\textsf{template}]
%     Guard for code which uses features of the \package{template} 
%     package. This code will end up in the \package{docindex} package, 
%     whereas the equivalent code which avoids using templates ends up 
%     in the \package{docidx2e} package.
%   \item[\textsf{default}]
%     This code protects the default values for template keys. The 
%     syntax for this is changing, so the default values are currently 
%     being assigned in the template bodies instead.
% \end{description}
% 
% The modules which control \program{makeindex} style files are:
% \begin{description}
%   \item[\textsf{ist}]
%     Code for the main style file \texttt{docindex.ist}.
%   \item[\textsf{idx}]
%     Code for a style file which is like the main one, but the input 
%     parameters are set to the same values as in the standard \LaTeX\ 
%     \texttt{gind.ist}.
%   \item[\textsf{glo}]
%     Code for a style file which is like the main one, but the input 
%     parameters are set to the same values as in the standard \LaTeX\ 
%     \texttt{gglo.ist}.
% \end{description}
% 
% 
% \subsection{Initial stuff}
% 
%    \begin{macrocode}
%<*pkg>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage
%<template>   {docindex}
%<!template>   {docidx2e}
   [2001/04/11 v1.00 doc index formatting package]
%    \end{macrocode}
%    
% Since the \texttt{multicols} environment is used by the \texttt{std} 
% template of type \texttt{docindex}, the \package{multicol} package 
% must have been loaded.
%    \begin{macrocode}
\RequirePackage{multicol}
%    \end{macrocode}
% This will probably change in \package{docindex} once I get around to 
% check how this kind of thing is implemented in the \LaTeXplus\ output 
% routine.
% 
% Since the \texttt{docindex} pagestyle may be used the \package{xdoc} 
% package must have been loaded. This also loads the \package{doc} 
% package which contains the definition of |\pfill|.
%    \begin{macrocode}
\RequirePackage{xdoc2}[2001/03/26]
%    \end{macrocode}
% 
% 
% \begin{option}{oldkeywords}
%   The \texttt{oldkeywords} option tells the \package{docindex} 
%   package to not change the index entry keywords from the \package{doc} 
%   defaults. The code for this option appears further down.
%    \begin{macrocode}
\DeclareOption{oldkeywords}{}
%    \end{macrocode}
% \end{option}
% 
% \begin{option}{usedocindexps}
%   The \texttt{usedocindexps} option tells the \package{docindex} 
%   package to set the pagestyle to \texttt{docindex} (defined by 
%   \package{xdoc}) when typesetting the index. The code for this option 
%   appears further down.
%    \begin{macrocode}
\DeclareOption{usedocindexps}{}
%    \end{macrocode}
% \end{option}
% 
%    \begin{macrocode}
\ProcessOptions\relax
%</pkg>
%    \end{macrocode}
% 
% 
% 
% \subsection{Index style files}
% \label{Ssec:ist}
% 
% The \program{makeindex} style files uses four commands. The most 
% important command is \DescribeMacro{\indexitem}|\indexitem|, which 
% has the two syntaxes
% \begin{quote}
%   |\indexitem|\marg{level}\marg{text}\marg{next level}\\
%   |\indexitem|\marg{level}\marg{text}|{9}|\marg{numbers}^^A
%     \marg{next level}  
% \end{quote}
% The \meta{level} is an integer in the range 1--3, the \meta{next level} 
% is an integer in the range 0--3, the \meta{text} is the item text, 
% and the \meta{numbers} is a list of (page or the like) numbers. The 
% reason for this dual syntax is limitations of \program{makeindex}: 
% there is no way of making the text inserted after an item depend on 
% whether there are any page numbers for this item, so one cannot make 
% \meta{numbers} a straightforward optional argument.
% 
% The level numbers specify at what level the item is. Level~1 
% corresponds to |\item|, level~2 corresponds to |\subitem|, and 
% level~3 corresponds to |\subsubitem|. The \meta{next level} number 
% may also be 0, and that denotes non-|\indexitem| material such as a 
% space between letter groups or the end of the index. The purpose of 
% the \meta{next level} argument is to let the formatting of an item 
% depend on what level the next item has, a feature that 
% \program{makeindex} alone doesn't provide. Since \program{makeindex} 
% only supports putting text in front of things, each new item must 
% begin by inserting the closing brace on the second last argument and 
% the very last argument of the \emph{previous} item before it can do 
% anything for itself. This leads to the following contents of the 
% \program{makeindex} |item_|\textellipsis\ parameters.
% 
% \xrefoff
%    \begin{macrocode}
%<*ist|idx|glo>
item_0  "}{1}\n\\indexitem{1}{"
item_1  "}{2}\n  \\indexitem{2}{"
item_01 "}{2}\n  \\indexitem{2}{"
item_x1 "}{2}\n  \\indexitem{2}{"
item_2  "}{3}\n    \\indexitem{3}{"
item_12 "}{3}\n    \\indexitem{3}{"
item_x2 "}{3}\n    \\indexitem{3}{"
%    \end{macrocode}
% \SpecialIndex{\indexitem} ^^A I can't believe I'm using this!
%    \begin{macrocode}
delim_0 "}{9}{"
delim_1 "}{9}{"
delim_2 "}{9}{"
delim_n ", "
delim_r "--"
%</ist|idx|glo>
%    \end{macrocode}
% \xrefon
% 
% 
% \begin{macro}{\indexitem}
% \begin{macro}{\DI@indexitem}
% \begin{macro}{\DI@indexitem@}
% \begin{macro}{\DI@last@level}
%   The |\indexitem| command (and its subsidiary macros |\DI@indexitem| 
%   and |\DI@indexitem@| only handle argument grabbing and some 
%   elementary processing of level numbers. The formatting of the item 
%   is instead handled by the |\DI@indexitem@|\meta{level}, where 
%   \meta{level} is the roman numeral |i|, |ii|, or |iii|, family of 
%   control sequences. |\indexitem| itself doesn't grab any arguments, 
%   instead it inserts the contents of |\DI@last@level| as an 
%   additional argument in front of |\DI@indexitem|. The actual 
%   argument structures of the other macros are
%   \begin{quote}
%     |\DI@indexitem|\marg{last}\marg{this}\marg{text}^^A
%       \marg{next/\texttt{9}}\\
%     |\DI@indexitem@|\marg{cmd}\marg{last}|{9}|\marg{text}^^A
%       |\NoValue|\marg{figures}\marg{next}
%   \end{quote}
%   where \meta{this} is the level of this item, \meta{next} is the 
%   level of the next item, \meta{text} is the item text, and 
%   \meta{figures} are the (page) numbers for this item. Several of the 
%   arguments of |\DI@indexitem@| are immediately gobbled; they are 
%   only used when the original |\indexitem| did not have a 
%   \meta{numbers} argument.
%   
%   The |\DI@last@level| macro stores the level of the last item before 
%   the current. It is set and used by |\DI@indexitem@|.
%    \begin{macrocode}
%<*pkg>
\newcommand\indexitem{%
   \relax
   \expandafter\DI@indexitem \expandafter{\DI@last@level}%
}%
%    \end{macrocode}
%    \begin{macrocode}
\def\DI@indexitem#1#2#3#4{%
   \edef\DI@last@level{\number#2\expandafter}%
   \ifnum #4=9
      \expandafter\expandafter \expandafter\DI@indexitem@
   \fi
   \csname DI@indexitem@\romannumeral#2\expandafter\endcsname
      {#1}{#4}{#3}\NoValue
}
%    \end{macrocode}
%    \begin{macrocode}
\def\DI@indexitem@#1#2#3#4#5#6#7{#1{#2}{#7}{#4}{#6}}
%    \end{macrocode}
%    \begin{macrocode}
\def\DI@last@level{0}
%</pkg>
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% The \describecsfamily{DI@indexitem@\meta{level}}|\DI@indexitem@|^^A
% \meta{level}, where \meta{level} is the lower case roman numeral form 
% of the level number, family of control sequences have the syntax
% \begin{quote}
%   |\DI@indexitem@|\meta{level}\,\marg{previous}\marg{next}^^A
%   \marg{text}\marg{figures}
% \end{quote}
% where \meta{previous} and \meta{next} are the levels of the previous 
% and following index items, \meta{text} is the entry text of this 
% item, and \meta{figures} are the (page) numbers for this item, if it 
% has any, or the token |\NoValue|, if it hasn't.
% 
% 
% \xrefoff
%    \begin{macrocode}
%<*ist|idx|glo>
group_skip     "}{0}\n%^^A\n\\indexnewletter{0}{"
heading_prefix ""
heading_suffix ""
headings_flag  1
%</ist|idx|glo>
%    \end{macrocode}
% \SpecialIndex{\indexnewletter}
% \xrefon
% 
% 
% \begin{macro}{\indexnewletter}
%   \changes{v\,1.00}{2001/04/05}{Made it \cs{outer}. (LH)}
%   The |\indexnewletter| command is placed in front of a new letter 
%   group. It has the syntax
%   \begin{quote}
%     |\indexnewletter|\marg{first}\marg{letter}\marg{next}
%   \end{quote}
%   where \meta{first} is a flag (|1| if this |\indexnewletter| 
%   is at the very beginning of the index, |0| otherwise), \meta{letter} 
%   is the letter name (according to the \program{makeindex} program; it 
%   can be e.g.\ the string `Symbols') and \meta{next} is the level of 
%   the next item (I think this will always be |1| with 
%   \program{makeindex}). The command takes care of declining an offer 
%   to join with the previous index item, inserts some vertical space 
%   if the \meta{first} is |0|, print the \meta{letter} using 
%   |\DI@letter@format|, and doesn't offer to join with the following 
%   item.
%    \begin{macrocode}
%<*pkg>
\@ifundefined{indexnewletter}{}{%
   \PackageInfo
%<template>      {docindex}
%<!template>      {docidx2e}
      {Command \protect\indexnewletter\space redefined}
}
\outer\def\indexnewletter#1#2#3{%
   \DI@item@nojoin
   \ifnum #1=\z@ \vspace{\DI@letter@skip}\fi
   \DI@letter@format{#2}%
   \def\DI@last@level{0}%
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
}
%</pkg>
%    \end{macrocode}
% \end{macro}
% 
% The index style files also need to set some parameters which aren't 
% directly connected to the commands provided by the \package{docindex} 
% package. First there's the input style parameters:\xrefoff
%    \begin{macrocode}
%<*ist|idx|glo>
actual '='
quote '!'
level '>'
%    \end{macrocode}
% Then the page precedence should be changed. This is mainly for the 
% convenience of use with documents that |\DocInclude| files, since 
% these by default number the files using letters.
%    \begin{macrocode}
page_precedence  "naArR"
%    \end{macrocode}
% In \texttt{docindex.ist}, both the \texttt{keyword} and the 
% |page_compositor| strings are different from their standard values. It 
% turns out to be hard to use a normal command as page compositor, 
% because \program{makeindex} always rejects spaces and braces in the 
% page number even if they is in the |page_compositor| parameter!
%    \begin{macrocode}
%<ist>keyword "\\xdocindexentry"
%<ist>page_compositor "\\+"
%    \end{macrocode}
% \SpecialIndex{\+}
% Finally, in the style file for the list of changes, the keyword must 
% be changed to |\glossaryentry|.
%    \begin{macrocode}
%<glo>keyword "\\glossaryentry"
%</ist|idx|glo>
%    \end{macrocode}
% \xrefon
% 
% 
% \begin{option}{oldkeywords}
% \begin{macro}{\XD@index@keyword}
% \begin{macro}{\XD@glossary@keyword}
% \begin{macro}{\XD@page@compositor}
%   \changes{v\,1.00}{2001/04/05}{Changed it from \cs{PageCompositor-} to 
%      \cs{+}. (LH)}
%   To make the contents of the \texttt{.idx} and \texttt{.glo} files 
%   compatible with the input parameter settings of 
%   \texttt{docindex.ist}, some macros used by the \package{xdoc} 
%   package must be redefined. This can however be stopped if the 
%   \texttt{oldkeywords} option is passed to the \package{docindex} 
%   package.
%    \begin{macrocode}
%<*pkg>
\@ifpackagewith
%<template>   {docindex}
%<!template>   {docidx2e}
   {oldkeywords}{}{
   \edef\XD@index@keyword{\@backslashchar xdocindexentry}
   \let\XD@glossary@keyword\XD@index@keyword
   \def\XD@page@compositor{\@backslashchar +}
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{option}
% 
% \changes{v\,1.00}{2001/03/25}{The index file is no longer a 
%    \texttt{thedocindex} environment---the layout must instead be set 
%    by the command which \cs{input}s the index. Introduced the 
%    \cs{docindexguard} command to handle situations with incompatible 
%    index styles. (LH)}
% 
% \begin{macro}{\docindexguard}
% \begin{macro}{\DI@ind@setup}
%   The first line of every \texttt{docindex} style sorted index file is
%   \begin{quote}
%     |\docindexguard{\endinput}|
%   \end{quote}
%   If the index file is inputted as a classical sorted index file then 
%   this will produce an undefined command error and no more lines in 
%   the index will be read. If the index file is inputted using the 
%   conventions of the \package{docindex} package then the 
%   |\docindexguard| will instead gobble the |\endinput| so that the 
%   file will be read.
%   
%   One can also have the opposite problem: a classical style index file 
%   is being input using \package{docindex} conventions. It is to 
%   overcome this problem that the |\DI@ind@setup| command has been 
%   introduced. Classical style index files begin by a |\begin| 
%   command, so that command is temporarily redefined to print a warning 
%   message and |\endinput| the file. Should the first command instead 
%   be |\docindexguard| then everything will be reset to normal. To 
%   accomplish this, |\DI@ind@setup| opens a group which should be 
%   closed by the initial |\docindexguard| or |\begin|.
%    \begin{macrocode}
\def\DI@ind@setup{\bgroup
   \def\docindexguard##1{\egroup}%
   \def\begin##1{%
      \egroup
      \PackageWarningNoLine
%<template>         {docindex}%
%<!template>         {docidx2e}%
         {Ignoring old style index file}
      \endinput
   }%
}
%</pkg>
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \xrefoff
%    \begin{macrocode}
%<*idx|glo|ist>
preamble  "\\docindexguard{\\endinput}\n%^^A\n\\indexnewletter{1}{"
postamble "}{0}\n\\endinput"
%</idx|glo|ist>
%    \end{macrocode}
% \SpecialIndex{\docindexguard}
% \SpecialIndex{\indexnewletter}
% \xrefon
% 
% In summary, this is the BNF syntax for a sorted index file that is to 
% be typeset using \package{docindex}:
% \begin{syntax}
%   \item[sorted index file]
%     \meta{guard}\meta{lettergroups}|\endinput|
%   \item[guard] |\docindexguard{\endinput}|
%   \item[lettergroups] \meta{lettergroup}\branch 
%     \meta{lettergroup}\meta{lettergroups}
%   \item[lettergroup] \meta{heading}\meta{items}
%   \item[heading] 
%     |\indexnewletter|\marg{first}\marg{letter}\marg{next}
%   \item[items] \meta{empty}\branch \meta{item}\meta{items}
%   \item[item] |\indexitem|\marg{level}\marg{text}\marg{next}\branch
%     |\indexitem|\marg{level}\marg{text}|{9}|\marg{numbers}\marg{next}
% \end{syntax}
% A \meta{level} is |1|, |2|, or |3|. A \meta{next} is |0|, |1|, |2|, or 
% |3|. Within a \meta{lettergroup}, the \meta{next} of one \meta{item} 
% or the \meta{heading} must equal the \meta{level} of the next 
% \meta{item} and the \meta{next} of the last item must be |0|. The 
% \meta{first} should be |1| in the first \meta{lettergroup} and |0| in 
% all the others.
% 
% 
% \subsection{Template mechanisms}
% 
% The \package{docindex} package loads the \package{xhj} and 
% \package{galley2} packages to gain access to the \texttt{justification} 
% type templates. This indirectly loads the \package{xparse} and 
% \package{template} packages.
%    \begin{macrocode}
%<*pkg>
%<template>\RequirePackage{xhj,galley2}
%    \end{macrocode}
% 
% Since the \package{docidx2e} package doesn't use the template mechanisms 
% provided by the \package{template} package, but still is to follow the 
% logic of the \package{docindex} package which does use these 
% mechanisms, it becomes convenient to define fakes for a couple of 
% \package{template} commands. First \package{docidx2e} checks if the 
% real \package{template} package has been loaded and emits a warning if 
% it has.
%    \begin{macrocode}
%<*!template>
\@ifpackageloaded{template}{
   \PackageWarningNoLine{docidx2e}{The docidx2e package is only meant%
      \MessageBreak for use when LaTeX2e* packages like 
      template\MessageBreak are not available.}
}{}
%    \end{macrocode}
% 
% Before continuing with the definitions, some of the data structures 
% used by the \package{template} mechanisms must be explained. A 
% template \emph{instance} is really only a macro; what makes instances 
% different from macros in general is that they usually aren't 
% explicitly programmed. Instead they are formed by combining two 
% different pieces of code: one which is the code part of some template, 
% and one which is a piece of code which sets the \emph{container} 
% macros\slash registers\slash parameters for the key values of this 
% template. In general, the first piece of code contains the 
% programming-like aspects of what the instance does, whereas the latter 
% contains those that have to do with lauout and design. The advantage 
% of this model is that it lets you implement many layouts without 
% requiring you to know everything about \LaTeX\ programming that it 
% would take to implement everything using macros.
% 
% Instances are stored in control sequences of the form
% \begin{quote}
%   \describecsfamily{TP@I{\meta{collection}}\break
%      {\meta{type}}\break{\meta{name}}}
%   |\TP@I|\marg{collection}\marg{type}\marg{name}
% \end{quote}
% The \meta{type} is the primary distinction between instances; for each 
% type there exists a specification of what all instances of that type 
% must do, and all instances of a type must be interchangeable. In 
% particular, all instances of a given template type must have the same 
% argument structure. The \meta{name} is simply the name used to 
% identify the instance (amongst all other instances of that type). 
% Finally, the \meta{collection} is something which can be used in 
% circumstances where one needs to quickly switch between different 
% definitions of an instance. If they have different \meta{collection}s 
% then they can exist simutaneously; which of them is used is determined 
% by which collection is currently active.
% 
% Collections are active on a ``per type'' basis; which collection is 
% active for instances of type \meta{type} is determined by the 
% contents of the \describecsfamily{TP@T{\meta{type}}} 
% |\TP@T|\marg{type} control sequences, which are macros with the 
% structure
% \begin{quote}
%   \marg{collection}\marg{arguments}
% \end{quote}
% If there is no instance with the requested name in the currently 
% active collection then the instance with the same name from the 
% normal collection (whose name is the empty string) will be used. The 
% \meta{arguments} part of the macro is simply the number of arguments 
% of instances of this type; it is only used when declaring templates.
% 
% \begin{macro}{\UseCollection}
%   The |\UseCollection| command sets the active collection for a given 
%   type. It has the syntax
%   \begin{quote}
%     |\UseCollection|\marg{type}\marg{collection}
%   \end{quote}
%   This macro was used up to v\,1.00 of \package{docindex} but a change 
%   in the package logic made it unnecessary.
%    \begin{macrocode}
% \providecommand*\UseCollection[2]{%
%    \expandafter\edef \csname TP@T{#1}\endcsname{%
%       {#2}%
%       {\expandafter\expandafter \expandafter\@secondoftwo
%          \csname TP@T{#1}\endcsname}%
%    }%
% }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@letinstance}
%   The |\@letinstance| macro |\let|s the (currently used) instance 
%   with given name and type to the \meta{target} control sequence. It 
%   has the syntax
%   \begin{quote}
%     |\@letinstance|\marg{target}\marg{type}\marg{name}
%   \end{quote}
%    \begin{macrocode}
\def\@letinstance#1#2#3{%
   \expandafter\let \expandafter#1%
      \csname TP@I%
         {\expandafter\expandafter \expandafter\@firstoftwo
            \csname TP@T{#2}\endcsname}%
         {#2}{#3}%
      \endcsname
   \ifx \relax#1%
      \expandafter\let \expandafter#1\csname TP@I{}{#2}{#3}\endcsname
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\UseInstance}
%   The |\UseInstance| calls the (currently used) instance with given 
%   name and type. Its syntax is
%   \begin{quote}
%     |\UseInstance|\marg{type}\marg{name}\,\meta{arguments of instance}
%   \end{quote}
%    \begin{macrocode}
\providecommand*\UseInstance[2]{%
   \@letinstance\@tempa{#1}{#2}%
   \ifx \relax\@tempa
      \PackageError{docidx2e}{Instance #2 of type #1 undefined}\@eha
   \else
      \expandafter\@tempa
   \fi
}
%</!template>
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \subsection{Templates for index item formatting}
% 
% \begin{templatetype}{justification}
%   In \package{docidx2e}, we have to provide a dummy definition of 
%   |\TP@T{justification}|.
%    \begin{macrocode}
%<!template>\@namedef{TP@T{justification}}{{}{0}}
%    \end{macrocode}
% \end{templatetype}
% 
% \changes{v\,1.00}{2001/04/08}{Using \texttt{single} template rather 
%    than the \texttt{std} template for the \texttt{indexitem}$n$ 
%    instances of type \texttt{justification}. (LH)}
% \begin{instance}{justification}{indexitem1}
% \begin{instance}{justification}{indexitem2}
% \begin{instance}{justification}{indexitem3}
%   The \texttt{indexitem}\meta{level} instances of the 
%   \texttt{justification} template set up paragraph indentation etc.\ 
%   for a paragraph containing an index item at that level. The layout 
%   is the same as that used by the \package{doc} package, but it is 
%   not specified in quite the same way.
%    \begin{macrocode}
%<*template>
\DeclareInstance{justification}{indexitem1}{single}{
   leftskip=30pt, rightskip=15pt, startskip=-30pt, parfillskip=-15pt,
   linefillskip=0pt plus 1fil, parindent=0pt
}
\DeclareInstance{justification}{indexitem2}{single}{
   leftskip=30pt, rightskip=15pt, startskip=-15pt, parfillskip=-15pt,
   linefillskip=0pt plus 1fil, parindent=0pt
}
\DeclareInstance{justification}{indexitem3}{single}{
   leftskip=30pt, rightskip=15pt, startskip=-5pt, parfillskip=-15pt,
   linefillskip=0pt plus 1fil, parindent=0pt
}
%</template>
%<*!template>
\@namedef{TP@I{}{justification}{indexitem1}}{%
   \leftskip=30\p@
   \rightskip=15\p@
   \parindent=-30\p@
   \parfillskip=-\rightskip
}
\@namedef{TP@I{}{justification}{indexitem2}}{%
   \leftskip=30\p@
   \rightskip=15\p@
   \parindent=-15\p@
   \parfillskip=-\rightskip
}
\@namedef{TP@I{}{justification}{indexitem3}}{%
   \leftskip=30\p@
   \rightskip=15\p@
   \parindent=-5\p@
   \parfillskip=-\rightskip
}
%</!template>
%    \end{macrocode}
% \end{instance}\end{instance}\end{instance}
% 
% 
% 
% \subsubsection{The \texttt{indexitem} template type}
% 
% \begin{templatetype}{indexitem}
% \begin{macro}{\DI@item@nojoin}
% \begin{macro}{\DI@item@join}
%   The argument structure of a template of type \texttt{indexitem} is
%   \begin{quote}
%     \marg{previous}\marg{next}\marg{text}\marg{figures}
%   \end{quote}
%   \meta{previous} and \meta{next} are the level codes of the index 
%   item before and after the current item, \meta{text} is the item text 
%   of the current index item, and \meta{figures} are the  (page) numbers 
%   for this item, if it has any, or the token |\NoValue|, if it hasn't.
% 
%   Templates of this type format and typeset one item in an index. In 
%   doing so they may do pretty much anything as long as the other items 
%   aren't affected: they may start and end paragraphs, change the 
%   paragraph justification, \textellipsis
%   
%   There is however one area in which the rules are rather strict, and 
%   that has to do with when two items can be joined. In a case where 
%   item A is followed by item B, item A can propose to item B that they 
%   should be joined and item B can then accept or decline this offer. 
%   Technically the offer consists of defining the two macros 
%   |\DI@item@join| and |\DI@item@nojoin|. If item B accepts the offer 
%   it will execute |\DI@item@join| and if it declines the offer it 
%   will execute |\DI@item@nojoin|. A typical definition of 
%   |\DI@item@join| might be to insert a punctuation mark and a typical 
%   definition of |\DI@item@nojoin| might be to end the current paragraph.
%   
%   There is however also a third case, namely that no offer was given. 
%   In this case |\DI@item@nojoin| should be |\let| to |\@empty| and 
%   |\DI@item@join| should be |\let| to |\@firstofone|. The reason for 
%   this last rule is that |\DI@item@join| has the syntax
%   \begin{quote}
%     |\DI@item@join|\marg{no-join recovery code}
%   \end{quote}
%   where the \meta{no-join recovery code} is code that item B needs to 
%   have executed if there is no join although item B would have 
%   accepted it. |\DI@item@nojoin|, on the other hand, takes no 
%   argument.
%    \begin{macrocode}
%<template>\DeclareTemplateType{indexitem}{4}
%<!template>\@namedef{TP@T{indexitem}}{{}{4}}
\let\DI@item@join=\@firstofone
\let\DI@item@nojoin=\@empty
%    \end{macrocode}
% \end{macro}\end{macro}\end{templatetype}
% 
% \begin{template}{indexitem}{fixed}
%   The \texttt{fixed} template of type \texttt{indexitem} formats an 
%   item as the items in \package{doc}'s \texttt{theindex} environment. 
%   It is fixed in that it ignores the levels of the surrounding items.
%   
%   The keys for this template are:
%   \begin{description}
%     \keyvalitem{justification-setup}{i}
%       This is a template instance of type \texttt{justification}. It 
%       sets the justification for the paragraph containing the item, 
%       unless the item is being joined with the preceeding item.
%     \keyvalitem{pre-join}{b}
%       A switch for whether the item should accept to be joined with 
%       the item before. True means ``accept'', false means ``decline'' 
%       (which is the default).
%     \keyvalitem{nofig-action}{f1}
%       If the \meta{figures} argument is |\NoValue| then the \meta{text} 
%       argument is passed on to this macro for the actual formatting. 
%       The default expansion is precisely the \meta{text}.
%     \keyvalitem{fig-action}{f2}
%       If the \meta{figures} argument is not |\NoValue| then the 
%       \meta{text} and \meta{figures} arguments are passed on (in that 
%       order) to this macro for the actual formatting. The default 
%       expansion is
%       \begin{quote}
%         \meta{text}|\pfill|\meta{figures}
%       \end{quote}
%     \keyvalitem{post-join}{b}
%       A switch for whether the item should offer to join with the 
%       following item. True means ``make offer'', false (which is the 
%       default) means ``don't make offer''. Making the offer is 
%       furthermore conditioned by that the \meta{figures} argument is 
%       |\NoValue|.
%     \keyvalitem{nojoin-extra}{f0}
%       Extra code which is inserted after the normal code for an item 
%       if the item neither has any figures nor offers to join with the 
%       following item. The default value is a space of length 
%       \textit{linefillskip} followed by a |\nopagebreak|.^^A
%       \changes{v\,0.03}{2001/02/24}{Added the \textit{nojoin-extra} 
%          key. (LH)}^^A
%       \changes{v\,0.03}{2001/02/25}{Added \cs{nopagebreak} from 
%         \cs{efill} to default for \textit{nojoin-extra} key. (LH)}
%     \keyvalitem{join-extra}{f0}
%       Extra text which is inserted after the normal text of the item 
%       if there is a join, by default a comma and a space.
%     \keyvalitem{offjoin-extra}{f0}
%       Extra code which is inserted after the normal text of the item 
%       if a join is offered but declined. The default value is a space 
%       of length \textit{linefillskip} followed by a |\nopagebreak| 
%       (larger than the one from \textit{nojoin-extra}; if not for 
%       this, the default could have been taken to be 
%       |\DI@nojoin@extra|).
%   \end{description}
%   
%   Note that the contents of the \textit{nojoin-extra}, 
%   \textit{join-extra}, and \textit{offjoin-extra} keys must be robust 
%   as they may be subjected to a |\protected@edef|.
%   \changes{v\,0.03}{2001/02/24}{\cs{protected@edef}ing the macros
%     \cs{DI@item@join} and \cs{DI@item@nojoin}. (LH)}
%   
%    \begin{macrocode}
%<*template>
\DeclareTemplate{indexitem}{fixed}{4}{
   justification-setup =i{justification}      \DI@item@justification,
   pre-join      =b  
%<default>           {false}
                                               DI@prejoin@,
   nofig-action  =f1 
%<default>           {#1}
                                              \DI@nofig,
   fig-action    =f2 
%<default>           {#1\pfill#2}
                                              \DI@hasfig,
   post-join     =b  
%<default>           {false}
                                               DI@postjoin@,
   nojoin-extra    =f0 
%<default>           {\hspace*{\justification@g}
%<default>            \protect\nopagebreak[2]}
                                              \DI@nojoin@extra,
   join-extra    =f0 
%<default>           {,\space}
                                              \DI@join@extra,
   offjoin-extra =f0 
%<default>           {\hspace*{\justification@g}
%<default>            \protect\nopagebreak[4]}
                                              \DI@offjoin@extra
}{%
%<*!default>
   \let\ifDI@prejoin@\iffalse
   \let\DI@nofig\@firstofone
   \def\DI@hasfig##1##2{##1\pfill##2}%
   \let\ifDI@postjoin@\iffalse
   \def\DI@nojoin@extra{%
      \hspace*{\justification@g}\protect\nopagebreak[2]%
   }%
   \def\DI@join@extra{,\space}%
   \def\DI@offjoin@extra{%
      \hspace*{\justification@g}\protect\nopagebreak[4]%
   }%
%</!default>
   \DoParameterAssignments
   \ifDI@prejoin@
      \DI@item@join{\DI@item@justification}%
   \else
      \DI@item@nojoin\DI@item@justification
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \IfNoValueTF{#4}{%
      \DI@nofig{#3}%
      \ifDI@postjoin@
         \protected@edef\DI@item@join##1{\DI@join@extra}%
         \protected@edef\DI@item@nojoin{\DI@offjoin@extra\protect\par}%
      \else
         \DI@nojoin@extra\par
      \fi
   }{%
      \DI@hasfig{#3}{#4}%
      \par
   }%
   \ignorespaces
}
%    \end{macrocode}
% \end{template}
% 
% \begin{instance}{indexitem}{fixed1}
% \begin{instance}{indexitem}{fixed2}
% \begin{instance}{indexitem}{fixed3}
%   The \texttt{fixed1}, \texttt{fixed2}, and \texttt{fixed3} instances 
%   of type \texttt{indexitem} are simply the \texttt{fixed} template 
%   with different values assigned to the \textit{justification-setup} 
%   key.
%    \begin{macrocode}
\DeclareInstance{indexitem}{fixed1}{fixed}
   {justification-setup = indexitem1}
\DeclareInstance{indexitem}{fixed2}{fixed}
   {justification-setup = indexitem2}
\DeclareInstance{indexitem}{fixed3}{fixed}
   {justification-setup = indexitem3}
%</template>
%<*!template>
\@namedef{TP@I{}{indexitem}{fixed1}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem1}%
   \DI@item@nojoin
   \DI@item@justification
   \ifx \NoValue#4%
      #3\nobreak\hfil\nopagebreak[2]%
   \else
      #3\pfill#4%
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \par
}
\@namedef{TP@I{}{indexitem}{fixed2}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem2}%
   \DI@item@nojoin
   \DI@item@justification
   \ifx \NoValue#4%
      #3\nobreak\hfil\nopagebreak[2]%
   \else
      #3\pfill#4%
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \par
}
\@namedef{TP@I{}{indexitem}{fixed3}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem3}%
   \DI@item@nojoin
   \DI@item@justification
   \ifx \NoValue#4%
      #3\nobreak\hfil\nopagebreak[2]%
   \else
      #3\pfill#4%
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \par
}
%</!template>
%    \end{macrocode}
% \end{instance}\end{instance}\end{instance}
% 
% \begin{instance}{indexitem}{fixed-r1a}
% \begin{instance}{indexitem}{fixed-r2a-nocomma}
% \begin{instance}{indexitem}{fixed-a3r}
%   The \texttt{fixed-r1a}, \texttt{fixed-r2a-nocomma}, and 
%   \texttt{fixed-a3r} instances of type \texttt{indexitem} are again 
%   based on the \texttt{fixed} template, but here they always accept 
%   (or offer) to join with one neighbouring item, whereas they always 
%   reject to join with the other. As before, they differ in their 
%   values of the \textit{justification-setup} key, and the 
%   \texttt{-nocomma} is because that instance only inserts a space, 
%   not a comma and a space, when items are joined.
%    \begin{macrocode}
%<*template>
\DeclareInstance{indexitem}{fixed-r1a}{fixed}
   {justification-setup = indexitem1, post-join = true}
\DeclareInstance{indexitem}{fixed-r2a-nocomma}{fixed}
   {justification-setup = indexitem2, 
    post-join = true, join-extra = {\space}}
\DeclareInstance{indexitem}{fixed-a3r}{fixed}
   {justification-setup = indexitem3, pre-join = true}
%</template>
%<*!template>
\@namedef{TP@I{}{indexitem}{fixed-r1a}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem1}%
   \DI@item@nojoin
   \DI@item@justification
   \ifx \NoValue#4%
      #3%
      \def\DI@item@join##1{, }%
      \def\DI@item@nojoin{\nobreak\hfil\nopagebreak[4]\par}%
   \else
      #3\pfill#4\par
      \let\DI@item@join\@firstofone
      \let\DI@item@nojoin\@empty
   \fi
   \ignorespaces
}
\@namedef{TP@I{}{indexitem}{fixed-r2a-nocomma}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem2}%
   \DI@item@nojoin
   \DI@item@justification
   \ifx \NoValue#4%
      #3%
      \def\DI@item@join##1{ }%
      \def\DI@item@nojoin{\nobreak\hfil\nopagebreak[4]\par}%
   \else
      #3\pfill#4\par
      \let\DI@item@join\@firstofone
      \let\DI@item@nojoin\@empty
   \fi
   \ignorespaces
}
\@namedef{TP@I{}{indexitem}{fixed-a3r}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem3}%
   \DI@item@join{\DI@item@justification}%
   \ifx \NoValue#4%
      #3\hfil\nopagebreak[2]%
   \else
      #3\pfill#4%
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \par
}
%</!template>
%    \end{macrocode}
% \end{instance}\end{instance}\end{instance}
% 
% 
% \begin{template}{indexitem}{aloneaccept}
%   The \texttt{aloneaccept} template of type \texttt{indexitem} formats 
%   an item as the items in \package{doc}'s \texttt{theindex} environment. 
%   It accepts to be joined with the preceeding item if and only if 
%   both that and the following item are at a lower level than the item 
%   itself is.
%   
%   The keys for this template are:
%   \begin{description}
%     \keyvalitem{justification-setup}{i}
%       This is a template instance of type \texttt{justification}. It 
%       sets the justification for the paragraph containing the item, 
%       unless the item is being joined with the preceeding item.
%     \keyvalitem{ownlevel}{C}
%       This is the (nominal) level of this item; it will accept a join 
%       with the preceeding item if and only if the levels of both that 
%       and the following item are different from this number. 
%       \changes{v\,1.00}{2001/03/25}{Changed condition for accepting a 
%         join from ``neighbouring item levels are lower'' to 
%         ``neighbouring item levels are not equal to''. (LH)}
%       The default is 2.
%     \keyvalitem{nofig-action}{f1}
%       If the \meta{figures} argument is |\NoValue| then the \meta{text} 
%       argument is passed on to this macro for the actual formatting. 
%       The default expansion is the \meta{text} followed by a space of 
%       linefillskip.
%     \keyvalitem{fig-action}{f2}
%       If the \meta{figures} argument is not |\NoValue| then the 
%       \meta{text} and \meta{figures} arguments are passed on (in that 
%       order) to this macro for the actual formatting. The default 
%       expansion is
%       \begin{quote}
%         \meta{text}|\pfill|\meta{figures}
%       \end{quote}
%     \keyvalitem{post-join}{b}
%       A switch for whether the item should offer to join with the 
%       following item. True means ``make offer'', false (which is the 
%       default) means ``don't make offer''. Making the offer is 
%       furthermore conditioned by that the \meta{figures} argument is 
%       |\NoValue|.
%     \keyvalitem{nojoin-extra}{f0}
%       Extra code which is inserted after the normal code for an item 
%       if the item neither has any figures nor offers to join with the 
%       following item. The default value is a space of length 
%       \textit{linefillskip}.
%       \changes{v\,0.03}{2001/02/24}{Added the \textit{nojoin-extra} 
%          key. (LH)}
%     \keyvalitem{join-extra}{f0}
%       Extra text which is inserted after the normal text of the item 
%       if there is a join, by default a comma and a space.
%     \keyvalitem{offjoin-extra}{f0}
%       Extra code which is inserted after the normal text of the item 
%       if a join is offered but declined, by default the 
%       \textit{nojoin-extra} code followed by a |\nopagebreak|. 
%   \end{description}
%   
%   Note that the contents of the \textit{nojoin-extra}, 
%   \textit{join-extra}, and \textit{offjoin-extra} keys must be robust 
%   as they may be subjected to a |\protected@edef|.
%   \changes{v\,0.03}{2001/02/24}{\cs{protected@edef}ing the macros
%     \cs{DI@item@join} and \cs{DI@item@nojoin}. (LH)}
%   
%    \begin{macrocode}
%<*template>
\DeclareTemplate{indexitem}{aloneaccept}{4}{
   justification-setup =i{justification}      \DI@item@justification,
   ownlevel      =C  
%<default>           {2}
                                              \DI@this@level,
   nofig-action  =f1 
%<default>           {#1}
                                              \DI@nofig,
   fig-action    =f2 
%<default>           {#1\pfill#2}
                                              \DI@hasfig,
   post-join     =b  
%<default>           {false}
                                               DI@postjoin@,
   nojoin-extra    =f0 
%<default>           {\hspace*{\justification@g}}
                                              \DI@nojoin@extra,
   join-extra    =f0 
%<default>           {,\space}
                                              \DI@join@extra,
   offjoin-extra =f0 
%<default>           {\DI@nojoin@extra\protect\nopagebreak[4]}
                                              \DI@offjoin@extra
}{%
%<*!default>
   \def\DI@this@level{2}%
   \let\DI@nofig\@firstofone
   \def\DI@hasfig##1##2{##1\pfill##2}%
   \let\ifDI@postjoin@\iffalse
   \def\DI@nojoin@extra{\hspace*{\justification@g}}%
   \def\DI@join@extra{,\space}%
   \def\DI@offjoin@extra{\DI@nojoin@extra\protect\nopagebreak[4]}%
%</!default>
   \DoParameterAssignments
   \ifnum \DI@this@level=#1
      \DI@item@nojoin \DI@item@justification
   \else\ifnum \DI@this@level=#2
      \DI@item@nojoin \DI@item@justification
   \else
      \DI@item@join{\DI@item@justification}%
   \fi\fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \IfNoValueTF{#4}{%
      \DI@nofig{#3}%
      \ifDI@postjoin@
         \protected@edef\DI@item@join##1{\DI@join@extra}%
         \protected@edef\DI@item@nojoin{\DI@offjoin@extra\protect\par}%
      \else
         \DI@nojoin@extra \par
      \fi
   }{%
      \DI@hasfig{#3}{#4}%
      \par
   }%
   \ignorespaces
}
%</template>
%    \end{macrocode}
% \end{template}
% 
% \begin{instance}{indexitem}{aloneaccept2}
% \begin{instance}{indexitem}{aloneaceept3}
%   The \texttt{aloneaccept2} and \texttt{aloneaccept3} instances of type 
%   \texttt{indexitem} are simply the \texttt{aloneaccept} template 
%   with the levels fixed to two and three, respectively.
%    \begin{macrocode}
%<*template>
\DeclareInstance{indexitem}{aloneaccept2}{aloneaccept}
   {justification-setup = indexitem2, ownlevel = 2}
\DeclareInstance{indexitem}{aloneaccept3}{aloneaccept}
   {justification-setup = indexitem3, ownlevel = 3}
%</template>
%<*!template>
\@namedef{TP@I{}{indexitem}{aloneaccept2}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem2}%
   \ifnum #1=\tw@
      \DI@item@nojoin \DI@item@justification
   \else\ifnum #2=\tw@
      \DI@item@nojoin \DI@item@justification
   \else
      \DI@item@join{\DI@item@justification}%
   \fi\fi
   \ifx \NoValue#4%
      #3\nobreak\hfil\vadjust{}%
   \else
      #3\pfill #4%
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \par
}
\@namedef{TP@I{}{indexitem}{aloneaccept3}}#1#2#3#4{%
   \@letinstance\DI@item@justification{justification}{indexitem3}%
   \ifnum #1=\thr@@
      \DI@item@nojoin \DI@item@justification
   \else\ifnum #2=\thr@@
      \DI@item@nojoin \DI@item@justification
   \else
      \DI@item@join{\DI@item@justification}%
   \fi\fi
   \ifx \NoValue#4%
      #3\nobreak\hfil\vadjust{}%
   \else
      #3\pfill #4%
   \fi
   \let\DI@item@join\@firstofone
   \let\DI@item@nojoin\@empty
   \par
}
%</!template>
%    \end{macrocode}
% \end{instance}\end{instance}
% 
% 
% \subsubsection{The \texttt{docindex} template type}
% 
% \begin{templatetype}{docindex}
%   A template of type \texttt{docindex} takes care of typesetting an 
%   index found in a file (which is |\input|ted as part of this 
%   process), hence using an instance of type \texttt{docindex} is 
%   the same kind of action that the |\printindex| and |\printglossary| 
%   commands make.
%   
%   The template decides from which file the index should be read. It 
%   takes two arguments: the index prologue and the index epilogue. 
%   These are two pieces of text (which may just as well include a 
%   sectioning command) that are printed just before and after the 
%   index. Either argument may be empty. Immediately after the file 
%   containing the body of the index has been inputted, the template 
%   must execute |\DI@item@nojoin| to make sure that the last item is 
%   properly typeset.
%   
%   Templates of type \texttt{docindex} must begin by opening a group 
%   and end by closing it. They must furthermore locally define the 
%   following macros before any part of the index is typeset.
%   \begin{description}
%     \item[\cs{DI@indexitem@i}, \cs{DI@indexitem@ii}, and 
%       \cs{DI@indexitem@iii}]
%       Handlers for index items at level 1, 2, and 3 respectively. 
%       These handlers must conform to the specification for 
%       \texttt{indexitem} instances.
%     \item[\cs{DI@letter@skip}, \cs{DI@letter@format}]
%       These are described in the comments to the |\indexnewletter| 
%       command.
%     \item[\cs{+}]
%       The command for typesetting the separator between two parts of 
%       a composite (page) number. This is a parameterless macro.
%   \end{description}
%   
%    \begin{macrocode}
%<template>\DeclareTemplateType{docindex}{2}
%<!template>\@namedef{TP@T{docindex}}{{}{2}}
%    \end{macrocode}
% \end{templatetype}
% 
% \begin{template}{docindex}{std}
%   The \texttt{std} template of type \texttt{docindex} typesets an 
%   index while providing all the formatting parameters of the 
%   \package{doc} index and list of changes (and a few more).
%   \changes{v\,1.00}{2001/04/08}{The \mbox{\textit{-font}} keyvals 
%      renamed to \mbox{\textit{-setup}}, but the type stayed the 
%      same (f0). (LH)}
%   
%   \label{docindex:std}
%   The keys of the template are:
%   \begin{description}
%     \keyvalitem{file-name}{n}
%       The base name of the file in which the index is stored, by 
%       default the |\jobname|.\changes{v\,1.00}{2001/03/25}{Added 
%       \textit{file-name} and \textit{file-extension} keys, removed 
%       the \textit{default-prologue} and \textit{default-epilogue} 
%       keys. (LH)}
%     \keyvalitem{file-extension}{n}
%       The extension of the file in which the index is stored, by 
%       default \texttt{ind}.
%     \keyvalitem{item1}{i}
%       \texttt{indexitem} instance for level 1 items, by default 
%       \texttt{fixed1}.
%     \keyvalitem{item2}{i}
%       \texttt{indexitem} instance for level 2 items, by default 
%       \texttt{fixed2}.
%     \keyvalitem{item3}{i}
%       \texttt{indexitem} instance for level 3 items, by default 
%       \texttt{fixed3}.
%     \keyvalitem{columns}{C}
%       The number of columns in the index, by default 3.
%     \keyvalitem{reserved-height}{L}
%       The minimal amount of vertical space that must be left on the 
%       current page if the index is to start on it, by default 
%       80\,pt.^^A
%       \changes{v\,1.00}{2001/03/25}{Made \textit{reserved-height} work 
%          even when \textit{columns} is 1 by using the 
%          \package{multicol} macro \cs{enough@room}. (LH)}
%     \keyvalitem{column-sep}{l}
%       The horizontal separation between columns in the index, by 
%       default 10\,pt. (This may seem strange in comparison with 
%       \package{doc}, since |\IndexParms| contains the command 
%       |\columnsep=15pt|, but \package{doc} doesn't execute 
%       |\IndexParms| until \LaTeX\ is already in multi-column mode, and 
%       then it is too late for the changed value to have any effect.)
%     \keyvalitem{prologue-setup}{f0}
%       Various commands setting layout parameters (e.g.\ the font) for 
%       the prologue; by default empty.
%     \keyvalitem{body-setup}{f0}
%       Various commands setting layout parameters (e.g.\ the font) for 
%       the body of the index; by default |\small|.
%     \keyvalitem{epilogue-setup}{f0}
%       Various commands setting layout parameters (e.g.\ the font) for 
%       the epilogue; by default |\normalsize| (to counter the |\small| 
%       in the \textit{body-setup}).
%     \keyvalitem{letter-skip}{L}
%       The skip inserted before a new letter group, by default 10\,pt 
%       plus 2\,pt minus 3\,pt.
%     \keyvalitem{letter-format}{f1}
%       The macro which formats new letter groups; the argument is the 
%       heading for the group, as generated by \program{makeindex}. By 
%       defaults it typesets the argument in boldface, centered on a 
%       line.
%     \keyvalitem{pagestyle}{n}
%       If this is nonempty then the pagestyle by that name will be 
%       selected for the index. By default it is empty.
%     \keyvalitem{parskip}{l}
%       The value of |\parskip| to use inside the index, by default 
%       0\,pt plus 1\,pt. This key value is likely to change as the 
%       \LaTeXplus\ interfaces for galleys evolve.
%       \changes{v\,0.03}{2001/02/27}{Added \textit{parskip} keyval. (LH)}
%     \keyvalitem{page-compositor}{f0}
%       The text that is typeset to separate two parts of a composite 
%       (page) number, by default a hyphen.
%       \changes{v\,1.00}{2001/04/05}{Added \textit{page-compositor} 
%          keyval. (LH)}
%   \end{description}
%   
%    \begin{macrocode}
%<*template>
\DeclareTemplate{docindex}{std}{2}{
   file-name        =n
%<default>         {\jobname}
                                                    \DI@file@name,
   file-extension   =n                   
%<default>         {ind}
                                                    \DI@file@ext,
   item1            =i{indexitem} 
%<default>         {fixed1}
                                                    \DI@indexitem@i,
   item2            =i{indexitem} 
%<default>         {fixed2}
                                                    \DI@indexitem@ii,
   item3            =i{indexitem} 
%<default>         {fixed3}
                                                    \DI@indexitem@iii,
   reserved-height  =L  
%<default>         {80pt}
                                                    \DI@reserved@height,
   columns          =C  
%<default>         {3}
                                                    \DI@columns,
   column-sep       =l  
%<default>         {10pt}
                                                    \columnsep,
   prologue-setup    =f0 
%<default>         {}
                                                    \DI@prologue@setup,
   body-setup        =f0 
%<default>         {\small}
                                                    \DI@body@setup,
   epilogue-setup    =f0 
%<default>         {\normalsize}
                                                    \DI@epilogue@setup,
   letter-skip      =L  
%<default>         {10pt plus 2pt minus 3pt}
                                                    \DI@letter@skip,
   letter-format    =f1 
%<default>         {\UseInstance{justification}{center}%
%<default>          \textbf{#1}\nopagebreak\csname par\endcsname}
                                                    \DI@letter@format,
   pagestyle        =n  
%<default>             {}
                                                    \DI@pagestyle,
   parskip          =l  
%<default>             {0pt plus 1pt}
                                                    \parskip,
   page-compositor  =f0
%<default>             {-}
                                                    \+
}{%
   \begingroup
%<*!default>
   \def\DI@file@name{\jobname}%
   \def\DI@file@ext{ind}%
   \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
   \@letinstance\DI@indexitem@ii{indexitem}{fixed2}%
   \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
   \def\DI@reserved@height{80pt}%
   \def\DI@columns{3}%
   \columnsep=10pt%
   \let\DI@prologue@setup\@empty
   \def\DI@body@setup{\small}%
   \def\DI@epilogue@setup{\normalsize}%
   \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
   \def\DI@letter@format##1{%
      \UseInstance{justification}{center}%
      \textbf{##1}\nopagebreak\par
   }%
   \parskip=\z@\@plus\p@
   \let\DI@pagestyle\@empty
   \def\+{-}%
%</!default>
   \DoParameterAssignments
   \IfFileExists{\DI@file@name.\DI@file@ext}{%
      \ifnum \DI@columns>\@ne
         \begin{multicols}{\DI@columns}%
            [\DI@prologue@setup #1][\DI@reserved@height]%
      \else
         \enough@room{\DI@reserved@height}%
         \DI@prologue@setup #1\par
         \addvspace\multicolsep
      \fi
      \ifx \DI@pagestyle\@empty \else \pagestyle{\DI@pagestyle}\fi
      \DI@body@setup
      \DI@ind@setup
      \input{\DI@file@name.\DI@file@ext}%
      \DI@item@nojoin
      \ifx \DI@pagestyle\@empty \else
         \expandafter\thispagestyle \expandafter{\DI@pagestyle}%
      \fi
      \ifnum \DI@columns>\@ne
         \end{multicols}%
      \else
         \enough@room\postmulticols
         \addvspace\multicolsep
      \fi
      \DI@epilogue@setup #2\par
   }{\typeout{No file \DI@file@name.\DI@file@ext.}}%
   \endgroup
}
%    \end{macrocode}
% \end{template}
% 
% 
% \begin{instance}{docindex}{index}
% \begin{option}{usedocindexps}
%   The \texttt{index} instance of the \texttt{docindex} template type 
%   prints the normal index (as opposed to the list of changes). There 
%   are two different definitions of the instance: one which sets the 
%   pagestyle in the index, and one which does not; which one is used 
%   depends on whether the \texttt{usedocindexps} option has been 
%   passed to the package or not.
%    \begin{macrocode}
\@ifpackagewith{docindex}{usedocindexps}{%
   \DeclareInstance{docindex}{index}{std}{pagestyle=docindex}%
}{%
   \DeclareInstance{docindex}{index}{std}{}%
}
%</template>
%    \end{macrocode}
%   
%   The implementations of the \texttt{index} instance in 
%   \package{docidx2e} are slightly off in that they use \package{doc} 
%   parameters for various settings in the extent such parameters exist.
%   \changes{v\,0.03}{2001/02/24}{Added \cs{@nobreakfalse} in 
%      \package{docidx2e} implementation; the first item in the index 
%      does not directly follow a \cs{section}-type heading. (LH)}
%   \label{p:index-instance}
%    \begin{macrocode}
%<*!template>
\@ifpackagewith{docidx2e}{usedocindexps}{%
   \@namedef{TP@I{}{docindex}{index}}#1#2{%
      \begingroup
      \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
      \@letinstance\DI@indexitem@ii{indexitem}{fixed2}%
      \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
      \columnsep=10pt%
      \parskip=0pt plus 1pt%
      \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
      \def\DI@letter@format##1{%
         \par
         \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
         \nopagebreak
      }%
      \def\+{-}%
      \IfFileExists{\jobname.ind}{%
         \ifnum \c@IndexColumns>\@ne
            \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
         \else
            \enough@room{\IndexMin}%
            #1\par
            \addvspace\multicolsep
         \fi
         \pagestyle{docindex}%
         \small
         \@nobreakfalse
         \DI@ind@setup
         \input{\jobname.ind}%
         \DI@item@nojoin
         \thispagestyle{docindex}
         \ifnum \c@IndexColumns>\@ne
            \end{multicols}%
         \else
            \enough@room\postmulticols
            \addvspace\multicolsep
         \fi
         \normalsize #2\par
      }{\typeout{No file \jobname.ind.}}%
      \endgroup
   }
}{%
   \@namedef{TP@I{}{docindex}{index}}#1#2{%
      \begingroup
      \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
      \@letinstance\DI@indexitem@ii{indexitem}{fixed2}%
      \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
      \columnsep=10pt%
      \parskip=0pt plus 1pt%
      \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
      \def\DI@letter@format##1{%
         \par
         \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
         \nopagebreak
      }%
      \def\+{-}%
      \IfFileExists{\jobname.ind}{%
         \ifnum \c@IndexColumns>\@ne
            \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
         \else
            \enough@room{\IndexMin}%
            #1\par
            \addvspace\multicolsep
         \fi
         \small
         \@nobreakfalse
         \DI@ind@setup
         \input{\jobname.ind}%
         \DI@item@nojoin
         \ifnum \c@IndexColumns>\@ne
            \end{multicols}%
         \else
            \enough@room\postmulticols
            \addvspace\multicolsep
         \fi
         \normalsize #2\par
      }{\typeout{No file \jobname.ind.}}%
      \endgroup
   }
}
%</!template>
%    \end{macrocode}
% \end{option}\end{instance}
% 
% 
% \begin{instance}{docindex}{changes}
%   The \texttt{changes} instance of the \texttt{docindex} template 
%   type typesets a \package{doc} list of changes.
%   \changes{v\,0.03}{2001/02/24}{Added \cs{@nobreakfalse} in 
%      \package{docidx2e} implementation; the first item in the index 
%      does not directly follow a \cs{section}-type heading. (LH)}
%   \changes{v\,1.00}{2001/04/07}{Added \cs{makeatletter} in 
%      \package{docidx2e} implementation; it doesn't hurt and it is 
%      sometimes necessary (when commands that expand to private 
%      control sequences are used in the argument of \cs{changes}). 
%      (LH)}
%    \begin{macrocode}
%<*template>
\DeclareInstance{docindex}{changes}{std}{
   file-extension = gls,
   item2 = fixed-r2a-nocomma,
   item3 = fixed-a3r,
   columns = 2, 
   letter-format = {},
   letter-skip = \z@skip
}
%</template>
%    \end{macrocode}
%   \label{p:changes-instance}
%    \begin{macrocode}
%<*!template>
\@namedef{TP@I{}{docindex}{changes}}#1#2{%
   \begingroup
   \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
   \@letinstance\DI@indexitem@ii{indexitem}{fixed-r2a-nocomma}%
   \@letinstance\DI@indexitem@iii{indexitem}{fixed-a3r}%
   \columnsep=10pt%
   \parskip=0pt plus 1pt%
   \def\DI@letter@skip{\z@skip}%
   \let\DI@letter@format\@gobble
   \def\+{-}%
   \IfFileExists{\jobname.gls}{%
      \ifnum \c@GlossaryColumns>\@ne
         \begin{multicols}{\c@GlossaryColumns}[#1][\GlossaryMin]%
      \else
         \enough@room{\GlossaryMin}%
         #1\par
         \addvspace\multicolsep
      \fi
      \small
      \makeatletter
      \@nobreakfalse
      \DI@ind@setup
      \input{\jobname.gls}%
      \DI@item@nojoin
      \ifnum \c@GlossaryColumns>\@ne
         \end{multicols}%
      \else
         \enough@room\postmulticols
         \addvspace\multicolsep
      \fi
      \normalsize #2\par
   }{\typeout{No file \jobname.gls.}}
   \endgroup
}
%</!template>
%    \end{macrocode}
% \end{instance}
% 
% \begin{macro}{\PrintIndex}
% \begin{macro}{\PrintChanges}
%   The |\PrintIndex| and |\PrintChanges| commands are redefined to use 
%   the respective instances of template type \texttt{docindex}.
%    \begin{macrocode}
\renewcommand\PrintIndex{%
   \UseInstance{docindex}{index}{\index@prologue}{}%
   \global\let\PrintIndex\@empty
}
\renewcommand\PrintChanges{%
   \UseInstance{docindex}{changes}{\glossary@prologue}{}%
   \global\let\PrintChanges\@empty
}
%</pkg>
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \section{Notes and acknowledgements}
% 
% The exact descriptions of the parameters of the \program{makeindex} 
% program is the paper \cite{makeindex-paper} by Chen and Harrison, but 
% I have seen claims that there are parameters not listed there 
% (presumably becuase they were added after this paper was written). 
% \texttt{docindex.ist} does not change any such undocumented 
% parameter, however.
% 
% There are other index sorting programs than \package{makeindex} 
% around, such as for example \program{x\r{\i}ndy}~\cite{xindy}. 
% Should someone create index style files for such systems that are 
% equivalent (or superior, for that matter) to \texttt{docindex.ist} 
% then I would be happy to add them to the \package{docindex} 
% distribution.
% 
% Most of the actual layout parameter settings used by the 
% \package{docindex} package are not of my design, but copied from 
% various other \LaTeX\ packages such as~\cite{multicol,doc} (mainly by 
% Frank Mittelbach). I have however tried to sort out which parameters 
% are actually in force under the various conditions---something which 
% turned out to be less obvious than I originally suspected.
% 
% The idea to have the \texttt{docindex} type templates input the sorted 
% index file (rather than simply setting up the formatting of it as was 
% the case in v\,0.03) was taken from the \package{xindex} 
% package~\cite{xindex} by Achim Blumensath.
%
% \hbadness=10000 
%
% \Finale
% 
%
\endinput