\ProvidesFile{makedoc.tex}[2009/04/15 documentation for `makedoc.sty'] \title{\textsf{makedoc}---Preprocessing documentation by \TeX} %% 2009/04/10: \\---\\\ breaks TOC \author{Uwe L\"uck\,---\,{\tt http://contact-ednotes.sty.de.vu}} \listfiles \begingroup %% generate makedoc.doc and mdcorr.doc \RequirePackage{makedoc} \input{mdcorr.cfg} \LaTeXresultFile{makedoc.doc} \HeaderLines{22} \MainDocParser{\ProcessInputWith{comment}} \MakeDoc{makedoc.sty} \CloseResultFile \LaTeXresultFile{mdcorr.doc} \HeaderLines{0} \MainDocParser{\ProcessInputWith{comment}} \MakeDoc{mdcorr.cfg} \CloseResultFile \endgroup %% makedoc.doc and mdcorr.doc ready \documentclass{article} \input{makedoc.cfg} \begin{document} \maketitle \begin{abstract}\noindent\hspace{1sp}%% for niceverb-apostrophe 'makedoc' provides commands for generating \LaTeX\ input from a package file in order to typeset documentation of the latter (somewhat similar and opposite to 'docstrip'). Certain comment marks are removed, and listing commands are inserted. This continues the policy of 'niceverb' to minimize documentation markup in package files. 'makedoc' extends and exemplifies the parsing package 'fifinddo'. After an edit (and test) of your package, you get the new documentation in one run (or two or three runs---for labels and TOC, as usual) of the documentation driver file.---This is an \emph{alternative} to the standard 'doc' package and its `\DocInput'. The present approach provides \emph{less} than 'doc' does, rather deliberately. It may be helpful at least for the development of small packages, or at least at early stages. \end{abstract} \tableofcontents \section{Introduction} The abstract will not be repeated in this section. Let me add instead that I was in dire need of such a package, I got stuck with my packages because I lost orientation in them, and I was unhappy with the forms of documentations of my other packages, and documenting them with the 'doc' system was not attractive for me (neither considered helpful). I also worked on \emph{Windows} until September 2008, and I find a system like the present one still more attractive then using (learning!\@) other filtering utilities (see below on 'awk'). And I may work on \emph{Windows} once again and don't want to depend on installing some $\dots$ there. \subsection{Prior work and what is new} It is, of course, not a new idea to get around comment marks `%' to typeset the documentation. 'doc''s `\DocInput' does this by making `%' an ``ignored'' character. This way you cannot use `%' for commenting comments (so 'doc' offers a ``new comment mark'' `^^A'). You also cannot use `%' for commenting out code (that you are pondering or use for debugging only). Moreover, 'doc' requires enclosing package code explicitly by environment commands (behind comment marks). Stephan I. B\"ottcher with his 'lineno.sty' and Grzegorz Murzynowski in 'gmdoc' aimed at doing away with this requirement. 'lineno.sty' contains 'awk' scripts to remove starting comment marks and to insert listing commands. A file 'lineno.tex' is generated that typesets the documentation. By the way, 'lineno.sty' is full of discussions, but it is not 'docstrip'ped---the maintainers never have received a complaint that inputting 'lineno.sty' were too slow. 'gmdoc' seems to get around comment marks and insert listing commands \emph{while typesetting} by a refined version of `\DocInput', through some careful detecting and analysing comment marks, the approach resembles detection of lists in 'wiki.sty'.\footnote{See 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages document! I also find 'pauldoc' and 'xdoc' inspiring.} And this is a matter of principles---comparing the approaches of \emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting''} ('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler, sometimes detecting while typesetting. (Another example is the preprocessor 'easylatex' of which 'wiki.sty' is a much reduced ``while typesetting'' variant.) ``While typesetting'' may be easier when single characters or sequences of two or three encode markup information---but such detection can badly interfere with other packages etc. ``Preprocessing'' may be easier when entire ``strings'' of characters decide, which may be anywhere in a file line. 'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by \emph{\TeX}. There is a general discussion of this choice in the documentation of 'fifinddo'. Preprocessing here can be done in the same \LaTeX\ run as typesetting, though you can avoid incompatabilities with packages needed for typesetting (by inputting them only \emph{after} preprocessing). 'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be preferable to preprocessing with other utilities: When I took over maintenance of 'lineno.sty', I needed hard work to get the 'awk' script running. The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel} 'awk' (I chose a Munich 'nawk' and reworked the script a little). \TeX\ seems to have better fixed functionality than other utilities! %% TODO Paul Isambert's (CTAN recently) 2009/04/08 \subsection{Basics on using 'makedoc'} At least in the long run, using 'makedoc' should not imply commitment to a certain design or to certain \LaTeX\ packages for typesetting listings and documentations. Therefore, 'makedoc.cfg' (currently) contains \emph{local} or \emph{personal choices}, but also \emph{experiments} with future features of 'niceverb'. Especially, (at present) the `packagecode' environment that 'makedoc' `\write's must be chosen. Currently this is the `listing' environment from 'moreverb' with some modifications or extra settings. It may be vital to `\MakeOther' the active characters from 'niceverb' in the setup of `packagecode'. See the \emph{example} in section~\ref{sec:fifinddo}. Finally, each package file to be typeset will need its own \emph{script} of 'makedoc' commands. It should fit into the preamble of the main file for documenting the package (currently %% 2009/04/09 just 5 commands seem to suffice, see the \emph{example} in section~\ref{sec:fifinddo} and section~\ref{sec:script} on typical ``bundling'' \emph{script commands}). As an alternative, you may prefer to have ``content only'' (as much as possible) in the main typesetting file and in its preamble only `\input' a separate script file. Yes, the idea of documenting a package \emph{here} is to have a separate ``driver'' file for typsetting the documentation. It may contain an introduction and a guide for users. The documentation of the package code that has been prepared by the 'makedoc' script will be `\input'. Alternatively, the ``driver file'' could have title etc.\ only, or preamble and a minimal `document' environment only. So there may be many files, which may look confusing, especially as compared with the 'doc' procedure. However, \begin{enumerate} \item ``One file distribution'' still is possible thanks to the `filecontents' environment. \item The 'makedoc' script can create a batch file (fitting the system, maybe using Will Robertson's 'ifplatform', or 'texsys.cfg', or \dots) that removes certain auxiliary files or moves them to a certain directory. \item I find it helpful to have rather little ``contentual'' text in the package file. \item The procedure now runs very smoothly, once the stumbling blocks have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'! 'niceverb' v0.1 was too sloppy with some things, and self-documentation of 'makedoc.sty' was difficult---its parsing and that from 'verbatim' cannot distinguish between markup code and typeset code.} \end{enumerate} \subsection{Examples} The documentations of 'fifinddo' and of 'makedoc' itself are typeset using 'makedoc' (\hspace{1sp}'niceverb.pdf' as well, yet comments remained scarce). 'fifinddo.pdf' documents 'fifinddo.sty', typeset from 'fifinddo.tex', likewise 'makedoc.pdf'. Section~\ref{sec:fifinddo} contains listings of 'makedoc.cfg' and the 'makedoc' script file 'mkfddoc.tex' especially made for 'fifinddo.pdf'. 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input files that were made with 'makedoc.sty'---I have only looked at them when something was wrong (often syntax mistakes in typing). The Wikipedia syntax feature `%% === subsubsection ===' is only used in 'fifinddo.sty' and 'niceverb.sty'. \section{Implementation} \subsection{Preliminaries} Head of file (Legalese): \sloppy \input{makedoc.doc} The previous empty code line is the one \TeX\ insists to add at every end of a file it writes. %% todo TeXbook where? 2009/04/08 \section{Examples: documentation of 'fifinddo'}\label{sec:fifinddo} \subsection{\hspace{1sp}'makedoc.cfg'} 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following configuration file 'makedoc.cfg': \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< %% <- TODO should be 'niceverb' command 2009/04/08 \listinginput[5]{1}{makedoc.cfg} \endgroup \subsection{\hspace{1sp}'mkfddoc.tex'} 'fifinddo.pdf' was typeset with the following 'makedoc' script file 'mkfddoc.tex': \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< \listinginput[5]{1}{mkfddoc.tex} \endgroup \subsection{\hspace{1sp}'mdcorr.cfg'} 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following typographical corrections in 'mdcorr.cfg': \strut\hrule \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< \listinginput[5]{1}{mdcorr.cfg} \endgroup \hrule\strut This code also exemplifies the syntax 'niceverb' provides for writing about \LaTeX\ macros. It is typeset here with 'makedoc.sty' again and then looks thus: \strut\hrule \input{mdcorr.doc} \strut\hrule \end{document} 2009/04/12: more on examples 2009/04/15: exemplification of niceverb.sty by mdcorr.cfg