The file ltxdoc.dtx for use with L^{A}TEX 2ε.^{∗} It contains the code for ltxdoc.cls

David Carlisle

1995/11/28

1 Documentation of the L^{A}TEX sources

This class file is designed for documenting the L^{A}TEX source files. You may however find it generally useful as a class for typesetting the documentation of files produced in ‘doc’ format.

Each documented file in the standard distribution comes with extension dtx. The appropriate class package or initex file will be extracted from the source by the docstrip system. Each dtx file may be directly processed with L^{A}TEX 2ε, for example

 latex2e docclass.dtx

would produce the documentation of the Class and package interface.

Each file that is used in producing the L^{A}TEX 2ε format (ie not including the standard class and packages) will be printed together in one document if you L^{A}TEX the file sources2e.tex. This has the advantage that one can produce a full index of macro usage across all the source files.

If you need to customise the typesetting of any of these files, there are two options:

• You can use docstrip with the module ‘driver’ to extract a small L^{A}TEX file that you may edit to use whatever class or package options you require, before inputting the source file.

• You can create a file ltxdoc.cfg. This configuration file will be read whenever the ltxdoc class is used, and so can be used to customise the typesetting of all the source files, without having to edit lots of small driver files.

The second option is usually more convenient. various possibilities are discussed in the next section.

∗This file has version number v2.0q, dated 1995/11/28.

2 Customisation

The simplest form of customisation is to pass more options to the article class which is loaded by ltxdoc. For instance if you wish all the documentation to be formated for A4 paper, add the following line to ltxdoc.cfg:

 \PassOptionsToClass{a4paper}{article}

All the source files are in two parts, separated by \StopEventually. The first part (should) contain ‘user’ documentation. The second part is a full documented listing of the source code. The doc package provides the command \OnlyDescription which suppresses the code listings. This may also be used in the configuration file, but as the doc package is read later, you must delay the execution of \OnlyDescription until after the doc package has been read. The simplest way is to use \AtBeginDocument. Thus you could put the following in

your ltxdoc.cfg.
 \AtBeginDocument{\OnlyDescription}

If the full source listing sources2e.tex is processed, then an index and change history are produced by default, however indices are not normally produced for individual files.

As an example, consider ltclass.dtx, which contains the sources for the new class and package interface commands. With no cfg file, a 19 page document is produced. With the above configuration a slightly more readable document (4 pages) is produced.

Conversely, If you really want to read the source listings in detail, You will want to have an index. Again the index commands provided by the doc package may be used, but their execution must be delayed.

 \AtBeginDocument{\CodelineIndex\EnableCrossrefs}
 \AtEndDocument{\PrintIndex}

The doc package writes index files to be sorted using MakeIndex with the gind style, so one would then use a command such as

 makeindex -s gind.ist ltclass.idx

and re-run L^{A}TEX.

Similarly to print a Change history, you would add

 \AtBeginDocument{\RecordChanges}
 \AtEndDocument{\PrintChanges}

to ltxdoc.cfg, and use MakeIndex with a comand such as

 makeindex -s gglo.ist -o ltclass.gls ltclass.glo

Finally if you do not want to list all the sections of source2e.tex, you can

use \includeonly in the cfg file:
 \includeonly{ltvers,ltboxes}

3 Options

1 ⟨∗class⟩

 2 \DeclareOption{a5paper}{\@latexerr{Option not supported}%
 3 {}}
 4 \DeclareOption*{%
 5  \PassOptionsToClass  {\CurrentOption}{article}}

4 Configuration

Input a local configuration file, if it exists.

 6 \InputIfFileExists{ltxdoc.cfg}
 7  {\typeout{*************************************^^J%
 8  * Local config file ltxdoc.cfg used^^J%
 9  *************************************}}
10  {}

5 Option Processing

11 \ProcessOptions

6 Loading article and doc

12 \LoadClass{article}
13 \RequirePackage{doc}

Make | be a ‘short verb’ character, but not in the document preamble, where an active character may interfere with packages that are loaded.

14 \AtBeginDocument{\MakeShortVerb{\|}}

