Debian Codegraph @

texmf-dist/source/latex/nicetext/makedoc.tex

raw
1 \ProvidesFile{makedoc.tex}[2012/11/30 documenting makedoc.sty]
2 \RequirePackage{makedoc}
3 \documentclass[fleqn]{article} %% fleqn 2011/10/12
4 \input{makedoc.cfg}
5 %% 2011/08/22:
6 \MDkeywords{literate programming, .txt to .tex enhancement,
7 preprocessing documentation, macro programming}
8 \hypersetup{%
9 pdftitle=makedoc.sty preprocesses .sty for documentation,
10 pdfsubject=documenting makedoc.sty
11 }%% /2011/08/22
12 \sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21 niceverb!? 2011/01/25
13 \makeatletter %% TEST for hyperref compatibility 2010/03/11
14 % \def\@testdef #1#2#3{%
15 % \def\reserved@a{#3}%
16 % \expandafter \ifx \csname #1@#2\endcsname
17 % \reserved@a \else \@tempswatrue \fi
18 % \if@tempswa
19 % \typeout{^^J*** Type `r' <input> to get around
20 % \string\label\space issues! ***^^J}
21 % \errorcontextlines=0
22 % \show\reserved@a
23 % \expandafter \show \csname #1@#2\endcsname
24 % \fi
25 % }
26 % \makeatother
27 \begin{document}
28 \title{'makedoc'---Preprocessing documentation by \TeX\thanks{%
29 This document describes %% 2011/01/25
30 version~\textcolor{blue}{\UseVersionOf{makedoc.sty}}
31 of 'makedoc.sty' as of \UseDateOf{makedoc.sty}.}}
32 \maketitle
33 \begin{MDabstract}
34 'makedoc' provides commands for generating \LaTeX\ input from a
35 package file in order to typeset the latter's documentation
36 (somewhat similar and opposite to 'docstrip')---with
37 v0.3 \emph{a single one usually suffices}.
38 Certain comment marks are removed, listing commands are inserted,
39 and some (configurable) typographical `txt'$\to$\TeX\ corrections
40 are applied.---This
41 continues the policy of 'niceverb' to minimize documentation markup in
42 package files. 'makedoc' extends and exemplifies the parsing package
43 'fifinddo'. After an edit (and test) of your package, you get the new
44 documentation in one run (or the usual number of runs) of the
45 documentation driver file.---The present approach is meant to be an
46 \emph{alternative} to the standard 'doc' package and its `\DocInput'.
47 It provides \emph{less} than 'doc' does, rather deliberately. It may
48 be helpful at least for the development of small packages, or at least
49 at early stages.
50 \end{MDabstract}
51 \tableofcontents
52 \section{Introduction}
53 \emph{The abstract will not be repeated in this section.} Let me add
54 instead that I was in dire need of such a package, I got stuck with my
55 packages because I lost orientation in them, and I was unhappy with
56 the forms of documentations of my other packages, and documenting them
57 with the standard \LaTeX\ 'doc' system was not attractive for me
58 (neither considered helpful). %% clarified 2010/03/13
59 I also worked on \emph{Windows} until September 2008, and I
60 find a system like the present one still more attractive then using
61 (learning!\@) other filtering utilities (see below on 'awk'). And I
62 may work on \emph{Windows} once again and don't want to depend on
63 installing some $\dots$ there---\emph{I really would like to have
64 powerful tools for everything depending on nothing but \TeX\slash
65 \LaTeX!}
66
67 \section{Prior work and what is new}
68 It is, of course, not a new idea to get around comment marks `%' to
69 typeset the documentation. 'doc''s `\DocInput' does this by making `%'
70 an ``ignored" character. This way you cannot use `%' for commenting
71 comments (so 'doc' offers a ``new comment mark"
72 `^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!?
73 You also cannot use `%' for commenting out code (that you are
74 pondering---or using for debugging---only). %% clarified 2010/03/13
75
76 Moreover, 'doc' requires enclosing package code explicitly by
77 environment commands (behind comment marks). Stephan I. B\"ottcher
78 with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}'
79 and Grzegorz Murzynowski in \ctanpkgref{gmdoc}
80 aimed at doing away with this requirement.
81 'lineno.sty' contains 'awk' scripts
82 to remove starting comment marks and to insert listing commands.
83 A file 'lineno.tex' is generated that typesets the documentation.
84 By the way, 'lineno.sty' is full of discussions, but it is not
85 'docstrip'ped---the maintainers never have received a complaint
86 that inputting 'lineno.sty' were too slow.
87
88 'gmdoc' seems to get around comment marks and insert listing commands
89 \emph{while typesetting} by a refined version of `\DocInput',
90 through some careful detecting and analysing comment marks,
91 the approach resembles detection of lists in 'wiki.sty'.\footnote{See
92 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages
93 document! I also find
94 \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.}
95 And this is a matter of principles---comparing the approaches of
96 \emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"}
97 ('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler,
98 sometimes detecting while typesetting.
99 (Another example is the preprocessor
100 \ctanpkgref{easylatex}
101 of which 'wiki.sty' is a much reduced ``while typesetting" variant.)
102 ``While typesetting" may be easier when single characters or
103 sequences of two or three encode markup
104 information---but such detection can badly interfere with other
105 packages etc. ``Preprocessing" may be easier when entire ``strings"
106 of characters decide, which may be anywhere in a file line.
107
108 'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by
109 \emph{\TeX}. There is a general discussion of this choice in the
110 documentation of 'fifinddo'. Preprocessing here can be done in the
111 same \LaTeX\ run as typesetting, though you can avoid
112 incompatabilities with packages needed for typesetting
113 (by inputting them only \emph{after} preprocessing).
114
115 'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be
116 preferable to preprocessing with other utilities:
117 When I took over maintenance of 'lineno.sty',
118 I needed hard work to get the 'awk' script running.
119 The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel}
120 'awk' (I chose a Munich 'nawk' and reworked the script a little).
121 \TeX\ seems to have better fixed functionality than other utilities!
122
123 A different alternative to \LaTeX's 'doc' system is
124 Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}'
125 where the code environments extract package code in typesetting the
126 documentation. %% added 2010/03/10
127
128 \section{Styles supported (parsers provided)}\label{sec:styles}
129 % \section{Styles of commenting '.sty's}
130 We find different styles of documenting \LaTeX\ packages.
131 As the main aspects I consider
132 (i)~\emph{telling code from comments}
133 and (ii)~\emph{markup in comments}.
134 (You may find more details on the next matters in the
135 ``implementation" section.)
136
137 \subsection{Telling code from comments}
138 \emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX)
139 probably were named so to mark \emph{``comments"} as opposed
140 to code $\dots$ great, but actually, in ``daily practice,"
141 they are so handy---and used---for ``commenting out" \emph{code},
142 i.e., \emph{managing code versions} in a simple way:
143 one does not actually want to \emph{delete} code,
144 one might want to use it another time, maybe for debugging
145 $\dots$ or to remind of earlier attempts that should not be tried
146 again $\dots$
147
148 This is a problem for \emph{high-quality typesetting} of
149 documentation. \emph{Code} should be typeset about as you see it on
150 the \emph{screen}---\emph{monospaced}, this allows structuring by
151 indenting, it is common practice to use a typewriter typeface for
152 this. Real \emph{comments} should be typeset in \emph{high quality} as
153 usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden
154 code"} (``commented-out"). A comment mark starts the line, but
155 obviously it is not really a comment and rather should be typeset
156 like code (and otherwise they may break). %% 2010/03/22
157 Another problem are comments at the \emph{end} of a
158 \emph{code} line. Sometimes they are ``real comments" ('gmdoc'
159 supports this style). But sometimes
160 this is only another version of ``version management," code
161 ``commented-out."
162
163 I like the style of writing packages described before and use it all
164 the time. I mark ``real comments" with \emph{two} adjacent comment
165 marks and an ensuing space to distinguish them clearly from code
166 commented out.
167 %% Adapted to v0.4 2010/03/29:
168 \emph{This style is presently the one supported by \textup{'makedoc'}
169 as default.}
170 This way only a line starting with
171 |%% | is considered a ``real" comment line. The first three
172 characters are removed, and the rest is typeset in high quality.
173 Any other lines are typeset verbatim. The 'makedoc' \emph{parser}
174 doing this has an ``identifier" |PPScomment| (``percent, percent,
175 space"). Another identifier |comment| is a placeholder for
176 the comment parser to be used, by default it is an alias for
177 `PPScomment'. Lines just containing |%%| (without the space) may be
178 used to suppress empty code lines preceding section titles and for
179 keeping some visual, relieving space between code and comment lines.
180
181 The style I described previously may be considered ``unprofessional."
182 The many \LaTeX\ packages documented using the 'doc'\slash'.dtx'
183 system don't use comment marks for \emph{``commenting-out"}.
184 Or one may mark code commented out by putting no space between the
185 percent mark and the code.
186 With v0.4 of 'makedoc', this style is supported as |PScomment|.
187 You can directly call this as <main-parser> as described below,
188 or you can switch to it by
189 \[`\CopyFDconditionFromTo{PScomment}{comment}'\]
190
191 \subsection{Markup in comments}
192 \label{sec:mdoccorr-tex} %% 2012/03/18
193 Packages using the 'doc'\slash '.dtx' system as well as alternative
194 highly developed systems mentioned above use (enhanced) usual
195 \emph{\LaTeX} syntax for markup of comments. Other packages just use
196 an \emph{ASCII} style \emph{without} any markup. My idea was to
197 support the latter style by some `txt'$\to$\LaTeX\ functionality.
198 'makedoc' does this using a file 'mdoccorr.cfg' which is very small
199 right now.
200
201 I also thought of introducing another sort of ``decent" markup not
202 needing much more space than the ``ASCII kernel" of the comments.
203 This is to some extent implemented in 'niceverb.sty'. I thought of the
204 syntax of editing \textit{Wikipedia} pages; this is partially
205 implemented in 'wiki.sty' which unfortunately is not yet compatible
206 with 'niceverb'.
207
208 But 'makedoc' implements one \textit{Wikipedia} feature in a different
209 way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows:
210 \begin{eqnarray*}
211 \endcell\endcell`%% == Section =='\\
212 \endcell\endcell`%% === Subsection ==='\\
213 \endcell\endcell`%% ==== Subsubsection ===='
214 \end{eqnarray*}
215 i.e., you type `== <title> ==' in place of `\section{<title>}' etc.
216 The parser must replace `====<title3>===' before `===<title2>===' and
217 the latter before `==<title1>=='. In fact, 'makedoc' provides three
218 parsers for these situations:
219 \begin{description}
220 \cmdboxitem|\SectionLevelThreeParseInput| is the most general parser
221 offered. If it does not find two strings \lq`===='\rq\ enclosing
222 \emph{something}, it passes to
223 \cmdboxitem|\SectionLevelTwoParseInput| which unless finding
224 two strings `===' enclosing something passes to
225 \cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment
226 detector |comment|.
227 \end{description}
228
229
230 \section{Requirements}
231 'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand'
232 etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same
233 directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the
234 \LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it
235 should be installed anyway, or you can get its latest version
236 (v2.3, 2008/06/03?) from CTAN.
237
238 'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file
239 'mdoccorr.cfg' that should have come along with 'makedoc.sty' and
240 'fifinddo.sty'. You may need to have a modified copy of it in the
241 directory of your main `.tex' file `<jobname>.tex' fitting special
242 needs of your project.
243
244 \section{Using 'makedoc' the simplest way}
245 In the most simple case, you are preparing documentation for a package
246 file `<jobname>.sty' only, and you prepare a file `<jobname>.tex'
247 containing
248 \[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\]
249 and `\maketitle' etc.\ about your package.\footnote{With 'niceverb'
250 and &\title\ after &\begin{document}, you may replace
251 \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.}
252 The documentation will be produced by running `<jobname>.tex' with
253 \LaTeX\ (e.g., \texttt{latex <jobname>.tex}).
254
255 First, `<jobname>.tex' must have
256 \[|\usepackage{makedoc}|\quad\mbox{or}\quad
257 |\RequirePackage{makedoc}|\] %% 2011/11/05
258 in its preamble. There are no package options.
259
260 Second, to typeset the commented implementation from `<jobname>.sty',
261 include in <jobname>.tex's `document' environment a line
262 \[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\]
263 <header-lines> refers to a non-negative integer as follows:
264 We think the most simple and useful way of typesetting the first lines
265 of a package file including license and copyrights is ``depicting them
266 as image," i.e., \textit{verbatim}. We could try to determine the
267 number of these lines by parsing, but we won't do so soon. Please just
268 count them and enter the number as <header-lines>---and change it
269 until you can accept the outcome.
270
271 \section{Steps of advanced usage}
272 \subsection{Different main parsers (second mandatory argument)}
273
274 `\MakeInputJobDoc''s mandatory syntax actually is
275 \[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\]
276 <main-parser> refers to the parsing macro that is applied to each
277 input line whose number is greater than <header-lines>.
278 Examples for <main-parser> are named in section~\ref{sec:styles} above.
279 %% TODO above/below macro 2010/03/15
280 `\SectionLevelThreeParseInput' is just the most general one.
281 For \emph{efficiency} (!? or also to avoid problems?) you may
282 replace `Three' by `Two' or by `One', if the `====' or the `==='
283 feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia}
284 sectioning" feature is not used at all, use
285 \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\]
286 ---provided you want to adopt the \lq`%% '\rq\ style of marking
287 comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style
288 instead, use
289 \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\]
290
291 \subsection{Different extensions (optional arguments)}
292 If your package to be documented is a \emph{class} `<jobname>.cls',
293 a local configuration file `<jobname>.cfg' or something
294 else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg',
295 use
296 \[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\]
297 Moreover, `\MakeInputJobDoc' writes an intermediate file
298 `<jobname>.doc' and then `\input's it. If you do not like `doc'
299 as extension for the written file name (maybe you use
300 `<jobname>.doc' for something different already), preferring extension
301 <ext-out>, use
302 \[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\]
303 Yes, you must state <ext-in> then as well, I can't help $\dots$
304
305 If even <jobname> is wrong in your view, see next step $\dots$
306
307 \subsection{Commands modifying &\MakeInputJobDoc's behaviour}
308 \label{sec:modimake}
309 Already <jobname> may not be what you want. E.g., you may want
310 to collect documentations of some other files <job-1>, <job-2>,
311 $\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc'
312 with
313 \[`\renewcommand*{\mdJobName}{<job-1>}'\]
314 etc.\ (please reason yourself about additional requirements \dots)
315 As a matter of fact, `\MakeInputJobDoc' reads
316 \[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad}
317 `\mdJobName.<ext-out>'\]
318 Stated another way, <jobname> above referred to |\mdJobName|.
319
320 `\MakeInputJobInput' moreover (by default) produces one dot
321 per input line processed on screen to show progress.
322 The reason is that `makedoc' issues the command
323 |\ProcessLineMessage{\message{.}}|.
324 Already this trivial thing seems to slow down processing considerably
325 (nowadays). `\MakeInputJobInput' will run faster if preceded by
326 \[|\ProcessLineMessage{}|\]
327 which will suppress any message about processing.
328 However, the message may be helpful in trouble-shooting.
329
330 \subsection{Separating preprocessing from typesetting}
331 \label{sec:sep-pre-type} %% 2011/10/07
332 %% extended 2010/03/16
333 To some surprise, I observe that `\MakeInputJobDoc' \emph{works.}
334 This is quite a new discovery of mine (2010/03/13);
335 before I thought that, for safety, preprocessing should happen
336 inside a local group \emph{preceding} `\documentclass'.
337 |\MakeJobDoc| works like `\MakeInputJobDoc' described above,
338 yet it just \emph{preprocesses} the package to be documented,
339 waiting for an
340 \[`\input{<jobname>.<ext-out>}'\]
341 in the `document' environment to \emph{typeset} the documentation.
342 So 'makedoc.tex' once had in its preamble
343 % \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\]
344 % at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later.
345 \begin{eqnarray*}\endcell\endcell
346 `{\RequirePackage{makedoc}'\cr \endcell\endcell
347 ` \ProcessLineMessage{}'\cr \endcell\endcell
348 ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr
349 \endcell\endcell
350 `\documentclass{article}'
351 \end{eqnarray*}
352 I did experience some truth in my earlier safety policy:
353 With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used
354 in the `document' environment. `\MakeInputJobDoc' in fact does some
355 'niceverb' switching (provided 'niceverb' has been loaded)
356 when making use of `\MakeJobDoc'.
357 %% <- verbose to improve line breaks 2010/03/16
358
359 Thinking of this ``safety" approach, especially grouping
360 (`{<code>}'), %%% (`{\code}'), %% 2011/10/07
361 I had not much cared for compatibility with other packages
362 in choosing 'makedoc' macro names.
363
364 \subsection{Other 'makedoc' (and 'fifindo') script commands}
365 The next script commands may be considered of a lower level than
366 `\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter
367 commands. We also list commands from 'fifinddo.sty' that may be useful
368 or, indeed, are needed for preparing package documentations.
369 This may result in ideas on how do use the script commands for
370 different purposes than for preparing package documentations---e.g.,
371 apply `txt'$\to$\TeX\ preprocessing to arbitrary text files.
372
373 \subsubsection{Choosing parameter values for next preprocessing run}
374
375 This actually continues section~\ref{sec:modimake}.
376
377 \begin{description}
378 \cmdboxitem|\ResultFile{<output>}| (from 'fifinddo')
379 determines (and opens through the \TeX\ primitive `\openout')
380 the file <output> which will contain the result of
381 preprocessing the package file.
382 \cmdboxitem|\LaTeXresultFile{<output>}|---see next section.
383 \cmdboxitem|\Headerlines{<number>}| determines the <number> of lines
384 starting the input file to be copied \emph{verbatim}
385 (the first mandatory argument of `\MakeJobDoc').
386 \cmdboxitem|\MainDocParser{<parser>}| determines the <parser>
387 as in the \emph{second} mandatory argument of `\MakeJobDoc'.
388 \end{description}
389
390 We are now describing some parameters which rather must be switched
391 ``manually" instead of being modifiable by comfortable 'makedoc'
392 script commands.
393
394 With the \emph{``Wikipedia sectioning"} feature, you may change the outcome
395 regarding levels. Assume, e.g., the package file has titles along the
396 scheme \[`== <title> =='\] only, but these should become %% \[...\] 2012/11/12
397 \emph{subsections} of the ``implementation" section of the
398 corresponding `.tex' file. Then
399 \[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\]
400 -- see the implementation of the sectioning feature for details.
401
402 There is a command
403 \[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad}
404 |\OnEmptyInputLine|\]
405 which is modified by the former. However, I cannot say much about them
406 right now, I think they just were a difficult matter that I soon
407 decided no longer to think about for a while (cf.\ the
408 implementation). About the same holds for the hook |\EveryComment|.
409
410 The `txt'$\to$\TeX\ functionality is implemented through a hook
411 \[|\MakeDocCorrectHook{<characters>}|\]
412 'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e.,
413 it won't change <characters>. 'mdoccorr.cfg' should redefine it so it
414 really ``corrects" <characters>. You might try other definitions of
415 `\MakeDocCorrectHook' for different ``correcting" functions.
416 It should be \emph{noted} that (currently)
417 `\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty'
418 provides setup for (expandable) chains of expandable replacements.
419 The ``Wikipedia" sectioning feature moreover uses expandable
420 trimming (single) surrounding spaces, this might be provided in a more
421 general way.\footnote{%% TODO 2010/03/16
422 The \ctanpkgref{trimspaces} package
423 has been a \emph{model} for this feature here. It cannot be used
424 directly here because it reads blank spaces as \TeX\ characters with
425 category code 10 while 'makedoc' reads blank spaces as ``other"
426 characters (category code 12) in order to \emph{keep} all blank spaces.}
427
428 \subsubsection{``Manual" insertions to the output file}
429 \begin{description}
430 \cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes
431 <balanced> to <output> according to the earlier command
432 `\ResultFile{<output>}'.
433 \cmdboxitem|\WriteProvides| (from 'fifindo') writes a
434 `\ProvidesFile' line into <output> that declares the file
435 to be generated by 'fifindo'.
436 \cmdboxitem|\LaTeXresultFile{<output>}| issues
437 `\ResultFile{<output>}' and then writes a
438 `\ProvidesFile' line into <output> that declares the file
439 to be generated by 'makedoc'.
440 \end{description}
441
442 \subsubsection{Processing input and closing output}
443 \begin{description}
444 \cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em
445 reads 'mdoccorr.cfg'
446 (for `\MakeDocCorrectHook', see above),
447 %% removed \LaTeXresult... 2010/03/17
448 copies <number> according to `\HeaderLines' (see above)
449 from <input> into <output> (according to `\ResultFile'),
450 then processes the remaining lines of <input> according
451 to `\MainDocParser' (writing several things to <output>).
452 `\MakeDoc' invokes{\sloppy\par}
453 \cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}|
454 (from 'fifindo') reads <input> line by line---each one stored as
455 macro |\fdInputLine| and applies <loop-body> to it.
456 \TeX's ``special" character codes (of characters listed in
457 macro `\dospecials') are replaced by 12 (``other") by
458 default---see the 'fifinddo' documentation.
459 \cmdboxitem|\CloseResultFile| (from 'fifinddo')
460 \hskip 0pt plus 1em
461 \emph{closes}
462 <output> (using \TeX's primitive `\closeout').
463 \cmdboxitem|\MakeCloseDoc{<input>}| issues
464 `\MakeDoc{<input>}\CloseResultFile'.
465 \end{description}
466 %
467 Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing
468 additional <input> files writing into the same <output>. Or maybe you
469 want to add some additional lines manually to <output> using
470 `\WriteResult'.---By contrast, you may want to make a single output
471 file from a single input file! Therefore:
472 %% <- 2011/11/05 ->
473 %
474 \begin{description}
475 \cmdboxitem|\MakeSingleDoc[<out-ext>]{<in-output>.<in-ext>}| \
476 issues\\`\LaTeXresultFile{<in-output>.<out-ext>}'\quad
477 and\\`\MakeDocCloseDoc{<in-output>.<in-ext>}'.\\
478 The default for <out-ext> is `doc'.
479 \end{description}
480
481 %% removed 2010/03/09:
482 % At least in the long run, using 'makedoc' should not imply commitment
483 % to a certain design or to certain \LaTeX\ packages for typesetting
484 % listings and documentations. Therefore, 'makedoc.cfg' (currently)
485 % contains \emph{local} or \emph{personal choices}, but also
486 % \emph{experiments} with future features of 'niceverb'.
487 % Especially, (at present) the `packagecode'
488 % environment that 'makedoc' `\write's must be chosen.
489 % Currently this is the `listing' environment from 'moreverb'
490 % with some modifications or extra settings.
491 % It may be vital to `\MakeOther' the active characters from 'niceverb'
492 % in the setup of `packagecode'. See the \emph{example} in
493 % section~\ref{sec:fifinddo}.
494 %
495 % Finally,
496 % Each package file to be typeset needs its own little
497 % \emph{script} of 'makedoc' commands.
498 % With v0.3, one or two of these should suffice.
499
500 % It should fit into the preamble
501 % of the main file for documenting the package (currently %% 2009/04/09
502 % just 5 commands seem to suffice, see the \emph{example} in
503 % section~\ref{sec:fifinddo}).
504 % The script commands are described
505 % in the \dqtd{File handling} section of 'fifinddo.pdf' and in the
506 % present section~\ref{sec:script} (and \ref{sec:emptylines}).
507 % As an alternative, you may prefer to have ``content only" (as much as
508 % possible) in the main typesetting file and in its preamble only
509 % `\input' a separate script file.
510 %% removed 2010/03/10:
511 % Yes, the idea of documenting a package \emph{here} is to have a
512 % separate ``driver" file for typsetting the documentation.
513 % It may contain an introduction and a guide for users.
514 % The documentation of the package code that has been prepared by the
515 % 'makedoc' script will be `\input'. Alternatively, the ``driver file"
516 % could have title etc.\ only, or preamble and a minimal `document'
517 % environment only.
518 %
519 % So there may be many files, which may look confusing, especially as
520 % compared with the 'doc' procedure. However,
521 % \begin{enumerate}
522 % \item ``One file distribution" still is possible thanks to the
523 % `filecontents' environment.
524 % \item The 'makedoc' script can create a batch file (fitting the
525 % system, maybe using Will Robertson's 'ifplatform', or
526 % 'texsys.cfg', or \dots)
527 % that removes certain auxiliary files or moves them to a
528 % certain directory.
529 % \item I find it helpful to have rather little ``contentual" text
530 % in the package file.
531 % \item The procedure now runs very smoothly, once the stumbling blocks
532 % have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'!
533 % 'niceverb' v0.1 was too sloppy with
534 % some things, and self-documentation of 'makedoc.sty' was
535 % difficult---its parsing and that from 'verbatim' cannot
536 % distinguish between markup code and typeset code.}
537 % \end{enumerate}
538 \subsection{Star avoids &\input{mdoccorrhook}}
539 All the preprocessing commands described above---apart from the
540 'fifinddo' command `\ProcessFileWith'---input the file
541 'mdoccorr.cfg' with (typographical) replacement rules
542 (Sec.~\ref{sec:mdoccorr-tex}, Sec.~\ref{sec:mdoccorr})
543 automatically. They have star variants that don't:
544 |\MakeInputJobDoc*|, |\MakeJobDoc*|, |\MakeDoc*|,
545 |\MakeCloseDoc*|, and |\MakeSingleDoc*|.
546 This is useful when rules very specific to a certain package
547 must be applied instead of the usual ones.
548 The examples named in Sec.~\ref{sec:otherauth} use this feature
549 for formatting other author's plain text documentation
550 without modifying their files.
551
552 \section{Examples}%%% (documentation of 'mdoccorr.cfg')}
553 %% moved here 2010/03/23
554 \subsection{Documenting 'nicetext''s `mdoccorr.cfg'}
555 The documentations of 'fifinddo', 'makedoc', and 'niceverb'
556 themselves are typeset using 'makedoc'.
557 'fifinddo.pdf' documents 'fifinddo.sty', typeset
558 from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'.
559 % Section~\ref{sec:fifinddo} contains a listing of
560 % 'makedoc.cfg' and
561 % the 'makedoc' script file 'mkfddoc.tex'
562 % especially made for 'fifinddo.pdf'.
563 % 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input
564 % files that were made with 'makedoc.sty'---I have only looked at them
565 % when something was wrong (often syntax mistakes in typing).
566 The Wikipedia syntax feature
567 \begin{quote}
568 `%% === subsection ==='
569 \end{quote}
570 is used in 'fifinddo.sty' and 'niceverb.sty' only.
571
572 Along with 'makedoc' should come files `makedoc.tpl'---a template
573 'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue
574 on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?).
575 With other definitions of `\MakeDocCorrectHook'---see below---you can
576 use this dialogue for arbitrary replacement jobs (as an application of
577 'fifinddo' rather than 'makedoc').{\sloppy\par}
578
579 'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following
580 typographical corrections in 'mdoccorr.cfg' that defines
581 `\MakeDocCorrectHook':
582 % \strut\hrule %% rm. those struts 2012/11/12
583 % \listinginput[5]{1}{mdoccorr.cfg}
584 %% <- 2012/11/12 >
585 \MDsamplecodeinput{mdoccorr.cfg}
586 \noindent
587 This code also exemplifies the syntax 'niceverb' provides for writing
588 about \LaTeX\ macros. It is typeset here with 'makedoc.sty'
589 and then looks thus:
590 \bigskip
591 \hrule
592 \renewcommand*{\mdJobName}{mdoccorr}
593 \MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}}
594 \hrule
595 \bigskip
596 \noindent
597 And this is the content of the intermediate generated file:
598 % \listinginput[5]{1}{mdoccorr.doc}
599 \MDsamplecodeinput[75pt]{mdoccorr.doc}
600 % \enlargethispage{8pt} %% 2011/09/14 keep rule on same page %% rm. 2011/10/25
601 % \hrule
602 % \fussy %% 2010/03/29
603
604 \iffalse %% 2012/11/30
605 %% 2012/11/12:
606 \pagebreak
607 \subsection{Documenting 'nicetext''s `makedoc.cfg'}
608 `makedoc.cfg' once was meant to be just ``configuration,"
609 but then I introduced some definitions there that may be
610 more interesting and once become a package.
611 Its typeset documentation first:
612 \pagebreak[3]
613 \strut\bigskip
614 \hrule
615 \smallskip
616 \renewcommand*{\mdJobName}{makedoc}
617 \MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}}
618 \hrule
619 \bigskip
620 \noindent\strut
621 The bare code of `makedoc.cfg' is:
622 \MDsamplecodeinput{makedoc.cfg}
623
624 \fi
625 \subsection{Packages from other authors}
626 \label{sec:otherauth}
627 `substr.tex' should typeset a nicely formatted documentation
628 of Harald Har\-ders' 'substr.sty', see my own result `substr.pdf'.
629 'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style
630 that 'nicetext' has used itself.
631
632 `arseneau.tex' should typeset nicely formatted documentations
633 of a few packages by Donald Arseneau, see my own result `arseneau.pdf'.
634 This demonstrates the usual \lq`% '\rq\ commenting style
635 that 'makedoc' supports with v0.4.
636
637 % \pagebreak %% 2010/03/29; rm. 2011/09/14
638 \ResetCodeLineNumbers %% 2010/03/29
639 \section{Implementation}
640 \subsection{Preliminaries}
641 Head of file (Legalese):
642 \sloppy
643 \renewcommand*{\mdJobName}{makedoc}
644 \ProcessLineMessage{}
645 \MakeInputJobDoc{22}{\ProcessInputWith{comment}}
646 \enlargethispage{2\baselineskip} %% 2011/11/05
647 The previous empty code line is the one \TeX\ insists to add at every
648 end of a file it writes. %% todo TeXbook where? 2009/04/08
649
650 %% 2012/11/30:
651 \section{`makedoc.cfg' Documented}
652 `makedoc.cfg' once was meant to be just ``configuration,"
653 but then I introduced some definitions there that may be
654 more interesting and once become a package.
655 \renewcommand*{\mdJobName}{makedoc}
656 \MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}}
657
658 %% removed (TODO) 2010/03/15:
659 % \section{Examples: documentation of 'fifinddo'}
660 % \label{sec:fifinddo}
661 %% removed 2010/03/10:
662 % \subsection{'makedoc.cfg'}
663 % 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following
664 % configuration file 'makedoc.cfg':
665 % \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
666 % %% <- TODO should be 'niceverb' command 2009/04/08
667 % \listinginput[5]{1}{makedoc.cfg}
668 % \endgroup
669 %
670 %% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15
671 % \subsection{'mkfddoc.tex'}
672 % 'fifinddo.pdf' was typeset with the following 'makedoc' script file
673 % 'mkfddoc.tex':
674 % \begingroup
675 % \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
676 % \listinginput[5]{1}{mkfddoc.tex}
677 % \endgroup
678 %
679 %
680 \end{document}
681
682 2009/04/12 more on examples
683 2009/04/15 exemplification of niceverb.sty by mdcorr.cfg
684 2009/04/21 === subsubsection -> === subsection
685 2010/03/08 moved `only' for better line break
686 2010/03/09 removed something from "Basics"
687 2010/03/10 more changes in "Basics", pdf stuff to makedoc.cfg,
688 makedoc.cfg no longer example; CodeDoc
689 2010/03/11 use \MakeCloseDoc; \hfuzz with \listinginput;
690 tracing spurious `Label(s) may have changed'
691 2010/03/12 tests for hyperref compatibility completed
692 2010/03/13 use \MakeInputJobDoc; clarified ...; ctan.org/pkg
693 2010/03/14 updated ``Examples" and abstract; \href...easylatex
694 2010/03/15 ``styles supported"; abstract: txt->TeX; usage
695 2010/03/16 more on usage; mdcorr -> mdoccorr
696 2010/03/17 corr. mistake with \MakeDoc
697 2010/03/19 '' -> "
698 2010/03/20 for niceverb v0.31
699 2010/03/21 for niceverb v0.32
700 2010/03/22 "may break"
701 2010/03/23 \noindent in example, moved, added mdoccorr.doc,
702 makedoc.tpl
703 2010/03/29 \ResetCodeLineNumbers,
704 examples and explanations for v0.4
705 2010/03/30 \listfiles test
706 2010/11/27 \ProvidesFile for myfilist
707 2011/01/25 \thanks with readprov.sty
708 2011/08/22 using new makedoc.cfg features
709 2011/09/14 rm. \pagebreak
710 2011/10/07 "grouping" fix(?) + \label in "Separating"
711 2011/10/12 fleqn
712 2011/10/25 without \enlargethispage
713 2011/11/05 or \RequirePackage{makedoc}; \MakeSingleDoc
714 2011/11/19 debugging for fifinddo v0.5
715 2012/03/18 * forms; Harald H. corrected
716 2012/11/12 reworked `mdoccorr' example (\MDsampleinput),
717 added `makedoc.cfg' documentation as sample
718 2012/11/13 using \MDsamplecodeinput from `makedoc.cfg' same day