diff options
author | Karl Berry <karl@freefriends.org> | 2011-02-02 01:07:11 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-02-02 01:07:11 +0000 |
commit | eab6d7d5d02b3de8c4e17da89873e9b817f87114 (patch) | |
tree | 589e38cd3139ea199e593196903d1a1d1ebf101a /Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex | |
parent | f9cdf6d0869e9672668bf7e5f523c80aa7ea44b1 (diff) |
nicetext (1feb11)
git-svn-id: svn://tug.org/texlive/trunk@21257 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex | 646 |
1 files changed, 0 insertions, 646 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex deleted file mode 100644 index b6c78135c42..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex +++ /dev/null @@ -1,646 +0,0 @@ -\ProvidesFile{makedoc.tex}[2011/01/25 documenting makedoc.sty] -\RequirePackage{makedoc} -\documentclass{article} -\input{makedoc.cfg} -\usepackage{color} %% 2011/01/25 -\sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21 niceverb!? 2011/01/25 -\makeatletter %% TEST for hyperref compatibility 2010/03/11 -% \def\@testdef #1#2#3{% -% \def\reserved@a{#3}% -% \expandafter \ifx \csname #1@#2\endcsname -% \reserved@a \else \@tempswatrue \fi -% \if@tempswa -% \typeout{^^J*** Type `r' <input> to get around -% \string\label\space issues! ***^^J} -% \errorcontextlines=0 -% \show\reserved@a -% \expandafter \show \csname #1@#2\endcsname -% \fi -% } -% \makeatother -\begin{document} -\title{'makedoc'---Preprocessing documentation by \TeX\thanks{% - This document describes %% 2011/01/25 - version~\textcolor{blue}{\UseVersionOf{makedoc.sty}} - of 'makedoc.sty' as of \UseDateOf{makedoc.sty}.}} -\maketitle -\begin{abstract}\noindent -'makedoc' provides commands for generating \LaTeX\ input from a -package file in order to typeset the latter's documentation -(somewhat similar and opposite to 'docstrip')---with -v0.3 \emph{a single one usually suffices}. -Certain comment marks are removed, listing commands are inserted, -and some (configurable) typographical `txt'$\to$\TeX\ corrections -are applied.---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 the usual number of runs) of the -documentation driver file.---The present approach is meant to be an -\emph{alternative} to the standard 'doc' package and its `\DocInput'. -It 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} -\emph{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 standard \LaTeX\ 'doc' system was not attractive for me -(neither considered helpful). %% clarified 2010/03/13 -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---\emph{I really would like to have -powerful tools for everything depending on nothing but \TeX\slash -\LaTeX!} - -\section{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'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!? -You also cannot use `%' for commenting out code (that you are -pondering---or using for debugging---only). %% clarified 2010/03/13 - -Moreover, 'doc' requires enclosing package code explicitly by -environment commands (behind comment marks). Stephan I. B\"ottcher -with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}' -and Grzegorz Murzynowski in \ctanpkgref{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 - \ctanpkgref{pauldoc} and \ctanpkgref{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 -\ctanpkgref{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! - -A different alternative to \LaTeX's 'doc' system is -Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}' -where the code environments extract package code in typesetting the -documentation. %% added 2010/03/10 - -\section{Styles supported (parsers provided)}\label{sec:styles} -% \section{Styles of commenting '.sty's} -We find different styles of documenting \LaTeX\ packages. -As the main aspects I consider -(i)~\emph{telling code from comments} -and (ii)~\emph{markup in comments}. -(You may find more details on the next matters in the - ``implementation" section.) - -\subsection{Telling code from comments} -\emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX) -probably were named so to mark \emph{``comments"} as opposed -to code $\dots$ great, but actually, in ``daily practice," -they are so handy---and used---for ``commenting out" \emph{code}, -i.e., \emph{managing code versions} in a simple way: -one does not actually want to \emph{delete} code, -one might want to use it another time, maybe for debugging -$\dots$ or to remind of earlier attempts that should not be tried -again $\dots$ - -This is a problem for \emph{high-quality typesetting} of -documentation. \emph{Code} should be typeset about as you see it on -the \emph{screen}---\emph{monospaced}, this allows structuring by -indenting, it is common practice to use a typewriter typeface for -this. Real \emph{comments} should be typeset in \emph{high quality} as -usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden -code"} (``commented-out"). A comment mark starts the line, but -obviously it is not really a comment and rather should be typeset -like code (and otherwise they may break). %% 2010/03/22 -Another problem are comments at the \emph{end} of a -\emph{code} line. Sometimes they are ``real comments" ('gmdoc' -supports this style). But sometimes -this is only another version of ``version management," code -``commented-out." - -I like the style of writing packages described before and use it all -the time. I mark ``real comments" with \emph{two} adjacent comment -marks and an ensuing space to distinguish them clearly from code -commented out. -%% Adapted to v0.4 2010/03/29: -\emph{This style is presently the one supported by \textup{'makedoc'} - as default.} -This way only a line starting with -|%% | is considered a ``real" comment line. The first three -characters are removed, and the rest is typeset in high quality. -Any other lines are typeset verbatim. The 'makedoc' \emph{parser} -doing this has an ``identifier" |PPScomment| (``percent, percent, -space"). Another identifier |comment| is a placeholder for -the comment parser to be used, by default it is an alias for -`PPScomment'. Lines just containing |%%| (without the space) may be -used to suppress empty code lines preceding section titles and for -keeping some visual, relieving space between code and comment lines. - -The style I described previously may be considered ``unprofessional." -The many \LaTeX\ packages documented using the 'doc'\slash'.dtx' -system don't use comment marks for \emph{``commenting-out"}. -Or one may mark code commented out by putting no space between the -percent mark and the code. -With v0.4 of 'makedoc', this style is supported as |PScomment|. -You can directly call this as <main-parser> as described below, -or you can switch to it by -\[`\CopyFDconditionFromTo{PScomment}{comment}'\] - -\subsection{Markup in comments} -Packages using the 'doc'\slash '.dtx' system as well as alternative -highly developed systems mentioned above use (enhanced) usual -\emph{\LaTeX} syntax for markup of comments. Other packages just use -an \emph{ASCII} style \emph{without} any markup. My idea was to -support the latter style by some `txt'$\to$\LaTeX\ functionality. -'makedoc' does this using a file 'mdoccorr.cfg' which is very small -right now. - -I also thought of introducing another sort of ``decent" markup not -needing much more space than the ``ASCII kernel" of the comments. -This is to some extent implemented in 'niceverb.sty'. I thought of the -syntax of editing \textit{Wikipedia} pages; this is partially -implemented in 'wiki.sty' which unfortunately is not yet compatible -with 'niceverb'. - -But 'makedoc' implements one \textit{Wikipedia} feature in a different -way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows: -\begin{eqnarray*} - \endcell\endcell`%% == Section =='\\ - \endcell\endcell`%% === Subsection ==='\\ - \endcell\endcell`%% ==== Subsubsection ====' -\end{eqnarray*} -i.e., you type `== <title> ==' in place of `\section{<title>}' etc. -The parser must replace `====<title3>===' before `===<title2>===' and -the latter before `==<title1>=='. In fact, 'makedoc' provides three -parsers for these situations: -\begin{description} -\cmdboxitem|\SectionLevelThreeParseInput| is the most general parser - offered. If it does not find two strings \lq`===='\rq\ enclosing - \emph{something}, it passes to -\cmdboxitem|\SectionLevelTwoParseInput| which unless finding - two strings `===' enclosing something passes to -\cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment - detector |comment|. -\end{description} - - -\section{Requirements} -'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand' -etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same -directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the -\LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it -should be installed anyway, or you can get its latest version -(v2.3, 2008/06/03?) from CTAN. - -'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file -'mdoccorr.cfg' that should have come along with 'makedoc.sty' and -'fifinddo.sty'. You may need to have a modified copy of it in the -directory of your main `.tex' file `<jobname>.tex' fitting special -needs of your project. - -\section{Using 'makedoc' the simplest way} -In the most simple case, you are preparing documentation for a package -file `<jobname>.sty' only, and you prepare a file `<jobname>.tex' -containing -\[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\] -and `\maketitle' etc.\ about your package.\footnote{With 'niceverb' - and &\title\ after &\begin{document}, you may replace - \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.} -The documentation will be produced by running `<jobname>.tex' with -\LaTeX\ (e.g., \texttt{latex <jobname>.tex}). - -First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble. -There are no package options. - -Second, to typeset the commented implementation from `<jobname>.sty', -include in <jobname>.tex's `document' environment a line -\[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\] -<header-lines> refers to a non-negative integer as follows: -We think the most simple and useful way of typesetting the first lines -of a package file including license and copyrights is ``depicting them -as image," i.e., \textit{verbatim}. We could try to determine the -number of these lines by parsing, but we won't do so soon. Please just -count them and enter the number as <header-lines>---and change it -until you can accept the outcome. - -\section{Steps of advanced usage} -\subsection{Different main parsers (second mandatory argument)} - -`\MakeInputJobDoc''s mandatory syntax actually is -\[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\] -<main-parser> refers to the parsing macro that is applied to each -input line whose number is greater than <header-lines>. -Examples for <main-parser> are named in section~\ref{sec:styles} above. - %% TODO above/below macro 2010/03/15 -`\SectionLevelThreeParseInput' is just the most general one. -For \emph{efficiency} (!? or also to avoid problems?) you may -replace `Three' by `Two' or by `One', if the `====' or the `===' -feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia} -sectioning" feature is not used at all, use -\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\] ----provided you want to adopt the \lq`%% '\rq\ style of marking -comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style -instead, use -\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\] - -\subsection{Different extensions (optional arguments)} -If your package to be documented is a \emph{class} `<jobname>.cls', -a local configuration file `<jobname>.cfg' or something -else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg', -use -\[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\] -Moreover, `\MakeInputJobDoc' writes an intermediate file -`<jobname>.doc' and then `\input's it. If you do not like `doc' -as extension for the written file name (maybe you use -`<jobname>.doc' for something different already), preferring extension -<ext-out>, use -\[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\] -Yes, you must state <ext-in> then as well, I can't help $\dots$ - -If even <jobname> is wrong in your view, see next step $\dots$ - -\subsection{Commands modifying &\MakeInputJobDoc's behaviour} -\label{sec:modimake} -Already <jobname> may not be what you want. E.g., you may want -to collect documentations of some other files <job-1>, <job-2>, -$\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc' -with -\[`\renewcommand*{\mdJobName}{<job-1>}'\] -etc.\ (please reason yourself about additional requirements \dots) -As a matter of fact, `\MakeInputJobDoc' reads -\[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad} - `\mdJobName.<ext-out>'\] -Stated another way, <jobname> above referred to |\mdJobName|. - -`\MakeInputJobInput' moreover (by default) produces one dot -per input line processed on screen to show progress. -The reason is that `makedoc' issues the command -|\ProcessLineMessage{\message{.}}|. -Already this trivial thing seems to slow down processing considerably -(nowadays). `\MakeInputJobInput' will run faster if preceded by -\[|\ProcessLineMessage{}|\] -which will suppress any message about processing. -However, the message may be helpful in trouble-shooting. - -\subsection{Separating preprocessing from typesetting} - %% extended 2010/03/16 -To some surprise, I observe that `\MakeInputJobDoc' \emph{works.} -This is quite a new discovery of mine (2010/03/13); -before I thought that, for safety, preprocessing should happen -inside a local group \emph{preceding} `\documentclass'. -|\MakeJobDoc| works like `\MakeInputJobDoc' described above, -yet it just \emph{preprocesses} the package to be documented, -waiting for an -\[`\input{<jobname>.<ext-out>}'\] -in the `document' environment to \emph{typeset} the documentation. -So 'makedoc.tex' once had in its preamble -% \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\] -% at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later. -\begin{eqnarray*}\endcell\endcell - `{\RequirePackage{makedoc}'\cr \endcell\endcell - ` \ProcessLineMessage{}'\cr \endcell\endcell - ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr - \endcell\endcell - `\documentclass{article}' -\end{eqnarray*} -I did experience some truth in my earlier safety policy: -With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used -in the `document' environment. `\MakeInputJobDoc' in fact does some -'niceverb' switching (provided 'niceverb' has been loaded) -when making use of `\MakeJobDoc'. - %% <- verbose to improve line breaks 2010/03/16 - -Thinking of this ``safety" approach, especially grouping (`{\code}'), -I had not much cared for compatibility with other packages -in choosing 'makedoc' macro names. - -\subsection{Other 'makedoc' (and 'fifindo') script commands} -The next script commands may be considered of a lower level than -`\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter -commands. We also list commands from 'fifinddo.sty' that may be useful -or, indeed, are needed for preparing package documentations. -This may result in ideas on how do use the script commands for -different purposes than for preparing package documentations---e.g., -apply `txt'$\to$\TeX\ preprocessing to arbitrary text files. - -\subsubsection{Choosing parameter values for next preprocessing run} - -This actually continues section~\ref{sec:modimake}. - -\begin{description} -\cmdboxitem|\ResultFile{<output>}| (from 'fifinddo') - determines (and opens through the \TeX\ primitive `\openout') - the file <output> which will contain the result of - preprocessing the package file. -\cmdboxitem|\LaTeXresultFile{<output>}|---see next section. -\cmdboxitem|\Headerlines{<number>}| determines the <number> of lines - starting the input file to be copied \emph{verbatim} - (the first mandatory argument of `\MakeJobDoc'). -\cmdboxitem|\MainDocParser{<parser>}| determines the <parser> - as in the \emph{second} mandatory argument of `\MakeJobDoc'. -\end{description} - -We are now describing some parameters which rather must be switched -``manually" instead of being modifiable by comfortable 'makedoc' -script commands. - -With the \emph{``Wikipedia sectioning"} feature, you may change the outcome -regarding levels. Assume, e.g., the package file has titles along the -scheme `== <title> ==' only, but these should become -\emph{subsections} of the ``implementation" section of the -corresponding `.tex' file. Then -\[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\] --- see the implementation of the sectioning feature for details. - -There is a command -\[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad} - |\OnEmptyInputLine|\] -which is modified by the former. However, I cannot say much about them -right now, I think they just were a difficult matter that I soon -decided no longer to think about for a while (cf.\ the -implementation). About the same holds for the hook |\EveryComment|. - -The `txt'$\to$\TeX\ functionality is implemented through a hook -\[|\MakeDocCorrectHook{<characters>}|\] -'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e., -it won't change <characters>. 'mdoccorr.cfg' should redefine it so it -really ``corrects" <characters>. You might try other definitions of -`\MakeDocCorrectHook' for different ``correcting" functions. -It should be \emph{noted} that (currently) -`\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty' -provides setup for (expandable) chains of expandable replacements. -The ``Wikipedia" sectioning feature moreover uses expandable -trimming (single) surrounding spaces, this might be provided in a more -general way.\footnote{%% TODO 2010/03/16 - The \ctanpkgref{trimspaces} package - has been a \emph{model} for this feature here. It cannot be used - directly here because it reads blank spaces as \TeX\ characters with - category code 10 while 'makedoc' reads blank spaces as ``other" - characters (category code 12) in order to \emph{keep} all blank spaces.} - -\subsubsection{``Manual" insertions to the output file} -\begin{description} -\cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes - <balanced> to <output> according to the earlier command - `\ResultFile{<output>}'. -\cmdboxitem|\WriteProvides| (from 'fifindo') writes a - `\ProvidesFile' line into <output> that declares the file - to be generated by 'fifindo'. -\cmdboxitem|\LaTeXresultFile{<output>}| issues - `\ResultFile{<output>}' and then writes a - `\ProvidesFile' line into <output> that declares the file - to be generated by 'makedoc'. -\end{description} - -\subsubsection{Processing input and closing output} -\begin{description} -\cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em - reads 'mdoccorr.cfg' - (for `\MakeDocCorrectHook', see above), - %% removed \LaTeXresult... 2010/03/17 - copies <number> according to `\HeaderLines' (see above) - from <input> into <output> (according to `\ResultFile'), - then processes the remaining lines of <input> according - to `\MainDocParser' (writing several things to <output>). - `\MakeDoc' invokes{\sloppy\par} -\cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}| - (from 'fifindo') reads <input> line by line---each one stored as - macro |\fdInputLine| and applies <loop-body> to it. - \TeX's ``special" character codes (of characters listed in - macro `\dospecials') are replaced by 12 (``other") by - default---see the 'fifinddo' documentation. -\cmdboxitem|\CloseResultFile| (from 'fifinddo') - \hskip 0pt plus 1em - \emph{closes} - <output> (using \TeX's primitive `\closeout'). -\cmdboxitem|\MakeCloseDoc{<input>}| issues - `\MakeDoc{<input>}\CloseResultFile'. -\end{description} -% -Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing -additional <input> files writing into the same <output>. Or maybe you -want to add some additional lines manually to <output> using -`\WriteResult'. - -%% removed 2010/03/09: -% 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 needs its own little -% \emph{script} of 'makedoc' commands. -% With v0.3, one or two of these should suffice. - -% 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}). -% The script commands are described -% in the \dqtd{File handling} section of 'fifinddo.pdf' and in the -% present section~\ref{sec:script} (and \ref{sec:emptylines}). -% 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. -%% removed 2010/03/10: -% 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} - -\section{Examples}%%% (documentation of 'mdoccorr.cfg')} -%% moved here 2010/03/23 -\subsection{'nicetext', especially 'mdoccorr.cfg'} -The documentations of 'fifinddo', 'makedoc', and 'niceverb' -themselves are typeset using 'makedoc'. -'fifinddo.pdf' documents 'fifinddo.sty', typeset -from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'. -% Section~\ref{sec:fifinddo} contains a listing 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 -\begin{quote} - `%% === subsection ===' -\end{quote} -is used in 'fifinddo.sty' and 'niceverb.sty' only. - -Along with 'makedoc' should come files `makedoc.tpl'---a template -'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue -on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?). -With other definitions of `\MakeDocCorrectHook'---see below---you can -use this dialogue for arbitrary replacement jobs (as an application of -'fifinddo' rather than 'makedoc').{\sloppy\par} - -'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following -typographical corrections in 'mdoccorr.cfg' that defines -`\MakeDocCorrectHook': -\strut\hrule -\begingroup - \hfuzz=\textwidth \advance \hfuzz by 28pt - \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< - \listinginput[5]{1}{mdoccorr.cfg} -\endgroup -\hrule\noindent\strut -This code also exemplifies the syntax 'niceverb' provides for writing -about \LaTeX\ macros. It is typeset here with 'makedoc.sty' -and then looks thus: -% \sloppy %% 2010/03/29 -\strut\hrule -\renewcommand*{\mdJobName}{mdoccorr} -\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}} -\hrule \noindent\strut -And this is the content of the intermediate generated file: -\hrule -\begingroup - \hfuzz=\textwidth \advance \hfuzz by 28pt - \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< - \listinginput[5]{1}{mdoccorr.doc} -\endgroup -\hrule -% \fussy %% 2010/03/29 - -\subsection{Packages from other authors} -`substr.tex' should typeset a nicely formatted documentation -of Harald Har\-der's 'substr.sty', see my own result `substr.pdf'. -'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style -that 'nicetext' has used itself. - -`arseneau.tex' should typeset nicely formatted documentations -of a few packages by Donald Arseneau, see my own result `arseneau.pdf'. -This demonstrates the usual \lq`% '\rq\ commenting style -that 'makedoc' supports with v0.4. - -\pagebreak %% 2010/03/29 -\ResetCodeLineNumbers %% 2010/03/29 -\section{Implementation} -\subsection{Preliminaries} -Head of file (Legalese): -\sloppy -\renewcommand*{\mdJobName}{makedoc} -\ProcessLineMessage{} -\MakeInputJobDoc{22}{\ProcessInputWith{comment}} -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 - -%% removed (TODO) 2010/03/15: -% \section{Examples: documentation of 'fifinddo'} -% \label{sec:fifinddo} -%% removed 2010/03/10: -% \subsection{'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 -% -%% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15 -% \subsection{'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 -% -% -\end{document} - -2009/04/12 more on examples -2009/04/15 exemplification of niceverb.sty by mdcorr.cfg -2009/04/21 === subsubsection -> === subsection -2010/03/08 moved `only' for better line break -2010/03/09 removed something from "Basics" -2010/03/10 more changes in "Basics", pdf stuff to makedoc.cfg, - makedoc.cfg no longer example; CodeDoc -2010/03/11 use \MakeCloseDoc; \hfuzz with \listinginput; - tracing spurious `Label(s) may have changed' -2010/03/12 tests for hyperref compatibility completed -2010/03/13 use \MakeInputJobDoc; clarified ...; ctan.org/pkg -2010/03/14 updated ``Examples" and abstract; \href...easylatex -2010/03/15 ``styles supported"; abstract: txt->TeX; usage -2010/03/16 more on usage; mdcorr -> mdoccorr -2010/03/17 corr. mistake with \MakeDoc -2010/03/19 '' -> " -2010/03/20 for niceverb v0.31 -2010/03/21 for niceverb v0.32 -2010/03/22 "may break" -2010/03/23 \noindent in example, moved, added mdoccorr.doc, - makedoc.tpl -2010/03/29 \ResetCodeLineNumbers, - examples and explanations for v0.4 -2010/03/30 \listfiles test -2010/11/27 \ProvidesFile for myfilist -2011/01/25 \thanks with readprov.sty |