As ‘doc’ documents tend to have a lot of monospaced material, Set up some tt substitutions to occur silently.

15 \DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{}
16 \DeclareFontFamily{OMS}{cmtt}{\skewchar\font'60}
17 \DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{}
18 \DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{}

This substitution is in the standard fd file, but not silent.

19 \DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{}
20 \CodelineNumbered
21 \DisableCrossrefs

Increase the text width slightly so that width the standard fonts 72 columns of code may appear in a macrocode environment.

22 \setlength{\textwidth}{355pt}

Increase the marginpar width slightly, for long command names. And increase the left margin by a similar amount

23 \addtolength\marginparwidth{30pt}
24 \addtolength\oddsidemargin{20pt}
25 \addtolength\evensidemargin{20pt}
26 \setcounter{StandardModuleDepth}{1}

7 Useful abbreviations

\cmd{\foo} Prints \foo verbatim. It may be used inside moving arguments. \cs{foo} also prints \foo, for those who prefer that syntax. (This second form may even be used when \foo is \outer).

{\cmd \atop \cs}

27 \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
28 \def\cmd@to@cs#1#2{\char\number`#2\relax}
29 \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}

\star prints * for use in documenting star-forms of commands. \marg{text} prints {⟨text⟩}, ‘mandatory argument’. \oarg{text} prints [⟨text⟩], ‘optional argument’. \parg{te,xt} prints (⟨te,xt⟩), ‘picture mode argument’.

