summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex
blob: 2007e41d3ac97d33854c3bc711589b3581954f01 (plain)
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
\typeout{makedoc.tex 2010/03/30 documentation for `makedoc.sty'}

\listfiles

\RequirePackage{makedoc}

\documentclass{article}

\input{makedoc.cfg} %% with pdf stuff and 'niceverb'

%% removed for niceverb v0.31 TODO!? 2010/03/20:

\sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21

% \makeatletter %% TEST for hyperref compatibility 2010/03/11

%   \def\@testdef #1#2#3{%

%     \def\reserved@a{#3}%

%     \expandafter \ifx \csname #1@#2\endcsname

%    \reserved@a  \else \@tempswatrue \fi

%     \if@tempswa

%       \typeout{^^J*** Type `r' <input> to get around 

%                       \string\label\space issues! ***^^J}

%       \errorcontextlines=0

%       \show\reserved@a

%       \expandafter \show \csname #1@#2\endcsname

%     \fi

%    }

% \makeatother

\begin{document}

\title{'makedoc'---Preprocessing documentation by \TeX}

  %% 2009/04/10: \\---\\\ breaks TOC

\maketitle

\begin{abstract}\noindent

'makedoc' provides commands for generating \LaTeX\ input from a 

package file in order to typeset the latter's documentation 

(somewhat similar and opposite to 'docstrip')---with 

v0.3 \emph{a single one usually suffices}. 

Certain comment marks are removed, listing commands are inserted, 

and some (configurable) typographical `txt'$\to$\TeX\ corrections 

are applied.---This 

continues the policy of 'niceverb' to minimize documentation markup in 

package files. 'makedoc' extends and exemplifies the parsing package 

'fifinddo'. After an edit (and test) of your package, you get the new 

documentation in one run (or the usual number of runs) of the 

documentation driver file.---The present approach is meant to be an 

\emph{alternative} to the standard 'doc' package and its `\DocInput'. 

It provides \emph{less} than 'doc' does, rather deliberately. It may 

be helpful at least for the development of small packages, or at least 

at early stages.

\end{abstract}

\tableofcontents

\section{Introduction}

\emph{The abstract will not be repeated in this section.} Let me add 

instead that I was in dire need of such a package, I got stuck with my 

packages because I lost orientation in them, and I was unhappy with 

the forms of documentations of my other packages, and documenting them 

with the standard \LaTeX\ 'doc' system was not attractive for me 

(neither considered helpful). %% clarified 2010/03/13

I also worked on \emph{Windows} until September 2008, and I 

find a system like the present one still more attractive then using 

(learning!\@) other filtering utilities (see below on 'awk'). And I 

may work on \emph{Windows} once again and don't want to depend on 

installing some $\dots$ there---\emph{I really would like to have 

powerful tools for everything depending on nothing but \TeX\slash 

\LaTeX!}



\section{Prior work and what is new}

It is, of course, not a new idea to get around comment marks `%' to 

typeset the documentation. 'doc''s `\DocInput' does this by making `%' 

an ``ignored" character. This way you cannot use `%' for commenting 

comments (so 'doc' offers a ``new comment mark" 

`^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!?

You also cannot use `%' for commenting out code (that you are 

pondering---or using for debugging---only). %% clarified 2010/03/13



Moreover, 'doc' requires enclosing package code explicitly by 

environment commands (behind comment marks). Stephan I. B\"ottcher 

with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}' 

and Grzegorz Murzynowski in \ctanpkgref{gmdoc}

aimed at doing away with this requirement. 

'lineno.sty' contains 'awk' scripts 

to remove starting comment marks and to insert listing commands. 

A file 'lineno.tex' is generated that typesets the documentation. 

By the way, 'lineno.sty' is full of discussions, but it is not 

'docstrip'ped---the maintainers never have received a complaint 

that inputting 'lineno.sty' were too slow. 



'gmdoc' seems to get around comment marks and insert listing commands 

