summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/nicetext/makedoc.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-03-23 22:55:47 +0000
committerKarl Berry <karl@freefriends.org>2010-03-23 22:55:47 +0000
commit1245444c38f58a5f2d3cc77bd773a1cf1920ef4d (patch)
tree2dad97e9d4e96f2e81790e209f23ec1e9fd22307 /Master/texmf-dist/source/latex/nicetext/makedoc.tex
parent22780f70b0a868b2b458fa5177c8100498b4d2b2 (diff)
nicetext 0.3 (23mar10)
git-svn-id: svn://tug.org/texlive/trunk@17537 c570f23f-e606-0410-a88d-b1316a301751
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, 0 insertions, 214 deletions
diff --git a/Master/texmf-dist/source/latex/nicetext/makedoc.tex b/Master/texmf-dist/source/latex/nicetext/makedoc.tex
deleted file mode 100644
index 6808f391b50..00000000000
--- a/Master/texmf-dist/source/latex/nicetext/makedoc.tex
+++ /dev/null
@@ -1,214 +0,0 @@
-\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