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