\emph{while typesetting} by a refined version of `\DocInput', 

through some careful detecting and analysing comment marks, 

the approach resembles detection of lists in 'wiki.sty'.\footnote{See 

  'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages 

  document! I also find 

  \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.}

And this is a matter of principles---comparing the approaches of 

\emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"} 

('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler, 

sometimes detecting while typesetting. 

(Another example is the preprocessor 

\ctanpkgref{easylatex}

of which 'wiki.sty' is a much reduced ``while typesetting" variant.) 

``While typesetting" may be easier when single characters or 

sequences of two or three encode markup

information---but such detection can badly interfere with other 

packages etc. ``Preprocessing" may be easier when entire ``strings" 

of characters decide, which may be anywhere in a file line. 



'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by 

\emph{\TeX}. There is a general discussion of this choice in the 

documentation of 'fifinddo'. Preprocessing here can be done in the 

same \LaTeX\ run as typesetting, though you can avoid 

incompatabilities with packages needed for typesetting 

(by inputting them only \emph{after} preprocessing). 



'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be 

preferable to preprocessing with other utilities: 

When I took over maintenance of 'lineno.sty', 

I needed hard work to get the 'awk' script running. 

The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel} 

'awk' (I chose a Munich 'nawk' and reworked the script a little). 

\TeX\ seems to have better fixed functionality than other utilities! 



A different alternative to \LaTeX's 'doc' system is 

Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}' 

where the code environments extract package code in typesetting the 

documentation. %% added 2010/03/10



\section{Styles supported (parsers provided)}\label{sec:styles}

% \section{Styles of commenting '.sty's}

We find different styles of documenting \LaTeX\ packages. 

As the main aspects I consider 

(i)~\emph{telling code from comments} 

and (ii)~\emph{markup in comments}. 

(You may find more details on the next matters in the 

 ``implementation" section.)



\subsection{Telling code from comments}

\emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX) 

probably were named so to mark \emph{``comments"} as opposed 

to code $\dots$ great, but actually, in ``daily practice," 

they are so handy---and used---for ``commenting out" \emph{code}, 

i.e., \emph{managing code versions} in a simple way: 

one does not actually want to \emph{delete} code, 

one might want to use it another time, maybe for debugging

$\dots$ or to remind of earlier attempts that should not be tried 

again $\dots$



This is a problem for \emph{high-quality typesetting} of 

documentation. \emph{Code} should be typeset about as you see it on 

the \emph{screen}---\emph{monospaced}, this allows structuring by 

indenting, it is common practice to use a typewriter typeface for 

this. Real \emph{comments} should be typeset in \emph{high quality} as 

usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden 

code"} (``commented-out"). A comment mark starts the line, but 

obviously it is not really a comment and rather should be typeset 

like code (and otherwise they may break).           %% 2010/03/22

Another problem are comments at the \emph{end} of a 

\emph{code} line. Sometimes they are ``real comments" ('gmdoc' 

supports this style). But sometimes 

this is only another version of ``version management," code 

``commented-out."



I like the style of writing packages described before and use it all 

the time. I mark ``real comments" with \emph{two} adjacent comment 

marks and an ensuing space to distinguish them clearly from code 

commented out.

%% Adapted to v0.4 2010/03/29:

\emph{This style is presently the one supported by \textup{'makedoc'} 

      as default.}

This way only a line starting with 

|%% | is considered a ``real" comment line. The first three 

characters are removed, and the rest is typeset in high quality. 

Any other lines are typeset verbatim. The 'makedoc' \emph{parser} 

doing this has an ``identifier" |PPScomment| (``percent, percent, 

space"). Another identifier |comment| is a placeholder for 

the comment parser to be used, by default it is an alias for 

`PPScomment'. Lines just containing |%%| (without the space) may be 

used to suppress empty code lines preceding section titles and for 

keeping some visual, relieving space between code and comment lines.



The style I described previously may be considered ``unprofessional." 

The many \LaTeX\ packages documented using the 'doc'\slash'.dtx' 

system don't use comment marks for \emph{``commenting-out"}. 

