| 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 |