-
-
Notifications
You must be signed in to change notification settings - Fork 245
/
docstrip.dtx
4543 lines (4533 loc) · 166 KB
/
docstrip.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 (C) 1993-2021
% The LaTeX 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
\catcode`\{=1
\catcode`\}=2
\def\filename{docstrip.dtx}
\def\fileversion{v2.6a}
\def\filedate{2020-11-23}
\def\docdate {2020-11-23}
%%
%
%\iffalse
%
%% The docstrip program for use with TeX.
%% Copyright (C) 1989-1991 Frank Mittelbach
%% Copyright (C) 1992-1995 Johannes Braams, Denys Duchier,
%% Frank Mittelbach
%% Copyright (C) 1995 Marcin Woli\'nski
%% Copyright (C) 1996-1997 Mark Wooding, Marcin Woli\'nski
%% Copyright (C) 1998-2021 LaTeX Project and the above authors.
%% All rights are reserved.
%%
%
% \fi
%
% \changes{2.0b}{1991/05/29}{Added bugfix from Denys}
% \changes{2.0c}{1991/05/29}{Allow almost all characters in guard (DD)}
% \changes{2.0d}{1991/05/31}{Started merging in some of Franks code}
% \changes{2.0j}{1992/03/05}{Wrote introduction}
% \changes{2.0m}{1992/04/21}{Renamed all macros that deal with the
% parsing of boolean expressions}
% \changes{2.0m}{1992/04/25}{Removed dependency from ltugboat,
% incorporated driver file into source.}
% \changes{2.0m}{1992/04/25}{Added some missing percents; corrected some
% typos}
% \changes{2.0m-DL}{1992/05/08}{Various small corrections to English and
% typos}
% \changes{2.0q}{1992/07/01}{Changed all dates to yy/mm/dd for better
% sorting}
% \changes{2.2a}{1993/12/02}{Update for LaTeX2e}
% \changes{2.2c}{1993/12/17}{Renamed texsys.tex to texsys.cfg.}
% \changes{2.3a}{1995/08/17}{Swapped Primary with Secondary since
% expressions are generally described bottom-up}
% \changes{2.3b}{1995/08/22}{Completely changed expressions parser}
% \changes{2.3b}{1995/08/23}{Removed mechanism for checking if previous
% one-line guard is same as current (\cs{testOption},
% \cs{closeOption})---this is not a common
% case and testing complicates things unnecessarily}
% \changes{2.3c}{1995/08/24}{When file is multiply listed in \cs{file}
% clause it \emph{is} multiply read}
% \changes{2.3c}{1995/09/04}{Changed some dirty tricks to be
% less/more dirty---all uses of \cs{afterfi}}
% \changes{2.3e}{1995/09/25}{Directories support}
% \changes{2.3e}{1995/10/24}{added \cs{makepathname} to support
% systems with bizare pathnames}
% \changes{2.3e}{1995/10/25}{batch files work by \cs{input}}
% \changes{2.3e}{1996/10/02}{Introduced ``open lists''}
% \changes{2.4a}{1996/06/06}{Add stream limits (MDW)}
% \changes{2.4c}{1996/06/11}{Add initex support (DPC)}
% \changes{v2.6a}{2020-07-07}{Added the handling of @@-modules from
% \texttt{l3docstrip.dtx} (gh/337)}
%
% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ }
% \DoNotIndex{\@ne}
% \DoNotIndex{\advance,\begingroup,\catcode,\closein,\closeout}
% \DoNotIndex{\day,\def,\edef,\else,\empty,\endgroup,\errmessage}
% \DoNotIndex{\expandafter,\fi,\futurelet,\gdef,\global,\if,\ifeof}
% \DoNotIndex{\ifx,\immediate,\let,\loop,\m@ne,\message,\month}
% \DoNotIndex{\newcount}
% \DoNotIndex{\newif,\newlinechar,\newread,\newtoks,\newwrite}
% \DoNotIndex{\noexpand,\openin,\openout,\par,\read,\relax,\repeat}
% \DoNotIndex{\space,\the,\undefined,\write,\xdef,\year,\z@}
%
% ^^A some definitions for this documentation
%
% \newcommand{\ds}{\textsf{DocStrip}} ^^A maybe?
% \newcommand{\bsl}{\protect\bslash}
% \newcommand{\note}[1]{\marginpar{\textbf{#1}}}
% \newcommand{\netaddress}[1]{\texttt{#1}}
%
% ^^A override the default in doc.sty
% \makeatletter
% \renewenvironment{theglossary}{%
% \glossary@prologue%
% \GlossaryParms \let\item\@idxitem \ignorespaces}%
% {}
% \makeatother
%
%
% \changes{2.1c}{1993/02/25}{Added a setting for StandardModuleDepth}
% \setcounter{StandardModuleDepth}{1}
%
% \title{The \ds{} program%
% \thanks{This file has version number \fileversion,
% last revised \filedate,
% documentation dated \docdate.}}
%
% \changes{2.1b}{1993/02/23}{modified mailaddress of Johannes}
% \changes{2.4i}{1998/01/18}{removed mail addresses as it is hopeless
% to keep them up-to-date}
% \author{%
% Frank Mittelbach
% \and
% Denys Duchier
% \and
% Johannes Braams
% \and
% Marcin Woli\'nski
% \and
% Mark Wooding
% }
%
% \date{Printed \today}
%
% \MaintainedByLaTeXTeam{latex}
% \maketitle
%
% \begin{abstract}
% This document describes the implementation of the \ds{} program.
% The original version of this program was developed by Frank
% Mittelbach to accompany his \texttt{doc.sty} which enables literate
% programming in \LaTeX\@. Denys Duchier rewrote it to run either
% with \TeX\ or with \LaTeX, and to allow full boolean expressions in
% conditional guards instead of just comma-separated lists.
% Johannes Braams re-united the two implementations, documented and
% debugged the code.
%
% In September 1995 Marcin Woli\'nski changed many parts of the
% program to make use of \TeX's ability to write to multiple files
% at the same time to avoid re-reading sources. The performance
% improvement of version~2.3 came at a price of compatibility with
% some more obscure operating systems which limit the number of
% files a process can keep open. This was corrected in September
% 1996 by Mark Wooding and his changes were ``creatively merged''
% by Marcin Woli\'nski who made at the same time changes in batch
% files processing, handling of preambles and introduced ``verbatim
% mode''. After all that, David Carlisle merged the new version into
% the \LaTeX\ sources, and made a few other changes, principally
% making \ds{} work under initex, and removing the need for
% batch files to say \verb|\def\batchfile{...}|.
% \end{abstract}
%
% \section{Introduction}
%
% \subsection{Why the \ds{} program?} When Frank Mittelbach created
% the \texttt{doc} package, he invented a way to combine \TeX\ code
% and its documentation. From then on it was more or less possible
% to do literate programming in \TeX.
%
% This way of writing \TeX\ programs obviously has great
% advantages, especially when the program becomes larger than a
% couple of macros. There is one drawback however, and that is
% that such programs may take longer than expected to run because
% \TeX\ is an interpreter and has to decide for each line of the
% program file what it has to do with it. Therefore, \TeX\ programs
% may be sped up by removing all comments from them.
%
% By removing the comments from a \TeX\ program a new problem is
% introduced. We now have two versions of the program and both of
% them {\em have\/} to be maintained. Therefore it would be nice to
% have a possibility to remove the comments automatically, instead
% of doing it by hand. So we need a program to remove comments from
% \TeX\ programs. This could be programmed in any high level
% language, but maybe not everybody has the right compiler to
% compile the program. Everybody who wants to remove comments from
% \TeX\ programs has \TeX\@. Therefore the \ds{} program is
% implemented entirely in \TeX.
%
% \subsection{Functions of the \ds{} program}
%
% Having created the \ds{} program to remove comment lines from
% \TeX\ programs\footnote{Note that only comment lines, that is
% lines that start with a single \texttt{\%} character, are removed;
% all other comments stay in the code.} it became feasible to do more
% than just strip comments.\\ Wouldn't it be nice to have a way to
% include parts of the code only when some condition is set true?
% Wouldn't it be as nice to have the possibility to split the
% source of a \TeX\ program into several smaller files and combine
% them later into one `executable'?\\ Both these wishes have been
% implemented in the \ds{} program.
%
% \section{How to use the \ds{} program}
% A number of ways exist to use the \ds{} program:
% \begin{enumerate}
% \item The usual way to use \ds{} is to write a \emph{batch file}
% in such a way that it can be directly processed by \TeX{}.
% The batch file should contain the commands described below for
% controlling the \ds{} program.
% This allows you to set up a distribution where you can instruct
% the user to simply run
% \begin{quote}
% \texttt{TEX} \meta{batch file}
% \end{quote}
% to generate the executable versions of your files from the
% distribution sources.
% Most of the \LaTeX\ distribution is packaged this way.
% To produce such a batch file include a statement in your
% `batch file' that
% instructs \TeX\ to read \texttt{docstrip.tex}.
% The beginning of such a file would look like:
%\begin{verbatim}
% \input docstrip
% ...
%\end{verbatim}
% By convention the batch file should have extension |.ins|. But
% these days \ds{} in fact work with any extension.
%
% \item Alternatively you can instruct \TeX\ to read the file
% \texttt{docstrip.tex} and to see what happens. \TeX\ will ask
% you a few questions about the file you would like to be
% processed. When you have answered these questions it does
% its job and strips the comments from your \TeX\ code.
% \end{enumerate}
%
% \section{Configuring \ds}
% \subsection{Selecting output directories}
% \changes{2.3e}{1996/09/19}{Added documentation}
% Inspired by a desire to simplify reinstallations of \LaTeXe{} and
% to support operating systems which have an upper limit on the
% number of files allowed in a directory, \ds\ now allows
% installation scripts to specify output directories for files it
% creates. We suggest using TDS (\TeX\ directory structure) names
% of directories relative to \texttt{texmf} here. However these
% names should be thought of as a labels rather than actual names
% of directories. They get translated to actual system-dependent
% pathnames according to commands contained in a configuration file
% named \texttt{docstrip.cfg}.
%
% The configuration file is read by \ds{} just before it starts to
% process any batch file commands.
%
% If this file is not present \ds{} uses some default settings which
% ensure that files are only written to the current directory.
% However by use of this configuration file, a site maintainer can
% `enable' features of \ds{} that allow files to be written to
% alternative directories.
%
% \DescribeMacro{\usedir}
% Using this macro package author can tell where a file should be
% installed. All |\file|s generated in the scope of that
% declaration are written to a directory specified by its one
% argument. For example in \LaTeXe{} installation following
% declarations are used:
%\begin{verbatim}
% \usedir{tex/latex/base}
% \usedir{makeindex}
%\end{verbatim}
% And standard packages use
%\begin{verbatim}
% \usedir{tex/latex/tools}
% \usedir{tex/latex/babel}
%\end{verbatim}
% etc.
%
% \DescribeMacro{\showdirectory}
% Used to display directory names in messages. If some label is not
% defined it expands to |UNDEFINED (label is ...)| otherwise to a
% directory name. It is probably a good idea for every installation
% script to display at startup list of all directories that would
% be used and asking user to confirm that.
%
% The above macros are used by package/installation script
% author. The following macros are used in a configuration file,
% |docstrip.cfg|, by a system administrator to
% describe her/his local directory structure.
%
% \DescribeMacro{\BaseDirectory} This macro is administrator's way of
% saying ``yes, I want to use that directories support of
% yours''. \ds{} will write only to current directory unless your
% config has a call to this macro. (This means \ds{} won't write to
% random directories unless you tell it to, which is nice.) Using
% this macro you can specify a base directory for \TeX-related
% stuff. E.g., for many Unix systems that would be
%\begin{verbatim}
% \BaseDirectory{/usr/local/lib/texmf}
%\end{verbatim}
% and for standard em\TeX{} installation
%\begin{verbatim}
% \BaseDirectory{c:/emtex}
%\end{verbatim}
%
% \DescribeMacro{\DeclareDir}
% Having specified the base directory you should tell \ds{} how to
% interpret labels used in |\usedir| commands. This is done with
% |\DeclareDir| with two arguments. The first is the label and the
% second is actual name of directory relative to base
% directory. For example to teach \ds{} using standard em\TeX{}
% directories one would say:
%\begin{verbatim}
% \BaseDirectory{c:/emtex}
% \DeclareDir{tex/latex/base}{texinput/latex2e}
% \DeclareDir{tex/latex/tools}{texinput/tools}
% \DeclareDir{makeindex}{idxstyle}
%\end{verbatim}
% This will cause base latex files and font descriptions to be
% written to directory |c:\emtex\texinput\latex2e|, files of the
% \texttt{tools} package to be written to |c:\emtex\texinput\tools|
% and makeindex files to |c:\emtex\idxstyle|.
%
% Sometimes it is desirable to put some files outside of the base
% directory. For that reason |\DeclareDir| has a star form
% specifying absolute pathname. For example one could say
%\begin{verbatim}
% \DeclareDir*{makeindex}{d:/tools/texindex/styles}
%\end{verbatim}
%
% \DescribeMacro{\UseTDS}
% Users of systems conforming to TDS may well ask here ``do I
% really need to put a dozen of lines like
%\begin{verbatim}
% \DeclareDir{tex/latex/base}{tex/latex/base}
%\end{verbatim}
% in my config file''. The answer is |\UseTDS|. This macro causes
% \ds{} to use labels themselves for any directory you haven't
% overridden with |\DeclareDir|. The default behaviour is to raise
% an error on undefined labels because some users may want to know
% exactly where files go and not to allow \ds{} to write to random
% places. However I (MW) think this is pretty cool and my
% config says just (I'm running te\TeX{} under Linux)
%\begin{verbatim}
% \BaseDirectory{/usr/local/teTeX/texmf}
% \UseTDS
%\end{verbatim}
%
% The important thing to note here is that it is impossible to create
% a new directory from inside \TeX{}. So however you configure
% \ds, you need to create all needed directories before running
% the installation. Authors may want to begin
% every installation script by displaying a list of directories
% that will be used and asking user if he's sure all of them
% exist.
%
% Since file name syntax is OS specific \ds{} tries to guess it
% from the current directory syntax. It should succeed for Unix,
% MSDOS, Macintosh and VMS. However \ds{} will only initially
% know the current directory syntax if it is used with \LaTeX.
% If used with plain\TeX\ or initex it will not have this
% information\footnote{Except when processing the main
% \texttt{unpack.ins} batch file for the \LaTeX\ distribution, which
% takes special measures so that initex can learn the directory
% syntax.}.
% If you often use \ds{} with formats other than \LaTeX\ you should
% \emph{start} the file |docstrip.cfg| with a definition of
% |\WriteToDir|. E.g.,
% |\def\WriteToDir{./}| on MSDOS/Unix,
% |\def\WriteToDir{:}| on Macintosh,
% |\def\WriteToDir{[]}| on VMS.
%
% If your system requires something
% completely different you can define in |docstrip.cfg| macros
% |\dirsep| and |\makepathname|. Check for their definition in the
% implementation part. If you want some substantially different
% scheme of translating |\usedir| labels into directory names try
% redefining macro |\usedir|.
%
% \subsection{Setting maximum numbers of streams}
%
% \DescribeMacro{\maxfiles}
% In support of some of the more obscure operating systems, there's
% a limit on the number of files a program can have open. This can
% be expressed to \ds\ through the |\maxfiles| macro. If the number
% of streams \ds\ is allowed to open is $n$, your configuration file
% can say |\maxfiles{|$n$|}|, and \ds\ won't try to open more files
% than this. Note that this limit won't include files which are
% already open. There'll usually be two of these: the installation
% script which you started, and the file |docstrip.tex| which it
% included; you must bear these in mind yourself. \ds\ assumes
% that it can open at least four files before it hits some kind of
% maximum: if this isn't the case, you have real problems.
%
% \DescribeMacro{\maxoutfiles}
% Maybe instead of having a limit on the number of files \TeX\ can
% have open, there's a limit on the number of files it can write
% to (e.g., \TeX\ itself imposes a limit of 16~files being written
% at a time). This can be expressed by saying |\maxoutfiles{|$m$|}|
% in a configuration file. You must be able to have at least one
% output file open at a time; otherwise \ds\ can't do anything at
% all.
%
% Both these options would typically be put in the |docstrip.cfg|
% file.
%
%
% \section{The user interface}
%
% \subsection{The main program}
% \DescribeMacro{\processbatchFile} The `main program' starts with
% trying to process a batch file, this is accomplished by calling
% the macro |\processbatchFile|. It counts the number of batch
% files it processes, so that when the number of files processed is
% still zero after the call to |\processbatchFile| appropriate
% action can be taken.
%
% \DescribeMacro{\interactive} When no batch files have been processed
% the macro |\interactive| is called. It prompts the user for
% information. First the extensions of the input and output files
% is determined. Then a question about optional code is asked and
% finally the user can give a list of files that have to be
% processed.
%
% \DescribeMacro{\ReportTotals} When the \texttt{stats} option is
% included in the \ds{}-program it keeps a record of the number of
% files and lines that are processed. Also the number of comments
% removed and passed as well as the number of code lines that were
% passed to the output are accounted. The macro |\ReportTotals|
% shows a summary of this information.
%
% \subsection{Batchfile commands}
%
% The commands described in this section are available to build a
% batch file for \TeX.
%
% \DescribeMacro{\input}
% All \ds{} batch files should start with the line: |\input docstrip|
%
% Do not use the \LaTeX\ syntax |\input{docstrip}| as batch files may
% be used with plain~\TeX\ or ini\TeX.
% You may find that old batch files always have a line
% |\def\batchfile{|\meta{filename}|}|
% just before the input.
% Such usage is still supported but is now discouraged, as it causes
% \TeX\ to re-input the same file, using up one of its limited number
% of input streams.
%
% \DescribeMacro{\endbatchfile}
% All batch files should end with this command. Any lines after this
% in the file are ignored. In old files that start
% |\def\batchfile{|\ldots\ this command is optional, but is a good
% idea anyway. If this command is omitted from a batchfile then
% normally \TeX\ will go to its interactive |*| prompt, so you may
% stop \ds{} by typing |\endbatchfile| to this prompt.
%
% \DescribeMacro{\generate}
% \DescribeMacro{\file}
% \DescribeMacro{\from}
% The main reason for constructing a \ds{} command file is to
% describe what files should be generated, from what sources and
% what optional (`guarded') pieces of code should be included. The
% macro |\generate| is used to give \TeX\ this information. Its
% syntax is:
% \begin{quote}
% |\generate{|[|\file{|\meta{output}|}{|[|\from{|^^A
% \meta{input}|}{|\meta{optionlist}|}|]*|}|]*|}|
% \end{quote}
% The \meta{output} and \meta{input} are normal file specifications
% as are appropriate for your computer system. The
% \meta{optionlist} is a comma separated list of `options' that
% specify which optional code fragments in \meta{input} should be
% included in \meta{output}. Argument to |\generate| may contain
% some local declarations (e.g., the |\use...| commands described
% below) that will apply to all |\file|s after them. Argument to
% |\generate| is executed inside a group, so all local declarations
% are undone when |\generate| concludes.
%
% It is possible to specify multiple input files, each with its own
% \meta{optionlist}. This is indicated by the notation [\ldots]*.
% Moreover there can be many |\file| specifications in one
% |\generate| clause. This means that all these \meta{output} files
% should be generated while reading each of \meta{input} files
% once. Input files are read in order of first appearance in this
% clause. E.g.
%\begin{verbatim}
% \generate{\file{p1.sty}{\from{s1.dtx}{foo,bar}}
% \file{p2.sty}{\from{s2.dtx}{baz}
% \from{s3.dtx}{baz}}
% \file{p3.sty}{\from{s1.dtx}{zip}
% \from{s2.dtx}{zip}}
% }
%\end{verbatim}
% will cause \ds{} to read files \texttt{s1.dtx}, \texttt{s2.dtx},
% \texttt{s3.dtx} (in that order) and produce files
% \texttt{p1.sty}, \texttt{p2.sty}, \texttt{p3.sty}.
%
% The restriction to at most 16 output streams open in a while
% does not mean that you can produce at most 16 files with one
% |\generate|. In the example above only 2 streams are needed,
% since while \texttt{s1.dtx} is processed only \texttt{p1.sty} and
% \texttt{p3.sty} are being generated; while reading
% \texttt{s2.dtx} only \texttt{p2.sty} and \texttt{p3.sty}; and
% while reading \texttt{s3.dtx} file \texttt{p2.sty} . However
% example below needs 3 streams:
%\begin{verbatim}
% \generate{\file{p1.sty}{\from{s1.dtx}{foo,bar}}
% \file{p2.sty}{\from{s2.dtx}{baz}
% \from{s3.dtx}{baz}}
% \file{p3.sty}{\from{s1.dtx}{zip}
% \from{s3.dtx}{zip}}
% }
%\end{verbatim}
% Although while reading \texttt{s2.dtx} file \texttt{p3.sty} is
% not written it must remain open since some parts of
% \texttt{s3.dtx} will go to it later.
%
% Sometimes it is not possible to create a file by reading all
% sources once. Consider the following example:
%\begin{verbatim}
% \generate{\file{p1.sty}{\from{s1.dtx}{head}
% \from{s2.dtx}{foo}
% \from{s1.dtx}{tail}}
% \file{s1.drv}{\from{s1.dtx}{driver}}
% }
%\end{verbatim}
% To generate \texttt{p1.sty} file \texttt{s1.dtx} must be read
% twice: first time with option \texttt{head}, then file
% \texttt{s2.dtx} is read and then \texttt{s1.dtx} again this time
% with option \texttt{tail}. \ds{} handles this case correctly: if
% inside one |\file| declaration there are multiple |\from|es with
% the same input file this file \emph{is} read multiple times.
%
% If the order of |\from|s specified in one of your |\file|
% specifications does not match the order of input files
% established by previous |\file|s, \ds{} will raise an error and
% abort. Then you may either read one of next sections or give up
% and put that file in separate |\generate| (but then sources will
% be read again just for that file).
%
% \paragraph{For impatient.} Try following algorithm: Find
% file that is generated from largest number of sources, start
% writing |\generate| clause with this file and its sources in
% proper order. Take other files that are to be generated and add
% them checking if they don't contradict order of sources for the
% first one. If this doesn't work read next sections.
%
% \paragraph{For mathematicians.} Relation ``file $A$ must be
% read before file $B$'' is a partial order on the set of all your
% source files. Each |\from| clause adds a chain to this order.
% What you have to do is to perform a topological sort i.e. to
% extend partial order to linear one. When you have done it just
% list your source files in |\generate| in such a way that order of
% their first appearance in the clause matches linear order. If
% this cannot be achieved read next paragraph. (Maybe future
% versions of \ds{} will perform this sort automatically, so all
% these troubles will disappear.)
%
% \paragraph{For that who must know that all.} There is a
% diverse case when it's not possible to achieve proper order of
% reading source files. Suppose you have to generate two files,
% first from \texttt{s1.dtx} and \texttt{s3.dtx} (in that order)
% and second from \texttt{s2.dtx} and \texttt{s3.dtx}. Whatever
% way you specify this the files will be read in either as
% \texttt{s1 s3 s2} or \texttt{s2 s3 s1}. The key to solution is
% magical macro |\needed| that marks a file as needed to be input
% but not directing any output from it to current |\file|. In our
% example proper specification is:
%\begin{verbatim}
% \generate{\file{p1.sty}{\from{s1.dtx}{foo}
% \needed{s2.dtx}
% \from{s3.dtx}{bar}}
% \file{p2.sty}{\from{s2.dtx}{zip}
% \from{s3.dtx}{zap}}
% }
%\end{verbatim}
%
%
% \DescribeMacro{\askforoverwritetrue}
% \DescribeMacro{\askforoverwritefalse}
% These macros specify what should happen if a file that is to be
% generated already exists. If |\askforoverwritetrue| is active
% (the default) the user is asked whether the file should be
% overwritten. If however |\askforoverwritefalse| was issued
% existing files will be overwritten silently. These switches are
% local and can be issued in any place in the file even inside
% |\generate| clause (between |\file|s however).
%
% \DescribeMacro{\askonceonly}
% You might not want to set |\askforoverwritefalse| in a batch file
% as that says that it us always all right to overwrite other people's
% files. However for large installations, such as the base \LaTeX\
% distribution, being asked individually about hundreds of files
% is not very helpful either. A batchfile may therefore specify
% |\askonceonly|. This means that after the first time the batchfile
% asks the user a question, the user is given an option of to change
% the behaviour so that `yes' will be automatically assumed for all
% future questions. This applies to any use of the \ds{} command
% |\Ask| including, but not restricted to, the file overwrite
% questions controlled by |\askforoverwritetrue|.
%
% \DescribeMacro{\preamble}
% \DescribeMacro{\endpreamble}
% \DescribeMacro{\postamble}
% \DescribeMacro{\endpostamble}
% It is possible to add a number of lines to the output of the
% \ds{} program. The information you want to add to the start of
% the output file should be listed between the |\preamble| and
% |\endpreamble| commands; the lines you want to add to the end of
% the output file should be listed between the |\postamble| and
% |\endpostamble| commands. Everything that \ds{} finds for both
% the pre- and postamble it writes to the output file, but preceded
% with value of |\MetaPrefix| (default is two \%-characters). If
% you include a |^^J| character in one of these lines, everything
% that follows it on the same line is written to a new line in the
% output file. This `feature' can be used to add a |\typeout| or
% |\message| to the stripped file.
%
% \DescribeMacro{\declarepreamble}
% \DescribeMacro{\declarepostamble}
% \DescribeMacro{\usepreamble}
% \DescribeMacro{\usepostamble}
% \DescribeMacro{\nopreamble}
% \DescribeMacro{\nopostamble}
% Sometimes it is desirable to have different preambles for different
% files of a larger package (e.g., because some of them are
% customisable configuration files and they should be marked as
% such). In such a case one can say |\declarepreamble\somename|,
% then type in his/her preamble, end it with |\endpreamble|,
% and later on |\usepreamble\somename| to switch to this
% preamble.
% If no preamble should be used you can deploy the |\nopreamble|
% command. This command is equivalent to saying |\usepreamble\empty|.
% The same mechanism works for postambles, |\use...|
% declarations are local and can appear inside |\generate|.
%
% Commands |\preamble| and |\postamble| define and activate
% pre(post)ambles named |\defaultpreamble| and |\defaultpostamble|.
%
% \DescribeMacro{\batchinput}
% The batch file commands can be put into several batch files which
% are then executed from a master batch file. This is, for example,
% useful if a distribution consists of several distinct parts. You
% can then write individual batch files for every part and in
% addition a master file that simply calls the batch files for the
% parts. For this, call the individual batch files from the master
% file with the command |\batchinput{|\meta{file}|}|. Don't use
% |\input| for this purpose, this command
% should be used only for calling the \ds{} program as explained
% above and is ignored when used for any other purpose.
%
% \DescribeMacro{\ifToplevel}
% When batch files are nested you may want to suppress certain
% commands in the lower-level batch files such as terminal
% messages. For this purpose you can use the |\ifToplevel| command
% which executes its argument only if the current batch file is the
% outermost one. Make sure that you put the opening brace of the
% argument into the same line as the command itself, otherwise the
% \ds{} program will get confused.
%
% \DescribeMacro{\showprogress}
% \DescribeMacro{\keepsilent}
% When the option \texttt{stats} is included in \ds{} it can
% write message to the terminal as each line of the input file(s) is
% processed. This message consists of a single character, indicating
% kind of that particular line. We use the
% following characters:
% \begin{itemize}
% \item[\texttt{\%}] Whenever an input line is a comment
% \texttt{\%}-character is written to the terminal.
% \item[\texttt{.}] Whenever a code line is encountered
% a \texttt{.}-character is written on the terminal.
% \item[\texttt{/}] When a number of empty lines appear in a row in the
% input file, at most one of them is retained. The \ds{}
% program signals the removal of an empty line with the
% \texttt{/}-character.
% \item[\texttt{<}] When a `guard line' is found in the input and it
% starts a block of optionally included code, this is signalled
% on the terminal by showing the \texttt{<}-character, together
% with the boolean expression of the guard.
% \item[\texttt{>}] The end of a conditionally included block of code is
% indicated by showing the \texttt{>}-character.
% \end{itemize}
% This feature is turned on by default when the option
% \texttt{stats} is included, otherwise it is turned off. The
% feature can be toggled with the commands |\showprogress| and
% |\keepsilent|.
%
%
% \subsubsection{Supporting old interface}
%
% \DescribeMacro{\generateFile}
% Here is the old syntax for specifying what files are to be
% generated. It allows specification of just one output file.
% \begin{quote}
% |\generateFile{|\meta{output}|}{|\meta{ask}|}{|[|\from{|^^A
% \meta{input}|}{|\meta{optionlist}|}|]*|}|
% \end{quote}
% The meaning of \meta{output}, \meta{input} and
% \meta{optionslist} is just as for |\generate|. With
% \meta{ask} you can instruct \TeX\ to either silently overwrite a
% previously existing file (|f|) or to issue a warning and ask you
% if it should overwrite the existing file (|t|) (it overrides the
% |\askforoverwrite| setting).
%
% \DescribeMacro{\include}
% \DescribeMacro{\processFile}
% The earlier version of the \ds{} program supported a
% different kind of command to tell \TeX\ what to do. This command
% is less powerful than |\generateFile|; it can be used when
% \meta{output} is created from one \meta{input}. The syntax is:
% \begin{quote}
% |\include{|\meta{optionlist}|}|
%
% |\processFile{|\meta{name}|}{|\meta{inext}^^A
% |}{|\meta{outext}^^A
% |}{|\meta{ask}|}|
% \end{quote}
% This command is based on environments where filenames are
% constructed of two parts, the name and the extension, separated
% with a dot. The syntax of this command assumes that the
% \meta{input} and \meta{output} share the same name and only
% differ in their extension. This command is retained to be
% backwards compatible with the older version of \ds{}, but its use
% is not encouraged.
%
% \section{Conditional inclusion of code}
%
% When you use the \ds{} program to strip comments out of
% \TeX\ macro files you have the possibility to make more than one
% stripped macro file from one documented file. This is achieved by
% the support for optional code. The optional code is marked
% in the documented file with a `guard'.
%
% A guard is a boolean expression that is enclosed in |<| and |>|.
% It also {\em has\/} to follow the |%| at the beginning of the line.
% For example:
%\begin{verbatim}
% ...
% %<bool>\TeX code
% ...
%\end{verbatim}
% In this example the line of code will be included in \meta{output}
% if the option \texttt{bool} is present in the \meta{optionlist} of
% the |\generateFile| command.
%
% The syntax for the boolean expressions is:
%
%\DeleteShortVerb\|
% \begin{tabular}{lcl}
% \meta{Expression} & $::=$ & \meta{Secondary}
% [\{\texttt{|}, \texttt{,}\}
% \meta{Secondary}]*\\
% \meta{Secondary} & $::=$ &
% \meta{Primary} [\texttt{\&}
% \meta{Primary}]*\\
% \meta{Primary} & $::=$ &
% \meta{Terminal} $|$ \texttt{!}\meta{Primary}
% $|$ \texttt{(}\meta{Expression}\texttt{)}\\
% \end{tabular}
%
% The \texttt{|} stands for disjunction, the \texttt{\&} stands for
% conjunction and the \texttt{!}\ stands for negation. The
% \meta{Terminal} is any sequence of letters and evaluates to
% \meta{true} iff\footnote{iff stands for `if and only if'} it
% occurs in the list of options that have to be included.
%\MakeShortVerb\|
%
% Two kinds of optional code are supported: one can either have
% optional code that `fits' on one line of text, like the example
% above, or one can have blocks of optional code.
%
% To distinguish both kinds of optional code the `guard modifier'
% has been introduced. The `guard modifier' is one character that
% immediately follows the |<| of the guard. It can be either |*|
% for the beginning of a block of code, or |/| for the end of a
% block of code\footnote{To be compatible with the earlier version
% of \ds{} also \texttt{+} and \texttt{-} are supported as `guard
% modifiers'. However, there is an incompatibility with the
% earlier version since a line with a \texttt{+}-modified guard is
% not included inside a block with a guard that evaluates to false,
% in contrast to the previous behaviour.}. The beginning and
% ending guards for a block of code have to be on a line by
% themselves.
%
% When a block of code is {\em not\/} included, any guards that occur
% within that block are {\em not\/} evaluated.
%
% \section{Internal functions and variables}
%
% An important consideration for \LaTeX\ development is separating
% out public and internal functions. Functions and variables which
% are private to one module should not be used or modified by any
% other module. As \TeX{} does not have any formal namespacing
% system, this requires a convention for indicating which functions
% in a code-level module are public and which are private.
%
% Using \ds\ allows internal functions to be indicated
% using a `two part' system. Within the \texttt{.dtx} file,
% internal functions may be indicated using |@@| in place of the
% module name, for example
% \begin{verbatim}
% \cs_new_protected:Npn \@@_some_function:nn #1#2
% {
% % Some code here
% }
% \tl_new:N \l_@@_internal_tl
% \end{verbatim}
%
% To extract the code using \ds, the original `guard'
% mechanism is extended by the introduction of the syntax
% \texttt{\%<@@=\meta{module}>}. The \meta{module} name then
% replaces the |@@| when the code is extracted, so that
% \begin{verbatim}
% %<*package>
% %<@@=foo>
% \cs_new_protected:Npn \@@_some_function:nn #1#2
% {
% % Some code here
% }
% \tl_new:N \l_@@_internal_tl
% %</package>
% \end{verbatim}
% is extracted as
% \begin{verbatim}
% \cs_new_protected:Npn \__foo_some_function:nn #1#2
% {
% % Some code here
% }
% \tl_new:N \l__foo_internal_tl
% \end{verbatim}
% where the |__| indicates that the functions and variables are
% internal to the \texttt{foo} module.
%
% Use |@@@@| to obtain |@@| in the output (|@@@@@| to get |@@@|).
% For longer pieces of code the replacement can be completely
% suppressed by giving an empty module name, namely using the
% syntax \texttt{\%<@@=>}.
%
% \section{Those other languages}
% Since \TeX\ is an open system some of \TeX\ packages include
% non-\TeX\ files. Some authors use \ds\ to generate PostScript
% headers, shell scripts or programs in other languages. For them
% the comments-stripping activity of \ds\ may cause some
% trouble. This section describes how to produce non-\TeX\ files
% with \ds\ effectively.
%
% \subsection{Stuff \ds\ puts in every file}
% First problem when producing files in ``other'' languages is that
% \ds\ adds some bits to the beginning and end of every generated
% file that may not fit with the syntax of the language in
% question. So we'll study carefully what exactly goes where.
%
% The whole text put on beginning of file is kept in a macro defined
% by |\declarepreamble|. Every line of input presented to
% |\declarepreamble| is prepended with current value of
% |\MetaPrefix|. Standard \ds\ header is inserted before your text,
% and macros |\inFileName|, |\outFileName| and |\ReferenceLines|
% are used as placeholders for information which will be filled in
% later (specifically for each output file). Don't try to redefine
% these macros. After
%\begin{verbatim}
% \declarepreamble\foo
% ____________________________
% Package FOO for use with TeX
% \endpreamble
%\end{verbatim}
% macro |\foo| is defined as
%\begin{verbatim}
% %%^^J
% %% This is file `\outFileName ',^^J
% %% generated with the docstrip utility.^^J
% \ReferenceLines^^J
% %% ____________________________^^J
% %% Package FOO for use with TeX.
%\end{verbatim}
% You can play with it freely or even define it from scratch. To
% embed the preamble in Adobe structured comments just use |\edef|:
%\begin{verbatim}
% \edef\foo{\perCent!PS-Adobe-3.0^^J%
% \DoubleperCent\space Title: \outFileName^^J%
% \foo^^J%
% \DoubleperCent\space EndComments}
%\end{verbatim}
% After that use |\usepreamble\foo| to select your new preamble.
% Everything above works as well for postambles.
%
% You may also prevent \ds\ from adding anything to your file, and
% put any language specific invocations directly in your code:
%\begin{verbatim}
% \generate{\usepreamble\empty
% \usepostamble\empty
% \file{foo.ps}{\from{mypackage.dtx}{ps}}}
%\end{verbatim}
% or alternatively |\nopreamble| and |\nopostamble|.
%
% \subsection{Meta comments}
% You can change the prefix used for putting meta comments to
% output files by redefining |\MetaPrefix|. Its default value is
% |\DoubleperCent|. The preamble uses value of |\MetaPrefix|
% current at time of |\declarepreamble| while meta comments in the
% source file use value current at time of |\generate|. Note that
% this means that you cannot produce concurrently two files using
% different |\MetaPrefix|es.
%
% \subsection{Verbatim mode}
% If your programming language uses some construct that can
% interfere badly with \ds\ (e.g., percent in column one) you may
% need a way for preventing it from being stripped off. For that
% purpose \ds\ features `verbatim mode'.
%
% A `Guard expression' of the form |%<<|\meta{END-TAG} marks
% the start of a section that will be copied verbatim upto a line
% containing only a percent in column 1 followed by \meta{END-TAG}.
% You can select any \meta{END-TAG} you want, but note that spaces
% count here. Example:
%\begin{verbatim}
% %<*myblock>
% some stupid()
% #computer<program>
% %<<COMMENT
% % These two lines are copied verbatim (including percents
% %% even if \MetaPrefix is something different than %%).
% %COMMENT
% using*strange@programming<language>
% %</myblock>
%\end{verbatim}
% And the output is (when stripped with \texttt{myblock} defined):
%\begin{verbatim}
% some stupid()
% #computer<program>
% % These two lines are copied verbatim (including percents
% %% even if \MetaPrefix is something different than %%).
% using*strange@programming<language>
%\end{verbatim}
%
%\StopEventually{%
%^^A \section{Conclusion}
% \PrintIndex
% \PrintChanges
%^^A \makesignature
% }
%
% \section{Producing the documentation}
%
% We provide a short driver file that can be extracted by the
% \ds{} program using the conditional `\textsf{driver}'. To
% allow the use of \texttt{docstrip.dtx} as a program at Ini\TeX{}
% time (e.g., to strip
% off its own comments) we need to add a bit of primitive code.
% With this extra checking it is still possible to process this
% file with \LaTeXe{} to typeset the documentation.
% \changes{2.1b}{1993/02/23}{Added fontdefinitions for doc to the driver
% file, in order to get the layout of the code
% right; also added the layout definitions
% that are in effect in \texttt{doc.drv}}
% \changes{2.1c}{1993/02/23}{Remove definitions for fonts again}
% \changes{2.2f}{1994/02/26}{Allow direct processing of source}
% \begin{macrocode}
%<*driver>
% \end{macrocode}
% If |\documentclass| is undefined, e.g., if Ini\TeX{} or plain
% \TeX{} is used for formatting, we bypass the driver file.
%
% \changes{2.3a}{1995/08/20}{Changed driver}
% We use some trickery to avoid issuing |\end{document}| when
% the |\ifx| construction is unfinished. If condition below is
% true a |\fi| is constructed on the fly, the |\ifx| is completed,
% and the real |\fi| will never be seen as it comes after
% |\end{document}|. On the other hand if condition is false
% \TeX\ skips over |\csname fi\endcsname| having no idea that
% this could stand for |\fi|, driver is skipped and only then
% the condition completed.
%
% Additional guard |gobble| prevents \ds\ from extracting
% these tricks to real driver file.
% \begin{macrocode}
%<*gobble>
\ifx\jobname\relax\let\documentclass\undefined\fi
\ifx\documentclass\undefined
\else \csname fi\endcsname
%</gobble>
% \end{macrocode}
% Otherwise we process the following lines which will result in
% formatting the documentation.
% \begin{macrocode}
\documentclass{ltxdoc}
\EnableCrossrefs
% \DisableCrossrefs
% use \DisableCrossrefs if the
% index is ready
\RecordChanges
% \OnlyDescription
\typeout{Expect some Under- and overfull boxes}
\begin{document}
\DocInput{docstrip.dtx}
\end{document}
%<*gobble>
\fi