diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex | 1286 |
1 files changed, 1286 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex new file mode 100644 index 00000000000..2007e41d3ac --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex @@ -0,0 +1,1286 @@ +\typeout{makedoc.tex 2010/03/30 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. + +%% Adapted to v0.4 2010/03/29: + +\emph{This style is presently the one supported by \textup{'makedoc'} + + as default.} + +This way 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 a placeholder for + +the comment parser to be used, by default it is 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. + +With v0.4 of 'makedoc', this style is supported as |PScomment|. + +You can directly call this as <main-parser> as described below, + +or you can switch to it by + +\[`\CopyFDconditionFromTo{PScomment}{comment}'\] + + + +\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}}|\] + +---provided you want to adopt the \lq`%% '\rq\ style of marking + +comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style + +instead, use + +\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\] + + + +\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 + +\subsection{'nicetext', especially 'mdoccorr.cfg'} + +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: + +% \sloppy %% 2010/03/29 + +\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 + +% \fussy %% 2010/03/29 + + + +\subsection{Packages from other authors} + +`substr.tex' should typeset a nicely formatted documentation + +of Harald Har\-der's 'substr.sty', see my own result `substr.pdf'. + +'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style + +that 'nicetext' has used itself. + + + +`arseneau.tex' should typeset nicely formatted documentations + +of a few packages by Donald Arseneau, see my own result `arseneau.pdf'. + +This demonstrates the usual \lq`% '\rq\ commenting style + +that 'makedoc' supports with v0.4. + + + +\pagebreak %% 2010/03/29 + +\ResetCodeLineNumbers %% 2010/03/29 + +\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 + +2010/03/29 \ResetCodeLineNumbers, + + examples and explanations for v0.4 + +2010/03/30 \listfiles test + |