/
l3doc.dtx
4453 lines (4440 loc) · 141 KB
/
l3doc.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
%
%% File: l3doc.dtx Copyright (C) 1990-2018 The LaTeX3 project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version. The latest version
% of this license is in the file
%
% https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
% https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
\expandafter\begingroup
\fi
\input l3docstrip.tex
\askforoverwritefalse
\preamble
Copyright (C) 1990-2017 The LaTeX3 Project
It may be distributed and/or modified under the conditions of
the LaTeX Project Public License (LPPL), either version 1.3c of
this license or (at your option) any later version. The latest
version of this license is in the file:
https://www.latex-project.org/lppl.txt
This file is part of the "l3kernel bundle" (The Work in LPPL)
and all files in that bundle must be distributed together.
\endpreamble
% stop docstrip adding \endinput
\postamble
\endpostamble
\generate{\file{l3doc.cls}{\from{l3doc.dtx}{class,cfg}}}
%\generate{\file{l3doc.ist}{\from{l3doc.dtx}{docist}}}
\ifx\fmtname\nameofplainTeX
\expandafter\endbatchfile
\else
\expandafter\endgroup
\fi
%</driver>
%
%<*driver|class>
\RequirePackage{expl3,xparse,calc}
%</driver|class>
%
%<*driver>
\ProvidesFile{l3doc.dtx}[2017/03/18 L3 Experimental documentation class]
\documentclass{l3doc}
\usepackage{framed,lipsum}
\begin{document}
\DocInput{l3doc.dtx}
\end{document}
%</driver>
%
% This isn't included in the typeset documentation because it's a bit
% ugly:
%<*class>
\ProvidesExplClass{l3doc}{2018-04-30}{}
{L3 Experimental documentation class}
%</class>
% \fi
%
% \title{The \cls{l3doc} class}
% \author{\Team}
% \date{Released 2018-10-17}
% \maketitle
% \tableofcontents
%
% \begin{documentation}
%
%
% \section{Introduction}
%
% This is an ad-hoc class for documenting the \pkg{expl3} bundle, a
% collection of modules or packages that make up \LaTeX3's programming
% environment. Eventually it will replace the \cls{ltxdoc} class for
% \LaTeX3, but not before the good ideas in \pkg{hypdoc}, \cls{xdoc2},
% \pkg{docmfp}, and \cls{gmdoc} are incorporated.
%
% \textbf{It is much less stable than the main \pkg{expl3} packages.
% Use at own risk!}
%
% It is written as a \enquote{self-contained} docstrip file: executing
% |latex l3doc.dtx| generates the \file{l3doc.cls} file and typesets
% this documentation; execute |tex l3doc.dtx| to only generate
% \file{l3doc.cls}.
%
% \section{Features of other packages}
%
% This class builds on the \pkg{ltxdoc} class and the \pkg{doc} package,
% but in the time since they were originally written some improvements
% and replacements have appeared that we would like to use as
% inspiration.
%
% These packages or classes are \pkg{hypdoc}, \pkg{docmfp}, \pkg{gmdoc},
% and \pkg{xdoc}. I have summarised them below in order to work out
% what sort of features we should aim at a minimum for \pkg{l3doc}.
%
% \subsection{The \pkg{hypdoc} package}
%
% This package provides hyperlink support for the \pkg{doc} package. I
% have included it in this list to remind me that cross-referencing
% between documentation and implementation of methods is not very
% good. (\emph{E.g.}, it would be nice to be able to automatically
% hyperlink the documentation for a function from its implementation and
% vice-versa.)
%
% \subsection{The \pkg{docmfp} package}
%
% \begin{itemize}
% \item Provides \cs{DescribeRoutine} and the \env{routine}
% environment (\emph{etc.}) for MetaFont and MetaPost code.
% \item Provides \cs{DescribeVariable} and the \env{variable}
% environment (\emph{etc.}) for more general code.
% \item Provides \cs{Describe} and the \env{Code} environment
% (\emph{etc.}) as a generalisation of the above two
% instantiations.
% \item Small tweaks to the DocStrip system to aid non-\LaTeX{} use.
% \end{itemize}
%
% \subsection{The \pkg{xdoc2} package}
%
% \begin{itemize}
% \item Two-sided printing.
% \item \cs{NewMacroEnvironment}, \cs{NewDescribeEnvironment}; similar
% idea to \pkg{docmfp} but more comprehensive.
% \item Tons of small improvements.
% \end{itemize}
%
% \subsection{The \pkg{gmdoc} package}
%
% Radical re-implementation of \pkg{doc} as a package or class.
% \begin{itemize}
% \item Requires no |\begin{macrocode}| blocks!
% \item Automatically inserts |\begin{macro}| blocks!
% \item And a whole bunch of other little things.
% \end{itemize}
%
% \section{Problems \& Todo}
%
% Problems at the moment:
% (1)~not flexible in the types of things that can be documented;
% (2)~no obvious link between the |\begin{function}| environment for
% documenting things to the |\begin{macro}| function that's used
% analogously in the implementation.
%
% The \env{macro} should probably be renamed to \env{function} when it
% is used within an implementation section. But they should have the
% same syntax before that happens!
%
% Furthermore, we need another \enquote{layer} of documentation commands
% to account for \enquote{user-macro} as opposed to
% \enquote{code-functions}; the \pkg{expl3} functions should be
% documented differently, probably, to the \pkg{xparse} user macros (at
% least in terms of indexing).
%
% In no particular order, a list of things to do:
% \begin{itemize}
% \item Rename \env{function}/\env{macro} environments to better
% describe their use.
% \item Generalise \env{function}/\env{macro} for documenting
% \enquote{other things}, such as environment names, package
% options, even keyval options.
% \item New function like \tn{part} but for files (remove awkward
% \enquote{File} as \tn{partname}).
% \item Something better to replace \cs{StopEventually}; I'm thinking
% two environments \env{documentation} and \env{implementation} that
% can conditionally typeset/ignore their material. (This has been
% implemented but needs further consideration.)
% \item Hyperlink documentation and implementation of macros (see the
% \textsc{dtx} file of \pkg{svn-multi} v2 as an example). This is
% partially done, now, but should be improved.
% \end{itemize}
%
% \section{Documentation}
%
% \subsection{Configuration}
%
% Before class options are processed, \pkg{l3doc} loads a configuration
% file \file{l3doc.cfg} if it exists, allowing you to customise the
% behaviour of the class without having to change the documentation
% source files.
%
% For example, to produce documentation on letter-sized paper instead of
% the default A4 size, create \file{l3doc.cfg} and include the line
% \begin{verbatim}
% \PassOptionsToClass{letterpaper}{l3doc}
% \end{verbatim}
%
% By default, \pkg{l3doc} selects the |T1| font encoding and loads the
% Latin Modern fonts. To prevent this, use the class option
% |cm-default|.
%
% \subsection{Partitioning documentation and implementation}
%
% \pkg{doc} uses the \cs{OnlyDocumentation}/\cs{AlsoImplementation}
% macros to guide the use of \cs{StopEventually}|{}|, which is intended
% to be placed to partition the documentation and implementation within
% a single \file{.dtx} file.
%
% This isn't very flexible, since it assumes that we \emph{always} want
% to print the documentation. For the \pkg{expl3} sources, I wanted to
% be be able to input \file{.dtx} files in two modes: only displaying
% the documentation, and only displaying the implementation. For
% example:
% \begin{verbatim}
% \DisableImplementation
% \DocInput{l3basics,l3prg,...}
% \EnableImplementation
% \DisableDocumentation
% \DocInputAgain
% \end{verbatim}
%
% The idea being that the entire \pkg{expl3} bundle can be documented,
% with the implementation included at the back. Now, this isn't
% perfect, but it's a start.
%
% Use |\begin{documentation}...\end{documentation}| around the
% documentation, and |\begin{implementation}...\end{implementation}|
% around the implementation. The
% \cs{EnableDocumentation}/\cs{EnableImplementation} causes them to
% be typeset when the \file{.dtx} file is \cs{DocInput}; use
% \cs{DisableDocumentation}/\cs{DisableImplementation} to omit the
% contents of those environments.
%
% Note that \cs{DocInput} now takes comma-separated arguments, and
% \cs{DocInputAgain} can be used to re-input all \file{.dtx} files
% previously input in this way.
%
% \subsection{General text markup}
%
% Many of the commands in this section come from \pkg{ltxdoc} with some
% improvements.
%
% \begin{function}{\cmd, \cs}
% \begin{syntax}
% \cmd{\cmd} \oarg{options} \meta{control sequence}\\
% \cs{cs} \oarg{options} \marg{csname}
% \end{syntax}
% These commands are provided to typeset control sequences.
% |\cmd\foo| produces \enquote{\cmd\foo} and |\cs{foo}| produces the
% same. In general, \cs{cs} is more robust since
% it doesn't rely on catcodes being \enquote{correct} and is therefore
% recommended.
%
% These commands are aware of the |@@| \pkg{l3docstrip} syntax and
% replace such instances correctly in the typeset documentation.
% This only happens after a |%<@@=|\meta{module}|>| declaration.
%
% Additionally, commands can be used in the argument of \cs{cs}. For
% instance, |\cs{\meta{name}:\meta{signature}}| produces
% \cs{\meta{name}:\meta{signature}}.
%
% The \meta{options} are a key--value list which can contain the
% following keys:
% \begin{itemize}
% \item |index=|\meta{name}: the \meta{csname} is indexed as if
% one had written \cs{cs}\Arg{name}.
% \item |no-index|: the \meta{csname} is not indexed.
% \item |module=|\meta{module}: the \meta{csname} is indexed in
% the list of commands from the \meta{module}; the \meta{module}
% can in particular be |TeX| for \enquote{\TeX{} and \LaTeXe{}}
% commands, or empty for commands which should be placed in the
% main index. By default, the \meta{module} is deduced
% automatically from the command name.
% \item |replace| is a boolean key (\texttt{true} by default) which
% indicates whether to replace |@@| as \pkg{l3docstrip} does.
% \end{itemize}
% These commands allow hyphenation of control sequences after (most) underscores.
% By default, a hyphen is used to mark the hyphenation, but this can be changed with
% the \texttt{cs-break-nohyphen} class option.
% To disable hyphenation of control sequencies entirely, use \texttt{cs-break-off}.
% \end{function}
%
%
% \begin{function}{\tn}
% \begin{syntax}
% \cs{tn} \oarg{options} \marg{csname}
% \end{syntax}
% Analoguous to \cs{cs} but intended for \enquote{traditional} \TeX{}
% or \LaTeXe{} commands; they are indexed accordingly. This is in
% fact equivalent to \cs{cs} |[module=TeX, replace=false,|
% \meta{options}|]| \Arg{csname}.
% \end{function}
%
% \begin{function}{\meta}
% \begin{syntax}
% \cs{meta} \Arg{name}
% \end{syntax}
% \cs{meta} typesets the \meta{name} italicised in \meta{angle
% brackets}. Within a \env{function} environment or similar, angle
% brackets |<...>| are set up to be a shorthand for |\meta{...}|.
%
% This function has additional functionality over its \pkg{ltxdoc}
% versions; underscores can be used to subscript material as in math
% mode. For example, |\meta{arg_{xy}}| produces
% \enquote{\meta{arg_{xy}}}.
% \end{function}
%
% \begin{function}{\Arg, \marg, \oarg, \parg}
% \begin{syntax}
% |\Arg| \Arg{name}
% \end{syntax}
% Typesets the \meta{name} as for \cs{meta} and wraps it in braces.
%
% The \cs{marg}/\cs{oarg}/\cs{parg} versions follow from \pkg{ltxdoc}
% in being used for \enquote{mandatory} or \enquote{optional} or
% \enquote{picture} brackets as per \LaTeXe{} syntax.
% \end{function}
%
% \begin{function}{\file, \env, \pkg, \cls}
% \begin{syntax}
% \cs{pkg} \Arg{name}
% \end{syntax}
% These all take one argument and are intended to be used as semantic
% commands for representing files, environments, package names, and
% class names, respectively.
% \end{function}
%
% \subsection{Describing functions in the documentation}
%
% \DescribeEnv{function}
% \DescribeEnv{syntax}
% Two heavily-used environments are defined to describe the syntax of
% \pkg{expl3} functions and variables.
% \begin{framed}
% \vspace{-\baselineskip}
% \begin{verbatim}
% \begin{function}{\function_one:, \function_two:}
% \begin{syntax}
% |\foo_bar:| \Arg{meta} \meta{test_1}
% \end{syntax}
% \meta{description}
% \end{function}
% \end{verbatim}
% \hrulefill
% \par
% \hspace*{0.25\textwidth}
% \begin{minipage}{0.5\textwidth}
% \begin{function}{\function_one:, \function_two:}
% \begin{syntax}
% |\foo_bar:| \Arg{meta} \meta{test_1}
% \end{syntax}
% \meta{description}
% \end{function}
% \end{minipage}
% \end{framed}
%
% Function environments take an optional argument to indicate whether
% the function(s) it describes are expandable or restricted-expandable
% or defined in conditional forms. Use |EXP|, |rEXP|, |TF|, |pTF|, or |noTF| for
% this; note that |pTF| implies |EXP| since predicates must always be
% expandable, and that |noTF| means that the function without |TF|
% should be documented in addition to |TF|. As an example:
% \begin{framed}
% \vspace{-\baselineskip}
% \begin{verbatim}
% \begin{function}[pTF]{\cs_if_exist:N}
% \begin{syntax}
% \cs{cs_if_exist_p:N} \meta{cs}
% \end{syntax}
% \meta{description}
% \end{function}
% \end{verbatim}
% \hrulefill
% \par
% \hspace*{0.25\textwidth}
% \begin{minipage}{0.5\textwidth}
% \begin{function}[pTF]{\cs_if_exist:N}
% \begin{syntax}
% \cs{cs_if_exist_p:N} \meta{cs}
% \end{syntax}
% \meta{description}
% \end{function}
% \end{minipage}
% \end{framed}
%
% \DescribeEnv{variable}
% If you are documenting a variable instead of a function, use the
% \env{variable} environment instead; it behaves identically to the
% \env{function} environment above.
%
% \DescribeEnv{texnote}
% This environment is used to call out sections within \env{function}
% and similar that are only of interest to seasoned \TeX{} developers.
%
% \subsection{Describing functions in the implementation}
%
% \DescribeEnv{macro}
% The well-used environment from \LaTeXe{} for marking up the
% implementation of macros/functions remains the \env{macro}
% environment. Some changes in \pkg{l3doc}: it now accepts
% comma-separated lists of functions, to avoid a very large number of
% consecutive |\end{macro}| statements.
% Spaces and new lines are ignored (the option |[verb]| prevents this).
% \begin{verbatim}
% % \begin{macro}{\foo:N, \foo:c}
% % \begin{macrocode}
% ... code for \foo:N and \foo:c ...
% % \end{macrocode}
% % \end{macro}
% \end{verbatim}
% If you are documenting an auxiliary macro, it's generally not
% necessary to highlight it as much and you also don't need to check it
% for, say, having a test function and having a documentation chunk
% earlier in a \env{function} environment. \pkg{l3doc} will pick up these
% cases form the presence of |__| in the name, or you may force marking
% as internal by using |\begin{macro}[int]| to mark it as such. The margin
% call-out is then printed in grey for such cases.
%
% For documenting \pkg{expl3}-type conditionals, you may also pass this
% environment a |TF| option (and omit it from the function name) to
% denote that the function is provided with |T|, |F|, and |TF| suffixes.
% A similar |pTF| option prints both |TF| and |_p| predicate forms.
% An option |noTF| prints both the |TF| forms and a form with neither
% |T| nor |F|, to document functions such as \cs[no-index]{prop_get:NN}
% which also have conditional forms (\cs[no-index]{prop_get:NNTF}).
%
%
% \DescribeMacro{\TestFiles}
% \cs{TestFiles}\marg{list of files} is used to indicate which test
% files are used for the current code; they are printed in the
% documentation.
%
% \DescribeMacro{\UnitTested}
% Within a \env{macro} environment, it is a good idea to mark whether a
% unit test has been created for the commands it defines. This is
% indicated by writing \cs{UnitTested} anywhere within |\begin{macro}|
% \dots |\end{macro}|.
%
% If the class option |checktest| is enabled, then it is an \emph{error}
% to have a \env{macro} environment without a call to
% \file{Testfiles}. This is intended for large packages such as
% \pkg{expl3} that should have absolutely comprehensive tests suites and
% whose authors may not always be as sharp at adding new tests with new
% code as they should be.
%
% \DescribeMacro{\TestMissing}
% If a function is missing a test, this may be flagged by writing (as
% many times as needed) \cs{TestMissing} \marg{explanation of test
% required}. These missing tests are summarised in the listing
% printed at the end of the compilation run.
%
% \DescribeEnv{variable}
% When documenting variable definitions, use the \env{variable}
% environment instead. Here it behaves identically to the
% \env{macro} environment, except that if the class option |checktest|
% is enabled, variables are not required to have a test file.
%
% \DescribeEnv{arguments}
% Within a \env{macro} environment, you may use the \env{arguments}
% environment to describe the arguments taken by the function(s). It
% behaves like a modified enumerate environment.
% \begin{verbatim}
% % \begin{macro}{\foo:nn, \foo:VV}
% % \begin{arguments}
% % \item Name of froozle to be frazzled
% % \item Name of muble to be jubled
% % \end{arguments}
% % \begin{macrocode}
% ... code for \foo:nn and \foo:VV ...
% % \end{macrocode}
% % \end{macro}
% \end{verbatim}
%
%
% \subsection{Keeping things consistent}
%
% Whenever a function is either documented or defined with
% \env{function} and \env{macro} respectively, its name is stored in a
% sequence for later processing.
%
% At the end of the document (\emph{i.e.}, after the \file{.dtx} file
% has finished processing), the list of names is analysed to check
% whether all defined functions have been documented and vice versa. The
% results are printed in the console output.
%
% If you need to do more serious work with these lists of names, take a
% look at the implementation for the data structures and methods used to
% store and access them directly.
%
% \subsection{Documenting templates}
%
% The following macros are provided for documenting templates; might end
% up being something completely different but who knows.
% \begin{quote}\parskip=0pt\obeylines
% |\begin{TemplateInterfaceDescription}| \Arg{template type name}
% | \TemplateArgument{none}{---}|
% \textsc{or one or more of these:}
% | \TemplateArgument| \Arg{arg no} \Arg{meaning}
% \textsc{and}
% |\TemplateSemantics|
% | | \meta{text describing the template type semantics}
% |\end{TemplateInterfaceDescription}|
% \end{quote}
%
% \begin{quote}\parskip=0pt\obeylines
% |\begin{TemplateDescription}| \Arg{template type name} \Arg{name}
% \textsc{one or more of these:}
% | \TemplateKey| \marg{key name} \marg{type of key}
% | |\marg{textual description of meaning}
% | |\marg{default value if any}
% \textsc{and}
% |\TemplateSemantics|
% | | \meta{text describing special additional semantics of the template}
% |\end{TemplateDescription}|
% \end{quote}
%
% \begin{quote}\parskip=0pt\obeylines
% |\begin{InstanceDescription}| \oarg{text to specify key column width (optional)}
% \hfill\marg{template type name}\marg{instance name}\marg{template name}
% \textsc{one or more of these:}
% | \InstanceKey| \marg{key name} \marg{value}
% \textsc{and}
% |\InstanceSemantics|
% | | \meta{text describing the result of this instance}
% |\end{InstanceDescription}|
% \end{quote}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3doc} implementation}
%
% \begin{macrocode}
%<*class>
% \end{macrocode}
%
% \begin{macrocode}
%<@@=codedoc>
% \end{macrocode}
%
% \subsection{Variables}
%
% \begin{variable}{\g_docinput_clist}
% The list of files which have been input through \cs{DocInput}.
% \begin{macrocode}
\clist_new:N \g_docinput_clist
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_doc_functions_seq, \g_doc_macros_seq}
% All functions documented through \env{function}, and all macros
% introduced through \env{macro}. They can be compared to see what
% documentation or code is missing.
% \begin{macrocode}
\seq_new:N \g_doc_functions_seq
\seq_new:N \g_doc_macros_seq
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_detect_internals_bool, \l_@@_detect_internals_tl}
% If \texttt{true}, \pkg{l3doc} will check for use of internal
% commands \cs[no-index]{__\meta{pkg}_\ldots{}} from other packages in
% the argument of the \texttt{macro} environment, and in the code typeset in
% \texttt{macrocode} environments, but not in~\cs{cs}. Also a token list
% to store temporary data for this purpose.
% \begin{macrocode}
\bool_new:N \l_@@_detect_internals_bool
\bool_set_true:N \l_@@_detect_internals_bool
\tl_new:N \l_@@_detect_internals_tl
\tl_new:N \l_@@_detect_internals_cs_tl
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_output_coffin}
% The \env{function} environment is typeset by combining coffins
% containing various pieces (function names, description, \emph{etc.})
% into this coffin.
% \begin{macrocode}
\coffin_new:N \l_@@_output_coffin
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {\l_@@_functions_coffin, \l_@@_descr_coffin, \l_@@_syntax_coffin}
% These coffins contain respectively the list of function names
% (argument of the \env{function} environment), the text between
% |\begin{function}| and |\end{function}|, and the syntax given in the
% \env{syntax} environment.
% \begin{macrocode}
\coffin_new:N \l_@@_functions_coffin
\coffin_new:N \l_@@_descr_coffin
\coffin_new:N \l_@@_syntax_coffin
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_syntax_box}
% The contents of the \env{syntax} environment are typeset in this box
% before being transferred to \cs{l_@@_syntax_coffin}.
% \begin{macrocode}
\box_new:N \g_@@_syntax_box
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_in_function_bool}
% True when inside a \texttt{function} or \texttt{variable}
% environment. Used by the \texttt{syntax} environment to determine
% its behaviour.
% \begin{macrocode}
\bool_new:N \l_@@_in_function_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_long_name_bool, \l_@@_trial_width_dim}
% The boolean \cs{l_@@_long_name_bool} is \texttt{true} if the width
% \cs{l_@@_trial_width_dim} of the coffin \cs{l_@@_functions_coffin}
% (containing the current function names) is bigger than the space
% available in the margin.
% \begin{macrocode}
\bool_new:N \l_@@_long_name_bool
\dim_new:N \l_@@_trial_width_dim
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_nested_macro_int}
% The nesting of \env{macro} environments (this is now~$0$ outside a
% \env{macro} environment).
% \begin{macrocode}
\int_new:N \l_@@_nested_macro_int
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {
% \l_@@_macro_tested_bool,
% \g_@@_missing_tests_prop,
% \g_@@_not_tested_seq,
% \g_@@_testfiles_seq,
% }
% A boolean describing whether the current macro has tests, and some
% global structures which contain information about test files and
% which tests are missing.
% \begin{macrocode}
\bool_new:N \l_@@_macro_tested_bool
\prop_new:N \g_@@_missing_tests_prop
\seq_new:N \g_@@_not_tested_seq
\seq_new:N \g_@@_testfiles_seq
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {
% \l_@@_macro_internal_set_bool,
% \l_@@_macro_internal_bool,
% \l_@@_macro_TF_bool,
% \l_@@_macro_pTF_bool,
% \l_@@_macro_noTF_bool,
% \l_@@_macro_EXP_bool,
% \l_@@_macro_rEXP_bool,
% \l_@@_macro_var_bool,
% \l_@@_override_module_tl,
% \l_@@_macro_documented_tl,
% }
% Contain information about some options of function/macro
% environments. We initialize \cs{l_@@_override_module_tl} to avoid
% overriding module names by an empty name (meaning no module).
% \begin{macrocode}
\bool_new:N \l_@@_macro_internal_set_bool
\bool_new:N \l_@@_macro_internal_bool
\bool_new:N \l_@@_macro_TF_bool
\bool_new:N \l_@@_macro_pTF_bool
\bool_new:N \l_@@_macro_noTF_bool
\bool_new:N \l_@@_macro_EXP_bool
\bool_new:N \l_@@_macro_rEXP_bool
\bool_new:N \l_@@_macro_var_bool
\tl_new:N \l_@@_override_module_tl
\tl_set:Nn \l_@@_override_module_tl { \q_no_value }
\tl_new:N \l_@@_macro_documented_tl
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {
% \g_@@_lmodern_bool,
% \g_@@_checkfunc_bool,
% \g_@@_checktest_bool,
% \g_@@_cs_break_bool,
% \g_@@_kernel_bool
% }
% Information about package options.
% \begin{macrocode}
\bool_new:N \g_@@_lmodern_bool
\bool_new:N \g_@@_checkfunc_bool
\bool_new:N \g_@@_checktest_bool
\bool_new:N \g_@@_kernel_bool
\bool_new:N \g_@@_cs_break_bool
\bool_gset_true:N \g_@@_cs_break_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_tmpa_tl, \l_@@_tmpb_tl, \l_@@_tmpa_int, \l_@@_tmpa_seq}
% Some temporary variables.
% \begin{macrocode}
\tl_new:N \l_@@_tmpa_tl
\tl_new:N \l_@@_tmpb_tl
\int_new:N \l_@@_tmpa_int
\int_new:N \l_@@_tmpa_seq
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_names_block_tl}
% List of local sequence variables (produced through
% \cs{@@_lseq_name:n}), one for each set of variants in a
% \env{function} or \env{macro} environment. More precisely these
% sequences are named after the base forms, such as \cs{clist_count:n}
% or \cs{clist_count:N} (which are not variants). Each of these
% sequences have the base name (without any signature) as their first
% item, followed by the list of variant's signatures, or
% \cs{scan_stop:} to denote the absence of signature (no colon).
% \begin{macrocode}
\tl_new:N \l_@@_names_block_tl
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_variants_seq}
% Stores rather temporarily the list of variants (signatures only) of
% a function/macro that is being documented. It is global because we
% need it to keep its value throughout cells of an alignment.
% \begin{macrocode}
\seq_new:N \g_@@_variants_seq
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_names_verb_bool}
% Set to |true| if the main argument of a macro/function environment
% should be used as is, without removing any comma or space.
% \begin{macrocode}
\bool_new:N \l_@@_names_verb_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_names_seq}
% List of functions/environments/\ldots{} appearing as arguments of a
% given \env{function} or \env{macro} environment. These are the
% names after conversion of |_@@| and |@@| to |__|\meta{module name}
% and other sanitizing.
% \begin{macrocode}
\seq_new:N \l_@@_names_seq
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_nested_names_seq}
% Collects all macros in nested \env{macro} environments, to use them
% in the \enquote{End definition} text.
% \begin{macrocode}
\seq_new:N \g_@@_nested_names_seq
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {
% \l_@@_index_macro_tl, \l_@@_index_key_tl,
% \l_@@_index_module_tl, \l_@@_index_internal_bool
% }
% When analyzing a control sequence found within a \env{macrocode}
% environment, \cs{l_@@_index_macro_tl} holds the control sequence
% (partially a string), \cs{l_@@_index_key_tl} holds the future
% sort key in the index, and \cs{l_@@_index_module_tl} is the
% subindex in which the control sequence should be listed. Finally,
% \cs{l_@@_index_internal_bool} indicates when the control sequence is
% internal and should be indexed in a slightly different subindex.
% \begin{macrocode}
\tl_new:N \l_@@_index_macro_tl
\tl_new:N \l_@@_index_key_tl
\tl_new:N \l_@@_index_module_tl
\bool_new:N \l_@@_index_internal_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_module_name_tl}
% The module name, set when reading a line |<@@=|\meta{module}|>|.
% \begin{macrocode}
\tl_new:N \g_@@_module_name_tl
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\c_@@_iow_rule_tl, \c_@@_iow_midrule_tl}
% $40$~equal signs.
% \begin{macrocode}
\tl_const:Nn \c_@@_iow_rule_tl
{ ======================================== }
\tl_const:Nn \c_@@_iow_mid_rule_tl
{ -------------------------------------- }
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {\l_@@_macro_box, \l_@@_macro_index_box, \l_@@_macro_int}
% A vertical box in which the names given to the macro environment are
% typeset, a horizontal box in which we store the targets created by
% indexing commands, and the number of macros so far (including those
% from surrounding \env{macro} environments).
% \begin{macrocode}
\box_new:N \l_@@_macro_box
\box_new:N \l_@@_macro_index_box
\int_new:N \l_@@_macro_int
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {
% \l_@@_cmd_tl,
% \l_@@_cmd_index_tl,
% \l_@@_cmd_module_tl,
% \l_@@_cmd_noindex_bool,
% \l_@@_cmd_replace_bool,
% }
% Variables used to control the behaviour of \cs{cmd}, \cs{cs} and
% \cs{tn}.
% \begin{macrocode}
\tl_new:N \l_@@_cmd_tl
\tl_new:N \l_@@_cmd_index_tl
\tl_new:N \l_@@_cmd_module_tl
\bool_new:N \l_@@_cmd_noindex_bool
\bool_new:N \l_@@_cmd_replace_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_in_implementation_bool}
% This boolean is \texttt{true} within the \env{implementation}
% environment, and \texttt{false} anywhere else.
% \begin{macrocode}
\bool_new:N \l_@@_in_implementation_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}
% {
% \g_@@_typeset_documentation_bool,
% \g_@@_typeset_implementation_bool
% }
% These booleans control whether the documentation/implementation
% should be typeset. By default both should be.
% \begin{macrocode}
\bool_new:N \g_@@_typeset_documentation_bool
\bool_new:N \g_@@_typeset_implementation_bool
\bool_set_true:N \g_@@_typeset_documentation_bool
\bool_set_true:N \g_@@_typeset_implementation_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_base_name_tl, \l_@@_variants_prop}
% The name of the macro which is being documented (without its
% signature), and a property list mapping base forms of variants to
% all variants which have the same base form.
% \begin{macrocode}
\tl_new:N \g_@@_base_name_tl
\prop_new:N \l_@@_variants_prop
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_function_label_clist, \l_@@_no_label_bool}
% Option of a \env{function} environment which replaces the label that
% would normally be inserted by labels for the given list of control
% sequences. This is only useful to avoid duplicate labels when a
% function's documentation appears multiple times.
% \begin{macrocode}
\clist_new:N \l_@@_function_label_clist
\bool_new:N \l_@@_no_label_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_date_added_tl, \l_@@_date_updated_tl}
% Values of some options of the \env{function} environment.
% \begin{macrocode}
\tl_new:N \l_@@_date_added_tl
\tl_new:N \l_@@_date_updated_tl
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_macro_argument_tl}
% Save the argument of a \env{macro} or \env{function} environment for
% use in error messages.
% \begin{macrocode}
\tl_new:N \l_@@_macro_argument_tl
% \end{macrocode}
% \end{variable}
%
% ^^A Bruno: what does the next line do?
% \begin{macrocode}
% \int_new:N \c@CodelineNo
% \end{macrocode}
%
% \subsection{Variants and helpers}
%
% \begin{macro}{\@@_tmpa:w, \@@_tmpb:w}
% Auxiliary macros for temporary use.
% \begin{macrocode}
\cs_new_eq:NN \@@_tmpa:w ?
\cs_new_eq:NN \@@_tmpb:w ?
% \end{macrocode}
% \end{macro}
%
% \begin{macro}
% {
% \seq_set_split:NoV,
% \str_case:fn,
% \tl_count:f,
% \tl_greplace_all:Nxn,
% \tl_greplace_all:Nno,
% \tl_if_head_eq_charcode:oNTF,
% \tl_if_head_eq_charcode:oNT,
% \tl_if_head_eq_charcode:oNF,
% \tl_if_head_eq_meaning:VNF,
% \tl_if_in:noTF,
% \tl_if_in:ooTF,
% \tl_if_in:NoTF,
% \tl_if_in:NoT,
% \tl_if_in:NoF,
% \tl_remove_all:Nx,
% \tl_replace_all:Nxn,
% \tl_replace_all:Nnx,
% \tl_replace_all:Non,
% \tl_replace_all:Nno,
% \tl_replace_once:Noo,
% \tl_to_str:f,
% \tl_to_str:o,
% \prop_get:NxNTF,
% \prop_put:Nxn,
% \prop_gput:NVx,
% }
% A few missing variants.
% \begin{macrocode}
\cs_generate_variant:Nn \seq_set_split:Nnn { NoV }
\cs_generate_variant:Nn \seq_gput_right:Nn { Nf }
\cs_generate_variant:Nn \str_case:nn { fn }
\cs_generate_variant:Nn \tl_count:n { f }
\cs_generate_variant:Nn \tl_greplace_all:Nnn { Nx , Nno }
\cs_generate_variant:Nn \tl_if_empty:nTF { f }
\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNTF { o }
\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNT { o }
\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNF { o }
\cs_generate_variant:Nn \tl_if_head_eq_meaning:nNF { V }
\cs_generate_variant:Nn \tl_if_in:nnTF { no , oo }
\cs_generate_variant:Nn \tl_if_in:NnTF { No }
\cs_generate_variant:Nn \tl_if_in:NnT { No }
\cs_generate_variant:Nn \tl_if_in:NnF { No }
\cs_generate_variant:Nn \tl_remove_all:Nn { Nx }
\cs_generate_variant:Nn \tl_replace_all:Nnn { Nx , Nnx, No , Nno }
\cs_generate_variant:Nn \tl_replace_once:Nnn { Noo }
\cs_generate_variant:Nn \tl_to_str:n { f , o }
\cs_generate_variant:Nn \prop_get:NnNTF { Nx }
\cs_generate_variant:Nn \prop_put:Nnn { Nx }
\cs_generate_variant:Nn \prop_gput:Nnn { NVx }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[TF]{\@@_if_almost_str:n}
% Used to test if the argument of |\cmd| or other macros to be indexed
% is almost a string or not: for instance this is \texttt{false} if |#1|
% contains |\meta{...}|. The surprising |f|-expansion are there to
% cope with the case of |#1| starting with \cs{c_backslash_str}
% which should be expanded and considered to be \enquote{normal}.
% \begin{macrocode}
\prg_new_protected_conditional:Npnn \@@_if_almost_str:n #1 { TF , T , F }
{
\int_compare:nNnTF
{ \tl_count:n {#1} }
< { \tl_count:f { \tl_to_str:f {#1} } }
{ \prg_return_false: }
{ \prg_return_true: }
}
\cs_generate_variant:Nn \@@_if_almost_str:nT { V }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_trim_right:Nn, \@@_trim_right:No}
% Removes all material after |#2| in the token list variable~|#1|.
% Perhaps combine with \cs{@@_key_trim_module:n}?
% \begin{macrocode}
\cs_new_protected:Npn \@@_trim_right:Nn #1#2
{
\cs_set:Npn \@@_tmp:w ##1 #2 ##2 \q_stop { \exp_not:n {##1} }
\tl_set:Nx #1 { \exp_after:wN \@@_tmp:w #1 #2 \q_stop }
}
\cs_generate_variant:Nn \@@_trim_right:Nn { No }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[TF]{\@@_str_if_begin:nn, \@@_str_if_begin:oo}
% True if the first string starts with the second.
% \begin{macrocode}
\prg_new_protected_conditional:Npnn \@@_str_if_begin:nn #1#2 { TF , T , F }