summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/makedoc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/makedoc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/makedoc.tex616
1 files changed, 616 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/makedoc.tex
new file mode 100644
index 00000000000..5de416ecd53
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/nicetext/makedoc.tex
@@ -0,0 +1,616 @@
+\typeout{makedoc.tex 2010/03/23 documentation for `makedoc.sty'}
+% \listfiles
+\RequirePackage{makedoc}
+\documentclass{article}
+\input{makedoc.cfg} %% with pdf stuff and 'niceverb'
+%% removed for niceverb v0.31 TODO!? 2010/03/20:
+\sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21
+% \makeatletter %% TEST for hyperref compatibility 2010/03/11
+% \def\@testdef #1#2#3{%
+% \def\reserved@a{#3}%
+% \expandafter \ifx \csname #1@#2\endcsname
+% \reserved@a \else \@tempswatrue \fi
+% \if@tempswa
+% \typeout{^^J*** Type `r' <input> to get around
+% \string\label\space issues! ***^^J}
+% \errorcontextlines=0
+% \show\reserved@a
+% \expandafter \show \csname #1@#2\endcsname
+% \fi
+% }
+% \makeatother
+\begin{document}
+\title{'makedoc'---Preprocessing documentation by \TeX}
+ %% 2009/04/10: \\---\\\ breaks TOC
+\maketitle
+\begin{abstract}\noindent
+'makedoc' provides commands for generating \LaTeX\ input from a
+package file in order to typeset the latter's documentation
+(somewhat similar and opposite to 'docstrip')---with
+v0.3 \emph{a single one usually suffices}.
+Certain comment marks are removed, listing commands are inserted,
+and some (configurable) typographical `txt'$\to$\TeX\ corrections
+are applied.---This
+continues the policy of 'niceverb' to minimize documentation markup in
+package files. 'makedoc' extends and exemplifies the parsing package
+'fifinddo'. After an edit (and test) of your package, you get the new
+documentation in one run (or the usual number of runs) of the
+documentation driver file.---The present approach is meant to be an
+\emph{alternative} to the standard 'doc' package and its `\DocInput'.
+It provides \emph{less} than 'doc' does, rather deliberately. It may
+be helpful at least for the development of small packages, or at least
+at early stages.
+\end{abstract}
+\tableofcontents
+\section{Introduction}
+\emph{The abstract will not be repeated in this section.} Let me add
+instead that I was in dire need of such a package, I got stuck with my
+packages because I lost orientation in them, and I was unhappy with
+the forms of documentations of my other packages, and documenting them
+with the standard \LaTeX\ 'doc' system was not attractive for me
+(neither considered helpful). %% clarified 2010/03/13
+I also worked on \emph{Windows} until September 2008, and I
+find a system like the present one still more attractive then using
+(learning!\@) other filtering utilities (see below on 'awk'). And I
+may work on \emph{Windows} once again and don't want to depend on
+installing some $\dots$ there---\emph{I really would like to have
+powerful tools for everything depending on nothing but \TeX\slash
+\LaTeX!}
+
+\section{Prior work and what is new}
+It is, of course, not a new idea to get around comment marks `%' to
+typeset the documentation. 'doc''s `\DocInput' does this by making `%'
+an ``ignored" character. This way you cannot use `%' for commenting
+comments (so 'doc' offers a ``new comment mark"
+`^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!?
+You also cannot use `%' for commenting out code (that you are
+pondering---or using for debugging---only). %% clarified 2010/03/13
+
+Moreover, 'doc' requires enclosing package code explicitly by
+environment commands (behind comment marks). Stephan I. B\"ottcher
+with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}'
+and Grzegorz Murzynowski in \ctanpkgref{gmdoc}
+aimed at doing away with this requirement.
+'lineno.sty' contains 'awk' scripts
+to remove starting comment marks and to insert listing commands.
+A file 'lineno.tex' is generated that typesets the documentation.
+By the way, 'lineno.sty' is full of discussions, but it is not
+'docstrip'ped---the maintainers never have received a complaint
+that inputting 'lineno.sty' were too slow.
+
+'gmdoc' seems to get around comment marks and insert listing commands
+\emph{while typesetting} by a refined version of `\DocInput',
+through some careful detecting and analysing comment marks,
+the approach resembles detection of lists in 'wiki.sty'.\footnote{See
+ 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages
+ document! I also find
+ \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.}
+And this is a matter of principles---comparing the approaches of
+\emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"}
+('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler,
+sometimes detecting while typesetting.
+(Another example is the preprocessor
+\ctanpkgref{easylatex}
+of which 'wiki.sty' is a much reduced ``while typesetting" variant.)
+``While typesetting" may be easier when single characters or
+sequences of two or three encode markup
+information---but such detection can badly interfere with other
+packages etc. ``Preprocessing" may be easier when entire ``strings"
+of characters decide, which may be anywhere in a file line.
+
+'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by
+\emph{\TeX}. There is a general discussion of this choice in the
+documentation of 'fifinddo'. Preprocessing here can be done in the
+same \LaTeX\ run as typesetting, though you can avoid
+incompatabilities with packages needed for typesetting
+(by inputting them only \emph{after} preprocessing).
+
+'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be
+preferable to preprocessing with other utilities:
+When I took over maintenance of 'lineno.sty',
+I needed hard work to get the 'awk' script running.
+The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel}
+'awk' (I chose a Munich 'nawk' and reworked the script a little).
+\TeX\ seems to have better fixed functionality than other utilities!
+
+A different alternative to \LaTeX's 'doc' system is
+Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}'
+where the code environments extract package code in typesetting the
+documentation. %% added 2010/03/10
+
+\section{Styles supported (parsers provided)}\label{sec:styles}
+% \section{Styles of commenting '.sty's}
+We find different styles of documenting \LaTeX\ packages.
+As the main aspects I consider
+(i)~\emph{telling code from comments}
+and (ii)~\emph{markup in comments}.
+(You may find more details on the next matters in the
+ ``implementation" section.)
+
+\subsection{Telling code from comments}
+\emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX)
+probably were named so to mark \emph{``comments"} as opposed
+to code $\dots$ great, but actually, in ``daily practice,"
+they are so handy---and used---for ``commenting out" \emph{code},
+i.e., \emph{managing code versions} in a simple way:
+one does not actually want to \emph{delete} code,
+one might want to use it another time, maybe for debugging
+$\dots$ or to remind of earlier attempts that should not be tried
+again $\dots$
+
+This is a problem for \emph{high-quality typesetting} of
+documentation. \emph{Code} should be typeset about as you see it on
+the \emph{screen}---\emph{monospaced}, this allows structuring by
+indenting, it is common practice to use a typewriter typeface for
+this. Real \emph{comments} should be typeset in \emph{high quality} as
+usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden
+code"} (``commented-out"). A comment mark starts the line, but
+obviously it is not really a comment and rather should be typeset
+like code (and otherwise they may break). %% 2010/03/22
+Another problem are comments at the \emph{end} of a
+\emph{code} line. Sometimes they are ``real comments" ('gmdoc'
+supports this style). But sometimes
+this is only another version of ``version management," code
+``commented-out".
+
+I like the style of writing packages described before and use it all
+the time. I mark ``real comments" with \emph{two} adjacent comment
+marks and an ensuing space to distinguish them clearly from code
+commented out.
+\emph{Only this style is presently supported by \textup{'makedoc'}!}
+More precisely, 'makedoc' at present has only \emph{one} method to
+distinguish code from comment: Only a line starting with
+|%% | is considered a ``real" comment line. The first three
+characters are removed, and the rest is typeset in high quality.
+Any other lines are typeset verbatim. The 'makedoc' \emph{parser}
+doing this has an ``identifier" |PPScomment| (``percent, percent,
+space"). Another identifier |comment| is planned to be placeholder for
+the parser to be used, but currently is just an alias for
+`PPScomment'. Lines just containing |%%| (without the space) may be
+used to suppress empty code lines preceding section titles and for
+keeping some visual, relieving space between code and comment lines.
+
+The style I described previously may be considered ``unprofessional."
+The many \LaTeX\ packages documented using the 'doc'\slash'.dtx'
+system don't use comment marks for \emph{``commenting-out"}.
+Or one may mark code commented out by putting no space between the
+percent mark and the code. I could add a parser |PScomment| to deal
+with this kind of packages later.
+
+\subsection{Markup in comments}
+Packages using the 'doc'\slash '.dtx' system as well as alternative
+highly developed systems mentioned above use (enhanced) usual
+\emph{\LaTeX} syntax for markup of comments. Other packages just use
+an \emph{ASCII} style \emph{without} any markup. My idea was to
+support the latter style by some `txt'$\to$\LaTeX\ functionality.
+'makedoc' does this using a file 'mdoccorr.cfg' which is very small
+right now.
+
+I also thought of introducing another sort of ``decent" markup not
+needing much more space than the ``ASCII kernel" of the comments.
+This is to some extent implemented in 'niceverb.sty'. I thought of the
+syntax of editing \textit{Wikipedia} pages; this is partially
+implemented in 'wiki.sty' which unfortunately is not yet compatible
+with 'niceverb'.
+
+But 'makedoc' implements one \textit{Wikipedia} feature in a different
+way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows:
+\begin{eqnarray*}
+ \endcell\endcell`%% == Section =='\\
+ \endcell\endcell`%% === Subsection ==='\\
+ \endcell\endcell`%% ==== Subsubsection ===='
+\end{eqnarray*}
+i.e., you type `== <title> ==' in place of `\section{<title>}' etc.
+The parser must replace `====<title3>===' before `===<title2>===' and
+the latter before `==<title1>=='. In fact, 'makedoc' provides three
+parsers for these situations:
+\begin{description}
+\cmdboxitem|\SectionLevelThreeParseInput| is the most general parser
+ offered. If it does not find two strings \lq`===='\rq\ enclosing
+ \emph{something}, it passes to
+\cmdboxitem|\SectionLevelTwoParseInput| which unless finding
+ two strings `===' enclosing something passes to
+\cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment
+ detector |comment|.
+\end{description}
+
+
+\section{Requirements}
+'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand'
+etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same
+directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the
+\LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it
+should be installed anyway, or you can get its latest version
+(v2.3, 2008/06/03?) from CTAN.
+
+'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file
+'mdoccorr.cfg' that should have come along with 'makedoc.sty' and
+'fifinddo.sty'. You may need to have a modified copy of it in the
+directory of your main `.tex' file `<jobname>.tex' fitting special
+needs of your project.
+
+\section{Using 'makedoc' the simplest way}
+In the most simple case, you are preparing documentation for a package
+file `<jobname>.sty' only, and you prepare a file `<jobname>.tex'
+containing
+\[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\]
+and `\maketitle' etc.\ about your package.\footnote{With 'niceverb'
+ and &\title\ after &\begin{document}, you may replace
+ \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.}
+The documentation will be produced by running `<jobname>.tex' with
+\LaTeX\ (e.g., \texttt{latex <jobname>.tex}).
+
+First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble.
+There are no package options.
+
+Second, to typeset the commented implementation from `<jobname>.sty',
+include in <jobname>.tex's `document' environment a line
+\[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\]
+<header-lines> refers to a non-negative integer as follows:
+We think the most simple and useful way of typesetting the first lines
+of a package file including license and copyrights is ``depicting them
+as image," i.e., \textit{verbatim}. We could try to determine the
+number of these lines by parsing, but we won't do so soon. Please just
+count them and enter the number as <header-lines>---and change it
+until you can accept the outcome.
+
+\section{Steps of advanced usage}
+\subsection{Different main parsers (second mandatory argument)}
+
+`\MakeInputJobDoc''s mandatory syntax actually is
+\[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\]
+<main-parser> refers to the parsing macro that is applied to each
+input line whose number is greater than <header-lines>.
+Examples for <main-parser> are named in section~\ref{sec:styles} above.
+ %% TODO above/below macro 2010/03/15
+`\SectionLevelThreeParseInput' is just the most general one.
+For \emph{efficiency} (!? or also to avoid problems?) you may
+replace `Three' by `Two' or by `One', if the `====' or the `==='
+feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia}
+sectioning" feature is not used at all, use
+\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\]
+
+\subsection{Different extensions (optional arguments)}
+If your package to be documented is a \emph{class} `<jobname>.cls',
+a local configuration file `<jobname>.cfg' or something
+else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg',
+use
+\[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\]
+Moreover, `\MakeInputJobDoc' writes an intermediate file
+`<jobname>.doc' and then `\input's it. If you do not like `doc'
+as extension for the written file name (maybe you use
+`<jobname>.doc' for something different already), preferring extension
+<ext-out>, use
+\[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\]
+Yes, you must state <ext-in> then as well, I can't help $\dots$
+
+If even <jobname> is wrong in your view, see next step $\dots$
+
+\subsection{Commands modifying &\MakeInputJobDoc's behaviour}
+\label{sec:modimake}
+Already <jobname> may not be what you want. E.g., you may want
+to collect documentations of some other files <job-1>, <job-2>,
+$\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc'
+with
+\[`\renewcommand*{\mdJobName}{<job-1>}'\]
+etc.\ (please reason yourself about additional requirements \dots)
+As a matter of fact, `\MakeInputJobDoc' reads
+\[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad}
+ `\mdJobName.<ext-out>'\]
+Stated another way, <jobname> above referred to |\mdJobName|.
+
+`\MakeInputJobInput' moreover (by default) produces one dot
+per input line processed on screen to show progress.
+The reason is that `makedoc' issues the command
+|\ProcessLineMessage{\message{.}}|.
+Already this trivial thing seems to slow down processing considerably
+(nowadays). `\MakeInputJobInput' will run faster if preceded by
+\[|\ProcessLineMessage{}|\]
+which will suppress any message about processing.
+However, the message may be helpful in trouble-shooting.
+
+\subsection{Separating preprocessing from typesetting}
+ %% extended 2010/03/16
+To some surprise, I observe that `\MakeInputJobDoc' \emph{works.}
+This is quite a new discovery of mine (2010/03/13);
+before I thought that, for safety, preprocessing should happen
+inside a local group \emph{preceding} `\documentclass'.
+|\MakeJobDoc| works like `\MakeInputJobDoc' described above,
+yet it just \emph{preprocesses} the package to be documented,
+waiting for an
+\[`\input{<jobname>.<ext-out>}'\]
+in the `document' environment to \emph{typeset} the documentation.
+So 'makedoc.tex' once had in its preamble
+% \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\]
+% at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later.
+\begin{eqnarray*}\endcell\endcell
+ `{\RequirePackage{makedoc}'\cr \endcell\endcell
+ ` \ProcessLineMessage{}'\cr \endcell\endcell
+ ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr
+ \endcell\endcell
+ `\documentclass{article}'
+\end{eqnarray*}
+I did experience some truth in my earlier safety policy:
+With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used
+in the `document' environment. `\MakeInputJobDoc' in fact does some
+'niceverb' switching (provided 'niceverb' has been loaded)
+when making use of `\MakeJobDoc'.
+ %% <- verbose to improve line breaks 2010/03/16
+
+Thinking of this ``safety" approach, especially grouping (`{\code}'),
+I had not much cared for compatibility with other packages
+in choosing 'makedoc' macro names.
+
+\subsection{Other 'makedoc' (and 'fifindo') script commands}
+The next script commands may be considered of a lower level than
+`\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter
+commands. We also list commands from 'fifinddo.sty' that may be useful
+or, indeed, are needed for preparing package documentations.
+This may result in ideas on how do use the script commands for
+different purposes than for preparing package documentations---e.g.,
+apply `txt'$\to$\TeX\ preprocessing to arbitrary text files.
+
+\subsubsection{Choosing parameter values for next preprocessing run}
+
+This actually continues section~\ref{sec:modimake}.
+
+\begin{description}
+\cmdboxitem|\ResultFile{<output>}| (from 'fifinddo')
+ determines (and opens through the \TeX\ primitive `\openout')
+ the file <output> which will contain the result of
+ preprocessing the package file.
+\cmdboxitem|\LaTeXresultFile{<output>}|---see next section.
+\cmdboxitem|\Headerlines{<number>}| determines the <number> of lines
+ starting the input file to be copied \emph{verbatim}
+ (the first mandatory argument of `\MakeJobDoc').
+\cmdboxitem|\MainDocParser{<parser>}| determines the <parser>
+ as in the \emph{second} mandatory argument of `\MakeJobDoc'.
+\end{description}
+
+We are now describing some parameters which rather must be switched
+``manually" instead of being modifiable by comfortable 'makedoc'
+script commands.
+
+With the \emph{``Wikipedia sectioning"} feature, you may change the outcome
+regarding levels. Assume, e.g., the package file has titles along the
+scheme `== <title> ==' only, but these should become
+\emph{subsections} of the ``implementation" section of the
+corresponding `.tex' file. Then
+\[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\]
+-- see the implementation of the sectioning feature for details.
+
+There is a command
+\[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad}
+ |\OnEmptyInputLine|\]
+which is modified by the former. However, I cannot say much about them
+right now, I think they just were a difficult matter that I soon
+decided no longer to think about for a while (cf.\ the
+implementation). About the same holds for the hook |\EveryComment|.
+
+The `txt'$\to$\TeX\ functionality is implemented through a hook
+\[|\MakeDocCorrectHook{<characters>}|\]
+'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e.,
+it won't change <characters>. 'mdoccorr.cfg' should redefine it so it
+really ``corrects" <characters>. You might try other definitions of
+`\MakeDocCorrectHook' for different ``correcting" functions.
+It should be \emph{noted} that (currently)
+`\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty'
+provides setup for (expandable) chains of expandable replacements.
+The ``Wikipedia" sectioning feature moreover uses expandable
+trimming (single) surrounding spaces, this might be provided in a more
+general way.\footnote{%% TODO 2010/03/16
+ The \ctanpkgref{trimspaces} package
+ has been a \emph{model} for this feature here. It cannot be used
+ directly here because it reads blank spaces as \TeX\ characters with
+ category code 10 while 'makedoc' reads blank spaces as ``other"
+ characters (category code 12) in order to \emph{keep} all blank spaces.}
+
+\subsubsection{``Manual" insertions to the output file}
+\begin{description}
+\cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes
+ <balanced> to <output> according to the earlier command
+ `\ResultFile{<output>}'.
+\cmdboxitem|\WriteProvides| (from 'fifindo') writes a
+ `\ProvidesFile' line into <output> that declares the file
+ to be generated by 'fifindo'.
+\cmdboxitem|\LaTeXresultFile{<output>}| issues
+ `\ResultFile{<output>}' and then writes a
+ `\ProvidesFile' line into <output> that declares the file
+ to be generated by 'makedoc'.
+\end{description}
+
+\subsubsection{Processing input and closing output}
+\begin{description}
+\cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em
+ reads 'mdoccorr.cfg'
+ (for `\MakeDocCorrectHook', see above),
+ %% removed \LaTeXresult... 2010/03/17
+ copies <number> according to `\HeaderLines' (see above)
+ from <input> into <output> (according to `\ResultFile'),
+ then processes the remaining lines of <input> according
+ to `\MainDocParser' (writing several things to <output>).
+ `\MakeDoc' invokes{\sloppy\par}
+\cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}|
+ (from 'fifindo') reads <input> line by line---each one stored as
+ macro |\fdInputLine| and applies <loop-body> to it.
+ \TeX's ``special" character codes (of characters listed in
+ macro `\dospecials') are replaced by 12 (``other") by
+ default---see the 'fifinddo' documentation.
+\cmdboxitem|\CloseResultFile| (from 'fifinddo')
+ \hskip 0pt plus 1em
+ \emph{closes}
+ <output> (using \TeX's primitive `\closeout').
+\cmdboxitem|\MakeCloseDoc{<input>}| issues
+ `\MakeDoc{<input>}\CloseResultFile'.
+\end{description}
+%
+Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing
+additional <input> files writing into the same <output>. Or maybe you
+want to add some additional lines manually to <output> using
+`\WriteResult'.
+
+%% removed 2010/03/09:
+% At least in the long run, using 'makedoc' should not imply commitment
+% to a certain design or to certain \LaTeX\ packages for typesetting
+% listings and documentations. Therefore, 'makedoc.cfg' (currently)
+% contains \emph{local} or \emph{personal choices}, but also
+% \emph{experiments} with future features of 'niceverb'.
+% Especially, (at present) the `packagecode'
+% environment that 'makedoc' `\write's must be chosen.
+% Currently this is the `listing' environment from 'moreverb'
+% with some modifications or extra settings.
+% It may be vital to `\MakeOther' the active characters from 'niceverb'
+% in the setup of `packagecode'. See the \emph{example} in
+% section~\ref{sec:fifinddo}.
+%
+% Finally,
+% Each package file to be typeset needs its own little
+% \emph{script} of 'makedoc' commands.
+% With v0.3, one or two of these should suffice.
+
+% It should fit into the preamble
+% of the main file for documenting the package (currently %% 2009/04/09
+% just 5 commands seem to suffice, see the \emph{example} in
+% section~\ref{sec:fifinddo}).
+% The script commands are described
+% in the \dqtd{File handling} section of 'fifinddo.pdf' and in the
+% present section~\ref{sec:script} (and \ref{sec:emptylines}).
+% As an alternative, you may prefer to have ``content only" (as much as
+% possible) in the main typesetting file and in its preamble only
+% `\input' a separate script file.
+%% removed 2010/03/10:
+% Yes, the idea of documenting a package \emph{here} is to have a
+% separate ``driver" file for typsetting the documentation.
+% It may contain an introduction and a guide for users.
+% The documentation of the package code that has been prepared by the
+% 'makedoc' script will be `\input'. Alternatively, the ``driver file"
+% could have title etc.\ only, or preamble and a minimal `document'
+% environment only.
+%
+% So there may be many files, which may look confusing, especially as
+% compared with the 'doc' procedure. However,
+% \begin{enumerate}
+% \item ``One file distribution" still is possible thanks to the
+% `filecontents' environment.
+% \item The 'makedoc' script can create a batch file (fitting the
+% system, maybe using Will Robertson's 'ifplatform', or
+% 'texsys.cfg', or \dots)
+% that removes certain auxiliary files or moves them to a
+% certain directory.
+% \item I find it helpful to have rather little ``contentual" text
+% in the package file.
+% \item The procedure now runs very smoothly, once the stumbling blocks
+% have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'!
+% 'niceverb' v0.1 was too sloppy with
+% some things, and self-documentation of 'makedoc.sty' was
+% difficult---its parsing and that from 'verbatim' cannot
+% distinguish between markup code and typeset code.}
+% \end{enumerate}
+
+\section{Examples (documentation of 'mdoccorr.cfg')}
+%% moved here 2010/03/23
+The documentations of 'fifinddo', 'makedoc', and 'niceverb'
+themselves are typeset using 'makedoc'.
+'fifinddo.pdf' documents 'fifinddo.sty', typeset
+from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'.
+% Section~\ref{sec:fifinddo} contains a listing of
+% 'makedoc.cfg' and
+% the 'makedoc' script file 'mkfddoc.tex'
+% especially made for 'fifinddo.pdf'.
+% 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input
+% files that were made with 'makedoc.sty'---I have only looked at them
+% when something was wrong (often syntax mistakes in typing).
+The Wikipedia syntax feature
+\begin{quote}
+ `%% === subsection ==='
+\end{quote}
+is used in 'fifinddo.sty' and 'niceverb.sty' only.
+
+Along with 'makedoc' should come files `makedoc.tpl'---a template
+'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue
+on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?).
+With other definitions of `\MakeDocCorrectHook'---see below---you can
+use this dialogue for arbitrary replacement jobs (as an application of
+'fifinddo' rather than 'makedoc').{\sloppy\par}
+
+'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following
+typographical corrections in 'mdoccorr.cfg' that defines
+`\MakeDocCorrectHook':
+\strut\hrule
+\begingroup
+ \hfuzz=\textwidth \advance \hfuzz by 28pt
+ \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+ \listinginput[5]{1}{mdoccorr.cfg}
+\endgroup
+\hrule\noindent\strut
+This code also exemplifies the syntax 'niceverb' provides for writing
+about \LaTeX\ macros. It is typeset here with 'makedoc.sty'
+and then looks thus:
+\strut\hrule
+\renewcommand*{\mdJobName}{mdoccorr}
+\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}}
+\hrule \noindent\strut
+And this is the content of the intermediate generated file:
+\hrule
+\begingroup
+ \hfuzz=\textwidth \advance \hfuzz by 28pt
+ \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+ \listinginput[5]{1}{mdoccorr.doc}
+\endgroup
+\hrule
+
+\section{Implementation}
+\subsection{Preliminaries}
+Head of file (Legalese):
+\sloppy
+\renewcommand*{\mdJobName}{makedoc}
+\ProcessLineMessage{}
+\MakeInputJobDoc{22}{\ProcessInputWith{comment}}
+The previous empty code line is the one \TeX\ insists to add at every
+end of a file it writes. %% todo TeXbook where? 2009/04/08
+
+%% removed (TODO) 2010/03/15:
+% \section{Examples: documentation of 'fifinddo'}
+% \label{sec:fifinddo}
+%% removed 2010/03/10:
+% \subsection{'makedoc.cfg'}
+% 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following
+% configuration file 'makedoc.cfg':
+% \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+% %% <- TODO should be 'niceverb' command 2009/04/08
+% \listinginput[5]{1}{makedoc.cfg}
+% \endgroup
+%
+%% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15
+% \subsection{'mkfddoc.tex'}
+% 'fifinddo.pdf' was typeset with the following 'makedoc' script file
+% 'mkfddoc.tex':
+% \begingroup
+% \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\<
+% \listinginput[5]{1}{mkfddoc.tex}
+% \endgroup
+%
+%
+\end{document}
+
+2009/04/12 more on examples
+2009/04/15 exemplification of niceverb.sty by mdcorr.cfg
+2009/04/21 === subsubsection -> === subsection
+2010/03/08 moved `only' for better line break
+2010/03/09 removed something from "Basics"
+2010/03/10 more changes in "Basics", pdf stuff to makedoc.cfg,
+ makedoc.cfg no longer example; CodeDoc
+2010/03/11 use \MakeCloseDoc; \hfuzz with \listinginput;
+ tracing spurious `Label(s) may have changed'
+2010/03/12 tests for hyperref compatibility completed
+2010/03/13 use \MakeInputJobDoc; clarified ...; ctan.org/pkg
+2010/03/14 updated ``Examples" and abstract; \href...easylatex
+2010/03/15 ``styles supported"; abstract: txt->TeX; usage
+2010/03/16 more on usage; mdcorr -> mdoccorr
+2010/03/17 corr. mistake with \MakeDoc
+2010/03/19 '' -> "
+2010/03/20 for niceverb v0.31
+2010/03/21 for niceverb v0.32
+2010/03/22 "may break"
+2010/03/23 \noindent in example, moved, added mdoccorr.doc,
+ makedoc.tpl