diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/nicetext/use/makedoc.sty |
Initial commit
Diffstat (limited to 'macros/latex/contrib/nicetext/use/makedoc.sty')
-rw-r--r-- | macros/latex/contrib/nicetext/use/makedoc.sty | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/macros/latex/contrib/nicetext/use/makedoc.sty b/macros/latex/contrib/nicetext/use/makedoc.sty new file mode 100644 index 0000000000..2c52945662 --- /dev/null +++ b/macros/latex/contrib/nicetext/use/makedoc.sty @@ -0,0 +1,642 @@ +%% Macro package `makedoc.sty' for LaTeX2e, +%% copyright (C) 2009-2012 Uwe L\"uck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% for preparing documentations from packages. + +\def\fileversion{0.52} \def\filedate{2012/08/28} + +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3a of the License, or any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% We did our best to help you, but there is NO WARRANTY. +%% +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +% 1994/12/01: \newcommand* etc. +\ProvidesPackage{makedoc}[\filedate\space v\fileversion\space + TeX input from *.sty (UL)] +%% +%% |\PackageCodeTrue| and |\PackageCodeFalse| set `\ifPackageCode' +%% globally, so redefinition of `~' (playing a key role in 'fifinddo') +%% may be kept local. Note the capital `T' and `F'! +\newcommand*{\PackageCodeTrue} {\global\let\ifPackageCode\iftrue} +\newcommand*{\PackageCodeFalse}{\global\let\ifPackageCode\iffalse} +%% |\ifPackageCode| is used to determine whether a listing environment +%% must be `\beg'un or `\end'ed. You may also want to suppress empty +%% code lines, while empty lines should issue a `\par' break in +%% ``comment" mode. +%% +%% Since `\newif' is not used, `\ifPackageCode' must be declared +%% explicitly. Declaration of new `\if's must be early in case +%% they occur in code that is skipped by another `\if'\dots +%% [TODO!? cf. others 2010/03/15] +\PackageCodeFalse +%% +%% 'makedoc' is an extension of 'fifinddo' on which it depends. +\RequirePackage{fifinddo}[2012/08/27] +%% 'fifinddo' v0.6 loads 'stacklet.sty', so we can use %% 2012/08/28 +%% the underscore as a ``private letter" by the following: +\PushCatMakeLetter\_ %% 2012/08/28 +%% +%% \subsection{&\MakeDocCorrectHook\ (\dqtd{`txt2TeX'})} +%% \label{sec:mdoccorr} %% 2012/03/17 +%% |\MakeDocCorrectHook| is predefined to leave its argument without +%% the enclosing braces, otherwise unchanged: +\let\MakeDocCorrectHook\@firstofone +%% Less efficiently, the same could have been set up as +% \newcommand*{\MakeDocCorrectHook}[1]{\ProcessStringWith{#1}{LEAVE}} +%% according to 'fifinddo'. +%% +%% It may be \emph{redefined} in a \emph{configuration} file like +%% 'mdoccorr.cfg' %% was makedoc.cfg 2011/08/22 +%% or the 'makedoc' script file applying to a single +%% package file in order to, e.g., converting plain text to \TeX\ input +%% conforming to typographical conventions, making `$\dots$' from +%% \qtd{&.&.&.}, %% dots should not be replaced! +%% e.g. +%% Replace `LEAVE' in the previous suggestion by an identifier +%% whose job you have defined before, and use `\renewcommand' +%% in place of `\newcommand'. +%% See an example in 'mdoccorr.cfg'. %% fixed 2011/08/22 +%% +%% You can \emph{test} your own `\MakeDocCorrectHook' by +%% \[`\typeout{\MakeDocCorrectHook{<test-string>}}'\] +%% ... provided (sometimes) `\MakeOther\ ' ... +%% You can even change it using `\IfInputLine' from 'fifinddo' in the +%% midst of preprocessing a package documentation. +%% +%% \subsection{Distinguishing package code from comments}%% <- wiki style breaks in self-doc. +%% \label{sec:distinguish} +%% Use of comment marks is a matter of personal style. Only lines +%% starting with the sequence |%% | %% box 2010/03/16 +%% are typeset in \TeX\ quality +%% under the present release. Lines just containing |%%| +%% (without the space) are used to suppress empty code lines +%% preceding section titles (while keeping some visual space +%% in the package file). There is a preferable way to do this, +%% however not in the present release ... +%% +%% The parsing macros must be set up reading `%' and ` ' as ``other" +%% characters. Using the optional arguments for this creates +%% difficulties that can be somewhat avoided by redefining +%% |\PatternCodes|. +\SetPatternCodes{\MakeOther\%\MakeOther\ }%% 2010/03/30 +%% +%% The next line sets the ``sandbox" for the detecting macro, as it +%% is coined in the documentation of 'fifinddo', with ``identifier" +%% |PPScomment|. +\MakeSetupSubstringCondition{PPScomment}{%% }{{#1}} +%% The last argument stores the expanded input line for reference by +%% macros called. The next line is a test whether the setup works. +% \expandafter \show \csname \setup_substr_cond PPScomment\endcsname +%% Here comes the definition of the corresponding testing macro. +%% #3 is the expanded input line from above. The `\If'\dots commands, +%% `\fdInputLine', `\fdInputLine', and `\RemoveDummyPatternArg' +%% are from 'fifinddo'. +\MakeSubstringConditional{PPScomment}{%% }#3{%% #3 entire test string + \DecideCommentCode{#1}{#2}{#3}\PPstring} +%% |\DecideCommentCode{#1}{#2}{#3}{#4}| is shared with the parser +%% for the \lq`% '\rq\ commenting style. %% new 2010/03/28 +\newcommand*{\DecideCommentCode}[4]{% + \IfFDinputEmpty{\OnEmptyInputLine}{% +%% The empty line test comes early to offer control with +%% `\OnEmptyInputLine' both in code and comment mode. +%% Maybe it should always? %% TODO 2009/04/13 + \IfFDempty{#1}% + {\TreatAsComment{% + \RemoveDummyPatternArg\MakeDocCorrectHook{#2}}}% + {\ifx\fdInputLine#4% + \ifPackageCode\else \WriteResult{}\fi% +%% ... allows paragraphs in comments. + \else \TreatAsCode{#3}\fi}}} +%% Job |PScomment| deals with the |% | commenting style: +\MakeSetupSubstringCondition{PScomment}{% }{{#1}} +\MakeSubstringConditional{PScomment}{% }#3{% + \DecideCommentCode{#1}{#2}{#3}\PercentChar} +%% `\PercentChar' is from 'fifinddo'.---Return to `\fdPatternCodes': +\ResetPatternCodes %% 2010/03/30 +%% +%% |\PPstring| stores the line suppressing empty code lines with +%% the \lq`%% '\rq\ style: +\newcommand*{\PPstring}{} \xdef\PPstring{\PercentChar\PercentChar} +%% +%% |comment| will be a ``generic" identifier to call a comment line +%% detector. It might be predefined to issue an ``undefined" error; +%% however this release predefines it to behave like `PPScomment': +\CopyFDconditionFromTo{PPScomment}{comment} +%% This means that the \lq`%% '\rq\ commenting style is assumed by +%% default. \[`\CopyFDconditionFromTo{PScomment}{comment}'\] +%% switches to the \lq`% '\rq\ style (with the {\it Wikipedia} +%% sectioning parser). +%% Or just choose \[`\ProcessInputWith{PScomment}'\] as <main-parser> +%% (without the {\it Wikipedia} feature). +%% +%% Alternative still to be considered: +% \@namedef{\setup_substr_cond comment}{% +% \PackageError{makedoc}{Job `comment' not defined}% +% {Use \string\CopyFDconditionFromTo{comment}}} +%% +%% \subsection{Choice of package code environment} +%% With v0.3, we adopt the solution for typesetting package code +%% that was implemented in the former 'makedoc.cfg'. So we rely +%% on the `listing' and `listingcont' environments of the +%% 'moreverb' package. +%% +%% The earlier idea was that 'makedoc.sty' uses an undefined \LaTeX\ +%% environment `packagecode' that will be defined in 'makedoc.cfg'. +%% An accompanying idea was that 'makedoc' works before the +%% `\documentclass' line inside a group, while 'makedoc.cfg' +%% is read \emph{after} the `\documentclass' line. +%% +%% We now want to simplify things. We replace +%% \[`packagecode' \mbox{\quad by\quad } `mdPackageCode'\] +%% and define the new environment globally here. 'moreverb' +%% and our choice for `\listinglabel' are +%% called at `\begin{document}'---outside the possible group. +\gdef\mdPackageCode{% +% \small +%% 2011/01/19, v0.41: `\small' has affected the `\baselineskip' +%% above the code. So a `\par' must be executed before `\small'. +%% But we don't want to have the extra `\partopsep'---forced ... + \mdStartPackageCode %% 2011/01/19 v0.41 +%% From the next occurrence of the environment onwards, +%% `listing' must be replaced by `listingcont'. + \gdef\mdPackageCode{\mdStartPackageCode %% 2011/01/19 v0.41 + \listingcont}% + \listing{1}} +\gdef\mdStartPackageCode{% %% 2011/01/19 v0.41 +%% Smart `\small'---we might once allow `\partopsep' +%% in `vmode'---not this time: + \par \small \partopsep\z@skip +%% Get rid of 'niceverb' stuff: + % \MakeOther\`\MakeOther\'%% probably OK with moreverb + \MakeOther\<\MakeOther\|% +} +\gdef\endmdPackageCode{% + \endlisting + \global\let\endmdPackageCode\endlistingcont} +\AtBeginDocument{% + \RequirePackage{moreverb}% + \renewcommand*{\listinglabel}[1]{% + \llap{\scriptsize\rmfamily\the#1}\hskip\listingoffset\relax}% +} +%% |\ResetCodeLineNumbers| may be needed to \emph{reset} +%% 'moreverb''s (global!) code line number settings +%% (\emph{first} line number + {\it modulo} for displaying) +%% when combining documentations of \emph{more} than one package +%% with the present solution for implementing `mdPackageCode'. +%% %% 2010/12/20, rm. 2010/12/21: +%% % (With v0.41, the definition is global, so it can be used +%% % outside a group in a `.tex' preamble that does the preprocessing.) +\@ifdefinable\ResetCodeLineNumbers{%% global as above, v0.41 + \gdef\ResetCodeLineNumbers{% + \global\listing@line\@ne \gdef\listing@step{\@ne}}} +%% +%% \subsection{Dealing with comments} +%% |\TreatAsComment{<text>}| writes <text> to the documentation +%% file. If we had ``package code" (were in ``code mode") so far, +%% the listing environment is ended first. +\newcommand*{\TreatAsComment}[1]{% + \ifPackageCode + \WriteResult{\string\end{mdPackageCode\@empty}}% +%% The `\@empty' here is a lazy trick to save self-documentation +%% fighting 'verbatim''s ``highlight" of finding ends of listings +%% (to be improved). %% TODO 2010/03/09 +%% +%% We always use `\string' to prevent macro expansion in `\write'ing +%% in place of \LaTeX's `\protect', +%% as long as 'fifinddo' simply uses the primitive `\write' in place +%% of \LaTeX's `\proteced@write' ... %% todo 2009/04/08 + \PackageCodeFalse + \EveryComment +% \_empty_code_lines_false + \fi + \WriteResult{#1}} +%% Here, |\EveryComment| is a macro hook for inserting material that should +%% not appear in a listing environment, I had tried this %% 2010/03/18 +%% successfully: +%% \begin{verbatim} +%% \gdef\EveryComment{% +%% \global\let\EveryComment\relax +%% \WriteResult{\string\AutoCmdVerbSyntax}} +%% \end{verbatim} +%% Initialized: +\global\let\EveryComment\relax %% should be changed globally. +%% +%% \subsection{Sectioning} +%% \label{sec:secparsers} +%% We provide a facility from 'wiki.sty' that imitates the sectioning +%% syntax used in editing \emph{Wikipedia} pages, in a different +%% implementation (better compatibility) and in a more general way. +%% On Wikipedia, `== Definition ==' works similar as +%% `\section{Definition}' does with \LaTeX. With the present +%% implementation, you can type, e.g., +%% % \[`%%%%%%%%%%%%%%%%%%%%%% == Definition == %%%%%%%%%%%%%%%%%%%%%%'\] +%% $$`%%%%%%%%%%%%%%%%%%%%%% == Definition == %%%%%%%%%%%%%%%%%%%%%%'$$ +%% to get a similar result. The number of `%' characters doesn't +%% matter, and there can be other stuff, however: additional `=' +%% symbols may harm. Three sectioning levels are supported, through +%% `==<text>==', `===<text>===', and `====<text>====' (deepest). +%% +%% There are three detector macros made for programmers. +%% The most general one is +%% In the following definitions, there is a single tilde to prevent +%% `=' symbols being gobbled by the test (realized by accident). +%% %% 2009/04/13 +%% \par\noindent %% 2010/03/11 +%% |\SectionLevelThreeParseInput|: +\newcommand*{\SectionLevelThreeParseInput}{% + \expandafter \test_sec_level_iii \fdInputLine ~========&} +%% |\SectionLevelTwoParseInput| +\newcommand*{\SectionLevelTwoParseInput}{% + \expandafter \test_sec_level_ii \fdInputLine ~======&} +%% and |\SectionLevelOneParseInput| +\newcommand*{\SectionLevelOneParseInput}{% + \expandafter \test_sec_level_i \fdInputLine ~====&} +%% allow skipping deeper levels for efficiency. +%% % TODO in fifinddo: setup for 2 strings in 1 line 2009/04/13 +%% +%% In the terminology of the 'fifinddo' documentation, the previous +%% three commands are ``sandbox builders." The following three +%% commands are the corresponding ``substring conditionals." +%% However, 'fifinddo' so far %% todo 2009/04/08 +%% only deals with \emph{single} substrings, while here we are +%% dealing with \emph{pairs} of substrings. We are not using +%% general setup macros, but define the parsing macros ``manually," +%% as it is typical in many other macros in 'latex.ltx' and other +%% \LaTeX\ packages. You can fool our macros easily, there is +%% no syntax check. %% todo 2009/04/08 +\def\test_sec_level_iii#1====#2====#3&{% + \IfFDempty{#2}% + {\test_sec_level_ii #1======&}% + {\WriteSection\mdSectionLevelThree{#2}}} +\def\test_sec_level_ii#1===#2===#3&{% + \IfFDempty{#2}% + {\test_sec_level_i #1====&}% + {\WriteSection\mdSectionLevelTwo{#2}}} +\def\test_sec_level_i#1==#2==#3&{% + \IfFDempty{#2}% + {\RemoveTildeArg \ProcessStringWith{#1}{comment}}% + {\WriteSection\mdSectionLevelOne{#2}}} +%% `\ProcessStringWith' here passes the expanded `\fdInputLine' +%% to the general comment detector. +%% +%% |\WriteSection{<command>}{<text>}| replaces an input line +%% with a line \[`<command>{<text>}'\] +%% in the documentation file and switches into ``comment mode." +%% One possible space between `=' and the beginning of <text> +%% and one possible space between the end of <text> and `=' +%% are removed. +%% The method of dealing with surrounding blank +%% spaces is new with v0.3, moreover we now rely on a new method in +%% 'niceverb.sty' v0.3 to support its single right quote feature in +%% section titles.\footnote{&\ignorespaces\ and &\unskip\ used +%% previously do not work in PDF bookmarks.} +\newcommand*{\WriteSection}[2]{% + \TreatAsComment{^^J#1{\trim_correct{#2}}^^J}} +%% Trimming ``other" spaces is a little more clumsy than +%% what the 'trimspaces' package does whose code is by +%% Morten H\o gholm. It still has inspired the following. +\begingroup \MakeOther\ %% CARE! we must not indent ... +\long\gdef\trim_correct#1{\trim_fosp$#1$ $} +\long\gdef\trim_fosp#1$ {% +\IfFDempty{#1}{\trim_losp$}{\trim_losp#1$ }} +%% So we have a string \lq`\trim_losp$<text>$ $'\rq. +\long\gdef\trim_losp$#1 ${\tidy_sp_trim#1$} +%% So we have a string \lq`\tidy_sp_trim<text>$ $'\rq +%% or \lq`\tidy_sp_trim<text>$$'\rq. +\long\gdef\tidy_sp_trim#1$#2${\MakeDocCorrectHook{#1}} +\endgroup +%% We insert `\section' using |\mdSectionLevelOne| etc.\ +%% which the programmer can redefine, e.g., when the +%% documentation is part of a `\section' (or even deeper) +%% according to the ``documentation driver" file. +\newcommand*\mdSectionLevelOne {\string\section} +\newcommand*\mdSectionLevelTwo {\string\subsection} +\newcommand*\mdSectionLevelThree{\string\subsubsection} +%% +%% This sectioning feature is not used in (the documentation) of +%% 'makedoc.sty'---\emph{definitions} of the parsing macros fool +%% the same macros ... +%% +%% \subsection{Commented code} +%% |\TreatAsCode{<text>}| is the opposite to `\TreatAsComment{<text>}': +\newcommand*{\TreatAsCode}[1]{% + \ifPackageCode +% \_empty_code_lines_true + \else + \WriteResult{\string\begin{mdPackageCode}}% + \PackageCodeTrue + \fi + \WriteResult{#1}% +% \WriteResult{\maybe_result_empty_line #1}% +% \let\maybe_result_empty_line\empty +} +%% +%% \subsection{Dealing with empty input lines} %% TODO use!? 2010/03/09 +%% \label{sec:emptylines} +%% |\OnEmptyInputLine| is a default setting (or hook) for what to do +%% with empty lines in the input file. The default is to insert an +%% empty line in the output file: +\newcommand*{\OnEmptyInputLine}{\WriteResult{}} +%% |\NoEmptyCodeLines| changes the setting to suppressing empty code +%% lines, while in ``comment mode" an empty input line \emph{does} +%% insert an empty line, for starting a new paragraph: +\newcommand*{\NoEmptyCodeLines}{%% suppress empty code lines + \renewcommand*{\OnEmptyInputLine}{% + \ifPackageCode \else \WriteResult{}\fi}} +%% There is a better policy---didn't work so far ... +%% +%% \subsection{Bundling typical things: script commands} +%% \label{sec:script} +%% Practical experience suggested the following shorthands, +%% combining commands from 'makedoc' and 'fifinddo'. +%% +%% \subsubsection{Output file and &\filelist\ entry} +%% |\LaTeXresultFile{<output>}| chooses <output> as name +%% for the output file and saves you the extra line for inserting +%% the `\ProvidesFile' line as with 'fifinddo''s +%% `\WriteProvides'---however, it differs, actually it is 'makedoc' +%% that wants to be mentioned with `\ProvidesFile' ... +%% %% (otherwise copied from 'fifinddo') ... +\newcommand*{\LaTeXresultFile}[1]{% + \ResultFile{#1}%%% \WriteProvides} + \WriteResult{% + \string\ProvidesFile{\result_file_name}% + [\the\year/\two@digits\month/\two@digits\day\space + automatically generated with makedoc.sty]}}% +%% \subsubsection{Choose input file and run!} +%% |\MakeDoc{<input>}| preprocesses <input> to render input for +%% \LaTeX, considering what is typical for a \LaTeX\ package as the +%% <input> one here. It reads 'mdoccorr.cfg' (Sec.~\ref{sec:mdoccorr}) +%% automatically. +%% % [`input{mdoccorr.cfg}'] added for what `makedoc.tex' says about it. +%% % See `\make_job_doc' for TODOs about it. +%% % Now also wondering: \ (i)~there are other ways to get the +%% % correcting hook, so why forcing this here? \ +%% % (ii)~different correcting hooks for different input files?---% +%% % In case of a ``header" (see below) we change into ``code mode": +%% |\MakeDoc*{<input>}| \emph{avoids} inputting 'mdoccorr.cfg' +%% (e.g., for allowing replacements specific for the single package). +%% All similar commands (including those invoking `\MakeDoc') +%% get this ``my way" feature as of v0.5: +\newif\if_makedoc_autocorr_ +\_makedoc_autocorr_true %% 2012/04/03 +\newcommand*{\makedoc_maybe_autocorr}{% + \if_makedoc_autocorr_ \input{mdoccorr.cfg}% + \else \_makedoc_autocorr_true \fi} +%% <- TODO warning if one from `TEXMF/' used inadvertently!? +%% avoid reading twice!? %% 2010/03/11 +%% % or read it from 'makedoc' already? %% 2010/03/13 +%% +%% |\makedoc_star<next-cmd>| abbreviates star version definitions: +\newcommand*{\makedoc_star}[1]{% + \@ifstar{\_makedoc_autocorr_false#1}#1} +\newcommand*{\MakeDoc}{\makedoc_star\make_doc_arg} +\newcommand*{\make_doc_arg}[1]{% + \makedoc_maybe_autocorr + \ifnum\header_lines>\z@ + \WriteResult{\string\begin{mdPackageCode}}% + \PackageCodeTrue %% TODO both lines makedoc command!? + %% 2009/04/08 + \else \PackageCodeFalse \fi +%% The loop follows. There is a placeholder `\makedoc_line_body' +%% that is predefined below and can be changed while processing the +%% <input> file. + \ProcessFileWith{#1}{% + \CountInputLines %% stepping line counter is standard + \makedoc_line_body + \process_line_message}% +%% Currently the ``VERSION HISTORY" or, more generally, +%% a final part of the <input> file is typeset verbatim +%% (for ``tabbing" in the version history), +%% so we must leave ``code mode" finally: + \ifPackageCode + \WriteResult{\string\end{mdPackageCode\@empty}}%% self-doc-trick + \PackageCodeFalse %% TODO both lines makedoc command!? 2009/04/08 + \fi +%% When the <input> file has been processed, certain default settings +%% might be restored---in case another <input> file is processed for the +%% same documentation document: +% \HeaderLines{0}% +% \MainDocParser{\SectionLevelThreeParseInput}%% TODO!? 2009/04/08 +} +%% |\MakeCloseDoc{<input>}| %% 2010/03/11 +%% is a kind of shorthand for +%% \[`\MakeDoc{<input>}\CloseResultFile'\] %% was MakeClose 2011/10/12 +%% where `\CloseResultFile' is from 'fifinddo'. +%% The star version \[|\MakeCloseDoc*{<input>}|\] %% 2012/03/18 +%% \emph{avoids} reading 'mdoccorr.cfg': +\newcommand*{\MakeCloseDoc} {\makedoc_star\make_close_doc} +\newcommand*{\make_close_doc}[1]{\MakeDoc{#1}\CloseResultFile} +%% Reimplementation using 'fifinddo' v0.5 failed 2011/11/19: +% \newcommand*{\MakeCloseDoc}{\FinalInputFiletrue\MakeDoc} +%% `\MakeDoc' and `\MakeCloseDoc' actually \emph{process} +%% the <input> file, +%% depending on certain \emph{parameters} some of which are set +%% by the commands described next. +%% +%% \subsubsection{Combining input and output} +%% \[|\MakeSingleDoc[<out-ext>]{<in-output>.<in-ext>}|\] %% 2011/11/05 +%% generates `<in-output>.<out-ext>' from `<in-output>.<in-ext>', +%% using settings like `\MakeDoc'. The default for <out-ext> is `doc'. +%% `\MakeSingleDoc' combines `\LaTeXresultFile' +%% and `\MakeCloseDoc' with appropriate arguments. +%% The star version %% 2012/03/18 +%% \[|\MakeSingleDoc*[<out-ext>]{<in-output>.<in-ext>}|\] +%% \emph{avoids} reading 'mdoccorr.cfg'. +%% (TODO: not so sure about dot vs.\ optional <in-ext>.) +\newcommand*{\MakeSingleDoc}{\makedoc_star\make_single_doc_args} +\newcommand*{\make_single_doc_args}[2][doc]{% + \make_single_doc[#1]#2\@nil} +\def\make_single_doc[#1]#2.#3\@nil{% + \LaTeXresultFile{#2.#1}\MakeCloseDoc{#2.#3}} +%% +%% \subsubsection{Preamble vs.\ main part of input file} +%% A \LaTeX\ package typically has a ``header" or ``preamble" +%% (automatically inserted by 'docstrip') with very scarce information +%% on which file it is and what it provides, and with much more Legalese. +%% Typesetting it in \TeX\ quality may be more misleading than +%% typesetting it \emph{verbatim}. So we typeset it \emph{verbatim}. +%% Now: where does the ``header" end? +%% `\NeedsTeXFormat' might be considered the border.---Yet it seems +%% to be more simple and reliable just to act in terms of the +%% \emph{number of lines} +%% that the header should be long. This length <how-many-lines> is declared by +%% |\HeaderLines{<how-many-lines>}|: +\newcommand*{\HeaderLines}{\def\header_lines} +\HeaderLines{0} +%% So the default is that there aren't any header lines, unless +%% another `\HeaderLines' is issued before some `\MakeDoc'. +%% The way input is parsed \emph{after} the ``header" is set by +%% |\MainDocParser{<parsing-command>}|. +\newcommand*{\MainDocParser}{\def\main_doc_parser} +%% `\SectionLevelThreeParseInput' from section~\ref{sec:secparsers} +%% is the default, two alternatives are defined there, another one is +%% `\ProcessInputWith{comment}' from 'fifinddo' and +%% %% clarified 2010/03/09 `\ref' 2010/03/10 +%% section~\ref{sec:distinguish} +%% (general dividing into code and comments). +\MainDocParser{\SectionLevelThreeParseInput} +%% Here is how `\HeaderLines' and `\MainDocParser' act: +\newcommand*{\makedoc_line_body}{% + \IfInputLine{>\header_lines}% + {\let\makedoc_line_body\main_doc_parser + \makedoc_line_body}% %% switch to deciding + {\TreatAsCode{\fdInputLine}}} %% header verbatim +%% \subsubsection{Screen messages} +%% |\ProcessLineMessage{<command>}| is designed to choose a screen +%% (or log) message <command>. +%% % A simple setting may be \[`\ProcessLineMessage{\message{.}}'\] with +%% `\ProcessLineMessage{\message{.}}' has a result like with 'docstrip'. +%% You just get one dot on screen per input line +%% as a simple confirmation that +%% the program is not hung up. %% TODO phrase!? 2009/04/08 +%% However, the message may slow down a run considerably +%% (if so, choose `\ProcessLineMessage{}' in the script). +%% % , you really have to +%% % wait about a second while you hardly notice the 'makedoc' run +%% % without screen messages. Therefore, the default is \emph{not} +%% % to issue any screen message.%% TODO more complex procedures!? 2009/04/08 +%% %---No! +%% But it is better for beginner users of the package, +%% so made default. %% 2009/04/09 +\newcommand*{\ProcessLineMessage}{\def\process_line_message} +% % \ProcessLineMessage{} %% no, still more efficient: +% \let\process_line_message\relax +\ProcessLineMessage{\message{.}} +%% +%% \subsubsection{Bundling-bundling Standalones} +%% |\MakeInputJobDoc{<header-lines>}{<main-parser>}| +%% by default produces a file +%% \[`\jobname.doc' \mbox{\quad from\quad } `\jobname.sty'\] +%% with some standard settings. %%% \footnote{This command is new with v0.3.} +%% 'mdoccorr.cfg' (for `.txt'$\to$\LaTeX\ functionality) is read, +%% `\HeaderLines{<header-lines>}' +%% and `\MainDocParser{<main-parser>}' and finally +%% `\MakeCloseDoc{\jobname.sty}{\jobname.doc}' +%% % (with the arguments named before) +%% are executed. +%% Here `\jobname' expands to the file name base of the +%% `.tex' file you are running. It is assumed that you are preparing +%% documentation for `\jobname.tex' for your `\jobname.sty'. +%% In order to produce `<my-job>.doc' from `<my-job>.sty' instead, +%% \[`\renewcommand{\mdJobName}{<my-job>}'\] +%% If your input file has a different file name extension +%% <in-ext> than \qtd{`sty'}, use an optional argument +%% of `\MakeInputJobDoc': +%% \[|\MakeInputJobDoc[<in-ext>]{<header>}{<parser>}|\] +%% If the output file +%% should have a different extension <out-ext> than \qtd{`doc'}, +%% you must use \emph{two} optional arguments as follows: +%% \[|\MakeInputJobDoc[<in-ext>][<out-ext>]{<header>}{<parser>}|\] +%% `\MakeInputJobDoc' does \emph{not} execute `\ProcessLineMessage', +%% you can use the latter before so `\MakeInputJobDoc' respects it. +%% +%% |\MakeJobDoc| does the same as `\MakeInputJobDoc' apart from +%% typesetting the <created> file, so the latter needs an additional +%% `\input{<created>}'. +%% The star forms |\MakeInputJobDoc*| and %% 2012/03/18 +%% |\MakeJobDoc*| \emph{avoid} reading 'mdoccorr.cfg'. +%% +%% My original idea was that all preprocessing of package files +%% to be documented should <happen> \emph{before} +%% `\documentclass'---loading +%% 'makedoc.sty' included---inside a group (\lq`{<happen>}'\rq---in +%% order to avoid compatibility issues). +%% However, it now appears to me that loading 'makedoc' the usual way +%% in the document \emph{preamble} +%% and processing the package file (that is to be documented) +%% within the `document' environment works well enough and +%% will be easier to comprehend. +%% +%% This is the code for both `\MakeJobDoc' and `\MakeInputJobDoc': +\@ifdefinable{\mdJobName}{\let\mdJobName\jobname} +\newif\if_makedoc_input_ +\newcommand*{\MakeInputJobDoc}{% + \_makedoc_input_true \makedoc_star\make_job_doc_arg} +\newcommand*{\MakeJobDoc} {% + \_makedoc_input_false \makedoc_star\make_job_doc_arg} +\newcommand*{\make_job_doc_arg}[1][sty] + {\@testopt{\make_job_doc[#1]}{doc}} +%% Reading files as follows would fail with active 'niceverb' settings, +%% so we issue `\noNiceVerb' if it is defined. We do it inside a group +%% in case 'niceverb' settings are to be restored afterwards. +\def\make_job_doc[#1][#2]#3#4{% + \begingroup + \@ifundefined{noNiceVerb}{}% + {\let\MakeNormal\MakeNormalHere \noNiceVerb}% + \makedoc_maybe_autocorr %% 2012/03/17 +%% <- TODO stack danger in group!? 2010/03/13 + \LaTeXresultFile{\mdJobName.#2}% + \HeaderLines{#3}% + \MainDocParser{#4}% + \MakeCloseDoc{\mdJobName.#1}% +%% For typesetting the file just created, some 'nicetext' features +%% may be needed ... so restore the previous ones ... + \endgroup + \if_makedoc_input_\input{\mdJobName.#2}\fi +} +%% This feature may \emph{change}. +%% +%% \subsection{Leaving the package} %% mod. 2012/03/18 +\PopLetterCat\_ %% 2012/08/28 +\endinput +%% +%% \subsection{VERSION HISTORY} + +v0.1 2009/04/03 very first version, tested on morgan.sty +v0.2 2009/04/05 \OnEmptyInputLine, \NoEmptyCodeLines + comment -> PPScomment, \IfFDinputEmpty, + \EveryComment, \PPstring may be par break + 2009/04/08 \InputString -> \fdInputLine, + \section -> \subsection; documentation! + 2009/04/08f. \MakeDoc + 2009/04/12 ``line too long'' w/o redefining \PatternCodes; + \MakeDocCorrectHook + 2009/04/13 tilde with sectioning +v0.3 2010/03/08 \WriteSection 'trimspaces'-like + 2010/03/09 "fool" ("wiki" sectioning) nicer worded, + more use of `...' in place of `\dots'; + different treatment of package code environment + (new separate subsection); clarification on + \ProcessInputWith{comment} + 2010/03/10 supplied `\ref' + 2010/03/11 \MakeCloseDoc; corrected "undifined"; + \par\noindent in ``Sectioning"; \MakeJobDoc + 2010/03/12 &.&.&.; updated copyright + 2010/03/13 corr.: `_' not ``other"; tried to explain my + earlier reasoning about `\ifPackageCode'; + \MakeInputJobDoc + 2010/03/14 \make_doc_job without \niceverb_aux_cat + 2010/03/15 another remark to \ifPackageCode + 2010/03/16 use box with comment line markers; + mdcorr -> mdoccorr + 2010/03/18 report on using \EveryComment + 2010/03/19 '' -> " +v0.4 2010/03/23 "Distinguishing" + 2010/03/24 "both in" + 2010/03/27 switch back to \fdPatternCodes + 2010/03/28 include `% ' commenting style + 2010/03/29 \ResetCodeLineNumbers + 2010/03/30 use \SetPatternCodes, \ResetPatternCodes +v0.41 2010/12/20 \ResetCodeLineNumbers defined globally + 2010/12/21 ... rather presented as a bug-fix + 2011/01/19 \mdStartPackageCode + 2011/01/25 updated (C) +v0.41a 2011/08/22 doc.: makedoc.cfg -> mdoccorr.cfg +v0.41b 2011/10/12 doc.: MakeClose -> MakeDoc +v0.42 2011/11/05 \MakeDoc reads mdoccorr.cfg, \MakeSingleDoc + 2011/11/19 failing reimplementation of \MakeCloseDoc +v0.5 2012/03/17 removing 1 \make_job_doc TODO; star versions; + a few make_doc -> makedoc + 2012/03/18 star variants completed, copyright updated, + doc. "Leaving" +v0.51 2012/04/03 \_makedoc_autocorr_true +v0.52 2012/08/28 using `stacklet.sty' |