diff options
Diffstat (limited to 'Master/texmf-dist/tex/latex/nicetext/makedoc.sty')
-rw-r--r-- | Master/texmf-dist/tex/latex/nicetext/makedoc.sty | 574 |
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 - |