30 \providecommand\star{%
31 {\ttfamily*}}
32 \providecommand\marg[1]{%
33 {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
34 \providecommand\oarg[1]{%
35 {\ttfamily[}\meta{#1}{\ttfamily]}}
36 \providecommand\parg[1]{%
37 {\ttfamily(}\meta{#1}{\ttfamily)}}

8 Old Comments

The L^{A}TEX 2ε sources contain a lot of code inherited from L^{A}TEX2.09. The comments in this code were not designed to be typeset, and do not contain the necessary L^{A}TEX markup. The oldcomments environment typesets these comments, automatically sensing when any control sequence appears, and implicitly adding the \verb. This procedure does not produce particularly beautiful pages, but it allows us to fully document new sections, and have some form of typeset comments on all the old code.

Scan control names and put them in tt. will actually (incorrectly) scan past \\ but this does not matter as this is almost never followed by a letter in practice.

(ie \\foo) would put foo in \ttfamily.
38 \def\oc@scan#1{%
39 \ifx\oc@bslash#1%
40  \egroup\let\next\oc@bslash\else
41 \ifcat a\noexpand#1%

42  #1\let\next\oc@scan\else
43 \ifx\oc@percent#1%
44  \def\next{\char`\%\egroup}%
45 \else
46  #1\let\next\egroup
47 \fi\fi\fi\next}
48 \def\oc@bslash{\bgroup\oc@ttf\char`\\\oc@scan}%
49 \def\oc@verb#1{%
50 \catcode`#1\active
51 \uccode`\~`#1%
52 \uppercase{\def~{{\oc@ttf\char`#1}}}}
53 \begingroup
54 \obeyspaces%
55 \catcode`\/=\catcode`\\
56 /catcode`/\/active
57 /catcode`<=/catcode`{%
58 /catcode`>=/catcode`}%
59 /catcode`/{/active%
60 /catcode`/}/active%
61 /gdef/oldc< \end{oldcomments}>%
62 /gdef/begmac<    \begin{macrocode}>%
63 /gdef/obs</def <</oc@ttf/ >>>%
64 /endgroup%
65 \begingroup
66 \catcode`\/=\catcode`\\
67 \catcode`\\=13
68 /catcode`/|=/catcode`/%
69 /catcode`/%=13
70 /gdef/oldcomments{|
71  /makeatletter
72  /let/do/oc@verb/dospecials
73  /frenchspacing/@vobeyspaces/obs
74  /raggedright
75  /oc@verb/>|
76  /oc@verb/<|
77  /let\/oc@bslash
78  /let%/oc@percent
79  /obeylines
80  /parindent/z@
81  /ttfamily/expandafter/let/expandafter/oc@ttf/the/font
82  /rmfamily
83  /hfuzz/maxdimen

84 }

85 /endgroup
86 \begingroup
87 \sloppy%
88 \obeylines%
89 \gdef\oc@percent#1^^M{%

 90  \ifvmode%
 91  \def\commentline{#1}%
 92  \ifx\commentline\oldc%
 93  \end{oldcomments}%
 94  \else%
 95  \ifx\commentline\begmac%
 96  \begin{macrocode}%
 97  \else%
 98  \leavevmode%
 99  #1^^M%
100  \fi\fi%
101  \else%
102  {\oc@ttf\char`\%}#1^^M%
103  \fi}%
104 \endgroup%

9 DocInclude

105 \@addtoreset{CodelineNo}{part}

\DocInclude More or less exactly the same as \include, but uses \DocInput on a dtx file, not

 \input on a tex file.
106 \def\partname{File}
107 \def\DocInclude#1{%
108 \relax
109 \clearpage
110 \docincludeaux
111 \def\currentfile{#1.dtx}%
112 \ifnum\@auxout=\@partaux
113  \@latexerr{\string\include\space cannot be nested}\@eha
114 \else \@docinclude#1 \fi}
115 \def\@docinclude#1 {\clearpage
116 \if@filesw \immediate\write\@mainaux{\string\@input{#1.aux}}\fi
117 \@tempswatrue\if@partsw \@tempswafalse\edef\@tempb{#1}\@for
118 \@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}\fi
119 \if@tempswa \let\@auxout\@partaux \if@filesw
120 \immediate\openout\@partaux #1.aux
121 \immediate\write\@partaux{\relax}\fi
122 \part{#1.dtx}%
123 {\let\ttfamily\relax
124 \xdef\filekey{\filekey, \thepart={\ttfamily\currentfile}}}%
125 \DocInput{#1.dtx}%
126 \clearpage
127 \@writeckpt{#1}\if@filesw \immediate\closeout\@partaux \fi
128 \else\@nameuse{cp@#1}\fi\let\@auxout\@mainaux}
129 \gdef\codeline@wrindex#1{\if@filesw
130  \immediate\write\@indexfile
131  {\string\indexentry{#1}%

132  {\filesep\number\c@CodelineNo}}\fi}%
133 \let\filesep\@empty

\aalph Special form of \alph as currently source2e.tex includes more than 26 files .

134 \def\aalph#1{\@aalph{\csname c@#1\endcsname}}
135 \def\@aalph#1{%
136 \ifcase#1\or a\or b\or c\or d\or e\or f\or g\or h\or i\or
137  j\or k\or l\or m\or n\or o\or p\or q\or r\or s\or
138  t\or u\or v\or w\or x\or y\or z\or A\or B\or C\or
139  D\or E\or F\or G\or H\or I\or J\or K\or L\or M\or
140  N\or O\or P\or Q\or R\or S\or T\or U\or V\or W\or
141  X\or Y\or Z\else\@ctrerr\fi}
\docincludeaux
142 \def\docincludeaux{%
143 \def\thepart{\aalph{part}}\def\filesep{\thepart-}%
144 \let\filekey\@gobble
145 \g@addto@macro\index@prologue{%
146  \gdef\@oddfoot{\parbox{\textwidth}{\strut\footnotesize
147  \raggedright{\bfseries File Key:} \filekey}}%
148  \let\@evenfoot\@oddfoot}%
149 \global\let\docincludeaux\relax
150 \gdef\@oddfoot{%
151 \expandafter\ifx\csname ver@\currentfile\endcsname\relax
152  File \thepart: {\ttfamily\currentfile} %
153 \else
154  \GetFileInfo{\currentfile}%
155  File \thepart: {\ttfamily\filename} %
156  Date: \filedate\ %
157  Version \fileversion
158  \fi
159  \hfill\thepage}%
160 \let\@evenfoot\@oddfoot}%
161 \def\task#1#2{}

162 ⟨/class⟩