summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/latex/nicetext/makedoc.sty
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/tex/latex/nicetext/makedoc.sty')
-rw-r--r--Master/texmf-dist/tex/latex/nicetext/makedoc.sty574
1 files changed, 0 insertions, 574 deletions
diff --git a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty
index 292a44242d0..250d65d1fe1 100644
--- a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty
+++ b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty
@@ -1,1148 +1,574 @@
%% 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
-