summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/xdoc/docindex.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/xdoc/docindex.dtx
Initial commit
Diffstat (limited to 'macros/latex/contrib/xdoc/docindex.dtx')
-rw-r--r--macros/latex/contrib/xdoc/docindex.dtx2100
1 files changed, 2100 insertions, 0 deletions
diff --git a/macros/latex/contrib/xdoc/docindex.dtx b/macros/latex/contrib/xdoc/docindex.dtx
new file mode 100644
index 0000000000..47139d32b1
--- /dev/null
+++ b/macros/latex/contrib/xdoc/docindex.dtx
@@ -0,0 +1,2100 @@
+% \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 \ No newline at end of file