Debian Codegraph @

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

raw
1 % \CheckSum{2952}
2 %
3 % \iffalse meta-comment
4 %
5 % This file may be distributed and/or modified under the conditions
6 % of the LaTeX Project Public License, either version 1.2 of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in
9 % http://www.latex-project.org/lppl.txt
10 % and version 1.2 or later is part of all distributions of LaTeX
11 % version 1999/12/01 or later.
12 %
13 % Copyright 2000 2001 2002 Lars Hellstr\"om
14 %
15 %<*driver>
16 \documentclass{ltxdoc}
17 \usepackage{array,longtable}
18
19 \makeatletter
20 \IfFileExists{xdoc2.sty}{%
21 \usepackage[dolayout]{xdoc2}
22 \NewMacroEnvironment{xrefcmd}{\XD@grab@harmless\relax}{1}%
23 {\MacroFont##1 \normalfont XXR-command}%
24 {\XDMainIndex{%
25 \levelsorted{##1 (XXR-command)}{\texttt{##1} (XXR-command)}%
26 }%
27 \XDMainIndex{%
28 \levelsame{XXR-commands:}\levelsorted{##1}{\texttt{##1}}%
29 }}%
30 {{##1}{XXR-command \texttt{##1}}}%
31 {}%
32 \@namedef{XD@harmless\string\Bslash}{%
33 \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
34 \csname XD@harmless@92\endcsname}%
35 \XD@harmless@
36 }%
37 \IfFileExists{docidx2e.sty}{%
38 \usepackage{docidx2e}%
39 \AtEndDocument{%
40 \typeout{*********************************}%
41 \typeout{* Use docindex.ist when sorting *}%
42 \typeout{* xdoc2.idx and xdoc2.glo. \@spaces\space*}%
43 \typeout{*********************************}%
44 }%
45 }%
46 }{%
47 \newenvironment{option}[1]{\trivlist\item[]}{\endtrivlist}%
48 \newenvironment{xrefcmd}[1]{\trivlist\item[]}{\endtrivlist}%
49 \@ifpackagelater{doc}{2000/05/20}{}{%
50 \let\XD@fragile@meta=\meta
51 \def\meta{%
52 \ifx \protect\@typeset@protect
53 \expandafter\futurelet \expandafter\@let@token
54 \expandafter\XD@fragile@meta
55 \else
56 \noexpand\meta
57 \fi
58 }%
59 }%
60 }
61 \makeatother
62
63 \providecommand\describecsfamily[1]{%
64 \leavevmode
65 \GenericDescribePrint{\MacroFont\Bslash#1}%
66 \ignorespaces
67 }
68 \providecommand\describeoption[1]{%
69 \leavevmode
70 \GenericDescribePrint{\MacroFont#1 \normalfont option}%
71 \ignorespaces
72 }
73 \providecommand\GenericDescribePrint[1]{%
74 \marginpar{\raggedleft\strut #1}%
75 }
76 \providecommand\Bslash{\bslash}
77 \providecommand\DoNotIndexBy[1]{}
78 \DoNotIndexBy{@}
79 \DoNotIndexBy{@@}
80 \DoNotIndexBy{XD@}
81
82 \DeclareRobustCommand\package[1]{\textsf{#1}}
83 \DeclareRobustCommand\LaTeXplus{\LaTeXe$*$}
84 \newcommand\B{\penalty\exhyphenpenalty}
85 \ProvideTextCommandDefault\textminus{\textendash}
86
87 \hfuzz=15pt
88
89 \AlsoImplementation
90 \setcounter{IndexColumns}{2}
91
92 \CodelineIndex
93 \EnableCrossrefs
94 \RecordChanges
95
96 \begin{document}
97
98 \DocInput{xdoc2.dtx}
99
100 \PrintChanges
101 \PrintIndex
102
103 \end{document}
104 %</driver>
105 % \fi
106 %
107 % \title{The \package{xdoc} package --- experimental reimplementations
108 % of features from \package{doc}, second~prototype}
109 % \author{Lars Hellstr\"om^^A
110 % \thanks{E-mail: \texttt{[email protected]}}}
111 % \date{2003/07/07}
112 % \maketitle
113 %
114 % \DoNotIndex{\,,\-,\/,\ ,\#,\%,\&,\\,\^,\|}
115 % \DoNotIndex{\@addtoreset,\@auxout,\@bsphack,\@cclv,\@ctrerr}
116 % \DoNotIndex{\@eha,\@empty,\@esphack,\@evenfoot}
117 % \DoNotIndex{\@firstofone,\@firstoftwo,\@for}
118 % \DoNotIndex{\@gobble,\@gobblefour,\@gobbletwo}
119 % \DoNotIndex{\@ifclassloaded,\@ifdefinable,\@ifpackagewith,\@ifundefined}
120 % \DoNotIndex{\@input,\@latexerr,\@mainaux,\@mparswitchtrue}
121 % \DoNotIndex{\@namedef,\@nameuse,\@ne,\@next,\@nil,\@oddfoot,\@partaux}
122 % \DoNotIndex{\@partlist,\@secondoftwo,\@sptoken}
123 % \DoNotIndex{\@tempswafalse,\@tempswatrue,\@totalleftmargin}
124 % \DoNotIndex{\@typeset@protect,\@unexpandable@protect}
125 % \DoNotIndex{\@vobeyspaces,\@writeckpt,\@xxxii}
126 % \DoNotIndex{\active,\addto@hook,\addtolength,\advance,\AtBeginDocument}
127 % \DoNotIndex{\baselineskip,\begingroup,\bgroup,\box,\boxmaxdepth}
128 % \DoNotIndex{\catcode,\char,\clearpage,\closeout,\color@begingroup}
129 % \DoNotIndex{\color@endgroup,\copy,\csname}
130 % \DoNotIndex{\deadcycles,\DeclareOption,\DeclareRobustCommand,\def}
131 % \DoNotIndex{\discretionary,\divide,\do@space,\dp}
132 % \DoNotIndex{\edef,\egroup,\else,\em,\endcsname,\endgroup,\ensuremath}
133 % \DoNotIndex{\escapechar,\everypar,\expandafter}
134 % \DoNotIndex{\fi,\font,\footnotesize,\frenchspacing,\futurelet}
135 % \DoNotIndex{\g@addto@macro,\gdef,\global}
136 % \DoNotIndex{\hb@xt@,\hbox,\hfill,\hss,\ht,\hyphenchar}
137 % \DoNotIndex{\if,\if@filesw,\if@inlabel,\if@mparswitch,\if@partsw}
138 % \DoNotIndex{\if@reversemargin,\if@tempswa,\ifcase,\ifcat,\iffalse}
139 % \DoNotIndex{\ifmmode,\ifnum,\ifodd,\iftrue,\ifx,\ignorespaces}
140 % \DoNotIndex{\immediate,\include,\indexentry,\input,\inputlineno,\item}
141 % \DoNotIndex{\itshape,\kern}
142 % \DoNotIndex{\labelsep,\langle,\language,\leavevmode,\let,\long,\loop}
143 % \DoNotIndex{\m@ne,\m@ta,\makelabel,\marginpar,\marginparsep,\maxdimen}
144 % \DoNotIndex{\MessageBreak,\multiply}
145 % \DoNotIndex{\NeedsTeXFormat,\newcommand,\newdimen,\newlanguage}
146 % \DoNotIndex{\nfss@text,\noexpand,\normalfont,\normalmarginpar,\number}
147 % \DoNotIndex{\obeyspaces,\openout,\or}
148 % \DoNotIndex{\PackageError,\PackageInfo,\PackageWarning}
149 % \DoNotIndex{\PackageWarningNoLine,\pagestyle,\paperwidth,\parbox,\part}
150 % \DoNotIndex{\ProcessOptions,\protect,\protected@edef,\protected@write}
151 % \DoNotIndex{\protected@xdef,\ProvidesPackage}
152 % \DoNotIndex{\raggedleft,\raggedright,\rangle,\relax,\renewcommand}
153 % \DoNotIndex{\repeat,\RequirePackage}
154 % \DoNotIndex{\setbox,\setlength,\sixt@@n,\space,\string,\strut,\strutbox}
155 % \DoNotIndex{\textasciicircum,\textasciitilde,\textbackslash,\textbar}
156 % \DoNotIndex{\textbf,\textbraceleft,\textbraceright,\textdollar}
157 % \DoNotIndex{\textgreater,\textless,\textquotedbl,\textquoteleft}
158 % \DoNotIndex{\textquoteright,\texttt,\textunderscore,\textvisiblespace}
159 % \DoNotIndex{\textwidth,\the,\topsep,\trivlist,\tw@}
160 % \DoNotIndex{\uccode,\unhbox,\unrestored@protected@xdef,\unvbox}
161 % \DoNotIndex{\uppercase}
162 % \DoNotIndex{\vbox,\vss,\vtop,\write,\xdef,\z@}
163 %
164 % \changes{prot1}{2000/06/15}{Started writing first prototype. (LH)}
165 % \changes{prot2}{2000/07/13}{Began work on the second prototype. (LH)}
166 %
167 % \begin{abstract}
168 % The \package{xdoc} package contains reimplementations of some of
169 % the features found in the standard \LaTeX\ \package{doc}
170 % package~\cite{doc} by Mittelbach \emph{et~al. }The ultimate goals
171 % for these reimplementations are that the commands should be better,
172 % easily configurable, and be easy to extend, but this is only a
173 % second prototype implementation and nothing in it is guaranteed to
174 % be the same in the third prototype.\footnote{But there are no
175 % guarantees there will ever be a third prototype either.}
176 % \end{abstract}
177 %
178 % \tableofcontents
179 %
180 %
181 % \section{Usage}
182 %
183 % When I began working on this package I thought that there would be no
184 % need for a usage section (at least on the prototype stage)---either you
185 % are interested in using the new features and then you might just as
186 % well read the descriptions of the commands in the implementation part
187 % of this document (they are written as specifications of what the
188 % commands do), or else you can simply insert a |\usepackage|\B|{xdoc2}|
189 % in the preamble and see how things work a little better than when you
190 % simply use \package{doc}---but with some features it became natural
191 % to introduce incompatible changes and some new features ought to be
192 % mentioned. Hence I wrote a short section on usage after all.
193 %
194 % It is my intention that this document will eventually evolve into the
195 % source for a package \package{xdoc}\footnote{The name \package{doc2}
196 % has also been discussed; we'll see when we get there.} which will
197 % either build on the \package{doc} package and provide better
198 % implementations of many of its features, or replace it completely,
199 % but this document is still only the source for a prototype for that
200 % package. As I believe that the need for some improvement in this area
201 % is rather large however, I have decided to release this prototype so
202 % that other people can use it in their documents or create packages that
203 % are based on it. In doing so, one must of course bear in mind that this
204 % prototype needs not be compatible with the final \package{xdoc}
205 % package, and to overcome most incompatibility problems I therefore
206 % release it under the variant name \package{xdoc2}. This way, documents
207 % based on this prototype can still be typeset using the package they
208 % were written for long after the next \package{xdoc} prototype (or final
209 % version) is released.
210 %
211 % Thus although this document frequently speaks of \package{xdoc}, you
212 % might just as well read it as \package{xdoc2}.
213 %
214 %
215 % \subsection{Changes to old features}
216 %
217 % Whereas \package{doc} more or less assumes that all pages have the
218 % same layout, \package{xdoc} takes measures to ensure that the
219 % \package{doc} features support two-sided document designs. If the
220 % left margin has been widened to better accommodate long macro names
221 % however (like for example the \package{ltxdoc} document class does),
222 % then you may find that the outer margin on right (odd) pages is too
223 % narrow for printing macro names in. The remedy for this is the
224 % \GenericDescribePrint{\MacroFont dolayout \normalfont option}^^A
225 % \SortIndex{dolayout}{\texttt{dolayout} option\encapchar
226 % usage}\texttt{dolayout} option; in two-sided mode it causes
227 % \package{xdoc} to recompute the |\oddsidemargin| so that the outer
228 % margin has the same size on right pages as it previously did on left
229 % pages. In documents which are not processed in two-sided mode the
230 % \texttt{dolayout} option has no effect.
231 %
232 % |\DocInput| has been changed to not make percent a comment character
233 % upon return unless it was before the |\DocInput|. This makes |\DocInput|
234 % nestable and I recommend that \texttt{.dtx} files which input other
235 % \texttt{.dtx} files use |\DocInput| for this.
236 %
237 % The |\DocInclude| command, which is defined by the \package{ltxdoc}
238 % document class rather than \package{doc}, is also by default
239 % redefined in an incompatible manner by \package{xdoc}, but you can
240 % stop \package{xdoc} from making incompatible changes if you pass it the
241 % option \GenericDescribePrint{\MacroFont olddocinclude \normalfont
242 % option}\SortIndex{olddocinclude}{\texttt{olddocinclude} option^^A
243 % \encapchar usage}\texttt{olddocinclude}. The main incompatibility
244 % lies in that the default redefinition of |\DocInclude| behaves purely
245 % as an |\include| command which |\DocInput|s a \texttt{.dtx} file rather
246 % than merely |\input|ting a \texttt{.tex} file---you must pass the
247 % \GenericDescribePrint{\MacroFont fileispart \normalfont option}^^A
248 % \SortIndex{fileispart}{\texttt{fileispart} option\encapchar
249 % usage}\texttt{fileispart} option to \package{xdoc} to get the |\part|
250 % headings etc.\ for each new file---but there are also minor changes
251 % in the appearance of these headings, in how page styles are set, and
252 % in how the information presented in the page footer is obtained.
253 %
254 % Other changes are as far as I can tell minor and within the bounds of
255 % expected behaviour, but code that relies on the implementation of some
256 % feature in \package{doc} may of course behave differently or break
257 % completely. Note in particular that the formats of the internal
258 % \package{doc} variables |\saved@macroname|, |\macro@namepart|, and
259 % |\index@excludelist| have changed completely (see
260 % Section~\ref{Sec:Changes}, Subsection~\ref{Ssec:Scanning macrocode},
261 % and Subsection~\ref{Ssec:Index-exclude} respectively)---hence any hack
262 % involving one of these must be revised before it is used with
263 % \package{xdoc}. These are however exceptions; in my experience the most
264 % noticeable changes not listed above are that the index exclude
265 % mechanism actually works for control sequences whose names consist of
266 % a single non-letter and that symbols get sorted in a different order.
267 %
268 %
269 % \subsection{Some notable new features}
270 %
271 % The main new feature is the \DescribeMacro\NewMacroEnvironment
272 % |\NewMacroEnvironment| command, which defines a new \texttt{macro}-like
273 % environment. The command offers complete control of the argument
274 % structure, the formatting of the marginal heading, the code for making
275 % index entries, and the change entry sorting and formatting, but the
276 % syntax is too complex to explain here. Those who are interested in
277 % using it should read Section~\ref{Sec:Macro-environments}. In
278 % particular, Subsections~\ref{Ssec:Macro&environment}--^^A
279 % \ref{Ssec:More macros} contain several examples of how it can be
280 % used. In addition to using |\New|\-|Macro|\-|Environment| for
281 % redefining the \DescribeEnv{macro}\texttt{macro} and
282 % \DescribeEnv{environment}\texttt{environment} environments,
283 % \package{xdoc} also defines an \DescribeEnv{option}\texttt{option}
284 % environment (which is intended for document class and package
285 % options) and a \DescribeEnv{switch}\texttt{switch} environment (which
286 % is intended for switches defined using |\newif|; the argument should
287 % not include the |\if|).
288 %
289 % There is also a companion command \DescribeMacro\NewDescribeCommand
290 % |\NewDescribeCommand| which defines new commands similar to
291 % |\Describe|\-|Macro| and |\Describe|\-|Env|. The syntax of
292 % |\New|\-|Describe|\-|Command| is also too complex to explain here, so
293 % I have to refer readers who want to use it to Section~^^A
294 % \ref{Sec:Describing}. Two more commands which are defined in that
295 % section are \DescribeMacro\describeoption|\describe|\-|option|, which
296 % is the \texttt{describe}\dots\ companion of the \texttt{option}
297 % environment, and \DescribeMacro\describecsfamily
298 % |\describe|\-|cs|\-|family| which is meant for describing control
299 % sequence families (see the table on page~\pageref{Tab:CS-families} for
300 % examples of what I mean). The argument of this latter command is simply
301 % the material you would put between |\csname| and |\endcsname|. Variant
302 % parts are written as |\meta|\B\marg{text} and print as one would expect
303 % them to (but notice that the \meta{text} is a moving argument) whereas
304 % most other characters can be written verbatim without any special
305 % quoting (but |\|, |{|, |}|, and |%| need quoting; see the comments to
306 % the definition of |\describe|\-|cs|\-|family| for information on how
307 % to do that).
308 %
309 % The \DescribeMacro\DoNotIndexBy|\DoNotIndexBy| command tells the
310 % commands that make index entries for macros to ignore a certain
311 % character sequence when the index entries are sorted. The
312 % |\DoNotIndexBy| command takes one argument: the character sequence to
313 % ignore. If |\DoNotIndexBy| is used more than once then the indexing
314 % commands will look for, and if it finds it ignore, each of the
315 % character sequences given to it, starting with the one specified last.
316 %
317 % It has already been mentioned that the |\DocInclude| command has been
318 % changed. What has not been mentioned is its companion
319 % \DescribeMacro\setfileinfo|\setfileinfo|,
320 % which the partfiles should use for setting the date and version
321 % information presented in the page footer, but that is explained in
322 % detail in Subsection~\ref{Ssec:New DocInclude}.
323 %
324 % Finally there is a new variant of the |\changes| command which is
325 % intended for changes that, although not limited to a single macro and
326 % thus being ``general'' changes in the \package{doc} terminology, affect
327 % only a few (probably widely dispersed) macros (or whatever). The basic
328 % idea is that you can define a change with a specific version, date,
329 % and text using the \DescribeMacro{\definechange}|\definechange| command
330 % and then recall those parameters later using the
331 % \DescribeMacro{\usechange}|\usechange| command. Primarily this ensures
332 % that the entry texts are identical so that \package{makeindex} will
333 % combine them into one entry, but it is also specified which macro
334 % was changed at which page. See Section~\ref{Sec:Changes} for more
335 % details. Another new feature concerning |\changes| is that there is
336 % now support for sorting version numbers according to mathematical
337 % order rather than ASCII order. Traditionally the version numbers
338 % \texttt{2}, \texttt{11}, and \texttt{100} would have been sorted so
339 % that \texttt{100}${}<{}$\texttt{11}${}<{}$\texttt{2}, but if they are
340 % entered as \DescribeMacro{\uintver}|\uintver{2}|, |\uintver{11}|, and
341 % |\uintver{100}| then they will be sorted as
342 % \texttt{2}${}<{}$\texttt{11}${}<{}$\texttt{100}. The argument of
343 % |\uintver| must be a \TeX\ \meta{number}.
344 %
345 % \medskip
346 %
347 % \package{xdoc} also contains several features which are of little use
348 % as direct user commands, but which can simplify the definitions of other
349 % commands. The foremost of these are the `harmless character strings',
350 % which can be seen as a datatype for (short pieces of) verbatim text.
351 % \TeX\ typesets a harmless character string in pretty much the same way
352 % as the corresponding string of `other' tokens, but the harmless
353 % character string can also be written to file and read back arbitrarily
354 % many times without getting garbled, it doesn't make \package{makeindex}
355 % choke, and it survives being fed to a |\protected@edef|. The most
356 % important commands related to harmless character strings are
357 % \DescribeMacro\PrintChar|\PrintChar|, which is used for representing
358 % problematic characters, and \DescribeMacro\MakeHarmless|\MakeHarmless|,
359 % which converts arbitrary \TeX\ code to the corresponding harmless
360 % character string.
361 %
362 % The superfluity of indexing commands in \package{doc} has been
363 % replaced by the single command \DescribeMacro\IndexEntry|\IndexEntry|,
364 % which has been designed with the intention that it should provide a
365 % clear interface between the user level macros and the index sorting
366 % program. It takes three arguments: the index entry specification, the
367 % name of the encapsulation scheme that should be used, and the number to
368 % put in the index. The index entry specification is a sequence of
369 % |\LevelSame| and\slash or |\LevelSorted| commands, which have the
370 % respective syntaxes
371 % \begin{quote}
372 % \DescribeMacro\LevelSame|\LevelSame|\marg{text}\\
373 % \DescribeMacro\LevelSorted|\LevelSorted|\marg{sort key}\marg{text}
374 % \end{quote}
375 % Each such command specifies one level of the index entry. In the case of
376 % |\LevelSorted|, the \meta{text} is what will be written in the sorted
377 % index at that level and \meta{sort key} is what the index-sorting
378 % program should look at when sorting the entry (at that level). In the
379 % case of |\LevelSame|, the \meta{text} is used both as sort key and
380 % contents of entry in the sorted index. The first command is for the
381 % topmost level and each subsequent command is for the next sublevel.
382 % The complete description appears in Subsection~\ref{Ssec:IndexEntry}.
383 %
384 % \package{xdoc} also contains support for external cross-referencing
385 % programs (see Subsection~\ref{Ssec:XXR} for details) and a system for
386 % determining whether a piece of text falls on an even or an odd page
387 % (see Section~\ref{Sec:Twoside} for details). I expect that the latter
388 % system will eventually migrate out of \package{xdoc}, either to a
389 % package of its own, or into oblivion because the \LaTeXplus\ output
390 % routine makes it obsolete.
391 %
392 %
393 % \subsection{The \package{docindex} package}
394 %
395 % As of prototype version 2.2, the \package{xdoc} package has a companion
396 % package \package{docindex}~\cite{docindex} which provides improved
397 % formatting of the index and list of changes. \package{xdoc} works fine
398 % without \package{docindex}, however.
399 %
400 %
401 % \subsection{A note on command names}
402 %
403 % The \package{doc} package defines several commands with mixed-case
404 % names which (IMHO) should really have all-lower-case names (according
405 % to the rule of thumb spelled out in \cite[Ssec.~2.4]{clsguide}) since
406 % people use them in the capacity of being the author of a \texttt{.dtx}
407 % file rather than in the capacity of being the writer of a class or
408 % package. The names in question are
409 % \begin{longtable}{ll}
410 % \textbf{Name in \package{doc}}& \textbf{Better (?) name}\endhead
411 % \cs{AlsoImplementation}& \cs{alsoimplementation}\\
412 % \cs{CharacterTable}& \cs{charactertable}\\
413 % \cs{CharTableChanges}& \cs{chartablechanges}\\
414 % \cs{CheckModules}& \cs{checkmodules}\\
415 % \cs{CheckSum}& \cs{checksum}\\
416 % \cs{CodelineIndex}& \cs{codelineindex}\\
417 % \texttt{CodelineNo} (counter)& \texttt{codelineno}\\
418 % \cs{CodelineNumbered}& \cs{codelinenumbered}\\
419 % \cs{DeleteShortVerb}& \cs{deleteshortverb}\\
420 % \cs{DescribeEnv}& \cs{describeenv}\\
421 % \cs{DescribeMacro}& \cs{describemacro}\\
422 % \cs{DisableCrossrefs}& \cs{disablecrossrefs}\\
423 % \cs{DocInput}& \cs{docinput}\\
424 % \cs{DoNotIndex}& \cs{donotindex}\\
425 % \cs{DontCheckModules}& \cs{dontcheckmodules}\\
426 % \cs{EnableCrossrefs}& \cs{enablecrossrefs}\\
427 % \cs{Finale}& \cs{finale}\\
428 % \texttt{GlossaryColumns} (counter)& \texttt{glossarycolumns}\\
429 % \cs{GlossaryPrologue}& \cs{glossaryprologue}\\
430 % \texttt{IndexColumns} (counter)& \texttt{indexcolumns}\\
431 % \cs{IndexInput}& \cs{indexinput}\\
432 % \cs{IndexPrologue}& \cs{indexprologue}\\
433 % \cs{MakePrivateLetters}& \cs{makeprivateletters}\\
434 % \cs{MakeShortVerb}& \cs{makeshortverb}\\
435 % \cs{OnlyDescription}& \cs{onlydescription}\\
436 % \cs{PageIndex}& \cs{pageindex}\\
437 % \cs{PrintChanges}& \cs{printchanges}\\
438 % \cs{PrintIndex}& \cs{printindex}\\
439 % \cs{RecordChanges}& \cs{recordchanges}\\
440 % \cs{SortIndex}& \cs{sortindex}\\
441 % \cs{SpecialEscapechar}& \cs{specialescapechar}\\
442 % \texttt{StandardModuleDepth} (counter)& \texttt{standardmoduledepth}\\
443 % \cs{StopEventually}& \cs{stopeventually}
444 % \end{longtable}
445 % \noindent With the exception for \texttt{CodelineNo},\footnote{Where I
446 % recommend using \texttt{codelineno} instead of \texttt{CodelineNo},
447 % \cs{PrintCodelineNo} instead of \cs{theCodelineNo}, and
448 % \cs{thecodelineno} instead of \cs{number}\cs{c@CodelineNo}; see
449 % Subsection~\ref{Ssec:CodelineNo}.} I haven't changed any of the
450 % \package{doc} names in this \package{xdoc} prototype, nor introduced any
451 % of the ``better names'' as alternatives, but I think the matter should
452 % be given a bit of thought during the future development of
453 % \package{doc}\slash \package{xdoc}.
454 %
455 % For completeness, I should also remark that there are several macros
456 % that \package{doc} gives mixed-case names which I haven't listed above.
457 % The logo command names have special capitalizing rules by tradition.
458 % Some macros and named registers---for example |\Docstyle|\-|Parms|,
459 % |\Index|\-|Parms|, |\Macro|\-|Font|, |\Macro|\-|Topsep|,
460 % |\Make|\-|Percent|\-|Ignore|, and |\Print|\-|Macro|\-|Name|---are part
461 % of the package or document class writer's interface to \package{doc},
462 % although I cannot claim it to be obvious that for example
463 % |\Index|\-|Parms| and the \texttt{IndexColumns} counter should belong
464 % to different classes here (but several of these control sequences will
465 % probably disappear from the interface in \LaTeXplus\ anyway, so the
466 % problem isn't that important). The |\Special|\dots\B|Index| commands
467 % (and their even more special variants, such as
468 % |\Left|\-|Brace|\-|Index|) are internal commands rather than user level
469 % commands. Finally there is the |\Get|\-|File|\-|Info| command, which I
470 % doubt there is any point in having.
471 %
472 %
473 % \StopEventually{}
474 %
475 %
476 % \subsection{\package{docstrip} modules}
477 %
478 % The \package{docstrip} modules in \texttt{xdoc2.dtx} are:
479 % \begin{description}
480 % \item[\textsf{pkg}]
481 % This module directive surrounds the code for the \package{xdoc}
482 % package.
483 % \item[\textsf{driver}]
484 % The driver.
485 % \item[\textsf{internals}]
486 % This module contains an alternative replacement text for the
487 % |\Print|\-|Visible|\-|Char| command that uses ``\LaTeX\ internal
488 % character representation'' (i.e., as much as possible
489 % encoding-specific commands---|\text|\textellipsis\ commands and
490 % the like) rather than the primitive |\char| command for
491 % typesetting visible characters.
492 % It is provided as a separate module mainly for compability with
493 % prototype version~2.0, as this alternative definition can (as of
494 % prot.\,2.1) be chosen by passing the option
495 % \describeoption{notrawchar}\texttt{notrawchar} to \package{xdoc}.
496 % \item[\textsf{economical}]
497 % There is little point in storing the harmless representations of
498 % the 161 non-visible-ASCII characters as these representations are
499 % always the same and can be formed on the fly whenever they are
500 % needed. The \textsf{economical} modules contain some alternative
501 % code which makes use of this fact to reduce the number of control
502 % sequences used for storing the table of harmless representations.
503 % The \Module{economical} module appears inside the \Module{pkg}
504 % module.
505 % \item[\textsf{xdoc2}]
506 % This module contains code for compability with previous releases
507 % of \package{xdoc2}. It will not be included in \package{xdoc3}
508 % or \package{xdoc} (whichever is the next major version).
509 % \item[\textsf{enccmds}]
510 % This module contains the code for defining two \texttt{macro}-like
511 % environments for encoding-specific commands. These are not included
512 % in the \package{xdoc} package since so few \texttt{.dtx} files
513 % define encoding-specific commands.
514 % \item[\textsf{rsrccmd}]
515 % Similar to the \textsf{enccmds} module, but demonstrates the
516 % |\New|\-|Describe|\-|Command| command instead.
517 % \item[\textsf{example}]
518 % This surrounds some code which to \package{docstrip} looks like it
519 % should be copied, but isn't meant to.
520 % \end{description}
521 %
522 %
523 %
524 % \section{Initial stuff}
525 %
526 % First there's the usual |\NeedsTeXFormat| and |\ProvidesPackage|.
527 % \begin{macrocode}
528 %<*pkg>
529 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
530 \ProvidesPackage{xdoc2}[2003/07/06 prot2.5 doc reimplementation package]
531 % \end{macrocode}
532 %
533 % \subsection*{Options}
534 %
535 % The first option has to do with the page layout.
536 % Although \package{doc} itself doesn't modify any of the main layout
537 % parameters, it is well known that using it does tend to restrict
538 % one's choices in terms of document layout. In particular the
539 % \texttt{macro} and \texttt{environment} environments require a rather
540 % large left margin since they will otherwise print long macro names
541 % partially outside the paper. It is furthermore hard to decrease the
542 % |\textwidth| as it should be wide enough to contain about 70 columns of
543 % |\MacroFont| text. Thus the only solution is to do as the
544 % \package{ltxdoc}~\cite{ltxdoc} document class and enlarge the left
545 % margin at the expense of the right.
546 %
547 % The resulting layout has a left--right asymmetry with the main galley
548 % (the text rectangle) on the right and a very wide left margin (in
549 % which marginal headings and marginal notes appears). Although this
550 % layout is not uncommon in technical manuals, it is inappropriate for
551 % two-sided designs since the vertical line at which the two pages of a
552 % spread meet becomes the natural vertical symmetry axis for the entire
553 % spread and it breaks this symmetry to let the left margin be the
554 % widest on all pages. It would look better to always let the outer
555 % margin be the largest.
556 %
557 % \begin{option}{dolayout}
558 % \begin{macro}{\oddsidemargin}
559 % The \texttt{dolayout} option modifies |\oddsidemargin| so that
560 % spreads are symmetric around the center in two-sided mode. As size
561 % of the outer margin is taken the size of the left margin on left
562 % (even) pages, i.e., |\evensidemargin|${}+1\,\mathrm{in}$.
563 %
564 % In one-sided mode, the \texttt{dolayout} option does nothing.
565 % \begin{macrocode}
566 \DeclareOption{dolayout}{%
567 \if@twoside
568 \setlength\oddsidemargin{\paperwidth}
569 \addtolength\oddsidemargin{-\textwidth}
570 \addtolength\oddsidemargin{-\evensidemargin}
571 \addtolength\oddsidemargin{-2in}
572 \fi
573 }
574 % \end{macrocode}
575 % \end{macro}\end{option}
576 %
577 % \begin{option}{olddocinclude}
578 % \begin{option}{fileispart}
579 % The \texttt{olddocinclude} and \texttt{fileispart} options are
580 % related to the |\DocInclude| command defined by the \package{ltxdoc}
581 % document class. Some of the code related to that command relies on
582 % modifying the \package{doc} internal macro |\codeline@wrindex|, but
583 % that has no effect with \package{xdoc} so in order to get the
584 % expected results one has to reimplement the |\DocInclude| command as
585 % well. The \texttt{olddocinclude} and \texttt{fileispart} options
586 % control how this should be done.
587 %
588 % If the \texttt{olddocinclude} option is passed to \package{xdoc}
589 % then only the parts of the implementation of |\DocInclude| which
590 % must be altered to make the command work with the \package{xdoc}
591 % implementation of indexing and cross-referencing are changed. These
592 % redefinitions will furthermore only be made if the \package{ltxdoc}
593 % document class has been loaded; nothing is done if the
594 % \texttt{olddocinclude} option is passed and \package{ltxdoc} hasn't
595 % been loaded. Passing the \texttt{olddocinclude} option can be
596 % considered as requesting a ``compatibility mode'' for |\DocInclude|.
597 %
598 % If the \texttt{olddocinclude} option is not passed then the
599 % |\DocInclude| command is reimplemented from scratch, regardless of
600 % whether some definition of it has already been given or not. The
601 % basis of this reimplementation is the observation that the
602 % |\DocInclude| command of \package{ltxdoc} really does two quite
603 % distinct things at once---it is an |\include| command which
604 % |\DocInput|s files rather than |\input|ting them, but it also starts
605 % a new |\part|, sets the pagestyle, and changes how the values of
606 % some counters are typeset. This latter function is by default
607 % disabled in the \package{xdoc} implementation of |\DocInclude|, but
608 % passing the \texttt{fileispart} option enables it.
609 %
610 % There is no code for these two options here, as it is rather long;
611 % instead that code appears in Section~\ref{Sec:DocInclude}. The
612 % |\Pass|\-|Options|\-|To|\-|Package| commands make sure that these
613 % options are registered as local options for \package{xdoc}, so that
614 % one can test for them using |\@if|\-|package|\-|with| below.
615 % \begin{macrocode}
616 \DeclareOption{olddocinclude}{%
617 \PassOptionsToPackage{\CurrentOption}{xdoc2}%
618 }
619 \DeclareOption{fileispart}{%
620 \PassOptionsToPackage{\CurrentOption}{xdoc2}%
621 }
622 % \end{macrocode}
623 % \end{option}\end{option}
624 %
625 % \changes{prot2.5}{2003/07/06}{Reregeristing options in case
626 % they were global. (LH)}
627 %
628 % \begin{option}{notrawchar}
629 % The \texttt{notrawchar} option controls how the |\PrintVisibleChar|
630 % command is defined, and thereby what method is used for typesetting
631 % visible characters in e.g.\ macro names. The default is to use the
632 % |\char| primitive (which is better for \texttt{T1}-encoded fonts and
633 % non-italic \texttt{OT1}-encoded typewriter fonts), but the
634 % \texttt{notrawchar} option causes things to go via the ``\LaTeX\
635 % internal character representation'' instead (which is necessary
636 % for e.g.\ \texttt{OT1}-encoded non-typewriter fonts).
637 %
638 % There is no code for this option here; instead that code is found
639 % in the definition of |\Print|\-|Visible|\-|Char|.
640 % \begin{macrocode}
641 \DeclareOption{notrawchar}{%
642 \PassOptionsToPackage{\CurrentOption}{xdoc2}%
643 }
644 % \end{macrocode}
645 % \end{option}
646 %
647 %
648 % Then options are processed.
649 % \begin{macrocode}
650 \ProcessOptions\relax
651 % \end{macrocode}
652 % And finally the \package{doc} package is loaded.
653 % \begin{macrocode}
654 \RequirePackage{doc}
655 % \end{macrocode}
656 %
657 %
658 % \section{Character strings}
659 %
660 % A source of much of the complexity in \package{doc} is that it has to
661 % be able to deal with rather arbitrary strings of characters (mainly
662 % the names of control sequences). Once the initial problems with
663 % characters having troublesome catcodes have been overcome however, it
664 % is usually no problem to manage such things in \TeX. \package{doc}
665 % does however complicate things considerably by also putting these
666 % things in the index and list of changes. Not only must they then be
667 % formatted so that the \package{makeindex} program doesn't choke on
668 % them, but they must also be wrapped up in code that allows \TeX\ to
669 % make sense of them when they are read back. \package{doc} manages the
670 % \package{makeindex} problems mainly by allowing the user to change what
671 % characters are used as \package{makeindex} metacharacters and the
672 % reading back problem by making abundant use of |\verb|.
673 %
674 % All this relies on that the author of a document is making sure that
675 % the metacharacters aren't used for anything else. If for example the
676 % |\verbatimchar| (by default |+|) is one of the ``private letters''
677 % then names of control sequences containing that character will be
678 % typeset incorrectly because the |\verb| used to typeset it is
679 % terminated prematurely---control sequence names such as `|\lost+found|'
680 % will be typeset as `|\lost|found+'. On top of that, one also has to
681 % make sure that the font used for typesetting these |\verb| sections
682 % contains all the characters needed.
683 %
684 % For \package{xdoc}, I have chosen a completely different approach.
685 % Instead of allowing the strings (after they have converted to the
686 % internal format) to contain \TeX\ character tokens with arbitrary
687 % character codes, they may only contain \TeX\ character tokens which
688 % are unproblematic---the normal catcode should be 11 (letter) or 12
689 % (other), they should not be outside visible ASCII, and they may not
690 % be one of the \package{makeindex} metacharacters. All other characters
691 % are represented using a robust command which takes the character code
692 % (in decimal) as the argument. This takes care of all ``moving
693 % argument'' type problems that may occur.
694 %
695 % An important observation about these character strings is that
696 % they are strings of \emph{input} characters. This means that rather
697 % than using the characters in some special font for typesetting
698 % control sequences like |\^^M| (recall that the |^^| substitutions
699 % take place before tokenization), one should typeset them using only
700 % visible ASCII characters. (After all, that's the only way they are
701 % written in \TeX\ code.) The default definition is to typeset
702 % invisible characters as precisely the |^^|-sequences that \TeX\
703 % normally uses for these characters when they are written to a file.
704 %
705 %
706 % \subsection{Typesetting problematic characters}
707 %
708 % \begin{macro}{\PrintChar}
709 % \begin{macro}{\XD@threedignum}
710 % The |\PrintChar| command has the syntax
711 % \begin{quote}
712 % |\PrintChar|\marg{8-bit number}
713 % \end{quote}
714 % where \meta{8-bit number} is a \TeX\ number in the range 0--255.
715 % For arguments in the range 0--31, |\PrintChar| prints
716 % `\textit{\ttfamily\string^\string^@}'--`\textit{\ttfamily
717 % \string^\string^\string_}'. For an argument in the range 32--126,
718 % |\PrintChar| calls |\Print|\-|Visible|\-|Char| which by default
719 % simply does |\char| on that argument (but which can be redefined
720 % if the font set-up requires it); in particular, |\PrintChar{32}|
721 % should print a ``visible space'' character. |\PrintChar{127}| prints
722 % `\textit{\ttfamily\string^\string^?}'. For arguments in the range
723 % 128--255, |\PrintChar| prints
724 % `\textit{\ttfamily\string^\string^80}'--`\textit{\ttfamily
725 % \string^\string^ff}'.
726 %
727 % |\PrintChar| is robust. |\PrintChar| also has a special behaviour
728 % when it is written to a file (when |\protect| is |\noexpand|): it
729 % makes sure that the argument consists of three decimal digits, to
730 % ensure external sorting gets it right.
731 % \begin{macrocode}
732 \@ifundefined{PrintChar}{}{%
733 \PackageInfo{xdoc2}{Redefining \protect\PrintChar}%
734 }
735 \def\PrintChar{%
736 \ifx \protect\@typeset@protect
737 \expandafter\XD@PrintChar
738 \else\ifx \protect\noexpand
739 \string\PrintChar
740 \expandafter\expandafter \expandafter\XD@threedignum
741 \else
742 \noexpand\PrintChar
743 \fi\fi
744 }
745 % \end{macrocode}
746 %
747 % |\XD@threedignum| does a |\number| on its argument, possibly prepends
748 % a |0| or two, and wraps it all up in a ``group'' (the braces have
749 % category other, not beginning and end of group).
750 % \changes{prot2.1}{2000/11/15}{Braces inserted by
751 % \cs{XD@threedignum} are given catcode other. (LH)}
752 % \begin{macrocode}
753 \edef\XD@threedignum#1{%
754 \string{%
755 \noexpand\ifnum #1<100 %
756 \noexpand\ifnum #1<10 0\noexpand\fi
757 0%
758 \noexpand\fi
759 \noexpand\number#1%
760 \string}%
761 }
762 % \end{macrocode}
763 % \end{macro}\end{macro}
764 %
765 % \begin{macro}{\XD@PrintChar}
766 % \begin{macro}{\InvisibleCharPrefix}
767 % \begin{macro}{\InvisibleCharSuffix}
768 % |\XD@PrintChar| manages the typesetting for |\PrintChar|. It
769 % distinguishes between visible characters (code 32--126) and
770 % invisible characters. The visible characters are typeset directly
771 % using |\PrintVisibleChar|, whereas the invisible characters are
772 % typeset as |^^|-sequences.
773 %
774 % The macros |\InvisibleCharPrefix| and |\InvisibleCharSuffix| begin
775 % and end a |^^|-sequence. |\InvisibleCharPrefix| should print the
776 % actual |^^|, but it may also for example select a new font for
777 % the |^^|-sequence (such font changes are restored at the end of
778 % |\XD@PrintChar|).
779 % \begin{macrocode}
780 \def\XD@PrintChar#1{%
781 \leavevmode
782 \begingroup
783 \count@=#1\relax
784 \ifnum \@xxxii>\count@
785 \advance \count@ 64%
786 \InvisibleCharPrefix
787 \PrintVisibleChar\count@
788 \InvisibleCharSuffix
789 \else\ifnum 127>\count@
790 \PrintVisibleChar\count@
791 \else
792 \InvisibleCharPrefix
793 \ifnum 127=\count@ \PrintVisibleChar{63}\else
794 \@tempcnta=\count@
795 \divide \count@ \sixt@@n
796 \@tempcntb=\count@
797 \multiply \count@ \sixt@@n
798 \advance \@tempcnta -\count@
799 \advance \@tempcntb \ifnum 9<\@tempcntb 87\else 48\fi
800 \advance \@tempcnta \ifnum 9<\@tempcnta 87\else 48\fi
801 \char\@tempcntb \char\@tempcnta
802 \fi
803 \InvisibleCharSuffix
804 \fi\fi
805 \endgroup
806 }
807 % \end{macrocode}
808 % \begin{macrocode}
809 \newcommand\InvisibleCharPrefix{%
810 \/\em
811 \PrintVisibleChar{`\^}\PrintVisibleChar{`\^}%
812 }
813 \newcommand\InvisibleCharSuffix{\/}
814 % \end{macrocode}
815 % There are some alternative methods for making hexadecimal numbers
816 % which should perhaps be mentioned. The \LaTeX\ kernel contains a
817 % macro |\hexnumber@| which uses |\ifcase| to produce one hexadecimal
818 % digit, but that uses upper case letters, and things like `8E' look
819 % extremely silly if the upper case letters doesn't line with the
820 % digits. Applying |\meaning| to a \meta{chardef token} or
821 % \meta{mathchardef token} expands to |\char"|\meta{hex} and
822 % |\mathchar"|\meta{hex} respectively, where \meta{hex} is the
823 % corresponding number in hexadecimal, but that too has upper case A--F
824 % and leading zeros are removed.
825 % \end{macro}\end{macro}\end{macro}
826 %
827 % \begin{macro}{\PrintVisibleChar}
828 % \changes{prot2.1}{2000/12/18}{Made it possible to select the
829 % alternative defintion of \cs{PrintVisibleChar} through an
830 % \package{xdoc} package option. (LH)}
831 % The |\PrintVisibleChar| command should print the visible ASCII
832 % character whose character code is given in the argument. There are
833 % currently two definitions of this command: one which uses the \TeX\
834 % primitive |\char| and one which goes via the ``\LaTeX\ internal
835 % character representation'' for the character. By default
836 % \package{xdoc} uses the former definition, but if \package{xdoc}
837 % is passed the
838 % \SortIndex{notrawchar}{\texttt{notrawchar} option\encapchar usage}
839 % \texttt{notrawchar} option then it will use the latter.
840 %
841 % The reason there are two definitions is a deficiency in how the NFSS
842 % encoding attribute has been assigned to fonts; even though the
843 % encodings of Computer Modern Roman and Computer Modern Typewriter
844 % are quite different, \LaTeXe\ uses the \texttt{OT1} encoding for
845 % both. As a result of this, the \LaTeX\ internal representation will
846 % in some important cases use characters from non-typewriter fonts
847 % despite the fact that typewriter forms are immediately available.
848 % Since the cases in which the |\char| primitive produces results as
849 % least as good as those made through the \LaTeX\ internal
850 % character representation includes those that the current font is
851 % \texttt{T1}-encoded or an \texttt{OT1}-encoded nonitalic typewriter
852 % font, the shorter |\char| primitive defintion has been made the
853 % default.
854 %
855 % For compability with prototype version~2.0 of \package{xdoc}, the
856 % replacement text for |\Print|\-|Visible|\-|Char| that uses \LaTeX\
857 % internal character representation can alternatively be extracted by
858 % \package{docstrip}ping \texttt{xdoc2.dtx} with the option
859 % \Module{internals}.
860 % \begin{macrocode}
861 \@ifpackagewith{xdoc2}{notrawchar}{%
862 \newcommand\PrintVisibleChar[1]{%
863 %</pkg>
864 %<*pkg|internals>
865 \ifcase #1%
866 \or\or\or\or\or\or\or\or \or\or\or\or\or\or\or\or
867 \or\or\or\or\or\or\or\or \or\or\or\or\or\or\or\or
868 % "20
869 \textvisiblespace \or!\or\textquotedbl \or\#\or\textdollar
870 \or\%\or\&\or\textquoteright\or(\or)\or*\or+\or,\or-\or.\or/%
871 \or % "30
872 0\or1\or2\or3\or4\or5\or6\or7\or8\or9\or:\or;\or
873 \textless\or=\or\textgreater\or?%
874 \or % "40
875 @\or A\or B\or C\or D\or E\or F\or G\or
876 H\or I\or J\or K\or L\or M\or N\or O%
877 \or % "50
878 P\or Q\or R\or S\or T\or U\or V\or W\or X\or Y\or Z\or [\or
879 \textbackslash \or]\or\textasciicircum \or\textunderscore
880 \or % "60
881 \textquoteleft \or a\or b\or c\or d\or e\or f\or g\or h\or
882 i\or j\or k\or l\or m\or n\or o%
883 \or % "70
884 p\or q\or r\or s\or t\or u\or v\or w\or x\or y\or z\or
885 \textbraceleft \or\textbar \or\textbraceright \or
886 \textasciitilde
887 \fi
888 }%
889 %</pkg|internals>
890 %<*pkg>
891 }{%
892 \newcommand\PrintVisibleChar[1]{\char #1\relax}%
893 }
894 % \end{macrocode}
895 % \end{macro}
896 %
897 %
898 % \begin{macro}{\Bslash}
899 % It turns out that it is very common to say |\PrintChar{92}|
900 % (backslash), so a macro which expands to that reduces typing.
901 % \begin{macrocode}
902 \newcommand\Bslash{\PrintChar{92}}
903 % \end{macrocode}
904 % \end{macro}
905 %
906 %
907 % \subsection{Rendering character strings harmless}
908 %
909 % Replacing all problematic characters with |\PrintChar| calls certainly
910 % makes the strings easier to manage, but actually making those
911 % replacements is a rather complicated task. Therefore this subsection
912 % contains the macros necessary for doing these replacements.
913 %
914 % The first problem is how to efficiently recognise the problematic
915 % characters. A first solution which gets rather far is to mainly look
916 % in the |\catcode| register for that character and keep the character
917 % as it is if the category found there is 11 or 12, but replace it with
918 % a |\PrintChar| command if the category is anything else. Two extra
919 % tests can be performed to take care of invisible ASCII, and the
920 % \package{makeindex} metacharacters can be cared for by locally
921 % changing their catcodes for when the string is processed.
922 % Unfortunately this doesn't work inside \texttt{macrocode}
923 % environments (where one would like to use it for the macro
924 % cross-referencing) since that environment changes the catcodes of
925 % several characters from being problematic to being unproblematic and
926 % vice versa.\footnote{As the entire \texttt{macrocode} environment is
927 % tokenized by the expansion of \cs{xmacro@code} one could alternatively
928 % solve this problem by reimplementing the \texttt{macrocode}
929 % environment so that normal catcodes are in force when the contents are
930 % being typeset.} As furthermore harmless character strings should be
931 % possible to move to completely different parts of the document, the
932 % test used for determining whether a character is problematic should
933 % yield the same result throughout the document.
934 %
935 % Because of this, I have chosen a brute strength solution: build a
936 % table (indexed by character code) that gives the harmless form of
937 % every character. This table is stored in the
938 % \describecsfamily{XD@harmless@\meta{code}}^^A
939 % |\XD@harmless@|\meta{code} family of control sequences, where the
940 % \meta{code} is in the range |0|--|255|. Assignments to this table are
941 % global. In principle, the table should not change after the preamble,
942 % but there is a command |\SetHarmState| which can be used at any time
943 % for setting a single table entry. This could be useful for documents
944 % which, like for example~\cite{fontinst}, have nonstandard settings of
945 % |\catcode|s.
946 %
947 % \begin{macro}{\SetHarmState}
948 % The |\SetHarmState| command takes three arguments:
949 % \begin{quote}
950 % |\SetHarmState|\marg{type}\marg{char}\marg{harm}
951 % \end{quote}
952 % \meta{char} is the character whose entry should be set. \meta{type}
953 % is a flag which specifies what format \meta{char} is given in. If
954 % \meta{type} is |\BooleanTrue| then \meta{char} is the \TeX\
955 % \meta{number} of the table entry to set, and if \meta{type} is
956 % |\BooleanFalse| then \meta{char} is something which expands to a
957 % single character token whose entry should be set. The expansion is
958 % carried out by an |\edef|, so it needs not be only one level.
959 % \meta{harm} is |\BooleanTrue| if the character is problematic and
960 % |\BooleanFalse| if it is not.
961 %
962 % The \meta{type} and \meta{harm} arguments are currently not subject
963 % to any expansion. In the future they probably should be, but I
964 % don't want to make assumptions about the actual definitions of
965 % |\BooleanTrue| and |\BooleanFalse| at this point.
966 % \begin{macrocode}
967 \begingroup
968 \catcode\z@=12
969 \@ifdefinable\SetHarmState{
970 \gdef\SetHarmState#1#2#3{%
971 \begingroup
972 \ifx #1\BooleanTrue
973 \count@=#2\relax
974 \else
975 \protected@edef\@tempa{#2}%
976 \count@=\expandafter`\@tempa\relax
977 \fi
978 \ifx #3\BooleanTrue
979 \edef\@tempa{\noexpand\PrintChar{\the\count@}}%
980 \else
981 \uccode\z@=\count@
982 \uppercase{\def\@tempa{^^@}}%
983 \fi
984 \global\expandafter\let
985 \csname XD@harmless@\the\count@ \endcsname \@tempa
986 \endgroup
987 }%
988 }
989 \endgroup
990 % \end{macrocode}
991 % \end{macro}
992 %
993 % \begin{trivlist}\item[]\leavevmode ^^A Just for the look of it
994 % \GenericDescribePrint{\small\cs{XD@harmless@}\meta{code}}^^A
995 % ^^A There should have been a "main" index entry here as well,
996 % ^^A but generating that with \package{doc} commands is more than I
997 % ^^A bother to do right now.
998 % Initializing the |\XD@harmless@|\meta{code} table is a
999 % straightforward exercise of |\loop| \dots\ |\repeat|.
1000 % \begin{macrocode}
1001 %<*!economical>
1002 \count@=\z@
1003 \loop
1004 \expandafter\xdef \csname XD@harmless@\the\count@ \endcsname
1005 {\noexpand\PrintChar{\the\count@}}%
1006 \advance \count@ \@ne
1007 \ifnum 33>\count@ \repeat
1008 %</!economical>
1009 %<economical>\count@=\@xxxii
1010 \begingroup
1011 \catcode\z@=12\relax
1012 \@firstofone{%
1013 \endgroup
1014 \loop
1015 \if \ifnum 11=\catcode\count@ 1\else \ifnum 12=\catcode\count@
1016 1\else 0\fi\fi 1%
1017 \uccode\z@=\count@
1018 \uppercase{\def\@tempa{^^@}}%
1019 \else
1020 \edef\@tempa{\noexpand\PrintChar{\the\count@}}%
1021 \fi
1022 \global\expandafter\let
1023 \csname XD@harmless@\the\count@ \endcsname \@tempa
1024 \advance \count@ \@ne
1025 \ifnum 127>\count@ \repeat
1026 }
1027 %<*!economical>
1028 \loop
1029 \expandafter\xdef \csname XD@harmless@\the\count@ \endcsname
1030 {\noexpand\PrintChar{\the\count@}}%
1031 \ifnum \@cclv>\count@
1032 \advance \count@ \@ne
1033 \repeat
1034 %</!economical>
1035 % \end{macrocode}
1036 % Marking the \package{makeindex} metacharacters as harmful is
1037 % deferred until |\begin|\nolinebreak[2]|{document}|, since it is not
1038 % unreasonable that these are changed in the preamble.
1039 % \begin{macrocode}
1040 \AtBeginDocument{%
1041 \SetHarmState\BooleanFalse\actualchar\BooleanTrue
1042 \SetHarmState\BooleanFalse\encapchar\BooleanTrue
1043 \SetHarmState\BooleanFalse\levelchar\BooleanTrue
1044 \SetHarmState\BooleanFalse\quotechar\BooleanTrue
1045 }
1046 % \end{macrocode}
1047 % \package{doc}'s |\verbatimchar| is not harmful, since it isn't used
1048 % at all in \package{xdoc}.
1049 % \end{trivlist}
1050 %
1051 %
1052 % \begin{macro}{\MakeHarmless}
1053 % To render a character string harmless, you do
1054 % \begin{quote}
1055 % |\MakeHarmless|\marg{macro}\marg{string}
1056 % \end{quote}
1057 % This locally assigns to \meta{macro} the harmless character string
1058 % which corresponds to \meta{string}. During the conversion the converted
1059 % part of the string is stored in |\toks@|, but that is local to
1060 % |\MakeHarmless|.
1061 % \begin{macrocode}
1062 \def\MakeHarmless#1#2{%
1063 \begingroup
1064 \toks@={}%
1065 \escapechar=`\\%
1066 \XD@harmless@#2\XD@harmless@
1067 \expandafter\endgroup \expandafter\def \expandafter#1%
1068 \expandafter{\the\toks@}%
1069 }
1070 % \end{macrocode}
1071 %
1072 % \begin{macro}{\XD@harmless@iii}
1073 % \begin{macro}{\XD@harmless@iv}
1074 % \begin{macro}{\XD@harmless@v}
1075 % \changes{prot2}{2000/07/27}{Moved code for adding to \cs{toks@} here
1076 % and changed it to append the contents of \cs{XD@harmless@32}, not
1077 % necessarily a \cs{PrintChar}. (LH)}
1078 % \begin{macro}{\XD@harmless@vi}
1079 % What one has to be most careful about when rendering strings
1080 % harmless are the space tokens, since many of \TeX's primitives gladly
1081 % snatches an extra space (or more) where you don't want them to in
1082 % this case. Macro parameters can be particularly dangerous, as \TeX\
1083 % will skip any number of spaces while looking for the replacement
1084 % text for an undelimited macro argument. Therefore the algorithm for
1085 % rendering a character token harmless begins
1086 % (|\XD@|\B|harmless@iii|) with |\string|ing the next token in the
1087 % string---this preserves the character code and sets the category to
1088 % 12 for all characters except the ASCII space, which gets category 10
1089 % (space)---and then |\futurelet| is used to peek at the next token. If
1090 % it is a space token (|\XD@|\B|harmless@iv|) then the character code
1091 % is 32 and the actual space can be gobbled (|\XD@|\B|harmless@v|), and
1092 % if it isn't then the next token can be grabbed in an undelimited macro
1093 % argument (|\XD@|\B|harmless@vi|). In either case, the harmless form
1094 % is given by the |\XD@|\B|harmless@|\meta{code} table entry
1095 % (in |\XD@|\B|harmless@v| or |\XD@|\B|harmless@vi|).
1096 % \begin{macrocode}
1097 \def\XD@harmless@iii{%
1098 \expandafter\futurelet \expandafter\@let@token
1099 \expandafter\XD@harmless@iv \string
1100 }
1101 % \end{macrocode}
1102 % \begin{macrocode}
1103 \def\XD@harmless@iv{%
1104 \ifx \@let@token\@sptoken
1105 \expandafter\XD@harmless@v
1106 \else
1107 \expandafter\XD@harmless@vi
1108 \fi
1109 }
1110 % \end{macrocode}
1111 % ^^A Hack:
1112 % \begingroup
1113 % \expandafter\def \expandafter\MakePrivateLetters \expandafter{^^A
1114 % \MakePrivateLetters
1115 % \catcode`3=11
1116 % \catcode`2=11
1117 % }
1118 % \begin{macrocode}
1119 \begingroup
1120 \catcode`3=\catcode`a
1121 \catcode`2=\catcode`a
1122 \@firstofone{\gdef\XD@harmless@v} {%
1123 \toks@=\expandafter{\the \expandafter\toks@ \XD@harmless@32}%
1124 \XD@harmless@
1125 }
1126 \endgroup
1127 % \end{macrocode}
1128 % \endgroup
1129 % In the \Module{economical} (with hash table space) variant
1130 % implementation the |\XD@harmless@|\meta{code} table has entries only
1131 % for the characters in visible ASCII. Thus the harmless forms of
1132 % characters outside visible ASCII must be constructed on the fly.
1133 % \begin{macrocode}
1134 \def\XD@harmless@vi#1{%
1135 %<*economical>
1136 \if \ifnum `#1<\@xxxii 1\else \ifnum `#1>126 1\else 0\fi\fi 1%
1137 \toks@=\expandafter{\the\expandafter\toks@
1138 \expandafter\PrintChar \expandafter{\number`#1}%
1139 }%
1140 \else
1141 %</economical>
1142 \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
1143 \csname XD@harmless@\number`#1\endcsname}%
1144 %<economical> \fi
1145 \XD@harmless@
1146 }
1147 % \end{macrocode}
1148 % \end{macro}\end{macro}\end{macro}\end{macro}
1149 %
1150 % \begin{macro}{\XD@harmless@}
1151 % \begin{macro}{\XD@harmless@i}
1152 % \begin{macro}{\XD@harmless@ii}
1153 % But that is not all |\MakeHarmless| can do. In some cases (as for
1154 % example when one is describing a family of control sequences) one
1155 % might want to include things in the string that are not simply
1156 % characters, but more complex items---such as for example |\meta|
1157 % constructions like \meta{code}. To accommodate for this,
1158 % |\XD@harmless@| (which is the first step in converting a token)
1159 % always begins by checking whether the next token to render harmless
1160 % is a control sequence. If it is then it is checked (in
1161 % |\XD@harmless@ii|) whether the control sequence
1162 % \describecsfamily{XD@harmless\Bslash\meta{cs-name}}^^A
1163 % |\XD@harmless\|\meta{cs-name}, where \meta{cs-name} is the name
1164 % without |\| of the control sequence encountered, is defined. If it
1165 % isn't then the encountered control sequence is |\string|ed and
1166 % conversion continues as above, but if it is defined then the
1167 % encountered control sequence begins such a more complex item.
1168 % \begin{macrocode}
1169 \def\XD@harmless@{\futurelet\@let@token \XD@harmless@i}
1170 % \end{macrocode}
1171 % \begin{macrocode}
1172 \def\XD@harmless@i{%
1173 \ifcat \noexpand\@let@token \noexpand\XD@harmless@
1174 \expandafter\XD@harmless@ii
1175 \else
1176 \expandafter\XD@harmless@iii
1177 \fi
1178 }
1179 % \end{macrocode}
1180 % \begin{macrocode}
1181 \def\XD@harmless@ii#1{%
1182 \@ifundefined{XD@harmless\string#1}{%
1183 \expandafter\XD@harmless@vi \string#1%
1184 }{\csname XD@harmless\string#1\endcsname}%
1185 }
1186 % \end{macrocode}
1187 % \end{macro}\end{macro}\end{macro}
1188 %
1189 % \begin{macro}{\XD@harmless\XD@harmless@}
1190 % A control sequence |\XD@harmless\|\meta{cs-name} is responsible for
1191 % interpreting the string item that begins with the control sequence
1192 % |\|\meta{cs-name} and appending a harmless representation of it to
1193 % |\toks@|. Harmless representations should only contain robust
1194 % control sequences and they must not rely on changing any catcodes.
1195 % Normal |\XD@harmless\|\meta{cs-name} control sequences must also
1196 % end by inserting |\XD@harmless@| in front of what remains of the
1197 % string after the complex string item has been removed. This sees to
1198 % that the rest of the string is also rendered harmless. The only such
1199 % control sequence which does not insert |\XD@harmless@| is
1200 % |\XD@harmless\XD@harmless@|, but that is as it should be since
1201 % |\MakeHarmless| itself appends a |\XD@harmless@| to every character
1202 % string it should convert to mark the end of it.
1203 % \begin{macrocode}
1204 \expandafter\let
1205 \csname XD@harmless\string\XD@harmless@\endcsname \@empty
1206 % \end{macrocode}
1207 % \end{macro}
1208 % \end{macro}
1209 %
1210 % \begin{macro}{\XD@harmless\PrintChar}
1211 % It is occasionally convenient to use a |\PrintChar| command as part
1212 % of a string that is to be rendered harmless instead of using the raw
1213 % character. The definition is very similar to that of
1214 % |\XD@harmless@vi|.
1215 % \begin{macrocode}
1216 \@namedef{XD@harmless\string\PrintChar}#1{%
1217 %<*economical>
1218 \if \ifnum #1<\@xxxii 1\else \ifnum #1>126 1\else 0\fi\fi 1%
1219 \toks@=\expandafter{\the\expandafter\toks@
1220 \expandafter\PrintChar \expandafter{\number#1}%
1221 }%
1222 \else
1223 %</economical>
1224 \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
1225 \csname XD@harmless@\number#1\endcsname}%
1226 %<economical> \fi
1227 \XD@harmless@
1228 }
1229 % \end{macrocode}
1230 % \end{macro}
1231 %
1232 %
1233 % \subsection{Interaction with mechanisms that make characters
1234 % problematic}
1235 %
1236 % If additional visible characters are made problematic after the
1237 % initial |\XD@harmless@|\meta{code} table is formed then problems may
1238 % indeed arise, because some character which is expected to be
1239 % unproblematic when read from (for example) an \texttt{.ind} file will
1240 % actually not be. In fortunate cases this will only lead to that
1241 % characters will print strangely or not at all, but it can quite
1242 % conceivably lead to errors that prevent further typesetting and it
1243 % should therefore be prevented if possible.
1244 %
1245 % Right now, I can think of two mechanisms that make characters
1246 % problematic, and both do that by making them active. One is the
1247 % shorthand mechanism of \package{babel}, but I think I'll delay
1248 % implementing any interaction with that until some later prototype; I
1249 % don't know it well enough and anyway I don't think it is that likely
1250 % to cause any problems. The other mechanism is the short verb mechanism
1251 % of \package{doc} itself, and this should be taken care of right away.
1252 %
1253 % The main difficulty is that the |\XD@harmless@|\meta{code} table should
1254 % be the same throughout the document body (otherwise you may get more
1255 % than one index entry for the same thing, with index references
1256 % arbitrarily distributed between the two) whereas short verb characters
1257 % can be made and deleted at any time. It would actually be wrong to
1258 % always have the |\XD@harmless@|\meta{code} table entry mirroring the
1259 % current state of the character! Instead a character will be considered
1260 % as problematic even if it is only made problematic temporarily (with
1261 % the exception for characters that are made problematic in
1262 % \texttt{verbatim} environments and the like---the index file isn't
1263 % being read in while those catcodes are active). Since it is impossible
1264 % to know in the beginning of a document whether a character will be made
1265 % a short verb character at some later point, the modifications to the
1266 % |\XD@harmless@|\meta{code} table that will be made because of short verb
1267 % characters will (at least partially) be based on which characters were
1268 % made short verbs on the previous run.
1269 %
1270 % \begin{macro}{\SetCharProblematic}
1271 % \changes{prot2}{2000/07/26}{Command added. (LH)}
1272 % The |\SetCharProblematic| command should be called by commands which
1273 % make a character problematic (e.g.\ makes it active) in the general
1274 % context (commands which make some character problematic only in some
1275 % very special context, such as the \texttt{verbatim} environment,
1276 % need not call |\Set|\-|Char|\-|Problematic|). The syntax is
1277 % \begin{quote}
1278 % |\SetCharProblematic|\marg{code}
1279 % \end{quote}
1280 % and it sets the ``harm state'' of the character whose code is
1281 % \meta{code} to problematic.
1282 %
1283 % When |\SetCharProblematic| is called in the preamble, it sets the
1284 % harm state on the current run. When it is called in the document
1285 % body however, it sets the harm state on the next run by writing a
1286 % |\SetHarmState| command to the \texttt{.aux} file. This is done to
1287 % ensure that the contents of the |\XD@harmless@|\meta{code} table
1288 % doesn't change during the body of a document.
1289 % \begin{macrocode}
1290 \newcommand\SetCharProblematic[1]{%
1291 \SetHarmState\BooleanTrue{#1}\BooleanTrue
1292 }
1293 \AtBeginDocument{%
1294 \gdef\SetCharProblematic#1{%
1295 \if@filesw
1296 \immediate\write\@auxout{\string\SetHarmState
1297 \string\BooleanTrue {\number#1}\string\BooleanTrue}%
1298 \fi
1299 }%
1300 }
1301 % \end{macrocode}
1302 % \end{macro}
1303 %
1304 % \begin{macro}{\add@specials}
1305 % \changes{prot2}{2000/07/26}{Redefinition added. (LH)}
1306 % |\MakeShortVerb|'s call to |\SetCharProblematic| is put in the
1307 % |\add@|\B|specials| macro, which anyway already adds the character
1308 % to the |\dospecials| and |\@sanitize| lists. Only familiar
1309 % definitions of |\add@special| are changed.
1310 % \begin{macrocode}
1311 \def\@tempa#1{%
1312 \rem@special{#1}%
1313 \expandafter\gdef\expandafter\dospecials\expandafter
1314 {\dospecials \do #1}%
1315 \expandafter\gdef\expandafter\@sanitize\expandafter
1316 {\@sanitize \@makeother #1}}
1317 \ifx \@tempa\add@special
1318 \def\add@special#1{%
1319 \rem@special{#1}%
1320 \expandafter\gdef\expandafter\dospecials\expandafter
1321 {\dospecials \do #1}%
1322 \expandafter\gdef\expandafter\@sanitize\expandafter
1323 {\@sanitize \@makeother #1}%
1324 \SetCharProblematic{`#1}%
1325 }
1326 \else
1327 \PackageWarningNoLine{xdoc2}{Unfamiliar definition of
1328 \protect\add@special;\MessageBreak the macro was not patched}
1329 \fi
1330 % \end{macrocode}
1331 % \end{macro}
1332 %
1333 %
1334 %
1335 % \section{Indexing}
1336 % \label{Sec:Indexing}
1337 %
1338 % Each type of index entry \package{doc} produces is implemented through
1339 % a different indexing command.\footnote{Sometimes there are
1340 % even more than one command per entry type---the \cs{SpecialIndex},
1341 % \cs{LeftBraceIndex}, \cs{RightBraceIndex}, and \cs{PercentIndex}
1342 % commands all generate entries of the same type.} This might be
1343 % manageable when there are only \texttt{macro}s and
1344 % \texttt{environment}s to distinguish between, but it soon gets
1345 % unmanageable if more environments of this type are added. Therefore
1346 % all \package{xdoc} index entries are made with a single
1347 % command---|\IndexEntry|.
1348 %
1349 %
1350 % \subsection{New basic indexing commands}
1351 % \label{Ssec:IndexEntry}
1352 %
1353 % \begin{macro}{\IndexEntry}
1354 % \begin{macro}{\LevelSame}
1355 % \changes{prot2.1}{2000/11/18}{New name for \cs{levelsame}. (LH)}
1356 % \begin{macro}{\LevelSorted}
1357 % \changes{prot2.1}{2000/11/18}{New name for \cs{levelsorted}. (LH)}
1358 % \begin{macro}{\XD@if@index}
1359 % The |\IndexEntry| command writes one index entry to the \texttt{.idx}
1360 % file. It takes three arguments:
1361 % \begin{quote}
1362 % |\IndexEntry|\marg{entry text}\marg{encap}\marg{thenumber}
1363 % \end{quote}
1364 % The \meta{entry text} contains the text for the entry. It is a
1365 % nonempty sequence of commands in which each item is one of
1366 % \begin{quote}
1367 % |\LevelSame|\marg{text}\\
1368 % |\LevelSorted|\marg{sort key}\marg{text}
1369 % \end{quote}
1370 % Each such item specifies one level of the entry that is to be
1371 % written. In the case of |\LevelSorted|, the \meta{text} is what will
1372 % be written in the sorted index at that level and \meta{sort key} is
1373 % a key which the index-sorting program should use for sorting that
1374 % entry at that level. In the case of |\LevelSame|, the \meta{text} is
1375 % used both as sort key and contents of entry in the sorted index.
1376 % The first item is for the topmost level and each subsequent item is
1377 % for the next sublevel. The \meta{entry text} will be fully expanded
1378 % by the |\IndexEntry| command.
1379 %
1380 % \meta{thenumber} is the number (if any) that the index entry refers
1381 % to. It can consist of explicit characters, but it can also be a
1382 % |\the|\meta{counter} control sequence or a macro containing such
1383 % control sequences. \meta{thenumber} is fully expanded by the
1384 % |\IndexEntry| command, with the exception for occurrences of
1385 % |\thepage|---expansion of |\thepage| will instead be delayed until
1386 % the page is shipped out, so that the page numbers will be right.
1387 % \textbf{Note:} \meta{thenumber} must not contain any formatting that
1388 % will upset the index-sorting program. \package{doc}'s default
1389 % definition of |\theCodelineNo| contains such formatting, so one
1390 % must instead use |\thecodelineno| as \meta{thenumber} in that case.
1391 %
1392 % \meta{encap} is the name of the encapsulation scheme that should be
1393 % applied to \meta{thenumber}. All encapsulation schemes that have been
1394 % implemented instruct the index sorting program to wrap up
1395 % \meta{thenumber} in some code that gives it special formatting when
1396 % the sorted index is written, but one could also use the \meta{encap}
1397 % to specify `beginning of range' and `end of range' index entries.
1398 % Use \GenericDescribePrint{\small\texttt{none}}^^A
1399 % \SortIndex{none}{\texttt{none}\encapchar usage}\texttt{none} as
1400 % \meta{encap} if you don't want any special formatting.
1401 %
1402 % \textbf{Note:} |\IndexEntry| uses |\@tempa| internally, so you
1403 % cannot use that in argument \#2 or \#3. Using it in argument \#1
1404 % presents no problems, though.
1405 % \begin{macrocode}
1406 \newcommand\IndexEntry[3]{%
1407 \@bsphack
1408 \begingroup
1409 \def\LevelSame##1{\levelchar##1}%
1410 \def\LevelSorted##1##2{\levelchar##1\actualchar##2}%
1411 \protected@edef\@tempa{#1}%
1412 \protected@edef\@tempa{\expandafter\@gobble\@tempa\@empty}%
1413 \@ifundefined{XD@idxencap@#2}{%
1414 \PackageError{xdoc2}{Index entry encap `#2' unknown}\@eha
1415 }{%
1416 \XD@if@index{%
1417 \csname XD@idxencap@#2\endcsname\@tempa{#3}%
1418 }{}%
1419 }%
1420 \endgroup
1421 \@esphack
1422 }
1423 % \end{macrocode}
1424 % |\IndexEntry| does (like |\index|) not contribute any material to the
1425 % current list if indices aren't being made.
1426 %
1427 % |\XD@if@index| is |\@firstoftwo| if index entries are being written
1428 % and |\@second|\-|of|\-|two| if they are not.
1429 % \begin{macrocode}
1430 \let\XD@if@index=\@secondoftwo
1431 % \end{macrocode}
1432 % \end{macro}\end{macro}\end{macro}\end{macro}
1433 %
1434 % In \LaTeXplus, the \cs{IndexEntry} command should probably be
1435 % implemented using templates, e.g. the \meta{encap}s could be names of
1436 % instances.
1437 %
1438 % \begin{macro}{\levelsame}
1439 % \begin{macro}{\levelsorted}
1440 % These names were used for |\LevelSame| and |\LevelSorted|
1441 % respectively in prototype version~2.0, but the macros should belong
1442 % to the same capitalization class as |\IndexEntry| so their names
1443 % were changed in prototype version~2.1. The old names |\levelsame|
1444 % and |\levelsorted| will continue to work in \package{xdoc2}, though.
1445 % \begin{macrocode}
1446 %<*xdoc2>
1447 \newcommand*\levelsame{\LevelSame}
1448 \newcommand*\levelsorted{\LevelSorted}
1449 %</xdoc2>
1450 % \end{macrocode}
1451 % \end{macro}\end{macro}
1452 %
1453 % \describecsfamily{XD@idxencap@\meta{encap}}^^A
1454 % Macros in the family |\XD@idxencap@|\meta{encap} takes two
1455 % arguments as follows
1456 % \begin{quote}
1457 % |\XD@idxencap@|\meta{encap}\,\marg{entry}\,\marg{thenumber}
1458 % \end{quote}
1459 % They should write an entry with the \meta{encap} encapsulation of the
1460 % \meta{thenumber} to the index file. They need not check whether index
1461 % generation is on or not, but they must be subject to the \LaTeX\ kernel
1462 % \texttt{@filesw} switch. They must expand both arguments fully at the
1463 % time of the command, with the exception for the control sequence
1464 % |\thepage|, which should not be expanded until the page on which the
1465 % write appears is output. Both these conditions are met if the macro
1466 % is implemented using |\protected@write|.
1467 %
1468 % \begin{macro}{\XD@idxencap@none}
1469 % \begin{macro}{\XD@idxencap@main}
1470 % \begin{macro}{\XD@idxencap@usage}
1471 % These macros implement the encapsulation schemes that are used in
1472 % \package{doc}.
1473 % \begin{macrocode}
1474 \def\XD@idxencap@none#1#2{%
1475 \protected@write\@indexfile{}{\XD@index@keyword{#1}{#2}}%
1476 }
1477 % \end{macrocode}
1478 % \begin{macrocode}
1479 \def\XD@idxencap@main#1#2{%
1480 \protected@write\@indexfile{}%
1481 {\XD@index@keyword{#1\encapchar main}{#2}}%
1482 }
1483 % \end{macrocode}
1484 % \begin{macrocode}
1485 \def\XD@idxencap@usage#1#2{%
1486 \protected@write\@indexfile{}%
1487 {\XD@index@keyword{#1\encapchar usage}{#2}}%
1488 }
1489 % \end{macrocode}
1490 % \end{macro}\end{macro}\end{macro}
1491 %
1492 % \begin{macro}{\XD@index@keyword}
1493 % \changes{prot2.2}{2001/02/13}{Macro added and \meta{encap} macros
1494 % changed to use it. (LH)}
1495 % The |\XD@index@keyword| is a hook for changing the index entry
1496 % keyword (the text that is put in front of every index entry in the
1497 % \texttt{.idx} file). It is changed by e.g.\ the \package{docindex}
1498 % package~\cite{docindex}.
1499 % \begin{macrocode}
1500 \@ifundefined{XD@index@keyword}{%
1501 \edef\XD@index@keyword{\@backslashchar indexentry}%
1502 }{}
1503 % \end{macrocode}
1504 % \end{macro}
1505 %
1506 % \begin{macro}{\CodelineIndex}
1507 % \changes{prot2.1}{2000/10/08}{Using \cs{thecodelineno}. (LH)}
1508 % \begin{macro}{\PageIndex}
1509 % \begin{macro}{\TheXDIndexNumber}
1510 % The |\CodelineIndex| and |\PageIndex| commands do the same things as
1511 % in \package{doc}, but work with the \package{xdoc} internals instead
1512 % of the \package{doc} ones. |\TheXDIndexNumber| is used as
1513 % \meta{thenumber} argument to |\IndexEntry| by all indexing commands
1514 % that would have used |\special@index| in \package{doc}.
1515 % \begin{macrocode}
1516 \renewcommand\CodelineIndex{%
1517 \makeindex
1518 \let\XD@if@index=\@firstoftwo
1519 \codeline@indextrue
1520 \def\TheXDIndexNumber{\thecodelineno}%
1521 }
1522 % \end{macrocode}
1523 % \begin{macrocode}
1524 \renewcommand\PageIndex{%
1525 \makeindex
1526 \let\XD@if@index=\@firstoftwo
1527 \codeline@indexfalse
1528 \def\TheXDIndexNumber{\thepage}%
1529 }
1530 % \end{macrocode}
1531 % \begin{macrocode}
1532 \def\TheXDIndexNumber{??}
1533 % \end{macrocode}
1534 % \end{macro}\end{macro}\end{macro}
1535 %
1536 %
1537 % \subsection{Making good sort keys}
1538 %
1539 % \changes{prot2.1}{2000/11/15}{Sort key making commands added. (LH)}
1540 % A common nuisance in \package{doc} indices is that many macros are
1541 % sorted by parts of the name that do not carry any interesting
1542 % information. In the \LaTeX\ kernel many macro names begin with a
1543 % silent |@|, whereas the names of private macros in many packages
1544 % (including this one) begin with some fixed abbreviation of the
1545 % package name. Since such prefixes usually are harder to remember than
1546 % the rest of the macro name, it is not uncommon that the index position
1547 % one thinks of first isn't the one where the macro actually is put.
1548 % Hence a mechanism for removing such annoying prefixes from the macro
1549 % names might be useful, and that is presicely what is defined below.
1550 %
1551 % The actual mechanism is based on having a set of macros called
1552 % \emph{operators} which operate on the harmless character string that
1553 % is to become the sort key. Each operator has a specific prefix string
1554 % which it tries to match against the beginning of the to-be sort key,
1555 % and if they match then the prefix is moved to the end of the sort key.
1556 % Automatically constructed operators (see below) have names of the form
1557 % \describecsfamily{XD@operatorA@\meta{prefix}}|\XD@operatorA@|^^A
1558 % \meta{prefix}, but operators can be given arbitrary names.
1559 %
1560 % \begin{macro}{\XD@operators@list}
1561 % The |\XD@operators@list| macro contains the list of all currently
1562 % active operators.
1563 % \begin{macrocode}
1564 \let\XD@operators@list\@empty
1565 % \end{macrocode}
1566 % \end{macro}
1567 %
1568 % The operators do all their work at expand-time. When an operator
1569 % macro is expanded, it is in the context
1570 % \begin{quote}
1571 % \meta{operator} \meta{subsequent operators} |\@firstofone|
1572 % \meta{sort key text} |\@empty|
1573 % \end{quote}
1574 % There may not be any |\@empty|s or |\@firstofone|s amongst the
1575 % \meta{subsequent operators} or in the \meta{sort key text}. This should
1576 % expand to
1577 % \begin{quote}
1578 % \meta{subsequent operators} |\@firstofone| \meta{operated-on sort
1579 % key text} |\@empty|
1580 % \end{quote}
1581 % The purpose of the |\@firstofone| after the \meta{subsequent
1582 % operators} is to remove any spaces that some operator might have put
1583 % in front of the sort key. This happens if the entire sort key text has
1584 % been ignored by some operator.
1585 %
1586 % \begin{macro}{\MakeSortKey}
1587 % The |\MakeSortKey| command is called to make the acutal sort key.
1588 % The syntax of this command is
1589 % \begin{quote}
1590 % |\MakeSortKey|\marg{macro}\marg{text}\marg{extras}
1591 % \end{quote}
1592 % This locally defines \meta{macro} to be the sort key that the
1593 % currently active operators manufacture from \meta{text}. The
1594 % \meta{extras} argument can contain additional assignments needed for
1595 % handling macros with special harmless forms, such as |\meta|.
1596 % \begin{macrocode}
1597 \newcommand\MakeSortKey[3]{%
1598 \begingroup
1599 \def\PrintChar{\string\PrintChar\XD@threedignum}%
1600 #3%
1601 \unrestored@protected@xdef\@gtempa{#2}%
1602 \endgroup
1603 \protected@edef#1{%
1604 \expandafter\XD@operators@list \expandafter\@firstofone
1605 \@gtempa\@empty
1606 }%
1607 }
1608 % \end{macrocode}
1609 % \end{macro}
1610 %
1611 % \begin{macro}{\XD@make@operator}
1612 % The |\XD@make@operator| macro takes a harmless character sequence as
1613 % argument, constructs the corresponding operator, and returns the
1614 % operator control sequence in the |\toks@| token list register.
1615 %
1616 % More precisely, given a harmless character string \meta{string},
1617 % |\XD@make@operator| will construct a sequence of other tokens
1618 % \meta{text} from \meta{string} by replacing all |\PrintChar|
1619 % commands in the same way as |\MakeSortKey| does. Then it defines the
1620 % macro |\XD@operatorA@|\meta{text} to be
1621 % \begin{quote}
1622 % \raggedright \spaceskip=0.16666em
1623 % \#1\,|\@firstofone|\,\#2\,|\@empty| \ $\rightarrow$ \ %
1624 % |\XD@operatorB@|\meta{text} |\@firstofone| \#2
1625 % |\@firstofone| \meta{text} |\@firstofone| |\relax| \#1 |\@empty|
1626 % \end{quote}
1627 % and the macro |\XD@operatorB@|\meta{text} to do
1628 % \begin{quote}
1629 % \raggedright
1630 % \#1\,|\@firstofone|\,\meta{text}\,\#2\,|\@firstofone|\,\#3\,^^A
1631 % |\relax|\,\#4\,|\@empty| $\rightarrow$
1632 % \#4\,\( \left\{ \begin{array}{ll}
1633 % \mbox{\cs{@firstofone}\,\#2\,\textvisiblespace\,\meta{text}\,^^A
1634 % \cs{@empty}}& \mbox{if \#1 is empty}\\
1635 % \mbox{\#1\,\cs{@empty}}& \mbox{otherwise}
1636 % \end{array} \right.\)
1637 % \end{quote}
1638 %
1639 % \begin{macrocode}
1640 \def\XD@make@operator#1{%
1641 \begingroup
1642 \def\PrintChar{\string\PrintChar\XD@threedignum}%
1643 \let\protect\@gobble
1644 \xdef\@gtempa{#1}%
1645 \endgroup
1646 \expandafter\edef \csname XD@operatorA@\@gtempa\endcsname
1647 ##1\@firstofone##2\@empty{%
1648 \expandafter\noexpand \csname XD@operatorB@\@gtempa\endcsname
1649 \noexpand\@firstofone ##2\noexpand\@firstofone \@gtempa
1650 \noexpand\@firstofone \relax##1\noexpand\@empty
1651 }%
1652 \expandafter\edef \csname XD@operatorB@\@gtempa \expandafter\endcsname
1653 \expandafter##\expandafter1\expandafter\@firstofone \@gtempa
1654 ##2\@firstofone##3\relax##4\@empty{%
1655 \noexpand\ifx $##1$%
1656 \noexpand\expandafter \noexpand\@firstoftwo
1657 \noexpand\else
1658 \noexpand\expandafter \noexpand\@secondoftwo
1659 \noexpand\fi{%
1660 ##4\noexpand\@firstofone ##2 \@gtempa
1661 }{##4##1}%
1662 \noexpand\@empty
1663 }%
1664 \toks@=\expandafter{\csname XD@operatorA@\@gtempa\endcsname}%
1665 }
1666 % \end{macrocode}
1667 % \end{macro}
1668 %
1669 % \begin{macro}{\DoNotIndexBy}
1670 % The |\DoNotIndexBy| command has the syntax
1671 % \begin{quote}
1672 % |\DoNotIndexBy|\marg{morpheme}
1673 % \end{quote}
1674 % It causes the \meta{morpheme} to be put \emph{last} in the index
1675 % sort key for each macro name which begins by \meta{morpheme}. This
1676 % can be used to ignore e.g.\ ``silent'' |@|s at the beginning of a
1677 % macro name.
1678 % \begin{macrocode}
1679 \newcommand\DoNotIndexBy[1]{%
1680 \MakeHarmless\@tempa{#1}%
1681 \XD@make@operator\@tempa
1682 \expandafter\def \expandafter\XD@operators@list \expandafter{%
1683 \the\expandafter\toks@ \XD@operators@list
1684 }%
1685 }
1686 % \end{macrocode}
1687 % \end{macro}
1688 %
1689 %
1690 %
1691 %
1692 % \subsection{Reimplementations of \package{doc} indexing commands}
1693 %
1694 % The \package{doc} indexing commands aren't that interesting in
1695 % \package{xdoc}, since they take `raw' control sequences as
1696 % arguments rather than the harmless strings that the \package{xdoc}
1697 % commands will want to put in the index. But it can be instructive to
1698 % see how they would be implemented in this context.
1699 %
1700 % \begin{macro}{\SortIndex}
1701 % \changes{prot2.2}{2001/02/13}{Redefinition added. (LH)}
1702 % The |\SortIndex| takes a sort key and an entry text as argument, and
1703 % writes a one-level index entry for that.
1704 % \begin{macrocode}
1705 \renewcommand*\SortIndex[2]{%
1706 \IndexEntry{\LevelSorted{#1}{#2}}{none}{\thepage}%
1707 }
1708 % \end{macrocode}
1709 % \end{macro}
1710 %
1711 % \begin{macro}{\SpecialIndex}
1712 % \begin{macro}{\SpecialMainIndex}
1713 % \begin{macro}{\SpecialUsageIndex}
1714 % The |\SpecialIndex|, |\SpecialMainIndex|, and |\SpecialUsageIndex|
1715 % commands take a control sequence (or more often something which looks
1716 % like a |\string|ed control sequence) as their only argument. The
1717 % entry text is that item verbatim, and the initial backslash is
1718 % ignored in sorting (|\Special|\-|Index| always ignores the first
1719 % character regardless of whether it is a backslash or not, the other
1720 % two checks first). |\Special|\-|Index| has \texttt{none} formatting,
1721 % |\Special|\-|Main|\-|Index| has \texttt{main} formatting, and
1722 % |\Special|\-|Usage|\-|Index| has \texttt{usage} formatting of the
1723 % index number.
1724 %
1725 % Although these definitions will (or at least are supposed to) yield
1726 % the same typeset results as the \package{doc} definitions in the
1727 % mainstream cases, I doubt that they will do so in all cases. At any
1728 % rate, they shouldn't perform worse.
1729 % \begin{macrocode}
1730 \renewcommand\SpecialIndex[1]{%
1731 \expandafter\MakeHarmless \expandafter\@tempa
1732 \expandafter{\string#1}%
1733 \IndexEntry{%
1734 \LevelSorted{%
1735 \expandafter\XD@unbackslash \@tempa\@empty
1736 }{\texttt{\@tempa}}%
1737 }{none}{\TheXDIndexNumber}%
1738 }
1739 % \end{macrocode}
1740 % \begin{macrocode}
1741 \renewcommand\SpecialMainIndex[1]{%
1742 \expandafter\MakeHarmless \expandafter\@tempa
1743 \expandafter{\string#1}%
1744 \IndexEntry{%
1745 \LevelSorted{%
1746 \expandafter\XD@unbackslash \@tempa\@empty
1747 }{\texttt{\@tempa}}%
1748 }{main}{\TheXDIndexNumber}%
1749 }
1750 % \end{macrocode}
1751 % \begin{macrocode}
1752 \renewcommand\SpecialUsageIndex[1]{%
1753 \expandafter\MakeHarmless \expandafter\@tempa
1754 \expandafter{\string#1}%
1755 \IndexEntry{%
1756 \LevelSorted{%
1757 \expandafter\XD@unbackslash \@tempa\@empty
1758 }{\texttt{\@tempa}}%
1759 }{usage}{\thepage}%
1760 }
1761 % \end{macrocode}
1762 % \end{macro}\end{macro}\end{macro}
1763 %
1764 % \begin{macro}{\XD@unbackslash}
1765 % \begin{macro}{\XD@unbackslash@}
1766 % |\XD@unbackslash| is a utility macro which removes the first
1767 % character from a harmless character string if that character is a
1768 % backslash (i.e., if it is |\PrintChar{92}|). The \package{doc}
1769 % commands have traditionally used |\@gobble| for doing this, but the
1770 % \cs{@SpecialIndexHelper@} macro that was comparatively recently added
1771 % tries to do better.
1772 % \begin{macrocode}
1773 \def\XD@unbackslash#1{%
1774 \ifx \PrintChar#1%
1775 \expandafter\XD@unbackslash@
1776 \else
1777 \expandafter#1%
1778 \fi
1779 }
1780 \def\XD@unbackslash@#1{\ifnum #1=92 \else \PrintChar{#1}\fi}
1781 % \end{macrocode}
1782 % \end{macro}\end{macro}
1783 %
1784 % \begin{macro}{\SpecialMainEnvIndex}
1785 % \begin{macro}{\SpecialEnvIndex}
1786 % These are similar to the above, but \package{doc} thinks that the
1787 % arguments don't need any special care, and it produces two index
1788 % entries per command. |\Special|\-|Env|\-|Index| should really have
1789 % been called |\Special|\-|Usage|\-|Env|\-|Index|.
1790 % \begin{macrocode}
1791 \renewcommand\SpecialMainEnvIndex[1]{%
1792 \IndexEntry{\LevelSorted{#1}{\texttt{#1} (environment)}}{main}%
1793 {\TheXDIndexNumber}%
1794 \IndexEntry{\LevelSame{environments:}\LevelSorted{#1}{\texttt{#1}}}%
1795 {main}{\TheXDIndexNumber}%
1796 }
1797 % \end{macrocode}
1798 % \begin{macrocode}
1799 \renewcommand\SpecialEnvIndex[1]{%
1800 \IndexEntry{\LevelSorted{#1}{\texttt{#1} (environment)}}{usage}%
1801 {\thepage}%
1802 \IndexEntry{\LevelSame{environments:}\LevelSorted{#1}{\texttt{#1}}}%
1803 {usage}{\thepage}%
1804 }
1805 % \end{macrocode}
1806 % \end{macro}\end{macro}
1807 %
1808 % \begin{macro}{\it@is@a}
1809 % \begin{macro}{\XD@special@index}
1810 % The |\it@is@a| macro is a specialized version of |\SpecialIndex|,
1811 % but the format of its argument is quite different. After full
1812 % expansion the argument will become a single category 12 token
1813 % (\meta{t}, say), and the control sequence for which an entry should
1814 % be made is |\|\meta{t}. \package{doc} uses |\it@is@a| for control
1815 % sequences with one-character names. Note: The following
1816 % definition should really have special code for the \Module{economical}
1817 % \package{docstrip} module, but I don't think that is necessary
1818 % since the \package{doc} macros which used |\it@is@a| will be
1819 % redefined so that they don't.
1820 %
1821 % |\XD@special@index| does the same thing as |\SpecialIndex|, but it
1822 % does it with \package{xdoc} datatypes---the argument must be a
1823 % harmless character string that does not include the initial escape
1824 % (backslash).
1825 % \changes{prot2.1}{2000/11/15}{Using \cs{MakeSortKey} to make the
1826 % sort key. (LH)}
1827 % \begin{macrocode}
1828 \def\it@is@a#1{%
1829 \edef\@tempa{#1}%
1830 \XD@special@index{\csname XD@harmless@\number
1831 \expandafter`\@tempa\endcsname}%
1832 }
1833 % \end{macrocode}
1834 % \begin{macrocode}
1835 \def\XD@special@index#1{%
1836 \MakeSortKey\@tempa{#1}{}%
1837 \IndexEntry{\LevelSorted{\@tempa}{\texttt{\Bslash#1}}}{none}%
1838 {\TheXDIndexNumber}%
1839 }
1840 % \end{macrocode}
1841 % \end{macro}\end{macro}
1842 %
1843 % \begin{macro}{\LeftBraceIndex}
1844 % \begin{macro}{\RightBraceIndex}
1845 % \begin{macro}{\PercentIndex}
1846 % \begin{macro}{\OldMakeIndex}
1847 % More specialised forms of |\SpecialIndex|. The |\OldMakeIndex|
1848 % command can safely be made a no-op.
1849 % \begin{macrocode}
1850 \renewcommand\LeftBraceIndex{\XD@special@index{\PrintChar{123}}}
1851 \renewcommand\RightBraceIndex{\XD@special@index{\PrintChar{125}}}
1852 \renewcommand\PercentIndex{\XD@special@index{\PrintChar{37}}}
1853 \let\OldMakeIndex\relax
1854 % \end{macrocode}
1855 % \end{macro}\end{macro}\end{macro}\end{macro}
1856 %
1857 % \begin{macro}{\@wrindex}
1858 % \changes{prot2.2}{2001/02/13}{Redefinition added. (LH)}
1859 % Finally, while we're at redefining indexing commands, let's redefine
1860 % |\@wrindex| as well to ensure that the index entry keyword is the
1861 % same for all indexing commands.
1862 % \begin{macrocode}
1863 \def\@wrindex#1{%
1864 \protected@write\@indexfile{}{\XD@index@keyword{#1}{\thepage}}%
1865 \endgroup
1866 \@esphack
1867 }
1868 % \end{macrocode}
1869 % \end{macro}
1870 %
1871 %
1872 % \section{Cross-referencing}
1873 %
1874 % \subsection{Scanning \texttt{macrocode} for \TeX\ control sequences}
1875 % \label{Ssec:Scanning macrocode}
1876 %
1877 % The cross-referencing mechanism in \package{doc} isn't problematic in
1878 % the same way as the indexing mechanism is, so one could pretty much
1879 % leave it as it is, but there are things that are better done
1880 % differently when the basic indexing commands are based on harmless
1881 % character strings. Rather than storing control sequence names (without
1882 % escape character) as sequences of category 11 tokens, they will be
1883 % stored as the equivalent harmless character strings.
1884 %
1885 % \begin{macro}{\macro@switch}
1886 % As in \package{doc}, |\macro@switch| determines whether the control
1887 % sequence name that follows consists of letters (call |\macro@name|)
1888 % or a single non-letter (call |\short@macro|). Unlike \package{doc},
1889 % \package{xdoc} accumulates the characters from a multiple-letter
1890 % control sequence name in a token register (|\@toks|), which is why
1891 % that is cleared here.
1892 % \begin{macrocode}
1893 \def\macro@switch{%
1894 \ifcat\noexpand\next a%
1895 \toks@={}%
1896 \expandafter\macro@name
1897 \else
1898 \expandafter\short@macro
1899 \fi
1900 }
1901 % \end{macrocode}
1902 % \end{macro}
1903 %
1904 % \begin{macro}{\scan@macro}
1905 % Since |\macro@namepart| isn't used as in \package{doc}, I might as
1906 % well remove the command that cleared it from |\scan@macro|.
1907 % \begin{macrocode}
1908 \def\scan@macro{%
1909 \special@escape@char
1910 \step@checksum
1911 \ifscan@allowed
1912 \def\next{\futurelet\next\macro@switch}%
1913 \else \let\next\@empty \fi
1914 \next}
1915 % \end{macrocode}
1916 % \end{macro}
1917 %
1918 %
1919 %
1920 % \begin{macro}{\short@macro}
1921 % This macro will be invoked (with a single character as parameter)
1922 % when a single-character macro name has been spotted whilst
1923 % scanning within the \texttt{macrocode} environment. It will produce
1924 % an index entry for that macro, unless that macro has been excluded
1925 % from indexing, and it will also typeset the character that
1926 % constitutes the name of the macro.
1927 % \begin{macrocode}
1928 \def\short@macro#1{%
1929 \protected@edef\macro@namepart{%
1930 %<*economical>
1931 \ifnum `#1<\@xxxii
1932 \noexpand\PrintChar{\number`#1}%
1933 \else\ifnum `#1>126
1934 \noexpand\PrintChar{\number`#1}%
1935 \else
1936 %</economical>
1937 \csname XD@harmless@\number`#1\endcsname
1938 %<economical> \fi\fi
1939 }%
1940 \ifnot@excluded \XD@special@index{\macro@namepart}\fi
1941 % \end{macrocode}
1942 % The cross-referencing mechanism is disabled for when the actual
1943 % character is printed, as it could be the escape character. The index
1944 % entry must be generated before the character is printed to ensure
1945 % that no page break intervenes (recall that a |^^M| will start a new
1946 % line).
1947 % \begin{macrocode}
1948 \scan@allowedfalse #1\scan@allowedtrue
1949 }
1950 % \end{macrocode}
1951 % \end{macro}
1952 %
1953 % There is one mechanism in |\TeX|'s control sequence tokenization that
1954 % |\short@|\B|macro| doesn't cover, and that is the |^^| sequence
1955 % substitution---|\^^M| is (with default catcodes) seen as the three
1956 % tokens |\^|, |^|, and |M|, not as the single control
1957 % sequence token that \TeX\ will make out of it. But this is the way it
1958 % is done in \package{doc}.
1959 %
1960 %
1961 % \begin{macro}{\macro@name}
1962 % \begin{macro}{\more@macroname}
1963 % \begin{macro}{\macro@finish}
1964 % Then there's the macros for assembling a control sequence name which
1965 % consists of one or more letters (category 11 tokens). (This includes
1966 % both the characters which are normally letters in the document and
1967 % those that are made letters by |\MakePrivateLetters|.) They're
1968 % pretty straightforward.
1969 % \begin{macrocode}
1970 \def\macro@name#1{%
1971 %<*economical>
1972 \if \ifnum `#1<\@xxxii 1\else \ifnum `#1>126 1\else 0\fi\fi 1%
1973 \toks@=\expandafter{\the\expandafter\toks@
1974 \expandafter\PrintChar \expandafter{\number`#1}%
1975 }%
1976 \else
1977 %</economical>
1978 \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
1979 \csname XD@harmless@\number`#1\endcsname}%
1980 %<economical> \fi
1981 \futurelet\next\more@macroname}
1982 % \end{macrocode}
1983 % \begin{macrocode}
1984 \def\more@macroname{%
1985 \ifcat\noexpand\next a%
1986 \expandafter\macro@name
1987 \else
1988 \macro@finish
1989 \fi
1990 }
1991 % \end{macrocode}
1992 % \begin{macrocode}
1993 \def\macro@finish{%
1994 \edef\macro@namepart{\the\toks@}%
1995 \ifnot@excluded \XD@special@index{\macro@namepart}\fi
1996 \macro@namepart
1997 }
1998 % \end{macrocode}
1999 % \end{macro}\end{macro}\end{macro}
2000 %
2001 %
2002 %
2003 % \subsection{The index exclude list}
2004 % \label{Ssec:Index-exclude}
2005 %
2006 % The index exclude list mechanisms are not quite as simple to convert
2007 % for use with harmless character strings as the construction of macro
2008 % names are. This is because the trick used for searching the exclude
2009 % list for a certain string doesn't work if the string one is looking
2010 % for contains tokens with category 1 or 2 (beginning and end of group),
2011 % as the \meta{parameter text} of a |\def| cannot contain such tokens.
2012 % On the other hand the only groups that can appear in the harmless
2013 % character strings one will be looking for are the ones around the
2014 % argument of some |\PrintChar|, and these can easily be converted to
2015 % something else. Therefore an item in the index exclude list of
2016 % \package{xdoc} will have the format
2017 % \begin{quote}
2018 % |\do|\,\meta{string}
2019 % \end{quote}
2020 % where the \meta{string} is different from a harmless character string
2021 % only in that all |\PrintChar|\marg{num} have been replaced by
2022 % |\PrintChar|\parg{num}. The \meta{string} does not include an escape
2023 % character. The |\do| serves only to separate the item from the one
2024 % before, but it could in principle be used for other purposes as well
2025 % (such as in typesetting the entire exclude list).
2026 %
2027 % \begin{macro}{\XD@paren@PrintChar}
2028 % |\XD@paren@PrintChar| is a definition of |\PrintChar| which, when it
2029 % is used in an |\edef|, merely replaces the group around the argument
2030 % by a parenthesis and normalizes the number in the argument.
2031 % \changes{prot2.1}{2000/09/16}{\cs{number} added. (LH)}
2032 % \begin{macrocode}
2033 \def\XD@paren@PrintChar#1{\noexpand\PrintChar(\number#1)}
2034 % \end{macrocode}
2035 % \end{macro}
2036 %
2037 % \begin{macro}{\DoNotIndex}
2038 % \changes{prot2.1}{2000/09/16}{Also changing catcode of \%. (LH)}
2039 % \begin{macro}{\do@not@index}
2040 % \begin{macro}{\XD@do@not@index}
2041 % These are the macros which add elements to the index exclude list.
2042 % |\DoNotIndex| is pretty much as in \package{doc}, but I have added
2043 % resetting of the catcodes of `|,|' (since |\XD@do@not@index| relies
2044 % on it) and `|#|' (since it can otherwise mess things up for the
2045 % |\def\@tempa| in |\do@not@index|).
2046 % \begin{macrocode}
2047 \renewcommand\DoNotIndex{%
2048 \begingroup
2049 \MakePrivateLetters
2050 \catcode`\#=12\catcode`\\=12\catcode`,=12\catcode`\%=12
2051 \expandafter\endgroup \do@not@index
2052 }
2053 % \end{macrocode}
2054 %
2055 % |\do@not@index|, on the other hand, is quite different, as it more
2056 % or less has to convert the argument from the format used in
2057 % \package{doc} to that of \package{xdoc}. The bulk of the work is
2058 % done by |\XD@do@not@index|, which grabs one of the elements in the
2059 % argument of |\do@not@index| and converts it (minus the initial
2060 % backslash) to a harmless character string. That harmless character
2061 % string is then converted by |\XD@paren@PrintChar|, so that the
2062 % string can be searched for using |\expanded@notin|.
2063 %
2064 % The reason for using a special loop structure here, as opposed to
2065 % using for example |\@for|, is that one cannot use either of |\|
2066 % or |,| alone as item separators, as they may both be part of control
2067 % sequence names (consider for example |\DoNotIndex{\a,\\,\b,\,,\c}|),
2068 % but they should be sufficient when combined.
2069 %
2070 % The reason for storing new elements in |\toks@| until the end of
2071 % the loop and only then inserting them into the index exclude list
2072 % is speed; the index exclude list can get rather large, so you don't
2073 % want to expand it more often than you have to. I don't know if the
2074 % difference is noticeable, though.
2075 % \begin{macrocode}
2076 \begingroup
2077 \catcode`\|=0
2078 \catcode`\,=12
2079 \catcode`\\=12
2080 % \end{macrocode}
2081 % \SpecialEscapechar{\|}
2082 % \begin{macrocode}
2083 |gdef|do@not@index#1{%
2084 |def|@tempa{#1}%
2085 |ifx |@empty|@tempa |else
2086 |toks@={}%
2087 |expandafter|XD@do@not@index |@gobble #1,\|XD@do@not@index,\%
2088 |fi
2089 }
2090 |gdef|XD@do@not@index#1,\{%
2091 |ifx |XD@do@not@index#1%
2092 |index@excludelist=|expandafter{%
2093 |the|expandafter|index@excludelist |the|toks@
2094 }%
2095 |expandafter|@gobble
2096 |else
2097 |MakeHarmless|@tempa{#1}%
2098 |begingroup
2099 |let|PrintChar|XD@paren@PrintChar
2100 |unrestored@protected@xdef|@gtempa{|noexpand|do|@tempa}%
2101 |endgroup
2102 |toks@=|expandafter{|the|expandafter|toks@ |@gtempa}%
2103 |fi
2104 |XD@do@not@index
2105 }
2106 |endgroup
2107 % \end{macrocode}
2108 % \end{macro}\end{macro}\end{macro}
2109 %
2110 % \begin{macro}{\DoNotIndexHarmless}
2111 % The |\DoNotIndexHarmless| command takes a harmless character string
2112 % as argument and locally adds the control sequence whose name is that
2113 % character string to the index exclude list.
2114 % \begin{macrocode}
2115 \newcommand\DoNotIndexHarmless[1]{%
2116 \begingroup
2117 \let\PrintChar\XD@paren@PrintChar
2118 \unrestored@protected@xdef\@gtempa{\noexpand\do#1}%
2119 \endgroup
2120 \index@excludelist=\expandafter{%
2121 \the\expandafter\index@excludelist \@gtempa
2122 }%
2123 }
2124 % \end{macrocode}
2125 % \end{macro}
2126 %
2127 % \begin{macro}{\index@excludelist}
2128 % In case the index exclude list is not empty, its contents are
2129 % converted to \package{xdoc} format.
2130 % \begin{macrocode}
2131 \edef\@tempa{\the\index@excludelist}
2132 \index@excludelist{}
2133 \ifx \@tempa\@empty \else
2134 \def\@tempb#1,\@nil{\do@not@index{#1}}
2135 \expandafter\@tempb \@tempa \@nil
2136 \let\@tempa\@empty
2137 \let\@tempb\@empty
2138 \fi
2139 % \end{macrocode}
2140 % The fact that the |\XD@|\B|harmless@|\B\meta{code} table has not
2141 % yet reached its final form means that some of these control sequences
2142 % listed in the exclude list might get a different form here than they
2143 % actually should, but there isn't much that can be done about that. It
2144 % is furthermore unusual that control sequence are given such names
2145 % that they would be affected by this.
2146 % \end{macro}
2147 %
2148 % \begin{macro}{\ifnot@excluded}
2149 % The |\ifnot@excluded| macro ultimately boils down to an
2150 % \texttt{if}, which evaluates to true if and only if the string in
2151 % |\macro@namepart| is not one of the items in the index exclude
2152 % list. Before |\expanded@notin| gets to carry out the actual test,
2153 % the |\PrintChar| calls in |\macro@namepart| are converted by
2154 % |\XD@paren@PrintChar| (it's OK to use an unprotected |\edef| for
2155 % this, since |\PrintChar| is the only control sequence that can
2156 % appear in |\macro@namepart|) so that |\expanded@notin| can be used
2157 % to test for its presence.
2158 % \begin{macrocode}
2159 \def\ifnot@excluded{%
2160 \begingroup
2161 \let\PrintChar\XD@paren@PrintChar
2162 \edef\@tempa{\macro@namepart}%
2163 \expandafter\endgroup \expandafter\expanded@notin
2164 \expandafter{\expandafter\do \@tempa\do}%
2165 {\the\index@excludelist}%
2166 }
2167 % \end{macrocode}
2168 % \end{macro}
2169 %
2170 %
2171 % \subsection{External cross-referencing}
2172 % \label{Ssec:XXR}
2173 %
2174 % (This subsection is a bit speculatory, but I think the structures it
2175 % describes may come in handy.)
2176 %
2177 % \changes{prot2}{2000/07/31}{I finally decided that it would be better
2178 % to make the XXR-commands look like comments to \TeX. (LH)}
2179 %
2180 % It's rather easy to write macros for scanning \TeX\ code for the names
2181 % of control sequences---just look for the escape (category 0)
2182 % character, and whatever follows is the name of a control sequence.
2183 % Doing the same thing for other languages may lay anywhere between
2184 % ``a~tricky exercise in advanced \TeX\ programming'' and ``possible in
2185 % theory'',\footnote{I.e., you know it can be implemented as a computer
2186 % program (in some language), you know that any computer program can be
2187 % translated to a Turing machine (or if you prefer that, expressed in
2188 % lambda calculus), and you know that a Turing machine can be emulated
2189 % by \TeX, but that's the closest thing to a solution you've managed to
2190 % come up with.} but in most cases the available solutions turn out to be
2191 % too complicated and\slash or slow to be of practical use. When that
2192 % happens, one might instead want to use some external piece of software
2193 % for doing the cross-referencing.
2194 %
2195 % The commands in this subsection implement basic support for such an
2196 % external cross-referencing program (or XXR,\footnote{Maybe not the
2197 % most logical name, but it looks much cooler than ECR.} for short). The
2198 % idea is that an XXR should communicate with \LaTeX\ like \BibTeX\
2199 % does---scan the \texttt{.aux} file (or files, if we're |\include|ing
2200 % things) for certain ``commands'' and use them to locate the files to
2201 % cross-reference, get parameter settings (like for example entries for
2202 % the index exclude list), and so on. It should then cross-reference the
2203 % file(s) and write the index entries in a suitable format to some file
2204 % (appending them to the \texttt{.idx} file is probably the easiest
2205 % solution). This way, it is (almost) as simple to use as the built-in
2206 % cross-referencing and the extra work for supporting it is (in
2207 % comparison to not supporting it) negligible.
2208 %
2209 % \begin{xrefcmd}{ExternalXRefMsg}
2210 % \begin{macro}{\SendExternalXRefMsg}
2211 % \changes{prot2}{2000/07/28}{Added \cs{if@filesw} test. (LH)}
2212 % It's hardly possible to predict all kinds of information that one
2213 % might want to give to an XXR, and neither can one assume that
2214 % there is only one XXR program that will read the \texttt{.aux}
2215 % file. A complicated project might involve code in several languages,
2216 % and each language might have its own XXR.
2217 % Therefore the general XXR-command (text in an \texttt{.aux} file which
2218 % is used for communicating information to an XXR) simply has the syntax
2219 % \begin{quote}
2220 % \verb*|%%ExternalXRefMsg |\marg{who}\verb*| |\marg{what}
2221 % \end{quote}
2222 % \meta{who} identifies the XXR this message is meant for. It must be
2223 % balanced text to \TeX\ and may not contain any whitespace, but can
2224 % otherwise be rather arbitrary. \meta{what} is the actual message. It
2225 % too must be balanced text to \TeX\ and it may not contain any
2226 % newlines, but it is otherwise arbitrary.
2227 % \index{whitespace restrictions}^^A
2228 % The reason for these restrictions on the contents of \meta{who} and
2229 % \meta{what} is that many (maybe even most) scripting languages
2230 % (which is what at least the \texttt{.aux}-scanning part of an
2231 % XXR will probably be written in) are much better at recognising
2232 % words on a line than they are at recognising a brace-delimited group.
2233 % By accepting these restrictions, one can make sure that all XXRs can
2234 % correctly determine whether a message is for them, even if they see
2235 % the \texttt{.aux} file as a sequence of lines composed of
2236 % whitespace-delimited words.
2237 %
2238 % |\SendExternalXRefMsg| is the basic command for writing
2239 % |ExternalXRefMsg|s to the \texttt{.aux} file, but it might be
2240 % recommendable that XXR writers provide users with a set of commands
2241 % that have more specific purposes. The syntax of the
2242 % |\Send|\-|External|\-|XRef|\-|Msg| command is (hardly surprising)
2243 % \begin{quote}
2244 % |\SendExternalXRefMsg|\marg{who}\marg{what}
2245 % \end{quote}
2246 % |\SendExternalXRefMsg| does a protected full expansion (like
2247 % |\protected@edef|) of its arguments at the time it is called.
2248 % \begin{macrocode}
2249 \newcommand\SendExternalXRefMsg[2]{%
2250 \begingroup
2251 \if@filesw
2252 \let\protect\@unexpandable@protect
2253 \immediate\write\@auxout{\@percentchar\@percentchar
2254 ExternalXRefMsg {#1} {#2}}%
2255 \fi
2256 \endgroup
2257 }
2258 % \end{macrocode}
2259 % \end{macro}\end{xrefcmd}
2260 %
2261 % The remaining commands in this subsection address complications that
2262 % exist because of how \texttt{.dtx} files are generally written, and
2263 % thus constitutes difficulties that all XXRs will have to face.
2264 %
2265 % \begin{xrefcmd}{ExternalXRefFile}
2266 % The usual way to write \texttt{.dtx} files is to include a
2267 % driver---a~short piece of uncommented \LaTeX\ code which contains
2268 % the necessary preamble material and a document body which mainly
2269 % contains a |\DocInput| for the \texttt{.dtx} file itself---but it
2270 % is also usually understood that this driver may be copied to another
2271 % file if necessary and larger projects usually have a completely
2272 % separate driver file. Therefore an XXR cannot be expected to be
2273 % able to find the file(s) to cross-reference simply by changing
2274 % suffix on the name of the \texttt{.aux} file it reads its commands
2275 % from. A more intricate method must be used.
2276 %
2277 % To tell the XXR that ``here I input the file \dots'', one includes
2278 % an |External|\-|XRef|\-|File| XXR-command in the \texttt{.aux} file.
2279 % Its syntax is
2280 % \begin{quote}
2281 % \verb*|%%ExternalXRefFile |\marg{cmd}\verb*| |\marg{file}^^A
2282 % \verb*| |\marg{what}
2283 % \end{quote}
2284 % \meta{file} is the name (as given to |\input| or the like) of the
2285 % file to input. \meta{cmd} is either \texttt{begin} (begin of
2286 % \meta{file}) or \texttt{end} (end of \meta{file}). \meta{what} is a
2287 % declaration of what is in the file; XXRs should use it to determine
2288 % whether they should process this file or not. \meta{what} is empty
2289 % if all XXRs should process the file, but for example |\IndexInput|
2290 % will put \texttt{TeX} here to declare that the contents of this file
2291 % are \TeX\ code and only XXRs that cross-reference \TeX\ code need to
2292 % process this file.
2293 %
2294 % In connection to this, it should be mentioned that XXRs must also look
2295 % for (and act on) |\@input|\penalty\hyphenpenalty\marg{auxfile} commands
2296 % that |\include| or |\DocInclude| has written to the \texttt{.aux} file,
2297 % since these \meta{auxfile}s can also contain commands for the XXR
2298 % that should result in output to the same \texttt{.idx} file. In
2299 % particular, the |ExternalXRefFile| XXR-commands that are written
2300 % because of a |\DocInclude| will be written to such an \meta{auxfile}.
2301 % \end{xrefcmd}
2302 %
2303 % \begin{xrefcmd}{ExternalXRefSync}
2304 % Most XXRs will probably find it an unreasonable task to keep exact
2305 % track of all codelines in all documents, i.e., they will sometimes
2306 % think that a piece of code contains more or fewer numbered
2307 % codelines than it actually does. If for example a document contains
2308 % code such as\iffalse
2309 %<*example>
2310 % \fi
2311 %\begin{verbatim}
2312 %% \iffalse
2313 %% \begin{macrocode}
2314 %Etaoin Shrldu
2315 %% \end{macrocode}
2316 %% \fi
2317 %\end{verbatim}\iffalse
2318 %</example>
2319 %\fi
2320 % then all reasonable XXRs will probably be fooled into thinking that
2321 % the \texttt{Etaoin Shrldu} line is a numbered codeline. This would
2322 % of course be very bad if an XXR thought it should cross-reference
2323 % the contents of this line, but that shouldn't usually be a problem
2324 % since the specifications\footnote{I imagine these specifications
2325 % will consist of a list of \package{docstrip} options (modules),
2326 % possibly used in combination with restrictions on the names of
2327 % surrounding environments.} of what code should be cross-referenced
2328 % will probably make it clear that the above line should not be
2329 % cross-referenced. Code such as the above will still be problematic
2330 % however, as it will cause the XXR to believe that the
2331 % \texttt{codelineno} counter has another value on any following
2332 % line that is indexed than it actually has in the typeset
2333 % document. This will cause index entries to refer to another line
2334 % than it actually should.
2335 %
2336 % To overcome this, the |ExternalXRefSync| XXR-command can be used to
2337 % tell the XXR what the corresponding values of |\inputlineno| and
2338 % \texttt{codelineno} are. Its syntax is
2339 % \begin{quote}
2340 % \verb*|%%ExternalXRefSync |\marg{inputlineno}\verb*| |^^A
2341 % \marg{codelineno}
2342 % \end{quote}
2343 % where \meta{inputlineno} is the expansion of |\the\inputlineno| and
2344 % \meta{codelineno} is the expansion of |\thecodelineno|, both
2345 % expanded at the same point in the program. Note here that the first
2346 % line of a file is line number 1, that line number 0 is used to
2347 % denote ``just before the first line'', and that \texttt{codelineno}
2348 % gets increased immediately before the number is typeset (i.e.,
2349 % \texttt{codelineno} contains the number of the last numbered
2350 % codeline).
2351 % \end{xrefcmd}
2352 %
2353 % This doesn't support external cross-referencing by pages, since doing
2354 % that requires that the document outputs a lot more information to the
2355 % \texttt{.aux} file. In principle, one could put a |\mark|\penalty0
2356 % |{\thecodelineno}| in |\PrintCodelineNo| and a |\write| in the page
2357 % header which outputs to the \texttt{.aux} file which range of
2358 % codelines correspond to a given page, but the \LaTeXe\ sectioning
2359 % commands' use of marks tends to interfere with this. The \LaTeXplus\
2360 % package \package{xmarks} will probably solve that problem, though.
2361 %
2362 % \begin{macro}{\syncexternalxref}
2363 % \changes{prot2}{2000/07/28}{New name for \cs{SendExternalXRefSync}.
2364 % Also added \cs{if@filesw} test. (LH)}
2365 % ^^A Johann Sebastian Bach: 1685/03/21--1750/07/28
2366 % The |\syncexternalxref| command writes an |ExternalXRefSync|
2367 % XXR-command for the current line number and value of the
2368 % \texttt{codelineno} counter to \texttt{.aux} file. It is used for
2369 % synchronizing the numbered codeline counter that an XXR maintains with
2370 % the \texttt{codelineno} counter that is used for numbering codelines
2371 % in the typeset document after a piece of code in the document that
2372 % some XXR is likely to misinterpret. |\sync|\-|external|\-|xref|
2373 % shouldn't be used inside \texttt{macrocode} environments (or the
2374 % like) as they tend to read ahead in the file---instead it is best
2375 % placed shortly after such an environment. |\sync|\-|external|\-|xref|
2376 % has no arguments.
2377 % \begin{macrocode}
2378 \newcommand\syncexternalxref{%
2379 \if@filesw
2380 \immediate\write\@auxout{\@percentchar\@percentchar
2381 ExternalXRefSync {\the\inputlineno} {\thecodelineno}%
2382 }%
2383 \fi
2384 }
2385 % \end{macrocode}
2386 % \end{macro}
2387 %
2388 % \begin{xrefcmd}{ExternalXRefWrap}
2389 % The |\DocInclude| command complicates matters for XXRs by redefining
2390 % things so that the \texttt{codelineno} counter only makes up a part
2391 % of the line numbers appearing in the index. The purpose of the
2392 % |External|\-|XRef|\-|Wrap| XXR-command is to inform XXRs about such
2393 % changes. The command
2394 % \begin{quote}
2395 % \verb*|%%ExternalXRefWrap {|\meta{prefix}\verb*|} {|^^A
2396 % \meta{suffix}|}|
2397 % \end{quote}
2398 % means that codeline numbers written to the index should have the form
2399 % \begin{quote}
2400 % \meta{prefix}\meta{codelineno}\meta{suffix}
2401 % \end{quote}
2402 % This setting takes effect from the next |External|\-|XRef|\-|Sync|
2403 % and stays in effect until the end of the document or until another
2404 % |External|\-|XRef|\-|Wrap| overrides it. The state at the beginning
2405 % of the document is to have both \meta{prefix} and \meta{suffix}
2406 % empty.
2407 % \end{xrefcmd}
2408 %
2409 %
2410 % \begin{macro}{\XD@input}
2411 % The |\XD@input| command is a version of |\input| which takes care
2412 % to inform XXRs that another file is being |\input|ted. Its syntax is
2413 % \begin{quote}
2414 % |\XD@input|\marg{file}\marg{what}
2415 % \end{quote}
2416 % where \meta{file} is the name of the file to |\input| and \meta{what}
2417 % is the contents of the file, as specified in
2418 % |External|\-|XRef|\-|File| commands.
2419 % \begin{macrocode}
2420 \def\XD@input#1#2{%
2421 \if@filesw
2422 \immediate\write\@auxout{\@percentchar\@percentchar
2423 ExternalXRefFile {begin} {#1} {#2}%
2424 }%
2425 \immediate\write\@auxout{\@percentchar\@percentchar
2426 ExternalXRefSync {0} {\thecodelineno}%
2427 }%
2428 \fi
2429 \input{#1}%
2430 \if@filesw
2431 \immediate\write\@auxout{\@percentchar\@percentchar
2432 ExternalXRefFile {end} {#1} {#2}%
2433 }%
2434 \immediate\write\@auxout{\@percentchar\@percentchar
2435 ExternalXRefSync {\the\inputlineno} {\thecodelineno}%
2436 }%
2437 \fi
2438 }
2439 % \end{macrocode}
2440 % \end{macro}
2441 %
2442 % \begin{macro}{\DocInput}
2443 % The |\DocInput| command is redefined so that it writes
2444 % |External|\-|XRef|\-|File| and |External|\-|XRef|\-|Sync| XXR-commands
2445 % to the \texttt{.aux} file. Furthermore, with \package{xdoc} one
2446 % should always use the |\DocInput| command (or some command based on
2447 % it, like |\DocInclude|) for inputting a file where percent is an
2448 % `ignore' character---even when one such file inputs another. (Doing
2449 % that didn't work with the \package{doc} definition, as it always
2450 % called |\MakePercentComment| upon return, but the \package{xdoc}
2451 % definition contains code for dealing with that.)
2452 % \begin{macrocode}
2453 \renewcommand\DocInput[1]{%
2454 \relax
2455 \ifnum \catcode`\%=14
2456 \expandafter\@firstoftwo
2457 \else
2458 \expandafter\@secondoftwo
2459 \fi{%
2460 \MakePercentIgnore\XD@input{#1}{}\MakePercentComment
2461 }{\XD@input{#1}{}}%
2462 }
2463 % \end{macrocode}
2464 % \end{macro}
2465 %
2466 % \begin{macro}{\IndexInput}
2467 % The |\IndexInput| command also needs to be redefined to write
2468 % XXR-commands to the \texttt{.aux} file. It would
2469 % probably be enough here to write an |External|\-|XRef|\-|Sync|
2470 % after the file has been |\input| since no external
2471 % cross-referencing of |\IndexInput|ted files is needed, but I do the
2472 % more verbose variant here just to exemplify how these things would
2473 % look for other languages.
2474 % \begin{macrocode}
2475 \renewcommand\IndexInput[1]{%
2476 \begingroup
2477 \macro@code
2478 \frenchspacing
2479 \@vobeyspaces
2480 \XD@input{#1}{TeX}%
2481 \endmacrocode
2482 \endgroup
2483 }
2484 % \end{macrocode}
2485 % \end{macro}
2486 %
2487 %
2488 %
2489 % \section{Two-sided printing}
2490 % \label{Sec:Twoside}
2491 %
2492 % The main problem one faces when reimplementing \package{doc} so that
2493 % the marginal material always appears in the outer margin in two-sided
2494 % documents is that the justification of \package{doc}'s marginal
2495 % material is asymmetric; it always extends outwards. This means that
2496 % the justification to use when typesetting the marginal material must
2497 % depend on whether it is to be put on a left or a right
2498 % page---something which cannot be determined for sure when the
2499 % material is typeset! This is a minor difficulty if the marginal material
2500 % is put in place using \LaTeX's |\marginpar| command, as that allows the
2501 % user to supply different versions of the marginal paragraph for left and
2502 % right margin placements. It is however a major difficulty if the
2503 % marginal material is displaced out into the margin from within the main
2504 % galley (like the \texttt{macro} environment of \package{doc} does),
2505 % since the output routine is never involved.
2506 %
2507 % Even though this difficulty provides arguments for using a |\marginpar|
2508 % mechanism for all text that is put in the margin, that will not be
2509 % done in \package{xdoc} (but maybe it will in some successor).
2510 % Instead \package{xdoc} contains a general mechanism which uses data
2511 % written to the \texttt{.aux} file for determining whether a piece of
2512 % text was put on an odd or even numbered page the \emph{last} time the
2513 % document was typeset. By the usual convergence of page breaks in a
2514 % \LaTeX\ document, this will eventually produce a typeset document
2515 % with the marginal material consistently in the outer margin.
2516 %
2517 % The mechanism works as follows. The places in the document (the
2518 % document source) at which it is necessary to determine whether
2519 % something is going to appear on an even (left) or an odd (right) page
2520 % are called ``page situations''\footnote{I know it's not a particularly
2521 % good name. Suggestions for better names are gracefully accepted.} or
2522 % just ``situations''. In each situation, a relatively simple test (is
2523 % the \texttt{page} counter currently even or odd?) which is right more
2524 % often than not is used as a first guess, and both the guess, the
2525 % placement actually used, and the correct answer (determined from the
2526 % value of \texttt{page} when the piece of text is shipped out) are
2527 % recorded in the \texttt{.aux} file. If the guess (for the current
2528 % situation) coincided with the correct answer the last time the
2529 % document was typeset then the guess determined now is used, otherwise
2530 % the opposite of the guess determined now is used. Finally, when at
2531 % |\end{document}| the \texttt{.aux} file is inputted to check for
2532 % changed labels, the placements used are also checked and the user is
2533 % given a suitable warning if there was an incorrect one.
2534 %
2535 % \begin{macro}{\IfOddPageSituation}
2536 % The |\IfOddPageSituation| macro is the user level test for whether
2537 % the current page situation appears on an odd or an even page. It
2538 % has the syntax
2539 % \begin{quote}
2540 % |\IfOddPageSituation|\marg{odd}\marg{even}
2541 % \end{quote}
2542 % and this will expand to \meta{odd} if the current situation is
2543 % expected to end up on an odd page (based on how correct it was to
2544 % look at the value of \texttt{page} last time) and to \meta{even}
2545 % otherwise. In single-sided mode, it always expands to \meta{even}.
2546 % In two-sided mode, |\IfOddPageSituation| is redefined for the new
2547 % situation each time |\StepPageSituation| is called.
2548 % \begin{macrocode}
2549 \let\IfOddPageSituation=\@secondoftwo
2550 % \end{macrocode}
2551 % \end{macro}
2552 %
2553 % \begin{macro}{\StepPageSituation}
2554 % \changes{prot2.1}{2000/12/19}{Now also setting
2555 % \cs{IfOddPageSituation}, instead of having that macro performing
2556 % the test each time it is used. This fixes a rarely occuring bug
2557 % which occurs when a page is shipped out between
2558 % \cs{StepPageSituation} and a corresponding
2559 % \cs{IfOddPageSituation}. (LH)}
2560 % \begin{macro}{\macro@cnt}
2561 % \begin{macro}{\XD@next@wrong}
2562 % \begin{macro}{\XD@wrongs@list}
2563 % The |\StepPageSituation| command is called to inform the page
2564 % situation mechanism that a new situation has begun. The rule for
2565 % when you need to use |\Step|\-|Page|\-|Situation| is simple: if you
2566 % use |\IfOdd|\-|Page|\-|Situation| in two places which may end up on
2567 % different pages, then there must be a |\Step|\-|Page|\-|Situation|
2568 % between them. There is no code which automatically calls
2569 % |\Step|\-|Page|\-|Situation|---not even |\clearpage| or other
2570 % macros which force page breaks do this---hence macros which use
2571 % the page situation mechanism must always call |\Step|\-|Page|\-^^A
2572 % |Situation| explicitly when a new situation begins.
2573 %
2574 % Since the |\macro@cnt| count register isn't used for stacking
2575 % marginal headings (``macro'' names) anymore (see below), it is
2576 % employed for enumerating page situation. |\XD@next@wrong| is a macro
2577 % which contains the number of the next situation in which the guess
2578 % was wrong last time. Unless |\XD@next@wrong|${}={}$|\macro@cnt|, the
2579 % guess was right last time. All assignments to |\macro@cnt| and
2580 % |\XD@next@wrong| are global.
2581 %
2582 % |\XD@wrongs@list| is a list of all the wrong guesses. It has the
2583 % syntax
2584 % \begin{quote}
2585 % |\@elt|\marg{guess no.}|\@elt|\marg{guess no.}\dots
2586 % |\@elt|\marg{guess no.}
2587 % \end{quote}
2588 % where the \meta{guess no.}s are the numbers of the wrong guesses, in
2589 % increasing order. The contents of |\XD@wrongs@list| are collected
2590 % when the \texttt{.aux} file is inputted at |\begin|\B|{document}|,
2591 % and they are removed again as \TeX\ passes the situation in the
2592 % document that they apply to. All assignments to |\XD@wrong@list| are
2593 % global.
2594 %
2595 % Calling |\StepPageSituation| increases |\macro@cnt| by one,
2596 % updates |\XD@|\B|next@|\B|wrong| and |\XD@|\B|wrong@|\B|list|
2597 % appropriately, and sets |\IfOdd|\B|Page|\B|Situation| to
2598 % |\@firstoftwo| or |\@secondoftwo| (whichever is correct for this
2599 % situation). |\@next| is a list management macro from the \LaTeX\
2600 % kernel.
2601 % \begin{macrocode}
2602 \if@twoside
2603 \def\StepPageSituation{%
2604 \global\advance \macro@cnt \@ne
2605 \ifnum \XD@next@wrong<\macro@cnt
2606 \global\@next\XD@next@wrong\XD@wrongs@list{}{%
2607 \let\XD@next@wrong\maxdimen
2608 }%
2609 \fi
2610 \ifnum \ifodd\c@page -\fi \@ne=%
2611 \ifnum \XD@next@wrong=\macro@cnt -\fi \@ne
2612 \global\let\IfOddPageSituation\@secondoftwo
2613 \else
2614 \global\let\IfOddPageSituation\@firstoftwo
2615 \fi
2616 }
2617 \def\XD@next@wrong{-\maxdimen}
2618 \let\XD@wrongs@list\@empty
2619 \else
2620 \let\StepPageSituation=\relax
2621 \fi
2622 % \end{macrocode}
2623 % \end{macro}\end{macro}\end{macro}\end{macro}
2624 %
2625 %
2626 % \begin{macro}{\RecordPageSituation}
2627 % The |\RecordPageSituation| command generates a |\write| whatsit node
2628 % which records the outcome of the current page situation. It is the
2629 % location of this whatsit node that determines on which page a
2630 % certain situation is considered to occur. If you don't execute this
2631 % macro for a certain page situation, the first guess will always be
2632 % used for that situation and no warnings will be given if that guess
2633 % is incorrect. In single-sided mode, this is a no-op (thus you should
2634 % better place it somewhere where it doesn't affect spacing).
2635 % Furthermore you must make sure that \TeX\ does not change the value
2636 % of the \texttt{page} counter between a |\StepPageSituation| and its
2637 % corresponding |\RecordPageSituation|, since the |\ifodd| test must
2638 % yield the same result in both cases.
2639 %
2640 % \begin{macrocode}
2641 \if@twoside
2642 \def\RecordPageSituation{%
2643 \if@filesw
2644 \edef\@tempa{%
2645 \string\XD@situation{\the\macro@cnt}{%
2646 \ifodd\c@page 1\else 0\fi
2647 }{\IfOddPageSituation{1}{0}}%
2648 }%
2649 \write\@auxout\expandafter{\@tempa{\ifodd\c@page 1\else 0\fi}}%
2650 \fi
2651 }%
2652 \else
2653 \let\RecordPageSituation=\relax
2654 \fi
2655 % \end{macrocode}
2656 % \end{macro}
2657 %
2658 %
2659 % \begin{macro}{\XD@situation}
2660 % \changes{prot2}{2000/07/13}{Changed to allow multiple
2661 % \cs{XD@situation} commands for the same situation. This is
2662 % necessary for coping with documents which \cs{include} files. (LH)}
2663 % \changes{prot2}{2000/07/26}{Made redefinition at begin document
2664 % global. (LH)}
2665 % \begin{macro}{\XD@check@situation}
2666 % |\XD@situation| is the command that will be written to the
2667 % \texttt{.aux} file with the data about how the situation turned out.
2668 % Its syntax is
2669 % \begin{quote}
2670 % |\XD@situation|\marg{number}\marg{guess}\marg{did}\marg{correct}
2671 % \end{quote}
2672 % where \meta{number} is the number of the situation, and
2673 % \meta{guess}, \meta{did}, and \meta{correct} describe what the
2674 % guess, the actual action done, and what the correct action to do
2675 % respectively was. \meta{guess}, \meta{did}, and \meta{correct} are
2676 % either |0| (denoting even page) or |1| (denoting odd page).
2677 %
2678 % The definition for |\XD@situation| set here is the one which will
2679 % be in force when the \texttt{.aux} file is inputted at |\begin|\B
2680 % |{document}|; its purpose is to build the |\XD@wrongs@list|.
2681 % |\XD@check@situation| is the definition for |\XD@situation| which
2682 % will be in force when the \texttt{.aux} file is inputted at
2683 % |\end|\B|{document}|; its purpose is to check if anything was
2684 % incorrectly placed.
2685 %
2686 % The main problem |\XD@situation| has to face is that text in the
2687 % \texttt{.dvi} file needs not appear in exactly the same order as it
2688 % was typeset, and it is therefore possible that |\XD@situation|s in
2689 % the \texttt{.aux} file do not appear in increasing \meta{number}
2690 % order. Because of this, |\XD@situation| must sort the
2691 % |\XD@wrongs@list| while constructing it. The only reasonable
2692 % algorithm for this seems to be insertion sort, but as the items to
2693 % insert are almost surely almost sorted, a special check is done in
2694 % the beginning to see if that is the case. |\XD@next@wrong| is used
2695 % in this to store the number of the last item so far inserted into
2696 % the |\XD@wrongs@list|. By only assigning |\XD@next@wrong| locally
2697 % here, one is relieved of having to reset it in |\AtBeginDocument|
2698 % code.
2699 %
2700 % When sorting is actually applied, a new item |\@elt|\marg{insert}
2701 % is inserted through expanding the list. When doing that, the |\@elt|
2702 % macro has the syntax
2703 % \begin{quote}
2704 % |\@elt|\,\meta{flag}\,\marg{number}\,\meta{next}
2705 % \end{quote}
2706 % where \meta{flag} is |\BooleanTrue| or |\BooleanFalse|, \meta{number}
2707 % is the item that the |\@elt| belong to, and \meta{next} is either the
2708 % next |\@elt| or |\@gobble| (if this is the last). The \meta{flag}
2709 % specifies whether the item has been inserted; |\Boolean|\B|True| means
2710 % that it has. The above |\@elt|-sequence will expand to
2711 % \begin{quote}
2712 % |\noexpand|\,|\@elt|\,\marg{number}\,\meta{next}\,|\BooleanTrue|
2713 % \end{quote}
2714 % if \meta{flag} is |\BooleanTrue|, or \meta{flag} is |\BooleanFalse|
2715 % and \meta{number} is equal to \meta{insert}. It will expand to
2716 % \begin{quote}
2717 % |\noexpand|\,|\@elt|\,\marg{number}\,\meta{next}\,|\BooleanFalse|
2718 % \end{quote}
2719 % if \meta{flag} is |\BooleanFalse| and \meta{number} is less than
2720 % \meta{insert}. It expands to
2721 % \begin{quote}
2722 % |\noexpand|\,|\@elt|\,\marg{insert}\,|\noexpand|\,|\@elt|^^A
2723 % \,\marg{number}\\
2724 % \meta{next}\,|\BooleanTrue|
2725 % \end{quote}
2726 % if \meta{flag} is |\BooleanFalse| and \meta{number} is greater than
2727 % \meta{insert}.
2728 %
2729 % \begin{macrocode}
2730 \if@twoside
2731 \def\XD@situation#1#2#3#4{%
2732 \if #2#4\else
2733 \ifnum #1<\XD@next@wrong
2734 \begingroup
2735 \def\@elt##1##2##3{%
2736 \noexpand\@elt
2737 \ifcase
2738 \ifx ##1\BooleanTrue 0%
2739 \else\ifnum ##2<#1 1%
2740 \else\ifnum ##2>#1 2%
2741 \else 0%
2742 \fi\fi\fi
2743 \space
2744 {##2}\expandafter\@secondoftwo
2745 \or
2746 {##2}\expandafter\@firstoftwo
2747 \else
2748 {#1}\noexpand\@elt{##2}\expandafter\@secondoftwo
2749 \fi{##3\BooleanFalse}{##3\BooleanTrue}%
2750 }%
2751 \xdef\XD@wrongs@list{%
2752 \expandafter\expandafter \expandafter\@elt
2753 \expandafter\@firstoftwo \expandafter\BooleanFalse
2754 \XD@wrongs@list \@gobble
2755 }%
2756 \endgroup
2757 \else\ifnum #1>\XD@next@wrong
2758 \def\XD@next@wrong{#1}%
2759 \expandafter\gdef \expandafter\XD@wrongs@list
2760 \expandafter{\XD@wrongs@list \@elt{#1}}%
2761 \fi\fi
2762 \fi
2763 }
2764 \def\XD@check@situation#1#2#3#4{%
2765 \if #3#4\else
2766 \PackageWarningNoLine{xdoc2}{Page breaks may have changed.%
2767 \MessageBreak Rerun to get marginal material right}%
2768 \let\XD@situation\@gobblefour
2769 \fi
2770 }
2771 \AtBeginDocument{\global\let\XD@situation\XD@check@situation}
2772 \else
2773 \let\XD@situation\@gobblefour
2774 \fi
2775 % \end{macrocode}
2776 % \end{macro}\end{macro}
2777 %
2778 %
2779 % \begin{macro}{\XD@set@situation}
2780 % \begin{macro}{\XD@write@situation@ckpt}
2781 % \begin{macro}{\cl@@ckpt}
2782 % The page situation counter |\macro@cnt| is closely related to the
2783 % \texttt{page} counter and it needs to be among the counters whose
2784 % values are recorded in |\include| checkpoints, since the enumeration
2785 % of situations will otherwise change when files are added to or
2786 % removed from the |\@partlist|. It is not sufficient to simply set
2787 % the value of |\macro@cnt| however; one must also advance to the
2788 % correct position in the |\XD@wrongs@list| list and set
2789 % |\XD@next@wrong| accordingly. The |\XD@set@situation| command has
2790 % the syntax
2791 % \begin{quote}
2792 % |\XD@set@situation|\marg{number}
2793 % \end{quote}
2794 % It sets |\macro@cnt| to \meta{number} and updates |\XD@wrongs@list|
2795 % and |\XD@|\B|next@|\B|wrong| accordingly.
2796 % \begin{macrocode}
2797 \if@twoside
2798 \def\XD@set@situation#1{%
2799 \global\macro@cnt=#1\relax
2800 \loop \ifnum \XD@next@wrong<\macro@cnt
2801 \global\@next\XD@next@wrong\XD@wrongs@list{}{%
2802 \let\XD@next@wrong\maxdimen
2803 }%
2804 \repeat
2805 }
2806 \else \let\XD@set@situation=\@gobble \fi
2807 % \end{macrocode}
2808 %
2809 % The |\XD@write@situation@ckpt| macro writes an |\XD@set@situation|
2810 % command to the \texttt{.aux} file in the way that |\@wckptelt|
2811 % writes |\setcounter| commands for normal counters. A problem for
2812 % |\XD@write@situation@ckpt| is that it will have to appear in a
2813 % macro which is regularly subjected to the |\xdef| in |\@cons|. For
2814 % that reason, it will simply expand to itself whenever |\@elt| isn't
2815 % |\@wckptelt|.
2816 % \begin{macrocode}
2817 \if@twoside
2818 \def\XD@write@situation@ckpt{%
2819 \ifx \@elt\@wckptelt
2820 \immediate\write\@partaux{%
2821 \string\XD@set@situation{\the\macro@cnt}%
2822 }%
2823 \else
2824 \noexpand\XD@write@situation@ckpt
2825 \fi
2826 }
2827 \expandafter\def \expandafter\cl@@ckpt
2828 \expandafter{\cl@@ckpt \XD@write@situation@ckpt}
2829 \fi
2830 % \end{macrocode}
2831 % \end{macro}\end{macro}\end{macro}
2832 %
2833 %
2834 %
2835 % \section{The list of changes}
2836 % \label{Sec:Changes}
2837 %
2838 % Reimplementations elsewhere have required a few modifications related
2839 % to the |\changes| command. There are a lot of other things that could
2840 % and perhaps should be done with these mechanisms, though.
2841 %
2842 % \begin{macro}{\saved@macroname}
2843 % The contents of the |\saved@macroname| macro now have the syntax
2844 % \begin{quote}
2845 % \marg{sort key}\marg{text}
2846 % \end{quote}
2847 % i.e., exactly like the argument sequence of |\LevelSorted|. It's not
2848 % fed to that macro right now, but it is not unlikely that it will in
2849 % the future. The default definition corresponds to the default
2850 % definition in \package{doc}.
2851 % \begin{macrocode}
2852 \def\saved@macroname{{ }{\generalname}}
2853 % \end{macrocode}
2854 % Unlike the case in \package{doc}, the formatting of the text in
2855 % |\saved@macroname| must be included.
2856 % \end{macro}
2857 %
2858 % \begin{macro}{\if@version@key@}
2859 % The |@version@key@| switch is used for supporting intelligent
2860 % sorting of version numbers. It is normally false, but at times
2861 % where the version number argument of |\changes| is being expanded
2862 % because it will be used as a sort key then it is true. This is used
2863 % by the |\uintver| macro. Assignments to this switch are as a rule
2864 % global, since it is never true for any longer time.
2865 % \changes{prot2.4}{2002/11/01}{Switch added. (LH)}
2866 % \begin{macrocode}
2867 \newif\if@version@key@
2868 \@version@key@false
2869 % \end{macrocode}
2870 % \end{macro}
2871 %
2872 % \begin{macro}{\uintver}
2873 % The |\uintver| command can be used in the \meta{version} argument
2874 % of |\changes| to ensure that (unsigned) integers are sorted in
2875 % mathematical rather than ASCII order by \package{makeindex}. Thus
2876 % if for example version |1.10| is later than version |1.9| then one
2877 % should write this as
2878 % \begin{quote}
2879 % |\changes{1.\uintver{10}}{|\dots
2880 % \end{quote}
2881 % The general syntax is
2882 % \begin{quote}
2883 % |\uintver|\marg{number}
2884 % \end{quote}
2885 % and this expands completely in \TeX's mouth.
2886 % \changes{prot2.4}{2002/11/01}{Command added. (LH)}
2887 %
2888 % The idea is that 0--9 are compared as 0--9, whereas 10--99 are
2889 % compared as A10--A99, 100--999 are compared as B100-B999, and so on.
2890 % The comparisons are correct up to 99999, but it could easily be
2891 % extended further.
2892 % \begin{macrocode}
2893 \newcommand*\uintver[1]{%
2894 \if@version@key@
2895 \ifnum #1>9
2896 \ifnum #1<100
2897 A%
2898 \else\ifnum #1<\@m
2899 B%
2900 \else\ifnum #1<\@M
2901 C%
2902 \else
2903 D%
2904 \fi\fi\fi
2905 \fi
2906 \fi
2907 \expandafter\@firstofone \expandafter{\number#1}%
2908 }
2909 % \end{macrocode}
2910 % \end{macro}
2911 %
2912 %
2913 % \begin{macro}{\changes@}
2914 % This |\changes@| is a simple redefinition of the \package{doc}
2915 % macro with the same name. The main difference is that all
2916 % formatting of the second entry level has been taken out---it is
2917 % supposed to be provided in |\saved@macroname|---but in addition to
2918 % that the date is being used as a third level sort key and |\uintver|
2919 % may be used in the version number to correct the data.
2920 % \changes{prot2.4}{2002/11/01}{Added support for \cs{uintver}. (LH)}
2921 %
2922 % The former makes more sense for projects where the date is
2923 % increased faster than the version number and it doesn't change
2924 % anything relevant in the remaining cases. The latter is necessary
2925 % if version numbers are assigned for example by CVS.
2926 % \begin{macrocode}
2927 \def\changes@#1#2#3{%
2928 \global\@version@key@true
2929 \protected@edef\@tempa{#1}%
2930 \global\@version@key@false
2931 \protected@edef\@tempa{%
2932 \noexpand\glossary{%
2933 \@tempa\actualchar#1\levelchar
2934 \expandafter\@firstoftwo\saved@macroname\actualchar
2935 \expandafter\@secondoftwo\saved@macroname:\levelchar
2936 #2\actualchar#3%
2937 }%
2938 }%
2939 \@tempa
2940 \endgroup
2941 \@esphack
2942 }
2943 % \end{macrocode}
2944 % \end{macro}
2945 %
2946 % \begin{macro}{\@wrglossary}
2947 % \changes{prot2.2}{2001/02/13}{Redefinition added. (LH)}
2948 % \begin{macro}{\XD@glossary@keyword}
2949 % \changes{prot2.2}{2001/02/13}{Macro added. (LH)}
2950 % The |\@wrglossary| macro is the one which actually writes entries
2951 % to the \texttt{.glo} file. It is redefined by \package{xdoc} to put
2952 % the contents of |\XD@glossary@keyword|, rather than a hardwired
2953 % |\glossaryentry|, in front of the glossary entry.
2954 % |\XD@glossary@keyword| is redefined by the \package{docindex}
2955 % package~\cite{docindex}.
2956 % \begin{macrocode}
2957 \def\@wrglossary#1{%
2958 \protected@write\@glossaryfile{}%
2959 {\XD@glossary@keyword{#1}{\thepage}}%
2960 \endgroup
2961 \@esphack
2962 }
2963 \@ifundefined{XD@glossary@keyword}{%
2964 \edef\XD@glossary@keyword{\@backslashchar glossaryentry}%
2965 }{}
2966 % \end{macrocode}
2967 % \end{macro}\end{macro}
2968 %
2969 % \begin{macro}{\definechange}
2970 % \begin{macro}{\XD@definechange}
2971 % The |\definechange| command has the syntax
2972 % \begin{quote}
2973 % |\definechange|\marg{name}\marg{version}\marg{date}\marg{text}
2974 % \end{quote}
2975 % The three last arguments are precisely like the arguments of
2976 % |\changes|, but |\definechange| doesn't write the change to the
2977 % \texttt{.glo} file; instead it stores them away as the ``named
2978 % change'' \meta{name}, for later use in the |\usechange| command.
2979 % \begin{macrocode}
2980 \newcommand\definechange{%
2981 \begingroup\@sanitize
2982 \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
2983 \expandafter\endgroup \XD@definechange
2984 }
2985 \def\XD@definechange#1#2#3#4{\@namedef{XD@ch-#1}{{#2}{#3}{#4}}}
2986 % \end{macrocode}
2987 % \end{macro}\end{macro}
2988 %
2989 % The named changes are stored in the
2990 % \describecsfamily{XD@ch-\meta{name}}|\XD@ch-|\meta{name} family of
2991 % control sequences. These are parameterless macros with replacement
2992 % texts of the form
2993 % \begin{quote}
2994 % \marg{version}\marg{date}\marg{text}
2995 % \end{quote}
2996 %
2997 % \begin{macro}{\usechange}
2998 % \begin{macro}{\XD@usechange}
2999 % \changes{prot2.4}{2002/11/01}{Added support for \cs{uintver}. (LH)}
3000 % To use a named change defined earlier, one of course uses the
3001 % command |\usechange|, which has the syntax
3002 % \begin{quote}
3003 % |\usechange|\marg{name}
3004 % \end{quote}
3005 % The effect of this is similar to that of a general |\changes|
3006 % (i.e., it appears outside all \texttt{macro}-like environments) with
3007 % the arguments specified in the |\definechange|, but this also
3008 % includes the macro (or whatever) name with the page number, using
3009 % the encapsulation mechanism in \package{makeindex}.
3010 % \begin{macrocode}
3011 \newcommand*\usechange[1]{%
3012 \@ifundefined{XD@ch-#1}{%
3013 \PackageError{xdoc2}{Named change `#1' undefined}\@eha
3014 }{%
3015 \expandafter\expandafter \expandafter\XD@usechange
3016 \csname XD@ch-#1\endcsname
3017 }%
3018 }
3019 \def\XD@usechange#1#2#3{%
3020 \def\@tempa{{ }{\generalname}}%
3021 \ifx \@tempa\saved@macroname
3022 \let\@tempa\@empty
3023 \else
3024 \protected@edef\@tempa{%
3025 \encapchar labelednumber%
3026 {\expandafter\@secondoftwo\saved@macroname}%
3027 }
3028 \fi
3029 \global\@version@key@true
3030 \protected@edef\@tempb{#1}%
3031 \global\@version@key@false
3032 \glossary{%
3033 \@tempb\actualchar #1\levelchar
3034 \space\actualchar\generalname:\levelchar
3035 #2\actualchar#3\@tempa
3036 }%
3037 }
3038 % \end{macrocode}
3039 % \end{macro}\end{macro}
3040 %
3041 % \begin{macro}{\labelednumber}
3042 % The |\labelednumber| macro belongs to the same category as the
3043 % |\main| and |\usage| macros, but it takes an extra argument. The
3044 % syntax is
3045 % \begin{quote}
3046 % |\labelednumber|\marg{extra}\marg{number}
3047 % \end{quote}
3048 % which typesets as
3049 % \begin{quote}
3050 % \meta{number} (\meta{extra})
3051 % \end{quote}
3052 % \begin{macrocode}
3053 \newcommand*\labelednumber[2]{#2\nolinebreak[2] (#1)}
3054 % \end{macrocode}
3055 % \end{macro}
3056 %
3057 %
3058 %
3059 % \section{\texttt{macro}-like environments}
3060 % \label{Sec:Macro-environments}
3061 %
3062 % There are several reasons one might want to improve the \texttt{macro}
3063 % and \texttt{environment} environments.
3064 % \begin{itemize}
3065 % \item
3066 % The code in them cannot be reused if you want to define other
3067 % things than \TeX\ macros or \LaTeX\ environments. (During the
3068 % last year or so, I have defined \texttt{macro}-like environments
3069 % for over a dozen different things.)
3070 % \item
3071 % They always put the macro\slash environment name to the left of
3072 % the current column. This is inappropriate for two-sided printing,
3073 % as there should be a symmetry over an entire spread in that case.
3074 % \item
3075 % The vertical extent of a macro\slash environment name must not
3076 % exceed that of the |\strut|, since they will otherwise overprint
3077 % each other when stacked. In particular this makes it impossible to
3078 % make line breaks in macro names---something which would otherwise
3079 % be of interest in projects (such as for example \cite{fontinst})
3080 % where some names are very long and obvious breakpoints are
3081 % available.
3082 % \end{itemize}
3083 % (I'm quite sure there are more things that have annoyed me, but I can't
3084 % remember which they are right now.) The redefinitions below take care
3085 % of the all these problems.
3086 %
3087 %
3088 % \subsection{Grabbing arguments}
3089 %
3090 % A special feature of the \texttt{macro}-like environments is that (at
3091 % least some) of their arguments must be given rather special treatment.
3092 % This special treatment usually consists of making temporary |\catcode|
3093 % changes for the time these arguments are tokenized---since the standard
3094 % |\catcode|s for some important characters tend to be unsatisfactory in
3095 % these cases---but there are other possibilities as well. For that
3096 % reason, the \package{xdoc} package employs a mechanism that is very
3097 % similar to that used in the Mittelbach--Rowley--Carlisle
3098 % \package{xparse} package~\cite{xparse}, although it does not share
3099 % any code with that. I call this mechanism the argument grabber.
3100 %
3101 % The heart of the argument grabber is the macro |\XD@grab@arguments|,
3102 % which has the following syntax:
3103 % \begin{quote}
3104 % |\XD@grab@arguments|\marg{call}\marg{grabber sequence}^^A
3105 % \meta{arguments to grab}
3106 % \end{quote}
3107 % \meta{call} is something which will eventually be placed in front of
3108 % all the arguments grabbed. It can simply be a single macro, but it
3109 % can also contain some arguments for that macro. \meta{grabber sequence}
3110 % is a sequence of grabbers. A \emph{grabber} is typically a macro which
3111 % grabs the next argument and stores it in a token list together with the
3112 % arguments that were grabbed before. A grabber could however be some
3113 % more complex piece of code that performs a similar action.
3114 %
3115 % \begin{table}
3116 % \begin{minipage}{\columnwidth}
3117 % \begin{center}\small
3118 % \begin{tabular}{lll>{\raggedright}p{0.3\linewidth}}
3119 % \textbf{Grabber}& \textbf{Arg.\ type}&
3120 % \textbf{Catcodes\footnote[1]{Catcode settings key:
3121 % --- = no change, PL = changes made by \cs{MakePrivateLetters},
3122 % OB = set the catcode of backslash to ordinary.}}&
3123 % \textbf{Post-processing}\tabularnewline
3124 % |\XD@grab@marg|& Mandatory& ---& None\tabularnewline
3125 % |\XD@grab@oarg|& Optional& ---& None\tabularnewline
3126 % |\XD@grab@sarg|\marg{char}& 1-char optional&
3127 % ---& Returns |\BooleanTrue| if the character was present
3128 % and |\BooleanFalse| otherwise.\tabularnewline
3129 % |\XD@grab@withprivate|& Mandatory& PL& None\tabularnewline
3130 % |\XD@grab@asmacro|\footnote[2]{This grabber is probably obsolete;
3131 % it is included because it grabs the argument in precisely the
3132 % way that the \texttt{macro} environment of \package{doc} does.}&
3133 % Mandatory& OB+PL& None\tabularnewline
3134 % |\XD@grab@harmless|\meta{proc}& Mandatory& ---&
3135 % |\MakeHarmless| followed by \meta{proc}\tabularnewline
3136 % |\XD@grab@harmless@oarg|& Optional& ---&
3137 % |\MakeHarmless|\tabularnewline
3138 % \multicolumn{3}{l}{\cs{XD@grab@harmless@asmacro}}\tabularnewline
3139 % & Mandatory& OB+PL&
3140 % |\MakeHarmless| followed by |\XD@unbackslash|\tabularnewline
3141 % |\XD@grab@harmless@cs|& Mandatory\footnote[3]{The argument is
3142 % normally precisely one control sequence.}& PL&
3143 % |\string| whilst |\escapechar| is set to \textminus1,
3144 % followed by |\MakeHarmless|\tabularnewline
3145 % \multicolumn{3}{l}{^^A
3146 % \cs{XD@grab@harmless@withprivate}\marg{proc}}\\
3147 % & Mandatory& PL& |\MakeHarmless| followed by \meta{proc}
3148 % \end{tabular}
3149 % \end{center}
3150 % \end{minipage}
3151 %
3152 % \caption{Grabbers currently defined by \package{xdoc}}
3153 % \label{Tab:Grabbers}
3154 % \end{table}
3155 %
3156 % When arguments are being grabbed, the \meta{call} is stored in |\toks@|
3157 % and the arguments are appended to |\toks@| as they are grabbed. For
3158 % that reason, a grabber may not itself call |\XD@grab@arguments|, nor
3159 % may it use a command defined through \package{xparse}'s
3160 % |\Declare|\-|Document|\-|Command| or anything else which uses this
3161 % token register in a bad way.
3162 %
3163 % When a grabber is expanded, it is in the context
3164 % \begin{quote}
3165 % \meta{grabber}\,\meta{following grabbers}\,|\XD@endgrab|\penalty0
3166 % \thinspace\meta{ungrabbed arguments}
3167 % \end{quote}
3168 % After it has grabbed its argument, everything of the above should be
3169 % put back except for the \meta{grabber} and the argument it grabbed.
3170 % The argument itself should be wrapped in a group and appended to
3171 % |\toks@|.
3172 %
3173 % \textbf{Note:} In prototype~2 the format in which the argument grabber
3174 % returns the grabbed arguments was changed so that it can now be
3175 % unified with argument grabbing mechanisms of \package{xparse}. I
3176 % think this should be done some time in the future, but for the moment
3177 % it seems best not to rely on \LaTeXplus\ packages like \package{xparse}.
3178 %
3179 % \begin{macro}{\XD@grab@arguments}
3180 % \begin{macro}{\XD@endgrab}
3181 % \changes{prot2}{2000/07/13}{The grabbed arguments are no longer
3182 % returned wrapped up in a group. There is no longer a need for
3183 % storing the base call separately in \cs{toks}\,\texttt{2}. (LH)}
3184 % The |\XD@grab@arguments| and |\XD@endgrab| macros set up and finish
3185 % off argument grabbing.
3186 % \begin{macrocode}
3187 \def\XD@grab@arguments#1#2{%
3188 \toks@={#1}%
3189 #2\XD@endgrab
3190 }
3191 % \end{macrocode}
3192 % \begin{macrocode}
3193 \def\XD@endgrab{\the\toks@}
3194 % \end{macrocode}
3195 % \end{macro}\end{macro}
3196 %
3197 % \begin{macro}{\XD@grab@marg}
3198 % A grabber for ordinary arguments, like the \texttt{m} arguments of
3199 % \package{xparse}.
3200 % \begin{macrocode}
3201 \long\def\XD@grab@marg#1\XD@endgrab#2{%
3202 \addto@hook\toks@{{#2}}%
3203 #1\XD@endgrab
3204 }
3205 % \end{macrocode}
3206 % \end{macro}
3207 %
3208 % \begin{macro}{\XD@grab@oarg}
3209 % \begin{macro}{\XD@grab@oarg@}
3210 % A grabber for optional arguments (\texttt{o} arguments in
3211 % \package{xparse}). It looks ahead for an optional argument and
3212 % grabs that argument if there was one. If it doesn't find anything
3213 % which looks like an optional argument (i.e., if the next character
3214 % isn't a |[|), then the grabber will not grab anything (although it
3215 % may have tokenized the next argument), but it will still append
3216 % |\NoValue| to |\toks@|.
3217 %
3218 % \begin{macrocode}
3219 \def\XD@grab@oarg#1\XD@endgrab{%
3220 \@ifnextchar[{\XD@grab@oarg@{#1}}{%
3221 \addto@hook\toks@\NoValue
3222 #1\XD@endgrab
3223 }%
3224 }
3225 % \end{macrocode}
3226 % |\XD@grab@oarg@| is a helper to remove the brackets around the
3227 % optional argument.
3228 % \begin{macrocode}
3229 \long\def\XD@grab@oarg@#1[#2]{%
3230 \addto@hook\toks@{{#2}}%
3231 #1\XD@endgrab
3232 }
3233 % \end{macrocode}
3234 % \end{macro}\end{macro}
3235 %
3236 % \begin{macro}{\XD@grab@sarg}
3237 % A grabber for `star'-type arguments (\texttt{s} arguments in
3238 % \package{xparse}). The syntax is
3239 % \begin{quote}
3240 % |\XD@grab@sarg|\marg{char}
3241 % \end{quote}
3242 % It looks ahead to see if the next character is the \meta{char}. In
3243 % that case it gobbles it and adds a |\BooleanTrue| to the grabbed
3244 % arguments, otherwise it adds a |\BooleanFalse| to the grabbed
3245 % arguments.
3246 % \changes{prot2.3}{2001/11/03}{Macro added. (LH)}
3247 % \begin{macrocode}
3248 \def\XD@grab@sarg#1#2\XD@endgrab{%
3249 \@ifnextchar#1{%
3250 \addto@hook\toks@\BooleanTrue
3251 \@firstoftwo{#2\XD@endgrab}%
3252 }{%
3253 \addto@hook\toks@\BooleanFalse
3254 #2\XD@endgrab
3255 }%
3256 }
3257 % \end{macrocode}
3258 % \end{macro}
3259 %
3260 % \begin{macro}{\XD@grab@withprivate}
3261 % |\XD@grab@withprivate| is like |\XD@grab@marg| but grabs the
3262 % argument when the catcodes are as set by |\MakePrivateLetters|.
3263 % \begin{macrocode}
3264 \def\XD@grab@withprivate{%
3265 \begingroup\MakePrivateLetters\relax\expandafter\endgroup
3266 \XD@grab@marg
3267 }
3268 % \end{macrocode}
3269 % To think about: Perhaps things like |\XD@grab@withprivate| should
3270 % rather be considered a modifier for a grabber? Instead of having
3271 % |\XD@grab@withprivate| be the entire grabber, one could let the
3272 % grabber be something like
3273 % \begin{quote}
3274 % |\XD@grab@withprivate\XD@grab@marg|
3275 % \end{quote}
3276 % where the |\XD@grab@withprivate| should only expand to
3277 % \begin{quote}
3278 % |\begingroup\MakePrivateLetters\relax\expandafter\endgroup|
3279 % \end{quote}
3280 % \end{macro}
3281 %
3282 % \begin{macro}{\XD@grab@asmacro}
3283 % |\XD@grab@asmacro| is very similar to |\XD@grab@withprivate|, but it
3284 % sees to that the catcode settings are exactly those used by
3285 % \package{doc}'s \texttt{macro} environment.
3286 % \begin{macrocode}
3287 \def\XD@grab@asmacro{%
3288 \begingroup
3289 \catcode`\\=12 \MakePrivateLetters\relax
3290 \expandafter\endgroup
3291 \XD@grab@marg
3292 }
3293 % \end{macrocode}
3294 % \end{macro}
3295 %
3296 % \begin{macro}{\XD@grab@harmless}
3297 % \begin{macro}{\XD@grab@harmless@oarg}
3298 % \changes{prot2.1}{2000/09/30}{Macro added. (LH)}
3299 % \begin{macro}{\XD@grab@harmless@oarg@}
3300 % \changes{prot2.1}{2000/09/30}{Macro added. (LH)}
3301 % The |\XD@grab@harmless| grabber grabs one mandatory argument and
3302 % converts it to a harmless character string, which it contributes to
3303 % the list of arguments. The syntax is
3304 % \begin{quote}
3305 % |\XD@grab@harmless|\marg{post-processing}
3306 % \end{quote}
3307 % where \meta{post-processing} are commands that will be performed
3308 % after the grabbed argument has been made harmless, but before it is
3309 % contributed to the list of arguments. Thus the
3310 % \meta{post-processing} can modify the argument some more, but
3311 % \meta{post-processing} can just as well be empty.
3312 % \begin{macrocode}
3313 \def\XD@grab@harmless#1#2\XD@endgrab#3{%
3314 \MakeHarmless\@tempa{#3}%
3315 #1%
3316 \toks@=\expandafter{\the\expandafter\toks@ \expandafter{\@tempa}}%
3317 #2\XD@endgrab
3318 }
3319 % \end{macrocode}
3320 %
3321 % The |\XD@grab@harmless@oarg| grabber grabs one optional argument and
3322 % converts it to a harmless character string. This string is
3323 % contributed to the list of arguments if the optional argument, or
3324 % else the token |\NoValue| is contributed instead.
3325 % \begin{macrocode}
3326 \def\XD@grab@harmless@oarg#1\XD@endgrab{%
3327 \@ifnextchar[{\XD@grab@harmless@oarg@{#1}}{%
3328 \addto@hook\toks@\NoValue
3329 #1\XD@endgrab
3330 }%
3331 }
3332 % \end{macrocode}
3333 % |\XD@grab@harmless@oarg@| is a helper to remove the brackets around
3334 % the optional argument.
3335 % \begin{macrocode}
3336 \long\def\XD@grab@harmless@oarg@#1[#2]{%
3337 \MakeHarmless\@tempa{#2}%
3338 \toks@=\expandafter{\the\expandafter\toks@ \expandafter{\@tempa}}%
3339 #1\XD@endgrab
3340 }
3341 % \end{macrocode}
3342 % \end{macro}\end{macro}\end{macro}
3343 %
3344 % \begin{macro}{\XD@grab@harmless@asmacro}
3345 % \begin{macro}{\XD@grab@harmless@cs}
3346 % \begin{macro}{\XD@grab@harmless@cs@}
3347 % The |\XD@grab@harmless@asmacro| grabber combines the features of
3348 % |\XD@grab@|\B|asmacro| and |\XD@grab@harmless|, since when the
3349 % argument to grab is tokenized the catcode of |\| is set to 12 and
3350 % the catcode assignments in |\MakePrivateLetters| are made. Then the
3351 % grabbed argument is converted to a harmless character sequence, and
3352 % finally the first character is removed if it is a backslash.
3353 % \begin{macrocode}
3354 \def\XD@grab@harmless@asmacro{%
3355 \begingroup
3356 \catcode`\\=12 \MakePrivateLetters\relax
3357 \expandafter\endgroup
3358 \XD@grab@harmless{%
3359 \protected@edef\@tempa{%
3360 \expandafter\XD@unbackslash\@tempa\@empty
3361 }%
3362 }%
3363 }
3364 % \end{macrocode}
3365 %
3366 % The |\XD@grab@harmless@cs| grabber is for use with commands like
3367 % \package{doc}'s |\Describe|\-|Macro|, which take an actual control
3368 % sequence as the argument. It grabs one argument while having
3369 % catcodes changed as indicated by |\Make|\-|Private|\-|Letters|,
3370 % |\string|s the argument while |\escapechar| is |-1| (so that there
3371 % is no escape character inserted), and continues as
3372 % |\XD@grab@harmless|.
3373 % \begin{macrocode}
3374 \def\XD@grab@harmless@cs{%
3375 \begingroup
3376 \MakePrivateLetters\relax
3377 \expandafter\endgroup \XD@grab@harmless@cs@
3378 }
3379 % \end{macrocode}
3380 % \begin{macrocode}
3381 \long\def\XD@grab@harmless@cs@#1\XD@endgrab#2{%
3382 \begingroup
3383 \escapechar=\m@ne
3384 \expandafter\endgroup
3385 \expandafter\MakeHarmless \expandafter\@tempa
3386 \expandafter{\string#2}%
3387 \toks@=\expandafter{\the\expandafter\toks@ \expandafter{\@tempa}}%
3388 #1\XD@endgrab
3389 }
3390 % \end{macrocode}
3391 % \end{macro}\end{macro}\end{macro}
3392 %
3393 % \begin{macro}{\XD@grab@harmless@withprivate}
3394 % |\XD@grab@harmless@withprivate| is like |\XD@grab@harmless| but
3395 % grabs the argument when the catcodes are as set by
3396 % |\Make|\-|Private|\-|Letters|.
3397 % Like |\XD@|\B|grab@|\B|harmless|, |\XD@grab@|\B|harmless@|\B
3398 % |withprivate| takes an argument which can contain code that
3399 % modifies the harmless character string after it has been formed.
3400 % \begin{macrocode}
3401 \def\XD@grab@harmless@withprivate{%
3402 \begingroup\MakePrivateLetters\relax\expandafter\endgroup
3403 \XD@grab@harmless
3404 }
3405 % \end{macrocode}
3406 % \end{macro}
3407 %
3408 %
3409 % \subsection{The \cs{XD@m@cro} and \cs{NewMacroEnvironment} commands}
3410 %
3411 % In \package{doc} the macro that contains most of the code for the
3412 % \texttt{macro} and \texttt{environment} environments is called
3413 % |\m@cro@|. In \package{xdoc} the corresponding macro is |\XD@m@cro|.
3414 %
3415 % At this point, it is helpful to recall what |\m@cro@| actually does.
3416 % It can be summarized in the following four points:
3417 % \begin{itemize}
3418 % \item It starts a |\trivlist|.\footnote{Seriously, can someone
3419 % explain to me why it seems just about every non-math \LaTeX\
3420 % environment that doesn't start a \cs{list} starts a \cs{trivlist}?
3421 % What good does all these \cs{trivlist}s do? Is it (a)~that people
3422 % just like the basic design, (b)~that there's some deep technical
3423 % reason, or (c)~that people in general doesn't have a clue but all
3424 % other environments do that so it's best to include it just in
3425 % case?}
3426 % \item It prints the name of the macro\slash environment that is
3427 % about to be defined in the margin.
3428 % \item It writes an index entry (and inhibits cross-referencing of
3429 % the macro inside the environment).
3430 % \item It sets |\saved@macroname| to the name of the macro\slash
3431 % environment (for use by |\changes|).
3432 % \end{itemize}
3433 %
3434 % The first and fourth points are simple, and commands for the third
3435 % were defined in Section~\ref{Sec:Indexing}, but the second point
3436 % needs a few helper macros.
3437 %
3438 %
3439 % \begin{macro}{\XDStackItemLabels}
3440 % \changes{prot2}{2000/07/28}{Made it work like a \cs{vtop} (but hide
3441 % the height) if \cs{XD@macro@dimen} is \texttt{-}\cs{maxdimen}.
3442 % (LH)}
3443 % \begin{macro}{\XD@macro@dimen}
3444 % The |\XDStackItemLabels| macro is a definition of |\makelabel| which
3445 % is used in the \texttt{macro}-like environments for stacking the
3446 % names printed by subsequent environments under each other. It makes
3447 % a box which has zero height and depth (it should have zero width as
3448 % well, but that is left as a restriction on the argument) and the
3449 % printed names will be stacked if the reference points of the
3450 % subsequent boxes generated by |\XD|\-|Stack|\-|Item|\-|Labels|
3451 % coincide.
3452 %
3453 % |\XD@macro@dimen| (always assigned globally) stores the vertical
3454 % distance from the reference point of the box that
3455 % |\XD|\-|Stack|\-|Item|\-|Labels| makes to the (bottommost) baseline
3456 % of the previous printed name. |\XD@macro@dimen| is updated by each
3457 % new |\XD|\-|Stack|\-|Item|\-|Labels|. The baseline of the next printed
3458 % name will be put one |\baselineskip| lower than that of the previous
3459 % printed name, except for when |\XD@macro@dimen| is |-\maxdimen| (see
3460 % below). To avoid that printed names clash into each other, this
3461 % additional |\baselineskip| is generated as normal interline glue
3462 % where the upper box has the same depth as a strut and the new value
3463 % of |\XD@macro@dimen| is measured in such a way that the printed
3464 % name's depth below the nominal baseline will not exceed the depth of
3465 % a strut (that's what the |\boxmaxdepth| assignment is for).
3466 % When |\XD@macro@dimen| is |-\maxdimen| the (topmost) baseline of the
3467 % printed name will instead go through the reference point of the box.
3468 % This case is intended for the first item label in a stack.
3469 %
3470 % The reason |\everypar| is cleared is that that is where the list
3471 % environments put the commands which actually insert the item label
3472 % into the paragraph. If that code gets executed inside |\makelabel|,
3473 % the list environments get seriously confused with not at all nice
3474 % consequences.
3475 % \begin{macrocode}
3476 \def\XDStackItemLabels#1{%
3477 \setbox\z@=\vbox{%
3478 \ifdim \XD@macro@dimen=-\maxdimen
3479 \setbox\z@=\vtop{%
3480 \color@begingroup
3481 \everypar={}%
3482 #1%
3483 \color@endgroup
3484 }%
3485 \kern-\ht\z@
3486 \unvbox\z@
3487 \else
3488 \color@begingroup
3489 \everypar={}%
3490 \kern\XD@macro@dimen
3491 \setbox\z@=\copy\strutbox \ht\z@=\z@ \box\z@
3492 #1%
3493 \color@endgroup
3494 \fi
3495 \boxmaxdepth=\dp\strutbox
3496 }%
3497 \global\XD@macro@dimen=\ht\z@
3498 \vtop to\z@{\unvbox\z@ \vss}%
3499 }
3500 % \end{macrocode}
3501 % \begin{macrocode}
3502 \newdimen\XD@macro@dimen
3503 % \end{macrocode}
3504 % \end{macro}\end{macro}
3505 %
3506 % \begin{macro}{\XDToMargin}
3507 % \changes{prot2.1}{2000/11/26}{New name for \cs{XD@to@margin}. (LH)}
3508 % The |\XDToMargin| macro takes one argument, which is assumed to be
3509 % some horizontal material, and puts that material in a |\hbox| of
3510 % width zero, horizontally shifted out into the the outer margin, in
3511 % such a way that longer arguments extend further out. |\marginparsep|
3512 % is used as the distance between the argument and the main galley. All
3513 % these placements assume that the |\hbox| will be put |\labelsep| to
3514 % the left of the beginning of a nonindented paragraph, since that is
3515 % where it will be put by the |\item| of a |\trivlist|.
3516 %
3517 % A question is where the margin should be considered to start if the
3518 % |\@total|\-|left|\-|margin| isn't zero. The corresponding
3519 % \package{doc} action would be to consider the margin as everything
3520 % outside the |\linewidth| width, but I don't think that would be
3521 % appropriate here (especially not since \package{doc} always puts the
3522 % codeline numbers at the edge of the |\textwidth| width).
3523 % \begin{macrocode}
3524 \newcommand\XDToMargin[1]{%
3525 \hb@xt@\z@{%
3526 \IfOddPageSituation{%
3527 \dimen@=-\@totalleftmargin
3528 \advance \dimen@ \labelsep
3529 \advance \dimen@ \textwidth
3530 \advance \dimen@ \marginparsep
3531 \kern\dimen@
3532 }\hss
3533 #1%
3534 \IfOddPageSituation\hss{%
3535 \dimen@=\@totalleftmargin
3536 \advance \dimen@ -\labelsep
3537 \advance \dimen@ \marginparsep
3538 \kern\dimen@
3539 }%
3540 }%
3541 }
3542 % \end{macrocode}
3543 % \end{macro}
3544 %
3545 % \begin{macro}{\XDParToMargin}
3546 % The |\XDParToMargin| command is in syntax and use similar to the
3547 % |\XDToMargin| command, but it will try to linebreak an argument
3548 % that is too long rather than letting it extend outside the paper.
3549 %
3550 % The implementation first tries to break the argument without
3551 % considering justification or positioning, but with a rather high
3552 % |\linepenalty|. If the result of that try is a single line paragraph
3553 % then |\XDToMargin| will be called to actually typeset the argument.
3554 % Otherwise the argument is typeset as a paragraph which gets
3555 % displaced out into the outer margin by giving |\leftskip| and
3556 % |\rightskip| nonzero natural widths. The practical line width in
3557 % the paragraph is the |\marginparwidth|, but the hboxes containing
3558 % the individual lines will have width zero. The first line of the
3559 % paragraph will be set flush outwards, the last line of the paragraph
3560 % will be set flush inwards, and the remaining lines will be centered.
3561 %
3562 % \changes{prot2.1}{2000/11/26}{Command added. (LH)}
3563 % \begin{macrocode}
3564 \newcommand\XDParToMargin[1]{%
3565 \parindent=\z@
3566 \setbox\z@=\vbox{%
3567 \leftskip=\z@skip
3568 \rightskip=\z@\@plus 1fil%
3569 \parfillskip=\z@skip
3570 \hsize=\marginparwidth
3571 \linepenalty=1000%
3572 \color@begingroup
3573 \noindent\ignorespaces #1\@@par
3574 \color@endgroup
3575 \expandafter}%
3576 \expandafter\ifnum \the\prevgraf<\tw@
3577 \XDToMargin{#1}%
3578 \else
3579 \hsize=\z@
3580 \leftskip=\z@ \@plus \marginparwidth
3581 \rightskip=\leftskip
3582 \IfOddPageSituation{%
3583 \dimen@=-\@totalleftmargin
3584 \advance \dimen@ \labelsep
3585 \advance \dimen@ \textwidth
3586 \advance \dimen@ \marginparsep
3587 \advance \leftskip \dimen@
3588 \advance \rightskip -\dimen@ \@minus \p@
3589 \advance \rightskip -\marginparwidth
3590 \parfillskip=\z@ \@plus 1fil%
3591 }{%
3592 \dimen@=\@totalleftmargin
3593 \advance \dimen@ -\labelsep
3594 \advance \dimen@ \marginparsep
3595 \advance \leftskip -\dimen@ \@minus \p@
3596 \advance \leftskip -\marginparwidth
3597 \advance \rightskip \dimen@
3598 \parfillskip=\z@ \@plus -\marginparwidth%
3599 }
3600 \noindent\nobreak\hskip\parfillskip
3601 \ignorespaces #1\@@par
3602 \fi
3603 }
3604 % \end{macrocode}
3605 % \end{macro}
3606 %
3607 %
3608 % In the following I exploit the implementation of the |\item| command
3609 % in a slightly hackish way. Instead of starting a new paragraph with
3610 % the item label (which is what one at first would believe |\item|
3611 % does), |\item| actually puts the label in the box |\@labels| register,
3612 % and stores code in |\everypar| that inserts that box into the new
3613 % paragraph. Therefore I can make sure that various |\write| whatsits
3614 % that need to be as the same page as an |\item| label will be there by
3615 % adding them to the contents of the |\@labels| box. This seems more
3616 % reliable to me than putting them on the vertical list followed by a
3617 % |\nobreak| as \package{doc} does, but that would probably work as
3618 % well.
3619 %
3620 % [A funny thing in that which confused me a while was the question of
3621 % whether the |\box| command that inserts the box into the paragraph and
3622 % simultaneously clears the register acted globally or locally. It turns
3623 % out that the question was ill-posed, as the distinction between local
3624 % and global assignments is determined by what restore items they put
3625 % on \TeX's save stack. The |\box| command doesn't put anything there,
3626 % so the assignment it makes will essentially appear at the same
3627 % grouping level as the |\setbox| command that set the contents of the
3628 % box register. As all |\setbox|es for the |\@labels| box register are
3629 % global, the box register will be globally void after |\box\@labels|.]
3630 %
3631 %
3632 % \begin{macro}{\XD@m@cro}
3633 % \changes{prot2}{2000/07/24}{Put the \meta{changes} argument before
3634 % the \meta{assign} argument. Executing the \meta{assign} code
3635 % after the \meta{changes} \cs{edef}. Changed the descriptions of
3636 % these arguments a little. (LH)}
3637 % \changes{prot2.1}{2000/11/26}{Removed \cs{XDToMargin} from the
3638 % argument of \cs{item}. It should now be included in \#1
3639 % instead. (LH)}
3640 % This is the workhorse of all the \texttt{macro}-like environments.
3641 % It calls |\trivlist| and sets related parameters, prints the
3642 % ``macro'' name in the proper place, updates the representation of
3643 % the ``macro'' name that |\changes| will use, and writes appropriate
3644 % index entries (possibly making temporary changes in
3645 % cross-referencing). Exactly what these tasks consist of can vary
3646 % quite a lot between different \texttt{macro}-like environments, and
3647 % therefore the |\XD@m@cro| macro has the following syntax:
3648 % \begin{quote}
3649 % |\XD@m@cro|\marg{print}\marg{index}\marg{changes}\marg{assign}
3650 % \end{quote}
3651 % \meta{print}, \meta{index}, and \meta{assign} are simply the
3652 % commands for printing the ``macro'' name as it should appear in the
3653 % margin, generating the index entries for this \texttt{macro}-like
3654 % environment, and making whatever additional local assignments that
3655 % are needed for this environment (usually a couple of
3656 % |\Do|\-|Not|\-|Index|\-|Harmless| commands, if anything at all)
3657 % respectively. At the time \meta{index} is executed,
3658 % \texttt{codelineno} holds the number of the \emph{next} codeline.
3659 % \meta{changes}, finally, is code that will be put in the context
3660 % \begin{quote}
3661 % |\protected@edef\saved@macroname{|\meta{changes}|}|
3662 % \end{quote}
3663 % to set the |\saved@macroname| macro (for |\changes|).
3664 % \begin{macrocode}
3665 \def\XD@m@cro#1#2#3#4{%
3666 \topsep\MacroTopsep
3667 \trivlist
3668 \global\setbox\@labels=\hbox{%
3669 \unhbox\@labels
3670 \if@inlabel \else
3671 \global\XD@macro@dimen=-\maxdimen
3672 \StepPageSituation
3673 \RecordPageSituation
3674 \fi
3675 \advance \c@codelineno \@ne
3676 #2%
3677 }%
3678 \let\makelabel\XDStackItemLabels
3679 \item[#1]%
3680 \protected@edef\saved@macroname{#3}%
3681 #4%
3682 \ignorespaces
3683 }
3684 % \end{macrocode}
3685 % \end{macro}
3686 %
3687 % In the first \package{xdoc} prototype, the \texttt{macro}-like
3688 % environments were implemented so that each new environment only used
3689 % two control sequences (|\|\meta{env} and |\end|\meta{env}), which is
3690 % the absolute minimum. This implementation worked fine for
3691 % single argument environments, but the number of helper macros that
3692 % would have to be introduced to deal with multiple argument
3693 % environments exceeded what could be considered reasonable. Therefore
3694 % the second prototype claims a third control sequence for the
3695 % implementation of a \texttt{macro}-like environment \meta{env}, namely
3696 % |\\|\meta{env}, which is also used by normal \LaTeXe\ environments
3697 % which take an optional argument.
3698 %
3699 % It should also be mentioned that the implementation in the first
3700 % prototype required that most of the code in |\|\meta{env} had to be
3701 % written in a very special way. Instead of using the |#|\meta{digit}
3702 % notation for the arguments and write straightforward \LaTeX\ code, one
3703 % had to express everything using macros which operate on arguments ``up
3704 % ahead'' (immediately after the code you can specify). This curious
3705 % coding model made it out of the question to create a class designer
3706 % interface for defining new \texttt{macro}-like environments, but in
3707 % the second \package{xdoc} prototype it is quite simple to do something
3708 % of that sort: the command name is |\New|\-|Macro|\-|Environment|.
3709 %
3710 % \begin{macro}{\NewMacroEnvironment}
3711 % \changes{prot2}{2000/07/13}{Command added. (LH)}
3712 % \changes{prot2}{2000/07/24}{Changed syntax in conformity with the
3713 % syntax change in \cs{XD@m@cro}. (LH)}
3714 % \changes{prot2.1}{2000/11/26}{Introduced star form with different
3715 % semanics for the \meta{print} argument. This uses the helper
3716 % macros \cs{XD@NewMacroEnvironment} and
3717 % \cs{XD@NewMacroEnvironment@}. (LH)}
3718 % \begin{macro}{\XD@NewMacroEnvironment}
3719 % \begin{macro}{\XD@NewMacroEnvironment@}
3720 % The |\NewMacroEnvironment| command is used for defining new
3721 % \texttt{macro}-like environments. It has the syntaxes
3722 % \begin{quote}
3723 % |\NewMacroEnvironment|\marg{name}\marg{grabbers}\marg{numargs}\\
3724 % \vadjust{}\hfill\marg{unjust-print}\marg{index}\marg{changes}^^A
3725 % \marg{assign}\\
3726 % |\NewMacroEnvironment*|\marg{name}\marg{grabbers}\marg{numargs}\\
3727 % \vadjust{}\hfill\marg{print}\marg{index}\marg{changes}\marg{assign}
3728 % \end{quote}
3729 % where \meta{name} is the name of the environment to define,
3730 % \meta{grabbers} is a sequence of argument grabbers, \meta{numargs}
3731 % is the number of arguments that the grabbers will grab, and
3732 % \meta{print}, \meta{index}, \meta{changes}, and \meta{assign} are
3733 % code that will be put in the respective arguments of |\XD@m@cro|.
3734 % In the four last arguments, argument specifiers |#1| to
3735 % |#|\meta{numargs} inclusive can be used do mean the arguments that
3736 % were grabbed by the sequence of grabbers.
3737 %
3738 % The argument grabbers that are currently made available by the
3739 % \package{xdoc} package are listed in Table~\ref{Tab:Grabbers} on
3740 % page~\pageref{Tab:Grabbers}.
3741 %
3742 % The \meta{print} code will be executed while \TeX\ is in internal
3743 % vertical mode and it should put one or several hboxes of width zero
3744 % onto the vertical list. The contents of these boxes should be some
3745 % amount of text which will appear displaced out into the outer margin
3746 % on the page when the reference point of the box appears |\labelsep|
3747 % to the left of the left edge of the line. The easiest way of
3748 % achieveing this is to use a \meta{print} of the form
3749 % \begin{quote}
3750 % |\XDToMargin|\marg{unjust-print}
3751 % \end{quote}
3752 % and this is exactly what the non-star form of |\NewMacroEnvironment|
3753 % does by default.
3754 %
3755 % \begin{macrocode}
3756 \newcommand\NewMacroEnvironment{%
3757 \@ifstar\XD@NewMacroEnvironment\XD@NewMacroEnvironment@
3758 }
3759 \def\XD@NewMacroEnvironment@#1#2#3#4{%
3760 \XD@NewMacroEnvironment{#1}{#2}{#3}{\XDToMargin{#4}}%
3761 }
3762 \def\XD@NewMacroEnvironment#1#2#3#4#5#6#7{%
3763 \expandafter\@ifdefinable\csname#1\endcsname{%
3764 \expandafter\def \csname#1\expandafter\endcsname
3765 \expandafter{\expandafter\XD@grab@arguments
3766 \csname\@backslashchar#1\endcsname{#2}}%
3767 \let\l@ngrel@x\relax
3768 \expandafter\@yargdef \csname\@backslashchar#1\endcsname \@ne
3769 {#3}{\XD@m@cro{#4}{#5}{#6}{#7}}%
3770 \expandafter\let \csname end#1\endcsname \endtrivlist
3771 }%
3772 }
3773 % \end{macrocode}
3774 % The \meta{grabbers} argument---in which one specifies a list of
3775 % internal macros---is not how the interface should really look, but I
3776 % think it will have to do for now. The final interface will probably
3777 % use something like the argument specifications of
3778 % |\Declare|\-|Document|\-|Command|, but there is little point in
3779 % implementing that before \package{xparse} has gotten its final form.
3780 % \end{macro}\end{macro}\end{macro}
3781 %
3782 % The macro |\@yargdef| used above should perhaps be checked so that its
3783 % syntax hasn't changed, but since |\@yargdef| quite recently
3784 % (\texttt{ltdefn.dtx} v\,1.3c, 1999/01/18) was completely reimplemented
3785 % without any change in the syntax (despite the fact that the syntax is
3786 % afterwards rather peculiar), I think it can be assumed that the syntax
3787 % will not change in \LaTeXe.
3788 %
3789 %
3790 %
3791 % \subsection{Reimplementing \texttt{macro} and \texttt{environment}}
3792 % \label{Ssec:Macro&environment}
3793 %
3794 % Well, then how does one reimplement the \texttt{macro} and
3795 % \texttt{environment} environments using |\XD@m@cro|? We shall soon
3796 % see, but first it is convenient to define a utility macro.
3797 %
3798 % \changes{prot2}{2000/07/14}{Lots of utility macros were removed:
3799 % \cs{XDWrapText}, \cs{XDAltWrapText}, \cs{XDSortAndText},
3800 % \cs{MultipleApply}, \cs{ApplicableUsageIndex}, and
3801 % \cs{XD@index@family}. (LH)}
3802 %
3803 % \begin{macro}{\XDMainIndex}
3804 % \changes{prot2}{2000/07/14}{New name and syntax for
3805 % \cs{ApplicableMainIndex}. (LH)}
3806 % The |\XDMainIndex| macro is an abbreviation to save a couple of
3807 % tokens in a very frequent call to |\IndexEntry|. It has the syntax
3808 % \begin{quote}
3809 % |\XDMainIndex|\marg{argument}
3810 % \end{quote}
3811 % and that expands to
3812 % \begin{quote}
3813 % |\IndexEntry|\marg{argument}|{main}{\TheXDIndexNumber}|
3814 % \end{quote}
3815 % \begin{macrocode}
3816 \newcommand\XDMainIndex[1]{\IndexEntry{#1}{main}{\TheXDIndexNumber}}
3817 % \end{macrocode}
3818 % \end{macro}
3819 %
3820 % \begin{environment}{macro}
3821 % \changes{prot2.1}{2000/11/15}{Using \cs{MakeSortKey} to make index
3822 % entry. (LH)}
3823 % \begin{environment}{environment}
3824 % It is very easy to implement \texttt{macro} and \texttt{environment}
3825 % environments which behave pretty much as in \package{doc} using the
3826 % |\New|\-|Macro|\-|Environment| command. The important difference
3827 % is that in \package{doc} everything that distinguished the two
3828 % environments was to be found in various helper macros, but here all
3829 % that code is in the |\\macro| and |\\environment| macros. Thus to
3830 % define one new \texttt{macro}-like environment, one doesn't have to
3831 % define six or so new macros---everything can be handled in one
3832 % definition.
3833 %
3834 % The reason for the |\let| commands below is of course that
3835 % \texttt{macro} and \texttt{environment} are already defined, and
3836 % there is no |\Renew|\-|Macro|\-|Environment| command. It could
3837 % perhaps have been better if |\New|\-|Macro|\-|Environment| had
3838 % behaved like |\Declare|\-|Robust|\-|Command|, but I don't think that
3839 % is an important problem for the moment.
3840 % \begin{macrocode}
3841 \let\macro=\relax
3842 \let\endmacro=\relax
3843 \NewMacroEnvironment{macro}{\XD@grab@harmless@asmacro}{1}
3844 {\MacroFont\Bslash#1}
3845 {\MakeSortKey\@tempa{#1}{}%
3846 \XDMainIndex{\LevelSorted{\@tempa}{\texttt{\Bslash#1}}}}
3847 {{#1}{\texttt{\Bslash#1}}}
3848 {\DoNotIndexHarmless{#1}}
3849 % \end{macrocode}
3850 % \begin{macrocode}
3851 \let\environment=\relax
3852 \let\endenvironment=\relax
3853 \NewMacroEnvironment{environment}{\XD@grab@harmless@asmacro}{1}
3854 {\MacroFont#1}
3855 {\XDMainIndex{\LevelSorted{#1}{\texttt{#1} (environment)}}%
3856 \XDMainIndex{%
3857 \LevelSame{environments:}\LevelSorted{#1}{\texttt{#1}}%
3858 }}%
3859 {{#1}{\texttt{#1}}}
3860 {}%
3861 % \end{macrocode}
3862 % \end{environment}\end{environment}
3863 %
3864 %
3865 % \subsection{Further examples of \texttt{macro}-like environments}
3866 % \label{Ssec:More macros}
3867 %
3868 % \begin{environment}{option}
3869 % The \texttt{option} environment is for class\slash package options.
3870 % IMHO, something like this environment should have been added to
3871 % \package{doc} years ago!
3872 %
3873 % \begin{macrocode}
3874 \NewMacroEnvironment{option}{\XD@grab@harmless\relax}{1}
3875 {\MacroFont#1 \normalfont option}
3876 {\XDMainIndex{\LevelSorted{#1}{\texttt{#1} option}}%
3877 \XDMainIndex{%
3878 \LevelSame{options:}\LevelSorted{#1}{\texttt{#1}}%
3879 }}%
3880 {{#1 option}{\texttt{#1} option}}
3881 {}%
3882 % \end{macrocode}
3883 % \end{environment}
3884 %
3885 % \begin{environment}{switch}
3886 % \changes{prot2.1}{2000/11/18}{Using \cs{MakeSortKey}. (LH)}
3887 % The \texttt{switch} environment is for switches created by
3888 % |\newif| (\PlainTeX\ style).
3889 % \begin{macrocode}
3890 \NewMacroEnvironment{switch}{\XD@grab@harmless\relax}{1}
3891 {\MacroFont#1 \normalfont switch}%
3892 % \end{macrocode}
3893 % What makes switches different from the other \texttt{macro}-like
3894 % environments defined here is the large number of index entries it
3895 % makes. For a switch \meta{sw} it first makes one under the `switches:'
3896 % heading:
3897 % \begin{macrocode}
3898 {%
3899 \MakeSortKey\XD@last@key{#1}{}%
3900 \XDMainIndex{%
3901 \LevelSame{switches:}\LevelSorted{\XD@last@key}{\texttt{#1}}%
3902 }%
3903 % \end{macrocode}
3904 % Second it makes a `\meta{sw} switch' entry:
3905 % \begin{macrocode}
3906 \XDMainIndex{\LevelSorted{\XD@last@key}{\texttt{#1} switch}}%
3907 % \end{macrocode}
3908 % Third it makes an entry for the macro |\if|\meta{sw}. The sort key
3909 % for this entry is \emph{not} subjected to |\MakeSortKey| because
3910 % no reasonable operator will act on the |if| prefix (an operator
3911 % which acts on |if| could do rather strange things to e.g. |\ifnum|).
3912 % \begin{macrocode}
3913 \XDMainIndex{\LevelSorted{if#1}{\texttt{\Bslash if#1}}}%
3914 % \end{macrocode}
3915 % Fourth it makes an entry for the macro |\|\meta{sw}|false|:
3916 % \begin{macrocode}
3917 \MakeSortKey\@tempa{#1false}{}%
3918 \XDMainIndex{\LevelSorted{\@tempa}{\texttt{\Bslash#1false}}}%
3919 % \end{macrocode}
3920 % Finally it makes an entry for the macro |\|\meta{sw}|true|:
3921 % \begin{macrocode}
3922 \MakeSortKey\@tempa{#1true}{}%
3923 \XDMainIndex{\LevelSorted{\@tempa}{\texttt{\Bslash#1true}}}%
3924 }%
3925 % \end{macrocode}
3926 % The |\changes| heading, on the other hand, is trivial.
3927 % \begin{macrocode}
3928 {{#1}{\texttt{#1} switch}}
3929 % \end{macrocode}
3930 % Finally, \texttt{switch} should turn off indexing of the three macros
3931 % it makes \texttt{main} entries for, since \package{makeindex} will
3932 % otherwise complain.
3933 % \begin{macrocode}
3934 {\DoNotIndexHarmless{if#1}%
3935 \DoNotIndexHarmless{#1false}%
3936 \DoNotIndexHarmless{#1true}}%
3937 %</pkg>
3938 % \end{macrocode}
3939 % \end{environment}
3940 %
3941 %
3942 % To end this section, there now follows two examples which are not
3943 % part of the package as they are very specific, but which have been
3944 % included here because they illustrate that \texttt{macro}-like
3945 % environments may have several arguments.
3946 %
3947 % \begin{environment}{enccommand}
3948 % \begin{environment}{enccomposite}
3949 % The \texttt{enccommand} and \texttt{enccomposite} environments can
3950 % be used for marking up sources for encoding definition files and the
3951 % like. \texttt{enccommand} is for encoding-specific commands and has
3952 % the syntax
3953 % \begin{quote}
3954 % |\begin{enccommand}|\marg{command}\oarg{encoding}
3955 % \end{quote}
3956 % where \meta{command} is the encoding-specific command and
3957 % \meta{encoding} is the encoding that this definition is for. If the
3958 % \meta{encoding} is omitted then the \texttt{enccommand} is assumed
3959 % to be for the default definition of the command.
3960 %
3961 % \texttt{enccomposite} is for composites of encoding-specific
3962 % commands (defined for example using |\Declare|\-|Text|\-|Composite|).
3963 % It has the syntax
3964 % \begin{quote}
3965 % |\begin{enccomposite}|\marg{command}\marg{encoding}\marg{argument}
3966 % \end{quote}
3967 % where \meta{command} and \meta{encoding} are as for
3968 % \texttt{enccommand} and \meta{argument} is the argument with which
3969 % the command is being composed.
3970 %
3971 % The marginal headings these commands print are the actual control
3972 % sequences in which the definitions are stored.
3973 % \begin{macrocode}
3974 %<*enccmds>
3975 \NewMacroEnvironment{enccommand}{%
3976 \XD@grab@harmless@asmacro \XD@grab@oarg
3977 }{2}{\MacroFont\Bslash \ifx\NoValue#2?\else#2\fi \Bslash #1}{%
3978 \XDMainIndex{%
3979 \LevelSorted{#1}{\texttt{\Bslash#1}}%
3980 \ifx \NoValue#2%
3981 \LevelSame{default}%
3982 \else
3983 \LevelSorted{#2}{\texttt{#2} encoding}%
3984 \fi
3985 }%
3986 }{{#1}{\texttt{\Bslash#1}}}{\DoNotIndexHarmless{#1}}
3987 % \end{macrocode}
3988 % \begin{macrocode}
3989 \NewMacroEnvironment{enccomposite}{%
3990 \XD@grab@harmless@asmacro \XD@grab@marg \XD@grab@harmless\relax
3991 }{3}{\MacroFont\Bslash#2\Bslash#1-#3}{%
3992 \XDMainIndex{%
3993 \LevelSorted{#1}{\texttt{\Bslash#1}}%
3994 \LevelSorted{#2}{\texttt{#2} encoding}%
3995 \LevelSorted{\XD@unbackslash#3\@empty}{\texttt{#3} composite}%
3996 }%
3997 }{{#1}{\texttt{\Bslash#1}}}{\DoNotIndexHarmless{#1}}
3998 %</enccmds>
3999 % \end{macrocode}
4000 % In the file \texttt{cyoutenc.dtx} the definitions of many
4001 % encoding-specific commands are written so that the same line of
4002 % code can work is all four files \texttt{t2aenc.def},
4003 % \texttt{t2benc.def}, \texttt{t2cenc.def}, and \texttt{x2enc.def}.
4004 % Therefore the \meta{encoding} argument of the \texttt{enccommand}
4005 % and \texttt{enccomposite} environments should perhaps rather be a
4006 % comma-separated list of encodings than a single encoding, but that
4007 % would make this example unnecessarily complicated.
4008 % \end{environment}\end{environment}
4009 %
4010 %
4011 %
4012 % \section{Describing macros and the like}
4013 % \label{Sec:Describing}
4014 %
4015 % \begin{macro}{\if@mparswitch}
4016 % \begin{macro}{\if@reversemargin}
4017 % In two-sided mode, marginal notes should appear in the outer
4018 % margin. The following code takes care of that.
4019 % \begin{macrocode}
4020 %<*pkg>
4021 \if@twoside
4022 \@mparswitchtrue
4023 \normalmarginpar
4024 \fi
4025 % \end{macrocode}
4026 % \end{macro}\end{macro}
4027 %
4028 % \begin{macro}{\GenericDescribePrint}
4029 % \changes{prot2}{2000/07/14}{\cs{leavevmode} and \cs{ignorespaces}
4030 % moved to \cs{NewDescribeCommand}. (LH)}
4031 % \changes{prot2}{2000/07/20}{Added \cs{strut}. Removed it from
4032 % arguments passed to \cs{GenericDescribePrint}. (LH)}
4033 % \changes{prot2.3}{2001/06/24}{Changed formatting to match that of
4034 % \cs{XDParToMargin}. (LH)}
4035 % The |\GenericDescribePrint| macro is a utility macro for use in
4036 % commands like |\Describe|\-|Macro|. Its syntax is
4037 % \begin{quote}
4038 % |\GenericDescribePrint|\marg{text}
4039 % \end{quote}
4040 % and it puts \meta{text} in a marginal paragraph, giving it the
4041 % appropriate justification for appearing in that margin.
4042 %
4043 % The first part simply tests whether the argument fits on a single
4044 % line.
4045 % \begin{macrocode}
4046 \newcommand\GenericDescribePrint[1]{%
4047 \setbox\z@=\vbox{%
4048 \parindent=\z@
4049 \leftskip=\z@skip
4050 \rightskip=\z@\@plus 1fil%
4051 \parfillskip=\z@skip
4052 \hsize=\marginparwidth
4053 \linepenalty=\@m
4054 \color@begingroup
4055 \noindent\ignorespaces #1\@@par
4056 \color@endgroup
4057 \expandafter}%
4058 \expandafter\ifnum \the\prevgraf<\tw@
4059 % \end{macrocode}
4060 % Then comes the actual typesetting. First the single-line format.
4061 % The braces in the optional argument are there to prevent trouble
4062 % in case |#1| contains a right brace; they will be stripped off when
4063 % the argument is grabbed.
4064 % \begin{macrocode}
4065 \if@twoside
4066 \marginpar[{\raggedleft\strut #1}]{\raggedright\strut #1}%
4067 \else
4068 \marginpar{\raggedleft\strut#1}%
4069 \fi
4070 \else
4071 \if@twoside
4072 \marginpar[{%
4073 \leftskip=\z@ \@plus \marginparwidth
4074 \rightskip=\leftskip
4075 \parfillskip=\z@ \@plus -\marginparwidth
4076 \noindent\nobreak\hskip\parfillskip
4077 \ignorespaces #1%
4078 }]{%
4079 \leftskip=\z@ \@plus \marginparwidth
4080 \rightskip=\leftskip
4081 \parfillskip=\z@ \@plus 1fil%
4082 \noindent\nobreak\hskip\parfillskip
4083 \ignorespaces #1%
4084 }%
4085 \else
4086 \marginpar{%
4087 \leftskip=\z@ \@plus \marginparwidth
4088 \rightskip=\leftskip
4089 \parfillskip=\z@ \@plus -\marginparwidth
4090 \noindent\nobreak\hskip\parfillskip
4091 \ignorespaces #1%
4092 }%
4093 \fi
4094 \fi
4095 }
4096 % \end{macrocode}
4097 % \end{macro}
4098 %
4099 % The \texttt{describe}-commands are supposed to be invisible---only
4100 % leave a single space even when there are spaces both before and after
4101 % them---but there are problems with the mechanisms for this. I get the
4102 % impression that they have never worked perfectly, but that seems to
4103 % be mainly due to that certain macros in the \LaTeX\ kernel never did
4104 % either, and I suspect that the general problem has been thrashed over
4105 % many times before.
4106 %
4107 % \package{doc}'s |\DescribeMacro| and |\DescribeEnv| are wrapped up in
4108 % a |\@bsphack| \dots\ |\@esphack| ``group'' to become invisible, but
4109 % the |\marginpar| and various index commands they are built on are
4110 % themselves already invisible, so one would suspect that there is no
4111 % need for additional invisibility. There are however two factors which
4112 % create this need. One is that it doesn't do the right thing at
4113 % beginning of lines; here it seems like what the
4114 % \texttt{describe}-commands would need is the |\@vbsphack| macro
4115 % (whose definition appears in \texttt{ltspace.dtx}, but which has been
4116 % commented out) since they should start a new paragraph and leave no
4117 % following space if they are used in vertical mode. The other factor is
4118 % that the standard |\@bsphack|--|\@esphack| can only suppress every
4119 % second intermediate space if several invisible commands appear in
4120 % sequence, as is quite common for the
4121 % \texttt{describe}-commands.\footnote{It would seem that a simple fix
4122 % for this is to have \cs{@esphack} insert \cs{nobreak}
4123 % \cs{hskip}\texttt{-}\cs{@savsk} \cs{hskip}\cs{@savsk} before it
4124 % executes \cs{ignorespaces}, but since that fix hasn't been
4125 % incorporated into the kernel or the \package{fixltx2e} package there
4126 % probably is some problem with it.}
4127 %
4128 % Instead the \package{doc} implementations of |\DescribeMacro| and
4129 % |\DescribeEnv| begin with |\leavevmode| and end with |\ignorespaces|,
4130 % which means that they are only ``invisible'' if they appear on on the
4131 % left of visible material, but that's how it has been for over a decade
4132 % now.
4133 %
4134 % \begin{macro}{\NewDescribeCommand}
4135 % \changes{prot2}{2000/07/14}{Command added. (LH)}
4136 % The |\NewDescribeCommand| command is a relative to the
4137 % |\New|\-|Macro|\-|Environment| command which defines commands
4138 % analogous to |\Describe|\-|Macro| rather than \texttt{macro}-like
4139 % environments. Its syntax is
4140 % \begin{quote}
4141 % |\NewDescribeCommand|\marg{command}\marg{grabbers}\B
4142 % \marg{numargs}\B\marg{definition}
4143 % \end{quote}
4144 % \meta{command} is the control sequence to define. \meta{grabbers}
4145 % and \meta{numargs} are as for the |\NewMacroEnvironment| command.
4146 % \meta{definition} is the command definition.
4147 % In addition to the definition given in the \meta{definition}
4148 % argument and the code for grabbing the arguments, the command
4149 % actually defined by |\New|\-|Describe|\-|Command| will contain a
4150 % |\leavevmode| at the start and an |\ignorespaces| at the end.
4151 %
4152 % The |\NewDescribeCommand| command should really just be a call to
4153 % \package{xparse}'s |\Declare|\-|Document|\-|Command|, but that will
4154 % have to wait until \package{xdoc} becomes based on the
4155 % \package{xparse} package.
4156 % \begin{macrocode}
4157 \newcommand\NewDescribeCommand[4]{%
4158 \@ifdefinable#1{%
4159 \expandafter\def \expandafter#1\expandafter{%
4160 \expandafter\XD@grab@arguments \csname\string#1\endcsname{#2}%
4161 }%
4162 \let\l@ngrel@x\relax
4163 \expandafter\@yargdef \csname\string#1\endcsname \@ne {#3}%
4164 {\leavevmode#4\ignorespaces}%
4165 }%
4166 }
4167 % \end{macrocode}
4168 % \end{macro}
4169 %
4170 % \begin{macro}{\DescribeMacro}
4171 % \changes{prot2.1}{2000/11/18}{Using \cs{MakeSortKey}. (LH)}
4172 % \begin{macro}{\DescribeEnv}
4173 % The |\DescribeMacro| and |\DescribeEnv| commands are as in
4174 % \package{doc}. The argument of |\DescribeMacro| is supposed to be
4175 % the actual control sequence to describe (not as with the
4176 % \texttt{macro} environment something which looks like the control
4177 % sequence after being |\string|ed).
4178 % \begin{macrocode}
4179 \let\DescribeMacro=\relax
4180 \NewDescribeCommand\DescribeMacro{\XD@grab@harmless@cs}{1}{%
4181 \GenericDescribePrint{\MacroFont\Bslash#1}%
4182 \MakeSortKey\@tempa{#1}{}%
4183 \IndexEntry{%
4184 \LevelSorted{\@tempa}{\texttt{\Bslash#1}}%
4185 }{usage}{\thepage}%
4186 }
4187 % \end{macrocode}
4188 % The argument of |\DescribeEnv|, on the other hand, is treated like
4189 % that of the \texttt{environment} environment, but backslash isn't
4190 % given catcode 12---only the catcode assignments in
4191 % |\Make|\-|Private|\-|Letters| are made.
4192 % \begin{macrocode}
4193 \let\DescribeEnv=\relax
4194 \NewDescribeCommand\DescribeEnv{%
4195 \XD@grab@harmless@withprivate\relax
4196 }{1}{%
4197 \GenericDescribePrint{\MacroFont#1}%
4198 \IndexEntry{%
4199 \LevelSame{environments:}\LevelSorted{#1}{\texttt{#1}}%
4200 }{usage}{\thepage}%
4201 \IndexEntry{%
4202 \LevelSorted{#1}{\texttt{#1} (environment)}%
4203 }{usage}{\thepage}%
4204 }
4205 % \end{macrocode}
4206 % \end{macro}\end{macro}
4207 %
4208 % \begin{macro}{\describeoption}
4209 % \changes{prot2}{2000/07/31}{Command added---I realised that the need
4210 % to describe options is probably as large as that to mark out
4211 % their definition. (LH)}
4212 % The |\describeoption| command is the \texttt{describe}-companion to
4213 % the \texttt{option} environment.
4214 % \begin{macrocode}
4215 \NewDescribeCommand\describeoption{\XD@grab@harmless\relax}{1}{%
4216 \GenericDescribePrint{\MacroFont#1 \normalfont option}%
4217 \IndexEntry{%
4218 \LevelSame{options:}\LevelSorted{#1}{\texttt{#1}}%
4219 }{usage}{\thepage}%
4220 \IndexEntry{%
4221 \LevelSorted{#1}{\texttt{#1} option}%
4222 }{usage}{\thepage}%
4223 }
4224 % \end{macrocode}
4225 % \end{macro}
4226 %
4227 %
4228 % \begin{macro}{\describecsfamily}
4229 % \changes{prot2}{2000/07/14}{Renamed \cs{DescribeCSFamily} and
4230 % incorporated the code from \cs{XD@index@family}. (LH)}
4231 % \changes{prot2.1}{2000/11/18}{Using \cs{MakeSortKey}. (LH)}
4232 % The |\describecsfamily| command is for marking out sections in text
4233 % where a particular family of control sequences is described---just
4234 % like |\DescribeMacro| does for individual commands. To clarify what
4235 % I mean by a control sequence family, here are a couple of examples:
4236 % \begin{longtable}{l >{\raggedright}p{0.55\linewidth}}
4237 % |\c@|\meta{counter}\label{Tab:CS-families}&
4238 % countdef token for the |\count| register storing the
4239 % \LaTeX\ counter \meta{counter}\tabularnewline
4240 % |\ps@|\meta{pagestyle}&
4241 % macro storing settings for the pagestyle \meta{pagestyle}^^A
4242 % \tabularnewline
4243 % |\|\meta{enc}|/|\meta{fam}|/|\meta{ser}|/|\meta{sh}|/|\meta{sz}&
4244 % the fontdef token for the font which has encoding \meta{enc},
4245 % family \meta{fam}, series \meta{ser}, shape \meta{sh}, and
4246 % size \meta{sz} under NFSS\tabularnewline
4247 % |\|\meta{enc}|\|\meta{cmd}&
4248 % the macro containing the definition for encoding \meta{enc} of
4249 % the encoding-specific \LaTeX\ command |\|\meta{cmd}^^A
4250 % \tabularnewline
4251 % |\fps@|\meta{type}&
4252 % the default placement specifier for \LaTeX\ floats of type
4253 % \meta{type}\tabularnewline
4254 % |\l@|\meta{name}&
4255 % a macro which formats table of contents entries for items of
4256 % type \meta{name} (\texttt{chapter}, \texttt{section}, etc.)^^A
4257 % \tabularnewline
4258 % |\l@|\meta{language}&
4259 % the |\language| number \package{babel} has allocated for the
4260 % language \meta{language} (\texttt{english}, \texttt{french},
4261 % etc.)\tabularnewline
4262 % |\i-|\meta{int}&
4263 % the control sequence (either a mathchardef token or a macro)
4264 % which stores the value of the \package{fontinst} integer
4265 % \meta{int}
4266 % \end{longtable}
4267 %
4268 % The syntax for |\describecsfamily| is
4269 % \begin{quote}
4270 % |\describecsfamily|\marg{cs-fam specification}
4271 % \end{quote}
4272 % The \meta{cs-fam specification} includes only what would be put
4273 % between |\csname| and |\endcsname|; the |\describecsfamily| command
4274 % will add a backslash when printing the name. No special catcodes
4275 % will be in force in the argument, but the |#|, |$|, |&|, |_|, |^|,
4276 % and |~| characters present no problems even if they have their
4277 % ordinary catcodes. All spaces are seen as ASCII space and \TeX\ is
4278 % skipping spaces as usual. Characters with catcode 0, 1, 2, 5, 9, 14,
4279 % or 15 may however be problematic.
4280 % If you need to specify such a problematic character then you can do
4281 % so by writing |\PrintChar|\marg{code}, where \meta{code} is the
4282 % ASCII code for the character, as a valid \TeX\ number in the range
4283 % 0--255. In case you do not remember the ASCII code for some
4284 % character \meta{c}, there is no harm in specifying it as
4285 % |`\|\meta{c}, e.g. |\PrintChar{`\}}| for a right brace. It is even
4286 % possible to write |\PrintChar| commands for characters outside
4287 % visible ASCII (but those are typeset as |^^|-sequences).
4288 %
4289 % The variant parts in the control sequence names are specified as
4290 % \begin{quote}
4291 % |\meta|\marg{text}
4292 % \end{quote}
4293 % and these will be typeset exactly as in normal text. The arguments
4294 % of |\meta|s appearing in a \meta{cs-fam specification} are moving.
4295 % All control sequences other than |\PrintChar| and |\meta| in a
4296 % \meta{cs-fam specification} (and which do not appear in the argument
4297 % of a |\PrintChar| or |\meta|) are essentially treated as if they
4298 % had been |\string|ed.
4299 %
4300 % Apart from the above differences in treatment of the argument, the
4301 % |\describe|\-|cs|\-|family| command is similar to
4302 % |\DescribeMacro|---it prints the control sequence name in the margin
4303 % and makes a \texttt{usage} index entry.
4304 % \begin{macrocode}
4305 \NewDescribeCommand\describecsfamily{\XD@grab@harmless{}}{1}{%
4306 \GenericDescribePrint{%
4307 \MetaNormalfont\MacroFont\Bslash#1%
4308 }%
4309 \MakeSortKey\@tempa{#1}{\def\meta##1{(##1)}}%
4310 \IndexEntry{%
4311 \LevelSorted{\@tempa}{\texttt{\protect\MetaNormalfont\Bslash#1}}%
4312 }{usage}{\thepage}%
4313 }
4314 %</pkg>
4315 % \end{macrocode}
4316 % \end{macro}
4317 %
4318 %
4319 % As for |\NewMacroEnvironment|, I also give an example of an
4320 % application of |\NewDescribeCommand| which is much too special for
4321 % including in \package{xdoc} in general and therefore the code is
4322 % placed in a special module. I had originally written the code as part
4323 % of another package, but I removed it because I thought it was a bit
4324 % too special even for that context. The commentry below is kept
4325 % unchanged.\changes{prot2.1}{2000/09/16}{Additional
4326 % \cs{NewDescribeCommand} code example added. (LH)}
4327 %
4328 % \begin{quotation}
4329 %
4330 % I believe this feature is primarily of interest for MacOS programs,
4331 % but there might be sufficiently similar structures in other operating
4332 % systems to make it useful even in other contexts. Be as it may, what
4333 % the feature described here does is that it allows the user to put an
4334 % entry in the index for each resource in the code. This gives an easy
4335 % way of checking that no two resources are assigned the same id, even
4336 % though there is no mechanism for especially warning for such
4337 % collisions.
4338 %
4339 % \begin{macro}{\DescribeResource}
4340 % The main command available is
4341 % \begin{quote}
4342 % |\DescribeResource|\marg{type}\marg{id}\marg{text}
4343 % \end{quote}
4344 % \meta{type} is a four-character string. Most special characters are
4345 % treated as ordinary ones (very useful for |#|s), but the visible
4346 % ASCII characters |%|, |{|, |\|, and |}| retain their usual meaning.
4347 % To use such a troublesome character \meta{c} in a resource type,
4348 % write it as |\PrintChar{`\|\meta{c}|}|. \meta{id} is a \TeX\ number;
4349 % it will be used as the number of the resource. \meta{text} is normal
4350 % text that will be put in the index entry to describe the resource; it
4351 % seems a good idea to use the name of the resource for this. \meta{id}
4352 % and \meta{text} are read with normal \LaTeX\ catcodes. Note that
4353 % \meta{text} is a moving argument.
4354 %
4355 % |\DescribeResource| does two things---it prints the \meta{type} and
4356 % \meta{id} of the resource in the margin, and it writes an entry
4357 % \begin{quote}
4358 % \meta{type} resources:\\
4359 % \vadjust{}\qquad\meta{id}\\
4360 % \vadjust{}\qquad\qquad\meta{text}
4361 % \end{quote}
4362 % (plus a lot of formatting not shown here) to the \texttt{.idx} file.
4363 % The reference is for the page.
4364 %
4365 % The idea with advancing |\count@| like that when constructing the
4366 % index entry is to get a sort key for which lexicographic order equals
4367 % the wanted order. This would not be the case if the number was simply
4368 % written down. The current code maps numbers to six-digit positive
4369 % integers, but five-digits integers would be sufficient (a resource
4370 % \meta{id} is a signed 16-bits integer). The construction chosen
4371 % here furthermore puts the negative numbers after the positive ones.
4372 % \begin{macrocode}
4373 %<*rsrccmd>
4374 \NewDescribeCommand\DescribeResource{%
4375 \XD@grab@harmless\relax \XD@grab@marg \XD@grab@marg
4376 }{3}{%
4377 \GenericDescribePrint{#1%
4378 \textnormal{:\ifnum#2<\z@ \textminus\number-\else\number\fi#2}%
4379 }%
4380 \count@=#2\relax
4381 \advance \count@ 100000\ifnum \count@<\z@ 0\fi \relax
4382 \protected@edef\@tempa{%
4383 \noexpand\LevelSorted{\the\count@}{%
4384 \ifnum #2<\z@ \string\textminus \number-\else\number\fi#2%
4385 }%
4386 }%
4387 \IndexEntry{%
4388 \LevelSorted{#1 resources:}{\texttt{#1} resources:}%
4389 \@tempa
4390 \LevelSame{#3}%
4391 }{usage}{\thepage}%
4392 }
4393 %</rsrccmd>
4394 % \end{macrocode}
4395 % \end{macro}
4396 %
4397 % \end{quotation}
4398 %
4399 %
4400 % \section{The \cs{DocInclude} command}
4401 % \label{Sec:DocInclude}
4402 %
4403 % The code in this section is based on code from the \package{ltxdoc}
4404 % document class~\cite{ltxdoc} and it implements a command called
4405 % |\DocInclude|. Two implementations of this command are given: one
4406 % which is essentially that of \package{ltxdoc} (preserving all its
4407 % peculiarities), and one which is a reimplementation from scratch. The
4408 % default is to use the latter, but passing the \texttt{olddocinclude}
4409 % option to \package{xdoc} selects the former.
4410 %
4411 %
4412 % \subsection{Old implementation}
4413 %
4414 % It should be observed that this is not a complete implementation of the
4415 % |\Doc|\-|Include| command---it only redefines the \package{ltxdoc}
4416 % macros that need to be changed if the |\Doc|\-|Include| command is to
4417 % work with \package{xdoc} (it doesn't for example change the definition
4418 % of |\Doc|\-|Include| itself). Furthermore it doesn't define anything if
4419 % the \package{ltxdoc} document class hasn't been loaded, since then the
4420 % details of the definition of |\Doc|\-|Include| (even if it would be
4421 % defined) are unknown.
4422 %
4423 % \begin{macro}{\CodelineIndex}
4424 % \changes{prot2.1}{2000/10/08}{Using \cs{thecodelineno}. (LH)}
4425 % \begin{macro}{\filesep}
4426 % \changes{prot2.2}{2001/02/13}{Redefined to use
4427 % \cs{XD@page@compositor}. (LH)}
4428 % \begin{macro}{\@docinclude}
4429 % \package{ltxdoc} redefines |\codeline@wrindex| so that |\filesep| is
4430 % prepended to each codeline number that is written to the index file.
4431 % That redefinition has no effect unless the |\Codeline|\-|Index|
4432 % command is executed afterwards however, so there is no harm in having
4433 % |\Codeline|\-|Index| itself apply the corresponding change.
4434 % \begin{macrocode}
4435 %<*pkg>
4436 \@ifpackagewith{xdoc2}{olddocinclude}{%
4437 \@ifclassloaded{ltxdoc}{%
4438 \renewcommand\CodelineIndex{%
4439 \makeindex
4440 \let\XD@if@index=\@firstoftwo
4441 \codeline@indextrue
4442 \def\TheXDIndexNumber{\filesep\thecodelineno}%
4443 }%
4444 % \end{macrocode}
4445 % The |\filesep| macro is redefined so that the \package{docindex}
4446 % package~\cite{docindex} can use a |page_compositor| string different
4447 % from the default |-| simply by redefining |\XD@page@compositor|.
4448 % This redefinition has to be put in |\docincludeaux| since that macro
4449 % redefines |\filesep| too.
4450 % \begin{macrocode}
4451 \expandafter\def \expandafter\docincludeaux \expandafter{%
4452 \docincludeaux
4453 \gdef\filesep{\thepart\XD@page@compositor}%
4454 }
4455 % \end{macrocode}
4456 % The change to |\@docinclude| merely consists of inserting code for
4457 % writing an |External|\-|XRef|\-|Wrap| to the \texttt{.aux} file to
4458 % record the new value of the \texttt{part} counter.
4459 % \begin{macrocode}
4460 \def\@docinclude#1 {%
4461 \clearpage
4462 \if@filesw
4463 \immediate\write\@mainaux{\string\@input{#1.aux}}%
4464 \fi
4465 \@tempswatrue
4466 \if@partsw
4467 \@tempswafalse
4468 \edef\@tempb{#1}%
4469 \@for\@tempa:=\@partlist\do{%
4470 \ifx\@tempa\@tempb\@tempswatrue\fi
4471 }%
4472 \fi
4473 \if@tempswa
4474 \let\@auxout\@partaux
4475 \if@filesw
4476 \immediate\openout\@partaux #1.aux
4477 \immediate\write\@partaux{\relax}%
4478 \fi
4479 \part{#1.dtx}%
4480 \if@filesw
4481 \immediate\write\@partaux{\@percentchar\@percentchar
4482 ExternalXRefWrap {\filesep} {}%
4483 }%
4484 \fi
4485 {%
4486 \let\ttfamily\relax
4487 \xdef\filekey{%
4488 \filekey, \thepart={\ttfamily\currentfile}%
4489 }%
4490 }%
4491 \DocInput{#1.dtx}%
4492 \clearpage
4493 \@writeckpt{#1}%
4494 \if@filesw \immediate\closeout\@partaux \fi
4495 \else
4496 \@nameuse{cp@#1}%
4497 \fi
4498 \let\@auxout\@mainaux
4499 }
4500 }{}
4501 }{}
4502 % \end{macrocode}
4503 % \end{macro}\end{macro}\end{macro}
4504 %
4505 %
4506 % \subsection{New implementation}
4507 % \label{Ssec:New DocInclude}
4508 %
4509 % The default action of the second implementation is to be precisely an
4510 % |\include| variant of |\DocInput|, but in addition to that it also
4511 % has a (one-argument) hook called |\docincludeaux| which is executed
4512 % before a file is actually |\DocInput|ted, but after it has been
4513 % determined that it should be included, and this hook is only executed
4514 % for the files which should be |\include|d. This hook is normally
4515 % |\@gobble|, but passing the \texttt{fileispart} option to
4516 % \package{xdoc} redefines it to start a new part and set the pagestyle.
4517 %
4518 % \begin{macro}{\DocInclude}
4519 % \begin{macro}{\@docinclude}
4520 % Most of the code for the |\DocInclude| command is put in the
4521 % |\@docinclude| macro; |\DocInclude| simply checks that it hasn't
4522 % been nested. The main difference to |\include| is that a nested
4523 % |\DocInclude| becomes an error plus the corresponding |\DocInput|,
4524 % whereas a nested |\include| simply becomes an error. The rationale
4525 % for this is that it is probably closer to what was intended.
4526 %
4527 % The argument of |\@docinclude| is, oddly enough, space-delimited.
4528 % This is inherited from the |\@include| macro in the \LaTeX\ kernel,
4529 % where it is a hack to make sure that the part \texttt{.aux} file
4530 % that is opened for writing really gets the suffix \texttt{.aux} (in
4531 % the worst case, \TeX\ could start overwriting a \texttt{.tex} file
4532 % instead).
4533 % \begin{macrocode}
4534 \@ifpackagewith{xdoc2}{olddocinclude}{}{%
4535 \def\DocInclude#1{%
4536 \ifnum\@auxout=\@partaux
4537 \@latexerr{\string\include\space cannot be nested}{%
4538 Your \protect\DocInclude\space will be reduced to a
4539 \protect\DocInput.%
4540 }%
4541 \DocInput{#1.dtx}%
4542 \else \@docinclude#1 \fi
4543 }%
4544 % \end{macrocode}
4545 % The only things in this |\@docinclude| that are not precisely as in
4546 % |\@include| are the |\docincludeaux| and |\DocInput| commands.
4547 % \begin{macrocode}
4548 \def\@docinclude#1 {%
4549 \clearpage
4550 \if@filesw
4551 \immediate\write\@mainaux{\string\@input{#1.aux}}%
4552 \fi
4553 \@tempswatrue
4554 \if@partsw
4555 \@tempswafalse
4556 \edef\@tempb{#1}%
4557 \@for\@tempa:=\@partlist\do{%
4558 \ifx\@tempa\@tempb \@tempswatrue \fi
4559 }%
4560 \fi
4561 \if@tempswa
4562 \let\@auxout\@partaux
4563 \if@filesw
4564 \immediate\openout\@partaux #1.aux
4565 \immediate\write\@partaux{\relax}%
4566 \fi
4567 \docincludeaux{#1.dtx}%
4568 \DocInput{#1.dtx}%
4569 \clearpage
4570 \@writeckpt{#1}%
4571 \if@filesw \immediate\closeout\@partaux \fi
4572 \else
4573 \deadcycles\z@
4574 \@nameuse{cp@#1}%
4575 \fi
4576 \let\@auxout\@mainaux
4577 }%
4578 }{}
4579 % \end{macrocode}
4580 % \end{macro}\end{macro}
4581 %
4582 % \begin{option}{fileispart}
4583 % \begin{macro}{\docincludeaux}
4584 % The \texttt{fileispart} option works by (re)defining a couple of
4585 % macros, of which the |\doc|\-|include|\-|aux| macro is the most
4586 % important. Its syntax is
4587 % \begin{quote}
4588 % |\docincludeaux|\marg{filename}
4589 % \end{quote}
4590 % where \meta{filename} is the name of a file that will be inputted.
4591 % The \texttt{fileispart} definition of this is to set |\currentfile|
4592 % to the harmless character string of \meta{filename}, produce a
4593 % |\part| heading whose text is that \meta{filename}, add the
4594 % \meta{filename} to the |\filekey| macro, set the page style to
4595 % \texttt{docpart}, clear the |\filedate|, |\fileversion|, and
4596 % |\fileinfo| macros, and write an |External|\-|XRef|\-|Wrap|
4597 % XXR-command to the \texttt{.aux} file to record the new codeline
4598 % number prefix.
4599 % \begin{macrocode}
4600 \@ifpackagewith{xdoc2}{olddocinclude}{\iffalse}{
4601 \@ifpackagewith{xdoc2}{fileispart}{\iftrue}{
4602 \let\docincludeaux=\@gobble
4603 \iffalse
4604 }
4605 } % If fileispart and not olddocinclude then
4606 \def\docincludeaux#1{%
4607 \MakeHarmless\currentfile{#1}%
4608 \part{\texttt{\currentfile}}%
4609 \pagestyle{docpart}%
4610 \let\filedate\@empty
4611 \let\fileversion\@empty
4612 \let\fileinfo\@empty
4613 \protected@xdef\filekey{%
4614 \filekey, \thepart=\texttt{\currentfile}%
4615 }%
4616 \if@filesw
4617 \immediate\write\@partaux{\@percentchar\@percentchar
4618 ExternalXRefWrap {\thepart\XD@page@compositor} {}%
4619 }%
4620 \fi
4621 }%
4622 % \end{macrocode}
4623 % \end{macro}
4624 %
4625 % \begin{macro}{\CodelineIndex}
4626 % \changes{prot2.1}{2000/10/08}{Using \cs{thecodelineno}. (LH)}
4627 % The \texttt{fileispart} option also adds the \texttt{codelineno}
4628 % counter to the reset list for \texttt{part} and changes the format
4629 % of codeline numbers written to the index.
4630 % \begin{macrocode}
4631 \@ifclassloaded{ltxdoc}{}{\@addtoreset{codelineno}{part}}%
4632 \renewcommand\CodelineIndex{%
4633 \makeindex
4634 \let\XD@if@index=\@firstoftwo
4635 \codeline@indextrue
4636 \def\TheXDIndexNumber{\thepart\XD@page@compositor\thecodelineno}%
4637 }%
4638 % \end{macrocode}
4639 % \end{macro}
4640 %
4641 % \begin{macro}{\partname}
4642 % \begin{macro}{\thepart}
4643 % \begin{macro}{\IndexParms}
4644 % Finally there are a couple of macros which are redefined for
4645 % aesthetic rather than technical reasons. Passing the
4646 % \texttt{fileispart} option sets |\partname| to \texttt{File}, sets
4647 % |\thepart| to |\aalph{part}|, and adds a setting of pagestyle to
4648 % |\IndexParms|. (The pagestyle setting is added to
4649 % |\index@|\B|prologue| by \package{ltxdoc}, but I think
4650 % |\Index|\-|Parms| is more appropriate.)
4651 % \begin{macrocode}
4652 \def\partname{File}
4653 \def\thepart{\aalph{part}}
4654 \expandafter\def \expandafter\IndexParms
4655 \expandafter{\IndexParms \pagestyle{docindex}}
4656 % \end{macrocode}
4657 % \end{macro}\end{macro}\end{macro}
4658 %
4659 % In case the index formatting is handled by the \package{docindex}
4660 % package~\cite{docindex} (or its \LaTeXe\ incarnation
4661 % \package{docidx2e}), the above addition to |\Index|\-|Parms| won't
4662 % have any effect. Therefore \package{xdoc} also passes the
4663 % \texttt{use}\-\texttt{doc}\-\texttt{index}\-\texttt{ps} option on
4664 % to these packages.
4665 % \begin{macrocode}
4666 \PassOptionsToPackage{usedocindexps}{docindex}
4667 \PassOptionsToPackage{usedocindexps}{docidx2e}
4668 \fi
4669 % \end{macrocode}
4670 % \end{option}
4671 %
4672 % \begin{macro}{\ps@docpart}
4673 % \begin{macro}{\setfileinfo}
4674 % \begin{macro}{\XD@set@file@info}
4675 % The \texttt{docpart} pagestyle is for pages made from the
4676 % |\DocInclude|d files. The page footers contain the page number, the
4677 % part (file) number, and the current file name. It also contains the
4678 % file date and version if that information is available.
4679 %
4680 % \package{ltxdoc} uses |\GetFileInfo| to get the date and version
4681 % information, but that's a very peculiar practice. The data one wants
4682 % to present are about the file being typeset---typically the version
4683 % of the package that is documented in this file---whereas the
4684 % |\GetFileInfo| command really extracts information about
4685 % \emph{unpacked} classes, packages, and similar files---files that
4686 % contribute to the typesetting by defining commands, not by containing
4687 % text. Such information may be of interest for documents which contain
4688 % alternative code for incompatible versions of for example a package,
4689 % but it is of no use for printing version information as above since
4690 % the version of a package used for typesetting a \texttt{.dtx} file
4691 % need not be the version actually contained in that \texttt{.dtx}
4692 % file. Thus the only way to make this work is by doing as the \LaTeX\
4693 % kernel source and include |\ProvidesFile| commands for the
4694 % \texttt{.dtx} file in each such file, which is a rather peculiar use
4695 % of the |\ProvidesFile| command.
4696 %
4697 % The |\setfileinfo| command provides an equivalent feature in a less
4698 % roundabout way. It has the syntax
4699 % \begin{quote}
4700 % |\setfileinfo[|\meta{date}\verb*+ +\meta{version}\verb*+ +^^A
4701 % \meta{info}|]|
4702 % \end{quote}
4703 % and it sets |\filedate| to \meta{date}, |\fileversion| to
4704 % \meta{version}, and |\fileinfo| to \meta{info} if the optional
4705 % argument is present; if the optional argument is missing or contains
4706 % fewer than three words then the missing fields are set to |?|.
4707 %
4708 % \begin{macrocode}
4709 \@ifpackagewith{xdoc2}{olddocinclude}{}{%
4710 \def\ps@docpart{%
4711 \def\@oddfoot{%
4712 File: \texttt{\currentfile}%
4713 \ifx \filedate\@empty \else \ Date: \filedate\fi
4714 \ifx \fileversion\@empty \else \ Version: \fileversion\fi
4715 \hfill\thepage
4716 }%
4717 \if@twoside
4718 \def\@evenfoot{%
4719 \thepage\hfill
4720 File: \texttt{\currentfile}%
4721 \ifx \filedate\@empty \else \ Date: \filedate\fi
4722 \ifx \fileversion\@empty \else \ Version: \fileversion\fi
4723 }%
4724 \else \let\@evenfoot\@oddfoot \fi
4725 }
4726 % \end{macrocode}
4727 % The corresponding definition in \package{ltxdoc} (there it appears in
4728 % |\docincludeaux|) is peculiar in that the odd page footer is set
4729 % globally but the even page footer only locally.
4730 %
4731 % The definition of |\setfileinfo| follows that of |\GetFileInfo|
4732 % except for the fact that the |\relax|es have been replaced by
4733 % |\@empty|s.
4734 % \begin{macrocode}
4735 \newcommand\setfileinfo[1][]{%
4736 \edef\@tempa{#1}%
4737 \expandafter\XD@set@file@info \@tempa\@empty? ? \@empty\@empty
4738 }
4739 \def\XD@set@file@info#1 #2 #3\@empty#4\@empty{%
4740 \def\filedate{#1}%
4741 \def\fileversion{#2}%
4742 \def\fileinfo{#3}%
4743 }
4744 }{}
4745 % \end{macrocode}
4746 % The reason for making the argument of |\setfileinfo| optional is
4747 % that with the |\Provides|\-|File| practice one can (potentially) put
4748 % all date and version information in one place through tricks like
4749 % \iffalse
4750 %<*example>
4751 % \fi
4752 %\begin{verbatim}
4753 %% \begin{macrocode}
4754 %\ProvidesPackage{foobar}
4755 %% \end{macrocode}
4756 %% \ProvidesFile{foobar.dtx}
4757 % [2000/02/02 v1.0 Silly example package]
4758 %%
4759 %\end{verbatim}\iffalse
4760 %</example>
4761 % \fi
4762 % By making the argument of |\setfileinfo| optional, I make sure that
4763 % people who have used such tricks only have to replace the
4764 % |\ProvidesFile{foobar.dtx}| by |\setfileinfo|.
4765 % \end{macro}\end{macro}\end{macro}
4766 %
4767 %
4768 % \begin{macro}{\ps@docindex}
4769 % \begin{macro}{\filekey}
4770 % The \texttt{docindex} pagestyle is for the index in
4771 % \texttt{fileispart} documents. It prints a file key, which is a
4772 % list of all the included files and their corresponding part letters,
4773 % at the bottom of every page. The file key is stored in the macro
4774 % |\filekey|, which should have been constructed file by file as they
4775 % are included. To add a file to the file key, it is recommended that
4776 % you do
4777 % \begin{quote}
4778 % |\protected@xdef\filekey{\filekey, |\meta{entry for new file}|}|
4779 % \end{quote}
4780 % The \texttt{fileispart} version of |\docincludeaux| already does
4781 % this. The initial value of |\filekey| is |\@gobble| so that the
4782 % comma before the first entry is removed. The |\@empty| below is
4783 % there in case no entry has been inserted.
4784 % \begin{macrocode}
4785 % \@ifpackagewith{xdoc2}{olddocinclude}{}{%
4786 \def\ps@docindex{%
4787 \def\@oddfoot{%
4788 \parbox{\textwidth}{%
4789 \strut\footnotesize\raggedright
4790 \textbf{File Key:} \filekey\@empty
4791 }%
4792 }%
4793 \let\@evenfoot\@oddfoot
4794 }%
4795 \let\filekey\@gobble
4796 % }
4797 % \end{macrocode}
4798 % \end{macro}\end{macro}
4799 %
4800 % It should be observed that since |\ps@docindex| only sets the page
4801 % style locally, the page style will revert to its previous setting at
4802 % the end of the \texttt{theindex} environment. As that previous
4803 % setting is probably that of the \texttt{docpart} page style, you
4804 % might have to set the page style manually.
4805 %
4806 % \begin{macro}{\aalph}
4807 % \begin{macro}{\@aalph}
4808 % |\aalph| is a variant of |\alph| which continues with the upper case
4809 % letters for 27--52. It is defined by \package{ltxdoc}, so it is
4810 % merely provided here.
4811 % \begin{macrocode}
4812 \providecommand*\aalph[1]{\@aalph{\csname c@#1\endcsname}}
4813 \providecommand*\@aalph[1]{%
4814 \ifcase#1\or a\or b\or c\or d\or e\or f\or g\or h\or i\or
4815 j\or k\or l\or m\or n\or o\or p\or q\or r\or s\or
4816 t\or u\or v\or w\or x\or y\or z\or A\or B\or C\or
4817 D\or E\or F\or G\or H\or I\or J\or K\or L\or M\or
4818 N\or O\or P\or Q\or R\or S\or T\or U\or V\or W\or
4819 X\or Y\or Z\else\@ctrerr\fi
4820 }
4821 % \end{macrocode}
4822 % In \texttt{source2e.tex} one can see that \package{doc}'s standard
4823 % \texttt{gind.ist} index style file won't sort the 35th file (part
4824 % \texttt{I}) correctly since it causes \package{makeindex} to read an
4825 % \texttt{I} as ``upper case Roman numeral one'', but I doubt very
4826 % many people encounter that problem in their projects.
4827 % \end{macro}\end{macro}
4828 %
4829 % \begin{macro}{\XD@page@compositor}
4830 % \changes{prot2.2}{2001/02/13}{Macro added, other macros changed to
4831 % use it. (LH)}
4832 % The |\XD@page@compositor| macro contains the string which is put
4833 % between the parts of a composite number in the index; it
4834 % corresponds to the |page_compositor| parameter of
4835 % \package{makeindex}.
4836 % \begin{macrocode}
4837 \providecommand*\XD@page@compositor{-}
4838 % \end{macrocode}
4839 % \end{macro}
4840 %
4841 %
4842 %
4843 % \section{Miscellanea}
4844 %
4845 % \subsection{Some \LaTeXplus\ stuff}
4846 %
4847 % \begin{macro}{\BooleanFalse}
4848 % \begin{macro}{\BooleanTrue}
4849 % \begin{macro}{\NoValue}
4850 % These three macros are borrowed from the \package{xparse}
4851 % package~\cite{xparse}, where they work as the three values
4852 % \emph{boolean false}, \emph{boolean true}, and \emph{absence of
4853 % value} respectively. The definitions are taken from
4854 % \package{xparse} v\,0.17 (1999/09/10).
4855 % \begin{macrocode}
4856 \@ifundefined{BooleanFalse}{\def\BooleanFalse{TF}}{}
4857 \@ifundefined{BooleanTrue}{\def\BooleanTrue{TT}}{}
4858 \@ifundefined{NoValue}{\def\NoValue{-NoValue-}}{}
4859 % \end{macrocode}
4860 % By using these macros (rather than some homegrown set of macros
4861 % or tokens) for denoting these values here I hopefully simplify a
4862 % transition to \LaTeXplus, but I don't want to rely on \LaTeXplus\
4863 % since it hasn't been released yet.
4864 % \end{macro}\end{macro}\end{macro}
4865 %
4866 %
4867 % \subsection{The \cs{meta} command}
4868 %
4869 % A reimplementation which has already (as of v\,2.0k) found its way into
4870 % the \package{doc} package is the one that the |\meta| command is made
4871 % robust, but since some people might still have older
4872 % versions of \package{doc} and since that feature is needed for
4873 % |\describe|\-|cs|\-|family|, I apply it here too. First I check
4874 % whether the definition of |\meta| is the old non-robust definition,
4875 % and only apply the fix if it is.
4876 % \begin{macrocode}
4877 \begingroup
4878 \obeyspaces%
4879 \catcode`\^^M\active%
4880 \gdef\@gtempa{\begingroup\obeyspaces\catcode`\^^M\active%
4881 \let^^M\do@space\let \do@space%
4882 \def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\itshape}%
4883 \m@ta}%
4884 \endgroup
4885 \ifx \meta\@gtempa
4886 % \end{macrocode}
4887 %
4888 % \begin{macro}{\l@nohyphenation}
4889 % The new implementation needs a |\language| without any hyphenation
4890 % patterns. By switching to that language, one can inhibit
4891 % hyphenation in a piece of text regardless of what line-breaking
4892 % parameter settings are in force when the paragraph is actually
4893 % broken. This new language will be called \texttt{nohyphenation} and
4894 % it is only allocated if it isn't already known (since some
4895 % \package{babel} settings files already defines this |\language|).
4896 % \begin{macrocode}
4897 \@ifundefined{l@nohyphenation}{\newlanguage\l@nohyphenation}{}
4898 % \end{macrocode}
4899 % \end{macro}
4900 %
4901 % \begin{macro}{\meta}
4902 % \begin{macro}{\meta@font@select}
4903 % This is the definition of |\meta| from \package{doc} v\,2.0m. For
4904 % an explanation of the implementation, se a \texttt{doc.dtx} at least
4905 % that new or entry \texttt{latex/3170} in the \LaTeX\ bugs database.
4906 % \begin{macrocode}
4907 \DeclareRobustCommand\meta[1]{%
4908 \ensuremath\langle
4909 \ifmmode \expandafter \nfss@text \fi
4910 {%
4911 \meta@font@select
4912 \edef\meta@hyphen@restore
4913 {\hyphenchar\the\font\the\hyphenchar\font}%
4914 \hyphenchar\font\m@ne
4915 \language\l@nohyphenation
4916 #1\/%
4917 \meta@hyphen@restore
4918 }\ensuremath\rangle
4919 }
4920 % \end{macrocode}
4921 % \begin{macrocode}
4922 \let\meta@font@select=\itshape
4923 \fi
4924 % \end{macrocode}
4925 % \end{macro}\end{macro}
4926 %
4927 % \begin{macro}{\MetaNormalfont}
4928 % \changes{prot2}{2000/07/24}{Removed robustness; protected it
4929 % explicitly wherever needed instead. (LH)}
4930 % The |\MetaNormalfont| command redefines |\meta@font@select| to do a
4931 % |\normal|\-|font| before the |\itshape|. It is useful if |\meta| is
4932 % going to be used to make |\rmfamily| interjections in |\ttfamily|
4933 % text.
4934 % \begin{macrocode}
4935 \newcommand\MetaNormalfont{\def\meta@font@select{\normalfont\itshape}}
4936 % \end{macrocode}
4937 % \end{macro}
4938 %
4939 % \begin{macro}{\XD@harmless\meta}
4940 % This macro is needed for making |\meta| behave as described in the
4941 % argument of |\describe|\-|cs|\-|family|, i.e., in text which is
4942 % going to be converted into a harmless character string.
4943 % \begin{macrocode}
4944 \@namedef{XD@harmless\string\meta}#1{%
4945 \toks@=\expandafter{\the\toks@ \meta{#1}}%
4946 \XD@harmless@
4947 }
4948 % \end{macrocode}
4949 % \end{macro}
4950 %
4951 %
4952 % \subsection{The checksum feature}
4953 %
4954 % The checksum mechanism in \package{doc} is a remnant from the times
4955 % when file truncation was a common problem and a mechanism for
4956 % detecting this was a great help.\footnote{Even though I suspect that
4957 % the recommended use of it---to put the checking \cs{Finale} at the
4958 % end of the \texttt{.dtx} file---may have reduced its usefulness
4959 % dramatically, as that \cs{Finale} would have been the one thing that
4960 % surely disappears if the file is truncated.} Today its main usefulness
4961 % seems to lie in that it distinguishes versions of a file that are
4962 % ``being worked on'' (where the checksum probably doesn't match) from
4963 % versions of a file that are ``polished and ready for upload''
4964 % (someone has bothered to fix the checksum), and as it exists it might
4965 % as well stay. There is a problem however with files which do not
4966 % contain \TeX\ code, as simply counting backslashes quite probably
4967 % isn't a good (or even reasonable) way of forming a checksum for these
4968 % files (if the checksum turns out to be zero, \package{doc} will
4969 % complain no matter what you do).
4970 %
4971 % \begin{macro}{\check@checksum}
4972 % \changes{prot2.1}{2000/10/02}{Redefinition added. (LH)}
4973 % For that reason, the |\check@checksum| macro is redefined to only
4974 % write the ``no checksum'' warning to the log file if the checksum
4975 % hasn't been set.
4976 % \begin{macrocode}
4977 \renewcommand\check@checksum{%
4978 \relax
4979 \ifnum \check@sum=\z@
4980 \PackageInfo{doc}{This macro file has no checksum!\MessageBreak
4981 The checksum should be \the\bslash@cnt}%
4982 \else\ifnum \check@sum=\bslash@cnt
4983 \typeout{*******************}%
4984 \typeout{* Checksum passed *}%
4985 \typeout{*******************}%
4986 \else
4987 \PackageError{doc}{Checksum not passed (\the\check@sum
4988 <>\the\bslash@cnt)}{The file currently documented seems
4989 to be wrong.\MessageBreak Try to get a correct version.}%
4990 \fi\fi
4991 \global\check@sum\z@
4992 }
4993 % \end{macrocode}
4994 % \end{macro}
4995 %
4996 %
4997 % \subsection{The \cs{theCodelineNo} situation}
4998 % \label{Ssec:CodelineNo}
4999 %
5000 % \changes{prot2.1}{2000/10/08}{\cs{theCodelineNo} situation cleared
5001 % up. (LH)}
5002 % \package{doc} incorporates formatting of the value of the
5003 % \texttt{CodelineNo} counter in the |\theCodelineNo| macro, which is a
5004 % bit awkward since it prevents using this macro in making e.g.\ index
5005 % entries. To get around this, \package{xdoc} introduces the alternative
5006 % name \texttt{codelineno} for this counter so that |\thecodelineno| can
5007 % produce the value representation without formatting.
5008 %
5009 % \begin{macro}{\c@codelineno}
5010 % \begin{macro}{\cl@codelineno}
5011 % \begin{macro}{\p@codelineno}
5012 % \begin{macro}{\thecodelineno}
5013 % The control sequences connected to the \texttt{codelineno} counter
5014 % are |\let| so that they refer to the same |\count| register as the
5015 % \texttt{CodelineNo} counter. Note that \texttt{CodelineNo} isn't a
5016 % proper \LaTeX\ counter, so the macros |\cl@CodelineNo| and
5017 % |\p@CodelineNo| are undefined. |\thecodelineno| is set to the default
5018 % value for a new counter.
5019 % \begin{macrocode}
5020 \@ifundefined{c@codelineno}{}{%
5021 \PackageInfo{xdoc2}{Overwriting codelineno counter}%
5022 }
5023 \let\c@codelineno=\c@CodelineNo
5024 \let\cl@codelineno=\@empty
5025 \let\p@codelineno=\@empty
5026 \def\thecodelineno{\@arabic\c@codelineno}
5027 % \end{macrocode}
5028 % \end{macro}\end{macro}\end{macro}\end{macro}
5029 %
5030 % \begin{macro}{\PrintCodelineNo}
5031 % The |\PrintCodelineNo| command is the new recommended command for
5032 % printing the formatted form of the codeline number counter. People
5033 % who write their own \texttt{macrocode}-like environments should use
5034 % |\PrintCodelineNo| instead of \package{doc}'s |\theCodelineNo|.
5035 % \begin{macrocode}
5036 \newcommand\PrintCodelineNo{\reset@font\scriptsize\thecodelineno}
5037 % \end{macrocode}
5038 % \end{macro}
5039 %
5040 % \begin{macro}{\theCodelineNo}
5041 % Finally |\theCodelineNo| is redefined to reference
5042 % |\PrintCodelineNo|. This is done for the sake of backwards
5043 % compability; I didn't feel like redefining |\macro@code| just for
5044 % the sake of changing the |\theCodelineNo| into a |\PrintCodelineNo|).
5045 % \begin{macrocode}
5046 \def\theCodelineNo{\PrintCodelineNo}
5047 % \end{macrocode}
5048 % \end{macro}
5049 %
5050 % \begin{macrocode}
5051 %</pkg>
5052 % \end{macrocode}
5053 %
5054 %
5055 % \section{Problems and things to do}
5056 %
5057 % This section lists some problems that exist with the current
5058 % implementations of commands in \package{xdoc}. The list is rather
5059 % unstable---items are added as I realize there is a problem and removed
5060 % when I find a solution---an in parts it is rather esoteric since most
5061 % of the problems have only been found theoretically.
5062 %
5063 % \medskip
5064 %
5065 % One of the less well-known features of the |\verb| command is that
5066 % it automatically inhibits the known syntactic ligatures. There is
5067 % no such mechanism implemented for the harmless character strings,
5068 % so some (in \TeX\ \texttt{macrocode} uncommon) character sequences
5069 % (such as |!`|) may produce unwanted results. The quick hack to
5070 % circumvent this is to use the |\SetHarmState| command to mark one
5071 % of the characters involved as problematic, as the |\PrintChar|
5072 % command is implemented so that the character it prints will not be
5073 % involved in ligaturing or kerning. On the other hand, \package{doc}
5074 % does nothing to suppress syntactic ligatures in macro or environment
5075 % names when they are printed in the margin, so for that material the
5076 % \package{xdoc} implementation might actually improve things, although
5077 % it could perform worse for verbatim material in the index and list of
5078 % changes.
5079 %
5080 % \medskip
5081 %
5082 % Things to do and\slash or think about:
5083 % \begin{itemize}
5084 % \item
5085 % Examine how complicated it would be to convert the
5086 % |\PrintChar| commands for visible characters in a harmless
5087 % character string back to explicit characters, for possible use in
5088 % sort keys. (This could be used to ensure that visible characters
5089 % are sorted in strict ASCII order.)
5090 % \item
5091 % Should those ``letters'' which are commonly used as word
5092 % separators---in \LaTeX\ code mainly |@|---be ignored when sort
5093 % keys are being formed (just like the backslash is)? (This would
5094 % require a change in the implementation of the \texttt{macro}
5095 % environment.)
5096 %
5097 % A mechanism for doing this is included as of prototype version~2.1.
5098 % \item
5099 % Examine how much more efficient it would be to put temporary
5100 % additions to the index exclude list in a separate list instead of
5101 % the main list. This could be advantageous for deeply nested
5102 % \texttt{macro} environments, as \TeX\ will otherwise store as many
5103 % (almost identical and often rather long) copies of the exclude list
5104 % as there are nested environments.
5105 %
5106 % When asked about it, Frank Mittelbach didn't think there was
5107 % any gains worth mentioning in this. On the other hand it might be
5108 % worth investigating reimplementations that avoid calling |\trivlist|
5109 % at the beginning of each \texttt{macro}-like environment when they
5110 % are nested, since |\trivlist| does quite a lot of assignments.
5111 %
5112 % \item
5113 % In an automatically generated index one often faces the problem
5114 % that the entries at the innermost level are best formatted in one
5115 % way when there is only one, but in a completely different way when
5116 % there are several of them. To get optimal formatting in both cases,
5117 % one would like to let the |\item|, |\subitem|, |\subsubitem| or
5118 % corresponding macros detect the situation in this respect and
5119 % choose the optimal formatting at each case.
5120 %
5121 % A mechanism for this is implemented by the \package{docindex}
5122 % package.
5123 % \end{itemize}
5124 %
5125 %
5126 % \begin{thebibliography}{9}
5127 % \bibitem{ltxdoc}
5128 % David Carlisle:
5129 % \textit{The file \texttt{ltxdoc.dtx} for use with \LaTeXe},
5130 % The \LaTeX3 Project; ^^A , 1993~ff.
5131 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
5132 % \texttt{latex}\slash \texttt{base}\slash \texttt{ltxdoc.dtx}.
5133 % \bibitem{docindex}
5134 % Lars Hellstr\"om:
5135 % \textit{The \package{docindex} package}, 2001,
5136 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
5137 % \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash
5138 % \texttt{docindex.dtx}.
5139 % \bibitem{fontinst}
5140 % Alan Jeffrey, Sebastian Rahtz, Ulrik Vieth (and as of v\,1.9 Lars
5141 % Hellstr\"om): \textit{The \package{fontinst} utility}, v\,1.8~ff.,
5142 % documented source code,
5143 % \textsc{ctan}:\discretionary{}{}{\thinspace}^^A
5144 % \texttt{fonts}\slash \texttt{utilities}\slash
5145 % \texttt{fontinst}\slash \texttt{source}/
5146 % \bibitem{clsguide}
5147 % The \LaTeX3 Project:
5148 % \textit{\LaTeXe~for class and package writers},
5149 % The \LaTeX3 Project; ^^A , 1995~ff.
5150 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
5151 % \texttt{latex}\slash \texttt{base}\slash \texttt{clsguide.tex}.
5152 % \bibitem{doc}
5153 % Frank Mittelbach, B.~Hamilton Kelly, Andrew Mills, Dave Love, and
5154 % Joachim \mbox{Schrod}: \textit{The \package{doc} and
5155 % \package{shortvrb} Packages}, The \LaTeX3 Project; ^^A , 1993~ff.
5156 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
5157 % \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}.
5158 % \bibitem{xparse}
5159 % Frank Mittelbach, Chris Rowley, and David Carlisle: \textit{The
5160 % \package{xparse} package}, The \LaTeX3 Project, 1999. Currently
5161 % not available by anonymous FTP, but available by HTTP from
5162 % \texttt{www.latex-project.org} (look for ``experimental code'').
5163 % \end{thebibliography}
5164 %
5165 % \Finale
5166 \endinput