diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/nicetext/makedoc.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/nicetext/makedoc.tex | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/nicetext/makedoc.tex b/Master/texmf-dist/source/latex/nicetext/makedoc.tex new file mode 100644 index 00000000000..6808f391b50 --- /dev/null +++ b/Master/texmf-dist/source/latex/nicetext/makedoc.tex @@ -0,0 +1,214 @@ +\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 |