summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/nicetext/use/makedoc.sty
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /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.sty642
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'