%% Macro package `makedoc.sty' for LaTeX2e, 

%% copyright (C) 2009 2010 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.4} \def\filedate{2010/03/30} 



%% 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}[2009/04/13]

%% Both 'fifinddo' and 'makedoc' use the ``underscore" `_' 

%% as ``private letter" and restore its standard ``subscript" 

%% function ({\it \TeX book Chap.\,7}) at their end. 

%% Push\slash pop functionality as with `@' and `\RequirePackage' 

%% is missing here. So after loading 'fifinddo',

%% we need to declare our private letter (again). 

\catcode`\_=11 %% underscore used in control words

%%

%% \subsection{&\MakeDocCorrectHook\ (\dqtd{`txt2TeX'})}

%% |\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 

%% 'makedoc.cfg' 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 'makedoc.cfg'.

%%

%% 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 

%% Get rid of 'niceverb' stuff:

  % \MakeOther\`\MakeOther\'%% probably OK with moreverb

  \MakeOther\<\MakeOther\|%

%% From the next occurrence of the environment onwards, 

%% `listing' must be replaced by `listingcont'. We must 

%% copy the previous code diligently. 

  \gdef\mdPackageCode{\small \MakeOther\<\MakeOther\|%

                      \listingcont}%

  \listing{1}}

\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':

\newcommand*{\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 == %%%%%%%%%%%%%%%%%%%%%%'\] 

%% 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:

\newcommand*{\MakeDoc}[1]{%

%% In case of a ``header" (see below) we change into ``code mode":

  \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 `\makd_doc_line_body' 

%% that is predefined below and can be changed while processing the 

%% <input> file. 

  \ProcessFileWith{#1}{%

    \CountInputLines %% stepping line counter is standard

    \make_doc_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

%% just is a shorthand for 

%% \[`\MakeClose{<input>}\CloseResultFile'\]

%% where `\CloseResultFile' is from 'fifinddo'.

\newcommand*{\MakeCloseDoc}[1]{\MakeDoc{#1}\CloseResultFile}

%% `\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{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: 

\def\make_doc_line_body{%

  \IfInputLine{>\header_lines}%

              {\let\make_doc_line_body\main_doc_parser

                   \make_doc_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>}'. 

%% 

%% 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

                               \make_job_doc_read}

\newcommand*{\MakeJobDoc}     {\_makedoc_input_false

                               \make_job_doc_read}

\newcommand*{\make_job_doc_read}[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}%

    \input{mdoccorr.cfg}% 

    %% <- TODO warning if not found!? 

    %%         or if one from TEXMF/ used inadvertently!?

    %%         avoid reading twice!? 2010/03/11

    %% <- TODO stack danger in group!? 2010/03/13 

    %% <- TODO or read it from 'makedoc' already! 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{Leave the package}

\catcode`\_=8   %% restores underscore use for subscripts

\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

