% \CheckSum{893}
% \iffalse
%
\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}
%
% \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}
%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage
% {docindex}
% {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
%
% \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}
%
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 "--"
%
% \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}
%
\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}
%
% \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}
%
group_skip "}{0}\n%^^A\n\\indexnewletter{0}{"
heading_prefix ""
heading_suffix ""
headings_flag 1
%
% \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}
%
\@ifundefined{indexnewletter}{}{%
\PackageInfo
% {docindex}
% {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
}
%
% \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}
%
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}
%keyword "\\xdocindexentry"
%page_compositor "\\+"
% \end{macrocode}
% \SpecialIndex{\+}
% Finally, in the style file for the list of changes, the keyword must
% be changed to |\glossaryentry|.
% \begin{macrocode}
%keyword "\\glossaryentry"
%
% \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}
%
\@ifpackagewith
% {docindex}
% {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
% {docindex}%
% {docidx2e}%
{Ignoring old style index file}
\endinput
}%
}
%
% \end{macrocode}
% \end{macro}\end{macro}
%
% \xrefoff
% \begin{macrocode}
%
preamble "\\docindexguard{\\endinput}\n%^^A\n\\indexnewletter{1}{"
postamble "}{0}\n\\endinput"
%
% \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}
%
%\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}
%
\@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}
%\@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}
%
\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
}
%
%
\@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}
%\DeclareTemplateType{indexitem}{4}
%\@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}
%
\DeclareTemplate{indexitem}{fixed}{4}{
justification-setup =i{justification} \DI@item@justification,
pre-join =b
% {false}
DI@prejoin@,
nofig-action =f1
% {#1}
\DI@nofig,
fig-action =f2
% {#1\pfill#2}
\DI@hasfig,
post-join =b
% {false}
DI@postjoin@,
nojoin-extra =f0
% {\hspace*{\justification@g}
% \protect\nopagebreak[2]}
\DI@nojoin@extra,
join-extra =f0
% {,\space}
\DI@join@extra,
offjoin-extra =f0
% {\hspace*{\justification@g}
% \protect\nopagebreak[4]}
\DI@offjoin@extra
}{%
%
\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}
%
%
\@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}
%
\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}
%
%
\@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}
%
\DeclareTemplate{indexitem}{aloneaccept}{4}{
justification-setup =i{justification} \DI@item@justification,
ownlevel =C
% {2}
\DI@this@level,
nofig-action =f1
% {#1}
\DI@nofig,
fig-action =f2
% {#1\pfill#2}
\DI@hasfig,
post-join =b
% {false}
DI@postjoin@,
nojoin-extra =f0
% {\hspace*{\justification@g}}
\DI@nojoin@extra,
join-extra =f0
% {,\space}
\DI@join@extra,
offjoin-extra =f0
% {\DI@nojoin@extra\protect\nopagebreak[4]}
\DI@offjoin@extra
}{%
%
\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
}
%
% \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}
%
\DeclareInstance{indexitem}{aloneaccept2}{aloneaccept}
{justification-setup = indexitem2, ownlevel = 2}
\DeclareInstance{indexitem}{aloneaccept3}{aloneaccept}
{justification-setup = indexitem3, ownlevel = 3}
%
%
\@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}
%\DeclareTemplateType{docindex}{2}
%\@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}
%
\DeclareTemplate{docindex}{std}{2}{
file-name =n
% {\jobname}
\DI@file@name,
file-extension =n
% {ind}
\DI@file@ext,
item1 =i{indexitem}
% {fixed1}
\DI@indexitem@i,
item2 =i{indexitem}
% {fixed2}
\DI@indexitem@ii,
item3 =i{indexitem}
% {fixed3}
\DI@indexitem@iii,
reserved-height =L
% {80pt}
\DI@reserved@height,
columns =C
% {3}
\DI@columns,
column-sep =l
% {10pt}
\columnsep,
prologue-setup =f0
% {}
\DI@prologue@setup,
body-setup =f0
% {\small}
\DI@body@setup,
epilogue-setup =f0
% {\normalsize}
\DI@epilogue@setup,
letter-skip =L
% {10pt plus 2pt minus 3pt}
\DI@letter@skip,
letter-format =f1
% {\UseInstance{justification}{center}%
% \textbf{#1}\nopagebreak\csname par\endcsname}
\DI@letter@format,
pagestyle =n
% {}
\DI@pagestyle,
parskip =l
% {0pt plus 1pt}
\parskip,
page-compositor =f0
% {-}
\+
}{%
\begingroup
%
\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}{}%
}
%
% \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}
%
\@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}
%
\DeclareInstance{docindex}{changes}{std}{
file-extension = gls,
item2 = fixed-r2a-nocomma,
item3 = fixed-a3r,
columns = 2,
letter-format = {},
letter-skip = \z@skip
}
%
% \end{macrocode}
% \label{p:changes-instance}
% \begin{macrocode}
%
\@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
}
%
% \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