home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 3 / Meeting_Pearls_III.iso / Pearls / texmf / inputs / distribs / doc / doc.doc < prev    next >
Encoding:
Text File  |  1992-09-08  |  187.0 KB  |  4,555 lines
  1. % \iffalse meta-comment
  2. %
  3. % Copyright (C) 1989-1992 by Frank Mittelbach.  All rights reserved.
  4. % 
  5. % This file is part of the doc package.
  6. % 
  7. % IMPORTANT NOTICE:
  8. % 
  9. % You are not allowed to change this file.  You may however copy
  10. % this file to a file with a different name and then change the
  11. % copy if you obey the restrictions on file changes described in
  12. % readme.mz.
  13. % 
  14. % You are NOT ALLOWED to distribute this file alone.  You are NOT
  15. % ALLOWED to take money for the distribution or use of this file
  16. % (or a changed version) except for a nominal charge for copying
  17. % etc.
  18. % 
  19. % You are allowed to distribute this file under the condition that
  20. % it is distributed together with all files mentioned in
  21. % readme.mz0.
  22. % 
  23. % If you receive only some of these files from someone, complain!
  24. % 
  25. % However, if these files are distributed by established suppliers
  26. % as part of a complete TeX distribution, and the structure of the
  27. % distribution would make it difficult to distribute the whole set
  28. % of files, *those parties* are allowed to distribute only some of
  29. % the files provided that it is made clear that the user will get
  30. % a complete distribution-set upon request to that supplier (not
  31. % me).  Notice that this permission is not granted to the end
  32. % user.
  33. % 
  34. % 
  35. % For error reports in case of UNCHANGED versions see readme.mz
  36. % 
  37. % 
  38. % \fi
  39. % ^^A -*-LaTeX-*-
  40.  
  41. % ^^A These shouldn't come out in .ist files, hence the module
  42. % ^^A comments, or in the printed version, hence temporary comment
  43. % ^^A category for `<'
  44. %\catcode`\<=14
  45. %<*style>
  46. \def\fileversion{v1.7k} 
  47. \def\filedate{92/08/24}
  48. \def\docdate {92/08/28}
  49. %</style>
  50. %\catcode`\<=12
  51.  
  52. % \CheckSum{1985}
  53. %% \CharacterTable
  54. %%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
  55. %%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
  56. %%   Digits        \0\1\2\3\4\5\6\7\8\9
  57. %%   Exclamation   \!     Double quote  \"     Hash (number) \#
  58. %%   Dollar        \$     Percent       \%     Ampersand     \&
  59. %%   Acute accent  \'     Left paren    \(     Right paren   \)
  60. %%   Asterisk      \*     Plus          \+     Comma         \,
  61. %%   Minus         \-     Point         \.     Solidus       \/
  62. %%   Colon         \:     Semicolon     \;     Less than     \<
  63. %%   Equals        \=     Greater than  \>     Question mark \?
  64. %%   Commercial at \@     Left bracket  \[     Backslash     \\
  65. %%   Right bracket \]     Circumflex    \^     Underscore    \_
  66. %%   Grave accent  \`     Left brace    \{     Vertical bar  \|
  67. %%   Right brace   \}     Tilde         \~}
  68. %%
  69. %\iffalse    This is a METACOMMENT
  70. %           Everything up to the next `\ fi' (without a blank) will
  71. %           be ignored.  This is necessary because `%' may no longer
  72. %           be a comment mark when this file is read in.
  73. %           
  74.  
  75. % Style-option `doc' to use with LaTeX v2.09
  76. %% Copyright (C) 1989-1992 Frank Mittelbach, all rights reserved.
  77. %
  78. %
  79. % Version:     Date:     Changes:
  80. %
  81. %  1.0a        5.5.88    This is nothing but a collection of tests and
  82. %                        hacks. It is certainly going to be greatly
  83. %                        changed.
  84. %                        Better not to use it!
  85. %  1.1a        13.5.88   \theindex and \endtheindex redefined.
  86. %  1.1b        15.5.88   \bslash redefined.
  87. %                        \verbatim changed so that `%'s will be ignored.
  88. %  1.1c        19.5.88   Partly documented and \@temp... in
  89. %                        \theindex replaced by private commands.
  90. %                        Moreover, \pageshrink incorporated in the
  91. %                        computation of the amount of free space on the
  92. %                        page.
  93. %  1.1d        3.6.88    Something goes wrong during the computation of
  94. %                        \pageshrink, therefore a bit of empty space is
  95. %                        inserted by
  96. %                        hand, and some tracing information introduced.
  97. %                        It can't stay like that!!
  98. %  1.2a        23.9.88   Documentation of the macros in DOC-format,
  99. %                        i.e. so that this file can document itself.
  100. %  1.2b        7.10.88   Change of the index environment.
  101. %  1.2c        10.10.88  Further Documentation.
  102. %  1.2d        19.10.88  \the before \catcode eliminated. (thanks P.
  103. %                        Breitenlohner)
  104. %  1.3a        24.10.88  Scanning of macro names via \scanmacro
  105. %                        introduced to produce index entries.
  106. %  1.3b         16.1.89  Scanning of macro names via \scanmacro
  107. %                        improved.
  108. %                        At present only suitable for the makeindex
  109. %                        program
  110. %                        in conjunction with a special style file.
  111. %                        Macro environment in `macro' environment
  112. %                        renamed.
  113. %  1.3c         30.1.89  Index environment removed. Will be developed in
  114. %                        other style file.
  115. %  1.4a         7.2.89   \SpecialEscapechar added (may change its name).
  116. %  1.4b         7.3.89   \SpecialEscapechar reimplemented.
  117. %  1.4c         9.3.89   \parts of \short@macro reimplemented because
  118. %                        of some bugs in the macros and the makeindex
  119. %                        program.
  120. %                        Old definition of \b@slash used for \bslash.
  121. %                        \b@slash removed.
  122. %  1.4d         10.3.89  English documentation added.
  123. %  1.4e         10.3.89  private names for private macros.
  124. %                        \makespecialletters renamed to
  125. %                        \MakePrivateLetters
  126. %  1.4f         12.3.89  \short@macro changed (again)
  127. %                        documentation update.
  128. %  1.4g         13.3.89  \DoNotIndex macros changed.
  129. %  1.4h         13.3.89  \DoNotIndex macros changed to version with
  130. %                        \@elt
  131. %  1.4i         15.3.89  documentation update
  132. %  1.4j         15.3.89  \printindex inserted
  133. %  1.4k         21.3.89  documentation update
  134. %                        \PrintDescribe... and \Describe... added
  135. %                        macro env. + \SpecialIndex changed to accept \
  136. %  1.4l         29.3.89  macro env. changed once more (\macro@ added) to
  137. %                        correct bug introduced in v1.4k
  138. %                        \SpecialUsageIndex and \SpecialEnvIndex added.
  139. %  1.4m          3.4.89  \OnlyDescription added, \MakePrivateLetters
  140. %                        changed
  141. %  1.4n         10.4.89  \MakePrivateLetters changed back to
  142. %                        \makeatletter.
  143. %                        \ifnot@excluded changed to allow other things
  144. %                        than
  145. %                        macro names in the exclude list (e.g. \abc*)
  146. %  1.4o         14.4.89  Documentation update (Brian's correction)
  147. %                        \EnableCrossrefs changed to disable
  148. %                        \DisableCrossrefs
  149. %  1.4p         15.4.89  Documentation update \Finale added,
  150. %                        some changes to index.tex 
  151. %  1.4q         19.4.89  Documentation update \verbatim changed (RmS)
  152. %                        twocolumns env. added index.tex changed.
  153. %  1.4r         22.4.89  Changed \macro@ to support \par and
  154. %                        conditionals (might be wrong.)
  155. %  1.4s         23.4.89  Getting nearer to the `final' version.
  156. %                        \@sphack ...
  157. %                        placed in several macros. Documentation update.
  158. %                        Tried a \changes macro (somewhere in the middle
  159. %                        of this file by using \glossary (might work!)
  160. %  1.4t         24.4.89  Should change to 1.5? Index now uses multicols
  161. %                        added \c@IndexColumns. Other changes forgotten.
  162. %                        Some macro names renamed.
  163. %  1.5a         26.4.89  Finally 1.5:  changes to \makelabel in macro
  164. %                        env.
  165. %  1.5b and higher...    are documented with the (undocumented) \changes
  166. %                        feature.
  167. %  \changes{v1.5f}{89/4/29}{Thanks to Brian who documented the
  168. %                          {\tt\bslash changes} macro feature.}
  169. %  \changes{v1.5g}{89/5/07}{MacroTopsep now called MacrocodeTopsep and
  170. %                          new MacroTopsep added}
  171. %  \changes{v1.5h}{89/05/17}{All lines shortened to <72 characters}
  172. %  \changes{v1.5j}{89/06/09}{Corrections by Ron Whitney added}
  173. %  \changes{v1.5q}{89/11/03}{`\ldots{}Listing macros renamed to
  174. %                         `\ldots{}Input. Suggested by R. Wonneberger}
  175. %  \changes{v1.5W}{90/02/05}{Counter codelineno renamed to CodelineNo}
  176. %                        
  177. %
  178. %\fi
  179. %
  180. % \hyphenation{make-index}
  181. % 
  182. % \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
  183. % \DoNotIndex{\@flushglue,\@gobble,\@input}
  184. % \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
  185. % \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
  186. % \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
  187. % \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
  188. % \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
  189. % \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
  190. % \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
  191. % \DoNotIndex{\cal,\csname,\def,\documentstyle,\dospecials,\edef}
  192. % \DoNotIndex{\egroup}
  193. % \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
  194. % \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
  195. % \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
  196. % \DoNotIndex{\ifcase}
  197. % \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
  198. % \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
  199. % \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
  200. % \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
  201. % \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
  202. % \DoNotIndex{\strutbox}
  203. % \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
  204. % \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
  205. % \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
  206. % \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
  207. % \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
  208. % \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
  209. % \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
  210. % \DoNotIndex{\nopagebreak}
  211. % \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
  212. % \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
  213. % \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
  214. % \DoNotIndex{\[,\{,\},\]}
  215. % \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
  216. % \DoNotIndex{\baselineskip,\begin,\tw@}
  217. % \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
  218. % \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
  219. % \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
  220. % \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
  221. % \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
  222. % \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
  223. % \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
  224. % \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
  225. % \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
  226. % \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
  227. % \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
  228. % \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
  229. % \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
  230. % \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
  231. % \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
  232. % \DoNotIndex{\bfdefault}
  233. %
  234. % \MakeShortVerb{\"}
  235. % \setcounter{StandardModuleDepth}{1}
  236. %
  237. % {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print
  238. % \gdef\dimenvalue#1pt{$#1$pt}}  ^^A a register value with a - sign
  239. %
  240. % \makeatletter  ^^A hack so that this can be printed without multicols
  241. % \newif \ifmulticols
  242. % \ifhave@multicol \multicolstrue \fi
  243. % \makeatother
  244. % \title{The {\tt doc}--Option\thanks{%
  245. %    This file has version number \fileversion{} dated \filedate{}.
  246. %    The documentation was last revised on \docdate.
  247. %       }}
  248. % \author{Frank Mittelbach\thanks{Further commentary added at Royal
  249. %        Military College of Science by B. Hamilton Kelly; English
  250. %        translation of parts of the original German commentary
  251. %        provided by Andrew Mills; fairly substantial additions,
  252. %        particularly from {\tt newdoc},  and
  253. %        documentation of post-v1.5q features added at v1.7a by Dave
  254. %        Love (SERC Daresbury Lab).}\\
  255. %         Gutenberg Universit\"at Mainz}
  256. %
  257. % \maketitle
  258. %
  259. % \begin{abstract}
  260. %    This style option contains the definitions that are necessary to
  261. %    format the documentation of style files.  The style file was
  262. %    developed in Mainz in cooperation with the Royal Military College
  263. %    of Science.  This is an update which documents various changes
  264. %    and new features in {\sf doc} and integrates the features of {\sf
  265. %    newdoc}. 
  266. % \end{abstract}
  267. %
  268. % \ifmulticols
  269. % \addtocontents{toc}{\protect\begin{multicols}{2}}
  270. % \fi
  271. %
  272. % {\parskip 0pt                ^^A We have to reset \parskip
  273. %                              ^^A (bug in \LaTeX)
  274. % \tableofcontents
  275. % }
  276. %
  277. % \changes{v1.7a}{92/02/25}{Miscellaneous small changes to the text}
  278. %
  279. % \ifmulticols
  280. % \begin{multicols}{2}[\section*{Preface to version 1.7}]
  281. % \else \section*{Preface to version 1.7} \fi
  282. %
  283. % This version of {\tt doc.doc} documents changes which have occurred
  284. % since the last published version \cite{art:doc} but which have been
  285. % present in distributed versions of {\tt doc.sty} for some time.  It
  286. % also integrates the (undocumented) features of the distributed {\tt
  287. % newdoc.sty}. 
  288. %
  289. % The following changes and additions have been made to the user
  290. % interface since the published version~\cite{art:doc}.  See
  291. % \S\ref{sec:interface} for more details. 
  292. % \begin{description}
  293. % \item[Driver mechanism] "\DocInput" is now used in the driver file
  294. % to input possibly multiple independent {\tt doc} files and {\tt doc}
  295. % no longer has to be the last style option.  "\IndexListing" is
  296. % replaced by "\IndexInput";
  297. % \item[Indexing] is controlled by "\PageIndex" and
  298. % "\CodelineIndex", one of which must be specified to produce an
  299. % index---there is no longer a "\makeindex" in the default
  300. % "\DocstyleParms";
  301. % \item[The {\tt macro} environment] now takes as argument the macro
  302. % name {\em with\/} the backslash;
  303. % \item[Verbatim text] Newlines are now forbidden inside "\verb" and
  304. % commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for
  305. % verbatim shorthand;
  306. % \item[{\tt \bslash par}] can now be used in "\DoNotIndex";
  307. % \item[Checksum/character table support] for ensuring the
  308. % integrity of distributions is added;
  309. % \item[{\tt \bslash printindex}] becomes "\PrintIndex";
  310. % \item[{\tt multicol.sty}] is no longer necessary to use {\tt doc} or
  311. % print the documentation (although it is recommended);
  312. % \item[`Docstrip' modules] are recognised and formatted specially.
  313. % \end{description}
  314. %
  315. % As well as adding some completely new stuff,
  316. % the opportunity has been taken to add some commentary to the code
  317. % formerly in {\tt newdoc.sty} and that added after version 1.5k of
  318. % {\tt doc.sty}.  Since (as noted in the sections concerned) this
  319. % commentary wasn't written by Frank Mittelbach but the code was, it is
  320. % probably {\em not\/} true in this case that ``if the code and
  321. % comments disagree both are probably wrong''!
  322. %
  323. % \subsection*{Bugs}
  324. %
  325. % There are some known bugs in this version:
  326. % \begin{itemize}
  327. % \item The `General changes' glossary entry would come out after
  328. %    macro names with a leading "!" and possibly a leading \verb+"+;
  329. % \item If you have an old version of {\sf makeindex} long "\changes"
  330. %    entries will come out strangely and you may find the section
  331. %    header amalgamated with the first changes entry.  Try to get an
  332. %    up-to-date one (see p.~\pageref{makeindex:version});
  333. % \item Because the accompanying {\sf makeindex} style files support
  334. %    the inconsistent attribute specifications of older and newer
  335. %    versions {\sf makeindex} always complains about three `unknown
  336. %    specifier's when sorting the index and changes entries.
  337. % \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with
  338. %    single character arguments, e.g., "{|}" instead of "{\|}" chaos
  339. %    may happen.
  340. % \end{itemize}
  341. % (Some `features' are documented below.)
  342. %
  343. % \subsection*{Wish list}
  344. %
  345. % \begin{itemize}
  346. % \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write
  347. % out to a special file information about the style's `exported'
  348. % definitions which they describe.  This could subsequently be
  349. % included in the {\tt docstrip}ped {\tt .sty} file in a suitable form
  350. % for use by smart editors in command completion, spelling checking
  351. % etc., based on the style options of a document.  This would need
  352. % agreement on a `suitable form'.
  353. % \item Indexing of the modules used in {\tt docstrip}'s "%<"
  354. % directives.  I'm not sure how to index directives containing
  355. % module combinations;
  356. % \item Writing out bibliographic information about the style;
  357. % \item Allow turning off use of the special font for, say, the next
  358. % guarded block.
  359. % \end{itemize}
  360. %
  361. % \ifmulticols
  362. % \end{multicols}
  363. % 
  364. % \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt}
  365. %                      \section{Introduction}]
  366. % \else
  367. % \section{Introduction}
  368. % \fi
  369. %
  370. % The \TeX{} macros which are described here allow definitions and
  371. % documentation to be held in one and the same file.  This has the
  372. % advantage that normally very complicated instructions are made
  373. % simpler to understand by comments inside the definition. In addition
  374. % to this, updates are easier and only one source file needs to be
  375. % changed.  On the other hand, because of this, the style files are
  376. % considerably longer: thus \TeX{} takes longer to load them.  If this
  377. % is a problem, there is an easy remedy: one needs only to run the
  378. % {\tt docstrip.tex} program that removes nearly all lines that begin
  379. % with a
  380. % percent sign.
  381. %
  382. % The idea of integrated documentation was born with the development
  383. % of the \TeX{} program; it was crystallized in Pascal with the \Web{}
  384. % system.  The advantages of this method are plain to see (it's easy
  385. % to make comparisons \cite{art:Knuthliterat}).  Since this
  386. % development, systems similar to \Web{} have been developed for other
  387. % programming languages. But for one of the most complicated
  388. % programming languages (\TeX) the documentation has however been
  389. % neglected.  The \TeX{} world seems to be divided between:---
  390. % \begin{itemize} \item a couple of ``wizards'', who produce many
  391. % lines of completely unreadable code ``off the cuff'', and \item many
  392. % users who are amazed that it works just how they want it to do.  Or
  393. % rather, who despair that certain macros refuse to do what is
  394. % expected of them.\end{itemize}
  395. %
  396. % I do not think that the \Web{} system is {\em the\/} reference work;
  397. % on the contrary, it is a prototype which suffices for the
  398. % development of programs within the \TeX{} world.  It is sufficient,
  399. % but not totally sufficient.\footnote{I know that this will be seen
  400. % differently by a few people, but this product should not be seen as
  401. % the finished product, at least as far as applications concerning
  402. % \TeX{} are concerned.  The long-standing debate over `multiple
  403. % change files' shows this well.} As a result of \Web, new programming
  404. % perspectives have been demonstrated; unfortunately, though, they
  405. % haven't been developed further for other programming languages.
  406. %
  407. % The method of documentation of \TeX{} macros which I have introduced
  408. % here should also only be taken as a first sketch.  It is designed
  409. % explicitly to run under \LaTeX{} alone.  Not because I was of the
  410. % opinion that this was the best starting point, but because from this
  411. % starting point it was the quickest to develop.\footnote{This
  412. % argument is a bad one, however, it is all too often trotted out.} As
  413. % a result of this design decision, I had to move away from the
  414. % concept of modularization; this was certainly a step backward.
  415. %
  416. % I would be happy if this article could spark off discussion over
  417. % \TeX\ documentation.  I can only advise anyone who thinks that they
  418. % can cope without documentation to ``Stop Time'' until he or she
  419. % completely understands the \AmSTeX{} source code.
  420. %
  421. %
  422. %
  423. %
  424. %
  425. % \subsection{Using the {\sf doc} style option}
  426. %
  427. % Just like any other option, invoke it by including it amongst the
  428. % style options in the optional parameter list for the
  429. % \verb+\documentstyle+ command.  {\sf Doc}'s use of
  430. % \verb+\reversemarginpars+ may make it incompatible with some style
  431. % options.
  432. % \changes{v1.7a}{92/02/25}{Altered usage info}
  433. %
  434. % \ifmulticols\end{multicols}\fi
  435. %
  436. %
  437. % \section{The User Interface}\label{sec:interface}
  438. % \subsection{The driver file}
  439. %
  440. % If one is going to document a set of macros with the {\tt doc}
  441. % option one has to prepare a special driver file which produces the
  442. % formatted document. This driver file has the following
  443. % characteristics:
  444. % 
  445. % \noindent \verb+\documentstyle[+\meta{options}]^^A
  446. %           \verb+{+\meta{document-style}\verb+}+\\[3pt]
  447. % \hspace*{10pt}\meta{preamble}\\[3pt]
  448. % \verb+\begin{document}+\\[3pt]
  449. % \hspace*{10pt}\meta{special input commands}\\[3pt]
  450. % \verb+\end{document}+
  451. %
  452. % The list of \meta{options} must contain the {\tt doc} option but it
  453. % is not necessary any longer to put this option on the end of the
  454. % list.
  455. %
  456. % The \meta{document-style} might be any document style, I normally
  457. % use {\tt article}.
  458. % 
  459. % In the \meta{preamble} one should place declarations which
  460. % manipulate the behavior of the {\tt doc} option like
  461. % \verb+\DisableCrossrefs+ or \verb+\OnlyDescription+.
  462. %
  463. % \DescribeMacro\DocInput \DescribeMacro\IndexInput
  464. % Finally the \meta{special input commands} part should contain one or
  465. % more \verb+\DocInput+\meta{file name} and/or
  466. % \verb+\IndexInput+\meta{file name} commands.  The
  467. % \verb+\DocInput+ command is used for files prepared for the {\tt
  468. % doc} option whereas \verb+\IndexInput+ can be used for all kinds of
  469. % macro files.  See page \pageref{..Input} for more details of
  470. % "\IndexInput".  Multiple "\DocInput"s can be used with a
  471. % number of included files which are each self-contained
  472. % self-documenting styles---for instance, each containing
  473. % "\maketitle". 
  474. %
  475. % As an example, the driver file for the {\tt doc} option itself is
  476. % derived from the following text.  This is meant to be extracted by
  477. % the {\tt docstrip} program which will remove the leading "<+driver>"
  478. % indicating the `module'; the line numbers are added by {\tt
  479. % doc}'s formatting.
  480. % \changes{v1.7a}{92/03/06}{Added docstrip-derivable driver file as
  481. %                           example.}
  482. % \changes{v1.7c}{92/04/01}{Expurgated ltugboat.sty from driver.}
  483. %    \begin{macrocode}
  484. %<+driver>\documentstyle[doc]{article}
  485. %<+driver>% dimensions from ltugboat.sty:
  486. %<+driver>\setlength\textwidth{31pc} \setlength\textheight{54pc}
  487. %<+driver>\setlength{\parindent}{0pt} 
  488. %<+driver>\setlength{\parskip}{2pt plus 1pt minus 1pt}
  489. %<+driver>\setlength{\oddsidemargin}{8pc} 
  490. %<+driver>\setlength{\marginparwidth}{8pc}
  491. %<+driver>\setlength{\topmargin}{-2.5pc} 
  492. %<+driver>\setlength{\headsep}{20pt}
  493. %<+driver>\setlength{\columnsep}{1.5pc} 
  494. %<+driver>\setlength{\columnwidth}{18.75pc}
  495. %<+driver>\EnableCrossrefs         
  496. %<+driver>%\DisableCrossrefs % Say \DisableCrossrefs if index is ready
  497. %<+driver>\RecordChanges                  % Gather update information
  498. %<+driver>\CodelineIndex                  % Index code by line number
  499. %<+driver>%\OnlyDescription  % comment out for implementation details
  500. %<+driver>%\OldMakeindex     % use if your MakeIndex is pre-v2.9
  501. %<+driver>\begin{document}
  502. %<+driver>   \DocInput{doc.doc}
  503. %<+driver>\end{document}
  504. %    \end{macrocode}
  505. %^^A As an example this is the driver file for the {\tt doc} option
  506. %^^A itself: 
  507. %^^A\begin{verbatim}
  508. %^^A\documentstyle[ltugboat,doc]{article}
  509. %^^A
  510. %^^A %  \DisableCrossrefs     % Say \DisableCrossrefs if the index
  511. %^^A                          % is ready.
  512. %^^A
  513. %^^A    \RecordChanges        % Gather update-information
  514. %^^A
  515. %^^A %  \OnlyDescription      % Remove the comment char if you only want
  516. %^^A                          % the description
  517. %^^A
  518. %^^A\SelfDocumenting          % Tugbot style macro (for doc)
  519. %^^A
  520. %^^A\begin{document}
  521. %^^A
  522. %^^A   \DocInput{doc.doc}
  523. %^^A
  524. %^^A\end{document}
  525. %^^A\end{verbatim}
  526. %
  527. % \changes{v1.7a}{92/02/25}{Note on avoiding driver file}
  528. % \subsection{Avoiding using a driver file}
  529. %
  530. % It is possible to dispense with a driver file at the expense of some
  531. % flexibility using the following trick.\footnote{Due to David
  532. % Carlisle, Manchester University.}  Before the documentation part of
  533. % the file starts, include (without leading "%"s!)\ something like
  534. % \begin{verbatim}
  535. %\ifcat a\noexpand @\let\next\relax\else\def\next{%
  536. %    \documentstyle[doc]{article}\MakePercentIgnore}\fi\next
  537. %\end{verbatim}
  538. % with any necessary extra style options included, of course.  Then
  539. % the file can either be used directly as a style file as normal or
  540. % have the documentation printed simply by using
  541. % "latex"~\meta{filename}.  You can also arrange to have this process
  542. % ask questions about whether to format only the usage section, for
  543. % instance. 
  544. %
  545. % \subsection{General conventions}
  546. %
  547. % A \TeX{} file prepared to be used with the `doc' style option
  548. % consists of `documentation parts' intermixed with `definition
  549. % parts'.
  550. %
  551. % Every line of a `documentation part' starts with a percent sign
  552. % (\verb+%+) in column one.  It may contain arbitrary \TeX{} or
  553. % \LaTeX{} commands except that the character `\verb+%+' cannot be
  554. % used as a comment character.
  555. % \SortIndex{\string^\string^A}{\string\verb\verbatimchar
  556. % \string^\string^A\verbatimchar \encapchar usage} To allow user
  557. % comments, the \verb+^^A+ character is defined as a comment character
  558. % later on.  Such `metacomments' may be also be included simply by
  559. % surrounding them with "\iffalse" \ldots~"\fi".
  560. %
  561. % All other parts of the file are called `definition parts'.  They
  562. % contain fractions of the macros described in the `documentation
  563. % parts'.
  564. %
  565. % If the file is used to define new macros (e.g.\ as a style file in
  566. % the \verb+\documentstyle+ macro), the `documentation parts' are
  567. % bypassed at high speed and the macro definitions are pasted
  568. % together, even if they are split into several `definition parts'.
  569. %
  570. % \DescribeEnv{macrocode}
  571. % On the other hand, if the documentation of these macros is to be
  572. % produced, the `definition parts' should be typeset verbatim. To
  573. % achieve this, these parts are surrounded by the {\sf macrocode}
  574. % environment.
  575. % More exactly: before a `definition part' there should be a line
  576. % containing\\
  577. % \hspace*{\MacroIndent}\verb*+%    \begin{macrocode}+\\
  578. % and after this part a line\\
  579. % \hspace*{\MacroIndent}\verb*+%    \end{macrocode}+\\
  580. % There must be {\em exactly\/} four spaces between the \verb+%+
  581. % and \verb+\end{macrocode}+ --- \TeX{} is looking for this string
  582. % and not for the macro while processing a `definition part'.
  583. %
  584. % Inside a `definition part' all \TeX{} commands are allowed; even the
  585. % percent sign could be used to suppress unwanted spaces etc.
  586. %
  587. % \DescribeEnv{macrocode*}
  588. % Instead of the {\sf macrocode} environment one can also use the {\sf
  589. % macrocode$*$} environment which produces the same results except
  590. % that spaces are printed as \nopagebreak\verb*+ + characters.
  591. %
  592. %
  593. %
  594. % \subsection{Describing the usage of new macros}
  595. %
  596. % \DescribeMacro\DescribeMacro
  597. % When you describe a new macro you may use \verb+\DescribeMacro+ to
  598. % indicate that at this point the usage of a specific macro is
  599. % explained. It takes one argument which will be printed in the margin
  600. % and also produces a special index entry.  For example, I used
  601. % \verb+\DescribeMacro{\DescribeMacro}+ to make clear that this is the
  602. % point where the usage of \verb+\DescribeMacro+ is explained.
  603. %
  604. % \DescribeMacro\DescribeEnv
  605. % An analogous macro \verb+\DescribeEnv+ should be used to indicate
  606. % that a \LaTeX{} environment is explained. It will produce a somewhat
  607. % different index entry. Below I used \verb+\DescribeEnv{verbatim}+.
  608. %
  609. % \DescribeEnv{verbatim}
  610. % It is often a good idea to include examples of the usage of new macros
  611. % in the text. Because of the \verb+%+ sign in the first column of every
  612. % row, the {\sf verbatim} environment is slightly altered to suppress
  613. % those
  614. % characters.\footnote{These macros were written by Rainer
  615. %                      Sch\"opf~\cite{art:verbatim}. He also
  616. %                      provided a new {\sf verbatim} environment which
  617. %                      can be used inside of other macros.}
  618. % \DescribeEnv{verbatim*}
  619. % The {\sf verbatim$*$} environment is changed in the same way.
  620. % \changes{v1.7a}{92/02/26}{Documented `verb change.}
  621. % \DescribeMacro\verb
  622. % The "\verb" command is re-implemented to give an error report if a
  623. % newline appears in its argument. 
  624. % The {\sf verbatim} and {\sf verbatim$*$} environments set text in
  625. % the style defined by "\MacroFont"~(\S\ref{sec:macrofont}).
  626. %
  627. %
  628. %
  629. % \subsection{Describing the definition of new macros}
  630. %
  631. % \DescribeEnv{macro}
  632. % To describe the definition of a new macro we use the {\sf macro}
  633. % environment. It has one argument: the name of the new
  634. % macro.\footnote{This is a change to the style design I described in
  635. %                ^^A \TUB ^^A removed in case ltugboat.sty not used
  636. %                {\sl TUGboat\/}\ 10\#1 (Jan.~89). We finally decided
  637. %                that it would 
  638. %                be better to use the macro name {\em with\/} the
  639. %                backslash as an argument.}
  640. % This argument is also used to print the name in the margin and to
  641. % produce an index entry.
  642. % Actually the index entries for usage and definition are different to
  643. % allow an easy reference.
  644. % This environment might be nested. In this case the
  645. % labels in the margin are placed under each other.
  646. % \changes{v1.7a}{92/02/26}{Note on need for some text in macro env.}
  647. % There should be some text---even  if it's just an empty
  648. % "\mbox{}"---in this environment before "\begin{macrocode}" or the
  649. % marginal label won't print in the right place. 
  650. %
  651. % \DescribeMacro\MacrocodeTopsep
  652. % \DescribeMacro\MacroTopsep
  653. % There also exist four style parameters: \verb+\MacrocodeTopsep+ and
  654. % \verb+\MacroTopsep+ are used to control the vertical spacing above
  655. % and below the {\sf macrocode} and the {\sf macro}
  656. % \DescribeMacro\MacroIndent
  657. % environment, \verb+\MacroIndent+ is used to indent the lines of code
  658. % and
  659. % \DescribeMacro\MacroFont \label{sec:macrofont}
  660. % \verb+\MacroFont+ holds the font and a possible size change command
  661. % for the code lines, the "verbatim"["*"] environment and the macro
  662. % names printed in the margin.  If you want
  663. % to change their default values in a 
  664. % style file (like {\tt ltugboat.sty}) use the \verb+\DocstyleParms+
  665. % command described below.
  666. %
  667. %
  668. %
  669. %
  670. % \subsection{Formatting the margins}
  671. %
  672. % \DescribeMacro\PrintDescribeMacro
  673. % \DescribeMacro\PrintDescribeEnv
  674. % \DescribeMacro\PrintMacroName
  675. % As mentioned earlier, some macros and the {\sf macro} environment
  676. % print their arguments in the margin. This is actually done by three
  677. % macros which are user
  678. % definable.\footnote{You may place the changed definitions in a
  679. %                     separate style
  680. %                     file or at the beginning of the documentation
  681. %                     file.
  682. %                     For example, if you don't like any names in the
  683. %                     margin
  684. %                     but want a fine index you can simply
  685. %                     {\tt \bslash let}
  686. %                     these macros equal {\tt \bslash @gobble}.
  687. %                     The doc style option won't redefine any existing
  688. %                     definitions of these macros.}
  689. % They are named \verb+\PrintDescribeMacro+, \verb+\PrintDescribeEnv+
  690. % and \verb+\PrintMacroName+ (called by the {\sf macro} environment).
  691. %
  692. %
  693. % \subsection{Using a special escape character}
  694. %
  695. % \DescribeMacro\SpecialEscapechar
  696. % If one defines complicated macros it is sometimes necessary to
  697. % introduce a new escape character because the `\verb+\+' has got a
  698. % special \verb+\catcode+. In this case one can use
  699. % \verb+\SpecialEscapechar+ to indicate which character is actually
  700. % used to play the r\^ole of the `\verb+\+'. A scheme like this is
  701. % needed because the {\sf macrocode} environment and its counterpart
  702. % {\sf macrocode$*$} produce an index entry for every occurrence of a
  703. % macro name. They would be very confused if you didn't tell them that
  704. % you'd changed \verb+\catcode+$\,$s.  The argument to
  705. % \verb+\SpecialEscapechar+ is a single-letter control sequence, that
  706. % is, one has to use \verb+\|+ for example to denote that `\verb+|+'
  707. % is used as an escape character. \verb+\SpecialEscapechar+ only
  708. % changes the behavior of the next {\sf macrocode} or {\sf
  709. % macrocode$*$} environment.
  710. %
  711. %  The actual index entries created will all be printed with \verb+\+
  712. % rather than \verb+|+, but this probably reflects their usage, if not
  713. % their definition, and anyway must be preferable to not having any
  714. % entry at all.  The entries {\em could\/} be formatted appropriately,
  715. % but the effort is hardly worth it, and the resulting index might be
  716. % more confusing (it would certainly be longer!).
  717. %
  718. %
  719. % \subsection{Cross-referencing all macros used}
  720. %
  721. % \DescribeMacro\DisableCrossrefs
  722. % \DescribeMacro\EnableCrossrefs
  723. % As already mentioned, every new macro name used within a {\sf
  724. % macrocode} or {\sf macrocode$*$} environment will produce an index
  725. % entry. In this way one can easily find out where a specific macro is
  726. % used.  Since \TeX{} is considerably slower when it has to produce
  727. % such a bulk of index entries one can turn off this feature by using
  728. % \verb+\DisableCrossrefs+ in the driver file. To turn it on again
  729. % just use
  730. % \verb+\EnableCrossrefs+.\footnote{Actually,
  731. %          {\tt\bslash EnableCrossrefs}
  732. %          changes things more drastically; any following
  733. %          {\tt\bslash DisableCrossrefs}
  734. %          which might be present in the source will be ignored.}
  735. %
  736. %
  737. % \DescribeMacro\DoNotIndex
  738. % But also finer control is provided. The \verb+\DoNotIndex+ macro
  739. % takes a list of macro names separated by commas. Those names won't
  740. % show up in the index. You might use several \verb+\DoNotIndex+
  741. % commands: their lists will be concatenated.  In this article I used
  742. % \verb+\DoNotIndex+ for
  743. % all macros which are already defined in \LaTeX.
  744. %
  745. % All three above declarations are local to the current group.
  746. %
  747. % Production (or not) of the index (via the "\makeindex" commend) is
  748. % controlled by using or omitting the following declarations in the
  749. % driver file preamble; if neither is used, no index is produced.
  750. % \DescribeMacro\PageIndex Using "\PageIndex" makes all index
  751. % entries refer to their page number; with
  752. % \DescribeMacro\CodelineIndex "\CodelineIndex", index entries
  753. % produced by "\DescribeMacro" and "\DescribeEnv" refer to page number
  754. % but those produced by the {\sf macro} environment refer to the
  755. % code lines, which will be numbered automatically.\footnote{The line
  756. % number is actually that of the first line of the first {\sf
  757. % macrocode} environment in the {\sf macro} environment.}
  758. % \DescribeMacro\theCodelineNo
  759. % The style of this numbering can be controlled by defining the macro
  760. % "\theCodelineNo".  Its default definition is to use scriptsize
  761. % arabic numerals; a user-supplied definition won't be overwritten.
  762. %
  763. %
  764. % \subsection{Producing the actual index entries}
  765. %
  766. % Several of the aforementioned macros will produce some sort of index
  767. % entries. These entries have to be sorted by an external
  768. % program---the current implementation assumes that the {\sf
  769. % makeindex} program by Chen~\cite{art:Chen} is used.
  770. %
  771. % But this isn't built in: one has only to redefine some of the
  772. % following macros to be able to use any other index program.  All
  773. % macros which are installation 
  774. % dependent are defined in such a way that they won't overwrite a
  775. % previous definition. Therefore it is safe to put the changed
  776. % versions in a style file which might be read in before the doc style
  777. % option.
  778. %
  779. %  To allow the user to change the specific characters recognized by
  780. %  his or her index program all characters which have special meaning
  781. %  in the {\sf makeindex} program are given symbolic
  782. %  names.\footnote{I don't know if there exists a program which needs
  783. %                  more command characters, but I hope not.}
  784. % However, all characters used should be of \verb+\catcode+ other than
  785. % `letter' (11).
  786. %
  787. % \DescribeMacro{\actualchar}
  788. % The \verb+\actualchar+ is used to separate the `key' and the actual
  789. % index entry.
  790. % \DescribeMacro{\quotechar}
  791. % The \verb+\quotechar+ is used before a special index program
  792. % character to suppress its special meaning.
  793. % \DescribeMacro{\encapchar}
  794. %  The \verb+\encapchar+ separates the indexing information from a
  795. % letter string which {\sf makeindex} uses as a \TeX{} command to
  796. % format the page number associated with a special entry.  It is used
  797. % in this style to apply the \verb+\main+ and the \verb+\usage+
  798. % commands.
  799. % \DescribeMacro{\levelchar}
  800. %  Additionally \verb+\levelchar+ is used to separate `item',
  801. % `subitem' and `subsubitem' entries.
  802. %
  803. % It is a good idea to stick to these symbolic names even if you know
  804. % which index program is used. In this way your files will be
  805. % portable.
  806. %
  807. % \DescribeMacro\SpecialMainIndex
  808. % To produce a main index entry for a macro the
  809. % \verb+\SpecialMainIndex+ macro\footnote{This macro is called by the
  810. % {\sf macro} environment.} may be used.  It is called `special'
  811. % because it has to print its argument verbatim.
  812. % \DescribeMacro\SpecialIndex
  813. % If you want a normal index entry for a macro name
  814. % \verb+\SpecialIndex+ might be used.\footnote{This macro is called
  815. % within the {\sf macrocode} environment when encountering a macro
  816. % name.}
  817. % \DescribeMacro\SpecialUsageIndex
  818. % \DescribeMacro\SpecialEnvIndex
  819. % To index the usage of a macro or an environment
  820. % \verb+\SpecialUsageIndex+ and \verb+\SpecialEnvIndex+ may be used.
  821. % \DescribeMacro\SortIndex
  822. % Additionally a \verb+\SortIndex+ command is provided.  It takes two
  823. % arguments---the sort key and the actual index entry.
  824. %
  825. % All these macros are normally used by other macros; you will need
  826. % them only in an emergency.
  827. %
  828. % \DescribeMacro\verbatimchar
  829. % But there is one characteristic worth mentioning: all macro names in
  830. % the index are typeset with the \verb+\verb*+ command. Therefore one
  831. % special character is needed to act as a delimiter for this command.
  832. % To allow a change in this respect, again this character is
  833. % referenced indirectly, by the macro \verb+\verbatimchar+. It expands
  834. % by default to \verb?+?  but if your code lines contain macros with
  835. % `{\tt +}' characters in their names (e.g.\ when you use \verb?\+?)
  836. % you will end up with an index entry containing \verb?\verb+\++?
  837. % which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this
  838. % case you should redefine \verb+\verbatimchar+ globally or locally to
  839. % overcome this problem.
  840. %
  841. % \DescribeMacro\*
  842. % We also provide a \verb+\*+ macro.  This is intended to be used for
  843. % index entries like
  844. % \begin{quote}
  845. %    index entries \\
  846. %    \hspace*{30pt} Special macros for \*
  847. % \end{quote}
  848. % Such an entry might be produced with the line:
  849. %\begin{verbatim}
  850. %   \index{index entries\levelchar Special macros for \*}
  851. %\end{verbatim}
  852. %
  853. % \DescribeMacro\OldMakeindex
  854. % Versions of {\sf makeindex} prior to 2.9 had some bugs affecting
  855. % {\sf doc}.  One of these, 
  856. % pertaining to the "%" character doesn't have a work-around
  857. % appropriate for versions with and without the
  858. % bug.\label{makeindex:version}  If
  859. % you have an old version, invoke "\OldMakeindex" in a
  860. % style file or the driver file to prevent problems with index entries
  861. % such as "\%", although you'll probably normally want to turn off
  862. % indexing of "\%" anyway.  Try to get an up-to-date {\sf makeindex}
  863. % from one of the \TeX{} repositories.
  864. %
  865. %
  866. % \subsection{Setting the index entries}
  867. %
  868. % \changes{v1.7a}{92/03/11}{Usage note on gind.ist.}
  869. % After the first formatting pass through the {\tt .doc} file you need
  870. % to sort the index entries written to the {\tt .idx} file using {\sf
  871. % makeindex} or your favourite alternative.  You need a suitable style
  872. % file for {\sf makeindex} (specified by the {\tt -s} switch).  A
  873. % suitable one is supplied with {\sf doc}, called {\tt gind.ist}.
  874. %
  875. % \DescribeMacro\PrintIndex
  876. % To read in and print the sorted index, just put the
  877. % \verb+\PrintIndex+ command as the last (commented-out, and thus
  878. % executed during the documentation pass through the file) command
  879. % in your style file.  Precede it by any bibliography commands
  880. % necessary for your citations.
  881. % Alternatively, it may be more convenient to put all such calls
  882. % amongst the arguments of the \verb+\StopEventually+ macro, in
  883. % which case a \verb+\Finale+ command should appear at the end of
  884. % your file.
  885. %
  886. % \DescribeEnv{theindex}
  887. % Contrary to standard \LaTeX, the index is typeset in three columns
  888. % by default. This is controlled by the \LaTeX{} counter `{\sf
  889. % IndexColumns}' and can therefore be changed with a
  890. % \verb+\setcounter+ declaration.  Additionally one doesn't want to
  891. % start a new page unnecessarily.  Therefore the {\sf theindex}
  892. % environment is redefined.
  893. % \DescribeMacro\IndexMin
  894. % When the {\sf theindex} environment starts it will measure how much
  895. % space is left on the current page. If this is more than
  896. % \verb+\IndexMin+ then the index will start on this page. Otherwise
  897. % \verb+\newpage+ is called.
  898. %
  899. % Then a short introduction about the meaning of several index entries
  900. % is typeset (still in onecolumn mode). Afterwards the actual index
  901. % entries follow in multi-column mode.
  902. % \DescribeMacro\IndexPrologue
  903. % You can change this prologue with the help of the
  904. % \verb+\IndexPrologue+ macro. Actually the section heading is also
  905. % produced in this way, so you'd better write something like:
  906. % \begin{verbatim}
  907. %   \IndexPrologue{\section*{Index} The index entries underlined ...} 
  908. %\end{verbatim}
  909. % When the {\sf theindex} environment is finished the last page will
  910. % be reformatted to produce balanced columns. This improves the layout
  911. % and allows the next article to start on the same page.
  912. % \DescribeMacro\IndexParms
  913. % Formatting of the index columns (values for \verb+\columnssep+
  914. % etc.)\ is controlled by the \verb+\IndexParms+ macro. It assigns the
  915. % following values:
  916. % \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A
  917. % \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A
  918. % \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip}
  919. % \begin{center}
  920. %  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
  921. %  \verb+\parindent+    & \IndexParms \the\parindent    &
  922. %  \verb+\columnsep+    & \IndexParms \the\columnsep    \\
  923. %  \verb+\parskip+      & \IndexParms \the\parskip           &
  924. %  \verb+\rightskip+    & \IndexParms 
  925. %                         \expandafter\dimenvalue\the\rightskip  \\
  926. %  \verb+\mathsurround+ & \IndexParms \the\mathsurround  &
  927. %  \verb+\parfillskip+  & \IndexParms 
  928. %                         \expandafter\dimenvalue\the\parfillskip      
  929. %  \end{tabular}
  930. % \end{center}
  931. % \DescribeMacro{\@idxitem}
  932. % Additionally it defines \verb+\@idxitem+ (which will be used when an
  933. % \verb+\item+ command is encountered) and selects \verb+\small+ size.
  934. % If you want to change any of these values you have to define them
  935. % all.
  936. %
  937. % \DescribeMacro\main
  938. % \DescribeMacro\usage
  939. % The page numbers for main index entries are encapsulated by the
  940. % \verb+\main+ macro (underlining its argument) and the numbers
  941. % denoting the description are encapsulated by the \verb+\usage+ macro
  942. % (which produces {\em italics}). As usual these commands are user
  943. % definable.
  944. %
  945. %
  946. % \subsection{Changing the default values of style parameters}
  947. %
  948. % \DescribeMacro\DocstyleParms
  949. % If you want to overwrite some default settings made by the {\tt doc}
  950. % style, you can either put your declarations in the driver file (that
  951. % is after {\tt doc.sty} is read in) or use a separate style file for
  952. % doing this work. In the latter case you can define the macro
  953. % \verb+\DocstyleParms+ to contain all assignments.  This
  954. % indirect approach is necessary if your style file might be read
  955. % before the {\tt doc.sty}, when some of the registers are not
  956. % allocated.  Its default definition is null.
  957. %
  958. % The doc style option currently assigns values to the following
  959. % registers:
  960. % \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A
  961. % \SpecialUsageIndex{\MacroTopsep}^^A
  962. % \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A
  963. % \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance}
  964. % \begin{center}
  965. %  \begin{tabular}{l@{\,=\,}ll@{\,=\,}l}
  966. %  \verb+\IndexMin+      & \the\IndexMin    &
  967. %  \verb+\MacroTopsep+   & \the\MacroTopsep    \\
  968. %  \verb+\marginparwidth+& \the\marginparwidth  &
  969. %  \verb+\MacroIndent+   & \the\MacroIndent \\
  970. %  \verb+\marginparpush+ & \the\marginparpush    &
  971. %  \verb+\MacrocodeTopsep+   & \the\MacrocodeTopsep \\
  972. %  \verb+\tolerance+     & \the\tolerance  
  973. %  \end{tabular}
  974. % \end{center}
  975. %
  976. %
  977. % \subsection{Additional bells and whistles}
  978. %
  979. % We provide macros for logos such as \Web, \AmSTeX, \BibTeX,
  980. % \SliTeX{} and \PlainTeX. Just type \verb+\Web+, \verb+\AmSTeX+,
  981. % \verb+\BibTeX+, \verb+\SliTeX+ or \verb+\PlainTeX+, respectively.
  982. % \LaTeX{} and \TeX{} are already defined in {\tt latex.tex}.
  983. %
  984. % \DescribeMacro\meta
  985. % Another useful macro is \verb+\meta+ which has one argument and
  986. % produces something like \meta{dimen parameter}.
  987. %
  988. % \DescribeMacro\OnlyDescription
  989. % \DescribeMacro\StopEventually
  990. % You can use the \verb+\OnlyDescription+ declaration in the driver
  991. % file to suppress the last part of your document (which presumably
  992. % exhibits the code). To make this work
  993. % you have to place the command \verb+\StopEventually+ at a suitable
  994. % point in your file.  This macro has one argument in which you put
  995. % all information you want to see printed if your document ends at
  996. % this point (for example a bibliography which is normally printed at
  997. % the very end). When the \verb+\OnlyDescription+ declaration is
  998. % missing the \verb+\StopEventually+
  999. % \DescribeMacro\Finale
  1000. % macro saves its argument in a macro called \verb+\Finale+ which can
  1001. % afterwards be used to get things back (usually at the very end).
  1002. % Such a scheme makes changes in two places unnecessary.
  1003. %
  1004. % Thus you can use this feature to produce a local guide for the
  1005. % \TeX{} users which describes only the usage of macros (most of them
  1006. % won't be interested in your definitions anyway).  For the same
  1007. % reason the \verb+\maketitle+
  1008. % \DescribeMacro\maketitle 
  1009. % command is slightly changed to allow multiple titles in one
  1010. % document.  So you can make one driver file reading in several
  1011. % articles at once.
  1012. % \DescribeMacro{\ps@titlepage}
  1013. % To avoid an unwanted {\sf pagestyle} on the title page the
  1014. % \verb+\maketitle+ command issues a \verb+\thispagestyle{titlepage}+
  1015. % declaration which produces a {\sf plain} page if the {\sf titlepage}
  1016. % page style is undefined.  This allows style files like {\sf
  1017. % ltugboat.sty} to define their own page styles for title pages.
  1018. %
  1019. % \DescribeMacro\IndexInput \label{..Input}
  1020. % Last but not least I defined an \verb+\IndexInput+ macro which
  1021. % takes a file name as an argument and produces a verbatim listing of
  1022. % the file, indexing every command as it goes along.  This might be
  1023. % handy, if you want to learn something about macros without enough
  1024. % documentation.  I used this feature to cross-reference {\tt
  1025. % latex.tex} getting a verbatim copy with about 15 pages
  1026. % index.\footnote{It took quit a long time and the resulting {\tt .idx}
  1027. %                file was longer than the {\tt .dvi} file.
  1028. %                Actually too long to be handled by the {\sf makeindex}
  1029. %                program directly (on our MicroVAX) but the final result
  1030. %                was worth the trouble.}
  1031. %
  1032. % \DescribeMacro\changes
  1033. % To maintain a change history within the file, the \verb+\changes+
  1034. % command may be placed amongst the description part of the changed
  1035. % code.  It takes three arguments, thus:
  1036. % \begin{quote}
  1037. % \verb+\changes{+\meta{version}\verb+}{+\meta{date}\verb+}{+^^A
  1038. % \meta{text}\verb+}+
  1039. % \end{quote}
  1040. % The changes may be used to produce an auxiliary file (\LaTeX's
  1041. % \verb+\glossary+ mechanism is used for this) which may be printed
  1042. % after suitable formatting. The \verb+\changes+ macro encloses the
  1043. % \meta{date} in parentheses and appends the \meta{text} to form the
  1044. % printed entry in such a change history; because old
  1045. % versions\footnote{Before 2.6.} of the {\sf makeindex} 
  1046. % program limit such fields to 64 characters, care should be taken
  1047. % not to exceed this limit when describing the change.  When
  1048. % referring to macros in change descriptions it is conventional to use
  1049. % "`"\meta{macroname} rather than attempting to format it properly and
  1050. % using up valuable characters in the entry with old {\sf makeindex}
  1051. % versions.
  1052. %
  1053. % \changes{v1.7a}{92/02/26}{Description of `RecordChanges etc. added
  1054. %                           to interface section.}
  1055. % \DescribeMacro\RecordChanges
  1056. % To cause the change information to be written out, include
  1057. % "\RecordChanges" in the driver file.
  1058. % \DescribeMacro\PrintChanges
  1059. % To read in and print the sorted change history (in two columns),
  1060. % just put the \verb+\PrintChanges+ command as the last
  1061. % (commented-out, and thus executed during the documentation pass
  1062. % through the file) command in your style file.  Alternatively, this
  1063. % command may form one of the arguments of the \verb+\StopEventually+
  1064. % command, although a change history is probably {\em not\/} required
  1065. % if only the description is being printed.
  1066. % The command assumes that {\sf makeindex} or some other program
  1067. % has processed the {\tt.glo} file to generate a sorted {\tt.gls} file.
  1068. % You need a special {\sf makeindex} style file; a suitable one is
  1069. % supplied with {\sf doc}, called {\tt gglo.ist}.
  1070. % \DescribeMacro\GlossaryMin \DescribeMacro\GlossaryPrologue
  1071. % \DescribeMacro\GlossaryParms
  1072. % The "\GlossaryMin", "\GlossaryPrologue" and  "\GlossaryParms" macros
  1073. % are analagous to the "\Index"\ldots\ versions.  (The \LaTeX{}
  1074. % `glossary' mechanism is used for the change entries.)
  1075. %
  1076. % \label{sec:checksum}
  1077. % \DescribeMacro\CharacterTable
  1078. % \DescribeMacro\CheckSum 
  1079. % To overcome some of the problems of sending files over the networks
  1080. % we developed two macros which should detect corrupted files. If one
  1081. % places the lines
  1082. % \begin{verbatim}
  1083. %%% \CharacterTable
  1084. %%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
  1085. %%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
  1086. %%%   Digits        \0\1\2\3\4\5\6\7\8\9
  1087. %%%   Exclamation   \!     Double quote  \"     Hash (number) \#
  1088. %%%   Dollar        \$     Percent       \%     Ampersand     \&
  1089. %%%   Acute accent  \'     Left paren    \(     Right paren   \)
  1090. %%%   Asterisk      \*     Plus          \+     Comma         \,
  1091. %%%   Minus         \-     Point         \.     Solidus       \/
  1092. %%%   Colon         \:     Semicolon     \;     Less than     \<
  1093. %%%   Equals        \=     Greater than  \>     Question mark \?
  1094. %%%   Commercial at \@     Left bracket  \[     Backslash     \\
  1095. %%%   Right bracket \]     Circumflex    \^     Underscore    \_
  1096. %%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
  1097. %%%   Right brace   \}     Tilde         \~}
  1098. %%%
  1099. %\end{verbatim}
  1100. % at the beginning of the file then character translation failures
  1101. % will be detected, provided of course, that the used {\tt doc} option
  1102. % has a correct default table.  The percent signs\footnote{There are
  1103. % two percent signs in each line. This has the effect that these lines
  1104. % are not removed by the {\tt docstrip.tex} program.} at the beginning
  1105. % of the lines should be typed in, since only the {\tt doc} option
  1106. % should look at this command.
  1107. %
  1108. % Another problem of mailing files is possible truncation.  To
  1109. % detect these sort of errors we provide a \verb+\CheckSum+ macro.
  1110. % The check-sum of a file is simply the number of backslashes in the
  1111. % code, i.e.\ all lines between the {\sf macrocode} environments.  But
  1112. % don't be afraid: you don't have count the code-lines yourself; this
  1113. % is done by the {\tt doc} style option for you.  You simply have to
  1114. % use the \verb+\StopEventually+ (which starts looking for backslashes)
  1115. % and the \verb+\Finale+ command.  The latter will inform you either
  1116. % that your file has no check-sum (telling you the right number) or
  1117. % that your number is incorrect (this time telling you both the
  1118. % correct and the incorrect one).  Then you go to the top of your file
  1119. % inserting the line
  1120. % \begin{quote}
  1121. %    \verb+%%   \CheckSum{+\meta{number}\verb+}+
  1122. % \end{quote}
  1123. % and that's all. If you precede it only with one percent then the
  1124. % line will not show up in {\tt docstrip} versions of the file.
  1125. % You should do so whenever you are using conditional code (see
  1126. % {\tt docstrip} documentation) since then the check-sum will not
  1127. % reflect the number of backslashes in the stripped of versions.
  1128. %
  1129. % \DescribeMacro\bslash
  1130. % From time to time, it is necessary to print a \verb+\+ without
  1131. % being able to use the \verb+\verb+ command because the
  1132. % \verb+\catcode+$\,$s of the symbols are already firmly
  1133. % established.  In this instance we can use the command
  1134. % \verb+\bslash+ presupposing, of course, that the actual font in
  1135. % use at this point contains a `backslash' as a symbol.  Note that
  1136. % this definition of \verb+\bslash+ is expandable; it inserts a
  1137. % $"\"_{12}$.  This means that you have to \verb+\protect+
  1138. % it if it is used in `moving arguments'.
  1139. %
  1140. % \DescribeMacro\MakePrivateLetters
  1141. % \changes{v1.7a}{92/02/26}{Documented `MakePrivateLetters in
  1142. %                           interface section}^^A
  1143. % If your macros "\catcode" anything other than "@" to `letter', you
  1144. % should redefine "\MakePrivateLetters" so that it also makes the
  1145. % relevant characters `letters' for the benefit of the indexing.  The
  1146. % default definition is just "\makeatletter".
  1147. %
  1148. % \DescribeMacro\MakeShortVerb \DescribeMacro\DeleteShortVerb
  1149. % It is awkward to have to type, say, "\verb+"\ldots"+" continually
  1150. % when quoting verbatim bits (like macro names) in the text, so an
  1151. % abbreviation mechanism is provided.  Pick a character
  1152. % \meta{c}---one which normally has catcode `other' unless you have
  1153. % very good reason not to---which
  1154. % you don't envisage using in the text, or not using often.  (I like
  1155. % \verb+"+, but you may prefer "|" if you have \verb+"+ active to do
  1156. % umlauts, for instance.)  Then if you say
  1157. % "\MakeShortVerb{\"\meta{c}"}" you can subsequently use
  1158. % \meta{c}\meta{text}\meta{c} as the equivalent of
  1159. % "\verb"\meta{c}\meta{text}\meta{c}.  Use
  1160. % "\DeleteShortVerb{\"\meta{c}"}" if you subsequently
  1161. % want \meta{c} to revert to its previous meaning---you can
  1162. % always turn it on again after the unusual section.  The `short verb'
  1163. % commands make global changes.  The abbreviated "\verb" may not
  1164. % appear in the argument of another command just like "\verb".
  1165. % However the `short verb' character may be used freely in the {\sf
  1166. % verbatim} and {\sf macrocode} environments without ill effect.
  1167. % "\DeleteShortVerb" is silently ignored if its argument does not
  1168. % currently represent a short verb character.  Both commands type a
  1169. % message to tell you the meaning of the character is being changed.
  1170. %
  1171. % \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules
  1172. % \DescribeMacro\Module \DescribeMacro\AltMacroFont
  1173. % The `module' directives of the {\sf docstrip} system
  1174. % \cite{art:docstrip} are normally 
  1175. % recognised and invoke special formatting.  This can be turned on and
  1176. % off in the {\tt .doc} file or the driver file using "\CheckModules"
  1177. % and "\DontCheckModules".  If checking for module directives is on
  1178. % (the default) then code in the scope of the directives is set as
  1179. % determined by the hook "\AltMacroFont", which gives {\small\tt\it
  1180. % small italic type\-writer\/} by default in the New Font
  1181. % Selection Scheme but just ordinary {\small\tt small type\-writer} in
  1182. % the old one, where a font such as italic typewriter can't be used
  1183. % portably (plug for NFSS); you will need to override
  1184. % this if you don't have the italic typewriter font available.
  1185. % Code is in such a scope if it's on a line beginning with "%<" or is
  1186. % between lines starting with "%<*"\meta{name list}">" and
  1187. % "%</"\meta{name list}">".  The directive is formatted by the macro
  1188. % "\Module" whose single argument is the text of the
  1189. % directive between, but not including, the angle brackets; this macro
  1190. % may be re-defined in the driver or style file and by default
  1191. % produces results like \Module{+foo|bar} with no following space.
  1192. %
  1193. % \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the
  1194. % whole code is surrounded by modules to produce several files from a
  1195. % single source. In this case it is clearly not appropriate to format
  1196. % all code lines in a special "\AltMacroFont". For this reason a
  1197. % counter "StandardModuleDepth" is provided which defines the level of
  1198. % module nesting which is still supposed to be formatted in
  1199. % "\MacroFont" rather then "\AltMacroFont". The default setting is
  1200. % "0", for this documentation it was set to
  1201. %\begin{verbatim}
  1202. %   \setcounter{StandardModuleDepth}{1}
  1203. %\end{verbatim}
  1204. % at the beginning of the file.
  1205. %
  1206. %
  1207. % \subsection{Basic usage summary}
  1208. % \changes{v1.7a}{92/03/11}{Added basic usage summary to spell it out.}
  1209. %
  1210. % To sum up, the basic structure of a {\tt .doc} file without any
  1211. % refinements is like this: 
  1212. % \begin{verse}\small
  1213. % "% "\meta{waffle}\ldots\\
  1214. % \quad\ldots \\
  1215. % "% \DescribeMacro{\fred}"\\
  1216. % "% "\meta{description of fred's use}\\
  1217. % \quad\ldots\\
  1218. % "% \StopEventually{"\meta{finale code}"}"\\
  1219. % \quad\ldots\\
  1220. % "% \begin{macro}{\fred}"\\
  1221. % "% "\meta{commentary on macro fred}\\
  1222. % \verb*+%    \begin{macrocode}+\\
  1223. % \meta{code for macro fred}\\
  1224. % \verb*+%    \end{macrocode}+\\
  1225. % "% \end{macro}"\\
  1226. % \quad\ldots\\
  1227. % "% \Finale \PrintIndex \PrintChanges"
  1228. % \end{verse}
  1229. % For examples of the use of most---if not all---of the features
  1230. % described above consult the {\tt doc.doc} source itself. 
  1231. %
  1232. % \subsection{Acknowledgements}
  1233. %
  1234. % I would like to thank all folks at Mainz and at the Royal Military
  1235. % College of Science for their help in this project. Especially Brian
  1236. % and Rainer who pushed everything with their suggestions, bug fixes,
  1237. % etc.
  1238. %
  1239. % A big thank you to David Love who brought the documentation
  1240. % up-to-date again, after I neglected this file for more than two
  1241. % years. This was most certainly a tough job as many features added to
  1242. % {\sf doc.doc} after its publication in {\sl TUGboat\/} have been never
  1243. % properly described. Beside this splendid work he kindly provided
  1244. % additional code (like ``docstrip'' module formatting) which I think
  1245. % every {\sf doc.doc} user will be grateful for.
  1246. %
  1247. %
  1248. % \StopEventually{
  1249. %  \begin{thebibliography}{1}
  1250. %    \bibitem{book:Buerger}  {\sc G. A. B\"urger}.
  1251. %      \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge
  1252. %                und lustige Abenteuer des Freyherrn v.\ M\"unchhausen.
  1253. %      \newblock London, 1786 \& 1788.
  1254. %    \bibitem{art:Knuthliterat} {\sc D. E. Knuth}.
  1255. %      \newblock Literate Programming.
  1256. %      \newblock Computer Journal, Vol.~27, {\it pp}.~97--111, May 1984.
  1257. %    \bibitem{book:KnuthA} {\sc D. E. Knuth}.
  1258. %      \newblock Computers \& Typesetting (The \TeX book).
  1259. %      \newblock Addison-Wesley, Vol. A, 1986.
  1260. %    \bibitem{art:Chen} {\sc L. Lamport}.
  1261. %      \newblock MakeIndex: An Index Processor for \LaTeX.
  1262. %      \newblock 17 February 1987.
  1263. %      \newblock (Taken from the file {\tt makeindex.tex} provided with
  1264. %      the program source code.)
  1265. %    \bibitem{art:doc} {\sc Frank Mittelbach}.
  1266. %      \newblock The {\tt doc}-option.
  1267. %      \newblock {\sl TUGboat}, Vol.~10(2), {\it pp}.~245--273, July
  1268. %        1989.
  1269. %    \bibitem{art:docstrip} {\sc Frank Mittelbach, Denys Duchier and
  1270. %         Johannes Braams}. 
  1271. %      \newblock {\tt docstrip.doc} (to appear).
  1272. %      \newblock The file is part of the DOC package.
  1273. %    \bibitem{book:Raspe} {\sc R. E. Raspe} (*1737, \dag 1797).
  1274. %      \newblock Baron M\"unchhausens narrative of his marvellous
  1275. %                travels and campaigns in Russia.
  1276. %      \newblock Oxford, 1785.
  1277. %    \bibitem{art:verbatim} {\sc Rainer Sch\"opf}.
  1278. %      \newblock A New Implementation of \LaTeX's {\tt verbatim} and
  1279. %      {\tt verbatim*} Environments.
  1280. %      \newblock File {\tt verbatim.doc}, version 1.4i.
  1281. %  \end{thebibliography}
  1282. %  ^^A\PrintIndex
  1283. %  ^^A\PrintChanges
  1284. %
  1285. %  \ifmulticols
  1286. %  \addtocontents{toc}{\protect\end{multicols}}
  1287. %  \fi
  1288. % 
  1289. % } ^^A end \StopEventually
  1290. %
  1291. %
  1292. % \section{The Description of Macros}
  1293. %
  1294. % Most of the following code is destined for {\tt doc.sty} after
  1295. % processing with {\tt docstrip} to include the module {\bf style}
  1296. % indicated here.  (All code in this file not appropriate to {\tt
  1297. % doc.sty} has to be included explicitly by docstrip so that this {\tt
  1298. % .doc} file can be used as directly as a style file rather than the
  1299. % stripped version.)  The usual font change for the
  1300. % conditionally-included lines between the \Module{*style} and
  1301. % \Module{/style} directives is suppressed since only the lines with
  1302. % an explicit directive are special in this file.
  1303. %    \begin{macrocode}
  1304. %<*style>
  1305. %    \end{macrocode}
  1306. % As always, we begin by identifying the latest version of this file
  1307. % on the VDU and in the {\sf log} file. But only if the macros are
  1308. % unknown to the system.  
  1309. % \changes{v1.5i}{89/06/07}{Avoid reading the file twice.}
  1310. %    \begin{macrocode}
  1311. \@ifundefined{macro@cnt}{}{\endinput} \typeout{Style-Option: `doc'
  1312. \fileversion \@spaces\space\space <\filedate> (FMi)} \typeout{English
  1313.    Documentation \@spaces\@spaces\space <\docdate> (DLo, FMi, RMCS)}
  1314. %    \end{macrocode}
  1315. % \DescribeMacro\fileversion
  1316. % \DescribeMacro\filedate
  1317. % \DescribeMacro\docdate
  1318. % As you can see I used macros like \verb+\fileversion+ to denote the
  1319. % version number and the date. They are defined at the very beginning
  1320. % of the style file (without a surrounding {\sf macrocode}
  1321. % environment), so I don't have to search for this place here when I
  1322. % change the version number.  You can see their actual outcome in a
  1323. % footnote to the title.
  1324. %
  1325. %
  1326. % The first thing that we do next is to get ourselves a new comment
  1327. % sign.  Because all sensible signs are already occupied, we will
  1328. % choose one that can only be entered indirectly:
  1329. % {\DoNotIndex{\^}^^A avoid misinterpretion !!!!! VERIFY  
  1330. %    \begin{macrocode}
  1331. \catcode`\^^A=14
  1332. %    \end{macrocode}
  1333. %    \SortIndex{\string^\string^A}{\string\verb\verbatimchar
  1334. %                                  \string^\string^A\verbatimchar
  1335. %                                  \encapchar main}
  1336. % }
  1337. %
  1338. %
  1339. % \subsection{Macros surrounding the `definition parts'}
  1340. %
  1341. % \begin{macro}{\macrocode}
  1342. %    Parts of the macro definition will be surrounded by the
  1343. %    environment {\sf macrocode}.  Put more precisely, they will be
  1344. %    enclosed by a macro whose argument (the text to be set
  1345. %    `verbatim') is terminated by the string 
  1346. % \verb*+%    \end{macrocode}+.  Carefully note the number of spaces.
  1347. %    \verb+\macrocode+ is defined completely analogously to
  1348. %    \verb+\verbatim+, but because a few small changes were carried
  1349. %    out, almost all internal macros have got new names.  We start by
  1350. %    calling the macro \verb+\macro@code+, the macro which bears the
  1351. %    brunt of most of the work, such as \verb+\catcode+ reassignments,
  1352. %    etc.
  1353. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
  1354. %    \begin{macrocode}
  1355. \def\macrocode{\macro@code
  1356. %    \end{macrocode}
  1357. %    Then we take care that all spaces have the same width, and that
  1358. %    they are not discarded.
  1359. %    \begin{macrocode}
  1360.    \frenchspacing \@vobeyspaces
  1361. %    \end{macrocode}
  1362. %    Before closing, we need to call \verb+\xmacro@code+.  It is this
  1363. %    macro that expects an argument which is terminated by the above
  1364. %    string.  This way it is possible to keep the \verb+\catcode+
  1365. %    changes local.
  1366. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
  1367. % \changes{v1.5t}{89/11/07}{Common code moved to `macro@code.}
  1368. %    \begin{macrocode}
  1369.    \xmacro@code}
  1370. %    \end{macrocode}
  1371. % \end{macro}
  1372. %
  1373. %
  1374. % \begin{macro}{\macro@code}
  1375. %    We will now begin with the macro that does the actual work:
  1376. %    \begin{macrocode}
  1377. \def\macro@code{%
  1378. %    \end{macrocode}
  1379. %    In theory it should consist of a {\sf trivlist} environment, but
  1380. %    the empty space before and after the environment should not be
  1381. %    too large.
  1382. %    \begin{macrocode}
  1383.    \topsep \MacrocodeTopsep
  1384. %    \end{macrocode}
  1385. %    The next parameter we set is \verb+\@beginparpenalty+, in order
  1386. %    to prevent a page break before such an environment.
  1387. %    \begin{macrocode}
  1388.    \@beginparpenalty \predisplaypenalty
  1389. %    \end{macrocode}
  1390. %    We then start a \verb+\trivlist+, set \verb+\parskip+ back to
  1391. %    zero and start an empty \verb+\item+.
  1392. %    \begin{macrocode}
  1393.    \trivlist \parskip \z@ \item[]%
  1394. %    \end{macrocode}
  1395. %    Additionally, everything should be set in {\tt typewriter} font.
  1396. %    Some people might prefer it somewhat differently; because of this
  1397. %    the font choice is
  1398. %    macro-driven.\footnote{The font change has to be placed
  1399. %                       {\em after\/}
  1400. %                       the {\tt\bslash item}. Otherwise a change to
  1401. %                       {\tt\bslash baselineskip} will affect the
  1402. %                       paragraph above.}
  1403. %    \begin{macrocode}
  1404.    \macro@font
  1405. %    \end{macrocode}
  1406. %    Because \verb+\item+ sets various parameters, we have found it
  1407. %    necessary to alter some of these retrospectively.
  1408. %    \begin{macrocode}
  1409.    \leftskip\@totalleftmargin \advance\leftskip\MacroIndent
  1410.    \rightskip\z@ \parindent\z@ \parfillskip\@flushglue
  1411. %    \end{macrocode}
  1412. %    The next line consists of the \LaTeX{} definition of \verb+\par+
  1413. %    used in \verb+\verbatim+ and should result in blank lines being
  1414. %    shown as blank lines.
  1415. % \changes{v1.5l}{89/09/10}{Code line numbers supported.}
  1416. % \changes{v1.5t}{89/11/07}{Call `leavevmode to get `everypar on
  1417. %                           blank lines.}
  1418. % \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from
  1419. %                          verbatim.sty} 
  1420. %    \begin{macrocode}
  1421.    \blank@linefalse \def\par{\ifblank@line
  1422.                              \leavevmode\fi
  1423.                              \blank@linetrue\@@par
  1424.                              \penalty\interlinepenalty}
  1425. %    \end{macrocode}
  1426. %    What use is this definition of \verb+\par+\,?  We use the macro
  1427. %   \verb+\obeylines+ of \cite{book:KnuthA} which changes all \verb+^^M+
  1428. %    to \verb+\par+ so that each can control its own indentation.
  1429. %    Next we must also ensure that all special signs are normalized;
  1430. %    that is, they must be given \verb+\catcode+ $12$.
  1431. %    \begin{macrocode}
  1432.    \obeylines \let\do\@makeother \catcode`\`\active \@noligs \dospecials
  1433. %    \end{macrocode}
  1434. % \changes{v1.5t}{89/11/07}{Common code added.}
  1435. % \changes{v1.5w}{90/02/05}{Skip of `@totalleftmargin added.}
  1436. % If indexing by code lines is switched on the line number is
  1437. % incremented and set appropriately.  We also check whether the start of
  1438. % the next line indicates a {\tt docstrip} module directive and process
  1439. % it appropriately if so using "\check@module".
  1440. %    \begin{macrocode}
  1441.    \global\@newlistfalse
  1442.    \global\@minipagefalse
  1443.    \ifcodeline@index
  1444.      \everypar{\global\advance\c@CodelineNo\@ne
  1445.                \llap{\theCodelineNo\ \hskip\@totalleftmargin}%
  1446.                \check@module}%
  1447.    \else \everypar{\check@module}%
  1448.    \fi
  1449. %    \end{macrocode}
  1450. %    We also initialize the cross-referencing feature by calling
  1451. %    \verb+\init@crossref+. This will start the scanning mechanism
  1452. %    when encountering an escape character.
  1453. %    \begin{macrocode}
  1454.    \init@crossref}
  1455. %    \end{macrocode}
  1456. % \end{macro}
  1457. %
  1458. %
  1459. % \begin{macro}{\ifblank@line}
  1460. % \begin{macro}{\blank@linetrue}
  1461. % \begin{macro}{\blank@linefalse}
  1462. %    \verb+\ifblank@line+ is the switch used in the definition above.
  1463. %    In the original {\sf verbatim} environment the \verb+\if@tempswa+
  1464. %    switch is used. This is dangerous because its value may change
  1465. %    while processing lines in the {\sf macrocode} environment.
  1466. %    \begin{macrocode}
  1467. \newif\ifblank@line
  1468. %    \end{macrocode}
  1469. % \end{macro}
  1470. % \end{macro}
  1471. % \end{macro}
  1472. %
  1473. % \begin{macro}{\endmacrocode}
  1474. %    Because we have begun a {\sf trivlist} environment in the {\sf
  1475. %    macrocode} environment, we must also end it.  We must also act on
  1476. %    the value of the "pm@module" flag (see below) and empty
  1477. %    "\everypar".
  1478. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)}
  1479. %    \begin{macrocode}
  1480. \def\endmacrocode{%
  1481.                  \ifpm@module \endgroup \pm@modulefalse \fi
  1482.                  \everypar{}%
  1483.                  \global\@inlabelfalse
  1484.                  \endtrivlist
  1485. %    \end{macrocode}
  1486. %    Additionally \verb+\close@crossref+ is used to do anything needed
  1487. %    to end the cross-referencing mechanism.
  1488. %    \begin{macrocode}
  1489.                  \close@crossref}
  1490. %    \end{macrocode}
  1491. % \end{macro}
  1492. %
  1493. %
  1494. % \begin{macro}{\MacroFont}
  1495. %    Here is the default definition for the \verb+\MacroFont+ macro.
  1496. %    If the new font selection scheme is in use we suppress changes
  1497. %    of math fonts thereby making doc much faster.
  1498. % \changes{v1.5x}{90/02/17}{`math@fontsfalse added for new font sel.}
  1499. % \changes{v1.7a}{92/03/13}{Added `reset@font for NFSS.}
  1500. %    \begin{macrocode}
  1501. \@ifundefined{MacroFont}{%
  1502.   \ifx\undefined\selectfont
  1503.     \def\MacroFont{\small\tt}\else
  1504.     \def\MacroFont{\math@fontsfalse\reset@font\small\tt}\fi
  1505.   }{}
  1506. %    \end{macrocode}
  1507. % \end{macro}
  1508. %
  1509. % \begin{macro}{\AltMacroFont}
  1510. % \begin{macro}{\macro@font}
  1511. % \changes{v1.7a}{92/03/12}{Added to support distinction of modules.}
  1512. % \changes{v1.7c}{92/03/26}{Altered font change for OFSS.}
  1513. % Although most of the macro code is set in "\MacroFont" we want to be
  1514. % able to switch to indicate module code set in "\AltMacroFont".
  1515. % "\macro@font" keeps track of which one we're using.  We can't do the
  1516. % same thing sensibly in OFSS as in NFSS.
  1517. %    \begin{macrocode}
  1518. \@ifundefined{AltMacroFont}{%
  1519.   \ifx\undefined\selectfont
  1520.     \def\AltMacroFont{\small\tt}\else
  1521.     \def\AltMacroFont{\math@fontsfalse\small\reset@font\it\tt}\fi
  1522.   }{}
  1523. \let\macro@font=\MacroFont
  1524. %    \end{macrocode}
  1525. % \end{macro}
  1526. % \end{macro}
  1527. %
  1528. % \begin{macro}{\check@module}
  1529. % \begin{macro}{\ifpm@module}
  1530. % \changes{v1.7a}{92/03/12}{Added.}
  1531. % This is inserted by "\everypar" at the start of each macrocode line to
  1532. % check whether it starts with module information.  (Such information is
  1533. % of the form "%<"\meta{switch}">", where the "%" must be at the
  1534. % start of the line and \meta{switch} comprises names with various
  1535. % possible separators and a possible leading "+", "-", "*" or "/"
  1536. % \cite{art:docstrip}.  All that concerns us here is what the first
  1537. % character of \meta{switch} is.)  First it checks the "pm@module" 
  1538. % flag in case the previous line had a non-block module
  1539. % directive i.e., not "%<*" or "%</"; if it did we need to close the
  1540. % group it started and unset the flag.  "\check@module" looks ahead at
  1541. % the next token and then calls "\ch@percent" to take action depending
  1542. % on whether or not it's a "%"; we don't want to expand the token at
  1543. % this stage.  This is all done conditionally so it can be turned off
  1544. % if it causes problems with code that wasn't designed to be {\tt
  1545. % docstrip}ped.
  1546. %    \begin{macrocode}
  1547. \def\check@module{%
  1548.   \ifcheck@modules
  1549.     \ifpm@module \endgroup \pm@modulefalse \fi
  1550.     \expandafter\futurelet\expandafter\next\expandafter\ch@percent
  1551.   \fi}
  1552. \newif\ifpm@module
  1553. %    \end{macrocode}
  1554. % \end{macro}
  1555. % \end{macro}
  1556. % \begin{macro}{\DontCheckModules}
  1557. % \begin{macro}{\CheckModules}
  1558. % \changes{v1.7a}{92/03/12}{Added.}
  1559. % \begin{macro}{\ifcheck@modules}
  1560. % Here are two driver-file interface macros for turning the module
  1561. % checking on and off using the "check@modules" switch.
  1562. %    \begin{macrocode}
  1563. \def\DontCheckModules{\check@modulesfalse}
  1564. \def\CheckModules{\check@modulestrue}
  1565. \newif\ifcheck@modules  \check@modulestrue
  1566. %    \end{macrocode}
  1567. % \end{macro}
  1568. % \end{macro}
  1569. % \end{macro}
  1570. % \begin{macro}{\ch@percent}
  1571. % \changes{v1.7a}{92/03/12}{Added.}
  1572. % If the lookahead token in "\next" is $"%"_{12}$ we go on to check
  1573. % whether the following one is "<" and otherwise do nothing.  Note the
  1574. % "\expandafter" to get past the "\fi".
  1575. %    \begin{macrocode}
  1576. \def\ch@percent{%
  1577.   \if \percentchar\next
  1578.     \expandafter\check@angle
  1579.   \fi}
  1580. %    \end{macrocode}
  1581. % \end{macro}
  1582. % \begin{macro}{\check@angle}
  1583. % \changes{v1.7a}{92/03/12}{Added.}
  1584. % Before looking ahead for the "<" the "%" is gobbled by the
  1585. % argument here.
  1586. %    \begin{macrocode}
  1587. \def\check@angle#1{\futurelet\next\ch@angle}
  1588. %    \end{macrocode}
  1589. % \end{macro}
  1590. % \begin{macro}{\ch@angle}
  1591. % \changes{v1.7a}{92/03/12}{Added.}
  1592. % If the current lookahead token is "<" we are defined to be
  1593. % processing a module directive can go on to look for "+"
  1594. % etc.; otherwise we must put back the gobbled "%".
  1595. %    \begin{macrocode}
  1596. \def\ch@angle{\if<\next
  1597.     \expandafter\ch@plus@etc 
  1598.   \else \percentchar \fi}
  1599. %    \end{macrocode}
  1600. % \end{macro}
  1601. % \begin{macro}{\ch@plus@etc}
  1602. % \begin{macro}{\check@plus@etc}
  1603. % \changes{v1.7a}{92/03/12}{Added.}
  1604. % We now have to decide what sort of a directive we're dealing with
  1605. % and do the right thing with it.
  1606. %    \begin{macrocode}
  1607. \def\ch@plus@etc<{\futurelet\next\check@plus@etc}
  1608. \def\check@plus@etc{%
  1609.     \if +\next
  1610.       \let\next\pm@module
  1611.     \else\if -\next
  1612.       \let\next\pm@module
  1613.     \else\if *\next
  1614.       \let\next\star@module
  1615.     \else\if /\next
  1616.       \let\next\slash@module
  1617.     \else
  1618.       \let\next\pm@module
  1619.     \fi\fi\fi\fi
  1620.     \next}
  1621. %    \end{macrocode}
  1622. % \end{macro}
  1623. % \end{macro}
  1624. % \begin{macro}{\pm@module}
  1625. % If we're not dealing with a block
  1626. % directive ("*" or "/") i.e., it's a single special line, we set
  1627. % everything up to the next ">" appropriately and then change to the
  1628. % special macro font inside a group which will be ended at the start
  1629. % of the next line.  If the apparent module directive is missing the
  1630. % terminating ">" this will lose, but then so will the {\tt docstrip}
  1631. % implementation.  An alternative strategy would be to have
  1632. % "\pm@module" make ">" active and clear a flag set here to indicate
  1633. % processing the directive.  Appropriate action could then be taken if
  1634. % the flag was found still to be set when processing the next line.
  1635. % \changes{v1.7a}{92/03/12}{Added.} 
  1636. % \changes{v1.7i}{92/07/11}{Support for fonts depending on nesting.}
  1637. %    \begin{macrocode}
  1638. \def\pm@module#1>{\pm@moduletrue
  1639.    \Module{#1}\begingroup 
  1640. %    \end{macrocode}
  1641. %    We switch to a special font as soon the nesting is higher than
  1642. %    the current value of "\c@StandardModuleDepth". We do a local
  1643. %    update to the "\guard@level" here which will be restored after
  1644. %    the current input line.
  1645. %    \begin{macrocode}
  1646.      \advance\guard@level\@ne
  1647.      \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi
  1648. }
  1649. %    \end{macrocode}
  1650. % \end{macro}
  1651. % \begin{macro}{\star@module}
  1652. % \begin{macro}{\slash@module}
  1653. % \changes{v1.7a}{92/03/12}{Added.}
  1654. % \changes{v1.7f}{92/05/16}{Take account of nested guards.}
  1655. % \changes{v1.7i}{92/07/11}{Add counter to determine when to switch to
  1656. %                           special font.}
  1657. % If the start or end of a module {\em block\/} is indicated, after
  1658. % setting the guard we have to check whether a change in the macrocode
  1659. % font should be done.  This will be the case if we are already inside
  1660. % a block or are ending the outermost block.  If so, we globally
  1661. % toggle the font for subsequent macrocode sections between the normal
  1662. % and special form, switching to the new one immediately.
  1663. % \changes{v1.7i}{92/07/17}{Support for fonts depending on module
  1664. %                           nesting}
  1665. %    \begin{macrocode}
  1666. \def\star@module#1>{%
  1667.   \Module{#1}%
  1668.   \global \advance \guard@level\@ne
  1669.   \ifnum \guard@level>\c@StandardModuleDepth
  1670.     \global\let\macro@font=\AltMacroFont \macro@font
  1671.   \fi}
  1672. \def\slash@module#1>{%
  1673.   \Module{#1}%
  1674.   \global \advance \guard@level\m@ne
  1675.   \ifnum \guard@level=\c@StandardModuleDepth
  1676.     \global\let\macro@font\MacroFont  \macro@font
  1677.   \fi
  1678. }
  1679. %    \end{macrocode}
  1680. % \end{macro}
  1681. % \end{macro}
  1682. %
  1683. %
  1684. %  \begin{macro}{\c@StandardModuleDepth}
  1685. % \changes{v1.7i}{92/07/11}{Counter added.}
  1686. %    Counter defining up to which level modules are considered part of
  1687. %    the main code. If, for  example, the whole code is surrounded by
  1688. %    a |%<*style>| module we better set this counter to |1| to avoid
  1689. %    getting the whole code be displayed in typewriter italic.
  1690. %    \begin{macrocode}
  1691. \newcounter{StandardModuleDepth}
  1692. %    \end{macrocode}
  1693. %  \end{macro}
  1694. %
  1695. %
  1696. % \begin{macro}{\guard@level}
  1697. % \changes{v1.7f}{92/05/16}{Added.}
  1698. % We need a counter to keep track of the guard nesting.
  1699. %    \begin{macrocode}
  1700. \newcount \guard@level
  1701. %    \end{macrocode}
  1702. % \end{macro}
  1703. % \begin{macro}{\Module}
  1704. % \changes{v1.7a}{92/03/12}{Added.}
  1705. % \changes{v1.7d}{92/04/25}{Use sans font for modules.}
  1706. % This provides a hook to determine the way the module directive is
  1707. % set.  It gets as argument everything between the angle brackets.
  1708. % The default is to set the contents in sans serif text between
  1709. % $\langle\,\rangle$ with the special characters suitably "\mathcode"d
  1710. % by "\mod@math@codes".  (You can't just set it in a sans text font
  1711. % because normally "|" will print as an em-dash.)  This is done
  1712. % differently depending on whether we have the NFSS or the old one.  In
  1713. % the latter case we can easily change "\fam" appropriately.
  1714. %    \begin{macrocode}
  1715. \@ifundefined{Module}{%
  1716.   \ifx\undefined\selectfont
  1717.     \def\Module#1{{\mod@math@codes$\fam\sffam\langle #1\rangle$}}
  1718. %    \end{macrocode}
  1719. % With NFSS what we probably {\em should\/} do is change to a new
  1720. % "\mathversion" but I (Dave Love) haven't spotted an easy way to do so
  1721. % correctly if the document uses a version other than "normal".  (We
  1722. % need to know in what font to set the other groups.)  This uses a new
  1723. % math alphabet rather than version and consequently has to worry about
  1724. % whether we're using {\sf oldlfont} or not.  I expect there's a better
  1725. % way\ldots
  1726. %    \begin{macrocode}
  1727.   \else
  1728.     \expandafter\ifx\csname ds@oldlfont\endcsname\relax
  1729.       \def\Module#1{{\mod@math@codes$\langle\sfmath{#1}\rangle$}}
  1730.     \else
  1731.       \def\Module#1{{\mod@math@codes$\langle{\sfmath #1}\rangle$}}
  1732.     \fi
  1733.   \fi}{}
  1734. %    \end{macrocode}
  1735. % \end{macro}
  1736. %
  1737. % \begin{macro}{\mod@math@codes}
  1738. % \changes{v1.7c}{92/03/26}{Added.}
  1739. % As well as `words', the module directive text might contain any of the
  1740. % characters "*/+-,&|!()" for the current version of {\sf docstrip}.  We
  1741. % only need special action for two of them in the math code changing
  1742. % required above: "|" is changed to a "\mathop" (it's normally
  1743. % \verb+"026A+) and "&" is also made a "\mathop", but in family 0.
  1744. % Remember that "&" will not have a special catcode when it's
  1745. % encountered. 
  1746. %    \begin{macrocode}
  1747. \def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026}
  1748. %    \end{macrocode}
  1749. % \end{macro}
  1750. %
  1751. % \begin{macro}{\sfmath}
  1752. % \changes{v1.7c}{92/03/26}{Added.}
  1753. % \changes{v1.7d}{92/04/25}{Use sans font for modules.}
  1754. % If NFSS is in use we need a new math alphabet which uses a sans serif
  1755. % font.
  1756. %    \begin{macrocode}
  1757. \ifx\selectfont\undefined
  1758. \else
  1759.   \ifx\sfmath\undefined
  1760.     \newmathalphabet*{\sfmath}{\sfdefault}{m}{n}\fi
  1761. \fi
  1762. %    \end{macrocode}
  1763. % \end{macro}
  1764. %
  1765. %
  1766. %
  1767. % \begin{macro}{\MacrocodeTopsep}
  1768. % \begin{macro}{\MacroIndent}
  1769. %    In the code above, we have used two registers. Therefore we have
  1770. %    to allocate them. The default values might be overwritten with
  1771. %    the help of the \verb+\DocstyleParms+ macro.
  1772. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  1773. % \changes{v1.5y}{90/02/24}{Default changed.}
  1774. % \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to
  1775. %                           avoid unnecessary fontwarning.}
  1776. %    \begin{macrocode}
  1777. \newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt
  1778. \newdimen\MacroIndent    
  1779. \settowidth\MacroIndent{\rm\scriptsize 00\ }
  1780. %    \end{macrocode}
  1781. % \end{macro}
  1782. % \end{macro}
  1783. %
  1784. %
  1785. %
  1786. %
  1787. % \begin{macro}{\macrocode*}
  1788. % \begin{macro}{\endmacrocode*}
  1789. %    Just as in the {\sf verbatim} environment, there is also a `star'
  1790. %    variant of the {\sf macrocode} environment in which a space is
  1791. %    shown by the symbol \verb*+ +.  Until this moment, I have not yet
  1792. %    used it (it will be used in the description of the definition of
  1793. %    \verb+\xmacro@code+ below) but it's exactly on this one occasion
  1794. %    {\em here\/} that you can't use it
  1795. %    (cf.\ M\"unchhausens Marsh problem)\footnote{Karl Friedrich
  1796. %         Hieronymus Frhr.\ v.\ M\"unchhausen (*1720, \dag1797).
  1797. %         Several books were written about fantastic adventures
  1798. %         supposedly told by him (see \cite{book:Raspe} or
  1799. %         \cite{book:Buerger}). In one story he escaped from the
  1800. %         marsh by pulling himself out by his hair.}
  1801. %    directly. Because of this, on this one occasion we'll cheat
  1802. %    around the problem with an additional comment character.  But now
  1803. %    back to \verb+\macrocode*+. We start with the macro
  1804. %    \verb+\macro@code+ which prepares everything and then call the
  1805. %    macro \verb+\sxmacro@code+ whose argument is terminated by the
  1806. %    string \verb*+%    \end{macrocode*}+.
  1807. %    \begin{macrocode}
  1808. \@namedef{macrocode*}{\macro@code\sxmacro@code}
  1809. %    \end{macrocode}
  1810. %    As we know, \verb+\sxmacro@code+ and then \verb+\end{macrocode*}+
  1811. %    (the macro, not the string), will be executed, so that for a
  1812. %    happy ending we still need to define the macro
  1813. %    \verb+\endmacrocode*+.
  1814. %    \begin{macrocode}
  1815. \expandafter\let\csname endmacrocode*\endcsname = \endmacrocode
  1816. %    \end{macrocode}
  1817. % \end{macro}
  1818. % \end{macro}
  1819. %
  1820. %
  1821. %
  1822. %
  1823. %
  1824. %
  1825. %
  1826. % \begin{macro}{\xmacro@code}
  1827. \catcode`\!=\catcode`\%   ^^A In this section there must not be
  1828.                               ^^A any exclamation marks.
  1829.                               ^^A
  1830. %    As already mentioned, the macro \verb+\xmacro@code+ expects an
  1831. %    argument delimited by the string \verb*+%    \end{macrocode}+.  At
  1832. %    the moment that this macro is called, the \verb+\catcode+ of
  1833. %    \TeX's special characters are 12 (`other') or 13 (`active').
  1834. %    Because of this we need to utilize a different escape character
  1835. %    during the definition.  This happens locally.
  1836. %    \begin{macrocode*}
  1837. \begingroup
  1838. \catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
  1839. %    \end{macrocode*}
  1840. %    Additionally, we need to ensure that the symbols in the above
  1841. %    string contain the \verb+\catcode+$\,$s which are available
  1842. %    within the {\sf macrocode} environment.
  1843. %    \begin{macrocode*}
  1844. \catcode`\{=12 \catcode`\}=12
  1845. \catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
  1846. !%    \end{macrocode*}
  1847. !    Next follows the actual definition of  \verb+\macro@code+;
  1848. !    notice the
  1849. !    use of the new escape character.  We manage to get the argument
  1850. !    surrounded by the string \verb+\end{macrocode}+, but at the end
  1851. !    however, in spite of the actual characters used during the
  1852. !    definition of
  1853. !    this macro, \verb+\end+ with the argument \verb+{macrocode}+
  1854. !    will be executed, to ensure a balanced environment.
  1855. !    \begin{macrocode*}
  1856. |gdef|xmacro@code#1%    \end{macrocode}[#1|end[macrocode]]
  1857. !%    \end{macrocode*}
  1858. ! \begin{macro}{\sxmacro@code}
  1859. !    The definition of \verb+\sxmacro@code+ is completely analogous,
  1860. !    only
  1861. !    here a slightly different terminating string will be used.
  1862. !    Note that the space is not active in this environment.
  1863. !    \begin{macrocode}
  1864. |catcode`| =12
  1865. |gdef|sxmacro@code#1%    \end{macrocode*}[#1|end[macrocode*]]
  1866. !%    \end{macrocode}
  1867. !    because the \verb+\catcode+ changes have been made local by
  1868. !    commencing a
  1869. !    new group, there now follows the matching \verb+\endgroup+
  1870. !    in a rather
  1871. !    unusual style of writing.
  1872. !    \begin{macrocode}
  1873. |endgroup
  1874. !%    \end{macrocode}
  1875. \catcode`\!=12
  1876. % \end{macro}
  1877. % \end{macro}
  1878. %
  1879. %
  1880. %
  1881. %
  1882. % \subsection{Macros for the `documentation parts'}
  1883. %
  1884. %
  1885. % \begin{macro}{\DescribeMacro}
  1886. % \begin{macro}{\Describe@Macro}
  1887. % \changes{v1.5v}{90/01/28}{Macro added.}
  1888. % \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.}
  1889. % \begin{macro}{\DescribeEnv}
  1890. % \begin{macro}{\Describe@Env}
  1891. % \changes{v1.5v}{90/01/28}{Macro added.}
  1892. % \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.}
  1893. %    The \verb+\DescribeMacro+ and \verb+\DescribeEnv+ macros should
  1894. %    print their arguments in the margin and produce an index entry.
  1895. %    We simply use \verb+\marginpar+ to get the desired result. This
  1896. %    is however not the best solution because the labels might be
  1897. %    slightly misplaced. One also might get a lot of `marginpar moved'
  1898. %    messages which are hard-wired into the \LaTeX{} output
  1899. %    routine.\footnote{It might be better to change these macros into
  1900. %    environments like the {\sf macro} environment.} First we change
  1901. %    to horizontal mode if necessary. The \LaTeX{} macros
  1902. %    \verb+\@bsphack+ and \verb+\@esphack+ are used to make those
  1903. %    commands invisible (i.e.\ to normalize the surrounding space and
  1904. %    to make the \verb+\spacefactor+ transparent).
  1905. % \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.}
  1906. %    \begin{macrocode}
  1907. \def\DescribeMacro{\leavevmode\@bsphack
  1908. %    \end{macrocode}
  1909. %    When documenting the code for the {\tt amstex.sty} option we
  1910. %    encountered a bug: the \verb+\catcode+ of \verb+@+ was active and
  1911. %    therefore couldn't be used in command names. So we first have to
  1912. %    make sure that we get all \verb+\catcode+s right by calling
  1913. %    \verb+\MakePrivateLetters+ inside a group. Then we call
  1914. %    \verb+\Describe@Macro+ to do the work.
  1915. %    \begin{macrocode}
  1916.    \begingroup\MakePrivateLetters\Describe@Macro}
  1917. \def\Describe@Macro#1{\endgroup
  1918.               \marginpar{\raggedleft\PrintDescribeMacro{#1}}%
  1919. %    \end{macrocode}
  1920. %    Note the use of \verb+\raggedleft+ to place the output flushed
  1921. %    right. Finally we call a macro which produces the actual index
  1922. %    entry and finish with \verb+\@esphack+ to leave no
  1923. %    trace.\footnote{The whole mechanism won't work because
  1924. %                    of the {\tt\bslash leavevmode} in front.
  1925. %                    As a temporary change {\tt\bslash ignorespaces}
  1926. %                    is added.}
  1927. %    \begin{macrocode}
  1928.               \SpecialUsageIndex{#1}\@esphack\ignorespaces}
  1929. %    \end{macrocode}
  1930. %    The \verb+\DescribeEnv+ macro is completely analogous.
  1931. % \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.}
  1932. %    \begin{macrocode}
  1933. \def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters
  1934.   \Describe@Env}
  1935. \def\Describe@Env#1{\endgroup
  1936.               \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
  1937.               \SpecialEnvIndex{#1}\@esphack\ignorespaces}
  1938. %    \end{macrocode}
  1939. %    To put the labels in the left margin we have to use the
  1940. %    \verb+\reversemarginpar+ declaration. (This means that the {\tt
  1941. %    doc.sty} can't be used with all style options.) We also make the
  1942. %    \verb+\marginparpush+ zero and \verb+\marginparwidth+ suitably
  1943. %    wide.
  1944. % \changes{v1.5d}{89/4/28}{marginparwith setting added.}
  1945. %    \begin{macrocode}
  1946. \reversemarginpar
  1947. \setlength\marginparpush{0pt}  \setlength\marginparwidth{8pc}
  1948. %    \end{macrocode}
  1949. % \end{macro}
  1950. % \end{macro}
  1951. % \end{macro}
  1952. % \end{macro}
  1953. %
  1954. % \begin{macro}{\bslash}
  1955. % \changes{v1.7a}{92/02/26}{Moved `bslash documentation to `user
  1956. %                           interface' part}
  1957. %    We start a new group in which to hide the alteration of
  1958. %    \verb+\catcode+$\,$s, and make \verb+|+ introduce commands,
  1959. %    whilst \verb+\+ becomes an `other' character.
  1960. %
  1961. %    \begin{macrocode}
  1962. {\catcode`\|=\z@ \catcode`\\=12
  1963. %    \end{macrocode}
  1964. %    Now we are able to define \verb+\bslash+ (globally) to generate a
  1965. %    backslash of \verb+\catcode+ `other'.  We then close this group,
  1966. %    restoring original \verb+\catcode+$\,$s.
  1967. %    \SpecialEscapechar{\|}
  1968. %    \begin{macrocode}
  1969. |gdef|bslash{\}}
  1970. %    \end{macrocode}
  1971. % \end{macro}
  1972. %
  1973. %
  1974. %
  1975. % \begin{macro}{\verbatim}
  1976. % \begin{macro}{\verbatim*}
  1977. % \changes{v1.7i}{92/07/12}{Added changed definition for verbatim!*.}
  1978. %    The {\sf verbatim} environment holds no secrets; it consists of
  1979. %    the normal \LaTeX{} environment.  We also set the
  1980. %    \verb+\@beginparpenalty+ and change to the font given by
  1981. %    \verb+\MacroFont+.
  1982. %    \begin{macrocode}
  1983. \def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim
  1984.               \MacroFont \frenchspacing \@vobeyspaces \@xverbatim}
  1985. %    \end{macrocode}
  1986. %    We deal in a similar way with the star form of this environment.
  1987. %    \begin{macrocode}
  1988. \@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim
  1989.               \MacroFont \@sxverbatim}
  1990. %    \end{macrocode}
  1991. % \end{macro}
  1992. % \end{macro}
  1993. %
  1994. % \begin{macro}{\@verbatim}
  1995. %    Additionally we redefine the \verb+\@verbatim+ macro so that it
  1996. %    suppresses \verb+%+ characters at the beginning of the line.  The
  1997. %    first lines are copied literally from {\tt latex.tex}.
  1998. % \changes{v1.7i}{92/07/12}{Added `@@par to clear possible `parshape.}
  1999. %    \begin{macrocode}
  2000. \def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi
  2001.       \leftskip\@totalleftmargin\rightskip\z@
  2002.       \parindent\z@\parfillskip\@flushglue\parskip\z@
  2003.       \@@par
  2004.       \@tempswafalse
  2005. %    \end{macrocode}
  2006. %    \verb+\@verbatim+ sets \verb+^^M+, the end of line character, to
  2007. %    be equal to \verb+\par+.  This control sequence is redefined
  2008. %    here; \verb+\@@par+ is the paragraph primitive of \TeX.
  2009. %    \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from
  2010. %                             verbatim.sty} 
  2011. %    \begin{macrocode}
  2012.  \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par
  2013.           \penalty\interlinepenalty
  2014. %    \end{macrocode}
  2015. %    We add a control sequence \verb+\check@percent+ to the definition
  2016. %    of \verb+\par+ whose task it is to check for a percent character.
  2017. %    \begin{macrocode}
  2018.    \check@percent}%
  2019. %    \end{macrocode}
  2020. %    The rest is again copied literally from {\tt latex.tex} (less
  2021. %    "\tt").
  2022. % \changes{v1.7a}{92/02/26}{Removed redundant `tt.}
  2023. %    \begin{macrocode}
  2024.  \obeylines \catcode`\`\active \@noligs \let\do\@makeother
  2025.  \dospecials}
  2026. %    \end{macrocode}
  2027. % \end{macro}
  2028. %
  2029. % \begin{macro}{\check@percent}
  2030. %    Finally we define \verb+\check@percent+.  Since this must compare
  2031. %    a character with a percent sign we must first (locally) change
  2032. %    percent's \verb+\catcode+ so that it is seen by \TeX.  The
  2033. %    definition itself is nearly trivial: grab the following
  2034. %    character, check if it is a \verb+%+, and insert it again if not.
  2035. %    At the end of the {\sf verbatim} environment this macro will peek
  2036. %    at the next input line. In that case the argument to
  2037. %    \verb+\check@percent+ might be a \verb+\par+ or a macro with
  2038. %    arguments. Therefore we make the definition \verb+\long+
  2039. %    (\verb+\par+ allowed) and use the normal \verb+\next+ mechanism
  2040. %    to reinsert the argument after the \verb+\fi+ if necessary.
  2041. %  \changes{v1.5i}{89/06/07}{Definition changed to `long'}
  2042. %  \changes{v1.5i}{89/06/07}{Macro `next' used to guard against
  2043. %                            macro with arguments}
  2044. %    There is a subtle problem here, the equal sign between
  2045. %    \verb+\next+ and \verb+#1+ is actually necessary. Do you see why?
  2046. %    The omission of this token once caused a funny error.
  2047. %  \changes{v1.5u}{89/11/14}{equal sign added.}
  2048. %    \begin{macrocode}
  2049. {\catcode`\%=12 
  2050.  \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else
  2051.                                     \let\next=#1\fi \next}}
  2052. %    \end{macrocode}
  2053. % \end{macro}
  2054. %
  2055. % \begin{macro}{\verb}
  2056. % \changes{v1.7a}{92/02/27}{Now warns about newlines (from
  2057. %                           newdoc with `@noligs added).}
  2058. % We re-define "\verb" to check for newlines in its argument since a
  2059. % missing delimiter is difficult to detect in {\sf doc} source.
  2060. % Although the code is somewhat different, the
  2061. % method follows \cite{art:verbatim}, which should be
  2062. % consulted for commentary.  Perhaps there should be a font-changing
  2063. % hook rather than just using "\tt", but if so it probably should be
  2064. % different from "\MacroFont" since that normally includes "\small"
  2065. % and would look wrong inline.  (There's no particular reason for
  2066. % using lower-casing here to
  2067. % splice in the relevant character, rather than the upper-casing used in
  2068. % the definition of "\SpecialEscapechar"
  2069. % (\S\ref{sect:specialescapechar}); remember that the case
  2070. % shift doesn't touch the control sequence tokens.)
  2071. % \changes{v1.7a}{92/02/28}{Added math math check (from verbatim.sty).}
  2072. %    \begin{macrocode}
  2073. \begingroup
  2074.   \lccode`\~=`\^^M
  2075.   \lowercase{%
  2076.     \gdef\verb{\relax
  2077.       \ifmmode \hbox \else \leavevmode\null \fi
  2078.       \bgroup
  2079.       \tt   \catcode`\`\active \@noligs
  2080.       \let~\verb@err
  2081.       \catcode`\^^M\active
  2082.       \let\do\@makeother \dospecials
  2083.       \@ifstar\@sverb{\@vobeyspaces \frenchspacing \@sverb}}}
  2084. \endgroup
  2085. \def\verb@err{\egroup\@latexerr{\string\verb\space
  2086.                command ended by end of line.}\@ehc}
  2087. %    \end{macrocode}
  2088. % \end{macro}
  2089. % \begin{macro}{\@sverb}
  2090. % \changes{v1.7a}{92/02/27}{Added for `verb change.}
  2091. % \changes{v1.7a}{92/02/28}{Now same as in verbatim.sty.}
  2092. % See \cite{art:verbatim} for commentary.
  2093. %    \begin{macrocode}
  2094. \def\@sverb#1{%
  2095.   \catcode`#1\active  \lccode`\~`#1%
  2096.   \lowercase{\let~\egroup}}
  2097. %    \end{macrocode}
  2098. % \end{macro}
  2099. %
  2100. %
  2101. % \begin{macro}{\macro}
  2102. % \begin{macro}{\m@cro@}
  2103. % \changes{v1.5v}{90/01/28}{`macro@ renamed to `m@cro@ since AmSTeX
  2104. %      defines another macro of the same name.}
  2105. % \begin{macro}{\macro@cnt}
  2106. % \begin{macro}{\macro@level}
  2107. %    \label{page:macro} The {\sf macro} environment is implemented as
  2108. %    a {\sf trivlist} environment, whereby in order that the macro
  2109. %    names can be placed under one another in the margin
  2110. %    (corresponding to the macro's nesting depth), the macro
  2111. %    \verb+\makelabel+ must be altered.  In order to store the nesting
  2112. %    depth, we use a counter. We also need a counter to count the
  2113. %    number of nested {\sf macro} environments.
  2114. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  2115. %    \begin{macrocode}
  2116. \newcount\macro@cnt \macro@cnt=0
  2117. \newcount\macro@level \macro@level=0
  2118. %    \end{macrocode}
  2119. %    The environment takes an argument---the macro name to be
  2120. %    described.  Since this name may contain special `letters' we have
  2121. %    to re-\verb+\catcode+ them before scanning the argument. This is
  2122. %    done by the \verb+\MakePrivateLetters+ macro.  On toplevel we
  2123. %    start with \verb+\begingroup+ otherwise we simply re-catcode the
  2124. %    special letters and call \verb+\m@cro@+. Therefore the
  2125. %    \verb+\endgroup+ at the start of this macro will cancel the group
  2126. %    opened by the \verb+\begin+ macro if we are already inside a {\sf
  2127. %    macro} environment. This avoids problems with the save-stack on
  2128. %    small systems since then the \verb+\trivlist+ used later on will
  2129. %    not put anything onto this stack.
  2130. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  2131. % \changes{v1.7a}{92/02/26}{Catcode backslash to other (from newdoc).}
  2132. %    \begin{macrocode}
  2133. \def\macro{%
  2134.    \ifnum\macro@level=\z@ \begingroup \fi
  2135.    \catcode`\\12
  2136.    \MakePrivateLetters \m@cro@}
  2137. %    \end{macrocode}
  2138. %    After scanning the argument we close the group to get the normal
  2139. %    \verb+\catcode+$\,$s back. Then we assign a special value to
  2140. %    \verb+\topsep+ and start a {\sf trivlist} environment.
  2141. %    Additionally we advance the \verb+\macro@level+ counter to keep
  2142. %    track of the number of nested {\sf macro} environments.
  2143. % \changes{v1.5f}{89/5/07}{MacroTopsep parameter added.}
  2144. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  2145. %    \begin{macrocode}
  2146. \long\def\m@cro@#1{\endgroup \topsep\MacroTopsep \trivlist
  2147.    \advance\macro@level\@ne
  2148. %    \end{macrocode}
  2149. % We also save the name being described in \verb+\saved@macroname+ for
  2150. % use in conjunction with the \verb+\changes+ macro.
  2151. %    \begin{macrocode}
  2152.    \edef\saved@macroname{\string#1}%
  2153. %    \end{macrocode}
  2154. %    Now there follows a variation of \verb+\makelabel+ which is used
  2155. %    should the environment not be nested, or should it lie between
  2156. %    two successive \verb+\begin{macro}+ instructions or explanatory
  2157. %    text.  One can recognize this with the switch \verb+\if@inlabel+
  2158. %    which will be \verb+true+ in the case of successive \verb+\item+
  2159. %    commands.
  2160. %    \begin{macrocode}
  2161.   \def\makelabel##1{\llap{##1}}%
  2162. %    \end{macrocode}
  2163. %    If \verb+@inlabel+ is \verb+true+ and if $\verb=\macro@cnt= > 0$
  2164. %    then the above definition needs to be changed, because in this
  2165. %    case \LaTeX{} would otherwise put the labels all on the same line
  2166. %    and this would lead to them being overprinted on top of each
  2167. %    other.  Because of this \verb+\makelabel+ needs to be redefined
  2168. %    in this case.
  2169. %    \begin{macrocode}
  2170.   \if@inlabel
  2171. %    \end{macrocode}
  2172. %    If \verb+\macro@cnt+ has the value $1$, then we redefine
  2173. %    \verb+\makelabel+ so that the label will be positioned in the
  2174. %    second line of the margin.  As a result of this, two macro names
  2175. %    appear correctly, one under the other.  It's important whilst
  2176. %    doing this that the generated label box is not allowed to have
  2177. %    more depth than a normal line since otherwise the distance
  2178. %    between the first two text lines of \TeX{} will be incorrectly
  2179. %    calculated. The definition should then look like:
  2180. %\begin{verbatim}
  2181. %     \def\makelabel##1{\llap{\vtop to \baselineskip
  2182. %          {\hbox{\strut}\hbox{##1}\vss}}}
  2183. %\end{verbatim}
  2184. %    Completely analogous to this is the case where labels need to be
  2185. %    placed one under the other.  The lines above are only an example
  2186. %    typeset with the {\sf verbatim} environment. To produce the real
  2187. %    definition we save the value of \verb+\macro@cnt+ in
  2188. %    \verb+\count@+ and empty the temp macro \verb+\@tempa+ for later
  2189. %    use.
  2190. %    \begin{macrocode}
  2191.     \let\@tempa\@empty \count@\macro@cnt
  2192. %    \end{macrocode}
  2193. %    In the following loop we append for every already typeset label
  2194. %    an \verb+\hbox{\strut}+ to the definition of \verb+\@tempa+.
  2195. %    \begin{macrocode}
  2196.     \loop \ifnum\count@>\z@
  2197.       \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat
  2198. %    \end{macrocode}
  2199. %    Now be put the definition of \verb+\makelabel+ together.
  2200. % \changes{v1.5b}{89/04/27}{vbox to vtop changed in makelabel (test)}
  2201. % \changes{v1.5e}{89/04/28}{ht strutbox changed to baselineskip (test)}
  2202. %    \begin{macrocode}
  2203.     \edef\makelabel##1{\llap{\vtop to\baselineskip
  2204.                                {\@tempa\hbox{##1}\vss}}}%
  2205. %    \end{macrocode}
  2206. %    Next we increment the value of the nesting depth counter.  This
  2207. %    value inside the {\sf macro} environment is always at least one
  2208. %    after this point, but its toplevel definition is zero. Provided
  2209. %    this environment has been used correctly, $\verb+\macro@cnt+=0$
  2210. %    should not occur when $\verb+@inlabel+=\sf true$.  It is however
  2211. %    possible if this environment is used within other list
  2212. %    environments (but this would have little point).
  2213. %    \begin{macrocode}
  2214.     \advance \macro@cnt \@ne
  2215. %    \end{macrocode}
  2216. %    If \verb+@inlabel+ is false we reset \verb+\macro@cnt+ assuming
  2217. %    that there is enough room to print the macro name without
  2218. %    shifting.
  2219. %    \begin{macrocode}
  2220.   \else  \macro@cnt\@ne  \fi
  2221. %    \end{macrocode}
  2222. %    Now the label will be produced using \verb+\item+. The following
  2223. %    line is only a hack saving the day until a better solution is
  2224. %    implemented.  We have to face two problems: the argument might be
  2225. %    a \verb+\par+ which is forbidden in the argument of other macros
  2226. %    if they are not defined as \verb+\long+, or it is something like
  2227. %    \verb+\iffalse+ or \verb+\else+, i.e.\ something which will be
  2228. %    misinterpreted when \TeX{} is skipping conditional text. In both
  2229. %    cases \verb+\item+ will bomb, so we protect the argument by using
  2230. %    \verb+\string+.
  2231. %    \begin{macrocode}
  2232.   \edef\@tempa{\noexpand\item[\noexpand\PrintMacroName{\string#1}]}%
  2233.   \@tempa
  2234. %    \end{macrocode}
  2235. %    At this point we also produce an index entry.  Because it is not
  2236. %    known which index sorting program will be used, we do not use the
  2237. %    command \verb+\index+, but rather a command
  2238. %    \verb+\SpecialMainIndex+ after advancing the counter for indexing
  2239. %    by line number.  This may be redefined by the user in
  2240. %    order to generate an index entry which will be understood by the
  2241. %    index program in use (note the definition of
  2242. %    \verb+\SpecialMainIndex+ for our installation).
  2243. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  2244. %    \begin{macrocode}
  2245.   {\advance\c@CodelineNo\@ne\SpecialMainIndex{#1}\nobreak}%
  2246. %    \end{macrocode}
  2247. %    The \verb+\nobreak+ is needed to prevent a page break after the
  2248. %    \verb+\write+ produced by the \verb+\SpecialMainIndex+ macro.  We
  2249. %    exclude the new macro in the cross-referencing feature, to
  2250. %    prevent spurious non-main entry references.  Regarding possibly
  2251. %    problematic arguments, the implementation takes
  2252. %    care of \verb+\par+ and the conditionals are uncritical.
  2253. %    \changes{v1.7a}{92/03/02}{Removed redundant code checking for
  2254. %                             `par.}^^A
  2255. %    \begin{macrocode}
  2256.   \DoNotIndex{#1}%
  2257. %    \end{macrocode}
  2258. %    Because the space symbol should be ignored between the
  2259. %    \verb+\begin{macro}{...}+ and the following text we must take
  2260. %    care of this with \verb+\ignorespaces+.
  2261. %    \begin{macrocode}
  2262.   \ignorespaces}
  2263. %    \end{macrocode}
  2264. % \end{macro}
  2265. % \end{macro}
  2266. % \end{macro}
  2267. % \end{macro}
  2268. %
  2269. %
  2270. %
  2271. % \begin{macro}{\endmacro}
  2272. %    When ending a {\sf macro} environment we have to cancel the
  2273. %    \verb+\endgroup+ generated by the \verb+\end+ macro as long as we
  2274. %    are still inside another {\sf macro} environment. Therefore
  2275. %    we check the value of the \verb+\macro@level+ counter. Of course
  2276. %    this counter also has to be decremented.
  2277. %    \SpecialIndex{\macro@cnt}
  2278. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.}
  2279. %    \begin{macrocode}
  2280. \def\endmacro{%
  2281.    \endtrivlist
  2282.    \ifnum\macro@level>\@ne \advance\macro@level\m@ne \begingroup \fi}
  2283. %    \end{macrocode}
  2284. %  \end{macro}
  2285. %
  2286. % \begin{macro}{\MacroTopsep}
  2287. %    Here is the default value for the \verb+\MacroTopsep+ parameter
  2288. %    used above.
  2289. %    \begin{macrocode}
  2290. \newskip\MacroTopsep     \MacroTopsep = 7pt plus 2pt minus 2pt
  2291. %    \end{macrocode}
  2292. % \end{macro}
  2293. %
  2294. %
  2295. %
  2296. %
  2297. %
  2298. % \subsection{Formatting the margin}
  2299. %
  2300. % The following three macros should be user definable.
  2301. % Therefore we define those macros only if they have not already
  2302. % been defined.
  2303. %
  2304. % \begin{macro}{\PrintMacroName}
  2305. % \begin{macro}{\PrintDescribeMacro}
  2306. % \begin{macro}{\PrintDescribeEnv}
  2307. %    The formatting of the macro name in the left margin is done by
  2308. %    these macros. We first set a \verb+\strut+ to get the height and
  2309. %    depth of the normal lines. Then we change to the
  2310. %    \verb+\MacroFont+ using \verb+\string+ to \verb+\catcode+ the
  2311. %    argument to other (assuming that it is a macro name). Finally we
  2312. %    print a space.  The font change remains local since this macro
  2313. %    will be called inside an \verb+\hbox+.
  2314. %    \begin{macrocode}
  2315. \@ifundefined{PrintMacroName}
  2316.    {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{}
  2317. %    \end{macrocode}
  2318. %    We use the same formatting conventions when describing a macro.
  2319. %    \begin{macrocode}
  2320. \@ifundefined{PrintDescribeMacro}
  2321.    {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{}
  2322. %    \end{macrocode}
  2323. %    To format the name of a new environment there is no need to use
  2324. %    \verb+\string+.
  2325. %    \begin{macrocode}
  2326. \@ifundefined{PrintDescribeEnv}
  2327.    {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{}
  2328. %    \end{macrocode}
  2329. % \end{macro}
  2330. % \end{macro}
  2331. % \end{macro}
  2332. %
  2333. %
  2334. %
  2335. % \subsection{Creating index entries by scanning `macrocode'}
  2336. %
  2337. %  The following macros ensure that index entries are created for each
  2338. %  occurrence of a \TeX-like command (something starting with
  2339. %  `\verb+\+') providing indexing has been turned on with "\PageIndex"
  2340. %  or "\CodelineIndex".  With the default definitions of
  2341. %  \verb+\SpecialMainIndex+, etc., the index file generated is
  2342. %  intended to be processed by Chen's {\sf makeindex} program
  2343. %  \cite{art:Chen}.
  2344. %
  2345. %
  2346. %  Of course, in {\em this\/} style file itself we've sometimes had to
  2347. %  make \verb+|+ take the r\^ole of \TeX's escape character to
  2348. %  introduce command names at places where \verb+\+ has to belong to
  2349. %  some other category.  Therefore, we may also need to recognize
  2350. %  \verb+|+ as the introducer for a command when setting the text
  2351. %  inside the {\sf macrocode} environment.  Other users may have the
  2352. %  need to make similar reassignments for their macros.
  2353. %
  2354. %
  2355. % \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar}
  2356. % \begin{macro}{\active@escape@char}
  2357. % \begin{macro}{\special@escape@char}
  2358. %    The macro \verb+\SpecialEscapechar+ is used to denote a special
  2359. %    escape character for the next {\sf macrocode} environment. It has
  2360. %    one argument---the new escape character given as a
  2361. %    `single-letter' control sequence.  Its main purpose is defining
  2362. %    \verb+\special@escape@char+ to produce the chosen escape
  2363. %    character \verb+\catcode+$\,$d to 12 and
  2364. %    \verb+\active@escape@char+ to produce the same character but with
  2365. %    \verb+\catcode+ 13.
  2366. %
  2367. %    The macro \verb+\special@escape@char+ is used to {\em print\/}
  2368. %    the escape character while \verb+\active@escape@char+ is needed
  2369. %    in the definition of \verb+\init@crossref+ to start the scanning
  2370. %    mechanism.
  2371. %
  2372. %    In the definition of \verb+\SpecialEscapechar+ we need an
  2373. %    arbitrary character with \verb+\catcode+ 13. We use `\~{}' and
  2374. %    ensure that it is active. The \verb+\begingroup+ is used to make
  2375. %    a possible change local to the expansion of
  2376. %    \verb+\SpecialEscapechar+.
  2377. % \changes{v1.7g}{92/6/19}{Making tilde active moved outside
  2378. %    definition}
  2379. %    \begin{macrocode}
  2380. \begingroup
  2381. \catcode`\~\active
  2382. \gdef\SpecialEscapechar#1{%
  2383.     \begingroup
  2384. %    \end{macrocode}
  2385. %    Now we are ready for the definition of
  2386. %    \verb+\active@escape@char+.  It's a little tricky: we first
  2387. %    define locally the uppercase code of `\~{}' to be the new escape
  2388. %    character.
  2389. %    \begin{macrocode}
  2390.      \uccode`\~`#1%
  2391. %    \end{macrocode}
  2392. %    Around the definition of \verb+\active@escape@char+ we place an
  2393. %    \verb+\uppercase+ command. Recall that the expansion of
  2394. %    \verb+\uppercase+ changes characters according to their
  2395. %    \verb+\uccode+, but leaves their \verb+\catcode+$\,$s untouched
  2396. %    (cf.\ \TeX{}book page 41).
  2397. %    \begin{macrocode}
  2398.      \uppercase{\gdef\active@escape@char{~}}%
  2399. %    \end{macrocode}
  2400. %    The definition of \verb+\special@escape@char+ is easier, we use
  2401. %    \verb+\string+ to \verb+\catcode+ the argument of
  2402. %    \verb+\SpecialEscapechar+ to 12 and suppress the preceding
  2403. %    \verb+\escapechar+.
  2404. %    \begin{macrocode}
  2405.      \escapechar\m@ne  \xdef\special@escape@char{\string#1}%
  2406. %    \end{macrocode}
  2407. %    Now we close the group and end the definition: the value of
  2408. %    \verb+\escapechar+ as well as the \verb+\uccode+ and
  2409. %    \verb+\catcode+ of `\~{}' will be restored.
  2410. %    \begin{macrocode}
  2411.    \endgroup}
  2412. \endgroup
  2413. %    \end{macrocode}
  2414. % \end{macro}
  2415. % \end{macro}
  2416. % \end{macro}
  2417. %
  2418. %
  2419. %
  2420. %
  2421. % \begin{macro}{\init@crossref}
  2422. %    The replacement text of \verb+\init@crossref+ should fulfill the
  2423. %    following tasks:
  2424. %    \begin{itemize}
  2425. %       \parindent4em
  2426. %       \item[1)]
  2427. %          \verb+\catcode+ all characters used in macro names to
  2428. %          11 (i.e.\ `letter').
  2429. %       \item[2)]
  2430. %          \verb+\catcode+ the `\verb+\+' character to 13
  2431. %          (i.e.\ `active').
  2432. %       \item[3a)]
  2433. %          \verb+\let+ the `\verb+\+' equal \verb+\scan@macro+
  2434. %          (i.e.\ start the macro scanning mechanism) if there is
  2435. %          no  special escape character (i.e.\ the
  2436. %          \verb+\special@escape@char+ is `\verb+\+').
  2437. %       \item[3b)]
  2438. %          Otherwise \verb+\let+ it equal \verb+\bslash+, i.e.\
  2439. %          produce a printable \verb+\+.
  2440. %       \item[4)]
  2441. %          Make the \meta{special escape character} active.
  2442. %       \item[5)]
  2443. %          \verb+\let+ the active version of the special escape
  2444. %          character
  2445. %          (i.e.\ the expansion of \verb+\active@escape@char+) equal
  2446. %          \verb+\scan@macro+.
  2447. %    \end{itemize}
  2448. %    The reader might ask why we bother to \verb+\catcode+ the
  2449. %    `\verb+\+' first to 12 (at the end of \verb+\macro@code+) then
  2450. %    re-\verb+\catcode+ it to 13 in order to produce a $\verb+\+_{12}$
  2451. %    in case 3b) above.  This is done because we have to ensure that
  2452. %    `\verb+\+' has \verb+\catcode+ 13 within the {\sf macrocode}
  2453. %    environment.  Otherwise the delimiter for the argument of
  2454. %    \verb+\xmacro@code+ would not be found (parameter matching
  2455. %    depends on \verb+\catcode+$\,$s).
  2456. %
  2457. %    Therefore we first re-\verb+\catcode+ some characters.
  2458. %    \begin{macrocode}
  2459. \begingroup   \catcode`\|=\z@  \catcode`\\=\active
  2460. %    \end{macrocode}
  2461. %    We carry out tasks 2) and 3b) first.
  2462. %    \SpecialEscapechar{\|}
  2463. %    \begin{macrocode}
  2464. |gdef|init@crossref{|catcode`|\|active   |let\|bslash
  2465. %    \end{macrocode}
  2466. %    Because of the popularity of the `\verb+@+' character as a
  2467. %    `letter' in macros, we normally have to change its
  2468. %    \verb+\catcode+ here, and thus fulfill task 1).  But the macro
  2469. %    designer might use other characters as private letters as well,
  2470. %    so we use a macro to do the \verb+\catcode+ switching.
  2471. %    \SpecialEscapechar\|
  2472. %    \begin{macrocode}
  2473.     |MakePrivateLetters
  2474. %    \end{macrocode}
  2475. %    Now we \verb+\catcode+ the special escape character to 13 and
  2476. %    \verb+\let+ it equal \verb+\scan@macro+, i.e.\ fulfill tasks 4)
  2477. %    and 5). Note the use of \verb+\expandafter+ to insert the chosen
  2478. %    escape character saved in \verb+\special@escape@char+ and
  2479. %    \verb+\active@escape@char+.
  2480. %    \SpecialEscapechar\|
  2481. %    \begin{macrocode}
  2482.     |catcode|expandafter`|special@escape@char|active
  2483.     |expandafter|let|active@escape@char|scan@macro}
  2484. |endgroup
  2485. %    \end{macrocode}
  2486. %    If there is no special escape character, i.e.\ if
  2487. %    \verb+\SpecialEscapechar+ is \verb+\\+, the second last line will
  2488. %    overwrite the previous definition of $\verb+\+_{13}$.  In this
  2489. %    way all tasks are fulfilled.
  2490. %
  2491. %    For happy documenting we give default values to
  2492. %    \verb+\special@escape@char+ and \verb+\active@escape@char+ with
  2493. %    the following line:
  2494. %    \begin{macrocode}
  2495. \SpecialEscapechar{\\}
  2496. %    \end{macrocode}
  2497. % \end{macro}
  2498. %
  2499. %
  2500. %
  2501. % \begin{macro}{\MakePrivateLetters}
  2502. %    Here is the default definition of this command, which makes just
  2503. %    the \verb+@+ into a letter. The user may change it if he/she
  2504. %    needs more or other characters masquerading as letters.
  2505. %    \begin{macrocode}
  2506. \@ifundefined{MakePrivateLetters}
  2507.     {\let\MakePrivateLetters\makeatletter}{}
  2508. %    \end{macrocode}
  2509. % \end{macro}
  2510. %
  2511. % \begin{macro}{\close@crossref}
  2512. %    At the end of a cross-referencing part we prepare ourselves for
  2513. %    the next one by setting the escape character to `\verb+\+'.
  2514. %    \begin{macrocode}
  2515. \def\close@crossref{\SpecialEscapechar\\}
  2516. %    \end{macrocode}
  2517. % \end{macro}
  2518. %
  2519. %
  2520. %
  2521. %
  2522. % \subsection{Macros for scanning macro names}
  2523. %
  2524. % \begin{macro}{\scan@macro}
  2525. % \changes{v1.5k}{89/09/04}{Support for checksum added.}
  2526. % \begin{macro}{\macro@namepart}
  2527. %    The \verb+\init@crossref+ will have made \verb+\active+ our
  2528. %    \verb+\special@escape@char+, so that each
  2529. %    \verb+\active@escape@char+ will invoke \verb+\scan@macro+ when
  2530. %    within the {\sf macrocode} environment.  By this means, we can
  2531. %    automatically add index entries for every \TeX-like command which
  2532. %    is met whilst setting (in verbatim) the contents of {\sf
  2533. %    macrocode} environments.
  2534. %    \begin{macrocode}
  2535. \def\scan@macro{%
  2536. %    \end{macrocode}
  2537. %    First we output the character which triggered this macro.  Its
  2538. %    version \verb+\catcode+$\,$d to 12 is saved in
  2539. %    \verb+\special@escape@char+. We also call \verb+\step@checksum+
  2540. %    to generate later on a proper check-sum (see section
  2541. %    \ref{sec:checksum} for details).
  2542. %    \begin{macrocode}
  2543.    \special@escape@char
  2544.    \step@checksum
  2545. %    \end{macrocode}
  2546. %    If the {\sf macrocode} environment contains, for example, the
  2547. %    command \verb+\\+, the second \verb+\+ should not start the
  2548. %    scanning mechanism. Therefore we use a switch to decide if
  2549. %    scanning of macro names is allowed.
  2550. %    \begin{macrocode}
  2551.    \ifscan@allowed
  2552. %    \end{macrocode}
  2553. %    The macro assembles the letters forming a \TeX\ command in
  2554. %    \verb+\macro@namepart+ so this is initially cleared; we then set
  2555. %    \verb+\next+ to the {\it first\/} character following the
  2556. %    \verb+\+ and call \verb+\macro@switch+ to determine whether that
  2557. %    character is a letter or not.
  2558. %    \begin{macrocode}
  2559.       \let\macro@namepart\@empty
  2560.       \def\next{\futurelet\next\macro@switch}%
  2561. %    \end{macrocode}
  2562. %    As you recognize, we actually did something else, because we have
  2563. %    to defer the \verb+\futurelet+ call until after the final
  2564. %    \verb+\fi+.  If, on the other hand, the scanning is disabled we
  2565. %    simply \verb+\let+ \verb+\next+ equal `empty'.
  2566. %    \begin{macrocode}
  2567.    \else \let\next\@empty \fi
  2568. %    \end{macrocode}
  2569. %    Now we invoke \verb+\next+ to carry out what's needed.
  2570. %    \begin{macrocode}
  2571.    \next}
  2572. %    \end{macrocode}
  2573. % \end{macro}
  2574. % \end{macro}
  2575. %
  2576. %
  2577. % \begin{macro}{\ifscan@allowed}
  2578. % \begin{macro}{\scan@allowedtrue}
  2579. % \begin{macro}{\scan@allowedfalse}
  2580. %    \verb+\ifscan@allowed+ is the switch used above to determine if
  2581. %    the \verb+\active@escape@char+\SpecialIndex{\active@escape@char}
  2582. %    should start the macro scanning mechanism.
  2583. %    \begin{macrocode}
  2584. \newif\ifscan@allowed    \scan@allowedtrue
  2585. %    \end{macrocode}
  2586. % \end{macro}
  2587. % \end{macro}
  2588. % \end{macro}
  2589. %
  2590. %
  2591. % \begin{macro}{\EnableCrossrefs}
  2592. % \begin{macro}{\DisableCrossrefs}
  2593. %    At this point we might define two macros which allow the user to
  2594. %    disable or enable the cross-referencing mechanism. Processing of
  2595. %    files will be faster if only main index entries are generated
  2596. %    (i.e., if \verb+\DisableCrossrefs+ is in force).
  2597. %    \begin{macrocode}
  2598. \def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack}
  2599. %    \end{macrocode}
  2600. %    The macro \verb+\EnableCrossrefs+ will also disable any
  2601. %    \verb+\DisableCrossrefs+ command encountered afterwards.
  2602. %    \begin{macrocode}
  2603. \def\EnableCrossrefs{\@bsphack\scan@allowedtrue
  2604.                      \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack}
  2605. %    \end{macrocode}
  2606. % \end{macro}
  2607. % \end{macro}
  2608. %
  2609. %
  2610. %
  2611. %
  2612. % \begin{macro}{\macro@switch}
  2613. %    Now that we have the character which follows the escape character
  2614. %    (in \verb+\next+), we can determine whether it's a `letter'
  2615. %    (which probably includes \verb+@+).
  2616. %
  2617. %    If it is, we let \verb+\next+ invoke a macro which assembles the
  2618. %    full command name.
  2619. %    \begin{macrocode}
  2620. \def\macro@switch{\ifcat\noexpand\next a%
  2621.      \let\next\macro@name
  2622. %    \end{macrocode}
  2623. %    Otherwise, we have a `single-character' command name.  For all
  2624. %    those single-character names, we use \verb+\short@macro+ to
  2625. %    process them into suitable index entries.
  2626. %    \begin{macrocode}
  2627.      \else \let\next\short@macro  \fi
  2628. %    \end{macrocode}
  2629. %    Now that we know what macro to use to process the macro name, we
  2630. %    invoke it~\ldots
  2631. %    \begin{macrocode}
  2632.    \next}
  2633. %    \end{macrocode}
  2634. % \end{macro}
  2635. %
  2636. %
  2637. % \begin{macro}{\short@macro}
  2638. % \changes{v1.5c}{89/4/27}{Corrected bad bug by putting the
  2639. %                         scan@allowedfalse macro before printing
  2640. %                         the argument.}
  2641. % \changes{v1.7a}{92/03/10}{Ensure character stored in `macro@namepart
  2642. %                           as `letter' so index exclusion works.}
  2643. %    This macro will be invoked (with a single character as parameter)
  2644. %    when a single-character macro name has been spotted whilst
  2645. %    scanning within the {\sf macrocode} environment.
  2646. %
  2647. %    First we take a look at the \verb+\index@excludelist+ to see
  2648. %    whether this macro name should produce an index entry.  This is
  2649. %    done by the \verb+\ifnot@excluded+ macro which assumes that the
  2650. %    macro name is saved in \verb+\macro@namepart+.  The character
  2651. %    mustn't be stored with a special category code or exclusion from
  2652. %    the index won't work, so we employ the case-changing trick used
  2653. %    elsewhere.  Since the argument might be an active character,
  2654. %    \verb+\string+ is used to normalize it. 
  2655. %    \begin{macrocode}
  2656. \def\short@macro#1{\begingroup
  2657.    \catcode`\&=11  \uccode`\&=\expandafter`\string#1%
  2658.    \uppercase{\def\macro@namepart{&}}%
  2659.    \endgroup
  2660.    \ifnot@excluded
  2661. %    \end{macrocode}
  2662. %    If necessary the index entry is produced by the macro
  2663. %    \verb+\produce@index+. Depending on the actual character seen,
  2664. %    this macro has to do different things, so we pass the character
  2665. %    as an argument.
  2666. %    \begin{macrocode}
  2667.      \produce@index{#1}\fi
  2668. %    \end{macrocode}
  2669. %    Then we disable the cross-referencing mechanism with
  2670. %    \verb+\scan@allowedfalse+ and print the actual character. The
  2671. %    index entry was generated first to ensure that no page break
  2672. %    intervenes (recall that a \verb+^^M+ will start a new line).
  2673. %    \begin{macrocode}
  2674.     \scan@allowedfalse#1%
  2675. %    \end{macrocode}
  2676. %    After typesetting the character we can safely enable the
  2677. %    cross-referencing feature again. Note that this macro won't be
  2678. %    called (since \verb+\macro@switch+ won't be called) if
  2679. %    cross-referencing is globally disabled.
  2680. %    \begin{macrocode}
  2681.     \scan@allowedtrue }
  2682. %    \end{macrocode}
  2683. % \end{macro}
  2684. %
  2685. %
  2686. %
  2687. % \begin{macro}{\produce@index}
  2688. % \changes{v1.4s}{89/04/23}{Added noexpand to all {\tt\protect\bslash
  2689. %                if} tests
  2690. %               to avoid garbage produced by new active chars}
  2691. % \changes{v1.4s}{89/04/23}{Used {\tt\protect\bslash string} for the
  2692. %                          same reason.}
  2693. % \changes{v1.5c}{89/4/27}{Corrected bad bug by placing the
  2694. %                         scan@allowedfalse macro into short@macro}
  2695. %    This macro is supposed to generate a suitable \verb+\SortIndex+
  2696. %    command for a given single-letter control sequence.  We test
  2697. %    first for the cases which involve active characters (i.e.\ the
  2698. %    backslash, the special escape character (if any), the space and
  2699. %    the \verb+^^M+).  Using the \verb+\if+ test (testing for
  2700. %    character codes), we have to ensure that the argument isn't
  2701. %    expanded.
  2702. %    \begin{macrocode}
  2703. \def\produce@index#1{%
  2704.   \if\noexpand#1\special@escape@char
  2705. %    \end{macrocode}
  2706. %    If the character is the special escape character (or the
  2707. %    `\verb+\+' in case there was none) the \verb+\it@is@a+ macro is
  2708. %    used to produce the actual \verb+\SortIndex+ call.
  2709. %    \begin{macrocode}
  2710.      \scan@allowedfalse \it@is@a\special@escape@char \else
  2711. %    \end{macrocode}
  2712. %    Next comes the test for a `\verb+\+' which must be the
  2713. %    $\verb+\+_{13}$ expanding to \verb+\bslash+.
  2714. %    \begin{macrocode}
  2715.      \if\noexpand#1\bslash \it@is@a\bslash \else
  2716. %    \end{macrocode}
  2717. %    Another possibility is \verb*+ +$_{13}$. Recall that \verb+\space+
  2718. %    produces a \verb*+ +$_{10}$.
  2719. %    \begin{macrocode}
  2720.        \if\noexpand#1\space \it@is@a\space \else
  2721. %    \end{macrocode}
  2722. %    The last\footnote{Well, it isn't the last active character after
  2723. %                      all. I added {\tt \bslash @noligs} some days ago
  2724. %                      and now {\tt `} too is active. So we have to make
  2725. %                      sure that such characters don't get expanded in 
  2726. %                      the index.} 
  2727. %    possibility of an active character is \verb+^^M+\@.  In this case
  2728. %    we don't test for character codes, since it is easier to look if
  2729. %    the character is equal to \verb+\par+. (We are inside the {\sf
  2730. %    macrocode} environment.)
  2731. %    \begin{macrocode}
  2732.          \ifx#1\par
  2733. %    \end{macrocode}
  2734. %    If we end up here we have just scanned a \verb+\^^M+ or something
  2735. %    similar. Since this will be treated like \verb*+\ + by \TeX{} we
  2736. %    produce a corresponding index entry.
  2737. %    \begin{macrocode}
  2738.          \it@is@a\space \else
  2739. %    \end{macrocode}
  2740. %    If it is the token \verb+\relax+ we do nothing. This can't happen
  2741. %    when the `doc' option is used in the way described here, but was
  2742. %    added to allow extensions like the {\tt idxverb} option.
  2743. %  \changes{v1.5t}{89/11/14}{Added `relax as a possible token to allow
  2744. %                            extensions.}
  2745. %    \begin{macrocode}
  2746.          \ifx#1\relax \else
  2747. %    \end{macrocode}
  2748. %    The next three branches are needed because of bugs in
  2749. %    our {\sf makeindex} program. You can't produce unbalanced index
  2750. %    entries\footnote{This is possible for \TeX{} if you use
  2751. %                     {\tt\string{$_{12}$ \rm or \tt\string}$_{12}$},
  2752. %                     but {\sf makeindex} will complain.}
  2753. %    and you have to double a percent character. To get around these
  2754. %    restrictions we use special macros to produce the \verb+\index+
  2755. %    calls.\footnote{Brian {\sc Hamilton Kelly} has written fixes for
  2756. %                  all three
  2757. %                  bugs. When they've found their way through all
  2758. %                    installations,
  2759. %                    the lines above will be removed. See 
  2760. %                    page~\pageref{bug:fixes} if you already have them.
  2761. %                    (I'm not sure which versions incorporate these, but
  2762. %                    2.11 is OK.  See also
  2763. %                    \pageref{makeindex:version}.)}
  2764. %    \begin{macrocode}
  2765.            \if\noexpand#1\bgroup \LeftBraceIndex \else
  2766.              \if\noexpand#1\egroup \RightBraceIndex \else
  2767.                \if\noexpand#1\percentchar \PercentIndex \else
  2768. %    \end{macrocode}
  2769. %    All remaining characters are used directly to produce their index
  2770. %    entries. This is possible even for the characters which have
  2771. %    special meanings in the index program, provided we quote the
  2772. %    characters.  (This is correctly done in \verb+\it@is@a+.)
  2773. %    \begin{macrocode}
  2774.                  \it@is@a{\string#1}%
  2775. %    \end{macrocode}
  2776. %    We now need a whole pile of \verb+\fi+$\,$s to match up with
  2777. %    the \verb+\if+$\,$s.
  2778. %    \begin{macrocode}
  2779.        \fi \fi \fi \fi \fi \fi \fi \fi}
  2780. %    \end{macrocode}
  2781. % \end{macro}
  2782. %
  2783. %
  2784. %
  2785. % \begin{macro}{\macro@name}
  2786. %    We now come to the macro which assembles command names which
  2787. %    consist of one or more `letters' (which might well include
  2788. %    \verb+@+ symbols, or anything else which has a \verb+\catcode+ of
  2789. %    11).
  2790. %
  2791. %    To do this we add the `letter' to the existing definition of
  2792. %    \verb+\macro@namepart+ (which you will recall was originally set
  2793. %    to \verb+\@empty+).
  2794. %    \begin{macrocode}
  2795. \def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}%
  2796. %    \end{macrocode}
  2797. %    Then we grab hold of the {\em next\/} single character and let
  2798. %    \verb+\more@macroname+ determine whether it belongs to the letter
  2799. %    string forming the command name or is a `non-letter'.
  2800. %    \begin{macrocode}
  2801.      \futurelet\next\more@macroname}
  2802. %    \end{macrocode}
  2803. % \end{macro}
  2804. %
  2805. %
  2806. %
  2807. %
  2808. %
  2809. % \begin{macro}{\more@macroname}
  2810. %
  2811. %    This causes another call of \verb+\macro@name+ to add in the next
  2812. %    character, if it is indeed a `letter'.
  2813. %    \begin{macrocode}
  2814. \def\more@macroname{\ifcat\noexpand\next a%
  2815.      \let\next\macro@name
  2816. %    \end{macrocode}
  2817. %    Otherwise, it finishes off the index entry by invoking
  2818. %    \verb+\macro@finish+.
  2819. %    \begin{macrocode}
  2820.      \else \let\next\macro@finish \fi
  2821. %    \end{macrocode}
  2822. %    Here's where we invoke whatever macro was \verb+\let+ equal to
  2823. %    \verb+\next+.
  2824. %    \begin{macrocode}
  2825.      \next}
  2826. %    \end{macrocode}
  2827. % \end{macro}
  2828. %
  2829. %
  2830. %
  2831. %
  2832. %
  2833. % \begin{macro}{\macro@finish}
  2834. %    When we've assembled the full `letter'-string which forms the
  2835. %    command name, we set the characters forming the entire command
  2836. %    name, and generate an appropriate \verb+\index+ command (provided
  2837. %    the command name is not on the list of exclusions).  The
  2838. %    `\verb+\+' is already typeset; therefore we only have to output
  2839. %    all `letters' saved in \verb+\macro@namepart+.
  2840. %    \begin{macrocode}
  2841. \def\macro@finish{%
  2842.   \macro@namepart
  2843. %    \end{macrocode}
  2844. %    Then we call \verb+\ifnot@excluded+ to decide whether we have to
  2845. %    produce an index entry. The construction with \verb+\@tempa+ is
  2846. %    needed because we want the expansion of \verb+\macro@namepart+ in
  2847. %    the \verb+\index+ command.\footnote{The {\tt \bslash index}
  2848. %    command will expand its argument in the {\tt\bslash output}
  2849. %    routine.  At this time {\tt\bslash macro@namepart} might have a
  2850. %    new value.}
  2851. %    \begin{macrocode}
  2852.   \ifnot@excluded
  2853.      \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
  2854.      \@tempa  \fi}
  2855. %    \end{macrocode}
  2856. % \end{macro}
  2857. %
  2858. %
  2859. %
  2860. %
  2861. %
  2862. % \subsection[The index exclude list]{The index exclude
  2863. %             list\footnotemark} 
  2864. %            \footnotetext{Warning: the incomplete commentary on {\tt
  2865. %                          \bslash DoNotIndex} and the macros it calls
  2866. %                          was written by Dave Love.} 
  2867. %
  2868. %    The internal form of the index exclude list is
  2869. % \begin{quote}
  2870. % \meta{macro name}\verb+,+\meta{macro name}\verb+,+
  2871. % \ldots\verb+,+
  2872. % \end{quote}
  2873. % where \meta{macro name} is a macro name like
  2874. % $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$.  Note that the "\"
  2875. % has category `other' and the other characters in the name are all
  2876. % `letter', regardless of their normal category. 
  2877. %
  2878. % \begin{macro}{\DoNotIndex}
  2879. %    This macro is used to suppress macro names in the index.  It
  2880. %    starts off with a new group because we have to change the
  2881. %    \verb+\catcode+$\,$s of all characters which belong to `letters'
  2882. %    while macros are defined.
  2883. %    \begin{macrocode}
  2884. \def\DoNotIndex{\begingroup \MakePrivateLetters
  2885.     \catcode`\\12
  2886. %    \end{macrocode}
  2887. %    Then we call the macro which actually reads the argument given by
  2888. %    the user.
  2889. %    \begin{macrocode}
  2890.     \do@not@index}
  2891. %    \end{macrocode}
  2892. % \end{macro}
  2893. %
  2894. %
  2895. %
  2896. % \begin{macro}{\do@not@index}
  2897. %    We make the \verb+\do@not@index+ macro \verb+\long+
  2898. %    since the user might want to exclude the \verb+\par+ 
  2899. %    macro.
  2900. %    \begin{macrocode}
  2901. \long\def\do@not@index#1{%
  2902. %    \end{macrocode}
  2903. %    It just adds to a token list after finishing the group in which
  2904. %    the catcodes were changed.
  2905. %    \changes{v1.7a}{92/02/26}{Replaced with newdoc version.}
  2906. %    \begin{macrocode}
  2907.     \endgroup
  2908.     \addto@hook\index@excludelist{#1,}}    
  2909. %    \end{macrocode}
  2910. % \end{macro}
  2911. %
  2912. % \begin{macro}{\addto@hook}
  2913. % The code for adding tokens (the second argument) to a token list
  2914. % (the first argument) is taken from~\cite{art:verbatim}, but it needs
  2915. % to be "\long" in case "\par" is amongst the tokens.
  2916. %    \begin{macrocode}
  2917. \long\def\addto@hook#1#2{#1\expandafter{\the#1#2}}
  2918. %    \end{macrocode}
  2919. % \end{macro}
  2920. %
  2921. % \begin{macro}{\index@excludelist}
  2922. % We need an initially-empty register for the excluded list.
  2923. %    \begin{macrocode}
  2924. \newtoks\index@excludelist
  2925. \index@excludelist{}
  2926. %    \end{macrocode}
  2927. % \end{macro}
  2928. %
  2929. % \begin{macro}{\ifnot@excluded}
  2930. %    \changes{v1.7a}{92/02/26}{Replaced with newdoc version.}
  2931. % \begin{macro}{\expanded@notin}
  2932. %    Now we take a look at the \verb+\index@excludelist+ to see
  2933. %    whether a macro name saved in \verb+\macro@namepart+ should
  2934. %    produce an index entry. This macro is a pseudo \verb+\if+; it
  2935. %    should expand to \verb+\iftrue+ or \verb+\iffalse+ depending on
  2936. %    the contents of \verb+\index@excludelist+.
  2937. %    \begin{macrocode}
  2938. \begingroup
  2939. %    \end{macrocode}
  2940. %    First we change "\catcode"s so that "\" is `other' and "|" a
  2941. %    temporary for the escape character. This is necessary since our
  2942. %    macro names are stored that way in the "\index@excludelist".
  2943. %    \begin{macrocode}
  2944. \catcode`\|=0%
  2945. \catcode`\\=12
  2946. %    \end{macrocode}
  2947. %    Then we define "\ifnot@excluded" to call "\expanded@notin" with
  2948. %    two arguments: the first is the string "\" followed by the
  2949. %    contents of "\macro@namepart" followed by a "," and the second is
  2950. %    "\the" followed by "\index@excludelist". To achieve the expansion
  2951. %    of "\macro@namepart", i.e.\ to pass its contents, we need a
  2952. %    suitable number of "\expandafter"s.
  2953. %    \SpecialEscapechar{\|}
  2954. %    \begin{macrocode}
  2955. |gdef|ifnot@excluded{|expandafter
  2956.      |expanded@notin|expandafter{|expandafter
  2957.      \|macro@namepart,}{|the|index@excludelist}}
  2958. |endgroup
  2959. %    \end{macrocode}
  2960. %    The macro "\expanded@notin" now does the dirty work. It first
  2961. %    defines a macro "\in@@" with a very special parameter text. If
  2962. %    you look closely "\in@@" has three arguments, the first one is
  2963. %    delimited by the first argument of "\expanded@notin" (i.e.\ by
  2964. %    the string starting with a "\" and ending with a "," above), the
  2965. %    second is undelimited (which means that it will get the next
  2966. %    token after our string, and the third is delimited again and will
  2967. %    get the rest up to the token "\in@@". In other words the token
  2968. %    "\in@@" is also used as a delimiter.
  2969. %    \begin{macrocode}
  2970. \def\expanded@notin#1#2{%
  2971.  \def\in@@##1#1##2##3\in@@{%
  2972. %    \end{macrocode}
  2973. %    Now the replacement text simply compares the second argument
  2974. %    (i.e.\ the undelimited one after our string) to the token
  2975. %    "\expanded@notin". This is an unclosed "\ifx" statement which
  2976. %    means that this macro behaves similar to a normal \TeX{}
  2977. %    conditional.
  2978. %    \begin{macrocode}
  2979.   \ifx\expanded@notin##2}%
  2980. %    \end{macrocode}
  2981. %    After all these preparations we call "\in@@". First we expand the
  2982. %    token after "\in@@" (which is "\the" from the second argument to
  2983. %    "\expanded@notin"). As a result we get the contents of the
  2984. %    "\index@excludelist" inserted after "\in@@". After this contents
  2985. %    we add once more the string we are looking for, then the token
  2986. %    "\expanded@notin" and finally the token "\in@@".
  2987. %    \begin{macrocode}
  2988.  \expandafter\in@@#2#1\expanded@notin\in@@}
  2989. %    \end{macrocode}
  2990. %    Now what happens when the macro "\in@@" above gets called? The
  2991. %    first argument to "\in@@" is delimited by our string. In other
  2992. %    words it will get everything from the contents of
  2993. %    "\index@excludelist" before this string. If the string is not in
  2994. %    "\index@excludelist" then it gets the whole contents, since after
  2995. %    it we had inserted the string one more. In this case the next
  2996. %    token is "\expanded@notin" which gets assigned to the second
  2997. %    argument and the third argument will be empty. If, on the other
  2998. %    hand, the string was inside "\index@excludelist" then the second
  2999. %    argument will not be the token "\expanded@notin" and the third
  3000. %    argument will be all the garbage up to "\in@@". Therefore testing
  3001. %    the seconded argument, as done in the definition of "\in@@" will
  3002. %    tell us  whether or not the string is in "\index@includelist" and
  3003. %    this was exactly what we wanted. (Deep breath.) You got
  3004. %    that?\footnote{\TeX{}book page 125. The code described above is
  3005. %    originally due to Michael Spivak who used a similar method within
  3006. %    the \AmSTeX{} macros.}
  3007. % \end{macro}
  3008. % \end{macro}
  3009. %
  3010. %
  3011. %
  3012. %
  3013. %
  3014. %
  3015. %
  3016. % \subsection{Macros for generating index entries}
  3017. %
  3018. % Here we provide default definitions for the macros invoked to create
  3019. % index entries; these are either invoked explicitly, or automatically
  3020. % by \verb+\scan@macro+.  As already mentioned, the definitions given
  3021. % here presuppose that the \verb+.idx+ file will be processed by
  3022. % Chen's {\sf makeindex} program --- they may be redefined for use
  3023. % with the user's favourite such program.
  3024. %
  3025. % To assist the reader in locating items in the index, all such
  3026. % entries are sorted alphabetically {\em ignoring\/} the initial
  3027. % `\verb+\+'; this is achieved by issuing an \verb+\index+ command
  3028. % which contains the `actual' operator for {\sf makeindex}.  The
  3029. % default value for the latter operator is `\verb+@+', but the latter
  3030. % character is so popular in \LaTeX\ style files that it is necessary
  3031. % to substitute another character.  This is indicated to {\sf
  3032. % makeindex} by means of an `index style file'; the character selected
  3033. % for this function is \verb+=+, and therefore this character too must
  3034. % be specially treated when it is met in a \TeX\ command.  A suitable
  3035. % index style file is provided amongst the supporting files for this
  3036. % style file in {\tt gind.ist} and is generated from this source by
  3037. % processing with {\tt docstrip} to extract the module {\bf gind}.  A
  3038. % similar style file {\tt gglo.ist} is supplied for sorting the change
  3039. % information in the glossary file and is extracted as module {\bf
  3040. % gglo}.  First of all we add some information to the front of the
  3041. % {\tt .ist} files.  \changes{v1.7a}{92/03/11}{Gglo.ist and gind.ist
  3042. % now derivable from doc.doc with docstrip.}
  3043. %    \begin{macrocode}
  3044. %</style>
  3045. %<+gind|gglo>%% This is a MAKEINDEX style file which should be used to
  3046. %<+gind>%% generate the formatted index for use with the doc
  3047. %<+gglo>%% generate the formatted change history for use with the doc
  3048. %<+gind|gglo>%% style option. The TeX commands used below are defined in
  3049. %<+gind|gglo>%% doc.sty.  The commands for MAKEINDEX like `level'
  3050. %<+gind|gglo>%% `item_x1' are described in `` Makeindex, A General
  3051. %<+gind|gglo>%% Purpose, Formatter-Independent Index Processor'' by
  3052. %<+gind|gglo>%% Pehong Chen. 
  3053. %<+gind|gglo>
  3054. %    \end{macrocode}
  3055. %
  3056. % \begin{macro}{\actualchar}
  3057. % \begin{macro}{\quotechar}
  3058. % \begin{macro}{\levelchar}
  3059. %    First come the definitions of \verb+\actualchar+,
  3060. %    \verb+\quotechar+ and \verb+\levelchar+. Note, that our defaults
  3061. %    are not the ones used by the {\sf makeindex} program without a
  3062. %    style file.
  3063. %    \begin{macrocode}
  3064. %<*style>
  3065. \@ifundefined{actualchar}{\def\actualchar{=}}{}
  3066. \@ifundefined{quotechar}{\def\quotechar{!}}{}
  3067. \@ifundefined{levelchar}{\def\levelchar{>}}{}
  3068. %</style>
  3069. %<+gind|gglo>actual '='
  3070. %<+gind|gglo>quote '!'
  3071. %<+gind|gglo>level '>'
  3072. %<*style>
  3073. %    \end{macrocode}
  3074. % \end{macro}
  3075. % \end{macro}
  3076. % \end{macro}
  3077. %
  3078. %
  3079. % \begin{macro}{\encapchar}
  3080. %    The {\sf makeindex} default for the \verb+\encapchar+ isn't
  3081. %    changed.
  3082. %    \begin{macrocode}
  3083. \@ifundefined{encapchar}{\def\encapchar{|}}{}
  3084. %    \end{macrocode}
  3085. % \end{macro}
  3086. %
  3087. %
  3088. % \begin{macro}{\verbatimchar}
  3089. %    We also need a special character to be used as a delimiter for
  3090. %    the \verb+\verb*+ command used in the definitions below.
  3091. %    \begin{macrocode}
  3092. \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{}
  3093. %    \end{macrocode}
  3094. % \end{macro}
  3095. %
  3096. %
  3097. % \begin{macro}{\SpecialIndex}
  3098. %    The \verb+\SpecialIndex+ command creates index entries for
  3099. %    macros.  If the argument is \verb+\+$xyz$, the command produces
  3100. %    \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}|
  3101. %    given the above defined defaults for \verb+\actualchar+,
  3102. %    \verb+\quotechar+ and \verb+\verbatimchar+.  We first remove the
  3103. %    initial `\verb+\+' to get a better index.
  3104. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3105. %    \begin{macrocode}
  3106. \def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble
  3107.                                       \string#1\actualchar
  3108. %    \end{macrocode}
  3109. %    Then follows the actual entry. A \verb+\quotechar+ is placed
  3110. %    before the \verb+*+ to allow its use as a special {\sf makeindex}
  3111. %    character.  Again \verb+\@bsphack+ and \verb+\@esphack+ are used
  3112. %    to make the macros invisible.
  3113. %    \begin{macrocode}
  3114.       \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}%
  3115.     \@esphack}
  3116. %    \end{macrocode}
  3117. % \end{macro}
  3118.  
  3119. % \begin{macro}{\SpecialMainIndex}
  3120. % \begin{macro}{\SpecialUsageIndex}
  3121. %    The \verb+\SpecialMainIndex+ macro is used to cross-reference the
  3122. %    names introduced by the {\sf macro} environment.  The action is
  3123. %    as for \verb+\SpecialIndex+, except that {\sf makeindex} is
  3124. %    instructed to `encap'sulate the entry with the string
  3125. %    \verb+|main+ to cause it to generate a call of the \verb+\main+
  3126. %    macro.
  3127. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3128. %    \begin{macrocode}
  3129. \def\SpecialMainIndex#1{\@bsphack\special@index{\expandafter\@gobble
  3130.                                         \string#1\actualchar
  3131.                                         \string\verb
  3132.                                         \quotechar*\verbatimchar
  3133.                                         \string#1\verbatimchar
  3134.                                         \encapchar main}%
  3135.                         \@esphack}
  3136. %    \end{macrocode}
  3137. %    The \verb+\SpecialUsageIndex+ is literally the same---only we use
  3138. %    {\tt usage} instead of {\tt main}.
  3139. %    \begin{macrocode}
  3140. \def\SpecialUsageIndex#1{\@bsphack\index{\expandafter\@gobble\string#1%
  3141.     \actualchar\string\verb\quotechar*\verbatimchar
  3142.     \string#1\verbatimchar
  3143.     \encapchar usage}\@esphack}
  3144. %    \end{macrocode}
  3145. % \end{macro}
  3146. % \end{macro}
  3147. %
  3148. %
  3149. %
  3150. %
  3151. % \begin{macro}{\SpecialEnvIndex}
  3152. %    Indexing environments is done a little bit differently; we produce
  3153. %    two index entries with the \verb+\SpecialEnvIndex+ macro:
  3154. %    \begin{macrocode}
  3155. \def\SpecialEnvIndex#1{\@bsphack
  3156. %    \end{macrocode}
  3157. %    First we sort the environment under its own name stating in the
  3158. %    actual entry that this is an environment.
  3159. %    \begin{macrocode}
  3160.     \index{#1\actualchar{\tt #1} (environment)\encapchar usage}%
  3161. %    \end{macrocode}
  3162. %    The second entry is sorted as a subitem under the key
  3163. %    `environments:'. 
  3164. %    \begin{macrocode}
  3165.     \index{environments:\levelchar{\tt #1}\encapchar usage}\@esphack}
  3166. %    \end{macrocode}
  3167. %    Because both entries correspond to `descriptions' of the
  3168. %    environment, we encapsulate the page numbers with the
  3169. %    \verb+\usage+ macro.
  3170. % \end{macro}
  3171. %
  3172. %
  3173. %
  3174. % \begin{macro}{\SortIndex}
  3175. %    This macro is used to generate the index entries for any
  3176. %    single-character command that \verb+\scan@macro+ encounters.  The
  3177. %    first parameter specifies the lexical order for the character,
  3178. %    whilst the second gives the actual characters to be printed in
  3179. %    the entry. It can also be used directly to generate index entries
  3180. %    which differ in sort key and actual entry.
  3181. %    \begin{macrocode}
  3182. \def\SortIndex#1#2{\index{#1\actualchar#2}}
  3183. %    \end{macrocode}
  3184. % \end{macro}
  3185. %
  3186. %
  3187. %
  3188. % \begin{macro}{\it@is@a}
  3189. %    This macro is supposed to produce a correct \verb+\SortIndex+
  3190. %    entry for a given character. Since this character might be
  3191. %    recognised as a `command' character by the index program used,
  3192. %    all characters are quoted with the \verb+\quotechar+.
  3193. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3194. %    \begin{macrocode}
  3195. \def\it@is@a#1{\special@index{\quotechar #1\actualchar
  3196.                           \string\verb\quotechar*\verbatimchar
  3197.                           \quotechar\bslash\quotechar#1\verbatimchar}}
  3198. %    \end{macrocode}
  3199. % \end{macro}
  3200. %
  3201. %
  3202. %
  3203. % \begin{macro}{\LeftBraceIndex}
  3204. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3205. % \begin{macro}{\RightBraceIndex}
  3206. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3207. %    These two macros fix the problems with {\sf makeindex}.  Note the
  3208. %    `hack' with \verb+\iffalse}\fi+ to satisfy both \TeX{} and the
  3209. %    {\sf makeindex} program. When this is written to the {\tt .idx}
  3210. %    file \TeX{} will see both braces (so we get a balanced text).
  3211. %    {\sf makeindex} will also see balanced braces but when the actual
  3212. %    index entry is again processed by \TeX{} the brace in between
  3213. %    \verb+\iffalse+ \verb+\fi+ will vanish.
  3214. %    \begin{macrocode}
  3215. \@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{%
  3216.    \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar
  3217.           \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{}
  3218.  
  3219. \@ifundefined{RightBraceIndex}{\def\RightBraceIndex{%
  3220.  \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb
  3221.            \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{}
  3222. %    \end{macrocode}
  3223. % \end{macro}
  3224. % \end{macro}
  3225. %
  3226. %
  3227. % \begin{macro}{\PercentIndex}
  3228. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  3229. % \changes{v1.7c}{92/03/25}{Default now for bug-fixed makeindex}
  3230. % By default we assume a version of {\sf makeindex} without the
  3231. % percent bug is being used.
  3232. %    \begin{macrocode}
  3233. \@ifundefined{PercentIndex}
  3234.   {\def\PercentIndex{\it@is@a\percentchar}}{}
  3235. %    \end{macrocode}
  3236. % \end{macro}
  3237. % \begin{macro}{\OldMakeindex}
  3238. % \changes{v1.7c}{92/03/26}{Replaced `NewMakeIndex.}
  3239. % \begin{macro}{\percentchar}
  3240. %    Here is one solution for the percent bug in {\sf makeindex}.  The
  3241. %    macro \verb+\percentchar+ denotes a \verb+%+$_{12}$.
  3242. %    Calling this from a style option or the driver file sets things
  3243. %    up appropriately.\label{bug:fixes} 
  3244. %    \begin{macrocode}
  3245. \def\OldMakeindex{\def\PercentIndex{%
  3246.     \special@index{\quotechar\percentchar\actualchar\string\verb
  3247.            \quotechar*\verbatimchar\quotechar\bslash
  3248.            \percentchar\percentchar\verbatimchar}}}
  3249. {\catcode`\%=12 \gdef\percentchar{%}}
  3250. %    \end{macrocode}
  3251. % \end{macro}
  3252. % \end{macro}
  3253. %
  3254. %
  3255. %
  3256. %
  3257. %
  3258. %
  3259. % \subsection{Redefining the {\sf index} environment}
  3260. %
  3261. %\changes{v1.4r}{89/04/22}{twocols env. placed into separate file}
  3262. %\changes{v1.4?}{89/04/19}{use DEK's algorithm and implement
  3263. %                         a twocols env.}
  3264. %\changes{v1.4?}{89/04/16}{changes to the index env.}
  3265. %\changes{v1.5a}{89/04/26}{Now input multicol.sty instead of
  3266. %                         multcols.sty}
  3267. % \begin{macro}{\ifhave@multicol}
  3268. % \changes{v1.7a}{92/03/04}{Added to support avoiding multicol.sty}
  3269. %    By default
  3270. %    the index is set in three columns, and will start on the same
  3271. %    page as, and underneath, the last part of the text of the
  3272. %    documented style file, if possible.  The last page will be
  3273. %    reformatted with balanced columns.  This requires the {\sf
  3274. %    multicols} environment which is described elsewhere.
  3275. % ^^A  described elsewhere (see page~\xrefto{mittelbachmulti}).
  3276. %    So that {\sf doc} can be run independently of {\tt multicol.sty}
  3277. %    we first check for its existence and set the "have@multicol" flag
  3278. %    appropriately for use below.
  3279. %    \begin{macrocode}
  3280. \newif\ifhave@multicol
  3281. \openin\@ne multicol.sty
  3282. \ifeof\@ne \else \have@multicoltrue \fi
  3283. \closein\@ne \relax
  3284. %    \end{macrocode}
  3285. %    On systems where it is impossible to determine the existence of a
  3286. %    file using the above method the docstrip program can be directed
  3287. %    to force using multicol by including the next line.
  3288. % \changes{v1.7i}{92/07/14}{Force use of multicol.sty if necessary.}
  3289. %    \begin{macrocode}
  3290. %<+multicol>\have@multicoltrue
  3291. %    \end{macrocode}
  3292. % \end{macro}
  3293. %    If we found {\tt multicol.sty} we use it.  It would be nice to
  3294. %    delay this (and the re-definition of "theindex") until we knew
  3295. %    whether an index was actually required \ldots
  3296. %    \begin{macrocode}
  3297. \ifhave@multicol \input{multicol.sty} \fi
  3298. %    \end{macrocode}
  3299. %
  3300. % \begin{macro}{\IndexMin}
  3301. % \begin{macro}{\c@IndexColumns}
  3302. %    \changes{v1.4t}{89/04/24}{Counter added.}
  3303. %    If {\tt multicol} is in use,
  3304. %    when the index is started we compute the remaining space on the
  3305. %    current page; if it is greater than \verb+\IndexMin+, the first
  3306. %    part of the index will then be placed in the available space.
  3307. %    The number of columns set is controlled by the counter
  3308. %    \verb+\c@IndexColumns+ which can be changed with a
  3309. %    \verb+\setcounter+ declaration.
  3310. %    \begin{macrocode}
  3311. \newdimen\IndexMin         \IndexMin       = 80pt
  3312. \newcount\c@IndexColumns   \c@IndexColumns = 3
  3313. %    \end{macrocode}
  3314. % \end{macro}
  3315. % \end{macro}
  3316. %
  3317. %
  3318. % \begin{macro}{\theindex}
  3319. %    Now we start the multi-column mechanism, if appropriate. We use the
  3320. %    \verb+\c@IndexColumns+ \LaTeX{} counter declared above to denote
  3321. %    the number of columns and insert the `index prologue' text (which
  3322. %    might contain a \verb+\section+ call, etc.). See the default
  3323. %    definition for an example.
  3324. %    \changes{v1.4t}{89/04/24}{Incorporated new multicols env.}
  3325. %    \changes{v1.5a}{89/04/26}{Call multicols first}
  3326. %    \changes{v1.6e}{91/04/03}{Turned into env definition.}
  3327. %    \changes{v1.7a}{92/03/04}{Include test for multicols.}
  3328. %    \begin{macrocode}
  3329. \ifhave@multicol
  3330.   \renewenvironment{theindex}
  3331.     {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]%
  3332. %    \end{macrocode}
  3333. %    Then we make a few last minute assignments to read the individual
  3334. %    index \verb+\item+$\,$s and finish off by ignoring any initial
  3335. %    space.
  3336. %    \begin{macrocode}
  3337.       \IndexParms \let\item\@idxitem \ignorespaces}%
  3338. %    \end{macrocode}
  3339. % \end{macro}
  3340. % \begin{macro}{\endtheindex}
  3341. %    \changes{v1.4t}{89/04/24}{Incorporated new multicols env.}
  3342. %    At the end of the index, we have only to end the {\sf multicols}
  3343. %    environment.
  3344. %    \begin{macrocode}
  3345.     {\end{multicols}}
  3346. %    \end{macrocode}
  3347. %    If we can't use {\sf multicols} we warn the user and use an
  3348. %    environment that's basically the one from {\tt article.sty}.
  3349. %    \begin{macrocode}
  3350. \else
  3351.   \typeout{Can't find multicols.sty -- will use normal index layout if
  3352.      necessary.} 
  3353.   \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi
  3354.     \columnseprule \z@  \columnsep 35\p@
  3355.     \twocolumn[\index@prologue]%
  3356.     \IndexParms \let\item\@idxitem \ignorespaces}
  3357.   \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi}
  3358. \fi
  3359. %    \end{macrocode}
  3360. % \end{macro}
  3361. % Here are the necessary {\sf makeindex} declarations. We disable
  3362. % scanning of macro names inside the index with "\scan@allowedfalse\n"
  3363. % to avoid recursion.
  3364. %    \begin{macrocode}
  3365. %</style>
  3366. %<+gind>preamble
  3367. %<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
  3368. %<+gind>postamble
  3369. %<+gind>"\n\n \\end{theindex}\n"
  3370. %<*style>
  3371. %    \end{macrocode}
  3372. %
  3373. %
  3374. % \begin{macro}{\IndexPrologue}
  3375. % \begin{macro}{\index@prologue}
  3376. %    The \verb+\IndexPrologue+ macro is used to place a short message
  3377. %    into the document above the index.  It is implemented by
  3378. %    redefining \verb+\index@prologue+, a macro which holds the
  3379. %    default text.  We'd better make it a \verb+\long+ macro to allow
  3380. %    \verb+\par+ commands in its argument.
  3381. %    \begin{macrocode}
  3382. \long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack}
  3383. %    \end{macrocode}
  3384. %    Now we test whether the default is already defined by another
  3385. %    style file. If not we define it.
  3386. %    \begin{macrocode}
  3387. \@ifundefined{index@prologue}
  3388.      {\def\index@prologue{\section*{Index}%
  3389.                  \markboth{Index}{Index}%
  3390.                  The italic numbers denote the pages where the
  3391.                  corresponding entry is described,
  3392.                  numbers underlined point to the definition,
  3393.                  all others indicate the places where it is used.
  3394.                  }}{}
  3395. %    \end{macrocode}
  3396. % \end{macro}
  3397. % \end{macro}
  3398. %
  3399. %
  3400. %
  3401. % \begin{macro}{\IndexParms}
  3402. %    These are some last-minute assignments for formatting the index
  3403. %    entries. They are defined in a separate macro so that a user can
  3404. %    substitute different definitions.  We start by defining the
  3405. %    various parameters controlling leading and the separation between
  3406. %    the two columns.  The entire index is set in \verb+\small+ size.
  3407. %    \begin{macrocode}
  3408. \@ifundefined{IndexParms}
  3409.     {\def\IndexParms{%
  3410.        \parindent \z@
  3411.        \columnsep 15pt
  3412.        \parskip 0pt plus 1pt
  3413.        \rightskip 15pt
  3414.        \mathsurround \z@
  3415.        \parfillskip=-15pt
  3416.         \small
  3417. %    \end{macrocode}
  3418. % \begin{macro}{\@idxitem}
  3419. % \begin{macro}{\subitem}
  3420. % \begin{macro}{\subsubitem}
  3421. %    Index items are formatted with hanging indentation for any items
  3422. %    which may require more than one line.
  3423. %    \begin{macrocode}
  3424.        \def\@idxitem{\par\hangindent 30pt}%
  3425. %    \end{macrocode}
  3426. %    Any sub-item in the index is formatted with a 15pt indentation
  3427. %    under its main heading.
  3428. %    \begin{macrocode}
  3429.        \def\subitem{\@idxitem\hspace*{15pt}}%
  3430. %    \end{macrocode}
  3431. %    Whilst sub-sub-items go in a further 10pt.
  3432. %    \begin{macrocode}
  3433.        \def\subsubitem{\@idxitem\hspace*{25pt}}%
  3434. %    \end{macrocode}
  3435. % \begin{macro}{\indexspace}
  3436. %    The {\sf makeindex} program generates an \verb+\indexspace+
  3437. %    before each new alphabetic section commences. After this final
  3438. %    definition we end the \verb+\@ifundefined+ and the definition of
  3439. %    \verb+\IndexParms+.
  3440. %    \begin{macrocode}
  3441.        \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}%
  3442.       }}{}
  3443. %    \end{macrocode}
  3444. % \end{macro}
  3445. % \end{macro}
  3446. % \end{macro}
  3447. % \end{macro}
  3448. % \end{macro}
  3449. %
  3450. %
  3451. % \begin{macro}{\efill}
  3452. %    This definition of \verb+\efill+ is intended to be used after
  3453. %    index items which have no following text (for example, ``{\it
  3454. %    see\/}'' entries).  It just ensures that the current line is
  3455. %    filled, preventing ``\verb+Underfull \hbox+'' messages.
  3456. %    \begin{macrocode}
  3457. \def\efill{\hfill\nopagebreak}%
  3458. %</style>
  3459. %<+gind|gglo>item_x1   "\\efill \n \\subitem "
  3460. %<+gglo>item_x2   "\\ "
  3461. %<+gind>item_x2   "\\efill \n \\subsubitem "
  3462. %<*style>
  3463. %    \end{macrocode}
  3464. % \end{macro}
  3465. %
  3466. %
  3467. %
  3468. % \begin{macro}{\pfill}
  3469. % \begin{macro}{\dotfil}
  3470. % \begin{macro}{\dotfill}
  3471. %     The following definitions provide the \verb+\pfill+ command; if
  3472. %    this is specified in the index style file to {\sf makeindex} as
  3473. %    the delimiter to appear after index items, then the intervening
  3474. %    space before the referenced page numbers will be filled with
  3475. %    dots, with a little white space interpolated at each end of the
  3476. %    dots.  If the line is broken the dots will show up on both lines.
  3477. %    \begin{macrocode}
  3478. \def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus  1fill}%
  3479. \def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}%
  3480. \def\pfill{\unskip~\dotfill\penalty500\strut\nobreak
  3481.                \dotfil~\ignorespaces}%
  3482. %</style>
  3483. %<+gind|gglo>delim_0   "\\pfill "
  3484. %<+gind|gglo>delim_1   "\\pfill "
  3485. %<+gind|gglo>delim_2   "\\pfill "
  3486. %<*style>
  3487. %    \end{macrocode}
  3488. % \end{macro}
  3489. % \end{macro}
  3490. % \end{macro}
  3491. %
  3492. %
  3493. %
  3494. % \begin{macro}{\*}
  3495. %    Here is the definition for the \verb+\*+ macro. It isn't used in
  3496. %    this set of macros.
  3497. %    \begin{macrocode}
  3498. \def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}}
  3499. %    \end{macrocode}
  3500. % \end{macro}
  3501. %
  3502. %
  3503. % \begin{macro}{\main}
  3504. %    The {\it defining\/} entry for a macro name is flagged with the
  3505. %    string {\tt\encapchar main}\footnote{With the current definition
  3506. %    of {\tt\bslash encapchar} substituted for {\tt\encapchar}} in the
  3507. %    \verb+\index+ command; {\sf makeindex} processes this so that the
  3508. %    \verb+\main+ macro will be invoked to underline the page
  3509. %    number(s) on which the {\em definition\/} of the macro will be
  3510. %    found.
  3511. %    \begin{macrocode}
  3512. \@ifundefined{main}{\def\main#1{\underline{#1}}}{}
  3513. %    \end{macrocode}
  3514. % \end{macro}
  3515. %
  3516. % \begin{macro}{\usage}
  3517. %    The \verb+\usage+ macro is used to indicate entries describing
  3518. %    the usage of a macro. The corresponding page number(s) will be
  3519. %    set in {\it italics}.
  3520. %    \begin{macrocode}
  3521. \@ifundefined{usage}{\def\usage#1{{\it #1}}}{}
  3522. %    \end{macrocode}
  3523. % \end{macro}
  3524. %
  3525. %
  3526. % \begin{macro}{\PrintIndex}
  3527. % \changes{v1.5k}{89/09/04}{`printindex changed to `PrintIndex.}
  3528. % \changes{v1.7a}{92/02/26}{Documentation moved to interface section.}
  3529. % \begin{macro}{\printindex}
  3530. %    This is the same as "\printindex" in the {\sf makeidx} style.
  3531. %    \begin{macrocode}
  3532. \def\PrintIndex{\@input{\jobname.ind}}
  3533. %    \end{macrocode}
  3534. %    Since this macro was called \verb+\printindex+ in older versions
  3535. %    of {\tt doc.sty} we also provide the following definition.
  3536. %    \begin{macrocode}
  3537. \def\printindex{\typeout{\string\printindex\space is obsolete!}%
  3538.                 \typeout{Please use \string\PrintIndex\space
  3539.                          if you are a macro implementor^^J
  3540.                          or get a newer version of the documented 
  3541.                          software if you are a user}%
  3542.                 \PrintIndex}
  3543. %    \end{macrocode}
  3544. % \end{macro}
  3545. % \end{macro}
  3546. %
  3547. % We want headings in the index (and changes list) according to the
  3548. % initial character of the next block of entries and have to instruct
  3549. % {\sf makeindex} appropriately.  Unfortunately the specification for
  3550. % this changed sometime between versions 2.4 and 2.11 of {\sf
  3551. % makeindex}.  We provide both ways of doing it but unfortunately this
  3552. % will always produce a warning message from {\sf makeindex}.  This is
  3553. % for older versions:
  3554. %  \changes{v1.7h}{92/07/01}{Turn off headings in gls file}
  3555. %    \begin{macrocode}
  3556. %</style>
  3557. %<+gind,gglo>% The next lines will produce some warnings when
  3558. %<+gind,gglo>% running Makeindex as they try to cover two different
  3559. %<+gind,gglo>% versions of the program:
  3560. %<+gind,gglo>lethead_prefix   "{\\bf\\hfil "
  3561. %<+gind,gglo>lethead_suffix   "\\hfil}\\nopagebreak\n"
  3562. %<+gind>lethead_flag       1
  3563. %<+gglo>lethead_flag       0
  3564. %    \end{macrocode}
  3565. % This works for newer ones:
  3566. %    \begin{macrocode}
  3567. %<+gind,gglo>heading_prefix   "{\\bf\\hfil "
  3568. %<+gind,gglo>heading_suffix   "\\hfil}\\nopagebreak\n"
  3569. %<+gind>headings_flag       1
  3570. %<+gglo>headings_flag       0
  3571. %<*style>
  3572. %    \end{macrocode}
  3573. %
  3574. %
  3575. %
  3576. % \subsection[Dealing with the change history]
  3577. %            {Dealing with the change history\footnotemark}
  3578. % \footnotetext{The whole section was proposed by Brian {\sc Hamilton
  3579. %               Kelly}. He also documented and debugged the macros as
  3580. %               well as many other parts of this style option.}
  3581. %
  3582. % To provide a change history log, the \verb+\changes+ command has
  3583. % been introduced.  This takes three arguments, respectively, the
  3584. % version number of the file, the date of the change, and some detail
  3585. % regarding what change has been made.  The first of these arguments
  3586. % is otherwise ignored, but the others are written out and may be used
  3587. % to generate a history of changes, to be printed at the end of the
  3588. % document.  However, note that older versions of Chen's standard {\sf
  3589. % makeindex} 
  3590. % program limit any textual field to just 64 characters; therefore,
  3591. % is important that the number of characters in the second and third
  3592. % parameters should not exceed 61 altogether (to allow for the
  3593. % parentheses placed around the date).
  3594. %
  3595. % \begin{macro}{\changes}
  3596. % \changes{BHK}{89/04/26}{Documented {\tt\protect\bslash changes}
  3597. %                         command.}
  3598. % \changes{BHK}{89/04/26}{Changed definition of
  3599. %                         {\tt\protect\bslash protect}.}
  3600. %    The output of
  3601. %    the \verb+\changes+ command goes into the \meta{Glossary\_File}
  3602. %    and therefore uses the normal \verb+\glossaryentry+
  3603. %    commands.\footnote{Note that a recent change in \LaTeX{} 2.09
  3604. %    changed the command name in the {\tt.glo} file from {\tt\bslash
  3605. %    indexentry} to {\tt\bslash glossaryentry}.  It is therefore
  3606. %    necessary to have a special {\sf makeindex} style file called {\tt
  3607. %    gglo.ist} to process this file correctly.} Thus {\sf makeindex}
  3608. %    or a similar program can be used to process the output into a
  3609. %    sorted ``glossary''.  The \verb+\changes+ command commences by
  3610. %    taking the usual measures to hide its spacing, and then redefines
  3611. %    \verb+\protect+ for use within the argument of the generated
  3612. %    \verb+\indexentry+ command. 
  3613. %
  3614. %    We re-code nearly all chars found in \verb+\sanitize+ to letter
  3615. %    since the use of special style options which make some characters
  3616. %    active might upset the \verb+\changes+ command when writing its
  3617. %    entries to the file. However we have to leave \verb+%+ as comment
  3618. %    and \verb*+ + as \meta{space} otherwise chaos will happen.
  3619. %    And, of course the \verb+\+ should be available as escape
  3620. %    character.
  3621. % \changes{v1.5v}{90/01/28}{`Re-code a lot of chars.}
  3622. % \changes{v1.5m}{89/09/20}{`actualchar in second level removed.}
  3623. % \changes{v1.5o}{89/09/24}{New sorting.}
  3624. % \changes{v1.6c}{90/06/29}{Again new sorting.}
  3625. %    \begin{macrocode}
  3626. \def\changes{\@bsphack\begingroup\@sanitize
  3627.    \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
  3628.    \changes@}
  3629. \def\changes@#1#2#3{%
  3630.   \def\protect##1{\string##1\space}%
  3631.   \edef\@tempa{\noexpand\glossary{#1\levelchar
  3632.                                  \expandafter\@gobble
  3633.                                  \saved@macroname\actualchar
  3634.                                  \string\verb\quotechar*%
  3635.                                  \verbatimchar\saved@macroname
  3636.                                  \verbatimchar:\levelchar #3}}%
  3637.   \@tempa\endgroup\@esphack}
  3638. %    \end{macrocode}
  3639. % \begin{macro}{\saved@macroname}
  3640. % \changes{BHK}{89/04/26}{Provided for sorting outside
  3641. %                         {\sf macro} environment}
  3642. %    The entries are sorted for convenience by the name of the most
  3643. %    recently introduced macroname (i.e., that in the most recent
  3644. %    \verb+\begin{macro}+ command).  We therefore provide
  3645. %    \verb+\saved@macroname+ to record that argument, and provide a
  3646. %    default definition in case \verb+\changes+ is used outside a {\sf
  3647. %    macro} environment.  (This is a {\em wicked\/} hack to get such
  3648. %    entries at the beginning of the sorted list!  It works providing no
  3649. %    macro names start with "!" or \verb+"+.)
  3650. %    \changes{v1.7a}{92/03/02}{Changed string used for better sorting.}
  3651. %    \begin{macrocode}
  3652. \def\saved@macroname{"General"}
  3653. %    \end{macrocode}
  3654. % \end{macro}
  3655. %
  3656. % \begin{macro}{\RecordChanges}
  3657. % \changes{BHK}{89/04/26}{Renames former {\tt\protect\bslash
  3658. %                         PrintChanges} command.}
  3659. %    To cause the changes to be written (to a {\tt.glo}) file, we
  3660. %    define \verb+\RecordChanges+ to invoke \LaTeX's usual
  3661. %    \verb+\makeglossary+ command.
  3662. %    \begin{macrocode}
  3663. \let\RecordChanges\makeglossary
  3664. %    \end{macrocode}
  3665. % \end{macro}
  3666. % \end{macro}
  3667. %
  3668. % 
  3669. % \begin{macro}{\GlossaryMin}
  3670. %    \changes{BHK}{89/04/26}{Added to support
  3671. %                            {\tt\protect\bslash changes}.}
  3672. % \begin{macro}{\c@GlossaryColumns}
  3673. %    \changes{BHK}{89/04/26}{Added to support
  3674. %                            {\tt\protect\bslash changes}.}
  3675. %    The remaining macros are all analogues of those used for the {\sf
  3676. %    theindex} environment.  When the glossary is started we compute
  3677. %    the space which remains at the bottom of the current page; if
  3678. %    this is greater than \verb+\GlossaryMin+ then the first part of
  3679. %    the glossary will be placed in the available space.  The number
  3680. %    of columns set are controlled by the counter
  3681. %    \verb+\c@GlossaryColumns+ which can be changed with a
  3682. %    \verb+\setcounter+ declaration.
  3683. %    \begin{macrocode}
  3684. \newdimen\GlossaryMin         \GlossaryMin       = 80pt
  3685. \newcount\c@GlossaryColumns   \c@GlossaryColumns = 2
  3686. %    \end{macrocode}
  3687. % \end{macro}
  3688. % \end{macro}
  3689. %
  3690. %
  3691. % \begin{macro}{\theglossary}
  3692. %  \changes{BHK}{89/04/26}{Added to support
  3693. %                            {\tt\protect\bslash changes}.}
  3694. % \changes{v1.5p}{89/09/28}{Now call `multicols first.}
  3695. %    \changes{v1.6e}{91/04/03}{Turned into env definition.}
  3696. %    \changes{v1.7a}{92/03/10}{Changed to work without multicols if
  3697. %                              necessary.}
  3698. % \begin{macro}{\endglossary}
  3699. %    \changes{BHK}{89/04/26}{Added to support
  3700. %                            {\tt\protect\bslash changes}.}
  3701. %    The environment {\sf theglossary} is defined in the same manner
  3702. %    as the {\sf theindex} environment.
  3703. %    \begin{macrocode}
  3704. \ifhave@multicol
  3705.   \newenvironment{theglossary}{%
  3706.     \begin{multicols}\c@GlossaryColumns
  3707.                      [\glossary@prologue][\GlossaryMin]%
  3708.     \GlossaryParms \let\item\@idxitem \ignorespaces}%
  3709.    {\end{multicols}}
  3710. \else
  3711.   \newenvironment{theglossary}{%
  3712.       \@restonecoltrue\if@twocolumn\@restonecolfalse\fi
  3713.       \columnseprule \z@  \columnsep 35\p@
  3714.       \twocolumn[\glossary@prologue]%
  3715.       \GlossaryParms \let\item\@idxitem \ignorespaces}
  3716.     {\if@restonecol\onecolumn\else\clearpage\fi}
  3717. \fi
  3718. %    \end{macrocode}
  3719. % \end{macro}
  3720. % \end{macro}
  3721. % Here are the necessary {\sf makeindex} declarations with scanning
  3722. % disabled as for the index.
  3723. %    \begin{macrocode}
  3724. %</style>
  3725. %<+gglo>preamble
  3726. %<+gglo>"\n \\begin{theglossary} \n
  3727. %<+gglo>    \\makeatletter\\scan@allowedfalse\n"
  3728. %<+gglo>postamble
  3729. %<+gglo>"\n\n \\end{theglossary}\n"
  3730. %    \end{macrocode}
  3731. % This difference from {\tt gind.ist} is necessary if you have an
  3732. % up-to-date \LaTeX. 
  3733. %    \begin{macrocode}
  3734. %<+gglo>keyword "\\glossaryentry"
  3735. %<*style>
  3736. %    \end{macrocode}
  3737. %
  3738. %
  3739. % \begin{macro}{\GlossaryPrologue}
  3740. %    \changes{BHK}{89/04/26}{Added to support
  3741. %                            {\tt\protect\bslash changes}.}
  3742. % \begin{macro}{\glossary@prologue}
  3743. %    \changes{BHK}{89/04/26}{Added to support
  3744. %                            {\tt\protect\bslash changes}.}
  3745. %    The \verb+\GlossaryPrologue+ macro is used to place a short
  3746. %    message above the glossary into the document.  It is implemented
  3747. %    by redefining \verb+\glossary@prologue+, a macro which holds the
  3748. %    default text.  We better make it a long macro to allow
  3749. %    \verb+\par+ commands in its argument.
  3750. %    \begin{macrocode}
  3751. \long\def\GlossaryPrologue#1{\@bsphack
  3752.                              \def\glossary@prologue{#1}%
  3753.                              \@esphack}
  3754. %    \end{macrocode}
  3755. %    Now we test whether the default is already defined by another
  3756. %    style file. If not we define it.
  3757. %    \begin{macrocode}
  3758. \@ifundefined{glossary@prologue}
  3759.      {\def\glossary@prologue{\section*{{Change History}}%
  3760.                  \markboth{{Change History}}{{Change History}}%
  3761.                  }}{}
  3762. %    \end{macrocode}
  3763. % \end{macro}
  3764. % \end{macro}
  3765. %
  3766. % \begin{macro}{\GlossaryParms}
  3767. %    \changes{BHK}{89/04/26}{Added to support
  3768. %                            {\tt\protect\bslash changes}.}
  3769. % Unless the user specifies otherwise, we set the change history
  3770. % using the same parameters as for the index.
  3771. %    \begin{macrocode}
  3772. \@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{}
  3773. %    \end{macrocode}
  3774. % \end{macro}
  3775. % \begin{macro}{\PrintChanges}
  3776. %    \changes{BHK}{89/04/26}{Added to support
  3777. %                            {\tt\protect\bslash changes}.}
  3778. %    To read in and print the sorted change history, just put the
  3779. %    \verb+\PrintChanges+ command as the last (commented-out, and thus
  3780. %    executed during the documentation pass through the file) command
  3781. %    in your style file.  Alternatively, this command may form one of
  3782. %    the arguments of the \verb+\StopEventually+ command, although a
  3783. %    change history is probably {\em not\/} required if only the
  3784. %    description is being printed.
  3785. %
  3786. %    The command assumes that {\sf makeindex} or some other program
  3787. %    has processed the {\tt.glo} file to generate a sorted {\tt.gls}
  3788. %    file.
  3789. %    \begin{macrocode}
  3790. \def\PrintChanges{\@input{\jobname.gls}}
  3791. %    \end{macrocode}
  3792. % \end{macro}
  3793. %
  3794. %    
  3795. %
  3796. %
  3797. %
  3798. % \subsection{Bells and whistles}
  3799. %
  3800. % \begin{macro}{\StopEventually}
  3801. % \changes{v1.5k}{89/09/04}{Support for checksum.}
  3802. % \begin{macro}{\Finale}
  3803. % \changes{v1.5k}{89/09/04}{Support for checksum.}
  3804. % \changes{v1.5z}{90/04/22}{Define `Finale globally.}
  3805. % \begin{macro}{\OnlyDescription}
  3806. %    Here is the default definition for \verb+\StopEventually+, we
  3807. %    simply save its argument in the macro \verb+\Finale+.
  3808. %    \begin{macrocode}
  3809. \long\def\StopEventually#1{\@bsphack\gdef\Finale{#1%
  3810. %    \end{macrocode}
  3811. %    But \verb+\Finale+ will be called at the very end of a file. This
  3812. %    is exactly the point were we want to know if the file is
  3813. %    uncorrupted. Therefore we call \verb+\check@checksum+ at this
  3814. %    point. 
  3815. %    \begin{macrocode}
  3816.               \check@checksum}%
  3817. %    \end{macrocode}
  3818. %    On the other hand: \verb+\StopEventually+ is more or less a
  3819. %    dividing point between description and code. So we start to look
  3820. %    for the check-sum of the documented file by calling
  3821. %    \verb+\init@checksum+. 
  3822. %    \begin{macrocode}
  3823.            \init@checksum
  3824.            \@esphack}
  3825. %    \end{macrocode}
  3826. %    When the user places an \verb+\OnlyDescription+ declaration in
  3827. %    the driver file the document should only be typeset up to
  3828. %    \verb+\StopEventually+. We therefore have to redefine this macro.
  3829. %    \begin{macrocode}
  3830. \def\OnlyDescription{\@bsphack\long\def\StopEventually##1{%
  3831. %    \end{macrocode}
  3832. %    In this case the argument of \verb+\StopEventually+ should be set
  3833. %    and afterwards \TeX{} should stop reading from this file.
  3834. %    Therefore we finish this macro with
  3835. %    \begin{macrocode}
  3836.            ##1\endinput}\@esphack}
  3837. %    \end{macrocode}
  3838. % \end{macro}
  3839. % \end{macro}
  3840. % \end{macro}
  3841. %
  3842. % \begin{macro}{\meta}
  3843. % \changes{v1.4t}{89/04/24}{Macro added.}
  3844. % \begin{macro}{\m@ta}
  3845. % \changes{v1.5w}{90/02/03}{Breaks at space allowed.}
  3846. % \changes{v1.6a}{90/05/24}{Extra space bug corrected.}
  3847. %    The \verb+\meta+ macro is a bit tricky. We want to allow line
  3848. %    breaks at blanks in the argument but we don't want a break
  3849. %    in between. We therefore define \verb+\meta+ in a way that a
  3850. %    \verb*+ + is active when the argument is scanned. Words are then
  3851. %    scanned into \verb+\hbox+es. The active \verb*+ + will end the
  3852. %    preceding \verb+\hbox+ add an ordinary space and open a new
  3853. %    \verb+\hbox+. In this way breaks are only possible at spaces.  It
  3854. %    would be even better to forbid page breaks but this is not
  3855. %    possible in an all cases.
  3856. %    \begin{macrocode}
  3857. \begingroup
  3858. \obeyspaces%
  3859. \catcode`\^^M\active%
  3860. %    \end{macrocode}
  3861. %    We have to be careful to end all lines with a \verb+%+ sign in
  3862. %    this definition.
  3863. %    \begin{macrocode}
  3864. \gdef\meta{\begingroup\obeyspaces\catcode`\^^M\active%
  3865. \let^^M\do@space\let \do@space%
  3866. %    \end{macrocode}
  3867. %    To allow to break up words inside the \verb+\meta+ command we
  3868. %    redefine the \verb+\-+ command. It now has to end the last
  3869. %    open box, add a discretionary and start the next one for the
  3870. %    rest of the current word. See below for more details.
  3871. %
  3872. %    Finally we call \verb+\m@ta+ which
  3873. %    will scan the argument of \verb+\meta+.
  3874. %    \begin{macrocode}
  3875. \def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\it}%
  3876. \m@ta}%
  3877. \endgroup
  3878. %    \end{macrocode}
  3879. %    We start \verb+\m@ta+ by opening an \verb+\hbox+.
  3880. %    Inside this box there will be angle brackets and the argument
  3881. %    typeset in italic typeface. If there are no spaces or \verb+\-+ 
  3882. %    commands in this argument the result will be a single box. But
  3883. %    when a space is encountered (which has \verb+\catcode+ 13) then
  3884. %    it will expand into \verb+\do@space+ which will close the current
  3885. %    box, output a space (so that we have a legitimate break point, and
  3886. %    then opens an new box to catch the rest of the argument.
  3887. % \changes{v1.6d}{90/11/16}{`leavevmode added.}
  3888. %    \begin{macrocode}
  3889. \def\m@ta#1{\leavevmode\hbox\bgroup$\langle$\it#1\/$\rangle$\egroup
  3890. %    \end{macrocode}
  3891. %    Finally, we have to close the group which was started in
  3892. %    \verb+\meta+ 
  3893. %    to restore all our changes.
  3894. %    \begin{macrocode}
  3895.     \endgroup}
  3896. %    \end{macrocode}
  3897. %    The \verb+\do@space+ macro will produce the possible breakpoint
  3898. %    by ending the current box (\verb+\egroup+) and adding the
  3899. %    \verb+\space+ 
  3900. %    into the surrounding paragraph.
  3901. %    \begin{macrocode}
  3902. \def\do@space{\egroup\space
  3903. %    \end{macrocode}
  3904. %    Then we start a new box, switching again to italic to catch the
  3905. %    rest of the argument of \verb+\meta+. But we also have to make sure
  3906. %    that any space following  directly will be ignored. Therefore we
  3907. %    check the following token and discard it as long as it is a token
  3908. %    with the meaning \verb+\do@space+, i.e.\ a $\verb*+ +_{13}$ or a
  3909. %    $\verb+^^M+_{13}$.
  3910. %    \begin{macrocode}
  3911.     \hbox\bgroup\it\futurelet\next\sp@ce}
  3912. \def\sp@ce{\ifx\next\do@space\expandafter\sp@@ce\fi}
  3913. \def\sp@@ce#1{\futurelet\next\sp@ce}
  3914. %    \end{macrocode}
  3915. % \end{macro}
  3916. % \end{macro}
  3917. %
  3918. %
  3919. % \begin{macro}{\IndexInput}
  3920. %    This next macro may be used to read in a separate file (possibly
  3921. %    a style file that is {\em not\/} documented by this means) and
  3922. %    set it verbatim, whilst scanning for macro names and indexing the
  3923. %    latter.  This could be a useful first pass in preparing to
  3924. %    generate documentation for the file read.
  3925. %    \begin{macrocode}
  3926. \def\IndexInput#1{%
  3927. %    \end{macrocode}
  3928. %     We commence by setting up a group, and initializing a
  3929. %    \verb+\trivlist+ as is normally done by a
  3930. %    \verb+\begin{macrocode}+ command.
  3931. %    \begin{macrocode}
  3932.      \begingroup \macro@code
  3933. %    \end{macrocode}
  3934. %    We also make spacing behave as in the {\sf macrocode}
  3935. %    environment, because otherwise all the spaces will be shown
  3936. %    explicitly.
  3937. %    \begin{macrocode}
  3938.    \frenchspacing \@vobeyspaces
  3939. %    \end{macrocode}
  3940. %    Then it only remains to read in the specified file, and finish
  3941. %    off the \verb+\trivlist+.
  3942. % \changes{v1.5t}{89/11/07}{Call `endmacrocode instead of `endtrivlist.}
  3943. %    \begin{macrocode}
  3944.      \input{#1}\endmacrocode
  3945. %    \end{macrocode}
  3946. %    Of course, we need to finish off the group as well.
  3947. %    \begin{macrocode}
  3948.      \endgroup}
  3949. %    \end{macrocode}
  3950. % \end{macro}
  3951. %
  3952. %
  3953. % \begin{macro}{\maketitle}
  3954. %    The macro to generate titles is easily altered in order that it
  3955. %    can be used more than once (an article with many titles).  In the
  3956. %    original, diverse macros were concealed after use with
  3957. %    \verb+\relax+. We must cancel anything that may have been put
  3958. %    into \verb+\@thanks+, etc., otherwise {\em all\/} titles will
  3959. %    carry forward any earlier such setting!
  3960. %  \changes{v1.5j}{89/06/09}{thispagestyle plain removed}
  3961. %    \begin{macrocode}
  3962. \def\maketitle{\par
  3963.       \begingroup \def \thefootnote {\fnsymbol {footnote}}%
  3964.       \setcounter {footnote}\z@
  3965.       \def \@makefnmark {\hbox to \z@{$^{\@thefnmark }$\hss }}%
  3966.       \if@twocolumn \twocolumn [\@maketitle ]%
  3967.       \else \newpage \global \@topnum \z@ \@maketitle \fi
  3968. %    \end{macrocode}
  3969. % \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}}
  3970. %    For special formatting requirements (such as in TUGboat), we use
  3971. %    pagestyle \verb+titlepage+ for this; this is later defined to be
  3972. %    \verb+plain+, unless already defined, as, for example, by
  3973. %    \verb+ltugboat.sty+.
  3974. %    \begin{macrocode}
  3975.        \thispagestyle{titlepage}\@thanks \endgroup
  3976. %    \end{macrocode}
  3977. %    If the driver file documents many files, we don't want parts of a
  3978. %    title of one to propagate to the next, so we have to cancel
  3979. %    these:
  3980. %    \begin{macrocode}
  3981.       \setcounter {footnote}\z@
  3982.       \gdef\@date{\today}\gdef\@thanks{}%
  3983.       \gdef\@author{}\gdef\@title{}}
  3984. %    \end{macrocode}
  3985. % \end{macro}
  3986. %
  3987. %
  3988. % \begin{macro}{\ps@titlepage}
  3989. % \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}}
  3990. %    When a number of articles are concatenated into a journal, for
  3991. %    example, it is not usual for the title pages of such documents to
  3992. %    be formatted differently.  Therefore, a style option such as {\sf
  3993. %    ltugboat} can define this macro in advance.  However, if no such
  3994. %    definition exists, we use pagestyle {\tt plain} for title pages.
  3995. %    \begin{macrocode}
  3996. \@ifundefined{ps@titlepage}
  3997.     {\let\ps@titlepage=\ps@plain}{}
  3998. %    \end{macrocode}
  3999. % \end{macro}
  4000. %
  4001. % \begin{macro}{\MakeShortVerb}
  4002. % \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters
  4003. %                           `dospecials, `@sanitize).} 
  4004. % This arranges an abbreviation for "\verb" such that if you say
  4005. % "\MakeShortVerb{\"\meta{c}"}" subsequently using
  4006. % \meta{c}\meta{text}\meta{c} is equivalent to
  4007. % "\verb"\meta{c}\meta{text}\meta{c}.\footnote{Warning:
  4008. % the commentary in the rest of this section was written by Dave
  4009. % Love.}  In addition, the fact 
  4010. % that \meta{c} is made active is recorded for the benefit of the
  4011. % {\sf verbatim} and {\sf macrocode} environments.
  4012. % Note particularly that the definitions below are global.
  4013. % The first thing we do (it needn't be first) is to record
  4014. % the---presumably new---special character in "\dospecials" and
  4015. % "\@sanitize" using "\add@special".
  4016. %    \begin{macrocode}
  4017. \def\MakeShortVerb#1{%
  4018.   \typeout{*** Made \expandafter\@gobble\string#1\space a short
  4019.            reference for \string\verb \on@line\space ***}%
  4020.   \add@special{#1}%
  4021. %    \end{macrocode}
  4022. % Then the character's current catcode is stored in "\cc\"\meta{c}.
  4023. %    \begin{macrocode}
  4024.   \expandafter
  4025.   \xdef\csname cc\string#1\endcsname{\the\catcode`#1}%
  4026. %    \end{macrocode}
  4027. % The character is spliced into the definition using the same trick as
  4028. % used in "\verb" (for instance), having activated "~" in a group.
  4029. %    \begin{macrocode}
  4030.   \begingroup
  4031.     \catcode`\~\active  \lccode`\~`#1%
  4032.     \lowercase{%
  4033. %    \end{macrocode}
  4034. % The character's old meaning is recorded in "\ac\"\meta{c} prior to
  4035. % assigning it a new one.
  4036. %    \begin{macrocode}
  4037.     \global\expandafter\let
  4038.        \csname ac\string#1\endcsname~%
  4039.     \gdef~{\verb~}}%
  4040.   \endgroup
  4041. %    \end{macrocode}
  4042. % Finally the character is made active.
  4043. %    \begin{macrocode}
  4044.   \global\catcode`#1\active}
  4045. %    \end{macrocode}
  4046. % \end{macro}
  4047. % \begin{macro}{\DeleteShortVerb}
  4048. % \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters
  4049. %                           `dospecials, `@sanitize).}
  4050. % Here's the means of undoing a "\MakeShortVerb", for instance in a
  4051. % region where you need to use the character outside a verbatim
  4052. % environment.  It arranges for "\dospecials" and "\@sanitize" to be
  4053. % altered appropriately, restores the saved catcode and, if necessary,
  4054. % the character's meaning (as stored by 
  4055. % "\MakeShortVerb").  If the catcode wasn't stored in
  4056. % "\cc\"\meta{c} (by "\MakeShortVerb") the command is silently
  4057. % ignored. 
  4058. % \changes{v1.7a}{92/02/28}{Check for previous matched `MakeShortVerb
  4059. %                           to avoid error.}
  4060. %    \begin{macrocode}
  4061. \def\DeleteShortVerb#1{%
  4062.   \expandafter\ifx\csname cc\string#1\endcsname\relax
  4063.   \else
  4064.     \typeout{*** Deleted \expandafter\@gobble\string#1\space as short
  4065.              reference for \string\verb \on@line\space ***}%
  4066.     \rem@special{#1}%
  4067.     \global\catcode`#1\csname cc\string#1\endcsname
  4068.     \ifnum\catcode`#1=\active
  4069.       \begingroup
  4070.         \catcode`\~\active   \lccode`\~`#1%
  4071.         \lowercase{%
  4072.           \global\expandafter\let\expandafter~%
  4073.           \csname ac\string#1\endcsname}%
  4074.       \endgroup \fi \fi}
  4075. %    \end{macrocode}
  4076. % \end{macro}
  4077. % \begin{macro}{\add@special}
  4078. % \changes{v1.7a}{92/02/27}{Added for short verb facility.}
  4079. % This helper macro adds its argument to the
  4080. % "\dospecials" macro which is conventionally used by verbatim macros
  4081. % to alter the catcodes of the currently active characters.  We need
  4082. % to add "\do\"\meta{c} to the expansion of "\dospecials" after
  4083. % removing the character if it was already there to avoid multiple
  4084. % copies building up should "\MakeShortVerb" not be balanced by
  4085. % "\DeleteShortVerb" (in case anything that uses "\dospecials" cares
  4086. % about repetitions).
  4087. %    \begin{macrocode}
  4088. \def\add@special#1{%
  4089.   \rem@special{#1}%
  4090.   \expandafter\gdef\expandafter\dospecials\expandafter
  4091.     {\dospecials \do #1}%
  4092. %    \end{macrocode}
  4093. % Similarly we have to add "\@makeother\"\meta{c} to "\@sanitize"
  4094. % (which is used in things like "\index" to re-catcode all special
  4095. % characters except braces).
  4096. %    \begin{macrocode}
  4097.   \expandafter\gdef\expandafter\@sanitize\expandafter
  4098.     {\@sanitize \@makeother #1}}
  4099. %    \end{macrocode}
  4100. % \end{macro}
  4101. % \begin{macro}{\rem@special}
  4102. % \changes{v1.7a}{92/02/27}{Added for short verb facility.}
  4103. % The inverse of "\add@special" is slightly trickier.  "\do" is
  4104. % re-defined to expand to nothing if its argument is the character of
  4105. % interest, otherwise to expand simply to the argument.  We can then
  4106. % re-define "\dospecials" to be the expansion of itself.  The space
  4107. % after "=`##1" prevents an expansion to "\relax"!
  4108. %    \begin{macrocode}
  4109. \def\rem@special#1{%
  4110.   \def\do##1{%
  4111.     \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}%
  4112.   \xdef\dospecials{\dospecials}%
  4113. %    \end{macrocode}
  4114. % Fixing "\@sanitize" is the same except that we need to re-define
  4115. % "\@makeother" which obviously needs to be done in a group. 
  4116. %    \begin{macrocode}
  4117.   \begingroup
  4118.     \def\@makeother##1{%
  4119.       \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}%
  4120.     \xdef\@sanitize{\@sanitize}%
  4121.   \endgroup}
  4122. %    \end{macrocode}
  4123. % \end{macro}
  4124. % \begin{macro}{\MakeShortverb}
  4125. % \begin{macro}{\DeleteShortverb}
  4126. % \changes{v1.7a}{92/02/27}{Added (from newdoc).}
  4127. % These commands from {\sf newdoc} are now obsolete.
  4128. %    \begin{macrocode}
  4129. \def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb
  4130.                          syntax, this is obsolete ***}\MakeShortVerb}
  4131. \def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb
  4132.                          syntax, this is obsolete ***}\DeleteShortVerb}
  4133. %    \end{macrocode}
  4134. % \end{macro}
  4135. % \end{macro}
  4136. %
  4137. %
  4138. %
  4139. % \subsection[Providing a checksum and character table]
  4140. %        {Providing a checksum and character table\footnotemark}
  4141. %        \footnotetext{Warning: the commentary in this section was
  4142. %                      written by Dave Love. }
  4143. %
  4144. % 
  4145. % \begin{macro}{\init@checksum}
  4146. % The checksum mechanism works by counting backslashes in the
  4147. % macrocode.  This initialises the count (when called from
  4148. % "\StopEventually"). 
  4149. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4150. %    \begin{macrocode}
  4151. \def\init@checksum{\relax
  4152.     \global\bslash@cnt\z@}
  4153. %    \end{macrocode}
  4154. % \end{macro}
  4155. %
  4156. %
  4157. % \begin{macro}{\check@checksum}
  4158. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4159. % This reports the sum compared with the value ("\bslash@cnt") the
  4160. % file advertises.  It's called from "\Finale" (if that hasn't been
  4161. % re-defined). 
  4162. %    \begin{macrocode}
  4163. \def\check@checksum{\relax
  4164.      \ifnum\check@sum=\z@
  4165.        \typeout{**********************************}%
  4166.        \typeout{* This macro file has no checksum!}%
  4167.        \typeout{* The checksum should be \the\bslash@cnt!}%
  4168.        \typeout{**********************************}%
  4169.      \else
  4170.        \ifnum\check@sum=\bslash@cnt
  4171.          \typeout{*******************}%
  4172.          \typeout{* Checksum passed *}%
  4173.          \typeout{*******************}%
  4174.        \else
  4175.          \errhelp\wrong@checksum
  4176.          \errmessage{Checksum not passed 
  4177.                     (\the\check@sum<>\the\bslash@cnt)}%
  4178.         \fi
  4179.      \fi
  4180.      \global\check@sum\z@}
  4181. %    \end{macrocode}
  4182. % \end{macro}
  4183. %
  4184. %
  4185. % \begin{macro}{\check@sum}
  4186. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4187. % \begin{macro}{\bslash@cnt}
  4188. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4189. % \begin{macro}{\wrong@checksum}
  4190. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4191. % We need to define the counter for the number of backslashes counted
  4192. % ("\bslash@cnt") and the value advertised by the file ("\check@sum")
  4193. % as well as a help message for when things go wrong.
  4194. %    \begin{macrocode}
  4195. \newcount\check@sum           \check@sum  = \z@
  4196. \newcount\bslash@cnt          \bslash@cnt = \z@
  4197. \newhelp\wrong@checksum
  4198.    {The currently documented file seems to be wrong.^^J%
  4199.     Try to get a correct version.}%
  4200. %    \end{macrocode}
  4201. % \end{macro}
  4202. % \end{macro}
  4203. % \end{macro}
  4204. %
  4205. %
  4206. % \begin{macro}{\CheckSum}
  4207. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4208. % This is the interface to setting "\check@sum".
  4209. %    \begin{macrocode}
  4210. \def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack}
  4211. %    \end{macrocode}
  4212. % \end{macro}
  4213. %
  4214. %
  4215. %
  4216. % \begin{macro}{\step@checksum}
  4217. % \changes{v1.5k}{89/09/04}{Macro added to support checksum.}
  4218. % This advances the count when a backslash is encountered in the
  4219. % macrocode. 
  4220. %    \begin{macrocode}
  4221. \def\step@checksum{\global\advance\bslash@cnt\@ne}
  4222. %    \end{macrocode}
  4223. % \end{macro}
  4224. %
  4225. % \begin{macro}{\CharacterTable}
  4226. %    The user interface to the character table-checking does some
  4227. %    "\catcode"ing and then compares the following table with the
  4228. %    stored version. We need to have "@" of type ``other'' within the
  4229. %    table since this is the way it is usually returned when reading
  4230. %    in a normal document. To nevertheless have a private letter we
  4231. %    use "~" for this purpose. "~" does no harm as a ``letter'' as it
  4232. %    comes last in the table and therefore will not gobble following
  4233. %    space.
  4234. % \changes{v1.5m}{89/09/20}{Macro added to check character translation
  4235. %                           problems.}
  4236. % \changes{v1.5q}{89/11/01}{Made character table more readable.}
  4237. % \changes{v1.5t}{89/11/07}{Make \string\~{} letter in chartable
  4238. %                           macros.} 
  4239. % \changes{v1.5u}{89/11/14}{Made @ other in default table.}
  4240. %    \begin{macrocode}
  4241. \def\CharacterTable{\begingroup \CharTableChanges \character@table}
  4242. %    \end{macrocode}
  4243. % \end{macro}
  4244. % \def\MakePrivateLetters{\catcode`\~=11\makeatletter}
  4245. % \begin{macro}{\character@table}
  4246. % This does the work of comparing the tables and reporting the result.
  4247. % Note that the following code is enclosed in a group
  4248. % with "~" catcoded to letter.
  4249. %    \begin{macrocode}
  4250. \begingroup
  4251.   \catcode`\~=11
  4252.   \gdef\character@table#1{\def\used~table{#1}%
  4253.       \ifx\used~table\default~table
  4254.            \typeout{***************************}%
  4255.            \typeout{* Character table correct *}%
  4256.            \typeout{***************************}%
  4257.       \else
  4258.          \errhelp\wrong@table
  4259.          \errmessage{Character table corrupted}%
  4260.          \show\default~table
  4261.          \show\used~table
  4262.       \fi
  4263.       \endgroup}
  4264. %    \end{macrocode}
  4265. % \end{macro}
  4266. %
  4267. % \begin{macro}{\CharTableChanges}
  4268. %    When the character table is read in we need to scan it with a
  4269. %    fixed set of "\catcode"s. The reference table below  was defined by
  4270. %    assuming the normal "\catcode"s of \TeX{}, i.e.\ "@" is of type
  4271. %    other and the only token of type ``letter'' are the usual letters
  4272. %    of the alphabet. If, for some reason, other characters are made
  4273. %    ``letters'' then their "\catcode"s need to be restored before
  4274. %    checking the table. Otherwise spaces in the table are gobbled and
  4275. %    we get the information that the tables are different, even if
  4276. %    they are actually equal. For this reason "\CharTableChanges" can
  4277. %    be set up to locally restore the "\catcode"s of such ``letters''
  4278. %    to ``other''.
  4279. %    \begin{macrocode}
  4280.   \global\let\CharTableChanges\@empty
  4281. %    \end{macrocode}
  4282. % \end{macro}
  4283. %
  4284. % \begin{macro}{\default~table}
  4285. % Here's what the table {\em should\/} look like (modulo spaces).
  4286. %    \begin{macrocode}
  4287.   \makeatother
  4288.   \gdef\default~table
  4289.      {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
  4290.       Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
  4291.       Digits        \0\1\2\3\4\5\6\7\8\9
  4292.       Exclamation   \!     Double quote  \"     Hash (number) \#
  4293.       Dollar        \$     Percent       \%     Ampersand     \&
  4294.       Acute accent  \'     Left paren    \(     Right paren   \)
  4295.       Asterisk      \*     Plus          \+     Comma         \,
  4296.       Minus         \-     Point         \.     Solidus       \/
  4297.       Colon         \:     Semicolon     \;     Less than     \<
  4298.       Equals        \=     Greater than  \>     Question mark \?
  4299.       Commercial at \@     Left bracket  \[     Backslash     \\
  4300.       Right bracket \]     Circumflex    \^     Underscore    \_
  4301.       Grave accent  \`     Left brace    \{     Vertical bar  \|
  4302.       Right brace   \}     Tilde         \~}
  4303. \endgroup
  4304. %    \end{macrocode}
  4305. % \end{macro}
  4306. % \let\MakePrivateLetters=\makeatletter
  4307. % 
  4308. % \begin{macro}{\wrong@table}
  4309. % \changes{v1.7a}{92/02/28}{Moved to where the catcodes are right so it
  4310. %                           works.} 
  4311. % We need a help message in case of problems.
  4312. %    \begin{macrocode}
  4313.   \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J
  4314.             I now \string\show\space you both tables for comparison.}
  4315. %    \end{macrocode}
  4316. % \end{macro}
  4317. %
  4318. %
  4319. % \subsection[Attaching line numbers to code lines]
  4320. %            {Attaching line numbers to code lines\footnotemark}
  4321. %            \footnotetext{Warning: the commentary was written by Dave
  4322. %            Love.}
  4323. %
  4324. %
  4325. % The code in this section allows index entries to refer to code line
  4326. % numbers---the number of the first line of macrocode in the {\sf macro}
  4327. % environment. 
  4328. % 
  4329. % 
  4330. % \begin{macro}{\codeline@index}
  4331. % Indexing by code line is controlled by the "codeline@index" switch.
  4332. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)}
  4333. % \changes{v1.7a}{92/02/24}{Documented code line no. support.}
  4334. %    \begin{macrocode}
  4335. \newif\ifcodeline@index \codeline@indexfalse
  4336. %    \end{macrocode}
  4337. % \end{macro}
  4338. % \begin{macro}{\codeline@wrindex}
  4339. %    The code index entries are written out by "\special@index".  If
  4340. %    indexing is by code line this is "\let" to "\codeline@wrindex";
  4341. %    if indexing is by page it is just "\index".  However, if
  4342. %    "\nofiles" is given, we omit writing such an index entry at all.
  4343. % \changes{v1.7j}{92/08/14}{Added `if@filesw.}
  4344. %    \begin{macrocode}
  4345. \def\codeline@wrindex#1{\if@filesw
  4346.         \immediate\write\@indexfile
  4347.             {\string\indexentry{#1}%
  4348.             {\number\c@CodelineNo}}\fi}
  4349. %    \end{macrocode}
  4350. % \end{macro}
  4351. % \begin{macro}{\special@index}
  4352. % By default no index entries are written out.
  4353. %    \begin{macrocode}
  4354. \let\special@index = \@gobble
  4355. %    \end{macrocode}
  4356. % \end{macro}
  4357. % \begin{macro}{\CodelineIndex}
  4358. % \changes{v1.5u}{89/11/14}{Added `PageIndex and `CodelineIndex (Undoc)}
  4359. % This switches on use of the index file with "\makeindex", sets the
  4360. % switch to indicate code line numbering and defines "\special@index"
  4361. % appropriately. 
  4362. %    \begin{macrocode}
  4363. \def\CodelineIndex{\makeindex 
  4364.                    \codeline@indextrue
  4365.                    \let\special@index\codeline@wrindex}
  4366. %    \end{macrocode}
  4367. % \end{macro}
  4368. % \begin{macro}{\PageIndex}
  4369. % "\PageIndex" is similar.
  4370. %    \begin{macrocode}
  4371. \def\PageIndex{\makeindex 
  4372.                \codeline@indexfalse
  4373.                \let\special@index\index}
  4374. %    \end{macrocode}
  4375. % \end{macro}
  4376. %
  4377. %
  4378. % \begin{macro}{\c@CodelineNo}
  4379. % \changes{v1.5l}{89/09/10}{Counter added to support code line numbers.}
  4380. % \changes{v1.5y}{90/02/24}{Default changed.}
  4381. % \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to
  4382. %                           avoid unnecessary fontwarning.}
  4383. % We need a counter to keep track of the line number.
  4384. %    \begin{macrocode}
  4385. \newcount\c@CodelineNo  \c@CodelineNo\z@
  4386. %    \end{macrocode}
  4387. % \end{macro}
  4388. % \begin{macro}{\theCodelineNo}
  4389. % \changes{v1.7a}{92/02/25}{Existing definition not overwritten.}
  4390. % \changes{v1.7a}{92/03/12}{Use `reset@font for NFSS.}
  4391. % This provides a hook to control the format of line numbers which may
  4392. % be defined in a style file.
  4393. %    \begin{macrocode}
  4394. \@ifundefined{theCodelineNo}
  4395.   {\ifx\selectfont\undefined
  4396.      \def\theCodelineNo{\rm\scriptsize\arabic{CodelineNo}}%
  4397.    \else
  4398.      \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}%
  4399.    \fi}
  4400.   {} 
  4401. %    \end{macrocode}
  4402. % \end{macro}
  4403. %
  4404. %
  4405. %
  4406. %
  4407. % \subsection{Layout Parameters for documenting style files}
  4408. %
  4409. % \begin{macro}{\tolerance}
  4410. %    People documenting style files would probably rather have things
  4411. %    ``sticking out'' in overfull \verb+\hbox+es and poorish spacing,
  4412. %    because they probably don't want to spend a lot of time on making
  4413. %    all the line breaks perfect!
  4414. %    \begin{macrocode}
  4415.        \tolerance=1000\relax
  4416. %    \end{macrocode}
  4417. % \end{macro}
  4418. %
  4419. % \DeleteShortVerb{\"}
  4420. %
  4421. % The following \verb+\mathcode+ definitions allow the characters
  4422. % `\verb+\+'
  4423. % and `{\tt @}' to appear in \verb+\tt+ font when invoked in math 
  4424. % mode;\footnote{You may wonder why the definitions state that both
  4425. %                characters belong to the {\em variable family\/}
  4426. %                (i.e.\ the number 7 in front). The reason is this:
  4427. %                Originally the {\tt\bslash mathcode} of
  4428. %                {\tt\bslash} was defined to be {\tt "075C},
  4429. %                i.e.\ ordinary character number 92 (hex 5C) in
  4430. %                math family number 7 which is the typewriter family in
  4431. %                standard \LaTeX.
  4432. %                But this file should not depend on this specific
  4433. %                setting, so I changed these {\tt\bslash mathcode}$\,$s
  4434. %                to work with any family assignments. For an example
  4435. %                see the article about the new font selection scheme.}
  4436. % particularly for something like $\verb+\@abc+=1$.
  4437. %
  4438. % If an {\em old\/} version of the {\sf german} style option is in
  4439. % force, then the `\verb+"+' character is active and would upset the
  4440. % definition of the \meta{16-bit number} quantities below, therefore
  4441. % we change the \verb+\catcode+ of \verb+"+ inside a group, and use
  4442. % \verb+\global+.
  4443. %    \begin{macrocode}
  4444. { \catcode`\"=12
  4445.   \global\mathcode`\\="705C \global\mathcode`\@="7040 }
  4446. %    \end{macrocode}
  4447. % \MakeShortVerb{\"}
  4448. %
  4449. % \begin{macro}{\DocstyleParms}
  4450. %    This macro can be used, for example, to assign new values to
  4451. %    \verb+\MacrocodeTopsep+ and \verb+\MacroIndent+ and some other
  4452. %    internal registers.  If it is already defined, the default
  4453. %    definition won't be carried out. Note that it is necessary to
  4454. %    assign new values via this macro if it should be done in a style
  4455. %    file (like {\tt ltugboat.sty} for example) since the registers are
  4456. %    undefined before {\tt doc.sty} is read in.  The default values
  4457. %    for the internal registers are scattered over this file.
  4458. % \changes{v1.5u}{89/11/14}{`DocStyleParms now empty}
  4459. %    \begin{macrocode}
  4460. \@ifundefined{DocstyleParms}{}{}
  4461. %    \end{macrocode}
  4462. %    Now we allow overwriting the values by calling
  4463. %    \verb+\DocstyleParms+.
  4464. %    \begin{macrocode}
  4465. \DocstyleParms     \let\DocstyleParms\relax
  4466. %    \end{macrocode}
  4467. % \end{macro}
  4468. %
  4469. %
  4470. %
  4471. % \begin{macro}{\AmSTeX}
  4472. %   \changes{v1.5j}{89/06/09}{Macro AmsTeX renamed to AmSTeX}
  4473. % \begin{macro}{\BibTeX}
  4474. % \begin{macro}{\SliTeX}
  4475. %    Here are a few definitions which can usefully be employed when
  4476. %    documenting style files: now we can readily refer to \AmSTeX,
  4477. %    \BibTeX\ and \SliTeX, as well as the usual \TeX\ and \LaTeX.
  4478. %    \begin{macrocode}
  4479. \@ifundefined{AmSTeX}
  4480.    {\def\AmSTeX{\leavevmode\hbox{$\cal A\kern-.2em\lower.376ex%
  4481.         \hbox{$\cal M$}\kern-.2em\cal S$-\TeX}}}{}
  4482. \@ifundefined{BibTeX}
  4483.    {\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em%
  4484.     T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{}
  4485. \@ifundefined{SliTeX}
  4486.    {\def\SliTeX{{\rm S\kern-.06emL\kern-.18em\raise.32ex\hbox
  4487.                 {\sc i}\kern -.03em\TeX}}}{}
  4488. %    \end{macrocode}
  4489. % \end{macro}
  4490. % \end{macro}
  4491. % \end{macro}
  4492. % \begin{macro}{\PlainTeX}
  4493. % \changes{v1.5g}{89/05/07}{space between plain and TeX changed.}
  4494. % \begin{macro}{\Web}
  4495. %     There's even a \PlainTeX{} and a \Web.
  4496. %    \begin{macrocode}
  4497. \@ifundefined{PlainTeX}{\def\PlainTeX{{\sc Plain}\kern2pt\TeX}}{}
  4498. \@ifundefined{Web}{\def\Web{{\sc Web}}}{}
  4499. %    \end{macrocode}
  4500. % \end{macro}
  4501. % \end{macro}
  4502. %
  4503. %
  4504. % \subsection{Changing the {\tt\protect\bslash catcode} of \%}
  4505. %
  4506. % \begin{macro}{\MakePercentIgnore}
  4507. % \begin{macro}{\MakePercentComment}
  4508. %    And finally the most important bit: we change the \verb+\catcode+
  4509. %    of `\verb+%+' so that it is ignored (which is how we are able to
  4510. %    produce this document!). We provide two commands to do the actual
  4511. %    switching.
  4512. %^^A The \verb+\MakePercentIgnore+ is then called as the
  4513. %^^A last command in this file.
  4514. %    \begin{macrocode}
  4515. \def\MakePercentIgnore{\catcode`\%9\relax}
  4516. \def\MakePercentComment{\catcode`\%14\relax}
  4517. %    \end{macrocode}
  4518. % \end{macro}
  4519. % \end{macro}
  4520. %
  4521. % \begin{macro}{\DocInput}
  4522. %    The two macros above are now used to define the
  4523. %    \verb+\DocInput+ macro which was introduced in version v1.5l
  4524. %    (or so) of
  4525. %    the {\tt doc} style option. In older versions
  4526. %    \verb+\MakePercentIgnore+ was placed at the very end of {\tt
  4527. %    doc.sty}.
  4528. %    \begin{macrocode}
  4529. \def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
  4530. %    \end{macrocode}
  4531. % \end{macro}
  4532. % We can now finish the {\tt docstrip} main module.
  4533. %    \begin{macrocode}
  4534. %</style>
  4535. %    \end{macrocode}
  4536. %
  4537. %
  4538. %  \begin{macro}{\on@line}
  4539. %    Finally something for people with an old \LaTeX:
  4540. % \changes{v1.7k}{92/08/24}{Macro and test added.}
  4541. %    \begin{macrocode}
  4542. \ifx\on@line\undefined
  4543.   \def\on@line{ on input line \the\inputlineno}
  4544.   \errhelp{Support for input line numbers has been added
  4545.            to latex.tex <dec91>.^^J^^J%
  4546.            Please update to a newer LaTeX release.}
  4547.   \errmessage{Obsolete LaTeX release (older than Dec.91)}
  4548. \fi
  4549. %    \end{macrocode}
  4550. %  \end{macro}
  4551. %
  4552. % \Finale
  4553. % \PrintIndex \PrintChanges
  4554. \endinput
  4555.