Or one may mark code commented out by putting no space between the 

percent mark and the code. 

With v0.4 of 'makedoc', this style is supported as |PScomment|. 

You can directly call this as <main-parser> as described below, 

or you can switch to it by 

\[`\CopyFDconditionFromTo{PScomment}{comment}'\]



\subsection{Markup in comments}

Packages using the 'doc'\slash '.dtx' system as well as alternative 

highly developed systems mentioned above use (enhanced) usual 

\emph{\LaTeX} syntax for markup of comments. Other packages just use 

an \emph{ASCII} style \emph{without} any markup. My idea was to 

support the latter style by some `txt'$\to$\LaTeX\ functionality. 

'makedoc' does this using a file 'mdoccorr.cfg' which is very small 

right now.



I also thought of introducing another sort of ``decent" markup not 

needing much more space than the ``ASCII kernel" of the comments. 

This is to some extent implemented in 'niceverb.sty'. I thought of the 

syntax of editing \textit{Wikipedia} pages; this is partially 

implemented in 'wiki.sty' which unfortunately is not yet compatible 

with 'niceverb'.



But 'makedoc' implements one \textit{Wikipedia} feature in a different 

way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows:

\begin{eqnarray*}

  \endcell\endcell`%% == Section =='\\

  \endcell\endcell`%% === Subsection ==='\\

  \endcell\endcell`%% ==== Subsubsection ===='

\end{eqnarray*}

i.e., you type `== <title> ==' in place of `\section{<title>}' etc.

The parser must replace `====<title3>===' before `===<title2>===' and 

the latter before `==<title1>=='. In fact, 'makedoc' provides three 

parsers for these situations:

\begin{description}

\cmdboxitem|\SectionLevelThreeParseInput| is the most general parser 

    offered. If it does not find two strings \lq`===='\rq\ enclosing 

    \emph{something}, it passes to

\cmdboxitem|\SectionLevelTwoParseInput| which unless finding 

    two strings `===' enclosing something passes to

\cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment 

    detector |comment|. 

\end{description}





\section{Requirements}

'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand' 

etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same 

directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the 

\LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it 

should be installed anyway, or you can get its latest version 

(v2.3, 2008/06/03?) from CTAN. 



'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file 

'mdoccorr.cfg' that should have come along with 'makedoc.sty' and 

'fifinddo.sty'. You may need to have a modified copy of it in the 

directory of your main `.tex' file `<jobname>.tex' fitting special 

needs of your project. 



\section{Using 'makedoc' the simplest way}

In the most simple case, you are preparing documentation for a package 

file `<jobname>.sty' only, and you prepare a file `<jobname>.tex' 

containing 

\[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\]

and `\maketitle' etc.\ about your package.\footnote{With 'niceverb' 

    and &\title\ after &\begin{document}, you may replace 

    \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.}

The documentation will be produced by running `<jobname>.tex' with 

\LaTeX\ (e.g., \texttt{latex <jobname>.tex}).



First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble. 

There are no package options. 



Second, to typeset the commented implementation from `<jobname>.sty', 

include in <jobname>.tex's `document' environment a line 

\[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\]

<header-lines> refers to a non-negative integer as follows: 

We think the most simple and useful way of typesetting the first lines 

of a package file including license and copyrights is ``depicting them 

as image," i.e., \textit{verbatim}. We could try to determine the 

number of these lines by parsing, but we won't do so soon. Please just 

count them and enter the number as <header-lines>---and change it 

until you can accept the outcome.



\section{Steps of advanced usage}

\subsection{Different main parsers (second mandatory argument)}



`\MakeInputJobDoc''s mandatory syntax actually is 

\[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\]

<main-parser> refers to the parsing macro that is applied to each 

input line whose number is greater than <header-lines>. 

Examples for <main-parser> are named in section~\ref{sec:styles} above. 

  %% TODO above/below macro 2010/03/15

`\SectionLevelThreeParseInput' is just the most general one. 

For \emph{efficiency} (!? or also to avoid problems?) you may 

replace `Three' by `Two' or by `One', if the `====' or the `===' 

feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia} 

