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
|
\ProvidesFile{makedoc.tex}[2009/04/15 documentation for `makedoc.sty']
\title{\textsf{makedoc}---Preprocessing documentation by \TeX}
%% 2009/04/10: \\---\\\ breaks TOC
\author{Uwe L\"uck\,---\,{\tt http://contact-ednotes.sty.de.vu}}
\listfiles
\begingroup %% generate makedoc.doc and mdcorr.doc
\RequirePackage{makedoc}
\input{mdcorr.cfg}
\LaTeXresultFile{makedoc.doc}
\HeaderLines{22}
\MainDocParser{\ProcessInputWith{comment}}
\MakeDoc{makedoc.sty}
\CloseResultFile
\LaTeXresultFile{mdcorr.doc}
\HeaderLines{0}
\MainDocParser{\ProcessInputWith{comment}}
\MakeDoc{mdcorr.cfg}
\CloseResultFile
\endgroup %% makedoc.doc and mdcorr.doc ready
\documentclass{article}
\input{makedoc.cfg}
\begin{document}
\maketitle
\begin{abstract}\noindent\hspace{1sp}%% for niceverb-apostrophe
'makedoc' provides commands for generating \LaTeX\ input from a
package file in order to typeset documentation of the latter
(somewhat similar and opposite to 'docstrip').
Certain comment marks are removed, and listing commands are inserted.
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 two or three runs---for
labels and TOC, as usual) of the documentation driver file.---This
is an \emph{alternative} to the standard 'doc' package and its
`\DocInput'. The present approach 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}
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
'doc' system was not attractive for me (neither considered helpful).
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.
\subsection{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').
You also cannot use `%' for commenting out code (that you are
pondering or use for debugging only).
Moreover, 'doc' requires enclosing package code explicitly by
environment commands (behind comment marks). Stephan I. B\"ottcher
with his 'lineno.sty' and Grzegorz Murzynowski in '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 'pauldoc' and '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 '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!
%% TODO Paul Isambert's (CTAN recently) 2009/04/08
\subsection{Basics on using 'makedoc'}
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 will need its own
\emph{script} of 'makedoc' commands. 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} and section~\ref{sec:script}
on typical ``bundling'' \emph{script commands}).
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.
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}
\subsection{Examples}
The documentations of 'fifinddo' and of 'makedoc' itself are typeset
using 'makedoc' (\hspace{1sp}'niceverb.pdf' as well, yet comments
remained scarce). 'fifinddo.pdf' documents 'fifinddo.sty', typeset
from 'fifinddo.tex', likewise 'makedoc.pdf'.
Section~\ref{sec:fifinddo} contains listings 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 `%% === subsubsection ===' is only used in
'fifinddo.sty' and 'niceverb.sty'.
\section{Implementation}
\subsection{Preliminaries}
Head of file (Legalese):
\sloppy
\input{makedoc.doc}
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
\section{Examples: documentation of 'fifinddo'}\label{sec:fifinddo}
\subsection{\hspace{1sp}'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
\subsection{\hspace{1sp}'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
\subsection{\hspace{1sp}'mdcorr.cfg'}
'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following
typographical corrections in 'mdcorr.cfg':
\strut\hrule
\begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
\listinginput[5]{1}{mdcorr.cfg}
\endgroup
\hrule\strut
This code also exemplifies the syntax 'niceverb' provides for writing
about \LaTeX\ macros. It is typeset here with 'makedoc.sty' again
and then looks thus:
\strut\hrule
\input{mdcorr.doc}
\strut\hrule
\end{document}
2009/04/12: more on examples
2009/04/15: exemplification of niceverb.sty by mdcorr.cfg
|