Debian Codegraph @

texmf-dist/source/latex/xdoc/docindex.dtx

raw
1 % \CheckSum{893}
2 % \iffalse
3 %<*driver>
4 \documentclass{ltxdoc}
5 \usepackage{xdoc2}
6
7 \makeatletter
8 \NewMacroEnvironment{templatetype}{\XD@grab@harmless\relax}{1}%
9 {\MacroFont#1\ \normalfont type}%
10 {\XDMainIndex{\LevelSorted{#1}{\texttt{#1} template type}}}%
11 {{#1}{\texttt{#1} template type}}%
12 {}%
13 \NewMacroEnvironment*{template}{%
14 \XD@grab@harmless\relax\XD@grab@harmless\relax
15 }{2}%
16 {\XDParToMargin{\MacroFont #1\textnormal{\slash}#2 \normalfont
17 template}}%
18 {\XDMainIndex{
19 \LevelSorted{#1}{\texttt{#1} template type}%
20 \LevelSorted{#2}{\texttt{#2} template}%
21 }}%
22 {{#1/#2}{\texttt{#1}\slash\texttt{#2} template}}%
23 {\def\XD@template@sort{%
24 \LevelSorted{#1}{\texttt{#1} template type}%
25 \LevelSorted{#2}{\texttt{#2} template}%
26 }}%
27 \NewMacroEnvironment*{instance}{%
28 \XD@grab@harmless\relax\XD@grab@harmless\relax
29 }{2}%
30 {\XDParToMargin{\MacroFont #1\textnormal{\slash}#2 \normalfont
31 instance}}%
32 {\XDMainIndex{
33 \LevelSorted{#1}{\texttt{#1} template type}%
34 \LevelSorted{#2}{\texttt{#2} instance}%
35 }}%
36 {{#1/#2}{\texttt{#1}\slash\texttt{#2} instance}}%
37 {}%
38 \NewMacroEnvironment*{collectioninstance}{%
39 \XD@grab@harmless\relax\XD@grab@harmless\relax\XD@grab@harmless\relax
40 }{3}%
41 {\XDParToMargin{\MacroFont #2\textnormal{\slash}#3 \normalfont
42 instance (\texttt{#1} collection)}}%
43 {\XDMainIndex{
44 \LevelSorted{#2}{\texttt{#2} template type}%
45 \LevelSorted{#3}{\texttt{#3} instance}%
46 \LevelSorted{#1}{\texttt{#1} collection}%
47 }}%
48 {{#2/#3/#1}%
49 {\texttt{#2}\slash\texttt{#3} instance (\texttt{#1} collection)}}%
50 {}%
51 \@namedef{XD@harmless\string\break}{%
52 \toks@=\expandafter{\the\toks@ \protect\nolinebreak[3]}%
53 \XD@harmless@
54 }
55 \newcommand\keyvalitem[2]{%
56 \item[#1 (#2)%
57 \IndexEntry{\XD@template@sort
58 \LevelSorted{#1}{\textit{#1} keyval (#2)}%
59 }{usage}{\thepage}%
60 ]%
61 }
62 \newcommand{\xrefoff}{\scan@allowedfalse}
63 \newcommand{\xrefon}{\scan@allowedtrue}
64 \makeatother
65
66 \newenvironment{syntax}{%
67 \let\\=\break
68 \list{}{%
69 \setlength\topsep{\medskipamount}%
70 \setlength\partopsep{0pt}%
71 \setlength\itemsep{0pt plus 1pt}%
72 \setlength\parsep{\itemsep}%
73 \setlength\leftmargin{3em}%
74 \setlength\listparindent{1em}%
75 \setlength\itemindent{-2em}%
76 \setlength\labelwidth{0pt}%
77 \setlength\labelsep{0pt}%
78 \csname @endparpenalty\endcsname=500
79 \def\makelabel##1{\mbox{\meta{##1}${}\longrightarrow{}$}}%
80 }%
81 \addtolength\rightskip{0pt plus 1fil}%
82 \linepenalty=300%
83 }{\endlist}
84 \newcommand\branch{\({}\mid{}\)\ignorespaces}
85
86 \DeclareRobustCommand{\package}[1]{\textsf{#1}}
87 \DeclareRobustCommand{\program}[1]{\textsf{#1}}
88 \DeclareRobustCommand\LaTeXplus{\LaTeXe$*$}
89
90 \DoNotIndex{\addvspace,\@backslashchar,\begin,\begingroup,\bgroup}
91 \DoNotIndex{\csname,\DeclareInstance,\DeclareOption}
92 \DoNotIndex{\DeclareTemplate,\DeclareTemplateType,\def}
93 \DoNotIndex{\DoParameterAssignments,\edef,\egroup,\@eha}
94 \DoNotIndex{\@empty,\end,\endcsname,\endgroup,\endinput,\expandafter}
95 \DoNotIndex{\@firstofone,\@firstoftwo,\global,\@gobble,\hb@xt@,\hfil}
96 \DoNotIndex{\hsize,\hspace,\IfNoValueTF,\@ifpackageloaded}
97 \DoNotIndex{\@ifpackagewith,\@ifundefined,\ignorespaces,\@input@}
98 \DoNotIndex{\jobname,\leftskip,\let,\MessageBreak,\@namedef,\@ne}
99 \DoNotIndex{\NeedsTeXFormat,\newcommand,\nobreak,\@nobreakfalse}
100 \DoNotIndex{\nopagebreak,\normalsize,\NoValue,\number,\outer}
101 \DoNotIndex{\p@,\PackageError,\PackageInfo,\PackageWarningNoLine}
102 \DoNotIndex{\pagestyle,\par,\parfillskip,\parindent,\parskip}
103 \DoNotIndex{\@plus,\ProcessOptions,\protect,\protected@edef}
104 \DoNotIndex{\providecommand,\ProvidesPackage,\relax,\renewcommand}
105 \DoNotIndex{\RequirePackage,\rightskip,\romannumeral,\@secondoftwo}
106 \DoNotIndex{\small,\space,\textbf,\thispagestyle,\thr@@,\tw@}
107 \DoNotIndex{\vadjust,\vspace,\z@,\z@skip}
108 \DoNotIndex{\iffalse,\ifnum,\ifx,\else,\fi} % \fi \fi
109 \DoNotIndexBy{@}
110 \DoNotIndexBy{DI@}
111
112 \CodelineIndex
113 \EnableCrossrefs
114 \RecordChanges
115 \setcounter{IndexColumns}{2}
116 \setcounter{StandardModuleDepth}{2}
117
118
119 \begin{document}
120 \DocInput{docindex.dtx}
121 \PrintChanges
122 \PrintIndex
123 \end{document}
124 %</driver>
125 % \fi
126 %
127 % \title{The \package{docindex} package}
128 % \author{Lars Hellstr\"om}
129 % \date{8 July 2003}
130 % \maketitle
131 %
132 % \begin{abstract}
133 % The \package{docindex} package implements template-based formatting
134 % of indices and lists of changes\slash glossaries. In addition to this,
135 % the control structures employed also provide for a couple of new
136 % features, such as automatic collapsing of trivial index levels.
137 % \end{abstract}
138 %
139 % \tableofcontents
140 %
141 %
142 % \section{Introduction}
143 %
144 % In automatically generated indices with multi-level entries, such as the
145 % list of changes of a \package{doc} document, it often happens that some
146 % entries are uniquely identified by their primary level sort keys,
147 % although there are sort keys and text for additional levels. If then
148 % the formatting is designed for entries that are uniquely identified
149 % only when their secondary or tertiary sort keys are considered, one
150 % ends up with a couple of entries that look rather peculiar (building
151 % a tree which never branches) and usually take up much more space than
152 % they need to. The remedy for this is of course to make the formatting
153 % smart enough to recognise this situation when it occurs and flexible
154 % enough to format the text is a more suitable manner.
155 %
156 % An example of this is that if a document contains the index
157 % entries\footnote{I'm using the default \program{makeindex}
158 % metacharacters in these examples, but the style file provided for
159 % this package actually uses the same metacharacters as those style files
160 % provided by the \package{doc} package---hence the `\package{doc}'
161 % in `\package{docindex}'. }
162 % \begin{quote}
163 % |\index{Bernoulli!Jacob}\index{Bernoulli!Johann}|
164 % \end{quote}
165 % then it is probably reasonable to format this as
166 % \begin{quote}
167 % Bernoulli,\\
168 % \vadjust{}\quad Jacob\\
169 % \vadjust{}\quad Johann
170 % \end{quote}
171 % but if the index entries instead were
172 % \begin{quote}
173 % |\index{Jacobi!Carl}\index{Bernoulli!Jacob}|
174 % \end{quote}
175 % then it is probably better to format this as
176 % \begin{quote}
177 % Bernoulli, Jacob\\
178 % Jacobi, Carl
179 % \end{quote}
180 % than as
181 % \begin{quote}
182 % Bernoulli,\\
183 % \vadjust{}\quad Jacob\\
184 % Jacobi,\\
185 % \vadjust{}\quad Carl
186 % \end{quote}
187 %
188 % The \program{makeindex} program has some features in this direction,
189 % but they only allow dependence on the previous item in the index, not
190 % the next item, which is what you need to know when deciding whether
191 % `Jacob' should go on the same line as `Bernoulli'. Therefore
192 % \package{docindex} pretty much ignores these features in
193 % \program{makeindex} and instead sees to that each command that is to
194 % typeset an index item knows what kind of items were before and after it.
195 %
196 % Another reason for writing this package was to try out the template
197 % mechanisms as provided by the \LaTeXplus\ \package{template}
198 % package.\footnote{\LaTeXplus\ is the name of the \LaTeX\ version after
199 % \LaTeXe. Rather than being a completely different kernel\slash format,
200 % \LaTeXplus\ is (will be) implemented as a collection of \LaTeXe\
201 % packages which replace parts of the kernel. More information and
202 % package code can be found on the \LaTeX-project website~^^A
203 % \cite{LaTeX-project}.} My impression is that this experiment turned
204 % out strikingly well. I have always found the more layout-oriented
205 % aspects of \TeX\ programming a bit cumbersome, but the separation of
206 % layout details from control structures that becomes natural when
207 % employing template mechanisms seems to have made it much easier. I'm
208 % not sure why this is so, but it could be as simple as that the layout
209 % settings are no longer diluted in the control structures. In any
210 % case, I would recommend people creating new \LaTeXe\ packages to
211 % employ template mechanisms in at least the initial development
212 % versions of the package, for the following reasons: (i) it reduces the
213 % work of updating the package for \LaTeXplus, (ii) it furthers the
214 % development of \LaTeXplus, and (iii) it might actually become a
215 % better package.
216 %
217 % A third reason for writing the \package{docindex} package was to get
218 % the \LaTeX\ document ``back in control'' of how the index is formatted.
219 % Certainly it is the document which has the final say about what
220 % the command in the \texttt{.ind} file actually do, but the traditional
221 % \program{makeindex} style files that are used place severe restrictions
222 % on the formatting of the index simply because they control where the
223 % commands are put. \package{docindex} tries to reduce these
224 % restrictions by making all texts in the index arguments of commands.
225 % Certainly there is a lot more that could be done in this direction---in
226 % particular, the (page) numbers in the index could be coded as a
227 % |\do|-type list rather than as an explicitly comma-separated list as is
228 % done now---but what is in \package{docindex} at the moment seems to
229 % satisfy all my current needs.
230 %
231 %
232 % \section{Usage}
233 %
234 % \subsection{Straightforward usage}
235 %
236 % To make use of the \package{docindex} package in formatting the index
237 % and list of changes of a \package{doc}-type \LaTeX\ document, you must
238 % do the following:
239 % \begin{enumerate}
240 % \item Load the \package{docindex} package (or probably
241 % rather the \package{docidx2e} package---see below).
242 % \item Make sure that the index entries does not use any commands,
243 % such as |\verb|, that rely on changing catcodes or otherwise
244 % need to be executed before the entire entry text has been
245 % tokenized.
246 % \item Generate the \texttt{.ind} and \texttt{.gls} files using
247 % \texttt{docindex.ist} as style file for \program{make\-index}.
248 % \end{enumerate}
249 % (Item~2 may seem like a monumental task if one considers what the
250 % indices of \package{doc} documents traditionally looks like---there's
251 % a |\verb| for every macro name in the index---but it is really not
252 % that bad. \package{docindex} loads the \package{xdoc} package~^^A
253 % \cite{xdoc} which redefines \texttt{macro}, the cross-referencing
254 % mechanism, etc.\ so that the index entries generated by these no
255 % longer uses |\verb|. What is left for you to deal with are merely
256 % the possible uses of |\verb| in explicit |\index| or |\SortIndex|
257 % commands.)
258 %
259 % What advantages are there then for the normal user in having
260 % \package{docindex} formatting the index and list of changes, as
261 % opposed to using the default mechanisms in the \package{doc} package?
262 % I can only think of two: the index or list of changes may be typeset in
263 % a single column and the same \program{makeindex} style file can be
264 % used for both index and list of changes. Neither advantage is
265 % significant. Instead the advantage of \package{docindex} lies in that
266 % it becomes much simpler to change the formatting, which is rather an
267 % advantage for advanced users which have special needs, and
268 % in particular one can do this without having to supply e.g.\ extra
269 % \program{makeindex} style files.
270 %
271 % Another important point is that what you will want to use is probably
272 % not the \LaTeXplus\ \package{docindex} package, but the ``downgraded''
273 % \LaTeXe\ version \package{docidx2e}, as the former uses the
274 % \package{galley2} package which currently wrecks pretty much all
275 % justification in all existing document classes. \package{docidx2e}
276 % provides the same features as \package{docindex}, but configuring it
277 % is somewhat more cumbersome since \package{template} won't do most of
278 % the coding for you. It is however rather straightforward to convert
279 % a definition using the \package{docindex} package to something which
280 % achieves the same results with the \package{docidx2e} package.
281 %
282 %
283 % \subsection{Multiple indices}
284 %
285 % The \package{docindex} package makes it comparatively simple to
286 % include several indices in the same document: all one has to do is
287 % use an instance or template of type \texttt{docindex} for each index
288 % one wishes to typeset. The syntax for using such an instance is
289 % \begin{quote}
290 % |\UseInstance{docindex}|\marg{instance}\marg{prologue}^^A
291 % \marg{epilogue}
292 % \end{quote}
293 % The \meta{prologue} and \meta{epilogue} are texts which will be
294 % printed just before and after the index, respectively, and either may
295 % be empty. The text for the index itself is read from another file,
296 % the name and extentsion of which are specified by the instance. The
297 % \texttt{std} template prints the \meta{prologue} and \meta{epilogue}
298 % in one-column mode, whereas the index itself can be printed in one- or
299 % multicolumn mode (the default is three columns).
300 %
301 % The \package{doc} commands |\PrintIndex| and |\PrintGlossary| are
302 % redefined to be
303 % \begin{quote}
304 % |\UseInstance{docindex}{index}{\index@prologue}{}|
305 % \end{quote}
306 % and
307 % \begin{quote}
308 % |\UseInstance{docindex}{changes}{\glossary@prologue}{}|
309 % \end{quote}
310 % respectively. The \texttt{index} and \texttt{changes} instances of
311 % type \texttt{docindex} give the same formatting as the \package{doc}
312 % defaults. (The \package{docidx2e} definitions even use the
313 % \package{doc} package parameters where applicable, but in
314 % \package{docindex} it is much simpler to redefine the instance from
315 % scratch.)
316 %
317 % The format of the sorted index files (\texttt{.ind}, \texttt{.gls},
318 % etc.) that a \texttt{docindex} instance inputs is rather complicated
319 % and I would suggest that the generation of these files is left to the
320 % \program{makeindex} program, but the complete syntax is described in
321 % Subsection~\ref{Ssec:ist}. The syntax of the unsorted index files
322 % (\texttt{.idx}, \texttt{.glo}, etc.) is simpler; there are only a few
323 % things that are different from the index files of the \package{doc}
324 % package.
325 %
326 % The foremost difference is that the index entries should begin not
327 % with |\indexentry| or |\glossaryentry|, but with |\docindexentry|. The
328 % \package{xdoc} package provides hooks with which one can change these
329 % texts in entries generated using the |\index| and |\glossary| commands
330 % (as well as higher-level commands built on these, such as the
331 % |\SortIndex| and |\changes| commands) and \package{docindex} will use
332 % these hooks unless it gets passed the \describeoption{oldkeywords}
333 % \texttt{oldkeywords} option. If you are creating a third unsorted
334 % index file then you will have to make sure that the command for writing
335 % to that file uses |\docindexentry| in the right place.
336 %
337 % The other difference concerns the composite page numbers. The string
338 % which separates the parts of a composite page number is not a
339 % hyphen `|-|', but the string `|\+|'. (The |\+| command is locally
340 % defined for the typesetting of each index by the \texttt{docindex}
341 % template being used, and the default is to typeset a hyphen.) Again
342 % the \package{xdoc} package provides a hook for this, and this hook is
343 % used by \package{docindex} unless it gets passed the
344 % \texttt{oldkeywords} option.
345 %
346 % It also deserves to be listed which the metacharacters are that are
347 % the same as in \package{doc} indices. The level separator is `|>|',
348 % the sort~key\slash item~text separator is `|=|', and the quote
349 % character is `|!|'. All other \program{makeindex} metacharacter
350 % parameters have their default values.
351 %
352 %
353 %
354 % \subsection{Configuration}
355 %
356 % Configuration of the layout provided by the \package{docindex}
357 % package is primarily done by redefining the \texttt{index} and
358 % \texttt{changes} instances of type \texttt{docindex}, since these are
359 % the instances that are used by the |\PrintIndex| and |\PrintChanges|
360 % commands.
361 %
362 % The index in the \texttt{source2e.tex} file (the main driver for the
363 % \LaTeXe\ source) differs from the default in three respects: it is set
364 % in two columns rather than three, there is no seperator character
365 % between the parts of a composite page number, and the pagestyle is set
366 % to \texttt{docindex} during the index. This is set up by the
367 % redefinition
368 %\begin{verbatim}
369 %\DeclareInstance{docindex}{index}{std}{
370 % columns=2, page-compositor={}, pagestyle=docindex
371 %}
372 %\end{verbatim}
373 % (There are however also some changes of parameters related to
374 % linebreaking; more on that in connection to configuration of the
375 % \texttt{changes} instance below.)
376 %
377 % Another kind of modification can be found in the \package{tclldoc}
378 % package~\cite{tclldoc}. Here the primary level in the index is used for
379 % names of procedures and variables, whereas the secondary level for the
380 % namespace of the same (the same name may have different definitions
381 % in different namespaces). If there is only one namespace for a given
382 % name then it is probably overkill to format them as two different
383 % index items, but better to join them. This can be achieved through
384 % the redefinition
385 %\begin{verbatim}
386 %\DeclareInstance{docindex}{index}{std}{%
387 % item1=fixed-r1a, item2=aloneaccept2
388 %}%
389 %\end{verbatim}
390 % An item handled by the \texttt{fixed-r1a} instance (of type
391 % \texttt{indexitem}) always tries to join with the following item but
392 % rejects to join with the preceeding one. An item handled by the
393 % \texttt{aloneaccept2} instance accepts to join with the preceeding
394 % item if neither that nor the following item is a secondary level item.
395 % Thus an item for a name will join with the following item for a
396 % namespace if there is only one such item. As the reader no doubt
397 % realises, this also solves the problem with the Bernoullis that was
398 % described in the introduction.
399 %
400 % \pagebreak[1]
401 %
402 % As for configuring the list of changes formatting, it is instructive
403 % to start by considering its default definition:
404 %\begin{verbatim}
405 %\DeclareInstance{docindex}{changes}{std}{
406 % file-extension = gls,
407 % item2 = fixed-r2a-nocomma,
408 % item3 = fixed-a3r,
409 % columns = 2,
410 % letter-format = ,
411 % letter-skip = 0pt
412 %}
413 %\end{verbatim}
414 % In the list of changes a secondary level item (which contains the name
415 % of the macro or whatever which was changed) is joined with the
416 % following tertiary level item (which details the change that was made).
417 % There are two columns and letter groups are not given any special
418 % formatting.
419 %
420 % The definition of \texttt{changes} that would be used for
421 % \texttt{source2e.tex} differs from the above in only one keyval,
422 % namely \textit{body-setup}, but that contains quite a lot of material.
423 % To begin with there is the default |\small| which selects the font.
424 % Then there is a |\makeatletter| which is needed because some |\changes|
425 % entries in the \LaTeX\ sources include commands (e.g.~|\TeX|) that
426 % (when written to file) expand to other commands whose names include the
427 % |@| character. If these are to be tokenized correctly, |@| must be a
428 % letter when the \texttt{.gls} file is being inputted. Last, but not
429 % least, there is a modification of the linebreaking parameters:
430 %\begin{verbatim}
431 %\UseTemplate{linebreak}{TeX}{
432 %\end{verbatim}
433 % The file \texttt{source2e.tex} explicitly sets \textit{hbadness} and
434 % \textit{hfuzz} to make \TeX\ shut up about over- and underfull hboxes.
435 %\begin{verbatim}
436 % hbadness=10000, hfuzz=\maxdimen,
437 %\end{verbatim}
438 % In addition to this, there are a couple of parameters that are set by
439 % the \texttt{multicols} environment to values quite different from the
440 % defaults of the \texttt{TeX} template and thus must be set too. Here
441 % they are shown with their default values. The value of
442 % \textit{emergency\-stretch} could probably be increased.
443 %\begin{verbatim}
444 % pretolerance=-1, tolerance=9999, emergencystretch=8pt
445 %}
446 %\end{verbatim}
447 % Summing that up, we arrive at the following definition of the
448 % \texttt{changes} instance for \texttt{source2e.tex}.
449 %\begin{verbatim}
450 %\DeclareInstance{docindex}{changes}{std}{
451 % file-extension = gls,
452 % item2 = fixed-r2a-nocomma,
453 % item3 = fixed-a3r,
454 % columns = 2,
455 % letter-format = ,
456 % letter-skip = 0pt,
457 % body-setup = \small\makeatletter
458 % \UseTemplate{linebreak}{TeX}{
459 % hbadness=10000, hfuzz=\maxdimen,
460 % pretolerance=-1, tolerance=9999, emergencystretch=8pt
461 % }
462 %}
463 %\end{verbatim}
464 %
465 % Another example can be found in the \package{fisource}
466 % package\footnote{It should probably rather be made a document class,
467 % but I haven't found it that necessary to change that aspect of it.}^^A
468 % ~(v\,2.10 or later), which sets up formatting for the \program{fontinst}
469 % source. There the list of changes should be set in one column, with
470 % items from the tertiary level being joined with their parent
471 % secondary level items iff the tertiary item is the only one having
472 % that particular parent item. This is achieved through the definition
473 %\begin{verbatim}
474 %\DeclareInstance{docindex}{changes}{std}{%
475 % file-extension = gls,
476 % item2 = fixed-r2a-nocomma,
477 % item3 = aloneaccept3,
478 % columns = 1,
479 % letter-format = {},
480 % letter-skip = 0pt
481 % }
482 %\end{verbatim}
483 % where the difference to the default definition is in the values for
484 % the \textit{item3} and \textit{columns} keys.
485 %
486 % For details on what they various keys mean, see the declaration of
487 % the \texttt{std} template of type \texttt{docindex} on
488 % page~\pageref{docindex:std}.
489 %
490 % With the \package{docidx2e} package, configuration follows the same
491 % logic, even though it is much more technical as one has to define
492 % the instances without the help of a template. The default instance
493 % definitions for the \package{docidx2e} package are the
494 % \begin{quote}
495 % |\@namedef{TP@I{}{docindex}{index}}#1#2{|\dots|}|\\
496 % |\@namedef{TP@I{}{docindex}{changes}}#1#2{|\dots|}|
497 % \end{quote}
498 % that begin on pages~\pageref{p:index-instance}
499 % and~\pageref{p:changes-instance} respectively.
500 %
501 %
502 %
503 %
504 %
505 % \StopEventually{
506 % % \begin{thebibliography}{9}
507 % \bibitem{xindex}
508 % Achim Blumensath: \textit{The \package{xindex} package};
509 % \textsc{http:}/\slash
510 % \texttt{www-mgi.\nolinebreak[3]informatik.\nolinebreak[3]^^A
511 % rwth-aachen.de}\slash \texttt{\textasciitilde blume}/.
512 % \bibitem{makeindex-paper}
513 % Pehong Chen, Michael A. Harrison:
514 % \textit{Index Preparation and Processing},
515 % Software: practice \& experience, vol. \textbf{19}, no. 9 (1988),
516 % 897--915;
517 % Computer Science Tech. Report 87/347, University of California,
518 % Berkeley, March 1987;
519 % \textsc{ctan:}\discretionary{}{}{\thinspace}\texttt{indexing}^^A
520 % \slash\texttt{makeindex}\slash\texttt{paper}\slash
521 % \texttt{ind.tex}.
522 % \bibitem{tclldoc}
523 % Lars Hellstr\"om:
524 % \textit{The \package{tclldoc} package and class},
525 % v\,2.20 or newer;
526 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
527 % \texttt{latex}\slash \texttt{contrib}\slash
528 % \texttt{tclldoc}\slash \texttt{tclldoc.dtx}.
529 % Note: At the time of writing, this has not yet been uploaded
530 % to CTAN.
531 % \bibitem{xdoc}
532 % Lars Hellstr\"om:
533 % \textit{The \package{xdoc} package --- experimental
534 % reimplementations of features from \package{doc},
535 % second~prototype}, 2000--2003;
536 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
537 % \texttt{latex}\slash \texttt{contrib}\slash \texttt{xdoc}\slash
538 % \texttt{xdoc2.dtx}.
539 % \bibitem{xindy}
540 % Roger Kehr:
541 % \textit{\program{xindy} --- A Flexible Indexing System};
542 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{indexing}^^A
543 % \slash\texttt{xindy}/.
544 % \bibitem{LaTeX-project}
545 % The \LaTeX3 Project: \textit{The \LaTeX\ Project Home Page};
546 % \textsc{http:}/\slash\texttt{www.latex-project.org}/.
547 % \bibitem{multicol}
548 % Frank Mittelbach: \textit{An environment for multicolumn output};
549 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
550 % \texttt{latex}\slash \texttt{required}\slash \texttt{tools}\slash
551 % \texttt{multicol.dtx}.
552 % \bibitem{doc}
553 % Frank Mittelbach, B.~Hamilton Kelly, Andrew Mills, Dave Love, and
554 % Joachim \mbox{Schrod}: \textit{The \package{doc} and
555 % \package{shortvrb} Packages}, The \LaTeX3 Project; ^^A , 1993~ff.
556 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
557 % \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}.
558 % \end{thebibliography}
559 % }
560 %
561 %
562 %
563 %
564 % \section{Implementation}
565 %
566 % \subsection{\package{docstrip} modules}
567 %
568 % This file contains a number of \package{docstrip} module directives,
569 % and many of these guard code that is not going to be used. In part
570 % this mirrors the development of the code (and may get cleared up
571 % eventually), but most of this duplication has to do with making the
572 % code work in many different set-ups (some of which involve other
573 % packages whose interface is rapidly changing).
574 %
575 % The modules which control \LaTeX\ code are:
576 % \begin{description}
577 % \item[\textsf{pkg}]
578 % Main guard for code that is to end up in some \LaTeX\ package.
579 % \item[\textsf{template}]
580 % Guard for code which uses features of the \package{template}
581 % package. This code will end up in the \package{docindex} package,
582 % whereas the equivalent code which avoids using templates ends up
583 % in the \package{docidx2e} package.
584 % \item[\textsf{default}]
585 % This code protects the default values for template keys. The
586 % syntax for this is changing, so the default values are currently
587 % being assigned in the template bodies instead.
588 % \end{description}
589 %
590 % The modules which control \program{makeindex} style files are:
591 % \begin{description}
592 % \item[\textsf{ist}]
593 % Code for the main style file \texttt{docindex.ist}.
594 % \item[\textsf{idx}]
595 % Code for a style file which is like the main one, but the input
596 % parameters are set to the same values as in the standard \LaTeX\
597 % \texttt{gind.ist}.
598 % \item[\textsf{glo}]
599 % Code for a style file which is like the main one, but the input
600 % parameters are set to the same values as in the standard \LaTeX\
601 % \texttt{gglo.ist}.
602 % \end{description}
603 %
604 %
605 % \subsection{Initial stuff}
606 %
607 % \begin{macrocode}
608 %<*pkg>
609 \NeedsTeXFormat{LaTeX2e}
610 \ProvidesPackage
611 %<template> {docindex}
612 %<!template> {docidx2e}
613 [2001/04/11 v1.00 doc index formatting package]
614 % \end{macrocode}
615 %
616 % Since the \texttt{multicols} environment is used by the \texttt{std}
617 % template of type \texttt{docindex}, the \package{multicol} package
618 % must have been loaded.
619 % \begin{macrocode}
620 \RequirePackage{multicol}
621 % \end{macrocode}
622 % This will probably change in \package{docindex} once I get around to
623 % check how this kind of thing is implemented in the \LaTeXplus\ output
624 % routine.
625 %
626 % Since the \texttt{docindex} pagestyle may be used the \package{xdoc}
627 % package must have been loaded. This also loads the \package{doc}
628 % package which contains the definition of |\pfill|.
629 % \begin{macrocode}
630 \RequirePackage{xdoc2}[2001/03/26]
631 % \end{macrocode}
632 %
633 %
634 % \begin{option}{oldkeywords}
635 % The \texttt{oldkeywords} option tells the \package{docindex}
636 % package to not change the index entry keywords from the \package{doc}
637 % defaults. The code for this option appears further down.
638 % \begin{macrocode}
639 \DeclareOption{oldkeywords}{}
640 % \end{macrocode}
641 % \end{option}
642 %
643 % \begin{option}{usedocindexps}
644 % The \texttt{usedocindexps} option tells the \package{docindex}
645 % package to set the pagestyle to \texttt{docindex} (defined by
646 % \package{xdoc}) when typesetting the index. The code for this option
647 % appears further down.
648 % \begin{macrocode}
649 \DeclareOption{usedocindexps}{}
650 % \end{macrocode}
651 % \end{option}
652 %
653 % \begin{macrocode}
654 \ProcessOptions\relax
655 %</pkg>
656 % \end{macrocode}
657 %
658 %
659 %
660 % \subsection{Index style files}
661 % \label{Ssec:ist}
662 %
663 % The \program{makeindex} style files uses four commands. The most
664 % important command is \DescribeMacro{\indexitem}|\indexitem|, which
665 % has the two syntaxes
666 % \begin{quote}
667 % |\indexitem|\marg{level}\marg{text}\marg{next level}\\
668 % |\indexitem|\marg{level}\marg{text}|{9}|\marg{numbers}^^A
669 % \marg{next level}
670 % \end{quote}
671 % The \meta{level} is an integer in the range 1--3, the \meta{next level}
672 % is an integer in the range 0--3, the \meta{text} is the item text,
673 % and the \meta{numbers} is a list of (page or the like) numbers. The
674 % reason for this dual syntax is limitations of \program{makeindex}:
675 % there is no way of making the text inserted after an item depend on
676 % whether there are any page numbers for this item, so one cannot make
677 % \meta{numbers} a straightforward optional argument.
678 %
679 % The level numbers specify at what level the item is. Level~1
680 % corresponds to |\item|, level~2 corresponds to |\subitem|, and
681 % level~3 corresponds to |\subsubitem|. The \meta{next level} number
682 % may also be 0, and that denotes non-|\indexitem| material such as a
683 % space between letter groups or the end of the index. The purpose of
684 % the \meta{next level} argument is to let the formatting of an item
685 % depend on what level the next item has, a feature that
686 % \program{makeindex} alone doesn't provide. Since \program{makeindex}
687 % only supports putting text in front of things, each new item must
688 % begin by inserting the closing brace on the second last argument and
689 % the very last argument of the \emph{previous} item before it can do
690 % anything for itself. This leads to the following contents of the
691 % \program{makeindex} |item_|\textellipsis\ parameters.
692 %
693 % \xrefoff
694 % \begin{macrocode}
695 %<*ist|idx|glo>
696 item_0 "}{1}\n\\indexitem{1}{"
697 item_1 "}{2}\n \\indexitem{2}{"
698 item_01 "}{2}\n \\indexitem{2}{"
699 item_x1 "}{2}\n \\indexitem{2}{"
700 item_2 "}{3}\n \\indexitem{3}{"
701 item_12 "}{3}\n \\indexitem{3}{"
702 item_x2 "}{3}\n \\indexitem{3}{"
703 % \end{macrocode}
704 % \SpecialIndex{\indexitem} ^^A I can't believe I'm using this!
705 % \begin{macrocode}
706 delim_0 "}{9}{"
707 delim_1 "}{9}{"
708 delim_2 "}{9}{"
709 delim_n ", "
710 delim_r "--"
711 %</ist|idx|glo>
712 % \end{macrocode}
713 % \xrefon
714 %
715 %
716 % \begin{macro}{\indexitem}
717 % \begin{macro}{\DI@indexitem}
718 % \begin{macro}{\DI@indexitem@}
719 % \begin{macro}{\DI@last@level}
720 % The |\indexitem| command (and its subsidiary macros |\DI@indexitem|
721 % and |\DI@indexitem@| only handle argument grabbing and some
722 % elementary processing of level numbers. The formatting of the item
723 % is instead handled by the |\DI@indexitem@|\meta{level}, where
724 % \meta{level} is the roman numeral |i|, |ii|, or |iii|, family of
725 % control sequences. |\indexitem| itself doesn't grab any arguments,
726 % instead it inserts the contents of |\DI@last@level| as an
727 % additional argument in front of |\DI@indexitem|. The actual
728 % argument structures of the other macros are
729 % \begin{quote}
730 % |\DI@indexitem|\marg{last}\marg{this}\marg{text}^^A
731 % \marg{next/\texttt{9}}\\
732 % |\DI@indexitem@|\marg{cmd}\marg{last}|{9}|\marg{text}^^A
733 % |\NoValue|\marg{figures}\marg{next}
734 % \end{quote}
735 % where \meta{this} is the level of this item, \meta{next} is the
736 % level of the next item, \meta{text} is the item text, and
737 % \meta{figures} are the (page) numbers for this item. Several of the
738 % arguments of |\DI@indexitem@| are immediately gobbled; they are
739 % only used when the original |\indexitem| did not have a
740 % \meta{numbers} argument.
741 %
742 % The |\DI@last@level| macro stores the level of the last item before
743 % the current. It is set and used by |\DI@indexitem@|.
744 % \begin{macrocode}
745 %<*pkg>
746 \newcommand\indexitem{%
747 \relax
748 \expandafter\DI@indexitem \expandafter{\DI@last@level}%
749 }%
750 % \end{macrocode}
751 % \begin{macrocode}
752 \def\DI@indexitem#1#2#3#4{%
753 \edef\DI@last@level{\number#2\expandafter}%
754 \ifnum #4=9
755 \expandafter\expandafter \expandafter\DI@indexitem@
756 \fi
757 \csname DI@indexitem@\romannumeral#2\expandafter\endcsname
758 {#1}{#4}{#3}\NoValue
759 }
760 % \end{macrocode}
761 % \begin{macrocode}
762 \def\DI@indexitem@#1#2#3#4#5#6#7{#1{#2}{#7}{#4}{#6}}
763 % \end{macrocode}
764 % \begin{macrocode}
765 \def\DI@last@level{0}
766 %</pkg>
767 % \end{macrocode}
768 % \end{macro}\end{macro}\end{macro}\end{macro}
769 %
770 % The \describecsfamily{DI@indexitem@\meta{level}}|\DI@indexitem@|^^A
771 % \meta{level}, where \meta{level} is the lower case roman numeral form
772 % of the level number, family of control sequences have the syntax
773 % \begin{quote}
774 % |\DI@indexitem@|\meta{level}\,\marg{previous}\marg{next}^^A
775 % \marg{text}\marg{figures}
776 % \end{quote}
777 % where \meta{previous} and \meta{next} are the levels of the previous
778 % and following index items, \meta{text} is the entry text of this
779 % item, and \meta{figures} are the (page) numbers for this item, if it
780 % has any, or the token |\NoValue|, if it hasn't.
781 %
782 %
783 % \xrefoff
784 % \begin{macrocode}
785 %<*ist|idx|glo>
786 group_skip "}{0}\n%^^A\n\\indexnewletter{0}{"
787 heading_prefix ""
788 heading_suffix ""
789 headings_flag 1
790 %</ist|idx|glo>
791 % \end{macrocode}
792 % \SpecialIndex{\indexnewletter}
793 % \xrefon
794 %
795 %
796 % \begin{macro}{\indexnewletter}
797 % \changes{v\,1.00}{2001/04/05}{Made it \cs{outer}. (LH)}
798 % The |\indexnewletter| command is placed in front of a new letter
799 % group. It has the syntax
800 % \begin{quote}
801 % |\indexnewletter|\marg{first}\marg{letter}\marg{next}
802 % \end{quote}
803 % where \meta{first} is a flag (|1| if this |\indexnewletter|
804 % is at the very beginning of the index, |0| otherwise), \meta{letter}
805 % is the letter name (according to the \program{makeindex} program; it
806 % can be e.g.\ the string `Symbols') and \meta{next} is the level of
807 % the next item (I think this will always be |1| with
808 % \program{makeindex}). The command takes care of declining an offer
809 % to join with the previous index item, inserts some vertical space
810 % if the \meta{first} is |0|, print the \meta{letter} using
811 % |\DI@letter@format|, and doesn't offer to join with the following
812 % item.
813 % \begin{macrocode}
814 %<*pkg>
815 \@ifundefined{indexnewletter}{}{%
816 \PackageInfo
817 %<template> {docindex}
818 %<!template> {docidx2e}
819 {Command \protect\indexnewletter\space redefined}
820 }
821 \outer\def\indexnewletter#1#2#3{%
822 \DI@item@nojoin
823 \ifnum #1=\z@ \vspace{\DI@letter@skip}\fi
824 \DI@letter@format{#2}%
825 \def\DI@last@level{0}%
826 \let\DI@item@join\@firstofone
827 \let\DI@item@nojoin\@empty
828 }
829 %</pkg>
830 % \end{macrocode}
831 % \end{macro}
832 %
833 % The index style files also need to set some parameters which aren't
834 % directly connected to the commands provided by the \package{docindex}
835 % package. First there's the input style parameters:\xrefoff
836 % \begin{macrocode}
837 %<*ist|idx|glo>
838 actual '='
839 quote '!'
840 level '>'
841 % \end{macrocode}
842 % Then the page precedence should be changed. This is mainly for the
843 % convenience of use with documents that |\DocInclude| files, since
844 % these by default number the files using letters.
845 % \begin{macrocode}
846 page_precedence "naArR"
847 % \end{macrocode}
848 % In \texttt{docindex.ist}, both the \texttt{keyword} and the
849 % |page_compositor| strings are different from their standard values. It
850 % turns out to be hard to use a normal command as page compositor,
851 % because \program{makeindex} always rejects spaces and braces in the
852 % page number even if they is in the |page_compositor| parameter!
853 % \begin{macrocode}
854 %<ist>keyword "\\xdocindexentry"
855 %<ist>page_compositor "\\+"
856 % \end{macrocode}
857 % \SpecialIndex{\+}
858 % Finally, in the style file for the list of changes, the keyword must
859 % be changed to |\glossaryentry|.
860 % \begin{macrocode}
861 %<glo>keyword "\\glossaryentry"
862 %</ist|idx|glo>
863 % \end{macrocode}
864 % \xrefon
865 %
866 %
867 % \begin{option}{oldkeywords}
868 % \begin{macro}{\XD@index@keyword}
869 % \begin{macro}{\XD@glossary@keyword}
870 % \begin{macro}{\XD@page@compositor}
871 % \changes{v\,1.00}{2001/04/05}{Changed it from \cs{PageCompositor-} to
872 % \cs{+}. (LH)}
873 % To make the contents of the \texttt{.idx} and \texttt{.glo} files
874 % compatible with the input parameter settings of
875 % \texttt{docindex.ist}, some macros used by the \package{xdoc}
876 % package must be redefined. This can however be stopped if the
877 % \texttt{oldkeywords} option is passed to the \package{docindex}
878 % package.
879 % \begin{macrocode}
880 %<*pkg>
881 \@ifpackagewith
882 %<template> {docindex}
883 %<!template> {docidx2e}
884 {oldkeywords}{}{
885 \edef\XD@index@keyword{\@backslashchar xdocindexentry}
886 \let\XD@glossary@keyword\XD@index@keyword
887 \def\XD@page@compositor{\@backslashchar +}
888 }
889 % \end{macrocode}
890 % \end{macro}\end{macro}\end{macro}\end{option}
891 %
892 % \changes{v\,1.00}{2001/03/25}{The index file is no longer a
893 % \texttt{thedocindex} environment---the layout must instead be set
894 % by the command which \cs{input}s the index. Introduced the
895 % \cs{docindexguard} command to handle situations with incompatible
896 % index styles. (LH)}
897 %
898 % \begin{macro}{\docindexguard}
899 % \begin{macro}{\DI@ind@setup}
900 % The first line of every \texttt{docindex} style sorted index file is
901 % \begin{quote}
902 % |\docindexguard{\endinput}|
903 % \end{quote}
904 % If the index file is inputted as a classical sorted index file then
905 % this will produce an undefined command error and no more lines in
906 % the index will be read. If the index file is inputted using the
907 % conventions of the \package{docindex} package then the
908 % |\docindexguard| will instead gobble the |\endinput| so that the
909 % file will be read.
910 %
911 % One can also have the opposite problem: a classical style index file
912 % is being input using \package{docindex} conventions. It is to
913 % overcome this problem that the |\DI@ind@setup| command has been
914 % introduced. Classical style index files begin by a |\begin|
915 % command, so that command is temporarily redefined to print a warning
916 % message and |\endinput| the file. Should the first command instead
917 % be |\docindexguard| then everything will be reset to normal. To
918 % accomplish this, |\DI@ind@setup| opens a group which should be
919 % closed by the initial |\docindexguard| or |\begin|.
920 % \begin{macrocode}
921 \def\DI@ind@setup{\bgroup
922 \def\docindexguard##1{\egroup}%
923 \def\begin##1{%
924 \egroup
925 \PackageWarningNoLine
926 %<template> {docindex}%
927 %<!template> {docidx2e}%
928 {Ignoring old style index file}
929 \endinput
930 }%
931 }
932 %</pkg>
933 % \end{macrocode}
934 % \end{macro}\end{macro}
935 %
936 % \xrefoff
937 % \begin{macrocode}
938 %<*idx|glo|ist>
939 preamble "\\docindexguard{\\endinput}\n%^^A\n\\indexnewletter{1}{"
940 postamble "}{0}\n\\endinput"
941 %</idx|glo|ist>
942 % \end{macrocode}
943 % \SpecialIndex{\docindexguard}
944 % \SpecialIndex{\indexnewletter}
945 % \xrefon
946 %
947 % In summary, this is the BNF syntax for a sorted index file that is to
948 % be typeset using \package{docindex}:
949 % \begin{syntax}
950 % \item[sorted index file]
951 % \meta{guard}\meta{lettergroups}|\endinput|
952 % \item[guard] |\docindexguard{\endinput}|
953 % \item[lettergroups] \meta{lettergroup}\branch
954 % \meta{lettergroup}\meta{lettergroups}
955 % \item[lettergroup] \meta{heading}\meta{items}
956 % \item[heading]
957 % |\indexnewletter|\marg{first}\marg{letter}\marg{next}
958 % \item[items] \meta{empty}\branch \meta{item}\meta{items}
959 % \item[item] |\indexitem|\marg{level}\marg{text}\marg{next}\branch
960 % |\indexitem|\marg{level}\marg{text}|{9}|\marg{numbers}\marg{next}
961 % \end{syntax}
962 % A \meta{level} is |1|, |2|, or |3|. A \meta{next} is |0|, |1|, |2|, or
963 % |3|. Within a \meta{lettergroup}, the \meta{next} of one \meta{item}
964 % or the \meta{heading} must equal the \meta{level} of the next
965 % \meta{item} and the \meta{next} of the last item must be |0|. The
966 % \meta{first} should be |1| in the first \meta{lettergroup} and |0| in
967 % all the others.
968 %
969 %
970 % \subsection{Template mechanisms}
971 %
972 % The \package{docindex} package loads the \package{xhj} and
973 % \package{galley2} packages to gain access to the \texttt{justification}
974 % type templates. This indirectly loads the \package{xparse} and
975 % \package{template} packages.
976 % \begin{macrocode}
977 %<*pkg>
978 %<template>\RequirePackage{xhj,galley2}
979 % \end{macrocode}
980 %
981 % Since the \package{docidx2e} package doesn't use the template mechanisms
982 % provided by the \package{template} package, but still is to follow the
983 % logic of the \package{docindex} package which does use these
984 % mechanisms, it becomes convenient to define fakes for a couple of
985 % \package{template} commands. First \package{docidx2e} checks if the
986 % real \package{template} package has been loaded and emits a warning if
987 % it has.
988 % \begin{macrocode}
989 %<*!template>
990 \@ifpackageloaded{template}{
991 \PackageWarningNoLine{docidx2e}{The docidx2e package is only meant%
992 \MessageBreak for use when LaTeX2e* packages like
993 template\MessageBreak are not available.}
994 }{}
995 % \end{macrocode}
996 %
997 % Before continuing with the definitions, some of the data structures
998 % used by the \package{template} mechanisms must be explained. A
999 % template \emph{instance} is really only a macro; what makes instances
1000 % different from macros in general is that they usually aren't
1001 % explicitly programmed. Instead they are formed by combining two
1002 % different pieces of code: one which is the code part of some template,
1003 % and one which is a piece of code which sets the \emph{container}
1004 % macros\slash registers\slash parameters for the key values of this
1005 % template. In general, the first piece of code contains the
1006 % programming-like aspects of what the instance does, whereas the latter
1007 % contains those that have to do with lauout and design. The advantage
1008 % of this model is that it lets you implement many layouts without
1009 % requiring you to know everything about \LaTeX\ programming that it
1010 % would take to implement everything using macros.
1011 %
1012 % Instances are stored in control sequences of the form
1013 % \begin{quote}
1014 % \describecsfamily{TP@I{\meta{collection}}\break
1015 % {\meta{type}}\break{\meta{name}}}
1016 % |\TP@I|\marg{collection}\marg{type}\marg{name}
1017 % \end{quote}
1018 % The \meta{type} is the primary distinction between instances; for each
1019 % type there exists a specification of what all instances of that type
1020 % must do, and all instances of a type must be interchangeable. In
1021 % particular, all instances of a given template type must have the same
1022 % argument structure. The \meta{name} is simply the name used to
1023 % identify the instance (amongst all other instances of that type).
1024 % Finally, the \meta{collection} is something which can be used in
1025 % circumstances where one needs to quickly switch between different
1026 % definitions of an instance. If they have different \meta{collection}s
1027 % then they can exist simutaneously; which of them is used is determined
1028 % by which collection is currently active.
1029 %
1030 % Collections are active on a ``per type'' basis; which collection is
1031 % active for instances of type \meta{type} is determined by the
1032 % contents of the \describecsfamily{TP@T{\meta{type}}}
1033 % |\TP@T|\marg{type} control sequences, which are macros with the
1034 % structure
1035 % \begin{quote}
1036 % \marg{collection}\marg{arguments}
1037 % \end{quote}
1038 % If there is no instance with the requested name in the currently
1039 % active collection then the instance with the same name from the
1040 % normal collection (whose name is the empty string) will be used. The
1041 % \meta{arguments} part of the macro is simply the number of arguments
1042 % of instances of this type; it is only used when declaring templates.
1043 %
1044 % \begin{macro}{\UseCollection}
1045 % The |\UseCollection| command sets the active collection for a given
1046 % type. It has the syntax
1047 % \begin{quote}
1048 % |\UseCollection|\marg{type}\marg{collection}
1049 % \end{quote}
1050 % This macro was used up to v\,1.00 of \package{docindex} but a change
1051 % in the package logic made it unnecessary.
1052 % \begin{macrocode}
1053 % \providecommand*\UseCollection[2]{%
1054 % \expandafter\edef \csname TP@T{#1}\endcsname{%
1055 % {#2}%
1056 % {\expandafter\expandafter \expandafter\@secondoftwo
1057 % \csname TP@T{#1}\endcsname}%
1058 % }%
1059 % }
1060 % \end{macrocode}
1061 % \end{macro}
1062 %
1063 % \begin{macro}{\@letinstance}
1064 % The |\@letinstance| macro |\let|s the (currently used) instance
1065 % with given name and type to the \meta{target} control sequence. It
1066 % has the syntax
1067 % \begin{quote}
1068 % |\@letinstance|\marg{target}\marg{type}\marg{name}
1069 % \end{quote}
1070 % \begin{macrocode}
1071 \def\@letinstance#1#2#3{%
1072 \expandafter\let \expandafter#1%
1073 \csname TP@I%
1074 {\expandafter\expandafter \expandafter\@firstoftwo
1075 \csname TP@T{#2}\endcsname}%
1076 {#2}{#3}%
1077 \endcsname
1078 \ifx \relax#1%
1079 \expandafter\let \expandafter#1\csname TP@I{}{#2}{#3}\endcsname
1080 \fi
1081 }
1082 % \end{macrocode}
1083 % \end{macro}
1084 %
1085 % \begin{macro}{\UseInstance}
1086 % The |\UseInstance| calls the (currently used) instance with given
1087 % name and type. Its syntax is
1088 % \begin{quote}
1089 % |\UseInstance|\marg{type}\marg{name}\,\meta{arguments of instance}
1090 % \end{quote}
1091 % \begin{macrocode}
1092 \providecommand*\UseInstance[2]{%
1093 \@letinstance\@tempa{#1}{#2}%
1094 \ifx \relax\@tempa
1095 \PackageError{docidx2e}{Instance #2 of type #1 undefined}\@eha
1096 \else
1097 \expandafter\@tempa
1098 \fi
1099 }
1100 %</!template>
1101 % \end{macrocode}
1102 % \end{macro}
1103 %
1104 %
1105 %
1106 % \subsection{Templates for index item formatting}
1107 %
1108 % \begin{templatetype}{justification}
1109 % In \package{docidx2e}, we have to provide a dummy definition of
1110 % |\TP@T{justification}|.
1111 % \begin{macrocode}
1112 %<!template>\@namedef{TP@T{justification}}{{}{0}}
1113 % \end{macrocode}
1114 % \end{templatetype}
1115 %
1116 % \changes{v\,1.00}{2001/04/08}{Using \texttt{single} template rather
1117 % than the \texttt{std} template for the \texttt{indexitem}$n$
1118 % instances of type \texttt{justification}. (LH)}
1119 % \begin{instance}{justification}{indexitem1}
1120 % \begin{instance}{justification}{indexitem2}
1121 % \begin{instance}{justification}{indexitem3}
1122 % The \texttt{indexitem}\meta{level} instances of the
1123 % \texttt{justification} template set up paragraph indentation etc.\
1124 % for a paragraph containing an index item at that level. The layout
1125 % is the same as that used by the \package{doc} package, but it is
1126 % not specified in quite the same way.
1127 % \begin{macrocode}
1128 %<*template>
1129 \DeclareInstance{justification}{indexitem1}{single}{
1130 leftskip=30pt, rightskip=15pt, startskip=-30pt, parfillskip=-15pt,
1131 linefillskip=0pt plus 1fil, parindent=0pt
1132 }
1133 \DeclareInstance{justification}{indexitem2}{single}{
1134 leftskip=30pt, rightskip=15pt, startskip=-15pt, parfillskip=-15pt,
1135 linefillskip=0pt plus 1fil, parindent=0pt
1136 }
1137 \DeclareInstance{justification}{indexitem3}{single}{
1138 leftskip=30pt, rightskip=15pt, startskip=-5pt, parfillskip=-15pt,
1139 linefillskip=0pt plus 1fil, parindent=0pt
1140 }
1141 %</template>
1142 %<*!template>
1143 \@namedef{TP@I{}{justification}{indexitem1}}{%
1144 \leftskip=30\p@
1145 \rightskip=15\p@
1146 \parindent=-30\p@
1147 \parfillskip=-\rightskip
1148 }
1149 \@namedef{TP@I{}{justification}{indexitem2}}{%
1150 \leftskip=30\p@
1151 \rightskip=15\p@
1152 \parindent=-15\p@
1153 \parfillskip=-\rightskip
1154 }
1155 \@namedef{TP@I{}{justification}{indexitem3}}{%
1156 \leftskip=30\p@
1157 \rightskip=15\p@
1158 \parindent=-5\p@
1159 \parfillskip=-\rightskip
1160 }
1161 %</!template>
1162 % \end{macrocode}
1163 % \end{instance}\end{instance}\end{instance}
1164 %
1165 %
1166 %
1167 % \subsubsection{The \texttt{indexitem} template type}
1168 %
1169 % \begin{templatetype}{indexitem}
1170 % \begin{macro}{\DI@item@nojoin}
1171 % \begin{macro}{\DI@item@join}
1172 % The argument structure of a template of type \texttt{indexitem} is
1173 % \begin{quote}
1174 % \marg{previous}\marg{next}\marg{text}\marg{figures}
1175 % \end{quote}
1176 % \meta{previous} and \meta{next} are the level codes of the index
1177 % item before and after the current item, \meta{text} is the item text
1178 % of the current index item, and \meta{figures} are the (page) numbers
1179 % for this item, if it has any, or the token |\NoValue|, if it hasn't.
1180 %
1181 % Templates of this type format and typeset one item in an index. In
1182 % doing so they may do pretty much anything as long as the other items
1183 % aren't affected: they may start and end paragraphs, change the
1184 % paragraph justification, \textellipsis
1185 %
1186 % There is however one area in which the rules are rather strict, and
1187 % that has to do with when two items can be joined. In a case where
1188 % item A is followed by item B, item A can propose to item B that they
1189 % should be joined and item B can then accept or decline this offer.
1190 % Technically the offer consists of defining the two macros
1191 % |\DI@item@join| and |\DI@item@nojoin|. If item B accepts the offer
1192 % it will execute |\DI@item@join| and if it declines the offer it
1193 % will execute |\DI@item@nojoin|. A typical definition of
1194 % |\DI@item@join| might be to insert a punctuation mark and a typical
1195 % definition of |\DI@item@nojoin| might be to end the current paragraph.
1196 %
1197 % There is however also a third case, namely that no offer was given.
1198 % In this case |\DI@item@nojoin| should be |\let| to |\@empty| and
1199 % |\DI@item@join| should be |\let| to |\@firstofone|. The reason for
1200 % this last rule is that |\DI@item@join| has the syntax
1201 % \begin{quote}
1202 % |\DI@item@join|\marg{no-join recovery code}
1203 % \end{quote}
1204 % where the \meta{no-join recovery code} is code that item B needs to
1205 % have executed if there is no join although item B would have
1206 % accepted it. |\DI@item@nojoin|, on the other hand, takes no
1207 % argument.
1208 % \begin{macrocode}
1209 %<template>\DeclareTemplateType{indexitem}{4}
1210 %<!template>\@namedef{TP@T{indexitem}}{{}{4}}
1211 \let\DI@item@join=\@firstofone
1212 \let\DI@item@nojoin=\@empty
1213 % \end{macrocode}
1214 % \end{macro}\end{macro}\end{templatetype}
1215 %
1216 % \begin{template}{indexitem}{fixed}
1217 % The \texttt{fixed} template of type \texttt{indexitem} formats an
1218 % item as the items in \package{doc}'s \texttt{theindex} environment.
1219 % It is fixed in that it ignores the levels of the surrounding items.
1220 %
1221 % The keys for this template are:
1222 % \begin{description}
1223 % \keyvalitem{justification-setup}{i}
1224 % This is a template instance of type \texttt{justification}. It
1225 % sets the justification for the paragraph containing the item,
1226 % unless the item is being joined with the preceeding item.
1227 % \keyvalitem{pre-join}{b}
1228 % A switch for whether the item should accept to be joined with
1229 % the item before. True means ``accept'', false means ``decline''
1230 % (which is the default).
1231 % \keyvalitem{nofig-action}{f1}
1232 % If the \meta{figures} argument is |\NoValue| then the \meta{text}
1233 % argument is passed on to this macro for the actual formatting.
1234 % The default expansion is precisely the \meta{text}.
1235 % \keyvalitem{fig-action}{f2}
1236 % If the \meta{figures} argument is not |\NoValue| then the
1237 % \meta{text} and \meta{figures} arguments are passed on (in that
1238 % order) to this macro for the actual formatting. The default
1239 % expansion is
1240 % \begin{quote}
1241 % \meta{text}|\pfill|\meta{figures}
1242 % \end{quote}
1243 % \keyvalitem{post-join}{b}
1244 % A switch for whether the item should offer to join with the
1245 % following item. True means ``make offer'', false (which is the
1246 % default) means ``don't make offer''. Making the offer is
1247 % furthermore conditioned by that the \meta{figures} argument is
1248 % |\NoValue|.
1249 % \keyvalitem{nojoin-extra}{f0}
1250 % Extra code which is inserted after the normal code for an item
1251 % if the item neither has any figures nor offers to join with the
1252 % following item. The default value is a space of length
1253 % \textit{linefillskip} followed by a |\nopagebreak|.^^A
1254 % \changes{v\,0.03}{2001/02/24}{Added the \textit{nojoin-extra}
1255 % key. (LH)}^^A
1256 % \changes{v\,0.03}{2001/02/25}{Added \cs{nopagebreak} from
1257 % \cs{efill} to default for \textit{nojoin-extra} key. (LH)}
1258 % \keyvalitem{join-extra}{f0}
1259 % Extra text which is inserted after the normal text of the item
1260 % if there is a join, by default a comma and a space.
1261 % \keyvalitem{offjoin-extra}{f0}
1262 % Extra code which is inserted after the normal text of the item
1263 % if a join is offered but declined. The default value is a space
1264 % of length \textit{linefillskip} followed by a |\nopagebreak|
1265 % (larger than the one from \textit{nojoin-extra}; if not for
1266 % this, the default could have been taken to be
1267 % |\DI@nojoin@extra|).
1268 % \end{description}
1269 %
1270 % Note that the contents of the \textit{nojoin-extra},
1271 % \textit{join-extra}, and \textit{offjoin-extra} keys must be robust
1272 % as they may be subjected to a |\protected@edef|.
1273 % \changes{v\,0.03}{2001/02/24}{\cs{protected@edef}ing the macros
1274 % \cs{DI@item@join} and \cs{DI@item@nojoin}. (LH)}
1275 %
1276 % \begin{macrocode}
1277 %<*template>
1278 \DeclareTemplate{indexitem}{fixed}{4}{
1279 justification-setup =i{justification} \DI@item@justification,
1280 pre-join =b
1281 %<default> {false}
1282 DI@prejoin@,
1283 nofig-action =f1
1284 %<default> {#1}
1285 \DI@nofig,
1286 fig-action =f2
1287 %<default> {#1\pfill#2}
1288 \DI@hasfig,
1289 post-join =b
1290 %<default> {false}
1291 DI@postjoin@,
1292 nojoin-extra =f0
1293 %<default> {\hspace*{\justification@g}
1294 %<default> \protect\nopagebreak[2]}
1295 \DI@nojoin@extra,
1296 join-extra =f0
1297 %<default> {,\space}
1298 \DI@join@extra,
1299 offjoin-extra =f0
1300 %<default> {\hspace*{\justification@g}
1301 %<default> \protect\nopagebreak[4]}
1302 \DI@offjoin@extra
1303 }{%
1304 %<*!default>
1305 \let\ifDI@prejoin@\iffalse
1306 \let\DI@nofig\@firstofone
1307 \def\DI@hasfig##1##2{##1\pfill##2}%
1308 \let\ifDI@postjoin@\iffalse
1309 \def\DI@nojoin@extra{%
1310 \hspace*{\justification@g}\protect\nopagebreak[2]%
1311 }%
1312 \def\DI@join@extra{,\space}%
1313 \def\DI@offjoin@extra{%
1314 \hspace*{\justification@g}\protect\nopagebreak[4]%
1315 }%
1316 %</!default>
1317 \DoParameterAssignments
1318 \ifDI@prejoin@
1319 \DI@item@join{\DI@item@justification}%
1320 \else
1321 \DI@item@nojoin\DI@item@justification
1322 \fi
1323 \let\DI@item@join\@firstofone
1324 \let\DI@item@nojoin\@empty
1325 \IfNoValueTF{#4}{%
1326 \DI@nofig{#3}%
1327 \ifDI@postjoin@
1328 \protected@edef\DI@item@join##1{\DI@join@extra}%
1329 \protected@edef\DI@item@nojoin{\DI@offjoin@extra\protect\par}%
1330 \else
1331 \DI@nojoin@extra\par
1332 \fi
1333 }{%
1334 \DI@hasfig{#3}{#4}%
1335 \par
1336 }%
1337 \ignorespaces
1338 }
1339 % \end{macrocode}
1340 % \end{template}
1341 %
1342 % \begin{instance}{indexitem}{fixed1}
1343 % \begin{instance}{indexitem}{fixed2}
1344 % \begin{instance}{indexitem}{fixed3}
1345 % The \texttt{fixed1}, \texttt{fixed2}, and \texttt{fixed3} instances
1346 % of type \texttt{indexitem} are simply the \texttt{fixed} template
1347 % with different values assigned to the \textit{justification-setup}
1348 % key.
1349 % \begin{macrocode}
1350 \DeclareInstance{indexitem}{fixed1}{fixed}
1351 {justification-setup = indexitem1}
1352 \DeclareInstance{indexitem}{fixed2}{fixed}
1353 {justification-setup = indexitem2}
1354 \DeclareInstance{indexitem}{fixed3}{fixed}
1355 {justification-setup = indexitem3}
1356 %</template>
1357 %<*!template>
1358 \@namedef{TP@I{}{indexitem}{fixed1}}#1#2#3#4{%
1359 \@letinstance\DI@item@justification{justification}{indexitem1}%
1360 \DI@item@nojoin
1361 \DI@item@justification
1362 \ifx \NoValue#4%
1363 #3\nobreak\hfil\nopagebreak[2]%
1364 \else
1365 #3\pfill#4%
1366 \fi
1367 \let\DI@item@join\@firstofone
1368 \let\DI@item@nojoin\@empty
1369 \par
1370 }
1371 \@namedef{TP@I{}{indexitem}{fixed2}}#1#2#3#4{%
1372 \@letinstance\DI@item@justification{justification}{indexitem2}%
1373 \DI@item@nojoin
1374 \DI@item@justification
1375 \ifx \NoValue#4%
1376 #3\nobreak\hfil\nopagebreak[2]%
1377 \else
1378 #3\pfill#4%
1379 \fi
1380 \let\DI@item@join\@firstofone
1381 \let\DI@item@nojoin\@empty
1382 \par
1383 }
1384 \@namedef{TP@I{}{indexitem}{fixed3}}#1#2#3#4{%
1385 \@letinstance\DI@item@justification{justification}{indexitem3}%
1386 \DI@item@nojoin
1387 \DI@item@justification
1388 \ifx \NoValue#4%
1389 #3\nobreak\hfil\nopagebreak[2]%
1390 \else
1391 #3\pfill#4%
1392 \fi
1393 \let\DI@item@join\@firstofone
1394 \let\DI@item@nojoin\@empty
1395 \par
1396 }
1397 %</!template>
1398 % \end{macrocode}
1399 % \end{instance}\end{instance}\end{instance}
1400 %
1401 % \begin{instance}{indexitem}{fixed-r1a}
1402 % \begin{instance}{indexitem}{fixed-r2a-nocomma}
1403 % \begin{instance}{indexitem}{fixed-a3r}
1404 % The \texttt{fixed-r1a}, \texttt{fixed-r2a-nocomma}, and
1405 % \texttt{fixed-a3r} instances of type \texttt{indexitem} are again
1406 % based on the \texttt{fixed} template, but here they always accept
1407 % (or offer) to join with one neighbouring item, whereas they always
1408 % reject to join with the other. As before, they differ in their
1409 % values of the \textit{justification-setup} key, and the
1410 % \texttt{-nocomma} is because that instance only inserts a space,
1411 % not a comma and a space, when items are joined.
1412 % \begin{macrocode}
1413 %<*template>
1414 \DeclareInstance{indexitem}{fixed-r1a}{fixed}
1415 {justification-setup = indexitem1, post-join = true}
1416 \DeclareInstance{indexitem}{fixed-r2a-nocomma}{fixed}
1417 {justification-setup = indexitem2,
1418 post-join = true, join-extra = {\space}}
1419 \DeclareInstance{indexitem}{fixed-a3r}{fixed}
1420 {justification-setup = indexitem3, pre-join = true}
1421 %</template>
1422 %<*!template>
1423 \@namedef{TP@I{}{indexitem}{fixed-r1a}}#1#2#3#4{%
1424 \@letinstance\DI@item@justification{justification}{indexitem1}%
1425 \DI@item@nojoin
1426 \DI@item@justification
1427 \ifx \NoValue#4%
1428 #3%
1429 \def\DI@item@join##1{, }%
1430 \def\DI@item@nojoin{\nobreak\hfil\nopagebreak[4]\par}%
1431 \else
1432 #3\pfill#4\par
1433 \let\DI@item@join\@firstofone
1434 \let\DI@item@nojoin\@empty
1435 \fi
1436 \ignorespaces
1437 }
1438 \@namedef{TP@I{}{indexitem}{fixed-r2a-nocomma}}#1#2#3#4{%
1439 \@letinstance\DI@item@justification{justification}{indexitem2}%
1440 \DI@item@nojoin
1441 \DI@item@justification
1442 \ifx \NoValue#4%
1443 #3%
1444 \def\DI@item@join##1{ }%
1445 \def\DI@item@nojoin{\nobreak\hfil\nopagebreak[4]\par}%
1446 \else
1447 #3\pfill#4\par
1448 \let\DI@item@join\@firstofone
1449 \let\DI@item@nojoin\@empty
1450 \fi
1451 \ignorespaces
1452 }
1453 \@namedef{TP@I{}{indexitem}{fixed-a3r}}#1#2#3#4{%
1454 \@letinstance\DI@item@justification{justification}{indexitem3}%
1455 \DI@item@join{\DI@item@justification}%
1456 \ifx \NoValue#4%
1457 #3\hfil\nopagebreak[2]%
1458 \else
1459 #3\pfill#4%
1460 \fi
1461 \let\DI@item@join\@firstofone
1462 \let\DI@item@nojoin\@empty
1463 \par
1464 }
1465 %</!template>
1466 % \end{macrocode}
1467 % \end{instance}\end{instance}\end{instance}
1468 %
1469 %
1470 % \begin{template}{indexitem}{aloneaccept}
1471 % The \texttt{aloneaccept} template of type \texttt{indexitem} formats
1472 % an item as the items in \package{doc}'s \texttt{theindex} environment.
1473 % It accepts to be joined with the preceeding item if and only if
1474 % both that and the following item are at a lower level than the item
1475 % itself is.
1476 %
1477 % The keys for this template are:
1478 % \begin{description}
1479 % \keyvalitem{justification-setup}{i}
1480 % This is a template instance of type \texttt{justification}. It
1481 % sets the justification for the paragraph containing the item,
1482 % unless the item is being joined with the preceeding item.
1483 % \keyvalitem{ownlevel}{C}
1484 % This is the (nominal) level of this item; it will accept a join
1485 % with the preceeding item if and only if the levels of both that
1486 % and the following item are different from this number.
1487 % \changes{v\,1.00}{2001/03/25}{Changed condition for accepting a
1488 % join from ``neighbouring item levels are lower'' to
1489 % ``neighbouring item levels are not equal to''. (LH)}
1490 % The default is 2.
1491 % \keyvalitem{nofig-action}{f1}
1492 % If the \meta{figures} argument is |\NoValue| then the \meta{text}
1493 % argument is passed on to this macro for the actual formatting.
1494 % The default expansion is the \meta{text} followed by a space of
1495 % linefillskip.
1496 % \keyvalitem{fig-action}{f2}
1497 % If the \meta{figures} argument is not |\NoValue| then the
1498 % \meta{text} and \meta{figures} arguments are passed on (in that
1499 % order) to this macro for the actual formatting. The default
1500 % expansion is
1501 % \begin{quote}
1502 % \meta{text}|\pfill|\meta{figures}
1503 % \end{quote}
1504 % \keyvalitem{post-join}{b}
1505 % A switch for whether the item should offer to join with the
1506 % following item. True means ``make offer'', false (which is the
1507 % default) means ``don't make offer''. Making the offer is
1508 % furthermore conditioned by that the \meta{figures} argument is
1509 % |\NoValue|.
1510 % \keyvalitem{nojoin-extra}{f0}
1511 % Extra code which is inserted after the normal code for an item
1512 % if the item neither has any figures nor offers to join with the
1513 % following item. The default value is a space of length
1514 % \textit{linefillskip}.
1515 % \changes{v\,0.03}{2001/02/24}{Added the \textit{nojoin-extra}
1516 % key. (LH)}
1517 % \keyvalitem{join-extra}{f0}
1518 % Extra text which is inserted after the normal text of the item
1519 % if there is a join, by default a comma and a space.
1520 % \keyvalitem{offjoin-extra}{f0}
1521 % Extra code which is inserted after the normal text of the item
1522 % if a join is offered but declined, by default the
1523 % \textit{nojoin-extra} code followed by a |\nopagebreak|.
1524 % \end{description}
1525 %
1526 % Note that the contents of the \textit{nojoin-extra},
1527 % \textit{join-extra}, and \textit{offjoin-extra} keys must be robust
1528 % as they may be subjected to a |\protected@edef|.
1529 % \changes{v\,0.03}{2001/02/24}{\cs{protected@edef}ing the macros
1530 % \cs{DI@item@join} and \cs{DI@item@nojoin}. (LH)}
1531 %
1532 % \begin{macrocode}
1533 %<*template>
1534 \DeclareTemplate{indexitem}{aloneaccept}{4}{
1535 justification-setup =i{justification} \DI@item@justification,
1536 ownlevel =C
1537 %<default> {2}
1538 \DI@this@level,
1539 nofig-action =f1
1540 %<default> {#1}
1541 \DI@nofig,
1542 fig-action =f2
1543 %<default> {#1\pfill#2}
1544 \DI@hasfig,
1545 post-join =b
1546 %<default> {false}
1547 DI@postjoin@,
1548 nojoin-extra =f0
1549 %<default> {\hspace*{\justification@g}}
1550 \DI@nojoin@extra,
1551 join-extra =f0
1552 %<default> {,\space}
1553 \DI@join@extra,
1554 offjoin-extra =f0
1555 %<default> {\DI@nojoin@extra\protect\nopagebreak[4]}
1556 \DI@offjoin@extra
1557 }{%
1558 %<*!default>
1559 \def\DI@this@level{2}%
1560 \let\DI@nofig\@firstofone
1561 \def\DI@hasfig##1##2{##1\pfill##2}%
1562 \let\ifDI@postjoin@\iffalse
1563 \def\DI@nojoin@extra{\hspace*{\justification@g}}%
1564 \def\DI@join@extra{,\space}%
1565 \def\DI@offjoin@extra{\DI@nojoin@extra\protect\nopagebreak[4]}%
1566 %</!default>
1567 \DoParameterAssignments
1568 \ifnum \DI@this@level=#1
1569 \DI@item@nojoin \DI@item@justification
1570 \else\ifnum \DI@this@level=#2
1571 \DI@item@nojoin \DI@item@justification
1572 \else
1573 \DI@item@join{\DI@item@justification}%
1574 \fi\fi
1575 \let\DI@item@join\@firstofone
1576 \let\DI@item@nojoin\@empty
1577 \IfNoValueTF{#4}{%
1578 \DI@nofig{#3}%
1579 \ifDI@postjoin@
1580 \protected@edef\DI@item@join##1{\DI@join@extra}%
1581 \protected@edef\DI@item@nojoin{\DI@offjoin@extra\protect\par}%
1582 \else
1583 \DI@nojoin@extra \par
1584 \fi
1585 }{%
1586 \DI@hasfig{#3}{#4}%
1587 \par
1588 }%
1589 \ignorespaces
1590 }
1591 %</template>
1592 % \end{macrocode}
1593 % \end{template}
1594 %
1595 % \begin{instance}{indexitem}{aloneaccept2}
1596 % \begin{instance}{indexitem}{aloneaceept3}
1597 % The \texttt{aloneaccept2} and \texttt{aloneaccept3} instances of type
1598 % \texttt{indexitem} are simply the \texttt{aloneaccept} template
1599 % with the levels fixed to two and three, respectively.
1600 % \begin{macrocode}
1601 %<*template>
1602 \DeclareInstance{indexitem}{aloneaccept2}{aloneaccept}
1603 {justification-setup = indexitem2, ownlevel = 2}
1604 \DeclareInstance{indexitem}{aloneaccept3}{aloneaccept}
1605 {justification-setup = indexitem3, ownlevel = 3}
1606 %</template>
1607 %<*!template>
1608 \@namedef{TP@I{}{indexitem}{aloneaccept2}}#1#2#3#4{%
1609 \@letinstance\DI@item@justification{justification}{indexitem2}%
1610 \ifnum #1=\tw@
1611 \DI@item@nojoin \DI@item@justification
1612 \else\ifnum #2=\tw@
1613 \DI@item@nojoin \DI@item@justification
1614 \else
1615 \DI@item@join{\DI@item@justification}%
1616 \fi\fi
1617 \ifx \NoValue#4%
1618 #3\nobreak\hfil\vadjust{}%
1619 \else
1620 #3\pfill #4%
1621 \fi
1622 \let\DI@item@join\@firstofone
1623 \let\DI@item@nojoin\@empty
1624 \par
1625 }
1626 \@namedef{TP@I{}{indexitem}{aloneaccept3}}#1#2#3#4{%
1627 \@letinstance\DI@item@justification{justification}{indexitem3}%
1628 \ifnum #1=\thr@@
1629 \DI@item@nojoin \DI@item@justification
1630 \else\ifnum #2=\thr@@
1631 \DI@item@nojoin \DI@item@justification
1632 \else
1633 \DI@item@join{\DI@item@justification}%
1634 \fi\fi
1635 \ifx \NoValue#4%
1636 #3\nobreak\hfil\vadjust{}%
1637 \else
1638 #3\pfill #4%
1639 \fi
1640 \let\DI@item@join\@firstofone
1641 \let\DI@item@nojoin\@empty
1642 \par
1643 }
1644 %</!template>
1645 % \end{macrocode}
1646 % \end{instance}\end{instance}
1647 %
1648 %
1649 % \subsubsection{The \texttt{docindex} template type}
1650 %
1651 % \begin{templatetype}{docindex}
1652 % A template of type \texttt{docindex} takes care of typesetting an
1653 % index found in a file (which is |\input|ted as part of this
1654 % process), hence using an instance of type \texttt{docindex} is
1655 % the same kind of action that the |\printindex| and |\printglossary|
1656 % commands make.
1657 %
1658 % The template decides from which file the index should be read. It
1659 % takes two arguments: the index prologue and the index epilogue.
1660 % These are two pieces of text (which may just as well include a
1661 % sectioning command) that are printed just before and after the
1662 % index. Either argument may be empty. Immediately after the file
1663 % containing the body of the index has been inputted, the template
1664 % must execute |\DI@item@nojoin| to make sure that the last item is
1665 % properly typeset.
1666 %
1667 % Templates of type \texttt{docindex} must begin by opening a group
1668 % and end by closing it. They must furthermore locally define the
1669 % following macros before any part of the index is typeset.
1670 % \begin{description}
1671 % \item[\cs{DI@indexitem@i}, \cs{DI@indexitem@ii}, and
1672 % \cs{DI@indexitem@iii}]
1673 % Handlers for index items at level 1, 2, and 3 respectively.
1674 % These handlers must conform to the specification for
1675 % \texttt{indexitem} instances.
1676 % \item[\cs{DI@letter@skip}, \cs{DI@letter@format}]
1677 % These are described in the comments to the |\indexnewletter|
1678 % command.
1679 % \item[\cs{+}]
1680 % The command for typesetting the separator between two parts of
1681 % a composite (page) number. This is a parameterless macro.
1682 % \end{description}
1683 %
1684 % \begin{macrocode}
1685 %<template>\DeclareTemplateType{docindex}{2}
1686 %<!template>\@namedef{TP@T{docindex}}{{}{2}}
1687 % \end{macrocode}
1688 % \end{templatetype}
1689 %
1690 % \begin{template}{docindex}{std}
1691 % The \texttt{std} template of type \texttt{docindex} typesets an
1692 % index while providing all the formatting parameters of the
1693 % \package{doc} index and list of changes (and a few more).
1694 % \changes{v\,1.00}{2001/04/08}{The \mbox{\textit{-font}} keyvals
1695 % renamed to \mbox{\textit{-setup}}, but the type stayed the
1696 % same (f0). (LH)}
1697 %
1698 % \label{docindex:std}
1699 % The keys of the template are:
1700 % \begin{description}
1701 % \keyvalitem{file-name}{n}
1702 % The base name of the file in which the index is stored, by
1703 % default the |\jobname|.\changes{v\,1.00}{2001/03/25}{Added
1704 % \textit{file-name} and \textit{file-extension} keys, removed
1705 % the \textit{default-prologue} and \textit{default-epilogue}
1706 % keys. (LH)}
1707 % \keyvalitem{file-extension}{n}
1708 % The extension of the file in which the index is stored, by
1709 % default \texttt{ind}.
1710 % \keyvalitem{item1}{i}
1711 % \texttt{indexitem} instance for level 1 items, by default
1712 % \texttt{fixed1}.
1713 % \keyvalitem{item2}{i}
1714 % \texttt{indexitem} instance for level 2 items, by default
1715 % \texttt{fixed2}.
1716 % \keyvalitem{item3}{i}
1717 % \texttt{indexitem} instance for level 3 items, by default
1718 % \texttt{fixed3}.
1719 % \keyvalitem{columns}{C}
1720 % The number of columns in the index, by default 3.
1721 % \keyvalitem{reserved-height}{L}
1722 % The minimal amount of vertical space that must be left on the
1723 % current page if the index is to start on it, by default
1724 % 80\,pt.^^A
1725 % \changes{v\,1.00}{2001/03/25}{Made \textit{reserved-height} work
1726 % even when \textit{columns} is 1 by using the
1727 % \package{multicol} macro \cs{enough@room}. (LH)}
1728 % \keyvalitem{column-sep}{l}
1729 % The horizontal separation between columns in the index, by
1730 % default 10\,pt. (This may seem strange in comparison with
1731 % \package{doc}, since |\IndexParms| contains the command
1732 % |\columnsep=15pt|, but \package{doc} doesn't execute
1733 % |\IndexParms| until \LaTeX\ is already in multi-column mode, and
1734 % then it is too late for the changed value to have any effect.)
1735 % \keyvalitem{prologue-setup}{f0}
1736 % Various commands setting layout parameters (e.g.\ the font) for
1737 % the prologue; by default empty.
1738 % \keyvalitem{body-setup}{f0}
1739 % Various commands setting layout parameters (e.g.\ the font) for
1740 % the body of the index; by default |\small|.
1741 % \keyvalitem{epilogue-setup}{f0}
1742 % Various commands setting layout parameters (e.g.\ the font) for
1743 % the epilogue; by default |\normalsize| (to counter the |\small|
1744 % in the \textit{body-setup}).
1745 % \keyvalitem{letter-skip}{L}
1746 % The skip inserted before a new letter group, by default 10\,pt
1747 % plus 2\,pt minus 3\,pt.
1748 % \keyvalitem{letter-format}{f1}
1749 % The macro which formats new letter groups; the argument is the
1750 % heading for the group, as generated by \program{makeindex}. By
1751 % defaults it typesets the argument in boldface, centered on a
1752 % line.
1753 % \keyvalitem{pagestyle}{n}
1754 % If this is nonempty then the pagestyle by that name will be
1755 % selected for the index. By default it is empty.
1756 % \keyvalitem{parskip}{l}
1757 % The value of |\parskip| to use inside the index, by default
1758 % 0\,pt plus 1\,pt. This key value is likely to change as the
1759 % \LaTeXplus\ interfaces for galleys evolve.
1760 % \changes{v\,0.03}{2001/02/27}{Added \textit{parskip} keyval. (LH)}
1761 % \keyvalitem{page-compositor}{f0}
1762 % The text that is typeset to separate two parts of a composite
1763 % (page) number, by default a hyphen.
1764 % \changes{v\,1.00}{2001/04/05}{Added \textit{page-compositor}
1765 % keyval. (LH)}
1766 % \end{description}
1767 %
1768 % \begin{macrocode}
1769 %<*template>
1770 \DeclareTemplate{docindex}{std}{2}{
1771 file-name =n
1772 %<default> {\jobname}
1773 \DI@file@name,
1774 file-extension =n
1775 %<default> {ind}
1776 \DI@file@ext,
1777 item1 =i{indexitem}
1778 %<default> {fixed1}
1779 \DI@indexitem@i,
1780 item2 =i{indexitem}
1781 %<default> {fixed2}
1782 \DI@indexitem@ii,
1783 item3 =i{indexitem}
1784 %<default> {fixed3}
1785 \DI@indexitem@iii,
1786 reserved-height =L
1787 %<default> {80pt}
1788 \DI@reserved@height,
1789 columns =C
1790 %<default> {3}
1791 \DI@columns,
1792 column-sep =l
1793 %<default> {10pt}
1794 \columnsep,
1795 prologue-setup =f0
1796 %<default> {}
1797 \DI@prologue@setup,
1798 body-setup =f0
1799 %<default> {\small}
1800 \DI@body@setup,
1801 epilogue-setup =f0
1802 %<default> {\normalsize}
1803 \DI@epilogue@setup,
1804 letter-skip =L
1805 %<default> {10pt plus 2pt minus 3pt}
1806 \DI@letter@skip,
1807 letter-format =f1
1808 %<default> {\UseInstance{justification}{center}%
1809 %<default> \textbf{#1}\nopagebreak\csname par\endcsname}
1810 \DI@letter@format,
1811 pagestyle =n
1812 %<default> {}
1813 \DI@pagestyle,
1814 parskip =l
1815 %<default> {0pt plus 1pt}
1816 \parskip,
1817 page-compositor =f0
1818 %<default> {-}
1819 \+
1820 }{%
1821 \begingroup
1822 %<*!default>
1823 \def\DI@file@name{\jobname}%
1824 \def\DI@file@ext{ind}%
1825 \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
1826 \@letinstance\DI@indexitem@ii{indexitem}{fixed2}%
1827 \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
1828 \def\DI@reserved@height{80pt}%
1829 \def\DI@columns{3}%
1830 \columnsep=10pt%
1831 \let\DI@prologue@setup\@empty
1832 \def\DI@body@setup{\small}%
1833 \def\DI@epilogue@setup{\normalsize}%
1834 \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
1835 \def\DI@letter@format##1{%
1836 \UseInstance{justification}{center}%
1837 \textbf{##1}\nopagebreak\par
1838 }%
1839 \parskip=\z@\@plus\p@
1840 \let\DI@pagestyle\@empty
1841 \def\+{-}%
1842 %</!default>
1843 \DoParameterAssignments
1844 \IfFileExists{\DI@file@name.\DI@file@ext}{%
1845 \ifnum \DI@columns>\@ne
1846 \begin{multicols}{\DI@columns}%
1847 [\DI@prologue@setup #1][\DI@reserved@height]%
1848 \else
1849 \enough@room{\DI@reserved@height}%
1850 \DI@prologue@setup #1\par
1851 \addvspace\multicolsep
1852 \fi
1853 \ifx \DI@pagestyle\@empty \else \pagestyle{\DI@pagestyle}\fi
1854 \DI@body@setup
1855 \DI@ind@setup
1856 \input{\DI@file@name.\DI@file@ext}%
1857 \DI@item@nojoin
1858 \ifx \DI@pagestyle\@empty \else
1859 \expandafter\thispagestyle \expandafter{\DI@pagestyle}%
1860 \fi
1861 \ifnum \DI@columns>\@ne
1862 \end{multicols}%
1863 \else
1864 \enough@room\postmulticols
1865 \addvspace\multicolsep
1866 \fi
1867 \DI@epilogue@setup #2\par
1868 }{\typeout{No file \DI@file@name.\DI@file@ext.}}%
1869 \endgroup
1870 }
1871 % \end{macrocode}
1872 % \end{template}
1873 %
1874 %
1875 % \begin{instance}{docindex}{index}
1876 % \begin{option}{usedocindexps}
1877 % The \texttt{index} instance of the \texttt{docindex} template type
1878 % prints the normal index (as opposed to the list of changes). There
1879 % are two different definitions of the instance: one which sets the
1880 % pagestyle in the index, and one which does not; which one is used
1881 % depends on whether the \texttt{usedocindexps} option has been
1882 % passed to the package or not.
1883 % \begin{macrocode}
1884 \@ifpackagewith{docindex}{usedocindexps}{%
1885 \DeclareInstance{docindex}{index}{std}{pagestyle=docindex}%
1886 }{%
1887 \DeclareInstance{docindex}{index}{std}{}%
1888 }
1889 %</template>
1890 % \end{macrocode}
1891 %
1892 % The implementations of the \texttt{index} instance in
1893 % \package{docidx2e} are slightly off in that they use \package{doc}
1894 % parameters for various settings in the extent such parameters exist.
1895 % \changes{v\,0.03}{2001/02/24}{Added \cs{@nobreakfalse} in
1896 % \package{docidx2e} implementation; the first item in the index
1897 % does not directly follow a \cs{section}-type heading. (LH)}
1898 % \label{p:index-instance}
1899 % \begin{macrocode}
1900 %<*!template>
1901 \@ifpackagewith{docidx2e}{usedocindexps}{%
1902 \@namedef{TP@I{}{docindex}{index}}#1#2{%
1903 \begingroup
1904 \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
1905 \@letinstance\DI@indexitem@ii{indexitem}{fixed2}%
1906 \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
1907 \columnsep=10pt%
1908 \parskip=0pt plus 1pt%
1909 \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
1910 \def\DI@letter@format##1{%
1911 \par
1912 \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
1913 \nopagebreak
1914 }%
1915 \def\+{-}%
1916 \IfFileExists{\jobname.ind}{%
1917 \ifnum \c@IndexColumns>\@ne
1918 \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
1919 \else
1920 \enough@room{\IndexMin}%
1921 #1\par
1922 \addvspace\multicolsep
1923 \fi
1924 \pagestyle{docindex}%
1925 \small
1926 \@nobreakfalse
1927 \DI@ind@setup
1928 \input{\jobname.ind}%
1929 \DI@item@nojoin
1930 \thispagestyle{docindex}
1931 \ifnum \c@IndexColumns>\@ne
1932 \end{multicols}%
1933 \else
1934 \enough@room\postmulticols
1935 \addvspace\multicolsep
1936 \fi
1937 \normalsize #2\par
1938 }{\typeout{No file \jobname.ind.}}%
1939 \endgroup
1940 }
1941 }{%
1942 \@namedef{TP@I{}{docindex}{index}}#1#2{%
1943 \begingroup
1944 \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
1945 \@letinstance\DI@indexitem@ii{indexitem}{fixed2}%
1946 \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
1947 \columnsep=10pt%
1948 \parskip=0pt plus 1pt%
1949 \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
1950 \def\DI@letter@format##1{%
1951 \par
1952 \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
1953 \nopagebreak
1954 }%
1955 \def\+{-}%
1956 \IfFileExists{\jobname.ind}{%
1957 \ifnum \c@IndexColumns>\@ne
1958 \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
1959 \else
1960 \enough@room{\IndexMin}%
1961 #1\par
1962 \addvspace\multicolsep
1963 \fi
1964 \small
1965 \@nobreakfalse
1966 \DI@ind@setup
1967 \input{\jobname.ind}%
1968 \DI@item@nojoin
1969 \ifnum \c@IndexColumns>\@ne
1970 \end{multicols}%
1971 \else
1972 \enough@room\postmulticols
1973 \addvspace\multicolsep
1974 \fi
1975 \normalsize #2\par
1976 }{\typeout{No file \jobname.ind.}}%
1977 \endgroup
1978 }
1979 }
1980 %</!template>
1981 % \end{macrocode}
1982 % \end{option}\end{instance}
1983 %
1984 %
1985 % \begin{instance}{docindex}{changes}
1986 % The \texttt{changes} instance of the \texttt{docindex} template
1987 % type typesets a \package{doc} list of changes.
1988 % \changes{v\,0.03}{2001/02/24}{Added \cs{@nobreakfalse} in
1989 % \package{docidx2e} implementation; the first item in the index
1990 % does not directly follow a \cs{section}-type heading. (LH)}
1991 % \changes{v\,1.00}{2001/04/07}{Added \cs{makeatletter} in
1992 % \package{docidx2e} implementation; it doesn't hurt and it is
1993 % sometimes necessary (when commands that expand to private
1994 % control sequences are used in the argument of \cs{changes}).
1995 % (LH)}
1996 % \begin{macrocode}
1997 %<*template>
1998 \DeclareInstance{docindex}{changes}{std}{
1999 file-extension = gls,
2000 item2 = fixed-r2a-nocomma,
2001 item3 = fixed-a3r,
2002 columns = 2,
2003 letter-format = {},
2004 letter-skip = \z@skip
2005 }
2006 %</template>
2007 % \end{macrocode}
2008 % \label{p:changes-instance}
2009 % \begin{macrocode}
2010 %<*!template>
2011 \@namedef{TP@I{}{docindex}{changes}}#1#2{%
2012 \begingroup
2013 \@letinstance\DI@indexitem@i{indexitem}{fixed1}%
2014 \@letinstance\DI@indexitem@ii{indexitem}{fixed-r2a-nocomma}%
2015 \@letinstance\DI@indexitem@iii{indexitem}{fixed-a3r}%
2016 \columnsep=10pt%
2017 \parskip=0pt plus 1pt%
2018 \def\DI@letter@skip{\z@skip}%
2019 \let\DI@letter@format\@gobble
2020 \def\+{-}%
2021 \IfFileExists{\jobname.gls}{%
2022 \ifnum \c@GlossaryColumns>\@ne
2023 \begin{multicols}{\c@GlossaryColumns}[#1][\GlossaryMin]%
2024 \else
2025 \enough@room{\GlossaryMin}%
2026 #1\par
2027 \addvspace\multicolsep
2028 \fi
2029 \small
2030 \makeatletter
2031 \@nobreakfalse
2032 \DI@ind@setup
2033 \input{\jobname.gls}%
2034 \DI@item@nojoin
2035 \ifnum \c@GlossaryColumns>\@ne
2036 \end{multicols}%
2037 \else
2038 \enough@room\postmulticols
2039 \addvspace\multicolsep
2040 \fi
2041 \normalsize #2\par
2042 }{\typeout{No file \jobname.gls.}}
2043 \endgroup
2044 }
2045 %</!template>
2046 % \end{macrocode}
2047 % \end{instance}
2048 %
2049 % \begin{macro}{\PrintIndex}
2050 % \begin{macro}{\PrintChanges}
2051 % The |\PrintIndex| and |\PrintChanges| commands are redefined to use
2052 % the respective instances of template type \texttt{docindex}.
2053 % \begin{macrocode}
2054 \renewcommand\PrintIndex{%
2055 \UseInstance{docindex}{index}{\index@prologue}{}%
2056 \global\let\PrintIndex\@empty
2057 }
2058 \renewcommand\PrintChanges{%
2059 \UseInstance{docindex}{changes}{\glossary@prologue}{}%
2060 \global\let\PrintChanges\@empty
2061 }
2062 %</pkg>
2063 % \end{macrocode}
2064 % \end{macro}\end{macro}
2065 %
2066 %
2067 % \section{Notes and acknowledgements}
2068 %
2069 % The exact descriptions of the parameters of the \program{makeindex}
2070 % program is the paper \cite{makeindex-paper} by Chen and Harrison, but
2071 % I have seen claims that there are parameters not listed there
2072 % (presumably becuase they were added after this paper was written).
2073 % \texttt{docindex.ist} does not change any such undocumented
2074 % parameter, however.
2075 %
2076 % There are other index sorting programs than \package{makeindex}
2077 % around, such as for example \program{x\r{\i}ndy}~\cite{xindy}.
2078 % Should someone create index style files for such systems that are
2079 % equivalent (or superior, for that matter) to \texttt{docindex.ist}
2080 % then I would be happy to add them to the \package{docindex}
2081 % distribution.
2082 %
2083 % Most of the actual layout parameter settings used by the
2084 % \package{docindex} package are not of my design, but copied from
2085 % various other \LaTeX\ packages such as~\cite{multicol,doc} (mainly by
2086 % Frank Mittelbach). I have however tried to sort out which parameters
2087 % are actually in force under the various conditions---something which
2088 % turned out to be less obvious than I originally suspected.
2089 %
2090 % The idea to have the \texttt{docindex} type templates input the sorted
2091 % index file (rather than simply setting up the formatting of it as was
2092 % the case in v\,0.03) was taken from the \package{xindex}
2093 % package~\cite{xindex} by Achim Blumensath.
2094 %
2095 % \hbadness=10000
2096 %
2097 % \Finale
2098 %
2099 %
2100 \endinput