| 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 |