summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nicetext/makedoc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/nicetext/makedoc.tex')
-rw-r--r--Master/texmf-dist/source/latex/nicetext/makedoc.tex214
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