summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nicetext/makedoc.tex
blob: 6808f391b506461fe536c4d611f375b6827679e8 (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
\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