nicetext 0.3 (23mar10)

git-svn-id: svn://tug.org/texlive/trunk@17537 c570f23f-e606-0410-a88d-b1316a301751

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