sectioning" feature is not used at all, use 

\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\]

---provided you want to adopt the \lq`%% '\rq\ style of marking 

comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style 

instead, use 

\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\]



\subsection{Different extensions (optional arguments)}

If your package to be documented is a \emph{class} `<jobname>.cls', 

a local configuration file `<jobname>.cfg' or something 

else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg', 

use 

\[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\]

Moreover, `\MakeInputJobDoc' writes an intermediate file 

`<jobname>.doc' and then `\input's it. If you do not like `doc' 

as extension for the written file name (maybe you use 

`<jobname>.doc' for something different already), preferring extension 

<ext-out>, use

\[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\]

Yes, you must state <ext-in> then as well, I can't help $\dots$



If even <jobname> is wrong in your view, see next step $\dots$



\subsection{Commands modifying &\MakeInputJobDoc's behaviour}

\label{sec:modimake}

Already <jobname> may not be what you want. E.g., you may want 

to collect documentations of some other files <job-1>, <job-2>, 

$\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc'

with 

\[`\renewcommand*{\mdJobName}{<job-1>}'\]

etc.\ (please reason yourself about additional requirements \dots)

As a matter of fact, `\MakeInputJobDoc' reads 

\[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad} 

  `\mdJobName.<ext-out>'\]

Stated another way, <jobname> above referred to |\mdJobName|.



`\MakeInputJobInput' moreover (by default) produces one dot 

per input line processed on screen to show progress. 

The reason is that `makedoc' issues the command 

|\ProcessLineMessage{\message{.}}|.

Already this trivial thing seems to slow down processing considerably 

(nowadays). `\MakeInputJobInput' will run faster if preceded by 

\[|\ProcessLineMessage{}|\]

which will suppress any message about processing.

However, the message may be helpful in trouble-shooting.



\subsection{Separating preprocessing from typesetting}

  %% extended 2010/03/16

To some surprise, I observe that `\MakeInputJobDoc' \emph{works.} 

This is quite a new discovery of mine (2010/03/13); 

before I thought that, for safety, preprocessing should happen 

inside a local group \emph{preceding} `\documentclass'.

|\MakeJobDoc| works like `\MakeInputJobDoc' described above, 

yet it just \emph{preprocesses} the package to be documented, 

waiting for an 

\[`\input{<jobname>.<ext-out>}'\] 

in the `document' environment to \emph{typeset} the documentation. 

So 'makedoc.tex' once had in its preamble

% \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\]

% at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later. 

\begin{eqnarray*}\endcell\endcell

  `{\RequirePackage{makedoc}'\cr    \endcell\endcell

  ` \ProcessLineMessage{}'\cr       \endcell\endcell

  ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr

                                    \endcell\endcell

  `\documentclass{article}'

\end{eqnarray*} 

I did experience some truth in my earlier safety policy: 

With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used 

in the `document' environment. `\MakeInputJobDoc' in fact does some 

'niceverb' switching (provided 'niceverb' has been loaded) 

when making use of `\MakeJobDoc'.

  %% <- verbose to improve line breaks 2010/03/16



Thinking of this ``safety" approach, especially grouping (`{\code}'), 

I had not much cared for compatibility with other packages 

in choosing 'makedoc' macro names. 



\subsection{Other 'makedoc' (and 'fifindo') script commands}

The next script commands may be considered of a lower level than 

`\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter 

commands. We also list commands from 'fifinddo.sty' that may be useful 

or, indeed, are needed for preparing package documentations. 

This may result in ideas on how do use the script commands for 

different purposes than for preparing package documentations---e.g., 

apply `txt'$\to$\TeX\ preprocessing to arbitrary text files. 



\subsubsection{Choosing parameter values for next preprocessing run}



This actually continues section~\ref{sec:modimake}.



\begin{description}

\cmdboxitem|\ResultFile{<output>}| (from 'fifinddo') 

    determines (and opens through the \TeX\ primitive `\openout') 

    the file <output> which will contain the result of 

    preprocessing the package file.

\cmdboxitem|\LaTeXresultFile{<output>}|---see next section.

\cmdboxitem|\Headerlines{<number>}| determines the <number> of lines 

    starting the input file to be copied \emph{verbatim} 

    (the first mandatory argument of `\MakeJobDoc'). 

\cmdboxitem|\MainDocParser{<parser>}| determines the <parser> 

    as in the \emph{second} mandatory argument of `\MakeJobDoc'.

\end{description}



We are now describing some parameters which rather must be switched 

``manually" instead of being modifiable by comfortable 'makedoc' 

script commands.



With the \emph{``Wikipedia sectioning"} feature, you may change the outcome 

regarding levels. Assume, e.g., the package file has titles along the 

scheme `== <title> ==' only, but these should become 

\emph{subsections} of the ``implementation" section of the 

corresponding `.tex' file. Then 

\[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\]

-- see the implementation of the sectioning feature for details. 



There is a command 

\[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad}

  |\OnEmptyInputLine|\] 

which is modified by the former. However, I cannot say much about them 

right now, I think they just were a difficult matter that I soon 

decided no longer to think about for a while (cf.\ the 

implementation). About the same holds for the hook |\EveryComment|.



The `txt'$\to$\TeX\ functionality is implemented through a hook 

\[|\MakeDocCorrectHook{<characters>}|\] 

'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e., 

it won't change <characters>. 'mdoccorr.cfg' should redefine it so it 

really ``corrects" <characters>. You might try other definitions of 

`\MakeDocCorrectHook' for different ``correcting" functions.

It should be \emph{noted} that (currently) 

`\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty' 

provides setup for (expandable) chains of expandable replacements. 

The ``Wikipedia" sectioning feature moreover uses expandable 

trimming (single) surrounding spaces, this might be provided in a more 

general way.\footnote{%% TODO 2010/03/16

    The \ctanpkgref{trimspaces} package 

    has been a \emph{model} for this feature here. It cannot be used 

    directly here because it reads blank spaces as \TeX\ characters with 

    category code 10 while 'makedoc' reads blank spaces as ``other" 

    characters (category code 12) in order to \emph{keep} all blank spaces.}



\subsubsection{``Manual" insertions to the output file}

\begin{description}

\cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes 

    <balanced> to <output> according to the earlier command 

    `\ResultFile{<output>}'.

\cmdboxitem|\WriteProvides| (from 'fifindo') writes a 

    `\ProvidesFile' line into <output> that declares the file 

    to be generated by 'fifindo'.

\cmdboxitem|\LaTeXresultFile{<output>}| issues 

    `\ResultFile{<output>}' and then writes a 

    `\ProvidesFile' line into <output> that declares the file 

    to be generated by 'makedoc'.

\end{description}



\subsubsection{Processing input and closing output}

\begin{description}

\cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em

    reads 'mdoccorr.cfg' 

    (for `\MakeDocCorrectHook', see above),

    %% removed \LaTeXresult... 2010/03/17

    copies <number> according to `\HeaderLines' (see above) 

    from <input> into <output> (according to `\ResultFile'), 

    then processes the remaining lines of <input> according 

    to `\MainDocParser' (writing several things to <output>). 

    `\MakeDoc' invokes{\sloppy\par}

\cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}| 

    (from 'fifindo') reads <input> line by line---each one stored as 

    macro |\fdInputLine| and applies <loop-body> to it. 

    \TeX's ``special" character codes (of characters listed in 

    macro `\dospecials') are replaced by 12 (``other") by 

    default---see the 'fifinddo' documentation.

\cmdboxitem|\CloseResultFile| (from 'fifinddo') 

    \hskip 0pt plus 1em

    \emph{closes} 

    <output> (using \TeX's primitive `\closeout'). 

\cmdboxitem|\MakeCloseDoc{<input>}| issues 

    `\MakeDoc{<input>}\CloseResultFile'.

\end{description}

%

Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing 

additional <input> files writing into the same <output>. Or maybe you 

want to add some additional lines manually to <output> using 

`\WriteResult'.



%% removed 2010/03/09:

% At least in the long run, using 'makedoc' should not imply commitment 

% to a certain design or to certain \LaTeX\ packages for typesetting 

% listings and documentations. Therefore, 'makedoc.cfg' (currently) 

% contains \emph{local} or \emph{personal choices}, but also 

% \emph{experiments} with future features of 'niceverb'. 

% Especially, (at present) the `packagecode' 

% environment that 'makedoc' `\write's must be chosen. 

% Currently this is the `listing' environment from 'moreverb' 

% with some modifications or extra settings. 

% It may be vital to `\MakeOther' the active characters from 'niceverb' 

% in the setup of `packagecode'. See the \emph{example} in 

% section~\ref{sec:fifinddo}.

% 

% Finally, 

% Each package file to be typeset needs its own little

% \emph{script} of 'makedoc' commands. 

% With v0.3, one or two of these should suffice. 



% It should fit into the preamble 

% of the main file for documenting the package (currently %% 2009/04/09

%   just 5 commands seem to suffice, see the \emph{example} in 

%   section~\ref{sec:fifinddo}). 

% The script commands are described 

% in the \dqtd{File handling} section of 'fifinddo.pdf' and in the 

% present section~\ref{sec:script} (and \ref{sec:emptylines}).

% As an alternative, you may prefer to have ``content only" (as much as 

% possible) in the main typesetting file and in its preamble only 

% `\input' a separate script file.

%% removed 2010/03/10:

% Yes, the idea of documenting a package \emph{here} is to have a 

% separate ``driver" file for typsetting the documentation. 

% It may contain an introduction and a guide for users. 

% The documentation of the package code that has been prepared by the 

% 'makedoc' script will be `\input'. Alternatively, the ``driver file" 

% could have title etc.\ only, or preamble and a minimal `document' 

% environment only. 

% 

% So there may be many files, which may look confusing, especially as 

% compared with the 'doc' procedure. However, 

% \begin{enumerate}

% \item ``One file distribution" still is possible thanks to the 

%       `filecontents' environment. 

% \item The 'makedoc' script can create a batch file (fitting the 

%       system, maybe using Will Robertson's 'ifplatform', or 

%       'texsys.cfg', or \dots) 

%       that removes certain auxiliary files or moves them to a 

%       certain directory. 

% \item I find it helpful to have rather little ``contentual" text 

%       in the package file. 

% \item The procedure now runs very smoothly, once the stumbling blocks 

%       have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'!

%         'niceverb' v0.1 was too sloppy with 

%         some things, and self-documentation of 'makedoc.sty' was 

%         difficult---its parsing and that from 'verbatim' cannot 

%         distinguish between markup code and typeset code.}

% \end{enumerate}



\section{Examples}%%% (documentation of 'mdoccorr.cfg')}

%% moved here 2010/03/23

\subsection{'nicetext', especially 'mdoccorr.cfg'}

The documentations of 'fifinddo', 'makedoc', and 'niceverb' 

themselves are typeset using 'makedoc'.

'fifinddo.pdf' documents 'fifinddo.sty', typeset 

from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'. 

% Section~\ref{sec:fifinddo} contains a listing of 

% 'makedoc.cfg' and 

% the 'makedoc' script file 'mkfddoc.tex' 

% especially made for 'fifinddo.pdf'. 

% 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input 

% files that were made with 'makedoc.sty'---I have only looked at them 

% when something was wrong (often syntax mistakes in typing). 

The Wikipedia syntax feature 

\begin{quote}

  `%% === subsection ===' 

\end{quote}

is used in 'fifinddo.sty' and 'niceverb.sty' only.



Along with 'makedoc' should come files `makedoc.tpl'---a template 

'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue 

on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?). 

With other definitions of `\MakeDocCorrectHook'---see below---you can 

use this dialogue for arbitrary replacement jobs (as an application of 

'fifinddo' rather than 'makedoc').{\sloppy\par}



'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following 

typographical corrections in 'mdoccorr.cfg' that defines 

`\MakeDocCorrectHook':

\strut\hrule

\begingroup 

  \hfuzz=\textwidth \advance \hfuzz by 28pt

  \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<

  \listinginput[5]{1}{mdoccorr.cfg}

\endgroup

\hrule\noindent\strut

This code also exemplifies the syntax 'niceverb' provides for writing 

about \LaTeX\ macros. It is typeset here with 'makedoc.sty' 

and then looks thus:

%  \sloppy %% 2010/03/29

\strut\hrule

\renewcommand*{\mdJobName}{mdoccorr}

\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}}

\hrule \noindent\strut

And this is the content of the intermediate generated file:

\hrule

\begingroup 

  \hfuzz=\textwidth \advance \hfuzz by 28pt

  \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<

  \listinginput[5]{1}{mdoccorr.doc}

\endgroup

\hrule 

%  \fussy %% 2010/03/29



\subsection{Packages from other authors}

`substr.tex' should typeset a nicely formatted documentation 

of Harald Har\-der's 'substr.sty', see my own result `substr.pdf'. 

'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style 

that 'nicetext' has used itself.



`arseneau.tex' should typeset nicely formatted documentations 

of a few packages by Donald Arseneau, see my own result `arseneau.pdf'. 

This demonstrates the usual \lq`% '\rq\ commenting style 

that 'makedoc' supports with v0.4.



\pagebreak              %% 2010/03/29

\ResetCodeLineNumbers   %% 2010/03/29

\section{Implementation}

\subsection{Preliminaries} 

Head of file (Legalese):

\sloppy

\renewcommand*{\mdJobName}{makedoc}

\ProcessLineMessage{}

\MakeInputJobDoc{22}{\ProcessInputWith{comment}}

The previous empty code line is the one \TeX\ insists to add at every 

end of a file it writes. %% todo TeXbook where? 2009/04/08



%% removed (TODO) 2010/03/15:

% \section{Examples: documentation of 'fifinddo'}

% \label{sec:fifinddo} 

%% removed 2010/03/10:

% \subsection{'makedoc.cfg'} 

% 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following 

% configuration file 'makedoc.cfg':

% \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<

%   %% <- TODO should be 'niceverb' command 2009/04/08

%   \listinginput[5]{1}{makedoc.cfg}

% \endgroup

%

%% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15

% \subsection{'mkfddoc.tex'}

% 'fifinddo.pdf' was typeset with the following 'makedoc' script file 

% 'mkfddoc.tex':

% \begingroup 

%   \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<

%   \listinginput[5]{1}{mkfddoc.tex}

% \endgroup

% 

%

\end{document}



2009/04/12  more on examples

2009/04/15  exemplification of niceverb.sty by mdcorr.cfg

2009/04/21  === subsubsection -> === subsection

2010/03/08  moved `only' for better line break

2010/03/09  removed something from "Basics"

2010/03/10  more changes in "Basics", pdf stuff to makedoc.cfg, 

            makedoc.cfg no longer example; CodeDoc

2010/03/11  use \MakeCloseDoc; \hfuzz with \listinginput;

            tracing spurious `Label(s) may have changed'

2010/03/12  tests for hyperref compatibility completed

2010/03/13  use \MakeInputJobDoc; clarified ...; ctan.org/pkg

2010/03/14  updated ``Examples" and abstract; \href...easylatex

2010/03/15  ``styles supported"; abstract: txt->TeX; usage

2010/03/16  more on usage; mdcorr -> mdoccorr

2010/03/17  corr. mistake with \MakeDoc

2010/03/19  '' -> " 

2010/03/20  for niceverb v0.31

2010/03/21  for niceverb v0.32

2010/03/22  "may break"

2010/03/23  \noindent in example, moved, added mdoccorr.doc, 

            makedoc.tpl

2010/03/29  \ResetCodeLineNumbers, 

            examples and explanations for v0.4

2010/03/30  \listfiles test