diff options
author | Karl Berry <karl@freefriends.org> | 2010-03-23 22:55:47 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-03-23 22:55:47 +0000 |
commit | 1245444c38f58a5f2d3cc77bd773a1cf1920ef4d (patch) | |
tree | 2dad97e9d4e96f2e81790e209f23ec1e9fd22307 /Master/texmf-dist/source/latex/nicetext/makedoc.tex | |
parent | 22780f70b0a868b2b458fa5177c8100498b4d2b2 (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.tex | 214 |
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 |