diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/xdoc/docindex.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/xdoc/docindex.dtx | 2100 |
1 files changed, 2100 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/xdoc/docindex.dtx b/Master/texmf-dist/source/latex/xdoc/docindex.dtx new file mode 100644 index 00000000000..47139d32b12 --- /dev/null +++ b/Master/texmf-dist/source/latex/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 |