From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex-dev/base/doc.dtx | 4941 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4941 insertions(+) create mode 100644 macros/latex-dev/base/doc.dtx (limited to 'macros/latex-dev/base/doc.dtx') diff --git a/macros/latex-dev/base/doc.dtx b/macros/latex-dev/base/doc.dtx new file mode 100644 index 0000000000..aad1551543 --- /dev/null +++ b/macros/latex-dev/base/doc.dtx @@ -0,0 +1,4941 @@ +% \iffalse meta-comment +% +% Copyright 1993-2018 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% It may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% https://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% ^^A -*-LaTeX-*- +% +% ^^A These shouldn't come out in .ist files, hence the module +% ^^A comments, or in the printed version, hence temporary comment +% ^^A category for `<' +%\catcode`\<=14 +%<+package|shortvrb>\NeedsTeXFormat{LaTeX2e}[1994/12/01] +%<+package> \ProvidesPackage{doc} +%<+shortvrb>\ProvidesPackage{shortvrb} +%<+package|shortvrb> [2018/09/25 v2.1i +%<+package|shortvrb> Standard LaTeX documentation package (FMi)] +%\catcode`\<=12 +% +%% +%\iffalse This is a METACOMMENT +% Everything up to the next `\ fi' (without a blank) will +% be ignored. This is necessary because `%' may no longer +% be a comment mark when this file is read in. +% +% +%% Package `doc' to use with LaTeX 2e +%% Copyright (C) 1989-1999 Frank Mittelbach, all rights reserved. +% +% +% Version: Date: Changes: +% +% 1.0a 5.5.88 This is nothing but a collection of tests and +% hacks. It is certainly going to be greatly +% changed. +% Better not to use it! +% 1.5a and earlier... are not longer recorded +% 1.5b and higher... are documented with the (undocumented) \changes +% feature. +%\fi +% \changes{v1.5f}{1989/04/29}{Thanks to Brian who documented the +% \cs{changes} macro feature.} +% \changes{v1.5g}{1989/05/07}{MacroTopsep now called MacrocodeTopsep and +% new MacroTopsep added} +% \changes{v1.5h}{1989/05/17}{All lines shortened to <72 characters} +% \changes{v1.5j}{1989/06/09}{Corrections by Ron Whitney added} +% \changes{v1.5q}{1989/11/03}{`\ldots{}Listing macros renamed to +% `\ldots{}Input. Suggested by R. Wonneberger} +% \changes{v1.5w}{1990/02/05}{Counter codelineno renamed to CodelineNo} +% \changes{v1.9a}{1993/12/02}{Upgrade for LaTeX2e} +% \changes{v1.9d}{1993/12/20}{Protected changes entry.} +% \changes{v1.0p}{1994/05/21}{Use new error commands} +% +% +% \hyphenation{make-index} +% +% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty} +% \DoNotIndex{\@flushglue,\@gobble,\@input} +% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle} +% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa} +% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue} +% \DoNotIndex{\@thanks,\@thefnmark,\@topnum} +% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin} +% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces} +% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup} +% \DoNotIndex{\mathcal,\csname,\def,\documentstyle,\dospecials,\edef} +% \DoNotIndex{\egroup} +% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist} +% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global} +% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn} +% \DoNotIndex{\ifcase} +% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item} +% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower} +% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing} +% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc} +% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut} +% \DoNotIndex{\strutbox} +% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt} +% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@} +% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim} +% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary} +% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle} +% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode} +% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip} +% \DoNotIndex{\nopagebreak} +% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle} +% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb} +% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar} +% \DoNotIndex{\[,\{,\},\]} +% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode} +% \DoNotIndex{\baselineskip,\begin,\tw@} +% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q} +% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H} +% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z} +% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0} +% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_} +% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother} +% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment} +% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined} +% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc} +% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar} +% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode} +% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting} +% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf} +% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse} +% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault} +% \DoNotIndex{\bfdefault} +% +% \MakeShortVerb{\"} +% \setcounter{StandardModuleDepth}{1} +% +% {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print +% \gdef\dimenvalue#1pt{$#1$pt}} ^^A a register value with a - sign +% +% \newcommand{\DOC}{\texttt{doc}} +% +% \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}} +% \GetFileInfo{doc.sty} +% +% \CheckSum{2206} ^^A % keep the checksum in this file +% +% \title{The \DOC{} and \texttt{shortvrb} Packages\thanks +% {This file has version number \fileversion{} dated \filedate{}.}} +% \author{Frank Mittelbach\thanks{Further commentary added at Royal +% Military College of Science by B. Hamilton Kelly; English +% translation of parts of the original German commentary +% provided by Andrew Mills; fairly substantial additions, +% particularly from \texttt{newdoc}, and +% documentation of post-v1.5q features added at v1.7a by Dave +% Love (SERC Daresbury Lab). Extraction of \texttt{shortvrb} +% package added by Joachim Schrod (TU~Darmstadt).}} +% +% \MaintainedByLaTeXTeam{latex} +% \maketitle +% +% \begin{abstract} +% This package contains the definitions that are necessary to +% format the documentation of package files. The package was +% developed in Mainz in cooperation with the Royal Military College +% of Science. This is an update which documents various changes +% and new features in \DOC{} and integrates the features of +% \textsf{newdoc}. +% \end{abstract} +% +% \newif\ifmulticols +% \IfFileExists{multicol.sty}{\multicolstrue}{} +% +% \ifmulticols +% \addtocontents{toc}{\protect\begin{multicols}{2}} +% \fi +% +% {\parskip 0pt ^^A We have to reset \parskip +% ^^A (bug in \LaTeX) +% \tableofcontents +% } +% +% \changes{v1.7a}{1992/02/25}{Miscellaneous small changes to the text} +% +% \ifmulticols +% \begin{multicols}{2}[\section*{Preface to version 1.7}] +% \else \section*{Preface to version 1.7} \fi +% +% This version of \texttt{doc.dtx} documents changes which have occurred +% since the last published version \cite{art:doc} but which have been +% present in distributed versions of \texttt{doc.sty} for some time. It +% also integrates the (undocumented) features of the distributed +% \texttt{newdoc.sty}. +% +% The following changes and additions have been made to the user +% interface since the published version~\cite{art:doc}. See +% \S\ref{sec:interface} for more details. +% \begin{description} +% \item[Driver mechanism] "\DocInput" is now used in the driver file +% to input possibly multiple independent \DOC{} files and \DOC{} no +% longer has to be the last package. "\IndexListing" is replaced +% by "\IndexInput"; +% \item[Indexing] is controlled by "\PageIndex" and "\CodelineIndex", +% one of which must be specified to produce an index---there is no +% longer a "\makeindex" in the default "\DocstyleParms"; +% \item[The \texttt{macro} environment] now takes as argument the +% macro name {\em with\/} the backslash; +% \item[Verbatim text] Newlines are now forbidden inside "\verb" and +% commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for +% verbatim shorthand; +% \item[\texttt{\bslash par}] can now be used in "\DoNotIndex"; +% \item[Checksum/character table support] for ensuring the integrity +% of distributions is added; +% \item[\texttt{\bslash printindex}] becomes "\PrintIndex"; +% \item[\texttt{multicol.sty}] is no longer necessary to use \DOC{} or +% print the documentation (although it is recommended); +% \item[`Docstrip' modules] are recognised and formatted specially. +% \end{description} +% +% As well as adding some completely new stuff, +% the opportunity has been taken to add some commentary to the code +% formerly in \texttt{newdoc.sty} and that added after version 1.5k of +% \texttt{doc.sty}. Since (as noted in the sections concerned) this +% commentary wasn't written by Frank Mittelbach but the code was, it is +% probably {\em not\/} true in this case that ``if the code and +% comments disagree both are probably wrong''! +% +% \subsection*{Bugs} +% +% There are some known bugs in this version: +% \begin{itemize} +% \item The "\DoNotIndex" command doesn't work for some single +% character commands most noticeable "\%". +% \item The `General changes' glossary entry would come out after +% macro names with a leading "!" and possibly a leading |"|; +% \item If you have an old version of \textsf{makeindex} long "\changes" +% entries will come out strangely and you may find the section +% header amalgamated with the first changes entry. Try to get an +% up-to-date one (see p.~\pageref{makeindex:version}); +% \item Because the accompanying \textsf{makeindex} style files support +% the inconsistent attribute specifications of older and newer +% versions \textsf{makeindex} always complains about three `unknown +% specifier's when sorting the index and changes entries. +% \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with +% single character arguments, e.g., "{|}" instead of "{\|}" chaos +% may happen. +% \end{itemize} +% (Some `features' are documented below.) +% +% \subsection*{Wish list} +% +% \begin{itemize} +% \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write +% out to a special file information about the package's `exported' +% definitions which they describe. This could subsequently be +% included in the \texttt{docstrip}ped \texttt{.sty} file in a +% suitable form for use by smart editors in command completion, +% spelling checking etc., based on the packages used in a document. +% This would need agreement on a `suitable form'. \item Indexing of +% the modules used in \texttt{docstrip}'s "%<" directives. I'm not +% sure how to index directives containing module combinations; \item +% Writing out bibliographic information about the package; \item Allow +% turning off use of the special font for, say, the next guarded +% block. +% \end{itemize} +% +% \ifmulticols +% \end{multicols} +% +% \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt} +% \section{Introduction}] +% \else +% \section{Introduction} +% \fi +% +% The \TeX{} macros which are described here allow definitions and +% documentation to be held in one and the same file. This has the +% advantage that normally very complicated instructions are made +% simpler to understand by comments inside the definition. In addition +% to this, updates are easier and only one source file needs to be +% changed. On the other hand, because of this, the package files are +% considerably longer: thus \TeX{} takes longer to load them. If this +% is a problem, there is an easy remedy: one needs only to run the +% \texttt{docstrip.tex} program that removes nearly all lines that begin +% with a +% percent sign. +% +% The idea of integrated documentation was born with the development +% of the \TeX{} program; it was crystallized in Pascal with the \Web{} +% system. The advantages of this method are plain to see (it's easy +% to make comparisons \cite{art:Knuthliterat}). Since this +% development, systems similar to \Web{} have been developed for other +% programming languages. But for one of the most complicated +% programming languages (\TeX) the documentation has however been +% neglected. The \TeX{} world seems to be divided between:--- +% \begin{itemize} \item a couple of ``wizards'', who produce many +% lines of completely unreadable code ``off the cuff'', and \item many +% users who are amazed that it works just how they want it to do. Or +% rather, who despair that certain macros refuse to do what is +% expected of them.\end{itemize} +% +% I do not think that the \Web{} system is {\em the\/} reference work; +% on the contrary, it is a prototype which suffices for the +% development of programs within the \TeX{} world. It is sufficient, +% but not totally sufficient.\footnote{I know that this will be seen +% differently by a few people, but this product should not be seen as +% the finished product, at least as far as applications concerning +% \TeX{} are concerned. The long-standing debate over `multiple +% change files' shows this well.} As a result of \Web, new programming +% perspectives have been demonstrated; unfortunately, though, they +% haven't been developed further for other programming languages. +% +% The method of documentation of \TeX{} macros which I have introduced +% here should also only be taken as a first sketch. It is designed +% explicitly to run under \LaTeX{} alone. Not because I was of the +% opinion that this was the best starting point, but because from this +% starting point it was the quickest to develop.\footnote{This +% argument is a bad one, however, it is all too often trotted out.} As +% a result of this design decision, I had to move away from the +% concept of modularization; this was certainly a step backward. +% +% I would be happy if this article could spark off discussion over +% \TeX\ documentation. I can only advise anyone who thinks that they +% can cope without documentation to ``Stop Time'' until he or she +% completely understands the \AmSTeX{} source code. +% +% +% +% +% +% \subsection{Using the \DOC{} package} +% +% Just like any other package, invoke it by requesting it with a +% |\usepackage| command in the preamble. \textsf{Doc}'s use of +% |\reversemarginpars| may make it incompatible with some classes. +% \changes{v1.7a}{1992/02/25}{Altered usage info} +% +% +% \ifmulticols\end{multicols}\fi +% +% +% \section{The User Interface}\label{sec:interface} +% \subsection{The driver file} +% +% If one is going to document a set of macros with the \DOC{} +% package one has to prepare a special driver file which produces the +% formatted document. This driver file has the following +% characteristics: +% +% \noindent |\documentclass[|\meta{options}]^^A +% |{|\meta{document-class}|}|\\[1pt] +% |\usepackage{doc}|\\[3pt] +% \hspace*{10pt}\meta{preamble}\\[3pt] +% |\begin{document}|\\[3pt] +% \hspace*{10pt}\meta{special input commands}\\[3pt] +% |\end{document}| +% +% The \meta{document-class} might be any document class, I normally +% use \texttt{article}. +% +% In the \meta{preamble} one should place declarations which +% manipulate the behavior of the \DOC{} package like +% |\DisableCrossrefs| or |\OnlyDescription|. +% +% \DescribeMacro\DocInput \DescribeMacro\IndexInput +% Finally the \meta{special input commands} part should contain one or +% more |\DocInput|\meta{file name} and/or +% |\IndexInput|\meta{file name} commands. The +% |\DocInput| command is used for files prepared for the +% \DOC{} package whereas |\IndexInput| can be used for all kinds of +% macro files. See page \pageref{..Input} for more details of +% "\IndexInput". Multiple "\DocInput"s can be used with a +% number of included files which are each self-contained +% self-documenting packages---for instance, each containing +% "\maketitle". +% +% As an example, the driver file for the \DOC{} package itself is +% the following text surrounded by "%<*driver>" and "%". +% To produce the documentation you can simply run the \texttt{.dtx} +% file through \LaTeX{} in which case this code will be executed +% (loading the document class \texttt{ltxdoc}, etc.) or you can +% extract this into a separate file by using +% the \texttt{docstrip} program. +% The line numbers below are added by +% \DOC{}'s formatting. +% Note that the class \textsf{ltxdoc} has the \DOC{} package +% preloaded. +% \changes{v1.7a}{1992/03/06}{Added +% docstrip-derivable driver file as example.} +% \changes{v1.7c}{1992/04/01}{Expurgated ltugboat.sty from driver.} +% \begin{macrocode} +%<*driver> +\documentclass{ltxdoc} +\EnableCrossrefs + %\DisableCrossrefs % Say \DisableCrossrefs if index is ready +\CodelineIndex +\RecordChanges % Gather update information + %\OnlyDescription % comment out for implementation details + %\OldMakeindex % use if your MakeIndex is pre-v2.9 +\setlength\hfuzz{15pt} % dont make so many +\hbadness=7000 % over and under full box warnings +\begin{document} + \DocInput{doc.dtx} +\end{document} +% +% \end{macrocode} +% +% +% \subsection{General conventions} +% +% A \TeX{} file prepared to be used with the `doc' package +% consists of `documentation parts' intermixed with `definition +% parts'. +% +% Every line of a `documentation part' starts with a percent sign +% (|%|) in column one. It may contain arbitrary \TeX{} or +% \LaTeX{} commands except that the character `|%|' cannot be +% used as a comment character. +% \SortIndex{\string^\string^A}{\string\verb\verbatimchar +% \string^\string^A\verbatimchar \encapchar usage} To allow user +% comments, the |^^A| character is defined as a comment character +% later on. Such `metacomments' may be also be included simply by +% surrounding them with "\iffalse" \ldots~"\fi". +% +% All other parts of the file are called `definition parts'. They +% contain fractions of the macros described in the `documentation +% parts'. +% +% If the file is used to define new macros (e.g.\ as a package file in +% the |\usepackage| macro), the `documentation parts' are +% bypassed at high speed and the macro definitions are pasted +% together, even if they are split into several `definition parts'. +% +% \DescribeEnv{macrocode} +% On the other hand, if the documentation of these macros is to be +% produced, the `definition parts' should be typeset verbatim. To +% achieve this, these parts are surrounded by the \textsf{macrocode} +% environment. +% More exactly: before a `definition part' there should be a line +% containing\\ +% \hspace*{\MacroIndent}\verb*+% \begin{macrocode}+\\ +% and after this part a line\\ +% \hspace*{\MacroIndent}\verb*+% \end{macrocode}+\\ +% There must be {\em exactly\/} four spaces between the |%| +% and |\end{macrocode}| --- \TeX{} is looking for this string +% and not for the macro while processing a `definition part'. +% +% Inside a `definition part' all \TeX{} commands are allowed; even the +% percent sign could be used to suppress unwanted spaces etc. +% +% \DescribeEnv{macrocode*} Instead of the \textsf{macrocode} +% environment one can also use the \textsf{macrocode$*$} environment +% which produces the same results except that spaces are printed as +% \nopagebreak\verb*+ + characters. +% +% +% +% \subsection{Describing the usage of new macros} +% +% \DescribeMacro\DescribeMacro +% When you describe a new macro you may use |\DescribeMacro| to +% indicate that at this point the usage of a specific macro is +% explained. It takes one argument which will be printed in the margin +% and also produces a special index entry. For example, I used +% |\DescribeMacro{\DescribeMacro}| to make clear that this is the +% point where the usage of |\DescribeMacro| is explained. +% +% \DescribeMacro\DescribeEnv +% An analogous macro |\DescribeEnv| should be used to indicate +% that a \LaTeX{} environment is explained. It will produce a somewhat +% different index entry. Below I used |\DescribeEnv{verbatim}|. +% +% \DescribeEnv{verbatim} +% It is often a good idea to include examples of the usage of new macros +% in the text. Because of the |%| sign in the first column of every +% row, the \textsf{verbatim} environment is slightly altered to suppress +% those +% characters.\footnote{These macros were written by Rainer +% Sch\"opf~\cite{art:verbatim}. He also +% provided a new \textsf{verbatim} environment +% which can be used inside of other macros.} +% \DescribeEnv{verbatim*} +% The \textsf{verbatim$*$} environment is changed in the same way. +% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.} +% \DescribeMacro\verb +% The "\verb" command is re-implemented to give an error report if a +% newline appears in its argument. +% The \textsf{verbatim} and \textsf{verbatim$*$} environments set text +% in the style defined by "\MacroFont"~(\S\ref{sec:macrofont}). +% +% +% +% \subsection{Describing the definition of new macros} +% +% \DescribeEnv{macro} +% To describe the definition of a new macro we use the \textsf{macro} +% environment. It has one argument: the name of the new +% macro.\footnote{This is a change to the style design I described in +% ^^A \TUB ^^A removed in case ltugboat.sty not used +% \textsl{TUGboat\/}\ 10\#1 (Jan.~89). We finally decided +% that it would +% be better to use the macro name {\em with\/} the +% backslash as an argument.} +% This argument is also used to print the name in the margin and to +% produce an index entry. +% Actually the index entries for usage and definition are different to +% allow an easy reference. +% This environment might be nested. In this case the +% labels in the margin are placed under each other. +% \changes{v1.7a}{1992/02/26}{Note on need for some text in macro env.} +% There should be some text---even if it's just an empty +% "\mbox{}"---in this environment before "\begin{macrocode}" or the +% marginal label won't print in the right place. +% +% \DescribeMacro\MacrocodeTopsep +% \DescribeMacro\MacroTopsep +% There also exist four style parameters: |\MacrocodeTopsep| and +% |\MacroTopsep| are used to control the vertical spacing above +% and below the \textsf{macrocode} and the \textsf{macro} +% \DescribeMacro\MacroIndent +% environment, |\MacroIndent| is used to indent the lines of code +% and +% \DescribeMacro\MacroFont \label{sec:macrofont} +% |\MacroFont| holds the font and a possible size change command +% for the code lines, the "verbatim"["*"] environment and the macro +% names printed in the margin. If you want +% to change their default values in a +% class file (like \texttt{ltugboat.cls}) use the |\DocstyleParms| +% command described below. Starting with release 2.0a it can now +% be changed directly as long as the redefinition happens before +% the |\begin{document}|. +% +% +% +% +% \subsection{Formatting the margins} +% +% \DescribeMacro\PrintDescribeMacro +% \DescribeMacro\PrintDescribeEnv +% \DescribeMacro\PrintMacroName +% \DescribeMacro\PrintEnvName +% As mentioned earlier, some macros and the \textsf{macro} environment +% print their arguments in the margin. This is actually done by four +% macros which are user +% definable.\footnote{You may place the changed definitions in a +% separate package +% file or at the beginning of the documentation +% file. +% For example, if you don't like any names in the +% margin +% but want a fine index you can simply +% \texttt{\bslash let} +% these macros equal \texttt{\bslash @gobble}. +% The doc package won't redefine any existing +% definitions of these macros.} +% They are named |\PrintDescribeMacro|, |\PrintDescribeEnv|, +% |\PrintMacroName| (called by the \textsf{macro} environment) and +% |\PrintEnvName| (called by the \textsf{environment} environment). +% +% +% \subsection{Using a special escape character} +% +% \DescribeMacro\SpecialEscapechar +% If one defines complicated macros it is sometimes necessary to +% introduce a new escape character because the `|\|' has got a +% special |\catcode|. In this case one can use +% |\SpecialEscapechar| to indicate which character is actually +% used to play the r\^ole of the `|\|'. A scheme like this is +% needed because the \textsf{macrocode} environment and its counterpart +% \textsf{macrocode$*$} produce an index entry for every occurrence of a +% macro name. They would be very confused if you didn't tell them that +% you'd changed |\catcode|$\,$s. The argument to +% |\SpecialEscapechar| is a single-letter control sequence, that +% is, one has to use "\|" for example to denote that `\verb+|+' +% is used as an escape character. |\SpecialEscapechar| only +% changes the behavior of the next \textsf{macrocode} or +% \textsf{macrocode$*$} environment. +% +% The actual index entries created will all be printed with |\| +% rather than \verb+|+, but this probably reflects their usage, if not +% their definition, and anyway must be preferable to not having any +% entry at all. The entries {\em could\/} be formatted appropriately, +% but the effort is hardly worth it, and the resulting index might be +% more confusing (it would certainly be longer!). +% +% +% \subsection{Cross-referencing all macros used} +% +% \DescribeMacro\DisableCrossrefs \DescribeMacro\EnableCrossrefs As +% already mentioned, every new macro name used within a +% \textsf{macrocode} or \textsf{macrocode$*$} environment will produce +% an index entry. In this way one can easily find out where a specific +% macro is used. Since \TeX{} is considerably slower when it has to +% produce such a bulk of index entries one can turn off this feature +% by using |\DisableCrossrefs| in the driver file. To turn it on again +% just use |\EnableCrossrefs|.\footnote{Actually, \texttt{\bslash +% EnableCrossrefs} changes things more drastically; any following +% \texttt{\bslash DisableCrossrefs} which might be present in the +% source will be ignored.} +% +% +% \DescribeMacro\DoNotIndex +% But also finer control is provided. The |\DoNotIndex| macro +% takes a list of macro names separated by commas. Those names won't +% show up in the index. You might use several |\DoNotIndex| +% commands: their lists will be concatenated. In this article I used +% |\DoNotIndex| for +% all macros which are already defined in \LaTeX. +% +% All three above declarations are local to the current group. +% +% Production (or not) of the index (via the "\makeindex" commend) is +% controlled by using or omitting the following declarations in the +% driver file preamble; if neither is used, no index is produced. +% \DescribeMacro\PageIndex Using "\PageIndex" makes all index +% entries refer to their page number; with +% \DescribeMacro\CodelineIndex "\CodelineIndex", index entries +% produced by "\DescribeMacro" and "\DescribeEnv" refer to page number +% but those produced by the \textsf{macro} environment refer to the +% code lines, which will be numbered automatically.\footnote{The line +% number is actually that of the first line of the first +% \textsf{macrocode} environment in the \textsf{macro} environment.} +% \DescribeMacro\theCodelineNo +% The style of this numbering can be controlled by defining the macro +% "\theCodelineNo". Its default definition is to use scriptsize +% arabic numerals; a user-supplied definition won't be overwritten. +% +% \DescribeMacro\CodelineNumbered +% When you don't wish to get an index but want your code lines +% numbered use "\CodelineNumbered" instead of "\CodelineIndex". This +% prevents the generation of an unnecessary ".idx" file. +% +% +% \subsection{Producing the actual index entries} +% +% Several of the aforementioned macros will produce some sort of index +% entries. These entries have to be sorted by an external +% program---the current implementation assumes that the +% \textsf{makeindex} program by Chen~\cite{art:Chen} is used. +% +% But this isn't built in: one has only to redefine some of the +% following macros to be able to use any other index program. All +% macros which are installation +% dependent are defined in such a way that they won't overwrite a +% previous definition. Therefore it is safe to put the changed +% versions in a package file which might be read in before the doc +% package. +% +% To allow the user to change the specific characters recognized by +% his or her index program all characters which have special meaning +% in the \textsf{makeindex} program are given symbolic +% names.\footnote{I don't know if there exists a program which needs +% more command characters, but I hope not.} +% However, all characters used should be of |\catcode| other than +% `letter' (11). +% +% \DescribeMacro{\actualchar} +% The |\actualchar| is used to separate the `key' and the actual +% index entry. +% \DescribeMacro{\quotechar} +% The |\quotechar| is used before a special index program +% character to suppress its special meaning. +% \DescribeMacro{\encapchar} +% The |\encapchar| separates the indexing information from a +% letter string which \textsf{makeindex} uses as a \TeX{} command to +% format the page number associated with a special entry. It is used +% in this package to apply the |\main| and the |\usage| +% commands. +% \DescribeMacro{\levelchar} +% Additionally |\levelchar| is used to separate `item', +% `subitem' and `subsubitem' entries. +% +% It is a good idea to stick to these symbolic names even if you know +% which index program is used. In this way your files will be +% portable. +% +% \DescribeMacro\SpecialMainIndex +% \DescribeMacro\SpecialMainEnvIndex +% To produce a main index entry for a macro the +% |\SpecialMainIndex| macro\footnote{This macro is called by the +% \textsf{macro} environment.} may be used. It is called `special' +% because it has to print its argument verbatim. +% A similar macro, called |\SpecialMainEnvIndex| is used for indexing +% the main definition point of an +% environment.\footnote{This macro is called by the +% \textsf{environment} environment.} +% \DescribeMacro\SpecialIndex +% If you want a normal index entry for a macro name +% |\SpecialIndex| might be used.\footnote{This macro is called +% within the \textsf{macrocode} environment when encountering a macro +% name.} +% \DescribeMacro\SpecialUsageIndex +% \DescribeMacro\SpecialEnvIndex +% To index the usage of a macro or an environment +% |\SpecialUsageIndex| and |\SpecialEnvIndex| may be used. +% \DescribeMacro\SortIndex +% Additionally a |\SortIndex| command is provided. It takes two +% arguments---the sort key and the actual index entry. +% +% All these macros are normally used by other macros; you will need +% them only in an emergency. +% +% \DescribeMacro\verbatimchar +% But there is one characteristic worth mentioning: all macro names in +% the index are typeset with the |\verb*| command. Therefore one +% special character is needed to act as a delimiter for this command. +% To allow a change in this respect, again this character is +% referenced indirectly, by the macro |\verbatimchar|. It expands +% by default to \verb?+? but if your code lines contain macros with +% `\texttt{+}' characters in their names (e.g.\ when you use \verb?\+?) +% you will end up with an index entry containing \verb?\verb+\++? +% which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this +% case you should redefine |\verbatimchar| globally or locally to +% overcome this problem. +% +% \DescribeMacro\* +% We also provide a |\*| macro. This is intended to be used for +% index entries like +% \begin{quote} +% index entries \\ +% \hspace*{30pt} Special macros for \* +% \end{quote} +% Such an entry might be produced with the line: +%\begin{verbatim} +% \index{index entries\levelchar Special macros for \*} +%\end{verbatim} +% +% \DescribeMacro\OldMakeindex +% Versions of \textsf{makeindex} prior to 2.9 had some bugs affecting +% \DOC{}. One of these, +% pertaining to the "%" character doesn't have a work-around +% appropriate for versions with and without the +% bug.\label{makeindex:version} If +% you have an old version, invoke "\OldMakeindex" in a +% package file or the driver file to prevent problems with index entries +% such as "\%", although you'll probably normally want to turn off +% indexing of "\%" anyway. Try to get an up-to-date \textsf{makeindex} +% from one of the \TeX{} repositories. +% +% +% \subsection{Setting the index entries} +% +% \changes{v1.7a}{1992/03/11}{Usage note on gind.ist.} After the first +% formatting pass through the \texttt{.dtx} file you need to sort the +% index entries written to the \texttt{.idx} file using +% \textsf{makeindex} or your favourite alternative. You need a +% suitable style file for \textsf{makeindex} (specified by the +% \texttt{-s} switch). A suitable one is supplied with \DOC{}, +% called \texttt{gind.ist}. +% +% \DescribeMacro\PrintIndex +% To read in and print the sorted index, just put the +% |\PrintIndex| command as the last (commented-out, and thus +% executed during the documentation pass through the file) command +% in your package file. Precede it by any bibliography commands +% necessary for your citations. +% Alternatively, it may be more convenient to put all such calls +% amongst the arguments of the |\StopEventually| macro, in +% which case a |\Finale| command should appear at the end of +% your file. +% +% \DescribeEnv{theindex} +% Contrary to standard \LaTeX, the index is typeset in three columns +% by default. This is controlled by the \LaTeX{} counter +% `\textsf{IndexColumns}' and can therefore be changed with a +% |\setcounter| declaration. Additionally one doesn't want to +% start a new page unnecessarily. Therefore the \textsf{theindex} +% environment is redefined. +% \DescribeMacro\IndexMin +% When the \textsf{theindex} environment starts it will measure how much +% space is left on the current page. If this is more than +% |\IndexMin| then the index will start on this page. Otherwise +% |\newpage| is called. +% +% Then a short introduction about the meaning of several index entries +% is typeset (still in onecolumn mode). Afterwards the actual index +% entries follow in multi-column mode. +% \DescribeMacro\IndexPrologue +% You can change this prologue with the help of the +% |\IndexPrologue| macro. Actually the section heading is also +% produced in this way, so you'd better write something like: +% \begin{verbatim} +% \IndexPrologue{\section*{Index} The index entries underlined ...} +%\end{verbatim} +% When the \textsf{theindex} environment is finished the last page will +% be reformatted to produce balanced columns. This improves the layout +% and allows the next article to start on the same page. +% \DescribeMacro\IndexParms +% Formatting of the index columns (values for |\columnssep| +% etc.)\ is controlled by the |\IndexParms| macro. It assigns the +% following values: +% \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A +% \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A +% \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip} +% \begin{center} +% \begin{tabular}{l@{\,=\,}ll@{\,=\,}l} +% |\parindent| & \IndexParms \the\parindent & +% |\columnsep| & \IndexParms \the\columnsep \\ +% |\parskip| & \IndexParms \the\parskip & +% |\rightskip| & \IndexParms +% \expandafter\dimenvalue\the\rightskip \\ +% |\mathsurround| & \IndexParms \the\mathsurround & +% |\parfillskip| & \IndexParms +% \expandafter\dimenvalue\the\parfillskip +% \end{tabular} +% \end{center} +% \DescribeMacro{\@idxitem} +% Additionally it defines |\@idxitem| (which will be used when an +% |\item| command is encountered) and selects |\small| size. +% If you want to change any of these values you have to define them +% all. +% +% \DescribeMacro\main +% \DescribeMacro\usage +% The page numbers for main index entries are encapsulated by the +% |\main| macro (underlining its argument) and the numbers +% denoting the description are encapsulated by the |\usage| macro +% (which produces {\em italics}). As usual these commands are user +% definable. +% +% +% \subsection{Changing the default values of style parameters} +% +% \DescribeMacro\DocstyleParms If you want to overwrite some default +% settings made by the \DOC{} package, you can either put your +% declarations in the driver file (that is after \texttt{doc.sty} is +% read in) or use a separate package file for doing this work. In the +% latter case you can define the macro |\DocstyleParms| to contain all +% assignments. This indirect approach is necessary if your package file +% might be read before the \texttt{doc.sty}, when some of the +% registers are not allocated. Its default definition is null. +% +% The doc package currently assigns values to the following +% registers: +% \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A +% \SpecialUsageIndex{\MacroTopsep}^^A +% \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A +% \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance} +% \begin{center} +% \begin{tabular}{l@{\,=\,}ll@{\,=\,}l} +% |\IndexMin| & \the\IndexMin & +% |\MacroTopsep| & \the\MacroTopsep \\ +% |\marginparwidth|& \the\marginparwidth & +% |\MacroIndent| & \the\MacroIndent \\ +% |\marginparpush| & \the\marginparpush & +% |\MacrocodeTopsep| & \the\MacrocodeTopsep \\ +% |\tolerance| & \the\tolerance +% \end{tabular} +% \end{center} +% +% +% \subsection{Short input of verbatim text pieces} +% +% \DescribeMacro\MakeShortVerb +% \DescribeMacro{\MakeShortVerb*} \DescribeMacro\DeleteShortVerb It is +% awkward to have to type, say, "\verb|"\ldots"|" continually when +% quoting +% verbatim bits (like macro names) in the text, so an abbreviation +% mechanism is provided. Pick a character \meta{c}---one which +% normally has catcode `other' unless you have very good reason not +% to---which you don't envisage using in the text, or not using often. +% (I like |"|, but you may prefer "|" if you have |"| active to do +% umlauts, for instance.) Then if you say +% "\MakeShortVerb{\"\meta{c}"}" you can subsequently use +% \meta{c}\meta{text}\meta{c} as the equivalent of +% "\verb"\meta{c}\meta{text}\meta{c}; analogously, the "*"-form +% "\MakeShortVerb*{\"\meta{c}"}" gives you the equivalent of +% "\verb*"\meta{c}\meta{text}\meta{c}. Use +% "\DeleteShortVerb{\"\meta{c}"}" if you subsequently want \meta{c} to +% revert to its previous meaning---you can always turn it on again +% after the unusual section. The `short verb' commands make global +% changes. The abbreviated "\verb" may not appear in the argument of +% another command just like "\verb". However the `short verb' +% character may be used freely in the \textsf{verbatim} and +% \textsf{macrocode} environments without ill effect. +% "\DeleteShortVerb" is silently ignored if its argument does not +% currently represent a short verb character. Both commands type a +% message to tell you the meaning of the character is being changed. +% +% Please remember that the command "\verb" cannot be used in arguments +% of other commands. Therefore abbreviation characters for "\verb" +% cannot be used there either. +% +% This feature is also available as a sole package, \texttt{shortvrb}. +% +% +% \subsection{Additional bells and whistles} +% +% We provide macros for logos such as \Web, \AmSTeX, \BibTeX, +% \SliTeX{} and \PlainTeX. Just type |\Web|, |\AmSTeX|, +% |\BibTeX|, |\SliTeX| or |\PlainTeX|, respectively. +% \LaTeX{} and \TeX{} are already defined in \texttt{latex.tex}. +% +% \DescribeMacro\meta +% Another useful macro is |\meta| which has one argument and +% produces something like \meta{dimen parameter}. +% +% \DescribeMacro\OnlyDescription +% \DescribeMacro\StopEventually +% You can use the |\OnlyDescription| declaration in the driver +% file to suppress the last part of your document (which presumably +% exhibits the code). To make this work +% you have to place the command |\StopEventually| at a suitable +% point in your file. This macro has one argument in which you put +% all information you want to see printed if your document ends at +% this point (for example a bibliography which is normally printed at +% the very end). When the |\OnlyDescription| declaration is +% missing the |\StopEventually| +% \DescribeMacro\Finale +% macro saves its argument in a macro called |\Finale| which can +% afterwards be used to get things back (usually at the very end). +% Such a scheme makes changes in two places unnecessary. +% +% Thus you can use this feature to produce a local guide for the +% \TeX{} users which describes only the usage of macros (most of them +% won't be interested in your definitions anyway). For the same +% reason the |\maketitle| \DescribeMacro\maketitle command is slightly +% changed to allow multiple titles in one document. So you can make +% one driver file reading in several articles at once. +% \DescribeMacro{\ps@titlepage} To avoid an unwanted +% \textsf{pagestyle} on the title page the |\maketitle| command issues +% a |\thispagestyle{titlepage}| declaration which produces a +% \textsf{plain} page if the \textsf{titlepage} page style is +% undefined. This allows class files like \textsf{ltugboat.cls} to +% define their own page styles for title pages. +% +% \DescribeMacro\AlsoImplementation +% Typesetting the whole document is the default. However, this default +% can also be explicitly selected using the declaration +% |\AlsoImplementation|. This overwrites any previous +% |\OnlyDescription| declaration. The \LaTeXe{} distribution, for +% example, is documented using the \texttt{ltxdoc} class which allows +% for a configuration file \texttt{ltxdoc.cfg}. In such a file one +% could then add the statement +% \begin{quote} +% |\AtBeginDocument{\AlsoImplementation}| +% \end{quote} +% to make sure that all documents will show the code part. +% +% \DescribeMacro\IndexInput \label{..Input} Last but not least I +% defined an |\IndexInput| macro which takes a file name as an +% argument and produces a verbatim listing of the file, indexing every +% command as it goes along. This might be handy, if you want to learn +% something about macros without enough documentation. I used this +% feature to cross-reference \texttt{latex.tex} getting a verbatim +% copy with about 15 pages index.\footnote{It took quite a long time +% and the resulting \texttt{.idx} file was longer than the +% \texttt{.dvi} file. Actually too long to be handled by the +% \textsf{makeindex} program directly (on our MicroVAX) but the final +% result was worth the trouble.} +% +% \changes{v2.1d}{2006/02/02}{Corrected description of \cs{changes} +% macro.} +% \DescribeMacro\changes +% To maintain a change history within the file, the |\changes| +% command may be placed amongst the description part of the changed +% code. It takes three arguments, thus: +% \begin{quote} +% |\changes{|\meta{version}|}{|\meta{date}|}{|^^A +% \meta{text}|}| +% \end{quote} +% The changes may be used to produce an auxiliary file (\LaTeX's +% |\glossary| mechanism is used for this) which may be printed +% after suitable formatting. The |\changes| macro generates the +% printed entry in such a change history; because old +% versions\footnote{Before 2.6.} of the \textsf{makeindex} +% program limit such fields to 64 characters, care should be taken +% not to exceed this limit when describing the change. The actual +% entry consists of the \meta{version}, the |\actualchar|, the current +% macro name, a colon, the |\levelchar|, and, finally, the \meta{text}. +% The result is a glossaryentry for the \meta{version}, with the name of +% the current macro as subitem. Outside the |macro| environment, the +% text |\generalname| is used instead of the macro name. When +% referring to macros in change descriptions it is conventional to use +% |\cs{|\meta{macroname}|}| rather than attempting to format it properly +% and using up valuable characters in the entry with old \textsf{makeindex} +% versions. +% +% \changes{v1.7a}{1992/02/26}{Description of \cs{RecordChanges} etc. +% added +% to interface section.} \DescribeMacro\RecordChanges To cause the +% change information to be written out, include "\RecordChanges" in +% the driver file. \DescribeMacro\PrintChanges To read in and print +% the sorted change history (in two columns), just put the +% |\PrintChanges| command as the last (commented-out, and thus +% executed during the documentation pass through the file) command in +% your package file. Alternatively, this command may form one of the +% arguments of the |\StopEventually| command, although a change +% history is probably {\em not\/} required if only the description is +% being printed. The command assumes that \textsf{makeindex} or some +% other program has processed the \texttt{.glo} file to generate a +% sorted \texttt{.gls} file. You need a special \textsf{makeindex} +% style file; a suitable one is supplied with \DOC{}, called +% \texttt{gglo.ist}. \DescribeMacro\GlossaryMin +% \DescribeMacro\GlossaryPrologue \DescribeMacro\GlossaryParms The +% "\GlossaryMin", "\GlossaryPrologue" and "\GlossaryParms" macros are +% analogous to the "\Index"\ldots\ versions. (The \LaTeX{} `glossary' +% mechanism is used for the change entries.) +% +% \label{sec:checksum} +% \DescribeMacro\CharacterTable +% \DescribeMacro\CheckSum +% To overcome some of the problems of sending files over the networks +% we developed two macros which should detect corrupted files. If one +% places the lines +% \begin{flushleft} +% \small\ttfamily ^^A \ttfamily to get the blanks between "..."s +% ^^A right +%"%%\CharacterTable"\\ +%"%% {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"\\ +%"%% 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"\\ +%"%% Digits \0\1\2\3\4\5\6\7\8\9"\\ +%"%% Exclamation \! Double quote "\verb=\"= +%" Hash (number) \#"\\ +%"%% Dollar \$ Percent \% Ampersand \&"\\ +%"%% Acute accent \' Left paren \( Right paren \)"\\ +%"%% Asterisk \* Plus \+ Comma \,"\\ +%"%% Minus \- Point \. Solidus \/"\\ +%"%% Colon \: Semicolon \; Less than \<"\\ +%"%% Equals \= Greater than \> Question mark \?"\\ +%"%% Commercial at \@ Left bracket \[ Backslash \\"\\ +%"%% Right bracket \] Circumflex \^ Underscore \_"\\ +%"%% Grave accent \` Left brace \{ Vertical bar \|"\\ +%"%% Right brace \} Tilde \~}"\\ +%"%%" +%\end{flushleft} +% at the beginning of the file then character translation failures +% will be detected, provided of course, that the used \DOC{} +% package has a correct default table. The percent +% signs\footnote{There are two percent signs in each line. This has +% the effect that these lines are not removed by the +% \texttt{docstrip.tex} program.} at the beginning of the lines should +% be typed in, since only the \DOC{} package should look at this +% command. +% +% +% Another problem of mailing files is possible truncation. To detect +% these sort of errors we provide a |\CheckSum| macro. The check-sum +% of a file is simply the number of backslashes in the code, i.e.\ all +% lines between the \textsf{macrocode} environments. But don't be +% afraid: you don't have count the code-lines yourself; this is done +% by the \DOC{} package for you. You simply have add +% \begin{quote} +% |% \CheckSum{0}| +% \end{quote} +% near the beginning of the file and +% use +% the |\StopEventually| (which starts looking for backslashes) and the +% |\Finale| command. The latter will inform you either that your file +% has no check-sum (telling you the right number) or that your number +% is incorrect if you put in anything other than zero but guessed wrong (this time +% telling you both the correct and the +% incorrect one). Then you go to the top of your file again and change the +% line to the right number, i.e. +% line +% \begin{quote} +% |% \CheckSum{|\meta{number}|}| +% \end{quote} +% and that's all. +% +% While |\CharacterTable| and |\CheckSum| have been important features +% in the early days of the public internet when \DOC{} was written as +% the mail gateways back then were rather unreliable and often mangled +% files they are these days more a nuisance than any help. They are +% therefore now fully optional and no longer recommended for use with new files. +% +% +% \DescribeMacro\bslash +% From time to time, it is necessary to print a |\| without +% being able to use the |\verb| command because the +% |\catcode|$\,$s of the symbols are already firmly +% established. In this instance we can use the command +% |\bslash| presupposing, of course, that the actual font in +% use at this point contains a `backslash' as a symbol. Note that +% this definition of |\bslash| is expandable; it inserts a +% $"\"_{12}$. This means that you have to |\protect| +% it if it is used in `moving arguments'. +% +% \DescribeMacro\MakePrivateLetters +% \changes{v1.7a}{1992/02/26}{Documented \cs{MakePrivateLetters} in +% interface section}^^A +% If your macros "\catcode" anything other than "@" to `letter', you +% should redefine "\MakePrivateLetters" so that it also makes the +% relevant characters `letters' for the benefit of the indexing. The +% default definition is just "\makeatletter". +% +% \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules +% \DescribeMacro\Module \DescribeMacro\AltMacroFont The `module' +% directives of the \textsf{docstrip} system \cite{art:docstrip} are +% normally recognised and invoke special formatting. This can be +% turned on and off in the \texttt{.dtx} file or the driver file using +% "\CheckModules" and "\DontCheckModules". If checking for module +% directives is on (the default) then code in the scope of the +% directives is set as determined by the hook "\AltMacroFont", which +% gives {\small\ttfamily\itshape small italic type\-writer\/} by +% default in the New Font Selection Scheme but just ordinary +% {\small\ttfamily small type\-writer} in the old one, where a font +% such as italic typewriter can't be used portably (plug for NFSS); +% you will need to override this if you don't have the italic +% typewriter font available. Code is in such a scope if it's on a +% line beginning with "%<" or is between lines starting with +% "%<*"\meta{name list}">" and "%". The +% directive is formatted by the macro "\Module" whose single argument +% is the text of the directive between, but not including, the angle +% brackets; this macro may be re-defined in the driver or package file +% and by default produces results like \Module{+foo\string|bar} with no +% following space. +% +% \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the +% whole code is surrounded by modules to produce several files from a +% single source. In this case it is clearly not appropriate to format +% all code lines in a special "\AltMacroFont". For this reason a +% counter "StandardModuleDepth" is provided which defines the level of +% module nesting which is still supposed to be formatted in +% "\MacroFont" rather then "\AltMacroFont". The default setting is +% "0", for this documentation it was set to +%\begin{verbatim} +% \setcounter{StandardModuleDepth}{1} +%\end{verbatim} +% at the beginning of the file. +% +% +% \subsection{Basic usage summary} +% \changes{v1.7a}{1992/03/11}{Added basic usage summary to spell +% it out.} +% +% To sum up, the basic structure of a \texttt{.dtx} file without any +% refinements is like this: +% \begin{verse}\small +% "% "\meta{waffle}\ldots\\ +% \quad\ldots \\ +% "% \DescribeMacro{\fred}"\\ +% "% "\meta{description of fred's use}\\ +% \quad\ldots\\ +% "% \StopEventually{"\meta{finale code}"}"\\ +% \quad\ldots\\ +% "% \begin{macro}{\fred}"\\ +% "% "\meta{commentary on macro fred}\\ +% \verb*+% \begin{macrocode}+\\ +% \meta{code for macro fred}\\ +% \verb*+% \end{macrocode}+\\ +% "% \end{macro}"\\ +% \quad\ldots\\ +% "% \Finale \PrintIndex \PrintChanges" +% \end{verse} +% For examples of the use of most---if not all---of the features +% described above consult the \texttt{doc.dtx} source itself. +% +% \subsection{Acknowledgements} +% +% I would like to thank all folks at Mainz and at the Royal Military +% College of Science for their help in this project. Especially Brian +% and Rainer who pushed everything with their suggestions, bug fixes, +% etc. +% +% A big thank you to David Love who brought the documentation +% up-to-date again, after I neglected this file for more than two +% years. This was most certainly a tough job as many features added to +% \texttt{doc.dtx} after its publication in \textsl{TUGboat\/} have +% been never properly described. Beside this splendid work he kindly +% provided additional code (like ``docstrip'' module formatting) which +% I think every \textsf{doc.dtx} user will be grateful for. +% +% +% \StopEventually{ +% \begin{thebibliography}{1} +% \bibitem{book:Buerger} \textsc{G. A. B\"urger}. +% \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge +% und lustige Abenteuer des Freyherrn v.\ M\"unchhausen. +% \newblock London, 1786 \& 1788. +% \bibitem{art:Knuthliterat} \textsc{D. E. Knuth}. +% \newblock Literate Programming. +% \newblock Computer Journal, Vol.~27, \textit{pp}.~97--111, +% May 1984. +% \bibitem{book:KnuthA} \textsc{D. E. Knuth}. +% \newblock Computers \& Typesetting (The \TeX book). +% \newblock Addison-Wesley, Vol. A, 1986. +% \bibitem{art:Chen} \textsc{L. Lamport}. +% \newblock MakeIndex: An Index Processor for \LaTeX. +% \newblock 17 February 1987. +% \newblock (Taken from the file \texttt{makeindex.tex} provided +% with +% the program source code.) +% \bibitem{art:doc} \textsc{Frank Mittelbach}. +% \newblock The \DOC{}-option. +% \newblock \textsl{TUGboat}, Vol.~10(2), \textit{pp}.~245--273, +% July 1989. +% \bibitem{art:docstrip} \textsc{Frank Mittelbach, Denys Duchier and +% Johannes Braams}. +% \newblock \texttt{docstrip.dtx} (to appear). +% \newblock The file is part of the DOC package. +% \bibitem{book:Raspe} \textsc{R. E. Raspe} (*1737, \dag 1797). +% \newblock Baron M\"unchhausens narrative of his marvellous +% travels and campaigns in Russia. +% \newblock Oxford, 1785. +% \bibitem{art:verbatim} \textsc{Rainer Sch\"opf}. +% \newblock A New Implementation of \LaTeX's \texttt{verbatim} and +% \texttt{verbatim*} Environments. +% \newblock File \texttt{verbatim.doc}, version 1.4i. +% \end{thebibliography} +% +% \ifmulticols +% \addtocontents{toc}{\protect\end{multicols}} +% \fi +% +% } ^^A end \StopEventually +% +% +% \section{The Description of Macros} +% +% Most of the following code is destined for \texttt{doc.sty} after +% processing with \texttt{docstrip} to include the module +% \textbf{style} indicated here. (All code in this file not +% appropriate to \texttt{doc.sty} has to be included explicitly by +% docstrip so that this \texttt{.dtx} file can be used as directly as +% a package file rather than the stripped version.) The usual font +% change for the conditionally-included lines between the +% \Module{*style} and \Module{/style} directives is suppressed since +% only the lines with an explicit directive are special in this file. +% \begin{macrocode} +%<*package> +% \end{macrocode} +% Under \LaTeXe{} the test to avoid reading +% \DOC{} in twice is normally unnecessary. It was kept to only to +% stay compatible with \LaTeX209 styles that |\input| \DOC{} +% directly. +% \changes{v1.5i}{1989/06/07}{Avoid reading the file twice.} +% \begin{macrocode} +\@ifundefined{macro@cnt}{}{\endinput} +% \end{macrocode} +% +% \DescribeMacro\fileversion +% \DescribeMacro\filedate +% \DescribeMacro\docdate +% As you can see I used macros like |\fileversion| to denote the +% version number and the date. They are defined at the very beginning +% of the package file (without a surrounding \textsf{macrocode} +% environment), so I don't have to search for this place here when I +% change the version number. You can see their actual outcome in a +% footnote to the title. +% +% +% The first thing that we do next is to get ourselves a new comment +% sign. Because all sensible signs are already occupied, we will +% choose one that can only be entered indirectly: +% {\DoNotIndex{\^}^^A avoid misinterpretation !!!!! VERIFY +% \begin{macrocode} +\catcode`\^^A=14 +% \end{macrocode} +% We repeat this statement at the beginning of the document in case +% the \texttt{inputenc} package is used disabling it again. +% \changes{v2.0b}{1998/05/19}{Init docs private comment char at begin +% of document again (pr2581)} +% \begin{macrocode} +\AtBeginDocument{\catcode`\^^A=14\relax} +% \end{macrocode} +% \SortIndex{\string^\string^A}{\string\verb\verbatimchar +% \string^\string^A\verbatimchar +% \encapchar main} +% } +% +% +% \subsection{Options supported by \DOC{}} +% +% Not options available at the moment +% +% \begin{macrocode} +% \end{macrocode} +% +% +% \subsection{Macros surrounding the `definition parts'} +% +% \begin{environment}{macrocode} +% Parts of the macro definition will be surrounded by the +% environment \textsf{macrocode}. Put more precisely, they will be +% enclosed by a macro whose argument (the text to be set +% `verbatim') is terminated by the string +% \verb*+% \end{macrocode}+. Carefully note the number of spaces. +% |\macrocode| is defined completely analogously to +% |\verbatim|, but because a few small changes were carried +% out, almost all internal macros have got new names. We start by +% calling the macro |\macro@code|, the macro which bears the +% brunt of most of the work, such as |\catcode| reassignments, +% etc. +% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)} +% \begin{macrocode} +\def\macrocode{\macro@code +% \end{macrocode} +% Then we take care that all spaces have the same width, and that +% they are not discarded. +% \begin{macrocode} + \frenchspacing \@vobeyspaces +% \end{macrocode} +% Before closing, we need to call |\xmacro@code|. It is this +% macro that expects an argument which is terminated by the above +% string. This way it is possible to keep the |\catcode| +% changes local. +% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)} +% \changes{v1.5t}{1989/11/07}{Common code moved to \cs{macro@code}.} +% \begin{macrocode} + \xmacro@code} +% \end{macrocode} +% \end{environment} +% +% +% \begin{macro}{\macro@code} +% We will now begin with the macro that does the actual work: +% \begin{macrocode} +\def\macro@code{% +% \end{macrocode} +% In theory it should consist of a \textsf{trivlist} environment, but +% the empty space before and after the environment should not be +% too large. +% \begin{macrocode} + \topsep \MacrocodeTopsep +% \end{macrocode} +% The next parameter we set is |\@beginparpenalty|, in order +% to prevent a page break before such an environment. +% \begin{macrocode} + \@beginparpenalty \predisplaypenalty +% \end{macrocode} +% We then start a |\trivlist|, set |\parskip| back to +% zero and start an empty |\item|. +% \changes{v1.9b}{1993/12/03}{Forcing any label from macro env.} +% \begin{macrocode} + \if@inlabel\leavevmode\fi + \trivlist \parskip \z@ \item[]% +% \end{macrocode} +% Additionally, everything should be set in \texttt{typewriter} font. +% Some people might prefer it somewhat differently; because of this +% the font choice is +% macro-driven.\footnote{The font change has to be placed +% {\em after\/} +% the \texttt{\bslash item}. Otherwise a change to +% \texttt{\bslash baselineskip} will affect the +% paragraph above.} +% \begin{macrocode} + \macro@font +% \end{macrocode} +% Because |\item| sets various parameters, we have found it +% necessary to alter some of these retrospectively. +% \begin{macrocode} + \leftskip\@totalleftmargin \advance\leftskip\MacroIndent + \rightskip\z@ \parindent\z@ \parfillskip\@flushglue +% \end{macrocode} +% The next line consists of the \LaTeX{} definition of |\par| +% used in |\verbatim| and should result in blank lines being +% shown as blank lines. +% \changes{v1.5l}{1989/09/10}{Code line numbers supported.} +% \changes{v1.5t}{1989/11/07}{Call \cs{leavevmode} to get \cs{everypar} +% on blank lines.} +% \changes{v1.7c}{1992/03/24}{Added \cs{interlinepenalty} to +% \cs{par} from +% verbatim.sty} +% \begin{macrocode} + \blank@linefalse \def\par{\ifblank@line + \leavevmode\fi + \blank@linetrue\@@par + \penalty\interlinepenalty} +% \end{macrocode} +% What use is this definition of |\par|\,? We use the macro +% |\obeylines| of \cite{book:KnuthA} which changes all |^^M| +% to |\par| so that each can control its own indentation. +% Next we must also ensure that all special signs are normalized; +% that is, they must be given |\catcode| $12$. +% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim, +% which handles more ligatures.} +% \begin{macrocode} + \obeylines + \let\do\do@noligs \verbatim@nolig@list + \let\do\@makeother \dospecials +% \end{macrocode} +% \changes{v1.5t}{1989/11/07}{Common code added.} +% \changes{v1.5w}{1990/02/05}{Skip of \cs{@totalleftmargin} added.} If +% indexing by code lines is switched on the line number is incremented +% and set appropriately. We also check whether the start of the next +% line indicates a \texttt{docstrip} module directive and process it +% appropriately if so using "\check@module". +% \begin{macrocode} + \global\@newlistfalse + \global\@minipagefalse + \ifcodeline@index + \everypar{\global\advance\c@CodelineNo\@ne + \llap{\theCodelineNo\ \hskip\@totalleftmargin}% + \check@module}% + \else \everypar{\check@module}% + \fi +% \end{macrocode} +% We also initialize the cross-referencing feature by calling +% |\init@crossref|. This will start the scanning mechanism +% when encountering an escape character. +% \begin{macrocode} + \init@crossref} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\ifblank@line} +% \begin{macro}{\blank@linetrue} +% \begin{macro}{\blank@linefalse} +% |\ifblank@line| is the switch used in the definition above. +% In the original \textsf{verbatim} environment the |\if@tempswa| +% switch is used. This is dangerous because its value may change +% while processing lines in the \textsf{macrocode} environment. +% \begin{macrocode} +\newif\ifblank@line +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\endmacrocode} +% Because we have begun a \textsf{trivlist} environment in the +% \textsf{macrocode} environment, we must also end it. We must +% also act on the value of the "pm@module" flag (see below) and +% empty "\everypar". +% \changes{v1.5r}{1989/11/04}{Support for code line no. (Undoc)} +% \begin{macrocode} +\def\endmacrocode{% + \ifpm@module \endgroup \pm@modulefalse \fi + \everypar{}% + \global\@inlabelfalse + \endtrivlist +% \end{macrocode} +% Additionally |\close@crossref| is used to do anything needed +% to end the cross-referencing mechanism. +% \begin{macrocode} + \close@crossref} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\MacroFont} +% Here is the default definition for the |\MacroFont| macro. +% With the new math font handling in NFSS2 it isn't any longer +% correct to suppress the math font setup since this is now handled +% differently. But to keep the font change fast we use only a +% single |\selectfont| (in |\small|) and do the rest by hand. +% \changes{v1.5x}{1990/02/17}{\cs{math@fontsfalse} added for NFSS.} +% \changes{v1.7a}{1992/03/13}{Added \cs{reset@font} for NFSS.} +% \changes{v1.8c}{1993/10/25}{NFSS standard} +% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different +% math setup /pr1622} +% \begin{macrocode} +\@ifundefined{MacroFont}{% + \if@compatibility +% \end{macrocode} +% Despite the above statement we will call |\small| first if +% somebody is using a \LaTeX2.09 document with doc. I wouldn't have +% bothered since doc-sources should be up-to-date but since the +% request came from someone called David Carlisle \ldots :-) +% \changes{v1.9y}{1996/01/26}{Support compat mode} +% \begin{macrocode} + \def\MacroFont{\small + \usefont\encodingdefault + \ttdefault + \mddefault + \updefault + }% + \else + \def\MacroFont{\fontencoding\encodingdefault + \fontfamily\ttdefault + \fontseries\mddefault + \fontshape\updefault + \small}% + \fi + }{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\AltMacroFont} +% \begin{macro}{\macro@font} +% \changes{v1.7a}{1992/03/12}{Added to support distinction of modules.} +% \changes{v1.7c}{1992/03/26}{Altered font change for OFSS.} +% \changes{v1.7m}{1992/10/11}{Use sltt as default.} +% \changes{v1.8c}{1993/10/25}{NFSS standard} +% \changes{v1.9t}{1995/05/26}{Removed \cs{math@fontsfalse} (different +% math setup /pr1622} +% Although most of the macro code is set in "\MacroFont" we want to be +% able to switch to indicate module code set in "\AltMacroFont". +% "\macro@font" keeps track of which one we're using. We can't do the +% same thing sensibly in OFSS as in NFSS. +% \begin{macrocode} +\@ifundefined{AltMacroFont}{% + \if@compatibility +% \end{macrocode} +% Again have |\small| first if we are in compat mode. +% \changes{v1.9y}{1996/01/26}{Support compat mode} +% \begin{macrocode} + \def\AltMacroFont{\small + \usefont\encodingdefault + \ttdefault + \mddefault + \sldefault + }% + \else + \def\AltMacroFont{\fontencoding\encodingdefault + \fontfamily\ttdefault + \fontseries\mddefault + \fontshape\sldefault + \small + }% + \fi + }{} +% \end{macrocode} +% To allow changing the "\MacroFont" in the preamble we defer +% defining the internally used "\macro@font" until after the +% preamble. +% \changes{v2.0a}{1998/05/16}{Support changing \cs{MacroFont} in +% preamble} +% \begin{macrocode} +\AtBeginDocument{\let\macro@font\MacroFont} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\check@module} +% \begin{macro}{\ifpm@module} +% \changes{v1.7a}{1992/03/12}{Added.} +% This is inserted by "\everypar" at the start of each macrocode line to +% check whether it starts with module information. (Such information is +% of the form "%<"\meta{switch}">", where the "%" must be at the +% start of the line and \meta{switch} comprises names with various +% possible separators and a possible leading "+", "-", "*" or "/" +% \cite{art:docstrip}. All that concerns us here is what the first +% character of \meta{switch} is.) First it checks the "pm@module" +% flag in case the previous line had a non-block module +% directive i.e., not "%<*" or "%|. +% \changes{v2.0n}{2001/05/16}{Partly support docstrip's ``verbatim'' +% directive (pr/3331)} +% \begin{macrocode} + \else\ifx <\next + \percentchar + \else + \let\next\pm@module + \fi\fi\fi\fi\fi + \next} +\endgroup +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\pm@module} +% If we're not dealing with a block +% directive ("*" or "/") i.e., it's a single special line, we set +% everything up to the next ">" appropriately and then change to the +% special macro font inside a group which will be ended at the start +% of the next line. If the apparent module directive is missing the +% terminating ">" this will lose, but then so will the \texttt{docstrip} +% implementation. An alternative strategy would be to have +% "\pm@module" make ">" active and clear a flag set here to indicate +% processing the directive. Appropriate action could then be taken if +% the flag was found still to be set when processing the next line. +% \changes{v1.7a}{1992/03/12}{Added.} +% \changes{v1.7i}{1992/07/11}{Support for fonts depending on nesting.} +% \begin{macrocode} +\begingroup +\catcode`\~=\active +\lccode`\~=`\> +\lowercase{\gdef\pm@module#1~}{\pm@moduletrue + \Module{#1}\begingroup +% \end{macrocode} +% We switch to a special font as soon the nesting is higher than +% the current value of "\c@StandardModuleDepth". We do a local +% update to the "\guard@level" here which will be restored after +% the current input line. +% \begin{macrocode} + \advance\guard@level\@ne + \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\star@module} +% \begin{macro}{\slash@module} +% \changes{v1.7a}{1992/03/12}{Added.} +% \changes{v1.7f}{1992/05/16}{Take account of nested guards.} +% \changes{v1.7i}{1992/07/11}{Add counter to determine when to switch to +% special font.} +% If the start or end of a module {\em block\/} is indicated, after +% setting the guard we have to check whether a change in the macrocode +% font should be done. This will be the case if we are already inside +% a block or are ending the outermost block. If so, we globally +% toggle the font for subsequent macrocode sections between the normal +% and special form, switching to the new one immediately. +% \changes{v1.7i}{1992/07/17}{Support for fonts depending on module +% nesting} +% \begin{macrocode} +\lowercase{\gdef\star@module#1~}{% + \Module{#1}% + \global \advance \guard@level\@ne + \ifnum \guard@level>\c@StandardModuleDepth + \global\let\macro@font=\AltMacroFont \macro@font + \fi} +\catcode`\>=\active +\gdef\slash@module#1>{% + \Module{#1}% + \global \advance \guard@level\m@ne + \ifnum \guard@level=\c@StandardModuleDepth + \global\let\macro@font\MacroFont \macro@font + \fi +} +\endgroup +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\c@StandardModuleDepth} +% \changes{v1.7i}{1992/07/11}{Counter added.} +% Counter defining up to which level modules are considered part of +% the main code. If, for example, the whole code is surrounded by +% a |%<*package>| module we better set this counter to |1| to avoid +% getting the whole code be displayed in typewriter italic. +% \begin{macrocode} +\newcounter{StandardModuleDepth} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\guard@level} +% \changes{v1.7f}{1992/05/16}{Added.} +% We need a counter to keep track of the guard nesting. +% \begin{macrocode} +\newcount \guard@level +% \end{macrocode} +% \end{macro} +% \begin{macro}{\Module} +% \changes{v1.7a}{1992/03/12}{Added.} +% \changes{v1.7d}{1992/04/25}{Use sans font for modules.} +% This provides a hook to determine the way the module directive is +% set. It gets as argument everything between the angle brackets. +% The default is to set the contents in sans serif text between +% $\langle\,\rangle$ with the special characters suitably "\mathcode"d +% by "\mod@math@codes". (You can't just set it in a sans text font +% because normally "|" will print as an em-dash.) This is done +% differently depending on whether we have the NFSS or the old one. In +% the latter case we can easily change "\fam" appropriately. +% \changes{v1.8c}{1993/10/25}{NFSS standard} +% \begin{macrocode} +\@ifundefined{Module}{% +% \end{macrocode} +% With NFSS what we probably {\em should\/} do is change to a new +% "\mathversion" but I (Dave Love) haven't spotted an easy way to +% do so correctly if the document uses a version other than +% "normal". (We need to know in what font to set the other +% groups.) This uses a new math alphabet rather than version and +% consequently has to worry about whether we're using +% \textsf{oldlfnt} or not. I expect there's a better +% way\ldots +% \begin{macrocode} + \def\Module#1{\mod@math@codes$\langle\mathsf{#1}\rangle$} + }{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\mod@math@codes} +% \changes{v1.7c}{1992/03/26}{Added.} +% \changes{v2.1e}{2010/02/04}{Added mathcodes for +,-,:, and = (pr/4096)} +% As well as `words', the module +% directive text might contain any of the characters "*/+-,&|!()" +% for the current version of \textsf{docstrip}. We only need +% special action for two of them in the math code changing required +% above: "|" is changed to a "\mathop" (it's normally |"026A|) and +% "&" is also made a "\mathop", but in family 0. Remember that "&" +% will not have a special catcode when it's encountered. +% \begin{macrocode} +\def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026 + \mathcode`\-="702D \mathcode`\+="702B + \mathcode`\:="703A \mathcode`\=="703D } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\mathsf} +% \changes{v1.7c}{1992/03/26}{Added.} +% \changes{v1.7d}{1992/04/25}{Use sans font for modules.} +% \changes{v1.7n}{1993/02/21}{\cs{sfmath} Renamed to \cs{mathsf}.} +% \changes{v1.8c}{1993/10/25}{NFSS standard} +% If NFSS is in use we need a new math alphabet which uses a sans serif +% font. To support both the release one and two of NFSS the alphabet +% was renamed to "\mathsf" which is defined in NFSS2. +% \begin{macrocode} +%\ifx\selectfont\undefined +%\else +% \ifx\mathsf\undefined +% \newmathalphabet*{\mathsf}{\sfdefault}{m}{n}\fi +%\fi +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\MacrocodeTopsep} +% \begin{macro}{\MacroIndent} +% In the code above, we have used two registers. Therefore we have +% to allocate them. The default values might be overwritten with +% the help of the |\DocstyleParms| macro. +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \changes{v1.5y}{1990/02/24}{Default changed.} +% \changes{v1.6b}{1990/06/15}{\cs{rm} moved before \cs{scriptsize} to +% avoid unnecessary fontwarning.} +% \begin{macrocode} +\newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt +\newdimen\MacroIndent +\settowidth\MacroIndent{\rmfamily\scriptsize 00\ } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +% \begin{environment}{macrocode*} +% \begin{macro}{\endmacrocode*} +% Just as in the \textsf{verbatim} environment, there is also a +% `star' variant of the \textsf{macrocode} environment in which a +% space is shown by the symbol \verb*+ +. Until this moment, I +% have not yet used it (it will be used in the description of the +% definition of |\xmacro@code| below) but it's exactly on this one +% occasion {\em here\/} that you can't use it (cf.\ M\"unchhausens +% Marsh problem)\footnote{Karl Friedrich Hieronymus Frhr.\ v.\ +% M\"unchhausen (*1720, \dag1797). Several books were written +% about fantastic adventures supposedly told by him (see +% \cite{book:Raspe} or \cite{book:Buerger}). In one story he +% escaped from the marsh by pulling himself out by his hair.} +% directly. Because of this, on this one occasion we'll cheat +% around the problem with an additional comment character. But now +% back to |\macrocode*|. We start with the macro |\macro@code| +% which prepares everything and then call the macro |\sxmacro@code| +% whose argument is terminated by the string +%\verb*+% \end{macrocode*}+. +% \begin{macrocode} +\@namedef{macrocode*}{\macro@code\sxmacro@code} +% \end{macrocode} +% As we know, |\sxmacro@code| and then |\end{macrocode*}| +% (the macro, not the string), will be executed, so that for a +% happy ending we still need to define the macro +% |\endmacrocode*|. +% \begin{macrocode} +\expandafter\let\csname endmacrocode*\endcsname = \endmacrocode +% \end{macrocode} +% \end{macro} +% \end{environment} +% +% +% +% +% +% +% +% \begin{macro}{\xmacro@code} +\catcode`\!=\catcode`\% ^^A In this section there must not be + ^^A any exclamation marks. + ^^A +% As already mentioned, the macro |\xmacro@code| expects an +% argument delimited by the string \verb*+% \end{macrocode}+. At +% the moment that this macro is called, the |\catcode| of +% \TeX's special characters are 12 (`other') or 13 (`active'). +% Because of this we need to utilize a different escape character +% during the definition. This happens locally. +% \begin{macrocode*} +\begingroup +\catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@ +% \end{macrocode*} +% Additionally, we need to ensure that the symbols in the above +% string contain the |\catcode|$\,$s which are available +% within the \textsf{macrocode} environment. +% \begin{macrocode*} +\catcode`\{=12 \catcode`\}=12 +\catcode`\%=12 \catcode`\ =\active \catcode`\\=\active +!% \end{macrocode*} +! Next follows the actual definition of |\macro@code|; +! notice the +! use of the new escape character. We manage to get the argument +! surrounded by the string |\end{macrocode}|, but at the end +! however, in spite of the actual characters used during the +! definition of +! this macro, |\end| with the argument |{macrocode}| +! will be executed, to ensure a balanced environment. +! \begin{macrocode*} +|gdef|xmacro@code#1% \end{macrocode}[#1|end[macrocode]] +!% \end{macrocode*} +! \begin{macro}{\sxmacro@code} +! The definition of |\sxmacro@code| is completely analogous, +! only +! here a slightly different terminating string will be used. +! Note that the space is not active in this environment. +! \begin{macrocode} +|catcode`| =12 +|gdef|sxmacro@code#1% \end{macrocode*}[#1|end[macrocode*]] +!% \end{macrocode} +! because the |\catcode| changes have been made local by +! commencing a +! new group, there now follows the matching |\endgroup| +! in a rather +! unusual style of writing. +! \begin{macrocode} +|endgroup +!% \end{macrocode} +\catcode`\!=12 +% \end{macro} +% \end{macro} +% +% +% +% +% \subsection{Macros for the `documentation parts'} +% +% +% \begin{macro}{\DescribeMacro} +% \begin{macro}{\Describe@Macro} +% \changes{v1.5v}{1990/01/28}{Macro added.} +% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary +% fix} +% \begin{macro}{\DescribeEnv} +% \begin{macro}{\Describe@Env} +% \changes{v1.5v}{1990/01/28}{Macro added.} +% \changes{v1.5j}{1989/06/09}{\cs{ignorespaces} added as a temporary +% fix} +% The |\DescribeMacro| and |\DescribeEnv| macros should +% print their arguments in the margin and produce an index entry. +% We simply use |\marginpar| to get the desired result. This +% is however not the best solution because the labels might be +% slightly misplaced. One also might get a lot of `marginpar moved' +% messages which are hard-wired into the \LaTeX{} output +% routine.\footnote{It might be better to change these macros into +% environments like the \textsf{macro} environment.} First we change +% to horizontal mode if necessary. The \LaTeX{} macros +% |\@bsphack| and |\@esphack| are used to make those +% commands invisible (i.e.\ to normalize the surrounding space and +% to make the |\spacefactor| transparent). +% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.} +% \begin{macrocode} +\def\DescribeMacro{\leavevmode\@bsphack +% \end{macrocode} +% When documenting the code for the \texttt{amstex.sty} option we +% encountered a bug: the |\catcode| of |@| was active and +% therefore couldn't be used in command names. So we first have to +% make sure that we get all |\catcode|s right by calling +% |\MakePrivateLetters| inside a group. Then we call +% |\Describe@Macro| to do the work. +% \changes{v2.0g}{1999/03/22}{Parse backslash as letter in argument +% to \cs{DescribeMacro}.} +% \changes{v2.0h}{1999/03/25}{Correct errors introduced in v2.0g.} +% \begin{macrocode} + \begingroup\MakePrivateLetters\Describe@Macro} +\def\Describe@Macro#1{\endgroup + \marginpar{\raggedleft\PrintDescribeMacro{#1}}% +% \end{macrocode} +% Note the use of |\raggedleft| to place the output flushed +% right. Finally we call a macro which produces the actual index +% entry and finish with |\@esphack| to leave no +% trace.\footnote{The whole mechanism won't work because +% of the \texttt{\bslash leavevmode} in front. +% As a temporary change \texttt{\bslash ignorespaces} +% is added.} +% \begin{macrocode} + \SpecialUsageIndex{#1}\@esphack\ignorespaces} +% \end{macrocode} +% The |\DescribeEnv| macro is completely analogous. +% \changes{v1.5v}{1990/01/28}{\cs{MakePrivateLetters} added.} +% \begin{macrocode} +\def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters + \Describe@Env} +\def\Describe@Env#1{\endgroup + \marginpar{\raggedleft\PrintDescribeEnv{#1}}% + \SpecialEnvIndex{#1}\@esphack\ignorespaces} +% \end{macrocode} +% To put the labels in the left margin we have to use the +% |\reversemarginpar| declaration. (This means that the +% \texttt{doc.sty} can't be used with all classes or packages.) +% We also +% make the |\marginparpush| zero and |\marginparwidth| suitably +% wide. +% \changes{v1.5d}{1989/04/28}{\cs{marginparwidth} setting added.} +% \begin{macrocode} +\reversemarginpar +\setlength\marginparpush{0pt} \setlength\marginparwidth{8pc} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bslash} +% \changes{v1.7a}{1992/02/26}{Moved \cs{bslash} documentation to `user +% interface' part} +% We start a new group in which to hide the alteration of +% |\catcode|$\,$s, and make \verb+|+ introduce commands, +% whilst |\| becomes an `other' character. +% +% \begin{macrocode} +{\catcode`\|=\z@ \catcode`\\=12 +% \end{macrocode} +% Now we are able to define |\bslash| (globally) to generate a +% backslash of |\catcode| `other'. We then close this group, +% restoring original |\catcode|$\,$s. +% \SpecialEscapechar{\|} +% \begin{macrocode} +|gdef|bslash{\}} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{environment}{verbatim} +% \begin{environment}{verbatim*} +% \changes{v1.7i}{1992/07/12}{Added changed definition for verbatim!*.} +% The \textsf{verbatim} environment holds no secrets; it consists of +% the normal \LaTeX{} environment. We also set the +% |\@beginparpenalty| and change to the font given by +% |\MacroFont|. +% \begin{macrocode} +\def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim + \MacroFont \frenchspacing \@vobeyspaces \@xverbatim} +% \end{macrocode} +% We deal in a similar way with the star form of this environment. +% \begin{macrocode} +\@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim + \MacroFont \@sxverbatim} +% \end{macrocode} +% \end{environment} +% \end{environment} +% +% \begin{macro}{\@verbatim} +% Additionally we redefine the |\@verbatim| macro so that it +% suppresses |%| characters at the beginning of the line. The +% first lines are copied literally from \texttt{latex.tex}. +% \changes{v1.7i}{1992/07/12}{Added \cs{@@par} to clear possible +% \cs{parshape}.} +% \begin{macrocode} +\def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi + \leftskip\@totalleftmargin\rightskip\z@ + \parindent\z@\parfillskip\@flushglue\parskip\z@ + \@@par + \@tempswafalse +% \end{macrocode} +% |\@verbatim| sets |^^M|, the end of line character, to +% be equal to |\par|. This control sequence is redefined +% here; |\@@par| is the paragraph primitive of \TeX. +% \changes{v1.7c}{1992/03/24}{Added \cs{interlinepenalty} to +% \cs{par} from verbatim.sty} +% \begin{macrocode} + \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par + \penalty\interlinepenalty +% \end{macrocode} +% We add a control sequence |\check@percent| to the definition +% of |\par| whose task it is to check for a percent character. +% \begin{macrocode} + \check@percent}% +% \end{macrocode} +% The rest is again copied literally from \texttt{latex.tex} (less +% "\tt"). +% \changes{v1.7a}{1992/02/26}{Removed redundant \cs{tt}.} +% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim, +% which handles more ligatures.} +% \begin{macrocode} + \obeylines + \let\do\do@noligs \verbatim@nolig@list + \let\do\@makeother \dospecials} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\check@percent} +% Finally we define |\check@percent|. Since this must compare a +% character with a percent sign we must first (locally) change +% percent's |\catcode| so that it is seen by \TeX. The definition +% itself is nearly trivial: grab the following character, check if +% it is a |%|, and insert it again if not. At the end of the +% \textsf{verbatim} environment this macro will peek at the next +% input line. In that case the argument to |\check@percent| might +% be a |\par| or a macro with arguments. Therefore we make the +% definition |\long| (|\par| allowed) and use the normal |\next| +% mechanism to reinsert the argument after the |\fi| if necessary. +% \changes{v1.5i}{1989/06/07}{Definition changed to `long'} +% \changes{v1.5i}{1989/06/07}{Macro \cs{next} used to guard against +% macro with arguments} +% There is a subtle problem here, the equal sign between +% |\next| and |#1| is actually necessary. Do you see why? +% The omission of this token once caused a funny error. +% \changes{v1.5u}{1989/11/14}{equal sign added.} +% \begin{macrocode} +{\catcode`\%=12 + \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else + \let\next=#1\fi \next}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\verb} +% \changes{v1.7a}{1992/02/27}{Now warns about newlines (from +% newdoc with `@noligs added).} +% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX \cs{verb}} +% We re-define "\verb" to check for newlines in its argument since a +% missing delimiter is difficult to detect in \DOC{} source. +% The code is the same as in \texttt{latex.tex} of September 19, 1993. +% Perhaps there should be a font-changing +% hook rather than just using "\ttfamily", but if so it probably should be +% different from "\MacroFont" since that normally includes "\small" +% and would look wrong inline. +% \changes{v1.7a}{1992/02/28}{Added math mode check (from verbatim.sty)} +% \begin{macrocode} +\def\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi + \bgroup \let\do\do@noligs \verbatim@nolig@list + \ttfamily \verb@eol@error \let\do\@makeother \dospecials + \@ifstar{\@sverb}{\@vobeyspaces \frenchspacing \@sverb}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\verb@balance@group} +% \begin{macro}{\verb@egroup} +% \begin{macro}{\verb@eol@error} +% \changes{v1.8b}{1993/09/21}{Renamed \cs{verb@err} to +% \cs{verb@eol@error}, as in new LaTeX verbatim.} +% \begin{macrocode} +\let\verb@balance@group\@empty + +\def\verb@egroup{\global\let\verb@balance@group\@empty\egroup} + +\begingroup + \obeylines% + \gdef\verb@eol@error{\obeylines% + \def^^M{\verb@egroup\@latex@error{% + Text for \noexpand\verb command ended by end of line}\@ehc}}% +\endgroup +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\@sverb} +% \changes{v1.7a}{1992/02/27}{Added for \cs{verb} change.} +% \changes{v1.7a}{1992/02/28}{Now same as in verbatim.sty.} +% \changes{v1.8b}{1993/09/21}{Changed to conform to new LaTeX verbatim, +% which has better error trapping.} +% See \cite{art:verbatim} for commentary. +% \begin{macrocode} +\def\@sverb#1{% + \catcode`#1\active \lccode`\~`#1% + \gdef\verb@balance@group{\verb@egroup + \@latex@error{Illegal use of \noexpand\verb command}\@ehc}% + \aftergroup\verb@balance@group + \lowercase{\let~\verb@egroup}} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\verbatim@nolig@list} +% \begin{macro}{\do@noligs} +% These macros replace the old "\@noligs" mechanism by an +% extensible version to allow more ligatures to be added. +% \begin{macrocode} +\def\verbatim@nolig@list{\do\`\do\<\do\>\do\,\do\'\do\-} +\def\do@noligs#1{% + \catcode`#1\active + \begingroup + \lccode`\~=`#1\relax + \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1}}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\macro} +% \begin{macro}{\m@cro@} +% \changes{v1.5v}{1990/01/28}{\cs{macro@} renamed to \cs{m@cro@} +% since AmSTeX +% defines another macro of the same name.} +% \begin{macro}{\macro@cnt} +% \label{page:macro} The \textsf{macro} environment is implemented as +% a \textsf{trivlist} environment, whereby in order that the macro +% names can be placed under one another in the margin +% (corresponding to the macro's nesting depth), the macro +% |\makelabel| must be altered. In order to store the nesting +% depth, we use a counter. We also need a counter to count the +% number of nested \textsf{macro} environments. +% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} +% \changes{v1.9k}{1994/02/22}{Fix probably no longer necessary} +% \begin{macrocode} +\newcount\macro@cnt \macro@cnt=0 +% \end{macrocode} +% The environment takes an argument---the macro name to be +% described. Since this name may contain special `letters' we have +% to re-|\catcode| them before scanning the argument. This is done +% by the |\MakePrivateLetters| macro. +% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} +% \changes{v1.7a}{1992/02/26}{Catcode backslash to other (from newdoc).} +% \changes{v1.9k}{1994/02/22}{Don't omit extra group} +% \begin{macrocode} +\def\macro{\begingroup + \catcode`\\12 + \MakePrivateLetters \m@cro@ \iftrue} +% \end{macrocode} +% +% \begin{environment}{environment} +% \changes{v1.8c}{1993/10/25}{Environment added} +% The ``environment'' envrionment will be implemented just like the +% ``macro'' environment flagging any differences in the code by +% passing |\iffalse| or |\iftrue| to the |\m@cro@| environment +% doing the actual work. +% \begin{macrocode} +\def\environment{\begingroup + \catcode`\\12 + \MakePrivateLetters \m@cro@ \iffalse} +% \end{macrocode} +% \end{environment} +% +% After scanning the argument we close the group to get the normal +% |\catcode|$\,$s back. Then we assign a special value to +% |\topsep| and start a \textsf{trivlist} environment. +% \changes{v1.5f}{1989/05/07}{MacroTopsep parameter added.} +% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} +% \changes{v1.8c}{1993/10/25}{Support ``environment'' env} +% \changes{v1.9k}{1994/02/22}{Remove \cs{macro@level}} +% \begin{macrocode} +\long\def\m@cro@#1#2{\endgroup \topsep\MacroTopsep \trivlist +% \end{macrocode} +% We also save the name being described in |\saved@macroname| for +% use in conjunction with the |\changes| macro. +% \begin{macrocode} + \edef\saved@macroname{\string#2}% + #1 +% \end{macrocode} +% If documenting an environment we put is name in |\saved@indexname| +% otherwise the name without the backslash. +% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} +% \begin{macrocode} + \let\saved@indexname\saved@macroname + \else + \edef\saved@indexname{\expandafter\@gobble\string#2}% + \fi +% \end{macrocode} +% Now there follows a variation of |\makelabel| which is used +% should the environment not be nested, or should it lie between +% two successive |\begin{macro}| instructions or explanatory +% text. One can recognize this with the switch |\if@inlabel| +% which will be |true| in the case of successive |\item| +% commands. +% \begin{macrocode} + \def\makelabel##1{\llap{##1}}% +% \end{macrocode} +% If |@inlabel| is |true| and if $\verb=\macro@cnt= > 0$ +% then the above definition needs to be changed, because in this +% case \LaTeX{} would otherwise put the labels all on the same line +% and this would lead to them being overprinted on top of each +% other. Because of this |\makelabel| needs to be redefined +% in this case. +% \begin{macrocode} + \if@inlabel +% \end{macrocode} +% If |\macro@cnt| has the value $1$, then we redefine +% |\makelabel| so that the label will be positioned in the +% second line of the margin. As a result of this, two macro names +% appear correctly, one under the other. It's important whilst +% doing this that the generated label box is not allowed to have +% more depth than a normal line since otherwise the distance +% between the first two text lines of \TeX{} will be incorrectly +% calculated. The definition should then look like: +%\begin{verbatim} +% \def\makelabel##1{\llap{\vtop to \baselineskip +% {\hbox{\strut}\hbox{##1}\vss}}} +%\end{verbatim} +% Completely analogous to this is the case where labels need to be +% placed one under the other. The lines above are only an example +% typeset with the \textsf{verbatim} environment. To produce the real +% definition we save the value of |\macro@cnt| in +% |\count@| and empty the temp macro |\@tempa| for later +% use. +% \begin{macrocode} + \let\@tempa\@empty \count@\macro@cnt +% \end{macrocode} +% In the following loop we append for every already typeset label +% an |\hbox{\strut}| to the definition of |\@tempa|. +% \begin{macrocode} + \loop \ifnum\count@>\z@ + \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat +% \end{macrocode} +% Now be put the definition of |\makelabel| together. +% \changes{v1.5b}{1989/04/27}{vbox to vtop changed in makelabel (test)} +% \changes{v1.5e}{1989/04/28}{ht strutbox changed to baselineskip +% (test)} +% \begin{macrocode} + \edef\makelabel##1{\llap{\vtop to\baselineskip + {\@tempa\hbox{##1}\vss}}}% +% \end{macrocode} +% Next we increment the value of the nesting depth counter. This +% value inside the \textsf{macro} environment is always at least one +% after this point, but its toplevel definition is zero. Provided +% this environment has been used correctly, $|\macro@cnt|=0$ +% should not occur when |@inlabel|=\textsf{true}. It is +% however possible if this environment is used within other list +% environments (but this would have little point). +% \begin{macrocode} + \advance \macro@cnt \@ne +% \end{macrocode} +% If |@inlabel| is false we reset |\macro@cnt| assuming +% that there is enough room to print the macro name without +% shifting. +% \begin{macrocode} + \else \macro@cnt\@ne \fi +% \end{macrocode} +% Now the label will be produced using |\item|. The following +% line is only a hack saving the day until a better solution is +% implemented. We have to face two problems: the argument might be +% a |\par| which is forbidden in the argument of other macros +% if they are not defined as |\long|, or it is something like +% |\iffalse| or |\else|, i.e.\ something which will be +% misinterpreted when \TeX{} is skipping conditional text. In both +% cases |\item| will bomb, so we protect the argument by using +% |\string|. +% \begin{macrocode} + \edef\@tempa{\noexpand\item[% +% \end{macrocode} +% Depending on whether we are inside a ``macro'' or ``environment'' +% environment we use |\PrintMacroName| or |\PrintEnvName| to +% display the name. +% \begin{macrocode} + #1% + \noexpand\PrintMacroName + \else + \noexpand\PrintEnvName + \fi + {\string#2}]}% + \@tempa +% \end{macrocode} +% At this point we also produce an index entry. Because it is not +% known which index sorting program will be used, we do not use the +% command |\index|, but rather a command +% |\SpecialMainIndex| after advancing the counter for indexing +% by line number. This may be redefined by the user in +% order to generate an index entry which will be understood by the +% index program in use (note the definition of +% |\SpecialMainIndex| for our installation). +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \changes{v1.9u}{1995/08/06}{Removed brace group which +% killed \cs{DoNotIndex}} +% We advance the current codeline number and after producing an +% index entry revert to the original value +% \begin{macrocode} + \global\advance\c@CodelineNo\@ne +% \end{macrocode} +% Again the macro to call depends on the environment we are +% actually in. +% \begin{macrocode} + #1% + \SpecialMainIndex{#2}\nobreak + \DoNotIndex{#2}% + \else + \SpecialMainEnvIndex{#2}\nobreak + \fi + \global\advance\c@CodelineNo\m@ne +% \end{macrocode} +% The |\nobreak| is needed to prevent a page break after the +% |\write| produced by the |\SpecialMainIndex| macro. We +% exclude the new macro in the cross-referencing feature, to +% prevent spurious non-main entry references. Regarding possibly +% problematic arguments, the implementation takes +% care of |\par| and the conditionals are uncritical. +% \changes{v1.7a}{1992/03/02}{Removed redundant code checking for +% \cs{par}.}^^A +% +% Because the space symbol should be ignored between the +% |\begin{macro}{...}| and the following text we must take +% care of this with |\ignorespaces|. +% \begin{macrocode} + \ignorespaces} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% \begin{macro}{\endmacro} +% \begin{macro}{\endenvironment} +% Older releases of this environment omit the |\endgroup| token, +% when being nested. This was done to avoid unnecessary stack usage. +% However it does not work if \textsf{macro} and +% \textsf{environment} environments are mixed, therefore we now +% use a simpler approach. +% \changes{v1.5k}{1989/08/17}{Fix for save stack problem.} +% \changes{v1.9k}{1994/02/22}{Don't checkfor nesting} +% \begin{macrocode} +\let\endmacro \endtrivlist +\let\endenvironment\endmacro +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\MacroTopsep} +% Here is the default value for the |\MacroTopsep| parameter +% used above. +% \begin{macrocode} +\newskip\MacroTopsep \MacroTopsep = 7pt plus 2pt minus 2pt +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \subsection{Formatting the margin} +% +% The following three macros should be user definable. +% Therefore we define those macros only if they have not already +% been defined. +% +% \begin{macro}{\PrintMacroName} +% \begin{macro}{\PrintEnvName} +% \begin{macro}{\PrintDescribeMacro} +% \begin{macro}{\PrintDescribeEnv} +% The formatting of the macro name in the left margin is done by +% these macros. We first set a |\strut| to get the height and +% depth of the normal lines. Then we change to the +% |\MacroFont| using |\string| to |\catcode| the +% argument to other (assuming that it is a macro name). Finally we +% print a space. The font change remains local since this macro +% will be called inside an |\hbox|. +% \begin{macrocode} +\@ifundefined{PrintMacroName} + {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{} +% \end{macrocode} +% We use the same formatting conventions when describing a macro. +% \begin{macrocode} +\@ifundefined{PrintDescribeMacro} + {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{} +% \end{macrocode} +% To format the name of a new environment there is no need to use +% |\string|. +% \begin{macrocode} +\@ifundefined{PrintDescribeEnv} + {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{} +\@ifundefined{PrintEnvName} + {\def\PrintEnvName#1{\strut \MacroFont #1\ }}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% \subsection{Creating index entries by scanning `macrocode'} +% +% The following macros ensure that index entries are created for each +% occurrence of a \TeX-like command (something starting with +% `|\|') providing indexing has been turned on with "\PageIndex" +% or "\CodelineIndex". With the default definitions of +% |\SpecialMainIndex|, etc., the index file generated is +% intended to be processed by Chen's \textsf{makeindex} program +% \cite{art:Chen}. +% +% +% Of course, in {\em this\/} package file itself we've sometimes had to +% make \verb+|+ take the r\^ole of \TeX's escape character to +% introduce command names at places where |\| has to belong to +% some other category. Therefore, we may also need to recognize +% \verb+|+ as the introducer for a command when setting the text +% inside the \textsf{macrocode} environment. Other users may have the +% need to make similar reassignments for their macros. +% +% +% \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar} +% \begin{macro}{\active@escape@char} +% \begin{macro}{\special@escape@char} +% The macro |\SpecialEscapechar| is used to denote a special escape +% character for the next \textsf{macrocode} environment. It has one +% argument---the new escape character given as a `single-letter' +% control sequence. Its main purpose is defining +% |\special@escape@char| to produce the chosen escape character +% |\catcode|$\,$d to 12 and |\active@escape@char| to produce the +% same character but with |\catcode| 13. +% +% The macro |\special@escape@char| is used to {\em print\/} +% the escape character while |\active@escape@char| is needed +% in the definition of |\init@crossref| to start the scanning +% mechanism. +% +% In the definition of |\SpecialEscapechar| we need an +% arbitrary character with |\catcode| 13. We use `\~{}' and +% ensure that it is active. The |\begingroup| is used to make +% a possible change local to the expansion of +% |\SpecialEscapechar|. +% \changes{v1.7g}{1992/06/19}{Making tilde active moved outside +% definition} +% \begin{macrocode} +\begingroup +\catcode`\~\active +\gdef\SpecialEscapechar#1{% + \begingroup +% \end{macrocode} +% Now we are ready for the definition of +% |\active@escape@char|. It's a little tricky: we first +% define locally the uppercase code of `\~{}' to be the new escape +% character. +% \begin{macrocode} + \uccode`\~`#1% +% \end{macrocode} +% Around the definition of |\active@escape@char| we place an +% |\uppercase| command. Recall that the expansion of +% |\uppercase| changes characters according to their +% |\uccode|, but leaves their |\catcode|$\,$s untouched +% (cf.\ \TeX{}book page 41). +% \begin{macrocode} + \uppercase{\gdef\active@escape@char{~}}% +% \end{macrocode} +% The definition of |\special@escape@char| is easier, we use +% |\string| to |\catcode| the argument of +% |\SpecialEscapechar| to 12 and suppress the preceding +% |\escapechar|. +% \begin{macrocode} + \escapechar\m@ne \xdef\special@escape@char{\string#1}% +% \end{macrocode} +% Now we close the group and end the definition: the value of +% |\escapechar| as well as the |\uccode| and +% |\catcode| of `\~{}' will be restored. +% \begin{macrocode} + \endgroup} +\endgroup +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +% \begin{macro}{\init@crossref} +% The replacement text of |\init@crossref| should fulfill the +% following tasks: +% \begin{itemize} +% \parindent4em +% \item[1)] +% |\catcode| all characters used in macro names to +% 11 (i.e.\ `letter'). +% \item[2)] +% |\catcode| the `|\|' character to 13 +% (i.e.\ `active'). +% \item[3a)] +% |\let| the `|\|' equal |\scan@macro| +% (i.e.\ start the macro scanning mechanism) if there is +% no special escape character (i.e.\ the +% |\special@escape@char| is `|\|'). +% \item[3b)] +% Otherwise |\let| it equal |\bslash|, i.e.\ +% produce a printable |\|. +% \item[4)] +% Make the \meta{special escape character} active. +% \item[5)] +% |\let| the active version of the special escape +% character +% (i.e.\ the expansion of |\active@escape@char|) equal +% |\scan@macro|. +% \end{itemize} +% The reader might ask why we bother to |\catcode| the +% `|\|' first to 12 (at the end of |\macro@code|) then +% re-|\catcode| it to 13 in order to produce a $|\|_{12}$ +% in case 3b) above. This is done because we have to ensure that +% `|\|' has |\catcode| 13 within the \textsf{macrocode} +% environment. Otherwise the delimiter for the argument of +% |\xmacro@code| would not be found (parameter matching +% depends on |\catcode|$\,$s). +% +% Therefore we first re-|\catcode| some characters. +% \begin{macrocode} +\begingroup \catcode`\|=\z@ \catcode`\\=\active +% \end{macrocode} +% We carry out tasks 2) and 3b) first. +% \SpecialEscapechar{\|} +% \begin{macrocode} +|gdef|init@crossref{|catcode`|\|active |let\|bslash +% \end{macrocode} +% Because of the popularity of the `|@|' character as a +% `letter' in macros, we normally have to change its +% |\catcode| here, and thus fulfill task 1). But the macro +% designer might use other characters as private letters as well, +% so we use a macro to do the |\catcode| switching. +% \SpecialEscapechar\| +% \begin{macrocode} + |MakePrivateLetters +% \end{macrocode} +% Now we |\catcode| the special escape character to 13 and +% |\let| it equal |\scan@macro|, i.e.\ fulfill tasks 4) +% and 5). Note the use of |\expandafter| to insert the chosen +% escape character saved in |\special@escape@char| and +% |\active@escape@char|. +% \SpecialEscapechar\| +% \begin{macrocode} + |catcode|expandafter`|special@escape@char|active + |expandafter|let|active@escape@char|scan@macro} +|endgroup +% \end{macrocode} +% If there is no special escape character, i.e.\ if +% |\SpecialEscapechar| is |\\|, the second last line will +% overwrite the previous definition of $|\|_{13}$. In this +% way all tasks are fulfilled. +% +% For happy documenting we give default values to +% |\special@escape@char| and |\active@escape@char| with +% the following line: +% \begin{macrocode} +\SpecialEscapechar{\\} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\MakePrivateLetters} +% Here is the default definition of this command, which makes just +% the |@| into a letter. The user may change it if he/she +% needs more or other characters masquerading as letters. +% \begin{macrocode} +\@ifundefined{MakePrivateLetters} + {\let\MakePrivateLetters\makeatletter}{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\close@crossref} +% At the end of a cross-referencing part we prepare ourselves for +% the next one by setting the escape character to `|\|'. +% \begin{macrocode} +\def\close@crossref{\SpecialEscapechar\\} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \subsection{Macros for scanning macro names} +% +% \begin{macro}{\scan@macro} +% \changes{v1.5k}{1989/09/04}{Support for checksum added.} +% \begin{macro}{\macro@namepart} +% The |\init@crossref| will have made |\active| our +% |\special@escape@char|, so that each +% |\active@escape@char| will invoke |\scan@macro| when +% within the \textsf{macrocode} environment. By this means, we can +% automatically add index entries for every \TeX-like command which +% is met whilst setting (in verbatim) the contents of +% \textsf{macrocode} environments. +% \begin{macrocode} +\def\scan@macro{% +% \end{macrocode} +% First we output the character which triggered this macro. Its +% version |\catcode|$\,$d to 12 is saved in +% |\special@escape@char|. We also call |\step@checksum| +% to generate later on a proper check-sum (see section +% \ref{sec:checksum} for details). +% \begin{macrocode} + \special@escape@char + \step@checksum +% \end{macrocode} +% If the \textsf{macrocode} environment contains, for example, the +% command |\\|, the second |\| should not start the +% scanning mechanism. Therefore we use a switch to decide if +% scanning of macro names is allowed. +% \begin{macrocode} + \ifscan@allowed +% \end{macrocode} +% The macro assembles the letters forming a \TeX\ command in +% |\macro@namepart| so this is initially cleared; we then set +% |\next| to the \textit{first\/} character following the +% |\| and call |\macro@switch| to determine whether that +% character is a letter or not. +% \begin{macrocode} + \let\macro@namepart\@empty + \def\next{\futurelet\next\macro@switch}% +% \end{macrocode} +% As you recognize, we actually did something else, because we have +% to defer the |\futurelet| call until after the final +% |\fi|. If, on the other hand, the scanning is disabled we +% simply |\let| |\next| equal `empty'. +% \begin{macrocode} + \else \let\next\@empty \fi +% \end{macrocode} +% Now we invoke |\next| to carry out what's needed. +% \begin{macrocode} + \next} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\ifscan@allowed} +% \begin{macro}{\scan@allowedtrue} +% \begin{macro}{\scan@allowedfalse} +% |\ifscan@allowed| is the switch used above to determine if +% the |\active@escape@char|\SpecialIndex{\active@escape@char} +% should start the macro scanning mechanism. +% \begin{macrocode} +\newif\ifscan@allowed \scan@allowedtrue +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\EnableCrossrefs} +% \begin{macro}{\DisableCrossrefs} +% At this point we might define two macros which allow the user to +% disable or enable the cross-referencing mechanism. Processing of +% files will be faster if only main index entries are generated +% (i.e., if |\DisableCrossrefs| is in force). +% \begin{macrocode} +\def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack} +% \end{macrocode} +% The macro |\EnableCrossrefs| will also disable any +% |\DisableCrossrefs| command encountered afterwards. +% \begin{macrocode} +\def\EnableCrossrefs{\@bsphack\scan@allowedtrue + \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +% \begin{macro}{\macro@switch} +% Now that we have the character which follows the escape character +% (in |\next|), we can determine whether it's a `letter' +% (which probably includes |@|). +% +% If it is, we let |\next| invoke a macro which assembles the +% full command name. +% \begin{macrocode} +\def\macro@switch{\ifcat\noexpand\next a% + \let\next\macro@name +% \end{macrocode} +% Otherwise, we have a `single-character' command name. For all +% those single-character names, we use |\short@macro| to +% process them into suitable index entries. +% \begin{macrocode} + \else \let\next\short@macro \fi +% \end{macrocode} +% Now that we know what macro to use to process the macro name, we +% invoke it~\ldots +% \begin{macrocode} + \next} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\short@macro} +% \changes{v1.5c}{1989/04/27}{Corrected bad bug by putting the +% scan@allowedfalse macro before printing +% the argument.} +% \changes{v1.7a}{1992/03/10}{Ensure character stored in +% \cs{macro@namepart} as `letter' so index exclusion works.} +% This macro will be invoked (with a single character as parameter) +% when a single-character macro name has been spotted whilst +% scanning within the \textsf{macrocode} environment. +% +% First we take a look at the |\index@excludelist| to see +% whether this macro name should produce an index entry. This is +% done by the |\ifnot@excluded| macro which assumes that the +% macro name is saved in |\macro@namepart|. The character +% mustn't be stored with a special category code or exclusion from +% the index won't work, so we employ the case-changing trick used +% elsewhere. Since the argument might be an active character, +% |\string| is used to normalize it. +% \changes{v2.0e}{1998/12/28}{Correctly use the case-changing trick.} +% \begin{macrocode} +\begingroup +\catcode`\&=12 +\gdef\short@macro#1{\begingroup + \uccode`\&=\expandafter`\string#1% + \uppercase{\def\x{\def\macro@namepart{&}}}% + \expandafter\endgroup\x + \ifnot@excluded +% \end{macrocode} +% If necessary the index entry is produced by the macro +% |\produce@index|. Depending on the actual character seen, +% this macro has to do different things, so we pass the character +% as an argument. +% \begin{macrocode} + \produce@index{#1}\fi +% \end{macrocode} +% Then we disable the cross-referencing mechanism with +% |\scan@allowedfalse| and print the actual character. The +% index entry was generated first to ensure that no page break +% intervenes (recall that a |^^M| will start a new line). +% \begin{macrocode} + \scan@allowedfalse#1% +% \end{macrocode} +% After typesetting the character we can safely enable the +% cross-referencing feature again. Note that this macro won't be +% called (since |\macro@switch| won't be called) if +% cross-referencing is globally disabled. +% \begin{macrocode} + \scan@allowedtrue } +\endgroup +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\produce@index} +% \changes{v1.4s}{1989/04/23}{Added noexpand to all +% \cs{if} tests +% to avoid garbage produced by new active chars} +% \changes{v1.4s}{1989/04/23}{Used \texttt{\protect\bslash string} for +% the same reason.} +% \changes{v1.5c}{1989/04/27}{Corrected bad bug by placing the +% scan@allowedfalse macro into short@macro} +% This macro is supposed to generate a suitable |\SortIndex| +% command for a given single-letter control sequence. We test +% first for the cases which involve active characters (i.e.\ the +% backslash, the special escape character (if any), the space and +% the |^^M|). Using the |\if| test (testing for +% character codes), we have to ensure that the argument isn't +% expanded. +% \begin{macrocode} +\def\produce@index#1{% + \if\noexpand#1\special@escape@char +% \end{macrocode} +% If the character is the special escape character (or the +% `|\|' in case there was none) the |\it@is@a| macro is +% used to produce the actual |\SortIndex| call. +% \begin{macrocode} + \scan@allowedfalse \it@is@a\special@escape@char \else +% \end{macrocode} +% Next comes the test for a `|\|' which must be the +% $|\|_{13}$ expanding to |\bslash|. +% \begin{macrocode} + \if\noexpand#1\bslash \it@is@a\bslash \else +% \end{macrocode} +% Another possibility is \verb*+ +$_{13}$. Recall that |\space| +% produces a \verb*+ +$_{10}$. +% \begin{macrocode} + \if\noexpand#1\space \it@is@a\space \else +% \end{macrocode} +% The last\footnote{Well, it isn't the last active character after +% all. I added \texttt{\bslash @noligs} some days ago and now +% \texttt{`} too is active. So we have to make sure that such +% characters don't get expanded in the index.} possibility of an +% active character is |^^M|\@. In this case we don't test for +% character codes, since it is easier to look if the character is +% equal to |\par|. (We are inside the \textsf{macrocode} +% environment.) +% \begin{macrocode} + \ifx#1\par +% \end{macrocode} +% If we end up here we have just scanned a |\^^M| or something +% similar. Since this will be treated like \verb*+\ + by \TeX{} we +% produce a corresponding index entry. +% \begin{macrocode} + \it@is@a\space \else +% \end{macrocode} +% If it is the token |\relax| we do nothing. This can't happen +% when the `doc' package is used in the way described here, but was +% added to allow extensions like the \texttt{idxverb} option. +% \changes{v1.5t}{1989/11/14}{Added \cs{relax} as a possible token to +% allow extensions.} +% \begin{macrocode} + \ifx#1\relax \else +% \end{macrocode} +% The next three branches are needed because of bugs in +% our \textsf{makeindex} program. You can't produce unbalanced index +% entries\footnote{This is possible for \TeX{} if you use +% \texttt{\string{$_{12}$ \rmfamily or +% \ttfamily\string}$_{12}$}, +% but \textsf{makeindex} will complain.} +% and you have to double a percent character. To get around these +% restrictions we use special macros to produce the |\index| +% calls.\footnote{Brian \textsc{Hamilton Kelly} has written fixes for +% all three +% bugs. When they've found their way through all +% installations, +% the lines above will be removed. See +% page~\pageref{bug:fixes} if you already have them. +% (I'm not sure which versions incorporate these, but +% 2.11 is OK. See also +% \pageref{makeindex:version}.)} +% \begin{macrocode} + \if\noexpand#1\bgroup \LeftBraceIndex \else + \if\noexpand#1\egroup \RightBraceIndex \else + \if\noexpand#1\percentchar \PercentIndex \else +% \end{macrocode} +% All remaining characters are used directly to produce their index +% entries. This is possible even for the characters which have +% special meanings in the index program, provided we quote the +% characters. (This is correctly done in |\it@is@a|.) +% \begin{macrocode} + \it@is@a{\string#1}% +% \end{macrocode} +% We now need a whole pile of |\fi|$\,$s to match up with +% the |\if|$\,$s. +% \begin{macrocode} + \fi \fi \fi \fi \fi \fi \fi \fi} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\macro@name} +% We now come to the macro which assembles command names which +% consist of one or more `letters' (which might well include +% |@| symbols, or anything else which has a |\catcode| of +% 11). +% +% To do this we add the `letter' to the existing definition of +% |\macro@namepart| (which you will recall was originally set +% to |\@empty|). +% \begin{macrocode} +\def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}% +% \end{macrocode} +% Then we grab hold of the {\em next\/} single character and let +% |\more@macroname| determine whether it belongs to the letter +% string forming the command name or is a `non-letter'. +% \begin{macrocode} + \futurelet\next\more@macroname} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \begin{macro}{\more@macroname} +% +% This causes another call of |\macro@name| to add in the next +% character, if it is indeed a `letter'. +% \begin{macrocode} +\def\more@macroname{\ifcat\noexpand\next a% + \let\next\macro@name +% \end{macrocode} +% Otherwise, it finishes off the index entry by invoking +% |\macro@finish|. +% \begin{macrocode} + \else \let\next\macro@finish \fi +% \end{macrocode} +% Here's where we invoke whatever macro was |\let| equal to +% |\next|. +% \begin{macrocode} + \next} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \begin{macro}{\macro@finish} +% When we've assembled the full `letter'-string which forms the +% command name, we set the characters forming the entire command +% name, and generate an appropriate |\index| command (provided +% the command name is not on the list of exclusions). The +% `|\|' is already typeset; therefore we only have to output +% all `letters' saved in |\macro@namepart|. +% \begin{macrocode} +\def\macro@finish{% + \macro@namepart +% \end{macrocode} +% Then we call |\ifnot@excluded| to decide whether we have to +% produce an index entry. The construction with |\@tempa| is +% needed because we want the expansion of |\macro@namepart| in +% the |\index| command.\footnote{The \texttt{\bslash index} +% command will expand its argument in the \texttt{\bslash output} +% routine. At this time \texttt{\bslash macro@namepart} might have a +% new value.} +% \begin{macrocode} + \ifnot@excluded + \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}% + \@tempa \fi} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \subsection[The index exclude list]{The index exclude +% list\footnotemark} +% \footnotetext{Warning: the incomplete commentary on +% \texttt{\bslash DoNotIndex} and the macros it calls +% was written by Dave Love.} +% +% The internal form of the index exclude list is +% \begin{quote} +% \meta{macro name}|,|\meta{macro name}|,| +% \ldots|,| +% \end{quote} +% where \meta{macro name} is a macro name like +% $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$. Note that the "\" +% has category `other' and the other characters in the name are all +% `letter', regardless of their normal category. +% +% \begin{macro}{\DoNotIndex} +% This macro is used to suppress macro names in the index. It +% starts off with a new group because we have to change the +% |\catcode|$\,$s of all characters which belong to `letters' +% while macros are defined. +% \begin{macrocode} +\def\DoNotIndex{\begingroup \MakePrivateLetters + \catcode`\\12 +% \end{macrocode} +% Then we call the macro which actually reads the argument given by +% the user. +% \begin{macrocode} + \do@not@index} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\do@not@index} +% We make the |\do@not@index| macro |\long| +% since the user might want to exclude the |\par| +% macro. +% \begin{macrocode} +\long\def\do@not@index#1{% +% \end{macrocode} +% It just adds to a token list after finishing the group in which +% the catcodes were changed. +% \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.} +% \begin{macrocode} + \endgroup + \addto@hook\index@excludelist{#1,}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\addto@hook} +% The code for adding tokens (the second argument) to a token list +% (the first argument) is taken from~\cite{art:verbatim}, but it needs +% to be "\long" in case "\par" is amongst the tokens. +% \begin{macrocode} +\long\def\addto@hook#1#2{#1\expandafter{\the#1#2}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\index@excludelist} +% We need an initially-empty register for the excluded list. +% \begin{macrocode} +\newtoks\index@excludelist +\index@excludelist{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ifnot@excluded} +% \changes{v1.7a}{1992/02/26}{Replaced with newdoc version.} +% \begin{macro}{\expanded@notin} +% Now we take a look at the |\index@excludelist| to see +% whether a macro name saved in |\macro@namepart| should +% produce an index entry. This macro is a pseudo |\if|; it +% should expand to |\iftrue| or |\iffalse| depending on +% the contents of |\index@excludelist|. +% \begin{macrocode} +\begingroup +% \end{macrocode} +% First we change "\catcode"s so that "\" is `other' and "|" a +% temporary for the escape character. This is necessary since our +% macro names are stored that way in the "\index@excludelist". +% \begin{macrocode} +\catcode`\|=0% +\catcode`\\=12 +% \end{macrocode} +% Then we define "\ifnot@excluded" to call "\expanded@notin" with +% two arguments: the first is the string "\" followed by the +% contents of "\macro@namepart" followed by a "," and the second is +% "\the" followed by "\index@excludelist". To achieve the expansion +% of "\macro@namepart", i.e.\ to pass its contents, we need a +% suitable number of "\expandafter"s. +% \SpecialEscapechar{\|} +% \begin{macrocode} +|gdef|ifnot@excluded{|expandafter + |expanded@notin|expandafter{|expandafter + \|macro@namepart,}{|the|index@excludelist}} +|endgroup +% \end{macrocode} +% The macro "\expanded@notin" now does the dirty work. It first +% defines a macro "\in@@" with a very special parameter text. If +% you look closely "\in@@" has three arguments, the first one is +% delimited by the first argument of "\expanded@notin" (i.e.\ by +% the string starting with a "\" and ending with a "," above), the +% second is undelimited (which means that it will get the next +% token after our string, and the third is delimited again and will +% get the rest up to the token "\in@@". In other words the token +% "\in@@" is also used as a delimiter. +% \begin{macrocode} +\def\expanded@notin#1#2{% + \def\in@@##1#1##2##3\in@@{% +% \end{macrocode} +% Now the replacement text simply compares the second argument +% (i.e.\ the undelimited one after our string) to the token +% "\expanded@notin". This is an unclosed "\ifx" statement which +% means that this macro behaves similar to a normal \TeX{} +% conditional. +% \begin{macrocode} + \ifx\expanded@notin##2}% +% \end{macrocode} +% After all these preparations we call "\in@@". First we expand the +% token after "\in@@" (which is "\the" from the second argument to +% "\expanded@notin"). As a result we get the contents of the +% "\index@excludelist" inserted after "\in@@". After this contents +% we add once more the string we are looking for, then the token +% "\expanded@notin" and finally the token "\in@@". +% \begin{macrocode} + \expandafter\in@@#2#1\expanded@notin\in@@} +% \end{macrocode} +% Now what happens when the macro "\in@@" above gets called? The +% first argument to "\in@@" is delimited by our string. In other +% words it will get everything from the contents of +% "\index@excludelist" before this string. If the string is not in +% "\index@excludelist" then it gets the whole contents, since after +% it we had inserted the string one more. In this case the next +% token is "\expanded@notin" which gets assigned to the second +% argument and the third argument will be empty. If, on the other +% hand, the string was inside "\index@excludelist" then the second +% argument will not be the token "\expanded@notin" and the third +% argument will be all the garbage up to "\in@@". Therefore testing +% the seconded argument, as done in the definition of "\in@@" will +% tell us whether or not the string is in "\index@includelist" and +% this was exactly what we wanted. (Deep breath.) You got +% that?\footnote{\TeX{}book page 125. The code described above is +% originally due to Michael Spivak who used a similar method within +% the \AmSTeX{} macros.} +% \end{macro} +% \end{macro} +% +% +% +% +% +% +% +% \subsection{Macros for generating index entries} +% +% Here we provide default definitions for the macros invoked to create +% index entries; these are either invoked explicitly, or automatically +% by |\scan@macro|. As already mentioned, the definitions given +% here presuppose that the |.idx| file will be processed by +% Chen's \textsf{makeindex} program --- they may be redefined for use +% with the user's favourite such program. +% +% To assist the reader in locating items in the index, all such +% entries are sorted alphabetically {\em ignoring\/} the initial +% `|\|'; this is achieved by issuing an |\index| command which +% contains the `actual' operator for \textsf{makeindex}. The default +% value for the latter operator is `|@|', but the latter character is +% so popular in \LaTeX\ package files that it is necessary to substitute +% another character. This is indicated to \textsf{makeindex} by means +% of an `index style file'; the character selected for this function +% is |=|, and therefore this character too must be specially treated +% when it is met in a \TeX\ command. A suitable index style file is +% provided amongst the supporting files for this style file in +% \texttt{gind.ist} and is generated from this source by processing +% with \texttt{docstrip} to extract the module \textbf{gind}. A +% similar style file \texttt{gglo.ist} is supplied for sorting the +% change information in the glossary file and is extracted as module +% \textbf{gglo}. First of all we add some information to the front of +% the \texttt{.ist} files. \changes{v1.7a}{1992/03/11}{glo.ist and +% gind.ist now derivable from doc.dtx with docstrip.} +% \begin{macrocode} +% +%<+gind|gglo>%% This is a MAKEINDEX style file which should be used to +%<+gind>%% generate the formatted index for use with the doc +%<+gglo>%% generate the formatted change history for use with the doc +%<+gind|gglo>%% package. The TeX commands used below are defined in +%<+gind|gglo>%% doc.sty. The commands for MAKEINDEX like `level' +%<+gind|gglo>%% `item_x1' are described in `` Makeindex, A General +%<+gind|gglo>%% Purpose, Formatter-Independent Index Processor'' by +%<+gind|gglo>%% Pehong Chen. +%<+gind|gglo> +% \end{macrocode} +% +% \begin{macro}{\actualchar} +% \begin{macro}{\quotechar} +% \begin{macro}{\levelchar} +% First come the definitions of |\actualchar|, +% |\quotechar| and |\levelchar|. Note, that our defaults +% are not the ones used by the \textsf{makeindex} program without a +% style file. +% \begin{macrocode} +%<*package> +\@ifundefined{actualchar}{\def\actualchar{=}}{} +\@ifundefined{quotechar}{\def\quotechar{!}}{} +\@ifundefined{levelchar}{\def\levelchar{>}}{} +% +%<+gind|gglo>actual '=' +%<+gind|gglo>quote '!' +%<+gind|gglo>level '>' +%<*package> +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\encapchar} +% The \textsf{makeindex} default for the |\encapchar| isn't +% changed. +% \begin{macrocode} +\@ifundefined{encapchar}{\def\encapchar{|}}{} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\verbatimchar} +% We also need a special character to be used as a delimiter for +% the |\verb*| command used in the definitions below. +% \begin{macrocode} +\@ifundefined{verbatimchar}{\def\verbatimchar{+}}{} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\SpecialIndex} +% The |\SpecialIndex| command creates index entries for +% macros. If the argument is |\|$xyz$, the command produces +% \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}| +% given the above defined defaults for |\actualchar|, +% |\quotechar| and |\verbatimchar|. We first remove the +% initial `|\|' to get a better index. +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \begin{macrocode} +\def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble + \string#1\actualchar +% \end{macrocode} +% Then follows the actual entry. A |\quotechar| is placed +% before the |*| to allow its use as a special \textsf{makeindex} +% character. Again |\@bsphack| and |\@esphack| are used +% to make the macros invisible. +% \begin{macrocode} + \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}% + \@esphack} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\SpecialMainIndex} +% \begin{macro}{\SpecialMainEnvIndex} +% \begin{macro}{\SpecialUsageIndex} +% The |\SpecialMainIndex| macro is used to cross-reference the +% names introduced by the \textsf{macro} environment. The action is +% as for |\SpecialIndex|, except that \textsf{makeindex} is +% instructed to `encap'sulate the entry with the string +% \verb=|main= to cause it to generate a call of the |\main| +% macro. +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \changes{v2.0c}{1998/08/22}{Correctly handle single character +% control sequences like \cs{<}.} +% +% |\SpecialMainIndex| passes the macro name to be indexed on to the +% macro |\SpecialIndex@|. +% \begin{macrocode} +\def\SpecialMainIndex#1{\@bsphack\SpecialIndex@{#1}{\encapchar main}% + \@esphack} +% \end{macrocode} +% +% \begin{macro}{\SpecialIndex@} +% \changes{v2.0c}{1998/08/22}{Macro added.} +% \changes{v2.0f}{1999/02/27}{Temp fix to allow strange code in arg 1 +% (PR 2968)} +% The macro |\SpecialIndex@| does the real work for |\SpecialMainIndex| +% and |\SpecialUsageIndex|. It takes two arguments: the macro to be +% indexed (as a control sequence or list of character tokens) and the +% additional text for the index. +% \changes{v2.0g}{1999/03/22}{Correct so-called temp fix. I'm not going to +% explain this.} +% \begin{macrocode} +\begingroup + \catcode`\|=0 + \catcode`\\=12 + |gdef|@SpecialIndexHelper@#1#2|@nil{% + |if |noexpand#1\% + |gdef|@gtempa{#2}% + |else + |begingroup + |escapechar|m@ne + |expandafter|gdef|expandafter|@gtempa|expandafter{|string#1#2}% + |endgroup + |fi} +|endgroup +\def\SpecialIndex@#1#2{% +% \end{macrocode} +% The first thing it does is to convert the macro into a list of +% characters. Note that a character token list remains (mostly) unchanged. +% \begin{macrocode} + \@SpecialIndexHelper@#1\@nil +% \end{macrocode} +% The macro name \verb*|\ | has to handled in a special way. The reason +% is that the space token is skipped when \TeX\ is scanning macro +% parameters, so that the trick used below will not work. +% So, we check whether the replacement text of |\@tempa| starts with +% a space token and write the appropriate index entry. +% \begin{macrocode} + \def\@tempb{ }% + \ifcat \@tempb\@gtempa + \special@index{\quotechar\space\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar\space\verbatimchar#2}% + \else +% \end{macrocode} +% Having handled this special case we have to distinguish control +% sequences consisting of one or more +% letters and those that consists of exactly one nonletter. As character +% tokens in the replacement text of the macro |\@gtempa| have all +% category code $12$ (other), this is difficult. For simplicity, we treat +% all single character control sequences alike, irregardless of whether +% the character is a letter or not. This has the advantage that it works +% even for strange settings of the category codes. +% +% We define a utility macro |\@tempb| with two arguments, the second +% delimited by |\relax|. +% It will be called later so that the first argument is the first character +% of the macro name, and the second argument receives the rest of the +% characters. So we distinguish the two cases above by checking whether +% the second argument is empty. +% \begin{macrocode} + \def\@tempb##1##2\relax{\ifx\relax##2\relax +% \end{macrocode} +% If so, we define the helper macro |\@tempc| in a way that it +% adds quotechars in critical places. +% \begin{macrocode} + \def\@tempc{\special@index{\quotechar##1\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar##1\verbatimchar#2}}% +% \end{macrocode} +% Otherwise we write the characters as in |\SpecialIndex|. +% \begin{macrocode} + \else + \def\@tempc{\special@index{##1##2\actualchar + \string\verb\quotechar*\verbatimchar + \bslash##1##2\verbatimchar#2}}% + \fi}% +% \end{macrocode} +% Now pass the list of characters to \@tempb and call \@tempc to do the +% work. +% \begin{macrocode} + \expandafter\@tempb\@gtempa\relax + \@tempc + \fi} +% \end{macrocode} +% \end{macro} +% +% Slightly simpler is the main entry for environments +% \changes{v1.9e}{1994/02/03}{use \cs{ttfamily} with \cs{string}} +% \changes{v1.9f}{1994/02/07}{should have used \cs{noexpand}, sigh} +% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}} +% \changes{v1.9j}{1994/02/16}{Back to string:-)} +% \changes{v1.9s}{1994/10/14}{Added missing percent and changed to +% \cs{ttfamily}} +% \changes{v2.0d}{1998/12/20}{Correctly handle second index entry +% by using \cs{special@index} not \cs{index} (PR/2928).} +% \changes{v2.0e}{1998/12/28}{Use \cs{string}, not \cs{protect} in argument to +% \cs{special@index}.} +% \changes{v2.1c}{2004/07/23}{environment names incorrectly sorted in +% index (pr/3615)} +% \begin{macrocode} +\def\SpecialMainEnvIndex#1{\@bsphack\special@index{% + #1\actualchar + {\string\ttfamily\space#1} + (environment)% + \encapchar main}% + \special@index{environments:\levelchar#1\actualchar{% + \string\ttfamily\space#1}\encapchar + main}\@esphack} +% \end{macrocode} +% The |\SpecialUsageIndex| is similar to |\SpecialMainIndex|, except +% that it uses the standard |\index| command. +% \texttt{usage} instead of \texttt{main}. +% \begin{macrocode} +\def\SpecialUsageIndex#1{\@bsphack + {\let\special@index\index\SpecialIndex@{#1}{\encapchar usage}}% + \@esphack} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% +% \begin{macro}{\SpecialEnvIndex} +% Indexing environments is done a little bit differently; we produce +% two index entries with the |\SpecialEnvIndex| macro: +% \changes{v1.9e}{1994/02/03}{The index needs protecting} +% \changes{v1.9g}{1994/02/08}{should have used \cs{noexpand}, sigh} +% \changes{v1.9i}{1994/02/11}{should have used \cs{protect}} +% \begin{macrocode} +\def\SpecialEnvIndex#1{\@bsphack +% \end{macrocode} +% First we sort the environment under its own name stating in the +% actual entry that this is an environment. +% \begin{macrocode} + \index{#1\actualchar{\protect\ttfamily#1} + (environment)\encapchar usage}% +% \end{macrocode} +% The second entry is sorted as a subitem under the key +% `environments:'. +% \changes{v2.1b}{2004/02/09}{environment names incorrectly sorted in +% index (pr/3615)} +% \begin{macrocode} + \index{environments:\levelchar#1\actualchar + {\protect\ttfamily#1}\encapchar usage}\@esphack} +% \end{macrocode} +% Because both entries correspond to `descriptions' of the +% environment, we encapsulate the page numbers with the +% |\usage| macro. +% \end{macro} +% +% +% +% \begin{macro}{\SortIndex} +% This macro is used to generate the index entries for any +% single-character command that |\scan@macro| encounters. The +% first parameter specifies the lexical order for the character, +% whilst the second gives the actual characters to be printed in +% the entry. It can also be used directly to generate index entries +% which differ in sort key and actual entry. +% \begin{macrocode} +\def\SortIndex#1#2{\index{#1\actualchar#2}} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\it@is@a} +% This macro is supposed to produce a correct |\SortIndex| +% entry for a given character. Since this character might be +% recognised as a `command' character by the index program used, +% all characters are quoted with the |\quotechar|. +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \begin{macrocode} +\def\it@is@a#1{\special@index{\quotechar #1\actualchar + \string\verb\quotechar*\verbatimchar + \quotechar\bslash\quotechar#1\verbatimchar}} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\LeftBraceIndex} +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \begin{macro}{\RightBraceIndex} +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} These +% two macros fix the problems with \textsf{makeindex}. Note the +% `hack' with |\iffalse}\fi| to satisfy both \TeX{} and the +% \textsf{makeindex} program. When this is written to the +% \texttt{.idx} file \TeX{} will see both braces (so we get a +% balanced text). \textsf{makeindex} will also see balanced braces +% but when the actual index entry is again processed by \TeX{} the +% brace in between |\iffalse| |\fi| will vanish. +% \begin{macrocode} +\@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{% + \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar + \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} + +\@ifundefined{RightBraceIndex}{\def\RightBraceIndex{% + \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb + \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\PercentIndex} +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \changes{v1.7c}{1992/03/25}{Default now for bug-fixed makeindex} +% By default we assume a version of \textsf{makeindex} without the +% percent bug is being used. +% \begin{macrocode} +\@ifundefined{PercentIndex} + {\def\PercentIndex{\it@is@a\percentchar}}{} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\OldMakeindex} +% \changes{v1.7c}{1992/03/26}{Replaced \cs{NewMakeIndex}.} +% \begin{macro}{\percentchar} +% Here is one solution for the percent bug in \textsf{makeindex}. +% The macro |\percentchar| denotes a |%|$_{12}$. Calling this from +% a package or the driver file sets things up +% appropriately.\label{bug:fixes} +% \begin{macrocode} +\def\OldMakeindex{\def\PercentIndex{% + \special@index{\quotechar\percentchar\actualchar\string\verb + \quotechar*\verbatimchar\quotechar\bslash + \percentchar\percentchar\verbatimchar}}} +{\catcode`\%=12 \gdef\percentchar{%}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +% +% +% \subsection{Redefining the \textsf{index} environment} +% +%\changes{v1.4r}{1989/04/22}{twocols env. placed into separate file} +%\changes{v1.4?}{1989/04/19}{use DEK's algorithm and implement +% a twocols env.} +%\changes{v1.4?}{1989/04/16}{changes to the index env.} +%\changes{v1.5a}{1989/04/26}{Now input multicol.sty instead of +% multcols.sty} +% \begin{macro}{\ifhave@multicol} +% \changes{v1.7a}{1992/03/04}{Added to support avoiding multicol.sty} By +% default the index is set in three columns, and will start on the +% same page as, and underneath, the last part of the text of the +% documented package file, if possible. The last page will be +% reformatted with balanced columns. This requires the +% \textsf{multicols} environment which is described elsewhere. So +% that \DOC{} can be run independently of +% \texttt{multicol.sty} we first check for its existence and set +% the "have@multicol" flag appropriately for use below. +% \changes{v1.9a}{1993/12/02}{Use \cs{IfFileExists}} +% \changes{v1.9m}{1994/04/28}{Use \cs{RequirePackage} to load multicol} +% \begin{macrocode} +\newif\ifhave@multicol +% \end{macrocode} +% If we found \texttt{multicol.sty} we use it. It would be nice to +% delay this (and the re-definition of "theindex") until we knew +% whether an index was actually required \ldots +% \begin{macrocode} +\IfFileExists{multicol.sty}{\have@multicoltrue + \RequirePackage{multicol}% + }{} +% \end{macrocode} +% \end{macro} + +% +% \begin{macro}{\IndexMin} +% \begin{macro}{\c@IndexColumns} +% \changes{v1.4t}{1989/04/24}{Counter added.} +% If \texttt{multicol} is in use, +% when the index is started we compute the remaining space on the +% current page; if it is greater than |\IndexMin|, the first +% part of the index will then be placed in the available space. +% The number of columns set is controlled by the counter +% |\c@IndexColumns| which can be changed with a +% |\setcounter| declaration. +% \begin{macrocode} +\newdimen\IndexMin \IndexMin = 80pt +\newcount\c@IndexColumns \c@IndexColumns = 3 +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{environment}{theindex} +% Now we start the multi-column mechanism, if appropriate. We use the +% \LaTeX{} counter |\c@IndexColumns| declared above to denote +% the number of columns and insert the `index prologue' text (which +% might contain a |\section| call, etc.). See the default +% definition for an example. +% \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.} +% \changes{v1.5a}{1989/04/26}{Call multicols first} +% \changes{v1.6e}{1991/04/03}{Turned into env definition.} +% \changes{v1.7a}{1992/03/04}{Include test for multicols.} +% \begin{macrocode} +\ifhave@multicol + \renewenvironment{theindex} + {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% +% \end{macrocode} +% Then we make a few last minute assignments to read the individual +% index |\item|$\,$s and finish off by ignoring any initial +% space. +% \begin{macrocode} + \IndexParms \let\item\@idxitem \ignorespaces}% +% \end{macrocode} +% +% \begin{macro}{\endtheindex} +% \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.} +% At the end of the index, we have only to end the \textsf{multicols} +% environment. +% \begin{macrocode} + {\end{multicols}} +% \end{macrocode} +% If we can't use \textsf{multicols} we warn the user and use an +% environment that's basically the one from \texttt{article.sty}. +% \begin{macrocode} +\else + \typeout{Can't find multicol.sty -- will use normal index layout if + necessary.} + \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi + \columnseprule \z@ \columnsep 35\p@ + \twocolumn[\index@prologue]% + \IndexParms \let\item\@idxitem \ignorespaces} + \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi} +\fi +% \end{macrocode} +% \end{macro} +% \end{environment} +% +% Here are the necessary \textsf{makeindex} declarations. We disable +% scanning of macro names inside the index with "\scan@allowedfalse\n" +% to avoid recursion. +% \begin{macrocode} +% +%<+gind>preamble +%<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n" +%<+gind>postamble +%<+gind>"\n\n \\end{theindex}\n" +%<*package> +% \end{macrocode} +% +% +% \begin{macro}{\IndexPrologue} +% \begin{macro}{\index@prologue} +% \changes{v1.9w}{1995/12/27}{Text changed} +% \changes{v1.9x}{1996/01/11}{Text depends on code lines used} +% The |\IndexPrologue| macro is used to place a short message +% into the document above the index. It is implemented by +% redefining |\index@prologue|, a macro which holds the +% default text. We'd better make it a |\long| macro to allow +% |\par| commands in its argument. +% \begin{macrocode} +\long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack} +% \end{macrocode} +% Now we test whether the default is already defined by another +% package file. If not we define it. +% \changes{v2.0j}{2000/05/22}{Less obscure wording? (CAR pr/3202)} +% \begin{macrocode} +\@ifundefined{index@prologue} + {\def\index@prologue{\section*{Index}% + \markboth{Index}{Index}% + Numbers written in italic refer to the page + where the corresponding entry is described; + numbers underlined refer to the + \ifcodeline@index + code line of the + \fi + definition; numbers in roman refer to the + \ifcodeline@index + code lines + \else + pages + \fi + where the entry is used. + }}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% \begin{macro}{\IndexParms} +% These are some last-minute assignments for formatting the index +% entries. They are defined in a separate macro so that a user can +% substitute different definitions. We start by defining the +% various parameters controlling leading and the separation between +% the two columns. The entire index is set in |\small| size. +% \begin{macrocode} +\@ifundefined{IndexParms} + {\def\IndexParms{% + \parindent \z@ + \columnsep 15pt + \parskip 0pt plus 1pt + \rightskip 15pt + \mathsurround \z@ + \parfillskip=-15pt + \small +% \end{macrocode} +% \begin{macro}{\@idxitem} +% \begin{macro}{\subitem} +% \begin{macro}{\subsubitem} +% Index items are formatted with hanging indentation for any items +% which may require more than one line. +% \begin{macrocode} + \def\@idxitem{\par\hangindent 30pt}% +% \end{macrocode} +% Any sub-item in the index is formatted with a 15pt indentation +% under its main heading. +% \begin{macrocode} + \def\subitem{\@idxitem\hspace*{15pt}}% +% \end{macrocode} +% Whilst sub-sub-items go in a further 10pt. +% \begin{macrocode} + \def\subsubitem{\@idxitem\hspace*{25pt}}% +% \end{macrocode} +% \begin{macro}{\indexspace} +% The \textsf{makeindex} program generates an |\indexspace| +% before each new alphabetic section commences. After this final +% definition we end the |\@ifundefined| and the definition of +% |\IndexParms|. +% \begin{macrocode} + \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}% + }}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\efill} +% This definition of |\efill| is intended to be used after index +% items which have no following text (for example, ``\textit{ +% see\/}'' entries). It just ensures that the current line is +% filled, preventing ``|Underfull \hbox|'' messages. +% \begin{macrocode} +\def\efill{\hfill\nopagebreak}% +% +%<+gind|gglo>item_x1 "\\efill \n \\subitem " +%<+gglo>item_x2 "\\ " +%<+gind>item_x2 "\\efill \n \\subsubitem " +%<*package> +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\pfill} +% \begin{macro}{\dotfil} +% \begin{macro}{\dotfill} +% The following definitions provide the |\pfill| command; if +% this is specified in the index style file to \textsf{makeindex} as +% the delimiter to appear after index items, then the intervening +% space before the referenced page numbers will be filled with +% dots, with a little white space interpolated at each end of the +% dots. If the line is broken the dots will show up on both lines. +% \changes{v2.1i}{2018/09/25}{Guard against following \cs{unskip} (git/23)} +% \begin{macrocode} +\def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill\kern\z@}% +\def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil\kern\z@}% +\def\pfill{\unskip~\dotfill\penalty500\strut\nobreak + \dotfil~\ignorespaces}% +% +%<+gind|gglo>delim_0 "\\pfill " +%<+gind|gglo>delim_1 "\\pfill " +%<+gind|gglo>delim_2 "\\pfill " +%<*package> +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% +% +% \begin{macro}{\*} +% Here is the definition for the |\*| macro. It isn't used in +% this set of macros. +% \begin{macrocode} +\def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\main} +% The \textit{defining\/} entry for a macro name is flagged with +% the string \texttt{\encapchar main}\footnote{With the current +% definition of \texttt{\bslash encapchar} substituted for +% \texttt{\encapchar}} in the |\index| command; \textsf{makeindex} +% processes this so that the |\main| macro will be invoked to +% underline the page number(s) on which the {\em definition\/} of +% the macro will be found. +% \begin{macrocode} +\@ifundefined{main}{\def\main#1{\underline{#1}}}{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\usage} +% The |\usage| macro is used to indicate entries describing +% the usage of a macro. The corresponding page number(s) will be +% set in \textit{italics}. +% \begin{macrocode} +\@ifundefined{usage}{\def\usage#1{\textit{#1}}}{} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\PrintIndex} +% \changes{v1.5k}{1989/09/04}{\cs{printindex} changed to +% \cs{PrintIndex}} +% \changes{v1.7a}{1992/02/26}{Documentation moved to interface section.} +% \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.} +% \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.} +% This is the same as "\printindex" in the \textsf{makeidx} package. +% \begin{macrocode} +\def\PrintIndex{\@input@{\jobname.ind}% + \global\let\PrintIndex\@empty} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\printindex} +% Since the above macro was called |\printindex| in older versions +% of \texttt{doc.sty} the following definition was provided up to +% version 1.9y. +% \changes{v1.9z}{1996/04/17}{Commented out} +% \begin{macrocode} +%\def\printindex{\typeout{\string\printindex\space is obsolete!}% +% \typeout{Please use \string\PrintIndex\space +% if you are a macro implementor^^J +% or get a newer version of the documented +% software if you are a user}% +% \PrintIndex} +% \end{macrocode} +% \end{macro} +% +% We want headings in the index (and changes list) according to the +% initial character of the next block of entries and have to instruct +% \textsf{makeindex} appropriately. Unfortunately the specification +% for this changed sometime between versions 2.4 and 2.11 of +% \textsf{makeindex}. We provide both ways of doing it but +% unfortunately this will always produce a warning message from +% \textsf{makeindex}. This is for older versions: +% \changes{v1.7h}{1992/07/01}{Turn off headings in gls file} +% \begin{macrocode} +% +%<+gind,gglo>% The next lines will produce some warnings when +%<+gind,gglo>% running Makeindex as they try to cover two different +%<+gind,gglo>% versions of the program: +%<+gind,gglo>lethead_prefix "{\\bfseries\\hfil " +%<+gind,gglo>lethead_suffix "\\hfil}\\nopagebreak\n" +%<+gind>lethead_flag 1 +%<+gglo>lethead_flag 0 +% \end{macrocode} +% This works for newer ones: +% \begin{macrocode} +%<+gind,gglo>heading_prefix "{\\bfseries\\hfil " +%<+gind,gglo>heading_suffix "\\hfil}\\nopagebreak\n" +%<+gind>headings_flag 1 +%<+gglo>headings_flag 0 +%<*package> +% \end{macrocode} +% +% +% +% \subsection[Dealing with the change history] +% {Dealing with the change history\footnotemark} +% \footnotetext{The whole section was proposed by Brian \textsc{Hamilton +% Kelly}. He also documented and debugged the macros as +% well as many other parts of this package.} +% +% To provide a change history log, the |\changes| command has +% been introduced. This takes three arguments, respectively, the +% version number of the file, the date of the change, and some detail +% regarding what change has been made. The second of these arguments +% is otherwise ignored, but the others are written out and may be used +% to generate a history of changes, to be printed at the end of the +% document. However, note that older versions of Chen's standard +% \textsf{makeindex} +% program limit any textual field to just 64 characters; therefore, +% is important that the number of characters in the second and third +% parameters should not exceed 61 altogether (to allow for the +% parentheses placed around the date). +% +% \begin{macro}{\changes} +% \changes{BHK}{1989/04/26}{Documented \texttt{\protect\bslash changes} +% command.} +% \changes{BHK}{1989/04/26}{Changed definition of +% \texttt{\protect\bslash protect}.} The output of the |\changes| +% command goes into the \meta{Glossary\_File} and therefore uses +% the normal |\glossaryentry| commands.\footnote{Note that a recent +% change in \LaTeX{} 2.09 changed the command name in the +% \texttt{.glo} file from \texttt{\bslash indexentry} to +% \texttt{\bslash glossaryentry}. It is therefore necessary to +% have a special \textsf{makeindex} style file called +% \texttt{gglo.ist} to process this file correctly.} Thus +% \textsf{makeindex} or a similar program can be used to process +% the output into a sorted ``glossary''. The |\changes| command +% commences by taking the usual measures to hide its spacing, and +% then redefines |\protect| for use within the argument of the +% generated |\indexentry| command. +% +% We re-code nearly all chars found in |\sanitize| to letter +% since the use of special package which make some characters +% active might upset the |\changes| command when writing its +% entries to the file. However we have to leave |%| as comment +% and \verb*+ + as \meta{space} otherwise chaos will happen. +% And, of course the |\| should be available as escape +% character. +% \changes{v1.5v}{1990/01/28}{`Re-code a lot of chars.} +% \changes{v1.5m}{1989/09/20}{\cs{actualchar} in second level removed.} +% \changes{v1.5o}{1989/09/24}{New sorting.} +% \changes{v1.6c}{1990/06/29}{Again new sorting.} +% \changes{v1.9u}{1995/08/06}{Use \cs{protected@edef}} +% \begin{macrocode} +\def\changes{\@bsphack\begingroup\@sanitize + \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore + \changes@} +\def\changes@#1#2#3{% + \protected@edef\@tempa{\noexpand\glossary{#1\levelchar +% \end{macrocode} +% \changes{v1.9u}{1995/08/06}{Use value of \cs{saved@macroname} to +% find out about change entries at outer level} +% If the macro "\saved@macroname" doesn't contain any macro name +% (ie is empty) the current changes entry was done at top-level. +% In this case we precede it by "\generalname". +% \begin{macrocode} + \ifx\saved@macroname\@empty + \space + \actualchar + \generalname + \else +% \end{macrocode} +% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} +% \begin{macrocode} + \saved@indexname + \actualchar + \string\verb\quotechar*% + \verbatimchar\saved@macroname + \verbatimchar + \fi + :\levelchar #3}}% + \@tempa\endgroup\@esphack} +% \end{macrocode} +% +% \begin{macro}{\saved@macroname} +% \changes{BHK}{1989/04/26}{Provided for sorting outside \textsf{macro} +% environment} The entries are sorted for convenience by the name +% of the most recently introduced macroname (i.e., that in the most +% recent |\begin{macro}| command). We therefore provide +% |\saved@macroname| to record that argument, and provide a default +% definition in case |\changes| is used outside a \textsf{macro} +% environment. (This is a {\em wicked\/} hack to get such entries +% at the beginning of the sorted list! It works providing no macro +% names start with "!" or |"|.) \changes{v1.7a}{1992/03/02}{Changed +% string used for better sorting.} +% \changes{v1.9u}{1995/08/06}{Now empty by default} +% \begin{macrocode} +\def\saved@macroname{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\saved@indexname} +% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} +% The macroname being document without a backslash for the index +% (or the environment name which doesn't have one in the first place). +% \begin{macrocode} +\def\saved@indexname{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\generalname} +% \changes{v1.9u}{1995/08/06}{Macro added} +% This macro holds the string placed before changes entries on +% top-level. +% \begin{macrocode} +\def\generalname{General} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\RecordChanges} +% \changes{BHK}{1989/04/26}{Renames former \texttt{\protect\bslash +% PrintChanges} command.} +% To cause the changes to be written (to a \texttt{.glo}) file, we +% define |\RecordChanges| to invoke \LaTeX's usual +% |\makeglossary| command. +% \begin{macrocode} +\let\RecordChanges\makeglossary +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\GlossaryMin} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% \begin{macro}{\c@GlossaryColumns} +% \changes{BHK}{1989/04/26}{Added to support \texttt{\protect\bslash +% changes}.} The remaining macros are all analogues of those used +% for the \textsf{theindex} environment. When the glossary is +% started we compute the space which remains at the bottom of the +% current page; if this is greater than |\GlossaryMin| then the +% first part of the glossary will be placed in the available space. +% The number of columns set are controlled by the counter +% |\c@GlossaryColumns| which can be changed with a |\setcounter| +% declaration. +% \begin{macrocode} +\newdimen\GlossaryMin \GlossaryMin = 80pt +\newcount\c@GlossaryColumns \c@GlossaryColumns = 2 +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{environment}{theglossary} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% \changes{v1.5p}{1989/09/28}{Now call \cs{multicols} first.} +% \changes{v1.6e}{1991/04/03}{Turned into env definition.} +% \changes{v1.7a}{1992/03/10}{Changed to work without multicols if +% necessary.} +% \begin{macro}{\endglossary} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% The environment \textsf{theglossary} is defined in the same manner +% as the \textsf{theindex} environment. +% \begin{macrocode} +\ifhave@multicol + \newenvironment{theglossary}{% + \begin{multicols}\c@GlossaryColumns + [\glossary@prologue][\GlossaryMin]% + \GlossaryParms \let\item\@idxitem \ignorespaces}% + {\end{multicols}} +\else + \newenvironment{theglossary}{% + \@restonecoltrue\if@twocolumn\@restonecolfalse\fi + \columnseprule \z@ \columnsep 35\p@ + \twocolumn[\glossary@prologue]% + \GlossaryParms \let\item\@idxitem \ignorespaces} + {\if@restonecol\onecolumn\else\clearpage\fi} +\fi +% \end{macrocode} +% \end{macro} +% \end{environment} +% +% Here are the necessary \textsf{makeindex} declarations with scanning +% disabled as for the index. +% \begin{macrocode} +% +%<+gglo>preamble +%<+gglo>"\n \\begin{theglossary} \n +%<+gglo> \\makeatletter\\scan@allowedfalse\n" +%<+gglo>postamble +%<+gglo>"\n\n \\end{theglossary}\n" +% \end{macrocode} +% This difference from \texttt{gind.ist} is necessary if you have an +% up-to-date \LaTeX. +% \begin{macrocode} +%<+gglo>keyword "\\glossaryentry" +%<*package> +% \end{macrocode} +% +% +% \begin{macro}{\GlossaryPrologue} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% \begin{macro}{\glossary@prologue} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% The |\GlossaryPrologue| macro is used to place a short +% message above the glossary into the document. It is implemented +% by redefining |\glossary@prologue|, a macro which holds the +% default text. We better make it a long macro to allow +% |\par| commands in its argument. +% \begin{macrocode} +\long\def\GlossaryPrologue#1{\@bsphack + \def\glossary@prologue{#1}% + \@esphack} +% \end{macrocode} +% Now we test whether the default is already defined by another +% package file. If not we define it. +% \begin{macrocode} +\@ifundefined{glossary@prologue} + {\def\glossary@prologue{\section*{{Change History}}% + \markboth{{Change History}}{{Change History}}% + }}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\GlossaryParms} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% Unless the user specifies otherwise, we set the change history +% using the same parameters as for the index except that we make it sort +% of ragged right as it contains text that often doesn't break nicely in +% small columns. +% \changes{v2.1g}{2016/02/15}{Use ragged setting by default} +% \begin{macrocode} +\@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms + \expandafter\def\expandafter\GlossaryParms\expandafter{\GlossaryParms + \rightskip 15pt plus 1fil + \parfillskip -15pt plus -1fil\relax} +}{} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\PrintChanges} +% \changes{BHK}{1989/04/26}{Added to support +% \texttt{\protect\bslash changes}.} +% To read in and print the sorted change history, just put the +% |\PrintChanges| command as the last (commented-out, and thus +% executed during the documentation pass through the file) command +% in your package file. Alternatively, this command may form one of +% the arguments of the |\StopEventually| command, although a +% change history is probably {\em not\/} required if only the +% description is being printed. +% +% The command assumes that \textsf{makeindex} or some other program +% has processed the \texttt{.glo} file to generate a sorted +% \texttt{.gls} file. +% \changes{v1.9h}{1994/02/10}{Use \cs{@input@} instead of \cs{@input}.} +% \changes{v1.9w}{1995/12/29}{Turn the cmd into a noop after use.} +% \begin{macrocode} +\def\PrintChanges{\@input@{\jobname.gls}% + \global\let\PrintChanges\@empty} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \subsection{Bells and whistles} +% +% \begin{macro}{\StopEventually} +% \changes{v1.5k}{1989/09/04}{Support for checksum.} +% \begin{macro}{\Finale} +% \changes{v1.5k}{1989/09/04}{Support for checksum.} +% \changes{v1.5z}{1990/04/22}{Define \cs{Finale} globally.} +% \begin{macro}{\AlsoImplementation} +% \changes{v1.9w}{1995/12/27}{Macro added} +% \begin{macro}{\OnlyDescription} +% If |\AlsoImplementation| is in force the whole documentation +% including the code part will be typeset. This is the default. +% \begin{macrocode} +\newcommand\AlsoImplementation{% +% \end{macrocode} +% To make this happen we have to define +% |\StopEventually| in a way that its argument is typeset at the +% very end or more exactly at |\Finale|. For this we +% save its argument in the macro |\Finale|. +% \begin{macrocode} + \long\def\StopEventually##1{\@bsphack\gdef\Finale{##1% +% \end{macrocode} +% But |\Finale| will be called at the very end of a file. This +% is exactly the point were we want to know if the file is +% uncorrupted. Therefore we also call |\check@checksum| at this +% point. +% \begin{macrocode} + \check@checksum}% +% \end{macrocode} +% On the other hand: |\StopEventually| is more or less a +% dividing point between description and code. So we start to look +% for the check-sum of the documented file by calling +% |\init@checksum|. +% \begin{macrocode} + \init@checksum + \@esphack}% + } +% \end{macrocode} +% +% Since |\AlsoImplementation| should be the default we execute it +% and thus |\StopEventually| gets the desired meaning. +% \begin{macrocode} +\AlsoImplementation +% \end{macrocode} +% When the user places an |\OnlyDescription| declaration in +% the driver file the document should only be typeset up to +% |\StopEventually|. We therefore have to redefine this macro. +% \begin{macrocode} +\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{% +% \end{macrocode} +% In this case the argument of |\StopEventually| should be set +% and afterwards \TeX{} should stop reading from this file. +% Therefore we finish this macro with +% \begin{macrocode} + ##1\endinput}\@esphack} +% \end{macrocode} +% If no |\StopEventually| command is given we silently ignore a +% |\Finale| issued. +% \changes{v1.9n}{1994/04/28}{Ignore \cs{Finale} if no +% \cs{StopEventually} is given} +% \begin{macrocode} +\let\Finale\relax +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\meta} +% \changes{v1.4t}{1989/04/24}{Macro added.} +% \changes{v1.5w}{1990/02/03}{Breaks at space allowed.} +% \changes{v1.6a}{1990/05/24}{Extra space bug corrected.} +% The |\meta| macro is a bit tricky. We want to allow line +% breaks at blanks in the argument but we don't want a break +% in between. In the past this was done by defining |\meta| in a way that a +% \verb*+ + is active when the argument is scanned. Words are then +% scanned into |\hbox|es. The active \verb*+ + will end the +% preceding |\hbox| add an ordinary space and open a new +% |\hbox|. In this way breaks are only possible at spaces. The +% disadvantage of this method was that |\meta| was neither robust +% nor could it be |\protect|ed. The new implementation fixes this +% problem by defining |\meta| in a radically different way: we +% prevent hyphenation by defining a |\language| which has no +% patterns associated with it and use this to typeset the words +% within the angle brackets. +% \changes{v2.0i}{2000/05/21}{New implementation (pr/3170)} +% \begin{macrocode} +\ifx\l@nohyphenation\undefined + \newlanguage\l@nohyphenation +\fi +% \end{macrocode} +% +% \begin{macrocode} +\DeclareRobustCommand\meta[1]{% +% \end{macrocode} +% Since the old implementation of |\meta| could be used in math we +% better ensure that this is possible with the new one as +% well. So we use |\ensuremath| around |\langle| and +% |\rangle|. However this is not enough: if |\meta@font@select| +% below expands to |\itshape| it will fail if used in math +% mode. For this reason we hide the whole thing inside an +% |\nfss@text| box in that case. +% \changes{v2.0l}{2000/06/10}{Fixing changes for (pr/3170)} +% \begin{macrocode} + \ensuremath\langle + \ifmmode \expandafter \nfss@text \fi + {% + \meta@font@select +% \end{macrocode} +% Need to keep track of what we changed just in case the user +% changes font inside the argument so we store the font explicitly. +% \changes{v2.0m}{2000/07/04}{More fixing changes for (pr/3170)} +% \begin{macrocode} + \edef\meta@hyphen@restore + {\hyphenchar\the\font\the\hyphenchar\font}% + \hyphenchar\font\m@ne + \language\l@nohyphenation + #1\/% + \meta@hyphen@restore + }\ensuremath\rangle +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\meta@font@select} +% \changes{v2.0k}{2000/05/26}{Macro added (pr/3170)} +% Maske font used inside |\meta| customizable. +% \begin{macrocode} +\def\meta@font@select{\itshape} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\IndexInput} +% This next macro may be used to read in a separate file (possibly +% a package file that is {\em not\/} documented by this means) and +% set it verbatim, whilst scanning for macro names and indexing the +% latter. This could be a useful first pass in preparing to +% generate documentation for the file read. +% \begin{macrocode} +\def\IndexInput#1{% +% \end{macrocode} +% We commence by setting up a group, and initializing a +% |\trivlist| as is normally done by a +% |\begin{macrocode}| command. +% \begin{macrocode} + \begingroup \macro@code +% \end{macrocode} +% We also make spacing behave as in the \textsf{macrocode} +% environment, because otherwise all the spaces will be shown +% explicitly. +% \begin{macrocode} + \frenchspacing \@vobeyspaces +% \end{macrocode} +% Then it only remains to read in the specified file, and finish +% off the |\trivlist|. +% \changes{v1.5t}{1989/11/07}{Call \cs{endmacrocode} instead +% of \cs{endtrivlist}.} +% \begin{macrocode} + \input{#1}\endmacrocode +% \end{macrocode} +% Of course, we need to finish off the group as well. +% \begin{macrocode} + \endgroup} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\maketitle} +% The macro to generate titles is easily altered in order that it +% can be used more than once (an article with many titles). In the +% original, diverse macros were concealed after use with +% |\relax|. We must cancel anything that may have been put +% into |\@thanks|, etc., otherwise {\em all\/} titles will +% carry forward any earlier such setting! +% \changes{v1.5j}{1989/06/09}{thispagestyle plain removed} +% \changes{v1.9r}{1994/06/09}{Added new definitions of +% \cs{@makefnmark} and \cs{@makefntext}} +% \begin{macrocode} +\def\maketitle{\par + \begingroup \def \thefootnote {\fnsymbol {footnote}}% + \setcounter {footnote}\z@ + \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}% + \long\def\@makefntext##1{\parindent 1em\noindent + \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}% + \if@twocolumn \twocolumn [\@maketitle ]% + \else \newpage \global \@topnum \z@ \@maketitle \fi +% \end{macrocode} +% \changes{v1.5k}{1989/09/04}{Added \cs{ps@titlepage}} +% For special formatting requirements (such as in TUGboat), we use +% pagestyle |titlepage| for this; this is later defined to be +% |plain|, unless already defined, as, for example, by +% |ltugboat.sty|. +% \begin{macrocode} + \thispagestyle{titlepage}\@thanks \endgroup +% \end{macrocode} +% If the driver file documents many files, we don't want parts of a +% title of one to propagate to the next, so we have to cancel +% these: +% \begin{macrocode} + \setcounter {footnote}\z@ + \gdef\@date{\today}\gdef\@thanks{}% + \gdef\@author{}\gdef\@title{}} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\ps@titlepage} +% \changes{v1.5k}{1989/09/04}{Added \texttt{\protect\bslash +% ps@titlepage}} When a number of articles are concatenated into a +% journal, for example, it is not usual for the title pages of such +% documents to be formatted differently. Therefore, a class +% such as \textsf{ltugboat} can define this macro in advance. +% However, if no such definition exists, we use pagestyle +% \texttt{plain} for title pages. +% \begin{macrocode} +\@ifundefined{ps@titlepage} + {\let\ps@titlepage=\ps@plain}{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\MakeShortVerb} +% \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters +% \cs{dospecials}, \cs{@sanitize}).} +% This arranges an abbreviation for "\verb" such that if you say +% "\MakeShortVerb{\"\meta{c}"}" subsequently using +% \meta{c}\meta{text}\meta{c} is equivalent to +% "\verb"\meta{c}\meta{text}\meta{c}.\footnote{Warning: +% the commentary in the rest of this section was written by Dave +% Love.} In addition, the fact +% that \meta{c} is made active is recorded for the benefit of the +% \textsf{verbatim} and \textsf{macrocode} environments. +% Note particularly that the definitions below are global. +% The first thing we do (it needn't be first) is to record +% the---presumably new---special character in "\dospecials" and +% "\@sanitize" using "\add@special". +% +% \changes{v1.9e.2}{1994/02/07}{-js: Check if \protect\meta{c} is +% already an +% abbreviation for \cs{verb}.} +% Some unwary user might issue "\MakeShortVerb" for a second time, we +% better protect against this. We assume that this happened if a +% control sequence "\cc\"\meta{c} is bound, the probability that this +% name is used by another module is low. We will output a warning +% below, so that a possible error might be noticed by the programmer +% if he reads the "LOG" file. (Should have used module internal names, +% 'though.) +% +% \begin{macro}{\MakeShortVerb*} +% \changes{v2.1a}{2003/12/09}{(HjG) Added \texttt{*} form} +% This arranges an abbreviation for "\verb*" such that if you say +% "\MakeShortVerb*{\"\meta{c}"}" subsequently using +% \meta{c}\meta{text}\meta{c} is equivalent to +% "\verb*"\meta{c}\meta{text}\meta{c}. +% \begin{macrocode} +% +%<*package|shortvrb> +\def\MakeShortVerb{% + \@ifstar + {\def\@shortvrbdef{\verb*}\@MakeShortVerb}% + {\def\@shortvrbdef{\verb}\@MakeShortVerb}} +% \end{macrocode} +% \end{macro} +% \begin{macrocode} +\def\@MakeShortVerb#1{% + \expandafter\ifx\csname cc\string#1\endcsname\relax +% \end{macrocode} +% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}} +% \begin{macrocode} + \@shortvrbinfo{Made }{#1}\@shortvrbdef + \add@special{#1}% +% \end{macrocode} +% Then the character's current catcode is stored in "\cc\"\meta{c}. +% \begin{macrocode} + \expandafter + \xdef\csname cc\string#1\endcsname{\the\catcode`#1}% +% \end{macrocode} +% The character is spliced into the definition using the same trick as +% used in "\verb" (for instance), having activated "~" in a group. +% \begin{macrocode} + \begingroup + \catcode`\~\active \lccode`\~`#1% + \lowercase{% +% \end{macrocode} +% The character's old meaning is recorded in "\ac\"\meta{c} prior to +% assigning it a new one. +% \begin{macrocode} + \global\expandafter\let + \csname ac\string#1\endcsname~% + \expandafter\gdef\expandafter~\expandafter{\@shortvrbdef~}}% + \endgroup +% \end{macrocode} +% Finally the character is made active. +% \begin{macrocode} + \global\catcode`#1\active +% \end{macrocode} +% If we suspect that \meta{c} is already a short reference, we tell +% the user. Now he or she is responsible if anything goes wrong\,\dots +% \begin{macrocode} + \else +% \end{macrocode} +% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}} +% \begin{macrocode} + \@shortvrbinfo\@empty{#1 already}{\@empty\verb(*)}% + \fi} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\DeleteShortVerb} +% \changes{v1.7a}{1992/02/27}{Added (from newdoc but now alters +% \cs{dospecials}, \cs{@sanitize}).} +% Here's the means of undoing a "\MakeShortVerb", for instance in a +% region where you need to use the character outside a verbatim +% environment. It arranges for "\dospecials" and "\@sanitize" to be +% altered appropriately, restores the saved catcode and, if necessary, +% the character's meaning (as stored by +% "\MakeShortVerb"). If the catcode wasn't stored in +% "\cc\"\meta{c} (by "\MakeShortVerb") the command is silently +% ignored. +% \changes{v1.7a}{1992/02/28}{Check for previous matched +% \cs{MakeShortVerb} +% to avoid error.} +% \begin{macrocode} +\def\DeleteShortVerb#1{% + \expandafter\ifx\csname cc\string#1\endcsname\relax +% \end{macrocode} +% \changes{v2.1a}{2003/12/10}{(HjG) Notify user +% if it's not a short verb character} +% \begin{macrocode} + \@shortvrbinfo\@empty{#1 not}{\@empty\verb(*)}% + \else +% \end{macrocode} +% \changes{v1.9v}{1995/11/03}{(DPC) Use \cs{@shortvrbinfo}} +% \begin{macrocode} + \@shortvrbinfo{Deleted }{#1 as}{\@empty\verb(*)}% + \rem@special{#1}% + \global\catcode`#1\csname cc\string#1\endcsname +% \end{macrocode} +% \changes{v1.9e.2}{1994/02/07}{-js: Reset `cc`\protect\meta{c} in +% in \cs{DeleteShortVerb}} +% We must not forget to reset "\cc\"\meta{c}, otherwise the check in +% "\MakeShortVerb" for a repeated definition will not work. +% \begin{macrocode} + \global \expandafter\let \csname cc\string#1\endcsname \relax + \ifnum\catcode`#1=\active + \begingroup + \catcode`\~\active \lccode`\~`#1% + \lowercase{% + \global\expandafter\let\expandafter~% + \csname ac\string#1\endcsname}% + \endgroup \fi \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\@shortvrbinfo} +% \changes{v1.9v}{1995/11/03}{(DPC) Macro added} +% \changes{v2.1a}{2003/12/10}{(HjG) Third argument added +% on behalf of \cmd{\MakeShortVerb*}} +% Helper function for info messages. +% \begin{macrocode} +\def\@shortvrbinfo#1#2#3{% +% \PackageInfo{shortvrb}{% +% \PackageInfo{doc}{% + #1\expandafter\@gobble\string#2 a short reference + for \expandafter\string#3}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\add@special} +% \changes{v1.7a}{1992/02/27}{Added for short verb facility.} +% This helper macro adds its argument to the +% "\dospecials" macro which is conventionally used by verbatim macros +% to alter the catcodes of the currently active characters. We need +% to add "\do\"\meta{c} to the expansion of "\dospecials" after +% removing the character if it was already there to avoid multiple +% copies building up should "\MakeShortVerb" not be balanced by +% "\DeleteShortVerb" (in case anything that uses "\dospecials" cares +% about repetitions). +% \begin{macrocode} +\def\add@special#1{% + \rem@special{#1}% + \expandafter\gdef\expandafter\dospecials\expandafter + {\dospecials \do #1}% +% \end{macrocode} +% Similarly we have to add "\@makeother\"\meta{c} to "\@sanitize" +% (which is used in things like "\index" to re-catcode all special +% characters except braces). +% \begin{macrocode} + \expandafter\gdef\expandafter\@sanitize\expandafter + {\@sanitize \@makeother #1}} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\rem@special} +% \changes{v1.7a}{1992/02/27}{Added for short verb facility.} +% The inverse of "\add@special" is slightly trickier. "\do" is +% re-defined to expand to nothing if its argument is the character of +% interest, otherwise to expand simply to the argument. We can then +% re-define "\dospecials" to be the expansion of itself. The space +% after "=`##1" prevents an expansion to "\relax"! +% \begin{macrocode} +\def\rem@special#1{% + \def\do##1{% + \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}% + \xdef\dospecials{\dospecials}% +% \end{macrocode} +% Fixing "\@sanitize" is the same except that we need to re-define +% "\@makeother" which obviously needs to be done in a group. +% \begin{macrocode} + \begingroup + \def\@makeother##1{% + \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}% + \xdef\@sanitize{\@sanitize}% + \endgroup} +% +%<*package> +% \end{macrocode} +% \end{macro} +% \begin{macro}{\MakeShortverb} +% \begin{macro}{\DeleteShortverb} +% \changes{v1.7a}{1992/02/27}{Added (from newdoc).} +% These commands from \textsf{newdoc} are now obsolete. +% \begin{macrocode} +\def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb + syntax, this is obsolete ***}\MakeShortVerb} +\def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb + syntax, this is obsolete ***}\DeleteShortVerb} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% \subsection[Providing a checksum and character table] +% {Providing a checksum and character table\footnotemark} +% \footnotetext{Warning: the commentary in this section was +% written by Dave Love. } +% +% +% \begin{macro}{\init@checksum} +% The checksum mechanism works by counting backslashes in the +% macrocode. This initialises the count (when called from +% "\StopEventually"). +% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} +% \begin{macrocode} +\def\init@checksum{\relax + \global\bslash@cnt\z@} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\check@checksum} +% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} +% This reports the sum compared with the value ("\bslash@cnt") the +% file advertises. It's called from "\Finale" (if that hasn't been +% re-defined). +% \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum +% is specified in the file} +% \begin{macrocode} +\def\check@checksum{\relax + \ifnum\check@sum>\m@ne +% \end{macrocode} +% We do nothing if the checksum in the file is negative (or not given as +% it is initialized with -1). +% \begin{macrocode} + \ifnum\check@sum=\z@ + \typeout{**********************************}% + \typeout{* This macro file has no checksum!}% + \typeout{* The checksum should be \the\bslash@cnt!}% + \typeout{**********************************}% + \else + \ifnum\check@sum=\bslash@cnt + \typeout{*******************}% + \typeout{* Checksum passed *}% + \typeout{*******************}% + \else + \PackageError{doc}{Checksum not passed + (\the\check@sum<>\the\bslash@cnt)}% + {The file currently documented seems to be wrong.^^J% + Try to get a correct version.}% + \fi + \fi + \fi + \global\check@sum\m@ne} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\check@sum} +% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} +% \begin{macro}{\bslash@cnt} +% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} +% We need to define counters, "\bslash@cnt" for the number of +% backslashes counted and "\check@sum" for the value advertised by the +% file if any. A negative value means there is no checksum checking which is the default. +% \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum +% is specified in the file} +% \begin{macrocode} +\newcount\check@sum \check@sum = \m@ne +\newcount\bslash@cnt \bslash@cnt = \z@ +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \begin{macro}{\CheckSum} +% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} +% This is the interface to setting "\check@sum". +% \begin{macrocode} +\def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\step@checksum} +% \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} +% This advances the count when a backslash is encountered in the +% macrocode. +% \begin{macrocode} +\def\step@checksum{\global\advance\bslash@cnt\@ne} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\CharacterTable} +% The user interface to the character table-checking does some +% "\catcode"ing and then compares the following table with the +% stored version. We need to have "@" of type ``other'' within the +% table since this is the way it is usually returned when reading +% in a normal document. To nevertheless have a private letter we +% use "~" for this purpose. "~" does no harm as a ``letter'' as it +% comes last in the table and therefore will not gobble following +% space. +% \changes{v1.5m}{1989/09/20}{Macro added to check character translation +% problems.} +% \changes{v1.5q}{1989/11/01}{Made character table more readable.} +% \changes{v1.5t}{1989/11/07}{Make \string\~{} letter in chartable +% macros.} +% \changes{v1.5u}{1989/11/14}{Made @ other in default table.} +% \begin{macrocode} +\def\CharacterTable{\begingroup \CharTableChanges \character@table} +% \end{macrocode} +% \end{macro} +% \def\MakePrivateLetters{\catcode`\~=11\makeatletter} +% \begin{macro}{\character@table} +% This does the work of comparing the tables and reporting the result. +% Note that the following code is enclosed in a group +% with "~" catcoded to letter. +% \begin{macrocode} +\begingroup + \catcode`\~=11 + \gdef\character@table#1{\def\used~table{#1}% + \ifx\used~table\default~table + \typeout{***************************}% + \typeout{* Character table correct *}% + \typeout{***************************}% + \else + \PackageError{doc}{Character table corrupted} + {\the\wrong@table} + \show\default~table + \show\used~table + \fi + \endgroup} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\CharTableChanges} +% When the character table is read in we need to scan it with a +% fixed set of "\catcode"s. The reference table below was defined by +% assuming the normal "\catcode"s of \TeX{}, i.e.\ "@" is of type +% other and the only token of type ``letter'' are the usual letters +% of the alphabet. If, for some reason, other characters are made +% ``letters'' then their "\catcode"s need to be restored before +% checking the table. Otherwise spaces in the table are gobbled and +% we get the information that the tables are different, even if +% they are actually equal. For this reason "\CharTableChanges" can +% be set up to locally restore the "\catcode"s of such ``letters'' +% to ``other''. +% \begin{macrocode} + \global\let\CharTableChanges\@empty +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\default~table} +% Here's what the table {\em should\/} look like (modulo spaces). +% \begin{macrocode} + \makeatother + \gdef\default~table + {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 + 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 + Digits \0\1\2\3\4\5\6\7\8\9 + Exclamation \! Double quote \" Hash (number) \# + Dollar \$ Percent \% Ampersand \& + Acute accent \' Left paren \( Right paren \) + Asterisk \* Plus \+ Comma \, + Minus \- Point \. Solidus \/ + Colon \: Semicolon \; Less than \< + Equals \= Greater than \> Question mark \? + Commercial at \@ Left bracket \[ Backslash \\ + Right bracket \] Circumflex \^ Underscore \_ + Grave accent \` Left brace \{ Vertical bar \| + Right brace \} Tilde \~} +\endgroup +% \end{macrocode} +% \end{macro} +% \let\MakePrivateLetters=\makeatletter +% +% \begin{macro}{\wrong@table} +% \changes{v1.7a}{1992/02/28}{Moved to where the catcodes are right +% so it works.} +% We need a help message in case of problems. +% \begin{macrocode} + \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J + I now \string\show\space you both tables for comparison.} +% \end{macrocode} +% \end{macro} +% +% +% \subsection[Attaching line numbers to code lines] +% {Attaching line numbers to code lines\footnotemark} +% \footnotetext{Warning: the commentary was written by Dave +% Love.} +% +% +% The code in this section allows index entries to refer to code line +% numbers---the number of the first line of macrocode in the +% \textsf{macro} environment. +% +% +% \begin{macro}{\codeline@index} +% Indexing by code line is controlled by the "codeline@index" switch. +% \changes{v1.5s}{1989/11/05}{Support for code line no. (Undoc)} +% \changes{v1.7a}{1992/02/24}{Documented code line no. support.} +% \begin{macro}{\CodelineNumbered} +% \changes{v1.8a}{1993/05/19}{Macro added} +% \begin{macrocode} +\newif\ifcodeline@index \codeline@indexfalse +\let\CodelineNumbered\codeline@indextrue +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\codeline@wrindex} +% The code index entries are written out by "\special@index". If +% indexing is by code line this is "\let" to "\codeline@wrindex"; +% if indexing is by page it is just "\index". However, if +% "\nofiles" is given, we omit writing such an index entry at all. +% \changes{v1.7j}{1992/08/14}{Added \cs{if@filesw}.} +% \begin{macrocode} +\def\codeline@wrindex#1{\if@filesw + \immediate\write\@indexfile + {\string\indexentry{#1}% + {\number\c@CodelineNo}}\fi} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\special@index} +% By default no index entries are written out. +% \begin{macrocode} +\let\special@index = \@gobble +% \end{macrocode} +% \end{macro} +% \begin{macro}{\CodelineIndex} +% \changes{v1.5u}{1989/11/14}{Added \cs{PageIndex} and +% \cs{CodelineIndex} (Undoc)} +% This switches on use of the index file with "\makeindex", sets the +% switch to indicate code line numbering and defines "\special@index" +% appropriately. +% \begin{macrocode} +\def\CodelineIndex{\makeindex + \codeline@indextrue + \let\special@index\codeline@wrindex} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\PageIndex} +% "\PageIndex" is similar. +% \begin{macrocode} +\def\PageIndex{\makeindex + \codeline@indexfalse + \let\special@index\index} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\c@CodelineNo} +% \changes{v1.5l}{1989/09/10}{Counter added to support code line +% numbers} +% \changes{v1.5y}{1990/02/24}{Default changed.} +% \changes{v1.6b}{1990/06/15}{\cs{rm} moved before \cs{scriptsize} to +% avoid unnecessary fontwarning.} +% We need a counter to keep track of the line number. +% \begin{macrocode} +\newcount\c@CodelineNo \c@CodelineNo\z@ +% \end{macrocode} +% \end{macro} +% \begin{macro}{\theCodelineNo} +% \changes{v1.7a}{1992/02/25}{Existing definition not overwritten.} +% \changes{v1.7a}{1992/03/12}{Use \cs{reset@font} for NFSS.} +% This provides a hook to control the format of line numbers which may +% be defined in a class file. +% \begin{macrocode} +\@ifundefined{theCodelineNo} + {\ifx\selectfont\undefined + \def\theCodelineNo{\rmfamily\scriptsize\arabic{CodelineNo}}% + \else + \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}% + \fi} + {} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \subsection{Layout Parameters for documenting package files} +% +% \begin{macro}{\tolerance} +% People documenting package files would probably rather have things +% ``sticking out'' in overfull |\hbox|es and poorish spacing, +% because they probably don't want to spend a lot of time on making +% all the line breaks perfect! +% \begin{macrocode} + \tolerance=1000\relax +% \end{macrocode} +% \end{macro} +% +% \DeleteShortVerb{\"} +% +% The following |\mathcode| definitions allow the characters +% `|\|' +% and `\texttt{@}' to appear in |\ttfamily| font when invoked in math +% mode;\footnote{You may wonder why the definitions state that both +% characters belong to the {\em variable family\/} +% (i.e.\ the number 7 in front). The reason is this: +% Originally the \texttt{\bslash mathcode} of +% \texttt{\bslash} was defined to be \texttt{"075C}, +% i.e.\ ordinary character number 92 (hex 5C) in +% math family number 7 which is the typewriter family in +% standard \LaTeX. +% But this file should not depend on this specific +% setting, so I changed these +% \texttt{\bslash mathcode}$\,$s +% to work with any family assignments. For an example +% see the article about the new font selection scheme.} +% particularly for something like $|\@abc|=1$. +% +% If an {\em old\/} version of the \textsf{german} package is in +% force, then the `|"|' character is active and would upset the +% definition of the \meta{16-bit number} quantities below, therefore +% we change the |\catcode| of |"| inside a group, and use +% |\global|. +% \begin{macrocode} +{ \catcode`\"=12 + \global\mathcode`\\="705C \global\mathcode`\@="7040 } +% \end{macrocode} +% \MakeShortVerb{\"} +% +% \begin{macro}{\DocstyleParms} +% This macro can be used, for example, to assign new values to +% |\MacrocodeTopsep| and |\MacroIndent| and some other internal +% registers. If it is already defined, the default definition +% won't be carried out. Note that it is necessary to assign new +% values via this macro if it should be done in a class file (like +% \texttt{ltugboat.cls} for example) since the registers are +% undefined before \texttt{doc.sty} is read in. The default values +% for the internal registers are scattered over this file. +% \changes{v1.5u}{1989/11/14}{\cs{DocStyleParms} now empty} +% \changes{v2.1h}{2018/02/01}{Only use\cs{DocStyleParms} if defined +% (previously the test defined it)} +% \begin{macrocode} +\@ifundefined{DocstyleParms}{}{\DocstyleParms} +% \end{macrocode} +% Clear out |\DocstyleParms| after use (or non-use). +% \begin{macrocode} + \let\DocstyleParms\relax +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\AmSTeX} +% \changes{v1.5j}{1989/06/09}{Macro AmsTeX renamed to AmSTeX} +% \begin{macro}{\BibTeX} +% \begin{macro}{\SliTeX} +% Here are a few definitions which can usefully be employed when +% documenting package files: now we can readily refer to \AmSTeX, +% \BibTeX\ and \SliTeX, as well as the usual \TeX\ and \LaTeX. +% \begin{macrocode} +\@ifundefined{AmSTeX} + {\def\AmSTeX{\leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex% + \hbox{$\mathcal M$}\kern-.2em\mathcal S$-\TeX}}}{} +\@ifundefined{BibTeX} + {\def\BibTeX{{\rmfamily B\kern-.05em% + \textsc{i\kern-.025em b}\kern-.08em% + T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{} +\@ifundefined{SliTeX} + {\def\SliTeX{{\rmfamily S\kern-.06emL\kern-.18em\raise.32ex\hbox + {\scshape i}\kern -.03em\TeX}}}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \begin{macro}{\PlainTeX} +% \changes{v1.5g}{1989/05/07}{space between plain and TeX changed.} +% \begin{macro}{\Web} +% There's even a \PlainTeX{} and a \Web. +% \begin{macrocode} +\@ifundefined{PlainTeX}{\def\PlainTeX{\textsc{Plain}\kern2pt\TeX}}{} +\@ifundefined{Web}{\def\Web{\textsc{Web}}}{} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \subsection{Changing the \texttt{\protect\bslash catcode} of \%} +% +% \begin{macro}{\MakePercentIgnore} +% \begin{macro}{\MakePercentComment} +% And finally the most important bit: we change the |\catcode| +% of `|%|' so that it is ignored (which is how we are able to +% produce this document!). We provide two commands to do the actual +% switching. +%^^A The |\MakePercentIgnore| is then called as the +%^^A last command in this file. +% \begin{macrocode} +\def\MakePercentIgnore{\catcode`\%9\relax} +\def\MakePercentComment{\catcode`\%14\relax} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\DocInput} +% The two macros above are now used to define the |\DocInput| macro +% which was introduced in version v1.5l (or so) of the \DOC{} +% package. In older versions |\MakePercentIgnore| was placed +% at the very end of \texttt{doc.sty}. +% \begin{macrocode} +\def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment} +% \end{macrocode} +% \end{macro} +% +% \subsection{GetFileInfo} +% +% \begin{macro}{\GetFileInfo} +% \changes{v1.9o}{1994/05/08}{Macro added} +% \changes{v1.9z}{1997/02/05}{Missing percent latex/2404} +% Define |\filedate| and friends from info in the +% |\ProvidesPackage| etc.\ commands. +% \begin{macrocode} +\def\GetFileInfo#1{% + \def\filename{#1}% + \def\@tempb##1 ##2 ##3\relax##4\relax{% + \def\filedate{##1}% + \def\fileversion{##2}% + \def\fileinfo{##3}}% + \edef\@tempa{\csname ver@#1\endcsname}% + \expandafter\@tempb\@tempa\relax? ? \relax\relax} +% \end{macrocode} +% \end{macro} +% +% We can now finish the \texttt{docstrip} main module. +% \begin{macrocode} +% +% \end{macrocode} +% +% +% \Finale +% \PrintIndex \PrintChanges +\endinput -- cgit v1.2.3