% \CheckSum{2952}
% 
% \iffalse meta-comment
% 
% This file may be distributed and/or modified under the conditions 
% of the LaTeX Project Public License, either version 1.2 of this 
% license or (at your option) any later version. The latest version 
% of this license is in
%    http://www.latex-project.org/lppl.txt
% and version 1.2 or later is part of all distributions of LaTeX 
% version 1999/12/01 or later.
% 
% Copyright 2000 2001 2002 Lars Hellstr\"om
% 
%<*driver>
\documentclass{ltxdoc}
\usepackage{array,longtable}

\makeatletter
\IfFileExists{xdoc2.sty}{%
   \usepackage[dolayout]{xdoc2}
   \NewMacroEnvironment{xrefcmd}{\XD@grab@harmless\relax}{1}%
      {\MacroFont##1 \normalfont XXR-command}%
      {\XDMainIndex{%
         \levelsorted{##1 (XXR-command)}{\texttt{##1} (XXR-command)}%
       }%
       \XDMainIndex{%
         \levelsame{XXR-commands:}\levelsorted{##1}{\texttt{##1}}%
      }}%
      {{##1}{XXR-command \texttt{##1}}}%
      {}%
   \@namedef{XD@harmless\string\Bslash}{%
      \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
         \csname XD@harmless@92\endcsname}%
      \XD@harmless@
   }%
   \IfFileExists{docidx2e.sty}{%
      \usepackage{docidx2e}%
      \AtEndDocument{%
         \typeout{*********************************}%
         \typeout{* Use docindex.ist when sorting *}%
         \typeout{* xdoc2.idx and xdoc2.glo. \@spaces\space*}%
         \typeout{*********************************}%
      }%
   }%
}{%
   \newenvironment{option}[1]{\trivlist\item[]}{\endtrivlist}%
   \newenvironment{xrefcmd}[1]{\trivlist\item[]}{\endtrivlist}%
   \@ifpackagelater{doc}{2000/05/20}{}{%
      \let\XD@fragile@meta=\meta
      \def\meta{%
         \ifx \protect\@typeset@protect
            \expandafter\futurelet \expandafter\@let@token
               \expandafter\XD@fragile@meta
         \else
            \noexpand\meta
         \fi
      }%
   }%
}
\makeatother

\providecommand\describecsfamily[1]{%
   \leavevmode
   \GenericDescribePrint{\MacroFont\Bslash#1}%
   \ignorespaces
}
\providecommand\describeoption[1]{%
   \leavevmode
   \GenericDescribePrint{\MacroFont#1 \normalfont option}%
   \ignorespaces
}
\providecommand\GenericDescribePrint[1]{%
   \marginpar{\raggedleft\strut #1}%
}
\providecommand\Bslash{\bslash}
\providecommand\DoNotIndexBy[1]{}
\DoNotIndexBy{@}
\DoNotIndexBy{@@}
\DoNotIndexBy{XD@}

\DeclareRobustCommand\package[1]{\textsf{#1}}
\DeclareRobustCommand\LaTeXplus{\LaTeXe$*$}
\newcommand\B{\penalty\exhyphenpenalty}
\ProvideTextCommandDefault\textminus{\textendash}

\hfuzz=15pt

\AlsoImplementation
\setcounter{IndexColumns}{2}

\CodelineIndex
\EnableCrossrefs
\RecordChanges

\begin{document}

\DocInput{xdoc2.dtx}

\PrintChanges
\PrintIndex

\end{document}
%</driver>
% \fi
% 
% \title{The \package{xdoc} package --- experimental reimplementations 
%    of features from \package{doc}, second~prototype}
% \author{Lars Hellstr\"om^^A
%    \thanks{E-mail: \texttt{Lars.Hellstrom@math.umu.se}}}
% \date{2003/07/07}
% \maketitle
% 
% \DoNotIndex{\,,\-,\/,\ ,\#,\%,\&,\\,\^,\|}
% \DoNotIndex{\@addtoreset,\@auxout,\@bsphack,\@cclv,\@ctrerr}
% \DoNotIndex{\@eha,\@empty,\@esphack,\@evenfoot}
% \DoNotIndex{\@firstofone,\@firstoftwo,\@for}
% \DoNotIndex{\@gobble,\@gobblefour,\@gobbletwo}
% \DoNotIndex{\@ifclassloaded,\@ifdefinable,\@ifpackagewith,\@ifundefined}
% \DoNotIndex{\@input,\@latexerr,\@mainaux,\@mparswitchtrue}
% \DoNotIndex{\@namedef,\@nameuse,\@ne,\@next,\@nil,\@oddfoot,\@partaux}
% \DoNotIndex{\@partlist,\@secondoftwo,\@sptoken}
% \DoNotIndex{\@tempswafalse,\@tempswatrue,\@totalleftmargin}
% \DoNotIndex{\@typeset@protect,\@unexpandable@protect}
% \DoNotIndex{\@vobeyspaces,\@writeckpt,\@xxxii}
% \DoNotIndex{\active,\addto@hook,\addtolength,\advance,\AtBeginDocument}
% \DoNotIndex{\baselineskip,\begingroup,\bgroup,\box,\boxmaxdepth}
% \DoNotIndex{\catcode,\char,\clearpage,\closeout,\color@begingroup}
% \DoNotIndex{\color@endgroup,\copy,\csname}
% \DoNotIndex{\deadcycles,\DeclareOption,\DeclareRobustCommand,\def}
% \DoNotIndex{\discretionary,\divide,\do@space,\dp}
% \DoNotIndex{\edef,\egroup,\else,\em,\endcsname,\endgroup,\ensuremath}
% \DoNotIndex{\escapechar,\everypar,\expandafter}
% \DoNotIndex{\fi,\font,\footnotesize,\frenchspacing,\futurelet}
% \DoNotIndex{\g@addto@macro,\gdef,\global}
% \DoNotIndex{\hb@xt@,\hbox,\hfill,\hss,\ht,\hyphenchar}
% \DoNotIndex{\if,\if@filesw,\if@inlabel,\if@mparswitch,\if@partsw}
% \DoNotIndex{\if@reversemargin,\if@tempswa,\ifcase,\ifcat,\iffalse}
% \DoNotIndex{\ifmmode,\ifnum,\ifodd,\iftrue,\ifx,\ignorespaces}
% \DoNotIndex{\immediate,\include,\indexentry,\input,\inputlineno,\item}
% \DoNotIndex{\itshape,\kern}
% \DoNotIndex{\labelsep,\langle,\language,\leavevmode,\let,\long,\loop}
% \DoNotIndex{\m@ne,\m@ta,\makelabel,\marginpar,\marginparsep,\maxdimen}
% \DoNotIndex{\MessageBreak,\multiply}
% \DoNotIndex{\NeedsTeXFormat,\newcommand,\newdimen,\newlanguage}
% \DoNotIndex{\nfss@text,\noexpand,\normalfont,\normalmarginpar,\number}
% \DoNotIndex{\obeyspaces,\openout,\or}
% \DoNotIndex{\PackageError,\PackageInfo,\PackageWarning}
% \DoNotIndex{\PackageWarningNoLine,\pagestyle,\paperwidth,\parbox,\part}
% \DoNotIndex{\ProcessOptions,\protect,\protected@edef,\protected@write}
% \DoNotIndex{\protected@xdef,\ProvidesPackage}
% \DoNotIndex{\raggedleft,\raggedright,\rangle,\relax,\renewcommand}
% \DoNotIndex{\repeat,\RequirePackage}
% \DoNotIndex{\setbox,\setlength,\sixt@@n,\space,\string,\strut,\strutbox}
% \DoNotIndex{\textasciicircum,\textasciitilde,\textbackslash,\textbar}
% \DoNotIndex{\textbf,\textbraceleft,\textbraceright,\textdollar}
% \DoNotIndex{\textgreater,\textless,\textquotedbl,\textquoteleft}
% \DoNotIndex{\textquoteright,\texttt,\textunderscore,\textvisiblespace}
% \DoNotIndex{\textwidth,\the,\topsep,\trivlist,\tw@}
% \DoNotIndex{\uccode,\unhbox,\unrestored@protected@xdef,\unvbox}
% \DoNotIndex{\uppercase}
% \DoNotIndex{\vbox,\vss,\vtop,\write,\xdef,\z@}
% 
% \changes{prot1}{2000/06/15}{Started writing first prototype. (LH)}
% \changes{prot2}{2000/07/13}{Began work on the second prototype. (LH)}
% 
% \begin{abstract}
%   The \package{xdoc} package contains reimplementations of some of 
%   the features found in the standard \LaTeX\ \package{doc} 
%   package~\cite{doc} by Mittelbach \emph{et~al. }The ultimate goals 
%   for these reimplementations are that the commands should be better, 
%   easily configurable, and be easy to extend, but this is only a 
%   second prototype implementation and nothing in it is guaranteed to 
%   be the same in the third prototype.\footnote{But there are no 
%   guarantees there will ever be a third prototype either.}
% \end{abstract}
% 
% \tableofcontents
% 
% 
% \section{Usage}
% 
% When I began working on this package I thought that there would be no 
% need for a usage section (at least on the prototype stage)---either you 
% are interested in using the new features and then you might just as 
% well read the descriptions of the commands in the implementation part 
% of this document (they are written as specifications of what the 
% commands do), or else you can simply insert a |\usepackage|\B|{xdoc2}| 
% in the preamble and see how things work a little better than when you 
% simply use \package{doc}---but with some features it became natural 
% to introduce incompatible changes and some new features ought to be 
% mentioned. Hence I wrote a short section on usage after all.
% 
% It is my intention that this document will eventually evolve into the 
% source for a package \package{xdoc}\footnote{The name \package{doc2} 
% has also been discussed; we'll see when we get there.} which will 
% either build on the \package{doc} package and provide better 
% implementations of many of its features, or replace it completely, 
% but this document is still only the source for a prototype for that 
% package. As I believe that the need for some improvement in this area 
% is rather large however, I have decided to release this prototype so 
% that other people can use it in their documents or create packages that 
% are based on it. In doing so, one must of course bear in mind that this 
% prototype needs not be compatible with the final \package{xdoc} 
% package, and to overcome most incompatibility problems I therefore 
% release it under the variant name \package{xdoc2}. This way, documents 
% based on this prototype can still be typeset using the package they 
% were written for long after the next \package{xdoc} prototype (or final 
% version) is released.
% 
% Thus although this document frequently speaks of \package{xdoc}, you 
% might just as well read it as \package{xdoc2}.
% 
% 
% \subsection{Changes to old features}
% 
% Whereas \package{doc} more or less assumes that all pages have the 
% same layout, \package{xdoc} takes measures to ensure that the 
% \package{doc} features support two-sided document designs. If the 
% left margin has been widened to better accommodate long macro names 
% however (like for example the \package{ltxdoc} document class does), 
% then you may find that the outer margin on right (odd) pages is too 
% narrow for printing macro names in. The remedy for this is the
% \GenericDescribePrint{\MacroFont dolayout \normalfont option}^^A
% \SortIndex{dolayout}{\texttt{dolayout} option\encapchar 
% usage}\texttt{dolayout} option; in two-sided mode it causes 
% \package{xdoc} to recompute the |\oddsidemargin| so that the outer 
% margin has the same size on right pages as it previously did on left 
% pages. In documents which are not processed in two-sided mode the 
% \texttt{dolayout} option has no effect.
% 
% |\DocInput| has been changed to not make percent a comment character 
% upon return unless it was before the |\DocInput|. This makes |\DocInput| 
% nestable and I recommend that \texttt{.dtx} files which input other 
% \texttt{.dtx} files use |\DocInput| for this.
% 
% The |\DocInclude| command, which is defined by the \package{ltxdoc} 
% document class rather than \package{doc}, is also by default 
% redefined in an incompatible manner by \package{xdoc}, but you can 
% stop \package{xdoc} from making incompatible changes if you pass it the 
% option \GenericDescribePrint{\MacroFont olddocinclude \normalfont
% option}\SortIndex{olddocinclude}{\texttt{olddocinclude} option^^A
% \encapchar usage}\texttt{olddocinclude}. The main incompatibility 
% lies in that the default redefinition of |\DocInclude| behaves purely 
% as an |\include| command which |\DocInput|s a \texttt{.dtx} file rather 
% than merely |\input|ting a \texttt{.tex} file---you must pass the 
% \GenericDescribePrint{\MacroFont fileispart \normalfont option}^^A
% \SortIndex{fileispart}{\texttt{fileispart} option\encapchar 
% usage}\texttt{fileispart} option to \package{xdoc} to get the |\part| 
% headings etc.\ for each new file---but there are also minor changes 
% in the appearance of these headings, in how page styles are set, and 
% in how the information presented in the page footer is obtained.
% 
% Other changes are as far as I can tell minor and within the bounds of 
% expected behaviour, but code that relies on the implementation of some 
% feature in \package{doc} may of course behave differently or break 
% completely. Note in particular that the formats of the internal 
% \package{doc} variables |\saved@macroname|, |\macro@namepart|, and 
% |\index@excludelist| have changed completely (see 
% Section~\ref{Sec:Changes}, Subsection~\ref{Ssec:Scanning macrocode}, 
% and Subsection~\ref{Ssec:Index-exclude} respectively)---hence any hack 
% involving one of these must be revised before it is used with 
% \package{xdoc}. These are however exceptions; in my experience the most 
% noticeable changes not listed above are that the index exclude 
% mechanism actually works for control sequences whose names consist of 
% a single non-letter and that symbols get sorted in a different order.
% 
% 
% \subsection{Some notable new features}
% 
% The main new feature is the \DescribeMacro\NewMacroEnvironment
% |\NewMacroEnvironment| command, which defines a new \texttt{macro}-like 
% environment. The command offers complete control of the argument 
% structure, the formatting of the marginal heading, the code for making 
% index entries, and the change entry sorting and formatting, but the 
% syntax is too complex to explain here. Those who are interested in 
% using it should read Section~\ref{Sec:Macro-environments}. In 
% particular, Subsections~\ref{Ssec:Macro&environment}--^^A
% \ref{Ssec:More macros} contain several examples of how it can be 
% used. In addition to using |\New|\-|Macro|\-|Environment| for 
% redefining the \DescribeEnv{macro}\texttt{macro} and 
% \DescribeEnv{environment}\texttt{environment} environments, 
% \package{xdoc} also defines an \DescribeEnv{option}\texttt{option} 
% environment (which is intended for document class and package 
% options) and a \DescribeEnv{switch}\texttt{switch} environment (which 
% is intended for switches defined using |\newif|; the argument should 
% not include the |\if|).
% 
% There is also a companion command \DescribeMacro\NewDescribeCommand
% |\NewDescribeCommand| which defines new commands similar to 
% |\Describe|\-|Macro| and |\Describe|\-|Env|. The syntax of 
% |\New|\-|Describe|\-|Command| is also too complex to explain here, so 
% I have to refer readers who want to use it to Section~^^A
% \ref{Sec:Describing}. Two more commands which are defined in that 
% section are \DescribeMacro\describeoption|\describe|\-|option|, which 
% is the \texttt{describe}\dots\ companion of the \texttt{option} 
% environment, and \DescribeMacro\describecsfamily
% |\describe|\-|cs|\-|family| which is meant for describing control 
% sequence families (see the table on page~\pageref{Tab:CS-families} for 
% examples of what I mean). The argument of this latter command is simply 
% the material you would put between |\csname| and |\endcsname|. Variant 
% parts are written as |\meta|\B\marg{text} and print as one would expect 
% them to (but notice that the \meta{text} is a moving argument) whereas 
% most other characters can be written verbatim without any special 
% quoting (but |\|, |{|, |}|, and |%| need quoting; see the comments to 
% the definition of |\describe|\-|cs|\-|family| for information on how 
% to do that).
% 
% The \DescribeMacro\DoNotIndexBy|\DoNotIndexBy| command tells the 
% commands that make index entries for macros to ignore a certain 
% character sequence when the index entries are sorted. The 
% |\DoNotIndexBy| command takes one argument: the character sequence to 
% ignore. If |\DoNotIndexBy| is used more than once then the indexing 
% commands will look for, and if it finds it ignore, each of the 
% character sequences given to it, starting with the one specified last.
% 
% It has already been mentioned that the |\DocInclude| command has been 
% changed. What has not been mentioned is its companion 
% \DescribeMacro\setfileinfo|\setfileinfo|, 
% which the partfiles should use for setting the date and version 
% information presented in the page footer, but that is explained in 
% detail in Subsection~\ref{Ssec:New DocInclude}.
% 
% Finally there is a new variant of the |\changes| command which is 
% intended for changes that, although not limited to a single macro and 
% thus being ``general'' changes in the \package{doc} terminology, affect 
% only a few (probably widely dispersed) macros (or whatever). The basic 
% idea is that you can define a change with a specific version, date, 
% and text using the \DescribeMacro{\definechange}|\definechange| command 
% and then recall those parameters later using the 
% \DescribeMacro{\usechange}|\usechange| command. Primarily this ensures 
% that the entry texts are identical so that \package{makeindex} will 
% combine them into one entry, but it is also specified which macro 
% was changed at which page. See Section~\ref{Sec:Changes} for more 
% details. Another new feature concerning |\changes| is that there is 
% now support for sorting version numbers according to mathematical 
% order rather than ASCII order. Traditionally the version numbers 
% \texttt{2}, \texttt{11}, and \texttt{100} would have been sorted so 
% that \texttt{100}${}<{}$\texttt{11}${}<{}$\texttt{2}, but if they are 
% entered as \DescribeMacro{\uintver}|\uintver{2}|, |\uintver{11}|, and 
% |\uintver{100}| then they will be sorted as 
% \texttt{2}${}<{}$\texttt{11}${}<{}$\texttt{100}. The argument of 
% |\uintver| must be a \TeX\ \meta{number}.
% 
% \medskip
% 
% \package{xdoc} also contains several features which are of little use 
% as direct user commands, but which can simplify the definitions of other 
% commands. The foremost of these are the `harmless character strings', 
% which can be seen as a datatype for (short pieces of) verbatim text. 
% \TeX\ typesets a harmless character string in pretty much the same way 
% as the corresponding string of `other' tokens, but the harmless 
% character string can also be written to file and read back arbitrarily 
% many times without getting garbled, it doesn't make \package{makeindex} 
% choke, and it survives being fed to a |\protected@edef|. The most 
% important commands related to harmless character strings are 
% \DescribeMacro\PrintChar|\PrintChar|, which is used for representing 
% problematic characters, and \DescribeMacro\MakeHarmless|\MakeHarmless|, 
% which converts arbitrary \TeX\ code to the corresponding harmless 
% character string.
% 
% The superfluity of indexing commands in \package{doc} has been 
% replaced by the single command \DescribeMacro\IndexEntry|\IndexEntry|, 
% which has been designed with the intention that it should provide a 
% clear interface between the user level macros and the index sorting 
% program. It takes three arguments: the index entry specification, the 
% name of the encapsulation scheme that should be used, and the number to 
% put in the index. The index entry specification is a sequence of 
% |\LevelSame| and\slash or |\LevelSorted| commands, which have the 
% respective syntaxes
% \begin{quote}
%   \DescribeMacro\LevelSame|\LevelSame|\marg{text}\\
%   \DescribeMacro\LevelSorted|\LevelSorted|\marg{sort key}\marg{text}
% \end{quote}
% Each such command specifies one level of the index entry. In the case of 
% |\LevelSorted|, the \meta{text} is what will be written in the sorted 
% index at that level and \meta{sort key} is what the index-sorting 
% program should look at when sorting the entry (at that level). In the 
% case of |\LevelSame|, the \meta{text} is used both as sort key and 
% contents of entry in the sorted index. The first command is for the 
% topmost level and each subsequent command is for the next sublevel. 
% The complete description appears in Subsection~\ref{Ssec:IndexEntry}.
% 
% \package{xdoc} also contains support for external cross-referencing 
% programs (see Subsection~\ref{Ssec:XXR} for details) and a system for 
% determining whether a piece of text falls on an even or an odd page 
% (see Section~\ref{Sec:Twoside} for details). I expect that the latter 
% system will eventually migrate out of \package{xdoc}, either to a 
% package of its own, or into oblivion because the \LaTeXplus\ output 
% routine makes it obsolete.
% 
% 
% \subsection{The \package{docindex} package}
% 
% As of prototype version 2.2, the \package{xdoc} package has a companion 
% package \package{docindex}~\cite{docindex} which provides improved 
% formatting of the index and list of changes. \package{xdoc} works fine 
% without \package{docindex}, however.
% 
% 
% \subsection{A note on command names}
% 
% The \package{doc} package defines several commands with mixed-case 
% names which (IMHO) should really have all-lower-case names (according 
% to the rule of thumb spelled out in \cite[Ssec.~2.4]{clsguide}) since 
% people use them in the capacity of being the author of a \texttt{.dtx} 
% file rather than in the capacity of being the writer of a class or 
% package. The names in question are
% \begin{longtable}{ll}
%   \textbf{Name in \package{doc}}& \textbf{Better (?) name}\endhead
%   \cs{AlsoImplementation}& \cs{alsoimplementation}\\
%   \cs{CharacterTable}& \cs{charactertable}\\
%   \cs{CharTableChanges}& \cs{chartablechanges}\\
%   \cs{CheckModules}& \cs{checkmodules}\\
%   \cs{CheckSum}& \cs{checksum}\\
%   \cs{CodelineIndex}& \cs{codelineindex}\\
%   \texttt{CodelineNo} (counter)& \texttt{codelineno}\\
%   \cs{CodelineNumbered}& \cs{codelinenumbered}\\
%   \cs{DeleteShortVerb}& \cs{deleteshortverb}\\
%   \cs{DescribeEnv}& \cs{describeenv}\\
%   \cs{DescribeMacro}& \cs{describemacro}\\
%   \cs{DisableCrossrefs}& \cs{disablecrossrefs}\\
%   \cs{DocInput}& \cs{docinput}\\
%   \cs{DoNotIndex}& \cs{donotindex}\\
%   \cs{DontCheckModules}& \cs{dontcheckmodules}\\
%   \cs{EnableCrossrefs}& \cs{enablecrossrefs}\\
%   \cs{Finale}& \cs{finale}\\
%   \texttt{GlossaryColumns} (counter)& \texttt{glossarycolumns}\\
%   \cs{GlossaryPrologue}& \cs{glossaryprologue}\\
%   \texttt{IndexColumns} (counter)& \texttt{indexcolumns}\\
%   \cs{IndexInput}& \cs{indexinput}\\
%   \cs{IndexPrologue}& \cs{indexprologue}\\
%   \cs{MakePrivateLetters}& \cs{makeprivateletters}\\
%   \cs{MakeShortVerb}& \cs{makeshortverb}\\
%   \cs{OnlyDescription}& \cs{onlydescription}\\
%   \cs{PageIndex}& \cs{pageindex}\\
%   \cs{PrintChanges}& \cs{printchanges}\\
%   \cs{PrintIndex}& \cs{printindex}\\
%   \cs{RecordChanges}& \cs{recordchanges}\\
%   \cs{SortIndex}& \cs{sortindex}\\
%   \cs{SpecialEscapechar}& \cs{specialescapechar}\\
%   \texttt{StandardModuleDepth} (counter)& \texttt{standardmoduledepth}\\
%   \cs{StopEventually}& \cs{stopeventually}
% \end{longtable}
% \noindent With the exception for \texttt{CodelineNo},\footnote{Where I 
% recommend using \texttt{codelineno} instead of \texttt{CodelineNo}, 
% \cs{PrintCodelineNo} instead of \cs{theCodelineNo}, and 
% \cs{thecodelineno} instead of \cs{number}\cs{c@CodelineNo}; see 
% Subsection~\ref{Ssec:CodelineNo}.} I haven't changed any of the 
% \package{doc} names in this \package{xdoc} prototype, nor introduced any 
% of the ``better names'' as alternatives, but I think the matter should 
% be given a bit of thought during the future development of 
% \package{doc}\slash \package{xdoc}. 
% 
% For completeness, I should also remark that there are several macros 
% that \package{doc} gives mixed-case names which I haven't listed above. 
% The logo command names have special capitalizing rules by tradition. 
% Some macros and named registers---for example |\Docstyle|\-|Parms|, 
% |\Index|\-|Parms|, |\Macro|\-|Font|, |\Macro|\-|Topsep|, 
% |\Make|\-|Percent|\-|Ignore|, and |\Print|\-|Macro|\-|Name|---are part 
% of the package or document class writer's interface to \package{doc}, 
% although I cannot claim it to be obvious that for example 
% |\Index|\-|Parms| and the \texttt{IndexColumns} counter should belong 
% to different classes here (but several of these control sequences will 
% probably disappear from the interface in \LaTeXplus\ anyway, so the 
% problem isn't that important). The |\Special|\dots\B|Index| commands 
% (and their even more special variants, such as 
% |\Left|\-|Brace|\-|Index|) are internal commands rather than user level 
% commands. Finally there is the |\Get|\-|File|\-|Info| command, which I 
% doubt there is any point in having.
% 
% 
% \StopEventually{}
% 
% 
% \subsection{\package{docstrip} modules}
% 
% The \package{docstrip} modules in \texttt{xdoc2.dtx} are:
% \begin{description}
%   \item[\textsf{pkg}]
%     This module directive surrounds the code for the \package{xdoc} 
%     package.
%   \item[\textsf{driver}]
%     The driver.
%   \item[\textsf{internals}]
%     This module contains an alternative replacement text for the 
%     |\Print|\-|Visible|\-|Char| command that uses ``\LaTeX\ internal 
%     character representation'' (i.e., as much as possible 
%     encoding-specific commands---|\text|\textellipsis\ commands and 
%     the like) rather than the primitive |\char| command for 
%     typesetting visible characters. 
%     It is provided as a separate module mainly for compability with 
%     prototype version~2.0, as this alternative definition can (as of 
%     prot.\,2.1) be chosen by passing the option 
%     \describeoption{notrawchar}\texttt{notrawchar} to \package{xdoc}.
%   \item[\textsf{economical}]
%     There is little point in storing the harmless representations of 
%     the 161 non-visible-ASCII characters as these representations are 
%     always the same and can be formed on the fly whenever they are 
%     needed. The \textsf{economical} modules contain some alternative 
%     code which makes use of this fact to reduce the number of control 
%     sequences used for storing the table of harmless representations. 
%     The \Module{economical} module appears inside the \Module{pkg} 
%     module.
%   \item[\textsf{xdoc2}]
%     This module contains code for compability with previous releases 
%     of \package{xdoc2}. It will not be included in \package{xdoc3} 
%     or \package{xdoc} (whichever is the next major version).
%   \item[\textsf{enccmds}]
%     This module contains the code for defining two \texttt{macro}-like 
%     environments for encoding-specific commands. These are not included 
%     in the \package{xdoc} package since so few \texttt{.dtx} files 
%     define encoding-specific commands.
%   \item[\textsf{rsrccmd}]
%     Similar to the \textsf{enccmds} module, but demonstrates the 
%     |\New|\-|Describe|\-|Command| command instead.
%   \item[\textsf{example}]
%     This surrounds some code which to \package{docstrip} looks like it 
%     should be copied, but isn't meant to.
% \end{description}
% 
% 
% 
% \section{Initial stuff}
% 
% First there's the usual |\NeedsTeXFormat| and |\ProvidesPackage|.
%    \begin{macrocode}
%<*pkg>
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesPackage{xdoc2}[2003/07/06 prot2.5 doc reimplementation package]
%    \end{macrocode}
% 
% \subsection*{Options}
% 
% The first option has to do with the page layout. 
% Although \package{doc} itself doesn't modify any of the main layout 
% parameters, it is well known that using it does tend to restrict 
% one's choices in terms of document layout. In particular the 
% \texttt{macro} and \texttt{environment} environments require a rather 
% large left margin since they will otherwise print long macro names 
% partially outside the paper. It is furthermore hard to decrease the 
% |\textwidth| as it should be wide enough to contain about 70 columns of 
% |\MacroFont| text. Thus the only solution is to do as the 
% \package{ltxdoc}~\cite{ltxdoc} document class and enlarge the left 
% margin at the expense of the right. 
% 
% The resulting layout has a left--right asymmetry with the main galley 
% (the text rectangle) on the right and a very wide left margin (in 
% which marginal headings and marginal notes appears). Although this 
% layout is not uncommon in technical manuals, it is inappropriate for 
% two-sided designs since the vertical line at which the two pages of a 
% spread meet becomes the natural vertical symmetry axis for the entire 
% spread and it breaks this symmetry to let the left margin be the 
% widest on all pages. It would look better to always let the outer 
% margin be the largest.
% 
% \begin{option}{dolayout}
% \begin{macro}{\oddsidemargin}
%   The \texttt{dolayout} option modifies |\oddsidemargin| so that 
%   spreads are symmetric around the center in two-sided mode. As size 
%   of the outer margin is taken the size of the left margin on left 
%   (even) pages, i.e., |\evensidemargin|${}+1\,\mathrm{in}$.
%   
%   In one-sided mode, the \texttt{dolayout} option does nothing.
%    \begin{macrocode}
\DeclareOption{dolayout}{%
   \if@twoside
      \setlength\oddsidemargin{\paperwidth}
      \addtolength\oddsidemargin{-\textwidth}
      \addtolength\oddsidemargin{-\evensidemargin}
      \addtolength\oddsidemargin{-2in}
   \fi
}
%    \end{macrocode}
% \end{macro}\end{option}
% 
% \begin{option}{olddocinclude}
% \begin{option}{fileispart}
%   The \texttt{olddocinclude} and \texttt{fileispart} options are 
%   related to the |\DocInclude| command defined by the \package{ltxdoc} 
%   document class. Some of the code related to that command relies on 
%   modifying the \package{doc} internal macro |\codeline@wrindex|, but 
%   that has no effect with \package{xdoc} so in order to get the 
%   expected results one has to reimplement the |\DocInclude| command as 
%   well. The \texttt{olddocinclude} and \texttt{fileispart} options 
%   control how this should be done.
%   
%   If the \texttt{olddocinclude} option is passed to \package{xdoc} 
%   then only the parts of the implementation of |\DocInclude| which 
%   must be altered to make the command work with the \package{xdoc} 
%   implementation of indexing and cross-referencing are changed. These 
%   redefinitions will furthermore only be made if the \package{ltxdoc} 
%   document class has been loaded; nothing is done if the 
%   \texttt{olddocinclude} option is passed and \package{ltxdoc} hasn't 
%   been loaded. Passing the \texttt{olddocinclude} option can be 
%   considered as requesting a ``compatibility mode'' for |\DocInclude|.
%   
%   If the \texttt{olddocinclude} option is not passed then the 
%   |\DocInclude| command is reimplemented from scratch, regardless of 
%   whether some definition of it has already been given or not. The 
%   basis of this reimplementation is the observation that the 
%   |\DocInclude| command of \package{ltxdoc} really does two quite 
%   distinct things at once---it is an |\include| command which 
%   |\DocInput|s files rather than |\input|ting them, but it also starts 
%   a new |\part|, sets the pagestyle, and changes how the values of 
%   some counters are typeset. This latter function is by default 
%   disabled in the \package{xdoc} implementation of |\DocInclude|, but 
%   passing the \texttt{fileispart} option enables it.
%   
%   There is no code for these two options here, as it is rather long; 
%   instead that code appears in Section~\ref{Sec:DocInclude}. The 
%   |\Pass|\-|Options|\-|To|\-|Package| commands make sure that these 
%   options are registered as local options for \package{xdoc}, so that 
%   one can test for them using |\@if|\-|package|\-|with| below.
%    \begin{macrocode}
\DeclareOption{olddocinclude}{%
   \PassOptionsToPackage{\CurrentOption}{xdoc2}%
}
\DeclareOption{fileispart}{%
   \PassOptionsToPackage{\CurrentOption}{xdoc2}%
}
%    \end{macrocode}
% \end{option}\end{option}
%
% \changes{prot2.5}{2003/07/06}{Reregeristing options in case
%   they were global. (LH)}
% 
% \begin{option}{notrawchar}
%   The \texttt{notrawchar} option controls how the |\PrintVisibleChar| 
%   command is defined, and thereby what method is used for typesetting 
%   visible characters in e.g.\ macro names. The default is to use the 
%   |\char| primitive (which is better for \texttt{T1}-encoded fonts and 
%   non-italic \texttt{OT1}-encoded typewriter fonts), but the 
%   \texttt{notrawchar} option causes things to go via the ``\LaTeX\ 
%   internal character representation'' instead (which is necessary 
%   for e.g.\ \texttt{OT1}-encoded non-typewriter fonts).
%   
%   There is no code for this option here; instead that code is found 
%   in the definition of |\Print|\-|Visible|\-|Char|.
%    \begin{macrocode}
\DeclareOption{notrawchar}{%
   \PassOptionsToPackage{\CurrentOption}{xdoc2}%
}
%    \end{macrocode}
% \end{option}
% 
% 
% Then options are processed.
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
% And finally the \package{doc} package is loaded.
%    \begin{macrocode}
\RequirePackage{doc}
%    \end{macrocode}
% 
% 
% \section{Character strings}
% 
% A source of much of the complexity in \package{doc} is that it has to 
% be able to deal with rather arbitrary strings of characters (mainly 
% the names of control sequences). Once the initial problems with 
% characters having troublesome catcodes have been overcome however, it 
% is usually no problem to manage such things in \TeX. \package{doc} 
% does however complicate things considerably by also putting these 
% things in the index and list of changes. Not only must they then be 
% formatted so that the \package{makeindex} program doesn't choke on 
% them, but they must also be wrapped up in code that allows \TeX\ to 
% make sense of them when they are read back. \package{doc} manages the 
% \package{makeindex} problems mainly by allowing the user to change what 
% characters are used as \package{makeindex} metacharacters and the 
% reading back problem by making abundant use of |\verb|.
% 
% All this relies on that the author of a document is making sure that 
% the metacharacters aren't used for anything else. If for example the 
% |\verbatimchar| (by default |+|) is one of the ``private letters'' 
% then names of control sequences containing that character will be 
% typeset incorrectly because the |\verb| used to typeset it is 
% terminated prematurely---control sequence names such as `|\lost+found|' 
% will be typeset as `|\lost|found+'. On top of that, one also has to 
% make sure that the font used for typesetting these |\verb| sections 
% contains all the characters needed.
% 
% For \package{xdoc}, I have chosen a completely different approach. 
% Instead of allowing the strings (after they have converted to the 
% internal format) to contain \TeX\ character tokens with arbitrary 
% character codes, they may only contain \TeX\ character tokens which 
% are unproblematic---the normal catcode should be 11 (letter) or 12 
% (other), they should not be outside visible ASCII, and they may not 
% be one of the \package{makeindex} metacharacters. All other characters 
% are represented using a robust command which takes the character code 
% (in decimal) as the argument. This takes care of all ``moving 
% argument'' type problems that may occur.
% 
% An important observation about these character strings is that 
% they are strings of \emph{input} characters. This means that rather 
% than using the characters in some special font for typesetting 
% control sequences like |\^^M| (recall that the |^^| substitutions 
% take place before tokenization), one should typeset them using only 
% visible ASCII characters. (After all, that's the only way they are 
% written in \TeX\ code.) The default definition is to typeset 
% invisible characters as precisely the |^^|-sequences that \TeX\ 
% normally uses for these characters when they are written to a file.
% 
% 
% \subsection{Typesetting problematic characters}
% 
% \begin{macro}{\PrintChar}
% \begin{macro}{\XD@threedignum}
%   The |\PrintChar| command has the syntax
%   \begin{quote}
%     |\PrintChar|\marg{8-bit number}
%   \end{quote}
%   where \meta{8-bit number} is a \TeX\ number in the range 0--255. 
%   For arguments in the range 0--31, |\PrintChar| prints 
%   `\textit{\ttfamily\string^\string^@}'--`\textit{\ttfamily
%   \string^\string^\string_}'. For an argument in the range 32--126, 
%   |\PrintChar| calls |\Print|\-|Visible|\-|Char| which by default 
%   simply does |\char| on that argument (but which can be redefined 
%   if the font set-up requires it); in particular, |\PrintChar{32}| 
%   should print a ``visible space'' character. |\PrintChar{127}| prints 
%   `\textit{\ttfamily\string^\string^?}'. For arguments in the range 
%   128--255, |\PrintChar| prints 
%   `\textit{\ttfamily\string^\string^80}'--`\textit{\ttfamily
%   \string^\string^ff}'.
%   
%   |\PrintChar| is robust. |\PrintChar| also has a special behaviour 
%   when it is written to a file (when |\protect| is |\noexpand|): it 
%   makes sure that the argument consists of three decimal digits, to 
%   ensure external sorting gets it right.
%    \begin{macrocode}
\@ifundefined{PrintChar}{}{%
   \PackageInfo{xdoc2}{Redefining \protect\PrintChar}%
}
\def\PrintChar{%
   \ifx \protect\@typeset@protect
      \expandafter\XD@PrintChar
   \else\ifx \protect\noexpand
      \string\PrintChar
      \expandafter\expandafter \expandafter\XD@threedignum
   \else
      \noexpand\PrintChar
   \fi\fi
}
%    \end{macrocode}
%   
%   |\XD@threedignum| does a |\number| on its argument, possibly prepends 
%   a |0| or two, and wraps it all up in a ``group'' (the braces have 
%   category other, not beginning and end of group).
%   \changes{prot2.1}{2000/11/15}{Braces inserted by 
%      \cs{XD@threedignum} are given catcode other. (LH)}
%    \begin{macrocode}
\edef\XD@threedignum#1{%
   \string{%
   \noexpand\ifnum #1<100 %
      \noexpand\ifnum #1<10 0\noexpand\fi
      0%
   \noexpand\fi
   \noexpand\number#1%
   \string}%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\XD@PrintChar}
% \begin{macro}{\InvisibleCharPrefix}
% \begin{macro}{\InvisibleCharSuffix}
%   |\XD@PrintChar| manages the typesetting for |\PrintChar|. It 
%   distinguishes between visible characters (code 32--126) and 
%   invisible characters. The visible characters are typeset directly 
%   using |\PrintVisibleChar|, whereas the invisible characters are 
%   typeset as |^^|-sequences.
%   
%   The macros |\InvisibleCharPrefix| and |\InvisibleCharSuffix| begin 
%   and end a |^^|-sequence. |\InvisibleCharPrefix| should print the 
%   actual |^^|, but it may also for example select a new font for 
%   the |^^|-sequence (such font changes are restored at the end of 
%   |\XD@PrintChar|).
%    \begin{macrocode}
\def\XD@PrintChar#1{%
   \leavevmode
   \begingroup
      \count@=#1\relax
      \ifnum \@xxxii>\count@
         \advance \count@ 64%
         \InvisibleCharPrefix
         \PrintVisibleChar\count@
         \InvisibleCharSuffix
      \else\ifnum 127>\count@
         \PrintVisibleChar\count@
      \else
         \InvisibleCharPrefix
         \ifnum 127=\count@ \PrintVisibleChar{63}\else
            \@tempcnta=\count@
            \divide \count@ \sixt@@n
            \@tempcntb=\count@
            \multiply \count@ \sixt@@n
            \advance \@tempcnta -\count@
            \advance \@tempcntb \ifnum 9<\@tempcntb 87\else 48\fi
            \advance \@tempcnta \ifnum 9<\@tempcnta 87\else 48\fi
            \char\@tempcntb \char\@tempcnta
         \fi
         \InvisibleCharSuffix
      \fi\fi
   \endgroup
}
%    \end{macrocode}
%    \begin{macrocode}
\newcommand\InvisibleCharPrefix{%
   \/\em
   \PrintVisibleChar{`\^}\PrintVisibleChar{`\^}%
}
\newcommand\InvisibleCharSuffix{\/}
%    \end{macrocode}
%   There are some alternative methods for making hexadecimal numbers 
%   which should perhaps be mentioned. The \LaTeX\ kernel contains a 
%   macro |\hexnumber@| which uses |\ifcase| to produce one hexadecimal 
%   digit, but that uses upper case letters, and things like `8E' look 
%   extremely silly if the upper case letters doesn't line with the 
%   digits. Applying |\meaning| to a \meta{chardef token} or 
%   \meta{mathchardef token} expands to |\char"|\meta{hex} and 
%   |\mathchar"|\meta{hex} respectively, where \meta{hex} is the 
%   corresponding number in hexadecimal, but that too has upper case A--F 
%   and leading zeros are removed.
% \end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\PrintVisibleChar}
%   \changes{prot2.1}{2000/12/18}{Made it possible to select the 
%      alternative defintion of \cs{PrintVisibleChar} through an 
%      \package{xdoc} package option. (LH)}
%   The |\PrintVisibleChar| command should print the visible ASCII 
%   character whose character code is given in the argument. There are 
%   currently two definitions of this command: one which uses the \TeX\ 
%   primitive |\char| and one which goes via the ``\LaTeX\ internal 
%   character representation'' for the character. By default 
%   \package{xdoc} uses the former definition, but if \package{xdoc} 
%   is passed the 
%   \SortIndex{notrawchar}{\texttt{notrawchar} option\encapchar usage}
%   \texttt{notrawchar} option then it will use the latter.
%   
%   The reason there are two definitions is a deficiency in how the NFSS 
%   encoding attribute has been assigned to fonts; even though the 
%   encodings of Computer Modern Roman and Computer Modern Typewriter 
%   are quite different, \LaTeXe\ uses the \texttt{OT1} encoding for 
%   both. As a result of this, the \LaTeX\ internal representation will 
%   in some important cases use characters from non-typewriter fonts 
%   despite the fact that typewriter forms are immediately available.
%   Since the cases in which the |\char| primitive produces results as 
%   least as good as those made through the \LaTeX\ internal 
%   character representation includes those that the current font is 
%   \texttt{T1}-encoded or an \texttt{OT1}-encoded nonitalic typewriter 
%   font, the shorter |\char| primitive defintion has been made the 
%   default.
%   
%   For compability with prototype version~2.0 of \package{xdoc}, the 
%   replacement text for |\Print|\-|Visible|\-|Char| that uses \LaTeX\ 
%   internal character representation can alternatively be extracted by 
%   \package{docstrip}ping \texttt{xdoc2.dtx} with the option 
%   \Module{internals}.
%    \begin{macrocode}
\@ifpackagewith{xdoc2}{notrawchar}{%
   \newcommand\PrintVisibleChar[1]{%
%</pkg>
%<*pkg|internals>
      \ifcase #1%
      \or\or\or\or\or\or\or\or \or\or\or\or\or\or\or\or 
      \or\or\or\or\or\or\or\or \or\or\or\or\or\or\or\or
      % "20
         \textvisiblespace \or!\or\textquotedbl \or\#\or\textdollar 
         \or\%\or\&\or\textquoteright\or(\or)\or*\or+\or,\or-\or.\or/%
      \or % "30
         0\or1\or2\or3\or4\or5\or6\or7\or8\or9\or:\or;\or
         \textless\or=\or\textgreater\or?%
      \or % "40
         @\or A\or B\or C\or D\or E\or F\or G\or 
         H\or I\or J\or K\or L\or M\or N\or O%
      \or % "50
         P\or Q\or R\or S\or T\or U\or V\or W\or X\or Y\or Z\or [\or
         \textbackslash \or]\or\textasciicircum \or\textunderscore
      \or % "60
         \textquoteleft \or a\or b\or c\or d\or e\or f\or g\or h\or 
         i\or j\or k\or l\or m\or n\or o%
      \or % "70
         p\or q\or r\or s\or t\or u\or v\or w\or x\or y\or z\or
         \textbraceleft \or\textbar \or\textbraceright \or
         \textasciitilde
      \fi
   }%
%</pkg|internals>
%<*pkg>
}{%
   \newcommand\PrintVisibleChar[1]{\char #1\relax}%
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\Bslash}
%   It turns out that it is very common to say |\PrintChar{92}| 
%   (backslash), so a macro which expands to that reduces typing.
%    \begin{macrocode}
\newcommand\Bslash{\PrintChar{92}}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Rendering character strings harmless}
% 
% Replacing all problematic characters with |\PrintChar| calls certainly 
% makes the strings easier to manage, but actually making those 
% replacements is a rather complicated task. Therefore this subsection 
% contains the macros necessary for doing these replacements.
% 
% The first problem is how to efficiently recognise the problematic 
% characters. A first solution which gets rather far is to mainly look 
% in the |\catcode| register for that character and keep the character 
% as it is if the category found there is 11 or 12, but replace it with 
% a |\PrintChar| command if the category is anything else. Two extra 
% tests can be performed to take care of invisible ASCII, and the 
% \package{makeindex} metacharacters can be cared for by locally 
% changing their catcodes for when the string is processed. 
% Unfortunately this doesn't work inside \texttt{macrocode} 
% environments (where one would like to use it for the macro 
% cross-referencing) since that environment changes the catcodes of 
% several characters from being problematic to being unproblematic and 
% vice versa.\footnote{As the entire \texttt{macrocode} environment is 
% tokenized by the expansion of \cs{xmacro@code} one could alternatively 
% solve this problem by reimplementing the \texttt{macrocode} 
% environment so that normal catcodes are in force when the contents are 
% being typeset.} As furthermore harmless character strings should be 
% possible to move to completely different parts of the document, the 
% test used for determining whether a character is problematic should 
% yield the same result throughout the document.
% 
% Because of this, I have chosen a brute strength solution: build a 
% table (indexed by character code) that gives the harmless form of 
% every character. This table is stored in the
% \describecsfamily{XD@harmless@\meta{code}}^^A
% |\XD@harmless@|\meta{code} family of control sequences, where the 
% \meta{code} is in the range |0|--|255|. Assignments to this table are 
% global. In principle, the table should not change after the preamble, 
% but there is a command |\SetHarmState| which can be used at any time 
% for setting a single table entry. This could be useful for documents 
% which, like for example~\cite{fontinst}, have nonstandard settings of 
% |\catcode|s.
% 
% \begin{macro}{\SetHarmState}
%   The |\SetHarmState| command takes three arguments:
%   \begin{quote}
%     |\SetHarmState|\marg{type}\marg{char}\marg{harm}
%   \end{quote}
%   \meta{char} is the character whose entry should be set. \meta{type} 
%   is a flag which specifies what format \meta{char} is given in. If 
%   \meta{type} is |\BooleanTrue| then \meta{char} is the \TeX\ 
%   \meta{number} of the table entry to set, and if \meta{type} is 
%   |\BooleanFalse| then \meta{char} is something which expands to a 
%   single character token whose entry should be set. The expansion is 
%   carried out by an |\edef|, so it needs not be only one level. 
%   \meta{harm} is |\BooleanTrue| if the character is problematic and 
%   |\BooleanFalse| if it is not.
%   
%   The \meta{type} and \meta{harm} arguments are currently not subject 
%   to any expansion. In the future they probably should be, but I 
%   don't want to make assumptions about the actual definitions of 
%   |\BooleanTrue| and |\BooleanFalse| at this point.
%    \begin{macrocode}
\begingroup
   \catcode\z@=12
   \@ifdefinable\SetHarmState{
      \gdef\SetHarmState#1#2#3{%
         \begingroup
            \ifx #1\BooleanTrue
               \count@=#2\relax
            \else
               \protected@edef\@tempa{#2}%
               \count@=\expandafter`\@tempa\relax
            \fi
            \ifx #3\BooleanTrue
               \edef\@tempa{\noexpand\PrintChar{\the\count@}}%
            \else
               \uccode\z@=\count@
               \uppercase{\def\@tempa{^^@}}%
            \fi
            \global\expandafter\let
               \csname XD@harmless@\the\count@ \endcsname \@tempa
         \endgroup
      }%
   }
\endgroup
%    \end{macrocode}
% \end{macro}
% 
% \begin{trivlist}\item[]\leavevmode ^^A Just for the look of it
%   \GenericDescribePrint{\small\cs{XD@harmless@}\meta{code}}^^A
%   ^^A There should have been a "main" index entry here as well,
%   ^^A but generating that with \package{doc} commands is more than I 
%   ^^A bother to do right now.
%   Initializing the |\XD@harmless@|\meta{code} table is a 
%   straightforward exercise of |\loop| \dots\ |\repeat|.
%    \begin{macrocode}
%<*!economical>
\count@=\z@
\loop
   \expandafter\xdef \csname XD@harmless@\the\count@ \endcsname
      {\noexpand\PrintChar{\the\count@}}%
   \advance \count@ \@ne
\ifnum 33>\count@ \repeat
%</!economical>
%<economical>\count@=\@xxxii
\begingroup
   \catcode\z@=12\relax
   \@firstofone{%
\endgroup
   \loop
      \if \ifnum 11=\catcode\count@ 1\else \ifnum 12=\catcode\count@
            1\else 0\fi\fi 1%
         \uccode\z@=\count@
         \uppercase{\def\@tempa{^^@}}%
      \else
         \edef\@tempa{\noexpand\PrintChar{\the\count@}}%
      \fi
      \global\expandafter\let
         \csname XD@harmless@\the\count@ \endcsname \@tempa
      \advance \count@ \@ne
   \ifnum 127>\count@ \repeat
}
%<*!economical>
\loop
   \expandafter\xdef \csname XD@harmless@\the\count@ \endcsname
      {\noexpand\PrintChar{\the\count@}}%
\ifnum \@cclv>\count@ 
   \advance \count@ \@ne
\repeat
%</!economical>
%    \end{macrocode}
%   Marking the \package{makeindex} metacharacters as harmful is 
%   deferred until |\begin|\nolinebreak[2]|{document}|, since it is not 
%   unreasonable that these are changed in the preamble.
%    \begin{macrocode}
\AtBeginDocument{%
   \SetHarmState\BooleanFalse\actualchar\BooleanTrue
   \SetHarmState\BooleanFalse\encapchar\BooleanTrue
   \SetHarmState\BooleanFalse\levelchar\BooleanTrue
   \SetHarmState\BooleanFalse\quotechar\BooleanTrue
}
%    \end{macrocode}
%   \package{doc}'s |\verbatimchar| is not harmful, since it isn't used 
%   at all in \package{xdoc}.
% \end{trivlist}
% 
% 
% \begin{macro}{\MakeHarmless}
%   To render a character string harmless, you do
%   \begin{quote}
%     |\MakeHarmless|\marg{macro}\marg{string}
%   \end{quote}
%   This locally assigns to \meta{macro} the harmless character string 
%   which corresponds to \meta{string}. During the conversion the converted 
%   part of the string is stored in |\toks@|, but that is local to 
%   |\MakeHarmless|.
%    \begin{macrocode}
\def\MakeHarmless#1#2{%
   \begingroup
      \toks@={}%
      \escapechar=`\\%
      \XD@harmless@#2\XD@harmless@
   \expandafter\endgroup \expandafter\def \expandafter#1%
      \expandafter{\the\toks@}%
}
%    \end{macrocode}
% 
% \begin{macro}{\XD@harmless@iii}
% \begin{macro}{\XD@harmless@iv}
% \begin{macro}{\XD@harmless@v}
%   \changes{prot2}{2000/07/27}{Moved code for adding to \cs{toks@} here 
%      and changed it to append the contents of \cs{XD@harmless@32}, not 
%      necessarily a \cs{PrintChar}. (LH)}
% \begin{macro}{\XD@harmless@vi}
%   What one has to be most careful about when rendering strings 
%   harmless are the space tokens, since many of \TeX's primitives gladly 
%   snatches an extra space (or more) where you don't want them to in 
%   this case. Macro parameters can be particularly dangerous, as \TeX\ 
%   will skip any number of spaces while looking for the replacement 
%   text for an undelimited macro argument. Therefore the algorithm for 
%   rendering a character token harmless begins 
%   (|\XD@|\B|harmless@iii|) with |\string|ing the next token in the 
%   string---this preserves the character code and sets the category to 
%   12 for all characters except the ASCII space, which gets category 10 
%   (space)---and then |\futurelet| is used to peek at the next token. If 
%   it is a space token (|\XD@|\B|harmless@iv|) then the character code 
%   is 32 and the actual space can be gobbled (|\XD@|\B|harmless@v|), and 
%   if it isn't then the next token can be grabbed in an undelimited macro 
%   argument (|\XD@|\B|harmless@vi|). In either case, the harmless form 
%   is given by the |\XD@|\B|harmless@|\meta{code} table entry 
%   (in |\XD@|\B|harmless@v| or |\XD@|\B|harmless@vi|).
%    \begin{macrocode}  
\def\XD@harmless@iii{%
   \expandafter\futurelet \expandafter\@let@token 
   \expandafter\XD@harmless@iv \string
}
%    \end{macrocode}  
%    \begin{macrocode}  
\def\XD@harmless@iv{%
   \ifx \@let@token\@sptoken
      \expandafter\XD@harmless@v
   \else
      \expandafter\XD@harmless@vi
   \fi
}
%    \end{macrocode}
%   ^^A Hack:
%   \begingroup
%   \expandafter\def \expandafter\MakePrivateLetters \expandafter{^^A
%      \MakePrivateLetters
%      \catcode`3=11
%      \catcode`2=11
%   }
%    \begin{macrocode}
\begingroup
   \catcode`3=\catcode`a
   \catcode`2=\catcode`a
   \@firstofone{\gdef\XD@harmless@v} {%
      \toks@=\expandafter{\the \expandafter\toks@ \XD@harmless@32}%
      \XD@harmless@
   }
\endgroup
%    \end{macrocode}
%   \endgroup
%   In the \Module{economical} (with hash table space) variant 
%   implementation the |\XD@harmless@|\meta{code} table has entries only 
%   for the characters in visible ASCII. Thus the harmless forms of 
%   characters outside visible ASCII must be constructed on the fly.
%    \begin{macrocode}  
\def\XD@harmless@vi#1{%
%<*economical>
   \if \ifnum `#1<\@xxxii 1\else \ifnum `#1>126 1\else 0\fi\fi 1%
      \toks@=\expandafter{\the\expandafter\toks@
         \expandafter\PrintChar \expandafter{\number`#1}%
      }%
   \else
%</economical>   
   \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
      \csname XD@harmless@\number`#1\endcsname}%
%<economical>   \fi
   \XD@harmless@
}
%    \end{macrocode}  
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\XD@harmless@}
% \begin{macro}{\XD@harmless@i}
% \begin{macro}{\XD@harmless@ii}
%   But that is not all |\MakeHarmless| can do. In some cases (as for 
%   example when one is describing a family of control sequences) one 
%   might want to include things in the string that are not simply 
%   characters, but more complex items---such as for example |\meta| 
%   constructions like \meta{code}. To accommodate for this, 
%   |\XD@harmless@| (which is the first step in converting a token) 
%   always begins by checking whether the next token to render harmless 
%   is a control sequence. If it is then it is checked (in 
%   |\XD@harmless@ii|) whether the control sequence 
%   \describecsfamily{XD@harmless\Bslash\meta{cs-name}}^^A
%   |\XD@harmless\|\meta{cs-name}, where \meta{cs-name} is the name 
%   without |\| of the control sequence encountered, is defined. If it 
%   isn't then the encountered control sequence is |\string|ed and 
%   conversion continues as above, but if it is defined then the 
%   encountered control sequence begins such a more complex item.
%    \begin{macrocode}
\def\XD@harmless@{\futurelet\@let@token \XD@harmless@i}
%    \end{macrocode}  
%    \begin{macrocode}
\def\XD@harmless@i{%
   \ifcat \noexpand\@let@token \noexpand\XD@harmless@
      \expandafter\XD@harmless@ii
   \else
      \expandafter\XD@harmless@iii
   \fi
}
%    \end{macrocode}  
%    \begin{macrocode}
\def\XD@harmless@ii#1{%
   \@ifundefined{XD@harmless\string#1}{%
      \expandafter\XD@harmless@vi \string#1%
   }{\csname XD@harmless\string#1\endcsname}%
}
%    \end{macrocode}  
% \end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\XD@harmless\XD@harmless@}
%   A control sequence |\XD@harmless\|\meta{cs-name} is responsible for 
%   interpreting the string item that begins with the control sequence 
%   |\|\meta{cs-name} and appending a harmless representation of it to 
%   |\toks@|. Harmless representations should only contain robust 
%   control sequences and they must not rely on changing any catcodes. 
%   Normal |\XD@harmless\|\meta{cs-name} control sequences must also 
%   end by inserting |\XD@harmless@| in front of what remains of the 
%   string after the complex string item has been removed. This sees to 
%   that the rest of the string is also rendered harmless. The only such
%   control sequence which does not insert |\XD@harmless@| is 
%   |\XD@harmless\XD@harmless@|, but that is as it should be since 
%   |\MakeHarmless| itself appends a |\XD@harmless@| to every character 
%   string it should convert to mark the end of it.
%    \begin{macrocode}
\expandafter\let 
   \csname XD@harmless\string\XD@harmless@\endcsname \@empty
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\XD@harmless\PrintChar}
%   It is occasionally convenient to use a |\PrintChar| command as part 
%   of a string that is to be rendered harmless instead of using the raw 
%   character. The definition is very similar to that of 
%   |\XD@harmless@vi|.
%    \begin{macrocode}  
\@namedef{XD@harmless\string\PrintChar}#1{%
%<*economical>
   \if \ifnum #1<\@xxxii 1\else \ifnum #1>126 1\else 0\fi\fi 1%
      \toks@=\expandafter{\the\expandafter\toks@
         \expandafter\PrintChar \expandafter{\number#1}%
      }%
   \else
%</economical>   
   \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
      \csname XD@harmless@\number#1\endcsname}%
%<economical>   \fi
   \XD@harmless@
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Interaction with mechanisms that make characters 
%    problematic}
% 
% If additional visible characters are made problematic after the 
% initial |\XD@harmless@|\meta{code} table is formed then problems may 
% indeed arise, because some character which is expected to be 
% unproblematic when read from (for example) an \texttt{.ind} file will 
% actually not be. In fortunate cases this will only lead to that 
% characters will print strangely or not at all, but it can quite 
% conceivably lead to errors that prevent further typesetting and it 
% should therefore be prevented if possible.
% 
% Right now, I can think of two mechanisms that make characters 
% problematic, and both do that by making them active. One is the 
% shorthand mechanism of \package{babel}, but I think I'll delay 
% implementing any interaction with that until some later prototype; I 
% don't know it well enough and anyway I don't think it is that likely 
% to cause any problems. The other mechanism is the short verb mechanism 
% of \package{doc} itself, and this should be taken care of right away.
% 
% The main difficulty is that the |\XD@harmless@|\meta{code} table should 
% be the same throughout the document body (otherwise you may get more 
% than one index entry for the same thing, with index references 
% arbitrarily distributed between the two) whereas short verb characters 
% can be made and deleted at any time. It would actually be wrong to 
% always have the |\XD@harmless@|\meta{code} table entry mirroring the 
% current state of the character! Instead a character will be considered 
% as problematic even if it is only made problematic temporarily (with 
% the exception for characters that are made problematic in 
% \texttt{verbatim} environments and the like---the index file isn't 
% being read in while those catcodes are active). Since it is impossible 
% to know in the beginning of a document whether a character will be made 
% a short verb character at some later point, the modifications to the 
% |\XD@harmless@|\meta{code} table that will be made because of short verb 
% characters will (at least partially) be based on which characters were 
% made short verbs on the previous run.
% 
% \begin{macro}{\SetCharProblematic}
%   \changes{prot2}{2000/07/26}{Command added. (LH)}
%   The |\SetCharProblematic| command should be called by commands which 
%   make a character problematic (e.g.\ makes it active) in the general 
%   context (commands which make some character problematic only in some 
%   very special context, such as the \texttt{verbatim} environment, 
%   need not call |\Set|\-|Char|\-|Problematic|). The syntax is
%   \begin{quote}
%     |\SetCharProblematic|\marg{code}
%   \end{quote}
%   and it sets the ``harm state'' of the character whose code is 
%   \meta{code} to problematic.
%   
%   When |\SetCharProblematic| is called in the preamble, it sets the 
%   harm state on the current run. When it is called in the document 
%   body however, it sets the harm state on the next run by writing a 
%   |\SetHarmState| command to the \texttt{.aux} file. This is done to 
%   ensure that the contents of the |\XD@harmless@|\meta{code} table 
%   doesn't change during the body of a document.
%    \begin{macrocode}
\newcommand\SetCharProblematic[1]{%
   \SetHarmState\BooleanTrue{#1}\BooleanTrue
}
\AtBeginDocument{%
   \gdef\SetCharProblematic#1{%
      \if@filesw
         \immediate\write\@auxout{\string\SetHarmState 
            \string\BooleanTrue {\number#1}\string\BooleanTrue}%
      \fi
   }%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\add@specials}
%   \changes{prot2}{2000/07/26}{Redefinition added. (LH)}
%   |\MakeShortVerb|'s call to |\SetCharProblematic| is put in the 
%   |\add@|\B|specials| macro, which anyway already adds the character 
%   to the |\dospecials| and |\@sanitize| lists. Only familiar 
%   definitions of |\add@special| are changed.
%    \begin{macrocode}
\def\@tempa#1{%
  \rem@special{#1}%
  \expandafter\gdef\expandafter\dospecials\expandafter
    {\dospecials \do #1}%
  \expandafter\gdef\expandafter\@sanitize\expandafter
    {\@sanitize \@makeother #1}}
\ifx \@tempa\add@special
   \def\add@special#1{%
      \rem@special{#1}%
      \expandafter\gdef\expandafter\dospecials\expandafter
         {\dospecials \do #1}%
      \expandafter\gdef\expandafter\@sanitize\expandafter
         {\@sanitize \@makeother #1}%
      \SetCharProblematic{`#1}%
   }
\else
   \PackageWarningNoLine{xdoc2}{Unfamiliar definition of 
      \protect\add@special;\MessageBreak the macro was not patched}
\fi
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \section{Indexing}
% \label{Sec:Indexing}
% 
% Each type of index entry \package{doc} produces is implemented through 
% a different indexing command.\footnote{Sometimes there are 
% even more than one command per entry type---the \cs{SpecialIndex}, 
% \cs{LeftBraceIndex}, \cs{RightBraceIndex}, and \cs{PercentIndex} 
% commands all generate entries of the same type.} This might be 
% manageable when there are only \texttt{macro}s and 
% \texttt{environment}s to distinguish between, but it soon gets 
% unmanageable if more environments of this type are added. Therefore 
% all \package{xdoc} index entries are made with a single 
% command---|\IndexEntry|.
% 
% 
% \subsection{New basic indexing commands}
% \label{Ssec:IndexEntry}
% 
% \begin{macro}{\IndexEntry}
% \begin{macro}{\LevelSame}
%   \changes{prot2.1}{2000/11/18}{New name for \cs{levelsame}. (LH)}
% \begin{macro}{\LevelSorted}
%   \changes{prot2.1}{2000/11/18}{New name for \cs{levelsorted}. (LH)}
% \begin{macro}{\XD@if@index}
%   The |\IndexEntry| command writes one index entry to the \texttt{.idx} 
%   file. It takes three arguments:
%   \begin{quote}
%     |\IndexEntry|\marg{entry text}\marg{encap}\marg{thenumber}
%   \end{quote}
%   The \meta{entry text} contains the text for the entry. It is a 
%   nonempty sequence of commands in which each item is one of
%   \begin{quote}
%     |\LevelSame|\marg{text}\\
%     |\LevelSorted|\marg{sort key}\marg{text}
%   \end{quote}
%   Each such item specifies one level of the entry that is to be 
%   written. In the case of |\LevelSorted|, the \meta{text} is what will 
%   be written in the sorted index at that level and \meta{sort key} is 
%   a key which the index-sorting program should use for sorting that 
%   entry at that level. In the case of |\LevelSame|, the \meta{text} is 
%   used both as sort key and contents of entry in the sorted index.
%   The first item is for the topmost level and each subsequent item is 
%   for the next sublevel. The \meta{entry text} will be fully expanded 
%   by the |\IndexEntry| command.
%   
%   \meta{thenumber} is the number (if any) that the index entry refers 
%   to. It can consist of explicit characters, but it can also be a 
%   |\the|\meta{counter} control sequence or a macro containing such 
%   control sequences. \meta{thenumber} is fully expanded by the 
%   |\IndexEntry| command, with the exception for occurrences of 
%   |\thepage|---expansion of |\thepage| will instead be delayed until 
%   the page is shipped out, so that the page numbers will be right. 
%   \textbf{Note:} \meta{thenumber} must not contain any formatting that 
%   will upset the index-sorting program. \package{doc}'s default 
%   definition of |\theCodelineNo| contains such formatting, so one 
%   must instead use |\thecodelineno| as \meta{thenumber} in that case.
%   
%   \meta{encap} is the name of the encapsulation scheme that should be 
%   applied to \meta{thenumber}. All encapsulation schemes that have been 
%   implemented instruct the index sorting program to wrap up 
%   \meta{thenumber} in some code that gives it special formatting when 
%   the sorted index is written, but one could also use the \meta{encap} 
%   to specify `beginning of range' and `end of range' index entries. 
%   Use \GenericDescribePrint{\small\texttt{none}}^^A
%   \SortIndex{none}{\texttt{none}\encapchar usage}\texttt{none} as 
%   \meta{encap} if you don't want any special formatting.
%   
%   \textbf{Note:} |\IndexEntry| uses |\@tempa| internally, so you 
%   cannot use that in argument \#2 or \#3. Using it in argument \#1 
%   presents no problems, though.
%    \begin{macrocode}
\newcommand\IndexEntry[3]{%
   \@bsphack
   \begingroup
      \def\LevelSame##1{\levelchar##1}%
      \def\LevelSorted##1##2{\levelchar##1\actualchar##2}%
      \protected@edef\@tempa{#1}%
      \protected@edef\@tempa{\expandafter\@gobble\@tempa\@empty}%
      \@ifundefined{XD@idxencap@#2}{%
         \PackageError{xdoc2}{Index entry encap `#2' unknown}\@eha
      }{%
         \XD@if@index{%
            \csname XD@idxencap@#2\endcsname\@tempa{#3}%
         }{}%
      }%
   \endgroup
   \@esphack
}
%    \end{macrocode}
%   |\IndexEntry| does (like |\index|) not contribute any material to the 
%   current list if indices aren't being made.
%   
%   |\XD@if@index| is |\@firstoftwo| if index entries are being written 
%   and |\@second|\-|of|\-|two| if they are not.
%    \begin{macrocode}
\let\XD@if@index=\@secondoftwo
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% In \LaTeXplus, the \cs{IndexEntry} command should probably be 
% implemented using templates, e.g. the \meta{encap}s could be names of 
% instances.
% 
% \begin{macro}{\levelsame}
% \begin{macro}{\levelsorted}
%   These names were used for |\LevelSame| and |\LevelSorted| 
%   respectively in prototype version~2.0, but the macros should belong 
%   to the same capitalization class as |\IndexEntry| so their names 
%   were changed in prototype version~2.1. The old names |\levelsame| 
%   and |\levelsorted| will continue to work in \package{xdoc2}, though.
%    \begin{macrocode}
%<*xdoc2>
\newcommand*\levelsame{\LevelSame}
\newcommand*\levelsorted{\LevelSorted}
%</xdoc2>
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \describecsfamily{XD@idxencap@\meta{encap}}^^A
% Macros in the family |\XD@idxencap@|\meta{encap} takes two 
% arguments as follows
% \begin{quote}
%   |\XD@idxencap@|\meta{encap}\,\marg{entry}\,\marg{thenumber}
% \end{quote}
% They should write an entry with the \meta{encap} encapsulation of the 
% \meta{thenumber} to the index file. They need not check whether index 
% generation is on or not, but they must be subject to the \LaTeX\ kernel 
% \texttt{@filesw} switch. They must expand both arguments fully at the 
% time of the command, with the exception for the control sequence 
% |\thepage|, which should not be expanded until the page on which the 
% write appears is output. Both these conditions are met if the macro 
% is implemented using |\protected@write|.
% 
% \begin{macro}{\XD@idxencap@none}
% \begin{macro}{\XD@idxencap@main}
% \begin{macro}{\XD@idxencap@usage}
%   These macros implement the encapsulation schemes that are used in 
%   \package{doc}.
%    \begin{macrocode}
\def\XD@idxencap@none#1#2{%
   \protected@write\@indexfile{}{\XD@index@keyword{#1}{#2}}%
}
%    \end{macrocode}
%    \begin{macrocode}
\def\XD@idxencap@main#1#2{%
   \protected@write\@indexfile{}%
      {\XD@index@keyword{#1\encapchar main}{#2}}%
}
%    \end{macrocode}
%    \begin{macrocode}
\def\XD@idxencap@usage#1#2{%
   \protected@write\@indexfile{}%
      {\XD@index@keyword{#1\encapchar usage}{#2}}%
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\XD@index@keyword}
%   \changes{prot2.2}{2001/02/13}{Macro added and \meta{encap} macros 
%      changed to use it. (LH)}
%   The |\XD@index@keyword| is a hook for changing the index entry 
%   keyword (the text that is put in front of every index entry in the 
%   \texttt{.idx} file). It is changed by e.g.\ the \package{docindex} 
%   package~\cite{docindex}.
%    \begin{macrocode}
\@ifundefined{XD@index@keyword}{%
   \edef\XD@index@keyword{\@backslashchar indexentry}%
}{}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\CodelineIndex}
%   \changes{prot2.1}{2000/10/08}{Using \cs{thecodelineno}. (LH)}
% \begin{macro}{\PageIndex}
% \begin{macro}{\TheXDIndexNumber}
%   The |\CodelineIndex| and |\PageIndex| commands do the same things as 
%   in \package{doc}, but work with the \package{xdoc} internals instead 
%   of the \package{doc} ones. |\TheXDIndexNumber| is used as 
%   \meta{thenumber} argument to |\IndexEntry| by all indexing commands 
%   that would have used |\special@index| in \package{doc}.
%    \begin{macrocode}
\renewcommand\CodelineIndex{%
   \makeindex
   \let\XD@if@index=\@firstoftwo
   \codeline@indextrue
   \def\TheXDIndexNumber{\thecodelineno}%
}
%    \end{macrocode}
%    \begin{macrocode}
\renewcommand\PageIndex{%
   \makeindex
   \let\XD@if@index=\@firstoftwo
   \codeline@indexfalse
   \def\TheXDIndexNumber{\thepage}%
}
%    \end{macrocode}
%    \begin{macrocode}
\def\TheXDIndexNumber{??}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% 
% \subsection{Making good sort keys}
% 
% \changes{prot2.1}{2000/11/15}{Sort key making commands added. (LH)}
% A common nuisance in \package{doc} indices is that many macros are 
% sorted by parts of the name that do not carry any interesting 
% information. In the \LaTeX\ kernel many macro names begin with a 
% silent |@|, whereas the names of private macros in many packages 
% (including this one) begin with some fixed abbreviation of the 
% package name. Since such prefixes usually are harder to remember than 
% the rest of the macro name, it is not uncommon that the index position 
% one thinks of first isn't the one where the macro actually is put. 
% Hence a mechanism for removing such annoying prefixes from the macro 
% names might be useful, and that is presicely what is defined below.
% 
% The actual mechanism is based on having a set of macros called 
% \emph{operators} which operate on the harmless character string that 
% is to become the sort key. Each operator has a specific prefix string 
% which it tries to match against the beginning of the to-be sort key, 
% and if they match then the prefix is moved to the end of the sort key. 
% Automatically constructed operators (see below) have names of the form 
% \describecsfamily{XD@operatorA@\meta{prefix}}|\XD@operatorA@|^^A
% \meta{prefix}, but operators can be given arbitrary names.
% 
% \begin{macro}{\XD@operators@list}
%   The |\XD@operators@list| macro contains the list of all currently 
%   active operators.
%    \begin{macrocode}
\let\XD@operators@list\@empty
%    \end{macrocode}
% \end{macro}
% 
% The operators do all their work at expand-time. When an operator 
% macro is expanded, it is in the context
% \begin{quote}
%   \meta{operator} \meta{subsequent operators} |\@firstofone|
%   \meta{sort key text} |\@empty|
% \end{quote}
% There may not be any |\@empty|s or |\@firstofone|s amongst the 
% \meta{subsequent operators} or in the \meta{sort key text}. This should 
% expand to
% \begin{quote}
%   \meta{subsequent operators} |\@firstofone| \meta{operated-on sort 
%   key text} |\@empty|
% \end{quote}
% The purpose of the |\@firstofone| after the \meta{subsequent 
% operators} is to remove any spaces that some operator might have put 
% in front of the sort key. This happens if the entire sort key text has 
% been ignored by some operator.
% 
% \begin{macro}{\MakeSortKey}
%   The |\MakeSortKey| command is called to make the acutal sort key. 
%   The syntax of this command is
%   \begin{quote}
%     |\MakeSortKey|\marg{macro}\marg{text}\marg{extras}
%   \end{quote}
%   This locally defines \meta{macro} to be the sort key that the 
%   currently active operators manufacture from \meta{text}. The 
%   \meta{extras} argument can contain additional assignments needed for 
%   handling macros with special harmless forms, such as |\meta|.
%    \begin{macrocode}
\newcommand\MakeSortKey[3]{%
   \begingroup
      \def\PrintChar{\string\PrintChar\XD@threedignum}%
      #3%
      \unrestored@protected@xdef\@gtempa{#2}%
   \endgroup
   \protected@edef#1{%
      \expandafter\XD@operators@list \expandafter\@firstofone 
      \@gtempa\@empty
   }%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\XD@make@operator}
%   The |\XD@make@operator| macro takes a harmless character sequence as 
%   argument, constructs the corresponding operator, and returns the 
%   operator control sequence in the |\toks@| token list register.
%   
%   More precisely, given a harmless character string \meta{string}, 
%   |\XD@make@operator| will construct a sequence of other tokens 
%   \meta{text} from \meta{string} by replacing all |\PrintChar| 
%   commands in the same way as |\MakeSortKey| does. Then it defines the 
%   macro |\XD@operatorA@|\meta{text} to be
%   \begin{quote}
%     \raggedright \spaceskip=0.16666em
%     \#1\,|\@firstofone|\,\#2\,|\@empty| \ $\rightarrow$ \ %
%     |\XD@operatorB@|\meta{text} |\@firstofone| \#2 
%     |\@firstofone| \meta{text} |\@firstofone| |\relax| \#1 |\@empty|
%   \end{quote}
%   and the macro |\XD@operatorB@|\meta{text} to do
%   \begin{quote}
%     \raggedright
%     \#1\,|\@firstofone|\,\meta{text}\,\#2\,|\@firstofone|\,\#3\,^^A
%     |\relax|\,\#4\,|\@empty| $\rightarrow$ 
%     \#4\,\( \left\{ \begin{array}{ll} 
%     \mbox{\cs{@firstofone}\,\#2\,\textvisiblespace\,\meta{text}\,^^A
%     \cs{@empty}}& \mbox{if \#1 is empty}\\ 
%     \mbox{\#1\,\cs{@empty}}& \mbox{otherwise}
%     \end{array} \right.\)
%   \end{quote}
%   
%    \begin{macrocode}
\def\XD@make@operator#1{%
   \begingroup
      \def\PrintChar{\string\PrintChar\XD@threedignum}%
      \let\protect\@gobble
      \xdef\@gtempa{#1}%
   \endgroup
   \expandafter\edef \csname XD@operatorA@\@gtempa\endcsname
      ##1\@firstofone##2\@empty{%
      \expandafter\noexpand \csname XD@operatorB@\@gtempa\endcsname
      \noexpand\@firstofone ##2\noexpand\@firstofone \@gtempa
      \noexpand\@firstofone \relax##1\noexpand\@empty
   }%
   \expandafter\edef \csname XD@operatorB@\@gtempa \expandafter\endcsname
      \expandafter##\expandafter1\expandafter\@firstofone \@gtempa
      ##2\@firstofone##3\relax##4\@empty{%
      \noexpand\ifx $##1$%
         \noexpand\expandafter \noexpand\@firstoftwo
      \noexpand\else
         \noexpand\expandafter \noexpand\@secondoftwo
      \noexpand\fi{%
         ##4\noexpand\@firstofone ##2 \@gtempa
      }{##4##1}%
      \noexpand\@empty
   }%
   \toks@=\expandafter{\csname XD@operatorA@\@gtempa\endcsname}%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\DoNotIndexBy}
%   The |\DoNotIndexBy| command has the syntax
%   \begin{quote}
%     |\DoNotIndexBy|\marg{morpheme}
%   \end{quote}
%   It causes the \meta{morpheme} to be put \emph{last} in the index 
%   sort key for each macro name which begins by \meta{morpheme}. This 
%   can be used to ignore e.g.\ ``silent'' |@|s at the beginning of a 
%   macro name.
%    \begin{macrocode}
\newcommand\DoNotIndexBy[1]{%
   \MakeHarmless\@tempa{#1}%
   \XD@make@operator\@tempa
   \expandafter\def \expandafter\XD@operators@list \expandafter{%
      \the\expandafter\toks@ \XD@operators@list
   }%
}
%    \end{macrocode}
% \end{macro}
% 
%   
% 
% 
% \subsection{Reimplementations of \package{doc} indexing commands}
% 
% The \package{doc} indexing commands aren't that interesting in 
% \package{xdoc}, since they take `raw' control sequences as 
% arguments rather than the harmless strings that the \package{xdoc} 
% commands will want to put in the index. But it can be instructive to 
% see how they would be implemented in this context.
% 
% \begin{macro}{\SortIndex}
%   \changes{prot2.2}{2001/02/13}{Redefinition added. (LH)}
%   The |\SortIndex| takes a sort key and an entry text as argument, and 
%   writes a one-level index entry for that.
%    \begin{macrocode}
\renewcommand*\SortIndex[2]{%
   \IndexEntry{\LevelSorted{#1}{#2}}{none}{\thepage}%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\SpecialIndex}
% \begin{macro}{\SpecialMainIndex}
% \begin{macro}{\SpecialUsageIndex}
%   The |\SpecialIndex|, |\SpecialMainIndex|, and |\SpecialUsageIndex| 
%   commands take a control sequence (or more often something which looks 
%   like a |\string|ed control sequence) as their only argument. The 
%   entry text is that item verbatim, and the initial backslash is 
%   ignored in sorting (|\Special|\-|Index| always ignores the first 
%   character regardless of whether it is a backslash or not, the other 
%   two checks first). |\Special|\-|Index| has \texttt{none} formatting, 
%   |\Special|\-|Main|\-|Index| has \texttt{main} formatting, and 
%   |\Special|\-|Usage|\-|Index| has \texttt{usage} formatting of the 
%   index number.
%   
%   Although these definitions will (or at least are supposed to) yield 
%   the same typeset results as the \package{doc} definitions in the 
%   mainstream cases, I doubt that they will do so in all cases. At any 
%   rate, they shouldn't perform worse.
%    \begin{macrocode}
\renewcommand\SpecialIndex[1]{%
   \expandafter\MakeHarmless \expandafter\@tempa 
      \expandafter{\string#1}%
   \IndexEntry{%
      \LevelSorted{%
         \expandafter\XD@unbackslash \@tempa\@empty
      }{\texttt{\@tempa}}%
   }{none}{\TheXDIndexNumber}%
}
%    \end{macrocode}
%    \begin{macrocode}
\renewcommand\SpecialMainIndex[1]{%
   \expandafter\MakeHarmless \expandafter\@tempa 
      \expandafter{\string#1}%
   \IndexEntry{%
      \LevelSorted{%
         \expandafter\XD@unbackslash \@tempa\@empty
      }{\texttt{\@tempa}}%
   }{main}{\TheXDIndexNumber}%
}
%    \end{macrocode}
%    \begin{macrocode}
\renewcommand\SpecialUsageIndex[1]{%
   \expandafter\MakeHarmless \expandafter\@tempa 
      \expandafter{\string#1}%
   \IndexEntry{%
      \LevelSorted{%
         \expandafter\XD@unbackslash \@tempa\@empty
      }{\texttt{\@tempa}}%
   }{usage}{\thepage}%
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\XD@unbackslash}
% \begin{macro}{\XD@unbackslash@}
%   |\XD@unbackslash| is a utility macro which removes the first 
%   character from a harmless character string if that character is a 
%   backslash (i.e., if it is |\PrintChar{92}|). The \package{doc} 
%   commands have traditionally used |\@gobble| for doing this, but the 
%   \cs{@SpecialIndexHelper@} macro that was comparatively recently added 
%   tries to do better.
%    \begin{macrocode}
\def\XD@unbackslash#1{%
   \ifx \PrintChar#1%
      \expandafter\XD@unbackslash@
   \else
      \expandafter#1%
   \fi
}
\def\XD@unbackslash@#1{\ifnum #1=92 \else \PrintChar{#1}\fi}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\SpecialMainEnvIndex}
% \begin{macro}{\SpecialEnvIndex}
%   These are similar to the above, but \package{doc} thinks that the 
%   arguments don't need any special care, and it produces two index 
%   entries per command. |\Special|\-|Env|\-|Index| should  really have 
%   been called |\Special|\-|Usage|\-|Env|\-|Index|. 
%    \begin{macrocode}
\renewcommand\SpecialMainEnvIndex[1]{%
   \IndexEntry{\LevelSorted{#1}{\texttt{#1} (environment)}}{main}%
      {\TheXDIndexNumber}%
   \IndexEntry{\LevelSame{environments:}\LevelSorted{#1}{\texttt{#1}}}%
      {main}{\TheXDIndexNumber}%
}
%    \end{macrocode}
%    \begin{macrocode}
\renewcommand\SpecialEnvIndex[1]{%
   \IndexEntry{\LevelSorted{#1}{\texttt{#1} (environment)}}{usage}%
      {\thepage}%
   \IndexEntry{\LevelSame{environments:}\LevelSorted{#1}{\texttt{#1}}}%
      {usage}{\thepage}%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\it@is@a}
% \begin{macro}{\XD@special@index}
%   The |\it@is@a| macro is a specialized version of |\SpecialIndex|, 
%   but the format of its argument is quite different. After full 
%   expansion the argument will become a single category 12 token 
%   (\meta{t}, say), and the control sequence for which an entry should 
%   be made is |\|\meta{t}. \package{doc} uses |\it@is@a| for control 
%   sequences with one-character names. Note: The following 
%   definition should really have special code for the \Module{economical} 
%   \package{docstrip} module, but I don't think that is necessary 
%   since the \package{doc} macros which used |\it@is@a| will be
%   redefined so that they don't.
%   
%   |\XD@special@index| does the same thing as |\SpecialIndex|, but it 
%   does it with \package{xdoc} datatypes---the argument must be a 
%   harmless character string that does not include the initial escape 
%   (backslash).
%   \changes{prot2.1}{2000/11/15}{Using \cs{MakeSortKey} to make the 
%      sort key. (LH)}
%    \begin{macrocode}
\def\it@is@a#1{%
   \edef\@tempa{#1}%
   \XD@special@index{\csname XD@harmless@\number
      \expandafter`\@tempa\endcsname}%
}
%    \end{macrocode}
%    \begin{macrocode}
\def\XD@special@index#1{%
   \MakeSortKey\@tempa{#1}{}%
   \IndexEntry{\LevelSorted{\@tempa}{\texttt{\Bslash#1}}}{none}%
      {\TheXDIndexNumber}%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\LeftBraceIndex}
% \begin{macro}{\RightBraceIndex}
% \begin{macro}{\PercentIndex}
% \begin{macro}{\OldMakeIndex}
%   More specialised forms of |\SpecialIndex|. The |\OldMakeIndex| 
%   command can safely be made a no-op.
%    \begin{macrocode}
\renewcommand\LeftBraceIndex{\XD@special@index{\PrintChar{123}}}
\renewcommand\RightBraceIndex{\XD@special@index{\PrintChar{125}}}
\renewcommand\PercentIndex{\XD@special@index{\PrintChar{37}}}
\let\OldMakeIndex\relax
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\@wrindex}
%   \changes{prot2.2}{2001/02/13}{Redefinition added. (LH)}
%   Finally, while we're at redefining indexing commands, let's redefine 
%   |\@wrindex| as well to ensure that the index entry keyword is the 
%   same for all indexing commands.
%    \begin{macrocode}
\def\@wrindex#1{%
   \protected@write\@indexfile{}{\XD@index@keyword{#1}{\thepage}}%
   \endgroup
   \@esphack
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \section{Cross-referencing}
% 
% \subsection{Scanning \texttt{macrocode} for \TeX\ control sequences}
% \label{Ssec:Scanning macrocode}
% 
% The cross-referencing mechanism in \package{doc} isn't problematic in 
% the same way as the indexing mechanism is, so one could pretty much 
% leave it as it is, but there are things that are better done 
% differently when the basic indexing commands are based on harmless 
% character strings. Rather than storing control sequence names (without 
% escape character) as sequences of category 11 tokens, they will be 
% stored as the equivalent harmless character strings.
% 
% \begin{macro}{\macro@switch}
%   As in \package{doc}, |\macro@switch| determines whether the control 
%   sequence name that follows consists of letters (call |\macro@name|) 
%   or a single non-letter (call |\short@macro|). Unlike \package{doc}, 
%   \package{xdoc} accumulates the characters from a multiple-letter 
%   control sequence name in a token register (|\@toks|), which is why 
%   that is cleared here.
%    \begin{macrocode}
\def\macro@switch{%
   \ifcat\noexpand\next a%
      \toks@={}%
      \expandafter\macro@name
   \else
      \expandafter\short@macro
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\scan@macro}
%   Since |\macro@namepart| isn't used as in \package{doc}, I might as 
%   well remove the command that cleared it from |\scan@macro|.
%    \begin{macrocode}
\def\scan@macro{%
   \special@escape@char
   \step@checksum
   \ifscan@allowed
      \def\next{\futurelet\next\macro@switch}%
   \else \let\next\@empty \fi
   \next}
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \begin{macro}{\short@macro}
%   This macro will be invoked (with a single character as parameter)
%   when a single-character macro name has been spotted whilst
%   scanning within the \texttt{macrocode} environment. It will produce 
%   an index entry for that macro, unless that macro has been excluded 
%   from indexing, and it will also typeset the character that 
%   constitutes the name of the macro.
%    \begin{macrocode}
\def\short@macro#1{%
   \protected@edef\macro@namepart{%
%<*economical>
      \ifnum `#1<\@xxxii
         \noexpand\PrintChar{\number`#1}%
      \else\ifnum `#1>126
         \noexpand\PrintChar{\number`#1}%
      \else
%</economical>   
         \csname XD@harmless@\number`#1\endcsname
%<economical>      \fi\fi
   }%
   \ifnot@excluded \XD@special@index{\macro@namepart}\fi
%    \end{macrocode}
%   The cross-referencing mechanism is disabled for when the actual 
%   character is printed, as it could be the escape character. The index 
%   entry must be generated before the character is printed to ensure 
%   that no page break intervenes (recall that a |^^M| will start a new 
%   line).
%    \begin{macrocode}
   \scan@allowedfalse #1\scan@allowedtrue
}
%    \end{macrocode}
% \end{macro}
% 
% There is one mechanism in |\TeX|'s control sequence tokenization that 
% |\short@|\B|macro| doesn't cover, and that is the |^^| sequence 
% substitution---|\^^M| is (with default catcodes) seen as the three 
% tokens |\^|, |^|, and |M|, not as the single control 
% sequence token that \TeX\ will make out of it. But this is the way it 
% is done in \package{doc}.
% 
% 
% \begin{macro}{\macro@name}
% \begin{macro}{\more@macroname}
% \begin{macro}{\macro@finish}
%   Then there's the macros for assembling a control sequence name which 
%   consists of one or more letters (category 11 tokens). (This includes 
%   both the characters which are normally letters in the document and 
%   those that are made letters by |\MakePrivateLetters|.) They're 
%   pretty straightforward.
%    \begin{macrocode}
\def\macro@name#1{%
%<*economical>
   \if \ifnum `#1<\@xxxii 1\else \ifnum `#1>126 1\else 0\fi\fi 1%
      \toks@=\expandafter{\the\expandafter\toks@
         \expandafter\PrintChar \expandafter{\number`#1}%
      }%
   \else
%</economical>   
   \toks@=\expandafter{\the\expandafter\expandafter\expandafter\toks@
      \csname XD@harmless@\number`#1\endcsname}%
%<economical>   \fi
   \futurelet\next\more@macroname}
%    \end{macrocode}
%    \begin{macrocode}
\def\more@macroname{%
   \ifcat\noexpand\next a%
      \expandafter\macro@name
   \else
      \macro@finish
   \fi
}
%    \end{macrocode}
%    \begin{macrocode}
\def\macro@finish{%
   \edef\macro@namepart{\the\toks@}%
   \ifnot@excluded \XD@special@index{\macro@namepart}\fi
   \macro@namepart
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
%
%
%
% \subsection{The index exclude list}
% \label{Ssec:Index-exclude}
% 
% The index exclude list mechanisms are not quite as simple to convert 
% for use with harmless character strings as the construction of macro 
% names are. This is because the trick used for searching the exclude 
% list for a certain string doesn't work if the string one is looking 
% for contains tokens with category 1 or 2 (beginning and end of group), 
% as the \meta{parameter text} of a |\def| cannot contain such tokens. 
% On the other hand the only groups that can appear in the harmless 
% character strings one will be looking for are the ones around the 
% argument of some |\PrintChar|, and these can easily be converted to 
% something else. Therefore an item in the index exclude list of 
% \package{xdoc} will have the format
% \begin{quote}
%   |\do|\,\meta{string}
% \end{quote}
% where the \meta{string} is different from a harmless character string 
% only in that all |\PrintChar|\marg{num} have been replaced by 
% |\PrintChar|\parg{num}. The \meta{string} does not include an escape 
% character. The |\do| serves only to separate the item from the one 
% before, but it could in principle be used for other purposes as well 
% (such as in typesetting the entire exclude list).
% 
% \begin{macro}{\XD@paren@PrintChar}
%   |\XD@paren@PrintChar| is a definition of |\PrintChar| which, when it 
%   is used in an |\edef|, merely replaces the group around the argument 
%   by a parenthesis and normalizes the number in the argument.
%   \changes{prot2.1}{2000/09/16}{\cs{number} added. (LH)}
%    \begin{macrocode}
\def\XD@paren@PrintChar#1{\noexpand\PrintChar(\number#1)}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\DoNotIndex}
%   \changes{prot2.1}{2000/09/16}{Also changing catcode of \%. (LH)}
% \begin{macro}{\do@not@index}
% \begin{macro}{\XD@do@not@index}
%   These are the macros which add elements to the index exclude list. 
%   |\DoNotIndex| is pretty much as in \package{doc}, but I have added 
%   resetting of the catcodes of `|,|' (since |\XD@do@not@index| relies 
%   on it) and `|#|' (since it can otherwise mess things up for the 
%   |\def\@tempa| in |\do@not@index|).
%    \begin{macrocode}
\renewcommand\DoNotIndex{%
   \begingroup
      \MakePrivateLetters
      \catcode`\#=12\catcode`\\=12\catcode`,=12\catcode`\%=12
   \expandafter\endgroup \do@not@index
}
%    \end{macrocode}
%   
%   |\do@not@index|, on the other hand, is quite different, as it more 
%   or less has to convert the argument from the format used in 
%   \package{doc} to that of \package{xdoc}. The bulk of the work is 
%   done by |\XD@do@not@index|, which grabs one of the elements in the 
%   argument of |\do@not@index| and converts it (minus the initial 
%   backslash) to a harmless character string. That harmless character 
%   string is then converted by |\XD@paren@PrintChar|, so that the 
%   string can be searched for using |\expanded@notin|.
%   
%   The reason for using a special loop structure here, as opposed to 
%   using for example |\@for|, is that one cannot use either of |\| 
%   or |,| alone as item separators, as they may both be part of control 
%   sequence names (consider for example |\DoNotIndex{\a,\\,\b,\,,\c}|), 
%   but they should be sufficient when combined.
%   
%   The reason for storing new elements in |\toks@| until the end of 
%   the loop and only then inserting them into the index exclude list 
%   is speed; the index exclude list can get rather large, so you don't 
%   want to expand it more often than you have to. I don't know if the 
%   difference is noticeable, though.
%    \begin{macrocode}
\begingroup
   \catcode`\|=0
   \catcode`\,=12
   \catcode`\\=12
%    \end{macrocode}
%   \SpecialEscapechar{\|}
%    \begin{macrocode}
   |gdef|do@not@index#1{%
      |def|@tempa{#1}%
      |ifx |@empty|@tempa |else
         |toks@={}%
         |expandafter|XD@do@not@index |@gobble #1,\|XD@do@not@index,\%
      |fi
   }
   |gdef|XD@do@not@index#1,\{%
      |ifx |XD@do@not@index#1%
         |index@excludelist=|expandafter{%
            |the|expandafter|index@excludelist |the|toks@
         }%
         |expandafter|@gobble
      |else
         |MakeHarmless|@tempa{#1}%
         |begingroup
            |let|PrintChar|XD@paren@PrintChar
            |unrestored@protected@xdef|@gtempa{|noexpand|do|@tempa}%
         |endgroup
         |toks@=|expandafter{|the|expandafter|toks@ |@gtempa}%
      |fi
      |XD@do@not@index
   }
|endgroup
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\DoNotIndexHarmless}
%   The |\DoNotIndexHarmless| command takes a harmless character string 
%   as argument and locally adds the control sequence whose name is that 
%   character string to the index exclude list.
%    \begin{macrocode}
\newcommand\DoNotIndexHarmless[1]{%
   \begingroup
      \let\PrintChar\XD@paren@PrintChar
      \unrestored@protected@xdef\@gtempa{\noexpand\do#1}%
   \endgroup
   \index@excludelist=\expandafter{%
      \the\expandafter\index@excludelist \@gtempa
   }%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\index@excludelist}
%   In case the index exclude list is not empty, its contents are 
%   converted to \package{xdoc} format.
%    \begin{macrocode}
\edef\@tempa{\the\index@excludelist}
\index@excludelist{}
\ifx \@tempa\@empty \else
   \def\@tempb#1,\@nil{\do@not@index{#1}}
   \expandafter\@tempb \@tempa \@nil
   \let\@tempa\@empty
   \let\@tempb\@empty
\fi
%    \end{macrocode}
%   The fact that the |\XD@|\B|harmless@|\B\meta{code} table has not 
%   yet reached its final form means that some of these control sequences 
%   listed in the exclude list might get a different form here than they 
%   actually should, but there isn't much that can be done about that. It 
%   is furthermore unusual that control sequence are given such names 
%   that they would be affected by this.
% \end{macro}
% 
% \begin{macro}{\ifnot@excluded}
%   The |\ifnot@excluded| macro ultimately boils down to an 
%   \texttt{if}, which evaluates to true if and only if the string in 
%   |\macro@namepart| is not one of the items in the index exclude 
%   list. Before |\expanded@notin| gets to carry out the actual test, 
%   the |\PrintChar| calls in |\macro@namepart| are converted by 
%   |\XD@paren@PrintChar| (it's OK to use an unprotected |\edef| for 
%   this, since |\PrintChar| is the only control sequence that can 
%   appear in |\macro@namepart|) so that |\expanded@notin| can be used 
%   to test for its presence.
%    \begin{macrocode}
\def\ifnot@excluded{%
   \begingroup
      \let\PrintChar\XD@paren@PrintChar
      \edef\@tempa{\macro@namepart}%
   \expandafter\endgroup \expandafter\expanded@notin 
      \expandafter{\expandafter\do \@tempa\do}%
      {\the\index@excludelist}%
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{External cross-referencing}
% \label{Ssec:XXR}
% 
% (This subsection is a bit speculatory, but I think the structures it 
% describes may come in handy.)
% 
% \changes{prot2}{2000/07/31}{I finally decided that it would be better 
%    to make the XXR-commands look like comments to \TeX. (LH)}
% 
% It's rather easy to write macros for scanning \TeX\ code for the names 
% of control sequences---just look for the escape (category 0) 
% character, and whatever follows is the name of a control sequence. 
% Doing the same thing for other languages may lay anywhere between 
% ``a~tricky exercise in advanced \TeX\ programming'' and ``possible in 
% theory'',\footnote{I.e., you know it can be implemented as a computer 
% program (in some language), you know that any computer program can be 
% translated to a Turing machine (or if you prefer that, expressed in 
% lambda calculus), and you know that a Turing machine can be emulated 
% by \TeX, but that's the closest thing to a solution you've managed to 
% come up with.} but in most cases the available solutions turn out to be 
% too complicated and\slash or slow to be of practical use. When that 
% happens, one might instead want to use some external piece of software 
% for doing the cross-referencing.
% 
% The commands in this subsection implement basic support for such an 
% external cross-referencing program (or XXR,\footnote{Maybe not the 
% most logical name, but it looks much cooler than ECR.} for short). The 
% idea is that an XXR should communicate with \LaTeX\ like \BibTeX\ 
% does---scan the \texttt{.aux} file (or files, if we're |\include|ing 
% things) for certain ``commands'' and use them to locate the files to 
% cross-reference, get parameter settings (like for example entries for 
% the index exclude list), and so on. It should then cross-reference the 
% file(s) and write the index entries in a suitable format to some file 
% (appending them to the \texttt{.idx} file is probably the easiest 
% solution). This way, it is (almost) as simple to use as the built-in 
% cross-referencing and the extra work for supporting it is (in 
% comparison to not supporting it) negligible.
% 
% \begin{xrefcmd}{ExternalXRefMsg}
% \begin{macro}{\SendExternalXRefMsg}
%   \changes{prot2}{2000/07/28}{Added \cs{if@filesw} test. (LH)}
%   It's hardly possible to predict all kinds of information that one 
%   might want to give to an XXR, and neither can one assume that 
%   there is only one XXR program that will read the \texttt{.aux} 
%   file. A complicated project might involve code in several languages, 
%   and each language might have its own XXR. 
%   Therefore the general XXR-command (text in an \texttt{.aux} file which 
%   is used for communicating information to an XXR) simply has the syntax
%   \begin{quote}
%     \verb*|%%ExternalXRefMsg |\marg{who}\verb*| |\marg{what}
%   \end{quote}
%   \meta{who} identifies the XXR this message is meant for. It must be 
%   balanced text to \TeX\ and may not contain any whitespace, but can 
%   otherwise be rather arbitrary. \meta{what} is the actual message. It 
%   too must be balanced text to \TeX\ and it may not contain any 
%   newlines, but it is otherwise arbitrary. 
%   \index{whitespace restrictions}^^A
%   The reason for these restrictions on the contents of \meta{who} and 
%   \meta{what} is that many (maybe even most) scripting languages 
%   (which is what at least the \texttt{.aux}-scanning part of an 
%   XXR will probably be written in) are much better at recognising 
%   words on a line than they are at recognising a brace-delimited group. 
%   By accepting these restrictions, one can make sure that all XXRs can 
%   correctly determine whether a message is for them, even if they see 
%   the \texttt{.aux} file as a sequence of lines composed of 
%   whitespace-delimited words.
%   
%   |\SendExternalXRefMsg| is the basic command for writing 
%   |ExternalXRefMsg|s to the \texttt{.aux} file, but it might be 
%   recommendable that XXR writers provide users with a set of commands 
%   that have more specific purposes. The syntax of the 
%   |\Send|\-|External|\-|XRef|\-|Msg| command is (hardly surprising)
%   \begin{quote}
%     |\SendExternalXRefMsg|\marg{who}\marg{what}
%   \end{quote}
%   |\SendExternalXRefMsg| does a protected full expansion (like 
%   |\protected@edef|) of its arguments at the time it is called.
%    \begin{macrocode}
\newcommand\SendExternalXRefMsg[2]{%
   \begingroup
      \if@filesw
         \let\protect\@unexpandable@protect
         \immediate\write\@auxout{\@percentchar\@percentchar
            ExternalXRefMsg {#1} {#2}}%
      \fi
   \endgroup
}
%    \end{macrocode}
% \end{macro}\end{xrefcmd}
% 
% The remaining commands in this subsection address complications that 
% exist because of how \texttt{.dtx} files are generally written, and 
% thus constitutes difficulties that all XXRs will have to face.
% 
% \begin{xrefcmd}{ExternalXRefFile}
%   The usual way to write \texttt{.dtx} files is to include a 
%   driver---a~short piece of uncommented \LaTeX\ code which contains 
%   the necessary preamble material and a document body which mainly 
%   contains a |\DocInput| for the \texttt{.dtx} file itself---but it 
%   is also usually understood that this driver may be copied to another 
%   file if necessary and larger projects usually have a completely 
%   separate driver file. Therefore an XXR cannot be expected to be 
%   able to find the file(s) to cross-reference simply by changing 
%   suffix on the name of the \texttt{.aux} file it reads its commands 
%   from. A more intricate method must be used.
%   
%   To tell the XXR that ``here I input the file \dots'', one includes 
%   an |External|\-|XRef|\-|File| XXR-command in the \texttt{.aux} file. 
%   Its syntax is
%   \begin{quote}
%     \verb*|%%ExternalXRefFile |\marg{cmd}\verb*| |\marg{file}^^A
%     \verb*| |\marg{what}
%   \end{quote}
%   \meta{file} is the name (as given to |\input| or the like) of the 
%   file to input. \meta{cmd} is either \texttt{begin} (begin of 
%   \meta{file}) or \texttt{end} (end of \meta{file}). \meta{what} is a 
%   declaration of what is in the file; XXRs should use it to determine 
%   whether they should process this file or not. \meta{what} is empty 
%   if all XXRs should process the file, but for example |\IndexInput| 
%   will put \texttt{TeX} here to declare that the contents of this file 
%   are \TeX\ code and only XXRs that cross-reference \TeX\ code need to 
%   process this file.
%   
%   In connection to this, it should be mentioned that XXRs must also look 
%   for (and act on) |\@input|\penalty\hyphenpenalty\marg{auxfile} commands 
%   that |\include| or |\DocInclude| has written to the \texttt{.aux} file, 
%   since these \meta{auxfile}s can also contain commands for the XXR 
%   that should result in output to the same \texttt{.idx} file. In 
%   particular, the |ExternalXRefFile| XXR-commands that are written 
%   because of a |\DocInclude| will be written to such an \meta{auxfile}.
% \end{xrefcmd}
% 
% \begin{xrefcmd}{ExternalXRefSync}
%   Most XXRs will probably find it an unreasonable task to keep exact 
%   track of all codelines in all documents, i.e., they will sometimes 
%   think that a piece of code contains more or fewer numbered 
%   codelines than it actually does. If for example a document contains 
%   code such as\iffalse
%<*example>
%  \fi
%\begin{verbatim}
%% \iffalse
%%    \begin{macrocode}
%Etaoin Shrldu
%%    \end{macrocode}
%% \fi
%\end{verbatim}\iffalse
%</example>
%\fi
%   then all reasonable XXRs will probably be fooled into thinking that 
%   the \texttt{Etaoin Shrldu} line is a numbered codeline. This would 
%   of course be very bad if an XXR thought it should cross-reference 
%   the contents of this line, but that shouldn't usually be a problem 
%   since the specifications\footnote{I imagine these specifications 
%   will consist of a list of \package{docstrip} options (modules), 
%   possibly used in combination with restrictions on the names of 
%   surrounding environments.} of what code should be cross-referenced 
%   will probably make it clear that the above line should not be 
%   cross-referenced. Code such as the above will still be problematic 
%   however, as it will cause the XXR to believe that the 
%   \texttt{codelineno} counter has another value on any following 
%   line that is indexed than it actually has in the typeset 
%   document. This will cause index entries to refer to another line 
%   than it actually should.
%   
%   To overcome this, the |ExternalXRefSync| XXR-command can be used to 
%   tell the XXR what the corresponding values of |\inputlineno| and 
%   \texttt{codelineno} are. Its syntax is
%   \begin{quote}
%     \verb*|%%ExternalXRefSync |\marg{inputlineno}\verb*| |^^A
%     \marg{codelineno}
%   \end{quote}
%   where \meta{inputlineno} is the expansion of |\the\inputlineno| and 
%   \meta{codelineno} is the expansion of |\thecodelineno|, both 
%   expanded at the same point in the program. Note here that the first 
%   line of a file is line number 1, that line number 0 is used to 
%   denote ``just before the first line'', and that \texttt{codelineno} 
%   gets increased immediately before the number is typeset (i.e., 
%   \texttt{codelineno} contains the number of the last numbered 
%   codeline).
% \end{xrefcmd}
%   
% This doesn't support external cross-referencing by pages, since doing 
% that requires that the document outputs a lot more information to the 
% \texttt{.aux} file. In principle, one could put a |\mark|\penalty0
% |{\thecodelineno}| in |\PrintCodelineNo| and a |\write| in the page 
% header which outputs to the \texttt{.aux} file which range of 
% codelines correspond to a given page, but the \LaTeXe\ sectioning 
% commands' use of marks tends to interfere with this. The \LaTeXplus\ 
% package \package{xmarks} will probably solve that problem, though.
% 
% \begin{macro}{\syncexternalxref}
%   \changes{prot2}{2000/07/28}{New name for \cs{SendExternalXRefSync}. 
%      Also added \cs{if@filesw} test. (LH)}
%      ^^A Johann Sebastian Bach: 1685/03/21--1750/07/28
%   The |\syncexternalxref| command writes an |ExternalXRefSync| 
%   XXR-command for the current line number and value of the 
%   \texttt{codelineno} counter to \texttt{.aux} file. It is used for 
%   synchronizing the numbered codeline counter that an XXR maintains with 
%   the \texttt{codelineno} counter that is used for numbering codelines 
%   in the typeset document after a piece of code in the document that 
%   some XXR is likely to misinterpret. |\sync|\-|external|\-|xref| 
%   shouldn't be used inside \texttt{macrocode} environments (or the 
%   like) as they tend to read ahead in the file---instead it is best 
%   placed shortly after such an environment. |\sync|\-|external|\-|xref| 
%   has no arguments.
%    \begin{macrocode}
\newcommand\syncexternalxref{%
   \if@filesw
      \immediate\write\@auxout{\@percentchar\@percentchar 
         ExternalXRefSync {\the\inputlineno} {\thecodelineno}%
      }%
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{xrefcmd}{ExternalXRefWrap}
%   The |\DocInclude| command complicates matters for XXRs by redefining 
%   things so that the \texttt{codelineno} counter only makes up a part 
%   of the line numbers appearing in the index. The purpose of the 
%   |External|\-|XRef|\-|Wrap| XXR-command is to inform XXRs about such 
%   changes. The command
%   \begin{quote}
%     \verb*|%%ExternalXRefWrap {|\meta{prefix}\verb*|} {|^^A
%     \meta{suffix}|}|
%   \end{quote}
%   means that codeline numbers written to the index should have the form 
%   \begin{quote}
%     \meta{prefix}\meta{codelineno}\meta{suffix}
%   \end{quote}
%   This setting takes effect from the next |External|\-|XRef|\-|Sync| 
%   and stays in effect until the end of the document or until another 
%   |External|\-|XRef|\-|Wrap| overrides it. The state at the beginning 
%   of the document is to have both \meta{prefix} and \meta{suffix} 
%   empty.
% \end{xrefcmd}
% 
% 
% \begin{macro}{\XD@input}
%   The |\XD@input| command is a version of |\input| which takes care 
%   to inform XXRs that another file is being |\input|ted. Its syntax is
%   \begin{quote}
%     |\XD@input|\marg{file}\marg{what}
%   \end{quote}
%   where \meta{file} is the name of the file to |\input| and \meta{what} 
%   is the contents of the file, as specified in 
%   |External|\-|XRef|\-|File| commands.
%    \begin{macrocode}
\def\XD@input#1#2{%
   \if@filesw
      \immediate\write\@auxout{\@percentchar\@percentchar
         ExternalXRefFile {begin} {#1} {#2}%
      }%
      \immediate\write\@auxout{\@percentchar\@percentchar
         ExternalXRefSync {0} {\thecodelineno}%
      }%
   \fi
   \input{#1}%
   \if@filesw
      \immediate\write\@auxout{\@percentchar\@percentchar
         ExternalXRefFile {end} {#1} {#2}%
      }%
      \immediate\write\@auxout{\@percentchar\@percentchar
         ExternalXRefSync {\the\inputlineno} {\thecodelineno}%
      }%
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\DocInput}
%   The |\DocInput| command is redefined so that it writes 
%   |External|\-|XRef|\-|File| and |External|\-|XRef|\-|Sync| XXR-commands 
%   to the \texttt{.aux} file. Furthermore, with \package{xdoc} one 
%   should always use the |\DocInput| command (or some command based on 
%   it, like |\DocInclude|) for inputting a file where percent is an 
%   `ignore' character---even when one such file inputs another. (Doing 
%   that didn't work with the \package{doc} definition, as it always 
%   called |\MakePercentComment| upon return, but the \package{xdoc} 
%   definition contains code for dealing with that.)
%    \begin{macrocode}
\renewcommand\DocInput[1]{%
   \relax
   \ifnum \catcode`\%=14
      \expandafter\@firstoftwo
   \else
      \expandafter\@secondoftwo
   \fi{%
      \MakePercentIgnore\XD@input{#1}{}\MakePercentComment
   }{\XD@input{#1}{}}%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\IndexInput}
%   The |\IndexInput| command also needs to be redefined to write 
%   XXR-commands to the \texttt{.aux} file. It would 
%   probably be enough here to write an |External|\-|XRef|\-|Sync| 
%   after the file has been |\input| since no external 
%   cross-referencing of |\IndexInput|ted files is needed, but I do the 
%   more verbose variant here just to exemplify how these things would 
%   look for other languages.
%    \begin{macrocode}
\renewcommand\IndexInput[1]{%
   \begingroup
      \macro@code
      \frenchspacing
      \@vobeyspaces
      \XD@input{#1}{TeX}%
      \endmacrocode
   \endgroup
}
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \section{Two-sided printing}
% \label{Sec:Twoside}
% 
% The main problem one faces when reimplementing \package{doc} so that 
% the marginal material always appears in the outer margin in two-sided 
% documents is that the justification of \package{doc}'s marginal 
% material is asymmetric; it always extends outwards. This means that 
% the justification to use when typesetting the marginal material must 
% depend on whether it is to be put on a left or a right 
% page---something which cannot be determined for sure when the 
% material is typeset! This is a minor difficulty if the marginal material 
% is put in place using \LaTeX's |\marginpar| command, as that allows the 
% user to supply different versions of the marginal paragraph for left and 
% right margin placements. It is however a major difficulty if the 
% marginal material is displaced out into the margin from within the main 
% galley (like the \texttt{macro} environment of \package{doc} does), 
% since the output routine is never involved.
% 
% Even though this difficulty provides arguments for using a |\marginpar| 
% mechanism for all text that is put in the margin, that will not be 
% done in \package{xdoc} (but maybe it will in some successor). 
% Instead \package{xdoc} contains a general mechanism which uses data 
% written to the \texttt{.aux} file for determining whether a piece of 
% text was put on an odd or even numbered page the \emph{last} time the 
% document was typeset. By the usual convergence of page breaks in a 
% \LaTeX\ document, this will eventually produce a typeset document 
% with the marginal material consistently in the outer margin.
% 
% The mechanism works as follows. The places in the document (the 
% document source) at which it is necessary to determine whether 
% something is going to appear on an even (left) or an odd (right) page 
% are called ``page situations''\footnote{I know it's not a particularly 
% good name. Suggestions for better names are gracefully accepted.} or 
% just ``situations''. In each situation, a relatively simple test (is 
% the \texttt{page} counter currently even or odd?) which is right more 
% often than not is used as a first guess, and both the guess, the 
% placement actually used, and the correct answer (determined from the 
% value of \texttt{page} when the piece of text is shipped out) are 
% recorded in the \texttt{.aux} file. If the guess (for the current 
% situation) coincided with the correct answer the last time the 
% document was typeset then the guess determined now is used, otherwise 
% the opposite of the guess determined now is used. Finally, when at 
% |\end{document}| the \texttt{.aux} file is inputted to check for 
% changed labels, the placements used are also checked and the user is 
% given a suitable warning if there was an incorrect one.
% 
% \begin{macro}{\IfOddPageSituation}
%   The |\IfOddPageSituation| macro is the user level test for whether 
%   the current page situation appears on an odd or an even page. It 
%   has the syntax
%   \begin{quote}
%     |\IfOddPageSituation|\marg{odd}\marg{even}
%   \end{quote}
%   and this will expand to \meta{odd} if the current situation is 
%   expected to end up on an odd page (based on how correct it was to 
%   look at the value of \texttt{page} last time) and to \meta{even} 
%   otherwise. In single-sided mode, it always expands to \meta{even}. 
%   In two-sided mode, |\IfOddPageSituation| is redefined for the new 
%   situation each time |\StepPageSituation| is called.
%    \begin{macrocode}
\let\IfOddPageSituation=\@secondoftwo
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\StepPageSituation}
%   \changes{prot2.1}{2000/12/19}{Now also setting 
%      \cs{IfOddPageSituation}, instead of having that macro performing 
%      the test each time it is used. This fixes a rarely occuring bug 
%      which occurs when a page is shipped out between 
%      \cs{StepPageSituation} and a corresponding 
%      \cs{IfOddPageSituation}. (LH)}
% \begin{macro}{\macro@cnt}
% \begin{macro}{\XD@next@wrong}
% \begin{macro}{\XD@wrongs@list}
%   The |\StepPageSituation| command is called to inform the page 
%   situation mechanism that a new situation has begun. The rule for 
%   when you need to use |\Step|\-|Page|\-|Situation| is simple: if you 
%   use |\IfOdd|\-|Page|\-|Situation| in two places which may end up on 
%   different pages, then there must be a |\Step|\-|Page|\-|Situation| 
%   between them. There is no code which automatically calls 
%   |\Step|\-|Page|\-|Situation|---not even |\clearpage| or other 
%   macros which force page breaks do this---hence macros which use 
%   the page situation mechanism must always call |\Step|\-|Page|\-^^A
%   |Situation| explicitly when a new situation begins.
% 
%   Since the |\macro@cnt| count register isn't used for stacking 
%   marginal headings (``macro'' names) anymore (see below), it is 
%   employed for enumerating page situation. |\XD@next@wrong| is a macro 
%   which contains the number of the next situation in which the guess 
%   was wrong last time. Unless |\XD@next@wrong|${}={}$|\macro@cnt|, the 
%   guess was right last time. All assignments to |\macro@cnt| and
%   |\XD@next@wrong| are global.
%   
%   |\XD@wrongs@list| is a list of all the wrong guesses. It has the 
%   syntax
%   \begin{quote}
%     |\@elt|\marg{guess no.}|\@elt|\marg{guess no.}\dots
%     |\@elt|\marg{guess no.}
%   \end{quote}
%   where the \meta{guess no.}s are the numbers of the wrong guesses, in 
%   increasing order. The contents of |\XD@wrongs@list| are collected 
%   when the \texttt{.aux} file is inputted at |\begin|\B|{document}|, 
%   and they are removed again as \TeX\ passes the situation in the 
%   document that they apply to. All assignments to |\XD@wrong@list| are 
%   global.
%   
%   Calling |\StepPageSituation| increases |\macro@cnt| by one, 
%   updates |\XD@|\B|next@|\B|wrong| and |\XD@|\B|wrong@|\B|list| 
%   appropriately, and sets |\IfOdd|\B|Page|\B|Situation| to 
%   |\@firstoftwo| or |\@secondoftwo| (whichever is correct for this 
%   situation). |\@next| is a list management macro from the \LaTeX\ 
%   kernel.
%    \begin{macrocode}
\if@twoside
   \def\StepPageSituation{%
      \global\advance \macro@cnt \@ne
      \ifnum \XD@next@wrong<\macro@cnt
         \global\@next\XD@next@wrong\XD@wrongs@list{}{%
            \let\XD@next@wrong\maxdimen
         }%
      \fi
      \ifnum \ifodd\c@page -\fi \@ne=%
         \ifnum \XD@next@wrong=\macro@cnt -\fi \@ne
         \global\let\IfOddPageSituation\@secondoftwo
      \else
         \global\let\IfOddPageSituation\@firstoftwo
      \fi
   }
   \def\XD@next@wrong{-\maxdimen}
   \let\XD@wrongs@list\@empty
\else
   \let\StepPageSituation=\relax
\fi
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% 
% \begin{macro}{\RecordPageSituation}
%   The |\RecordPageSituation| command generates a |\write| whatsit node 
%   which records the outcome of the current page situation. It is the 
%   location of this whatsit node that determines on which page a 
%   certain situation is considered to occur. If you don't execute this 
%   macro for a certain page situation, the first guess will always be 
%   used for that situation and no warnings will be given if that guess 
%   is incorrect. In single-sided mode, this is a no-op (thus you should 
%   better place it somewhere where it doesn't affect spacing). 
%   Furthermore you must make sure that \TeX\ does not change the value 
%   of the \texttt{page} counter between a |\StepPageSituation| and its 
%   corresponding |\RecordPageSituation|, since the |\ifodd| test must 
%   yield the same result in both cases.
%   
%    \begin{macrocode}
\if@twoside
   \def\RecordPageSituation{%
      \if@filesw
         \edef\@tempa{%
            \string\XD@situation{\the\macro@cnt}{%
               \ifodd\c@page 1\else 0\fi
            }{\IfOddPageSituation{1}{0}}%
         }%
         \write\@auxout\expandafter{\@tempa{\ifodd\c@page 1\else 0\fi}}%
      \fi
   }%
\else
   \let\RecordPageSituation=\relax
\fi
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\XD@situation}
%   \changes{prot2}{2000/07/13}{Changed to allow multiple 
%     \cs{XD@situation} commands for the same situation. This is 
%     necessary for coping with documents which \cs{include} files. (LH)}
%   \changes{prot2}{2000/07/26}{Made redefinition at begin document 
%      global. (LH)}
% \begin{macro}{\XD@check@situation}
%   |\XD@situation| is the command that will be written to the 
%   \texttt{.aux} file with the data about how the situation turned out. 
%   Its syntax is
%   \begin{quote}
%     |\XD@situation|\marg{number}\marg{guess}\marg{did}\marg{correct}
%   \end{quote}
%   where \meta{number} is the number of the situation, and 
%   \meta{guess}, \meta{did}, and \meta{correct} describe what the 
%   guess, the actual action done, and what the correct action to do 
%   respectively was. \meta{guess}, \meta{did}, and \meta{correct} are 
%   either |0| (denoting even page) or |1| (denoting odd page).
%   
%   The definition for |\XD@situation| set here is the one which will 
%   be in force when the \texttt{.aux} file is inputted at |\begin|\B
%   |{document}|; its purpose is to build the |\XD@wrongs@list|. 
%   |\XD@check@situation| is the definition for |\XD@situation| which 
%   will be in force when the \texttt{.aux} file is inputted at 
%   |\end|\B|{document}|; its purpose is to check if anything was 
%   incorrectly placed.
%   
%   The main problem |\XD@situation| has to face is that text in the 
%   \texttt{.dvi} file needs not appear in exactly the same order as it 
%   was typeset, and it is therefore possible that |\XD@situation|s in 
%   the \texttt{.aux} file do not appear in increasing \meta{number} 
%   order. Because of this, |\XD@situation| must sort the 
%   |\XD@wrongs@list| while constructing it. The only reasonable 
%   algorithm for this seems to be insertion sort, but as the items to 
%   insert are almost surely almost sorted, a special check is done in 
%   the beginning to see if that is the case. |\XD@next@wrong| is used 
%   in this to store the number of the last item so far inserted into 
%   the |\XD@wrongs@list|. By only assigning |\XD@next@wrong| locally 
%   here, one is relieved of having to reset it in |\AtBeginDocument| 
%   code.
%   
%   When sorting is actually applied, a new item |\@elt|\marg{insert} 
%   is inserted through expanding the list. When doing that, the |\@elt| 
%   macro has the syntax
%   \begin{quote}
%     |\@elt|\,\meta{flag}\,\marg{number}\,\meta{next}
%   \end{quote}
%   where \meta{flag} is |\BooleanTrue| or |\BooleanFalse|, \meta{number} 
%   is the item that the |\@elt| belong to, and \meta{next} is either the 
%   next |\@elt| or |\@gobble| (if this is the last). The \meta{flag} 
%   specifies whether the item has been inserted; |\Boolean|\B|True| means 
%   that it has. The above |\@elt|-sequence will expand to
%   \begin{quote}
%     |\noexpand|\,|\@elt|\,\marg{number}\,\meta{next}\,|\BooleanTrue|
%   \end{quote}
%   if \meta{flag} is |\BooleanTrue|, or \meta{flag} is |\BooleanFalse| 
%   and \meta{number} is equal to \meta{insert}. It will expand to
%   \begin{quote}
%     |\noexpand|\,|\@elt|\,\marg{number}\,\meta{next}\,|\BooleanFalse|
%   \end{quote}
%   if \meta{flag} is |\BooleanFalse| and \meta{number} is less than 
%   \meta{insert}. It expands to
%   \begin{quote}
%     |\noexpand|\,|\@elt|\,\marg{insert}\,|\noexpand|\,|\@elt|^^A
%       \,\marg{number}\\
%     \meta{next}\,|\BooleanTrue|
%   \end{quote}
%   if \meta{flag} is |\BooleanFalse| and \meta{number} is greater than 
%   \meta{insert}.
%   
%    \begin{macrocode}
\if@twoside
   \def\XD@situation#1#2#3#4{%
      \if #2#4\else
         \ifnum #1<\XD@next@wrong
            \begingroup
               \def\@elt##1##2##3{%
                  \noexpand\@elt
                  \ifcase
                     \ifx ##1\BooleanTrue 0%
                     \else\ifnum ##2<#1 1%
                     \else\ifnum ##2>#1 2%
                     \else 0%
                     \fi\fi\fi
                  \space
                     {##2}\expandafter\@secondoftwo
                  \or
                     {##2}\expandafter\@firstoftwo
                  \else
                     {#1}\noexpand\@elt{##2}\expandafter\@secondoftwo
                  \fi{##3\BooleanFalse}{##3\BooleanTrue}%
               }%
               \xdef\XD@wrongs@list{%
                  \expandafter\expandafter \expandafter\@elt 
                  \expandafter\@firstoftwo \expandafter\BooleanFalse
                  \XD@wrongs@list \@gobble
               }%
            \endgroup
         \else\ifnum #1>\XD@next@wrong
            \def\XD@next@wrong{#1}%
            \expandafter\gdef \expandafter\XD@wrongs@list
               \expandafter{\XD@wrongs@list \@elt{#1}}%
         \fi\fi
      \fi
   }
   \def\XD@check@situation#1#2#3#4{%
      \if #3#4\else
         \PackageWarningNoLine{xdoc2}{Page breaks may have changed.%
            \MessageBreak Rerun to get marginal material right}%
         \let\XD@situation\@gobblefour
      \fi
   }
   \AtBeginDocument{\global\let\XD@situation\XD@check@situation}
\else
   \let\XD@situation\@gobblefour
\fi
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \begin{macro}{\XD@set@situation}
% \begin{macro}{\XD@write@situation@ckpt}
% \begin{macro}{\cl@@ckpt}
%   The page situation counter |\macro@cnt| is closely related to the 
%   \texttt{page} counter and it needs to be among the counters whose 
%   values are recorded in |\include| checkpoints, since the enumeration 
%   of situations will otherwise change when files are added to or 
%   removed from the |\@partlist|. It is not sufficient to simply set 
%   the value of |\macro@cnt| however; one must also advance to the 
%   correct position in the |\XD@wrongs@list| list and set 
%   |\XD@next@wrong| accordingly. The |\XD@set@situation| command has 
%   the syntax
%   \begin{quote}
%     |\XD@set@situation|\marg{number}
%   \end{quote}
%   It sets |\macro@cnt| to \meta{number} and updates |\XD@wrongs@list| 
%   and |\XD@|\B|next@|\B|wrong| accordingly.
%    \begin{macrocode}
\if@twoside
   \def\XD@set@situation#1{%
      \global\macro@cnt=#1\relax
      \loop \ifnum \XD@next@wrong<\macro@cnt
         \global\@next\XD@next@wrong\XD@wrongs@list{}{%
            \let\XD@next@wrong\maxdimen
         }%
      \repeat
   }
\else \let\XD@set@situation=\@gobble \fi
%    \end{macrocode}
%   
%   The |\XD@write@situation@ckpt| macro writes an |\XD@set@situation| 
%   command to the \texttt{.aux} file in the way that |\@wckptelt| 
%   writes |\setcounter| commands for normal counters. A problem for 
%   |\XD@write@situation@ckpt| is that it will have to appear in a 
%   macro which is regularly subjected to the |\xdef| in |\@cons|. For 
%   that reason, it will simply expand to itself whenever |\@elt| isn't 
%   |\@wckptelt|.
%    \begin{macrocode}
\if@twoside
   \def\XD@write@situation@ckpt{%
      \ifx \@elt\@wckptelt
         \immediate\write\@partaux{%
            \string\XD@set@situation{\the\macro@cnt}%
         }%
      \else
         \noexpand\XD@write@situation@ckpt
      \fi
   }
   \expandafter\def \expandafter\cl@@ckpt
      \expandafter{\cl@@ckpt \XD@write@situation@ckpt}
\fi
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% 
% 
% \section{The list of changes}
% \label{Sec:Changes}
% 
% Reimplementations elsewhere have required a few modifications related 
% to the |\changes| command. There are a lot of other things that could 
% and perhaps should be done with these mechanisms, though.
% 
% \begin{macro}{\saved@macroname}
%   The contents of the |\saved@macroname| macro now have the syntax
%   \begin{quote}
%     \marg{sort key}\marg{text}
%   \end{quote}
%   i.e., exactly like the argument sequence of |\LevelSorted|. It's not 
%   fed to that macro right now, but it is not unlikely that it will in 
%   the future. The default definition corresponds to the default 
%   definition in \package{doc}.
%    \begin{macrocode}
\def\saved@macroname{{ }{\generalname}}
%    \end{macrocode}
%   Unlike the case in \package{doc}, the formatting of the text in 
%   |\saved@macroname| must be included.
% \end{macro}
% 
% \begin{macro}{\if@version@key@}
%   The |@version@key@| switch is used for supporting intelligent 
%   sorting of version numbers. It is normally false, but at times 
%   where the version number argument of |\changes| is being expanded 
%   because it will be used as a sort key then it is true. This is used 
%   by the |\uintver| macro. Assignments to this switch are as a rule 
%   global, since it is never true for any longer time.
%   \changes{prot2.4}{2002/11/01}{Switch added. (LH)}
%    \begin{macrocode}
\newif\if@version@key@
\@version@key@false
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\uintver}
%   The |\uintver| command can be used in the \meta{version} argument 
%   of |\changes| to ensure that (unsigned) integers are sorted in 
%   mathematical rather than ASCII order by \package{makeindex}. Thus 
%   if for example version |1.10| is later than version |1.9| then one 
%   should write this as
%   \begin{quote}
%     |\changes{1.\uintver{10}}{|\dots
%   \end{quote}
%   The general syntax is
%   \begin{quote}
%     |\uintver|\marg{number}
%   \end{quote}
%   and this expands completely in \TeX's mouth.
%   \changes{prot2.4}{2002/11/01}{Command added. (LH)}
%   
%   The idea is that 0--9 are compared as 0--9, whereas 10--99 are 
%   compared as A10--A99, 100--999 are compared as B100-B999, and so on. 
%   The comparisons are correct up to 99999, but it could easily be 
%   extended further.
%    \begin{macrocode}
\newcommand*\uintver[1]{%
   \if@version@key@
      \ifnum #1>9
         \ifnum #1<100
            A%
         \else\ifnum #1<\@m
            B%
         \else\ifnum #1<\@M
            C%
         \else
            D%
         \fi\fi\fi
      \fi
   \fi
   \expandafter\@firstofone \expandafter{\number#1}%
}
%    \end{macrocode}
% \end{macro}
% 
%   
% \begin{macro}{\changes@}
%   This |\changes@| is a simple redefinition of the \package{doc} 
%   macro with the same name. The main difference is that all 
%   formatting of the second entry level has been taken out---it is 
%   supposed to be provided in |\saved@macroname|---but in addition to 
%   that the date is being used as a third level sort key and |\uintver| 
%   may be used in the version number to correct the data.
%   \changes{prot2.4}{2002/11/01}{Added support for \cs{uintver}. (LH)}
%   
%   The former makes more sense for projects where the date is 
%   increased faster than the version number and it doesn't change 
%   anything relevant in the remaining cases. The latter is necessary 
%   if version numbers are assigned for example by CVS.
%    \begin{macrocode}
\def\changes@#1#2#3{%
   \global\@version@key@true
   \protected@edef\@tempa{#1}%
   \global\@version@key@false
   \protected@edef\@tempa{%
      \noexpand\glossary{%
         \@tempa\actualchar#1\levelchar
         \expandafter\@firstoftwo\saved@macroname\actualchar
            \expandafter\@secondoftwo\saved@macroname:\levelchar
         #2\actualchar#3%
      }%
   }%
   \@tempa
   \endgroup
   \@esphack
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@wrglossary}
%   \changes{prot2.2}{2001/02/13}{Redefinition added. (LH)}
% \begin{macro}{\XD@glossary@keyword}
%   \changes{prot2.2}{2001/02/13}{Macro added. (LH)}
%   The |\@wrglossary| macro is the one which actually writes entries 
%   to the \texttt{.glo} file. It is redefined by \package{xdoc} to put 
%   the contents of |\XD@glossary@keyword|, rather than a hardwired 
%   |\glossaryentry|, in front of the glossary entry. 
%   |\XD@glossary@keyword| is redefined by the \package{docindex} 
%   package~\cite{docindex}.
%    \begin{macrocode}
\def\@wrglossary#1{%
   \protected@write\@glossaryfile{}%
      {\XD@glossary@keyword{#1}{\thepage}}%
   \endgroup
   \@esphack
}
\@ifundefined{XD@glossary@keyword}{%
   \edef\XD@glossary@keyword{\@backslashchar glossaryentry}%
}{}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\definechange}
% \begin{macro}{\XD@definechange}
%   The |\definechange| command has the syntax
%   \begin{quote}
%     |\definechange|\marg{name}\marg{version}\marg{date}\marg{text}
%   \end{quote}
%   The three last arguments are precisely like the arguments of 
%   |\changes|, but |\definechange| doesn't write the change to the 
%   \texttt{.glo} file; instead it stores them away as the ``named 
%   change'' \meta{name}, for later use in the |\usechange| command.
%    \begin{macrocode}
\newcommand\definechange{%
   \begingroup\@sanitize
   \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
   \expandafter\endgroup \XD@definechange
}
\def\XD@definechange#1#2#3#4{\@namedef{XD@ch-#1}{{#2}{#3}{#4}}}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% The named changes are stored in the 
% \describecsfamily{XD@ch-\meta{name}}|\XD@ch-|\meta{name} family of 
% control sequences. These are parameterless macros with replacement 
% texts of the form
% \begin{quote}
%   \marg{version}\marg{date}\marg{text}
% \end{quote}
% 
% \begin{macro}{\usechange}
% \begin{macro}{\XD@usechange}
%   \changes{prot2.4}{2002/11/01}{Added support for \cs{uintver}. (LH)}
%   To use a named change defined earlier, one of course uses the 
%   command |\usechange|, which has the syntax
%   \begin{quote}
%     |\usechange|\marg{name}
%   \end{quote}
%   The effect of this is similar to that of a general |\changes| 
%   (i.e., it appears outside all \texttt{macro}-like environments) with 
%   the arguments specified in the |\definechange|, but this also 
%   includes the macro (or whatever) name with the page number, using 
%   the encapsulation mechanism in \package{makeindex}.
%    \begin{macrocode}
\newcommand*\usechange[1]{%
   \@ifundefined{XD@ch-#1}{%
      \PackageError{xdoc2}{Named change `#1' undefined}\@eha
   }{%
      \expandafter\expandafter \expandafter\XD@usechange
         \csname XD@ch-#1\endcsname
   }%
}
\def\XD@usechange#1#2#3{%
   \def\@tempa{{ }{\generalname}}%
   \ifx \@tempa\saved@macroname
      \let\@tempa\@empty
   \else
      \protected@edef\@tempa{%
         \encapchar labelednumber%
         {\expandafter\@secondoftwo\saved@macroname}%
      }
   \fi
   \global\@version@key@true
   \protected@edef\@tempb{#1}%
   \global\@version@key@false
   \glossary{%
      \@tempb\actualchar #1\levelchar
      \space\actualchar\generalname:\levelchar
      #2\actualchar#3\@tempa
   }%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\labelednumber}
%   T