-
-
Notifications
You must be signed in to change notification settings - Fork 245
/
doc.dtx
6338 lines (6270 loc) · 238 KB
/
doc.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment
%
% Copyright 1993-2022
% 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 2008 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>
%<+package>\providecommand\DeclareRelease[3]{}
%<+package>\providecommand\DeclareCurrentRelease[2]{}
%<+package>
%<+package>\DeclareRelease{v2.1g}{2016-02-15}
%<+package> {doc-2016-02-15.sty}
%<+package>\DeclareRelease{v2}{2021-06-01}
%<+package> {doc-2021-06-01.sty}
%<+package>\DeclareCurrentRelease{v3}{2022-06-01}
%<+package>
%<+package>\ProvidesPackage{doc}
%<+shortvrb>\ProvidesPackage{shortvrb}
%<+package|shortvrb> [2022/06/01 v3.0i
%<+package|shortvrb> Standard LaTeX documentation package V3 (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-2022 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}\xspace}
%
% \newcommand\env{\texttt}
% \newcommand\opt{\texttt}
% \newcommand\cls{\texttt}
% \newcommand\pkg{\texttt}
% \newcommand\prg{\textsf}
%
% \newcommand\DOX{\env{DoX}\xspace}
% \newcommand\api{\textsc{api}\xspace}
%
% \newcommand\fmi[1]{\par\textbf{TODO: }\textit{#1}\par}
%
% \newcommand\NewIn[1]{\leavevmode
% \marginpar{\hfill\fbox{\fbox{New in #1}}\hspace*{1em}}\ignorespaces}
%
%
%\RenewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = ,
% idxgroup = LaTeX comands\actualchar\LaTeX{} commands ,
% printtype =
% ]{Macro}{macro}
%
%\RenewDocElement[macrolike = false ,
% toplevel = false,
% idxtype = env. ,
% idxgroup = Package environments,
% printtype = \textit{env.}
% ]{Env}{environment}
%
%
%\NewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = ,
% idxgroup = Package commands,
% printtype =
% ]{InterfaceMacro}{imacro}
%
%\NewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = ,
% idxgroup = Package commands (obsolete),
% printtype =
% ]{ObsoleteInterfaceMacro}{omacro}
%
%\NewDocElement[macrolike = false ,
% toplevel = false,
% idxtype = counter ,
% idxgroup = LaTeX counters\actualchar \LaTeX{} counters ,
% printtype = \textit{counter}
% ]{LaTeXCounter}{lcounter}
%
%\NewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = counter ,
% idxgroup = TeX counters\actualchar \protect\TeX{} counters ,
% printtype = \textit{counter}
% ]{TeXCounter}{tcounter}
%
%
%\NewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = skip ,
% idxgroup = LaTeX length\actualchar \LaTeX{} length (skip) ,
% printtype = \textit{skip}
% ]{LaTeXSkip}{lskip}
%
%\NewDocElement[macrolike = true ,
% toplevel = false,
% idxtype = dimen ,
% idxgroup = LaTeX length\actualchar \LaTeX{} length (dimen) ,
% printtype = \textit{dimen}
% ]{LaTeXDimen}{ldimen}
%
%\NewDocElement[macrolike = false ,
% toplevel = false,
% idxtype = option ,
% idxgroup = Package options ,
% printtype = \textit{option}
% ]{Option}{option}
%
% \renewcommand\code[1]{\mbox{$\ell$-#1}}
% \renewcommand\main[1]{\underline{\mbox{$\ell$-#1}}}
% \setcounter{IndexColumns}{2}
%
%
% \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}}
% \GetFileInfo{doc.sty}
%
% \CheckSum{0} ^^A % keep the checksum in this file but not now :-)
%
% \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).}~\thanks
% {Extraction of \texttt{shortvrb}
% package added by Joachim Schrod (TU~Darmstadt).}~\thanks
% {Version~3 now integrates code from Didier Verna's
% \DOX package and some of his documentation was
% reused (a.k.a.\ stolen).}}
% \date{Printed \today}
%
% \MaintainedByLaTeXTeam{latex}
%
% \maketitle
%
% \begin{abstract}
% Roughly 30 years ago (version 1.0 was dated 1988/05/05) I wrote
% the first version of the \DOC package, a package to provide code
% documentation for \TeX{} code. Since then it has be used all over
% the place to document the \LaTeX{} kernel and most of the
% packages that are nowadays available. The core code of version 2
% (which is the current version) exists since 1998, i.e., for 20
% years.
%
% If I would restart from scratch I would do a lot of things
% differently these days and in fact several other people have
% tried to come up with better solutions. However, as the saying
% goes, a bad standard is better than none, \DOC has prevailed and
% changing it now in incompatible ways is probably not really
% helpful.
%
% So this is version 3 of the package with some smaller extensions
% that are upwards compatible but hopefully serve well. Most
% important modifications are the integration of the
% \pkg{hypdoc} package to enable links within the document (in
% particular from the index) is so desired. Also integrated are the
% ideas from the \DOX package by Didier Verna (although I
% offer a different interface that imho fits better with the rest
% of \DOC's interfaces). Finally I updated a few odds and ends.
% \end{abstract}
%
%
% \newpage
%
% \addtocontents{toc}{\protect\begin{multicols}{2}}
%
% ^^A{\parskip 0pt ^^A We have to reset \parskip
% ^^A (bug in \LaTeX)
% \tableofcontents
% ^^A}
%
% \changes{v1.7a}{1992/02/25}{Miscellaneous small changes to the text}
% \changes{v3.0a}{2018/03/04}{Integrated DoX package}
% \changes{v3.0a}{2018/03/04}{Interfaced hypdoc package}
%
%
%
% \section{Introduction}
%
% This is a new version of the \DOC package, written roughly 30 years
% after the initial release. As the package has been used for so long
% (and largely unchanged)
% it is absolutely important to preserve existing interfaces, even if
% we can agree that they could have been done better.
%
% So this is a light-weight change, basically adding hyperlink support
% and adding a way to provide generally \DOC elements (not just macros
% and environments) and try to do this properly (which wasn't the case
% for environments either in the past). The ideas for this have been
% stolen from the \DOX package by Didier Verna even though I
% didn't keep his interfaces.
%
% Most of the documentation below is from the earlier release which
% accounts for some inconsistencies in presentation, mea culpa.
%
%
% \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:
% \begin{quote}
% \noindent |\documentclass|\oarg{options}^^A
% \marg{document-class}\\[1pt]
% |\usepackage{doc}|\\[3pt]
% \hspace*{10pt}\meta{preamble}\\[3pt]
% |\begin{document}|\\[3pt]
% \hspace*{10pt}\meta{special input commands}\\[3pt]
% |\end{document}|
% \end{quote}
% The \meta{document-class} might be any document class, I usually
% use \texttt{article}.
%
% In the \meta{preamble} one should place declarations which
% manipulate the behavior of the \DOC{} package like
% |\DisableCrossrefs| or |\OnlyDescription|.
%
%
% \DescribeInterfaceMacro\DocInput \DescribeInterfaceMacro\IndexInput
% Finally
% the \meta{special input commands} part should contain one or
% more |\DocInput|\marg{file name} and/or
% |\IndexInput|\marg{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 |%</driver>|.
% 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 \cls{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}
\usepackage[T1]{fontenc}
\usepackage{xspace}
\OnlyDescription
\EnableCrossrefs
%\DisableCrossrefs % Say \DisableCrossrefs if index is ready
\CodelineIndex
\RecordChanges % Gather update information
\SetupDoc{reportchangedates}
%\OnlyDescription % comment out for implementation details
\setlength\hfuzz{15pt} % don't show so many
\hbadness=7000 % over- and underfull box warnings
\begin{document}
\DocInput{doc.dtx}
\end{document}
%</driver>
% \end{macrocode}
%
% \RecordIndexType{\CodelineIndex}{InterfaceMacro}
% \RecordIndexType{\DisableCrossrefs}{InterfaceMacro}
% \RecordIndexType{\DocInput}{InterfaceMacro}
% \RecordIndexType{\EnableCrossrefs}{InterfaceMacro}
% \RecordIndexType{\OnlyDescription}{InterfaceMacro}
% \RecordIndexType{\RecordChanges}{InterfaceMacro}
% \RecordIndexType{\hbadness}{TeXCounter}
% \RecordIndexType{\hfuzz}{LaTeXDimen}
%
%
% \subsection{Package options}
%
% \NewIn{v3}
% Starting with version~3 the \DOC package now offers a small number
% of package options to modify its overall behavior. These are:
% \DescribeOption[noprint]{multicol}
% \DescribeOption[noprint]{nomulticol}
% \DescribeOption[noprint]{hyperref}
% \DescribeOption[noprint]{nohyperref}
% \DescribeOption[noprint]{debugshow}
% \DescribeOption[noprint]{noindex}
% \DescribeOption[noprint]{noprint}
% \DescribeOption[noprint]{reportchangedates}
% \begin{description}
% \item[\opt{hyperref}, \opt{nohyperref}] Boolean (default \texttt{true}). Load the
% \pkg{hyperref} package and make index references to code lines
% and pages and other items clickable links. \opt{nohyperref} is
% the complementary key.
%
% \item[\opt{multicol}, \opt{nomulticol}] Boolean (default \texttt{true}). Load the
% \pkg{multicol} package for use in typesetting the index and the
% list of changes. \opt{nomulticol} is
% the complementary key.
%
% \item[\opt{debugshow}] Boolean (default \texttt{false}). Provide
% various tracing information at the terminal and in the transcript
% file. In particular show which elements are indexed.
%
% \item[\opt{noindex}] Boolean (default \texttt{false}). If set, all
% automatic indexing is suppressed. This option can also be used on
% individual elements as described below.
%
% \item[\opt{noprint}] Boolean (default \texttt{false}). If set, then
% printing of element names in the margin will be suppressed. This
% option can also be used on individual elements as described
% below.
% \item[\opt{reportchangedates}] Boolean (default \texttt{false}). If
% set, then change entries list the date after the version number in
% the change log.
% \end{description}
%
% \DescribeInterfaceMacro{\SetupDoc} Instead of providing options to the \DOC
% package you can call \cs{SetupDoc} and provide them there. This
% allows, for example, to change default values in case \DOC was already
% loaded earlier.
%
%
%
% \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}^^A
% \SortIndex{\string^\string^X}{\string\verb\verbatimchar
% \string^\string^X\verbatimchar \encapchar usage}
% To allow user
% comments, the characters |^^A| and |^^X| are both defined as a comment character
% later on.\footnote{In version 2 it was only
% \texttt{\string^\string^A}, but many keyboards combine
% \texttt{\string^} and \texttt{A} and automatically turn it into
% ``Ä''; so \texttt{\string^\string^X} was added as an
% alternative in version 3.}
% 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 \env{macrocode}
% environment.
% More exactly: before a `definition part' there should be a line
% containing
% \begin{flushleft}
% \hspace*{\MacroIndent}\verb*+% \begin{macrocode}+
% \end{flushleft}
% and after this part a line
% \begin{flushleft}
% \hspace*{\MacroIndent}\verb*+% \end{macrocode}+
% \end{flushleft}
% 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 \env{macrocode}
% environment one can also use the \env{macrocode$*$} environment
% which produces the same results except that spaces are printed as
% \nopagebreak\verb*+ + characters.
%
%
%
% \subsection{Describing the usage of macros and environments}
%
% \DescribeInterfaceMacro\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.
%
% As the argument to |\DescribeMacro| is a command name, many people
% got used to using the (incorrect) short form, i.e., omitting the
% braces around the argument as in |\DescribeMacro\foo|. This does
% work as long as the macro name consists only of ``letters''.
% However, if the name contains special characters that are normally
% not of type ``letter'' (such as |@|, or in case of \pkg{expl3} |_|
% and |:|) this will fail dramatically. |\DescribeMacro| would then
% receive only a partial command name (up to the first ``non-letter'')
% e.g., |\DescribeMacro\foo@bar| would be equivalent to
% |\DescribeMacro{\foo} @bar| and you can guess that this can
% resulting in both incorrect output and possibly low-level error
% messages.
%
% \DescribeInterfaceMacro\DescribeEnv
% An analogous macro |\DescribeEnv| should be used to indicate that a
% \LaTeX{} environment is explained. It will produce a somewhat
% different index entry and a slightly different display in the
% margin. Below I used |\DescribeEnv{verbatim}|.
%
%
% \NewIn{v3}
% Starting with version~3 the \cs{Describe...} commands accept an
% optional argument in which you can specify either \opt{noindex}
% or \opt{noprint} to suppress indexing or printing for that
% particular instance. Using both would be possible too, but pointless
% as then the commands wouldn't do anything any more.
%
%
% \subsection{Describing the definition of macros and environments}
%
% \DescribeEnv{macro}
% To describe the definition of a (new) macro we use the \env{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.
%
% \NewIn{v3}
% In fact it is now allowed to specify several macros in the argument,
% separated by commas. This is a short form for starting several
% \env{macro} environments in direct succession. Of course, you
% should then have also only one matching |\end{macro}|.
%
% \DescribeLaTeXSkip\MacrocodeTopsep
% \DescribeLaTeXSkip\MacroTopsep
% There also exist four style parameters: |\MacrocodeTopsep| and
% |\MacroTopsep| are used to control the vertical spacing above
% and below the \env{macrocode} and the \env{macro}
% \DescribeLaTeXDimen\MacroIndent
% environment, |\MacroIndent| is used to indent the lines of code
% and
% \DescribeInterfaceMacro\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}|.
%
% \DescribeEnv{environment}
% For documenting the definition of environments one can use the
% environment \texttt{environment} which works like the \texttt{macro}
% environment, except that it expects an \meta{env-name}
% (without a backslash)
% as its argument and internally provides different index
% entries suitable for environments.
% Nowadays you can alternatively specify a comma-separated list of environments.
%
% \NewIn{v3}
% Starting with version~3 these environments accept an optional
% argument in which you can specify \opt{noindex} or \opt{noprint} or
% both to suppress indexing or printing for that particular
% instance. If any such setting is made on the environment level it
% overwrites whatever default was given when the \DOC element was
% defined or when the package was loaded.
%
%
%
%
% \subsection{Formatting names in the margin}
%
% \DescribeInterfaceMacro\PrintDescribeMacro
% \DescribeInterfaceMacro\PrintDescribeEnv
% \DescribeInterfaceMacro\PrintMacroName
% \DescribeInterfaceMacro\PrintEnvName
% As mentioned earlier, some macros and environment
% print their arguments in the margin. The actual formatting is 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 redefine them
% accept their argument and do nothing with it.}
% They are named |\PrintDescribeMacro| and |\PrintDescribeEnv| (defining
% how |\DescribeMacro| and |\DescribeEnv| behave) and
% |\PrintMacroName| and
% |\PrintEnvName| (called by the \env{macro} and \env{environment}
% environments, respectively).
%
%
% \subsection{Providing further documentation items}
%
% Out of the box the \DOC package offers the above commands and
% environments to document macros and environments.
% \NewIn{v3}
% With version 3
% this has now been extended in a generic fashion so that you can
% easily provide your own items, such as counters, length register,
% options etc.
%
% \DescribeInterfaceMacro{\NewDocElement}
% The general syntax for providing a new \DOC element is
% \begin{quote}
% \cs{NewDocElement}\oarg{options}\marg{element-name}\marg{env-name}
% \end{quote}
% By convention the \meta{element-name} has the first letter
% uppercased as in \texttt{Env} or \texttt{Macro}.
%
% Such a declaration will define for you
% \begin{itemize}
% \item the command |\Describe|\meta{element-name} which has the
% syntax
% \begin{quote}
% |\Describe|\meta{element-name}\oarg{options}\marg{element}
% \end{quote}
%
% \item the environment \meta{env-name} which has the syntax
% \begin{quote}
% \cs{begin}\marg{env-name}\oarg{options}\marg{element}
% \end{quote}
%
% \item the display command |\PrintDescribe|\meta{element-name} with
% the syntax
% \begin{quote}
% |\PrintDescribe|\meta{element-name}\marg{element}
% \end{quote}
%
% \item and the
% |\Print|\meta{element-name}|Name| display command for the
% environment.
% \end{itemize}
% If any of the commands or the environment is already defined (which
% especially with the \meta{env-name} is a danger) then you will
% receive an error telling you so.
%
% \DescribeInterfaceMacro{\RenewDocElement}
% If you want to modify an existing \DOC element use
% |\RenewDocElement| instead.
%
% For example, the already provided ``\texttt{Env}'' \DOC element could have been
% defined simply by making the declaration
% |\NewDocElement{Env}{environment}|
% though that's not quite what has been done, as we will see later.
%
% \DescribeOption[noprint]{macrolike}
% \DescribeOption[noprint]{envlike}
% \DescribeOption[noprint]{toplevel}
% \DescribeOption[noprint]{notoplevel}
% \DescribeOption[noprint]{idxtype}
% \DescribeOption[noprint]{printtype}
% \DescribeOption[noprint]{idxgroup}
% The \meta{options} are keyword/value and define further details on
% how that \DOC element should behave. They are:
% \begin{description}
% \item[\opt{macrolike}] Boolean (default \opt{false}). Does this \DOC
% element starts with a backslash?
%
% \item[\opt{envlike}] Boolean. Complementary option to
% \opt{macrolike}.
%
% \item[\opt{toplevel}] Boolean (default \opt{true}). Should all
% a top-level index entry be made? If set to \texttt{false} then
% either no index entries are produced or only grouped index entries
% (see \opt{idxgroup} for details).
%
% \item[\opt{notoplevel}] Boolean. Complementary option to
% \opt{toplevel}.
%
% \item[\opt{idxtype}] String (default \meta{env-name}). What to put
% (in parentheses if non-empty) at the end of a top-level index entry.
%
% \item[\opt{printtype}] String (default \meta{env-name}). What to put
% (in parentheses if non-empty) after an element name in the margin.
%
% \item[\opt{idxgroup}] String (default
% \meta{env-name}\texttt{s}). Name of the top-level index entry if
% entries are grouped. They are only grouped if this option is
% non-empty.
%
% \item[\opt{noindex}] Boolean (default \texttt{false}). If set this
% will suppress indexing for elements of this type. This setting
% overwrite any global setting of \opt{noindex}.
%
% \item[\opt{noprint}] Boolean (default \texttt{false}). If set this
% will suppress printing the element name in the margin. This setting
% overwrite any global setting of \opt{noprint}.
% \end{description}
% As usual giving a boolean option without a value sets it to
% \texttt{true}.
% \subsection{Displaying sample code 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 \env{verbatim} environment is slightly altered to suppress
% those
% characters.\footnote{These macros were written by Rainer
% Schöpf~\cite{art:verbatim}. He also
% provided a new \env{verbatim} environment
% which can be used inside of other macros.}
% \DescribeEnv{verbatim*}
% The \env{verbatim$*$} environment is changed in the same way.
% \changes{v1.7a}{1992/02/26}{Documented \cs{verb} change.}
% \DescribeInterfaceMacro\verb
% The |\verb| command is re-implemented to give an error report if a
% newline appears in its argument.
% The \env{verbatim} and \env{verbatim$*$} environments set text
% in the style defined by |\MacroFont|~(\S\ref{sec:macrofont}).
%
%
% \subsection{Using a special escape character}
%
% \DescribeInterfaceMacro\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 \env{macrocode} environment and its counterpart
% \env{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 \verb=\|= for example to denote that `\verb+|+'
% is used as an escape character. |\SpecialEscapechar| only
% changes the behavior of the next \env{macrocode} or
% \env{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}
%
% \DescribeInterfaceMacro\DisableCrossrefs \DescribeInterfaceMacro\EnableCrossrefs As
% already mentioned, every macro name used within a
% \env{macrocode} or \env{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\footnote{This
% comment was written about 30 years ago. \TeX{} is still considerably
% slower but while it took minutes to process a large document (such
% as the \LaTeX{} kernel documentation) it takes seconds or less these
% days. Thus \cs{DisableCrossrefs} isn't really that necessary these
% days.} 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, \cs{EnableCrossrefs} changes
% things more drastically; any following call to \cs{DisableCrossrefs}
% which might be present in the source will be ignored.}
%
%
% \DescribeInterfaceMacro\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.
% \DescribeInterfaceMacro\PageIndex Using |\PageIndex| makes all index
% entries refer to their page number; with
% \DescribeInterfaceMacro\CodelineIndex |\CodelineIndex|, index entries
% produced by |\DescribeMacro| and |\DescribeEnv| and possibly further
% |\Describe...| commands refer to a page number
% but those produced by the \env{macro} environment (or other \DOC
% element environments) refer to the
% code lines, which will be numbered automatically.\footnote{The line
% number is actually that of the first line of the first
% \env{macrocode} environment in the \env{macro} environment.}
% \DescribeInterfaceMacro\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.
%
% \DescribeInterfaceMacro\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
% \prg{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 \prg{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).
%
% \DescribeInterfaceMacro{\actualchar}
% The |\actualchar| is used to separate the `key' and the actual
% index entry.
% \DescribeInterfaceMacro{\quotechar}
% The |\quotechar| is used before a special index program
% character to suppress its special meaning.
% \DescribeInterfaceMacro{\encapchar}
% The |\encapchar| separates the indexing information from a
% letter string which \prg{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.
% \DescribeInterfaceMacro{\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.
%
% \fmi{describe old \cs{SpecialMainIndex} and \cs{SpecialUsageIndex}}
%
% \DescribeInterfaceMacro\SpecialMainMacroIndex
% \DescribeInterfaceMacro\SpecialMainEnvIndex
% To produce a main index entry for a macro the
% |\SpecialMainMacroIndex| macro\footnote{This macro is called by the
% \env{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
% \env{environment} environment.}
%
% \DescribeInterfaceMacro\SpecialMacroIndex
% \DescribeInterfaceMacro\SpecialEnvIndex
% To index the usage of a macro or an environment
% |\SpecialMacroIndex| and |\SpecialEnvIndex| may be used.
%
% All these macros are normally used by other macros; you will need
% them only in an emergency.
%
% \NewIn{v3}
% If further code elements are declared with
% |\NewDocElement|\marg{name}\texttt{...} then this sets up
% additional indexing commands, e.g.,
% \cs{SpecialMain\meta{name}Index}.
%
% \DescribeInterfaceMacro\SpecialIndex
% The \env{macrocode} environment is automatically indexing macros
% (normally by code line number). You can (with care) also do this
% manually by
% |\SpecialIndex|. However, note that if |\CodelineIndex| is used
% this will generate an entry referring to the last code line which is
% usually not what you want. It does, however, make some sense if you
% always refer to pages only, i.e., if you use |\PageIndex|.
%
% \DescribeInterfaceMacro\SpecialShortIndex
% \NewIn{v3}
% For single character macros, e.g., |\{|, doesn't always work
% correctly.
% For this reason there is now also
% a special variant the can produce correct index entries for them.
%
% \DescribeInterfaceMacro\SortIndex
% Additionally a |\SortIndex| command is provided. It takes two
% arguments---the sort key and the actual index entry.
%
% \DescribeInterfaceMacro\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?\+?)
% then that caused a problem because you ended up with an
% index entry containing \verb?\verb+\++?
% which will be typeset as `\verb+\++' and not as `\verb?\+?'.
% \NewIn{v3}
% In version 3 this is now automatically taken care of (with the help
% of the |\SpecialShortIndex| command).
%
% \DescribeInterfaceMacro\*
% 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}
%
%
% \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
% \prg{makeindex} or your favorite alternative. You need a
% suitable style file for \prg{makeindex} (specified by the
% \texttt{-s} switch). A suitable one is supplied with \DOC{},
% called \texttt{gind.ist}.
%
% \DescribeInterfaceMacro\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 |\MaybeStop| 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.
% \DescribeLaTeXCounter{IndexColumns}
% 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 \env{theindex}
% environment is redefined.
% \DescribeLaTeXDimen\IndexMin
% When the \env{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