From ee53eac199e12fb91859fd18a43dd506ff75e3a9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 20 Apr 2009 22:50:28 +0000 Subject: nicetext update (20apr09) git-svn-id: svn://tug.org/texlive/trunk@12766 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/tex/latex/nicetext/fifinddo.sty | 676 ++++++++++++++++++++++ Master/texmf-dist/tex/latex/nicetext/makedoc.sty | 367 ++++++++++++ Master/texmf-dist/tex/latex/nicetext/niceverb.sty | 111 ++-- 3 files changed, 1113 insertions(+), 41 deletions(-) create mode 100644 Master/texmf-dist/tex/latex/nicetext/fifinddo.sty create mode 100644 Master/texmf-dist/tex/latex/nicetext/makedoc.sty (limited to 'Master/texmf-dist/tex/latex/nicetext') diff --git a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty new file mode 100644 index 00000000000..1f03ae4c4ab --- /dev/null +++ b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty @@ -0,0 +1,676 @@ +%% Macro package `fifinddo.sty' for LaTeX2e, %% FIDO, FIND! +%% copyright (C) 2009 Uwe L\"uck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% for processing tex(t) files +%% (checking, filtering, converting, substituting, expanding, ...) + +\def\fileversion{0.3} \def\filedate{2009/04/15} + +%% 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 +%% +%% For the full documentation, look for `fifinddo.pdf'. +%% Its source starts in `fifinddo.tex'. +%% +%% === Format and package version === +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +% 1994/12/01: \newcommand* etc. +\ProvidesPackage{fifinddo}[\filedate\space v\fileversion\space + filtering TeX(t) files by TeX (UL)] +%% +%% === Category codes === +%% +%% We use the ``underscore'' as ``compound identifier.'' +\catcode`\_=11 %% underscore used in control words +%% +%% |\MakeOther| is a synonym for `\@makeother', needed for matching +%% special characters from the input file. It is exemplified by +%% |\fdPatternCodes| which is the default of |\PatternCodes|. +%% The latter is used in setup macros for reading patterns. +\@ifundefined{MakeOther}{\let\MakeOther\@makeother}{} +\newcommand*{\fdPatternCodes}{\MakeOther\&\MakeOther\$} +\newcommand*{\PatternCodes}{} \let\PatternCodes\fdPatternCodes + %% TODO adding/removing +%% It would be bad to have `\MakeOther\%' and `\MakeOther\ ' here in +%% that this may have unexpected, weird effects with arguments of +%% setup macros. Therefore neither `\dospecials' nor `\@sanitize' are +%% used. Curly braces remain untouched as default delimiters in setup +%% macros. For matching them, you must use `\MakeOther\{' and +%% `\MakeOther' in your `\PatternCodes', or |\Delimiters| to introduce +%% new ones at the same time, e.g., `\Delimiters\[\]': +\newcommand*{\Delimiters}[2]{% + \MakeOther\{\MakeOther\}\catcode`#1=1\catcode`#2=2\relax} +%% For replacing strings or for defining other strings of ``other'' +%% characters by `\edef', you can use some \LaTeX\ constructs---here +%% are copies |\PercentChar| and |\BackslashChar| of them +%% (do you need more?): +\newcommand*{\PercentChar}{} \let\PercentChar\@percentchar +\newcommand*{\BackslashChar}{} \let\BackslashChar\@backslashcar +%% +%% == File handling == +\newwrite\result_file %% or write to \@mainaux!? +%% |\ResultFile{}| opens (and empties) a file +%% to be written into. +\newcommand*{\ResultFile}[1]{% + \def\result_file_name{#1}% + \immediate\openout\result_file=#1} +%% |\WriteResult{}| writes a line into +%% (or more lines with `^^J'). +\newcommand*{\WriteResult}[1]{% + \immediate\write\result_file{#1}} +%% |\WriteProvides| writes a `\ProvidesFile' command to the +%% opened file. This should be used when +%% is made as \LaTeXe\ input. +\newcommand*{\WriteProvides}{% + \WriteResult{% + \string\ProvidesFile{\result_file_name}% + [\the\year/\two@digits\month/\two@digits\day\space + automatically generated with fifinddo.sty]}}% +%% |\ProcessFileWith{}{}| opens a file +%% and runs a loop on its lines the main body of which is . +%% When it starts, a new line of is stored as macro +%% |\fdInputLine|. +\newcommand*{\ProcessFileWith}[2]{% + \openin\@inputcheck=#1% +% \ifeof\@inputcheck %% bad `exists?' test +% \PackageError{fifinddo}{File `#1' not here}% +% {Mistyped?}% +% \else + \global\c@fdInputLine=\z@ %% line counter reset + \begingroup + \MakeOther\{\MakeOther\}\@sanitize + %% from docstrip.tex: + % \MakeOther\^^A\MakeOther\^^K%% irrelevant, not LaTeX + \endlinechar\m@ne + %% <- cf. TeXbook "extended keyboards" up-/downarrow + %% -> "math specials", cf. "space specials" + \MakeOther\^^I% ASCII horizontal tab -- guessed!? ^^L!? + \loop \ifeof\@inputcheck \else + \read\@inputcheck to \fdInputLine + \ignorespaces #2% + \repeat + \endgroup +% \fi + \closein\@inputcheck} +%% |\CloseResultFile| closes . +\newcommand*{\CloseResultFile}{\immediate\closeout\result_file} +%% Peter Wilson's 'newfile' provides more powerful file handling. +%% % <- TODO relevant? 2009/04/12 +%% +%% \pagebreak %% TODO move theory to fifinddo.tex 2009/04/12 +%% == Basic handling of substring conditionals == +%% \label{sec:theory} +%% === ``Substring Theory'' === +%% \begin{flushright}\it +%% I wished I could study string theory,\\ +%% but I only could study substring theory. +%% \end{flushright} +%% A \TeX\ macro, say, `\find' whose parameter text +%% (cf. \TeX book p.~203) +%% starts with `#1#2&' stops \TeX\ with an error if it does +%% not find and then `&'. Otherwise we have a situation +%% `\find&', and `\find' reads as +%% #1 and as #2. An important point to note is that +%% will not contain , but possibly has more +%% occurrences in . In this sense, `\find' uses the +%% \emph{first} occurrence of it finds in order to delimit #1. +%% Finding the \emph{last} occurrence of therefore needs a +%% special idea. +%% +%% In order to use `\find' for a test whether is in +%% , we build a ``sandbox'' |\find&|, where +%% contains \emph{and additionally} ---as a +%% ``dummy;'' so `&' delimits the search and `\find' finds +%% either in or somewhere else before `&'. +%% +%% Consider the simple sandbox |\find&|. +%% We can test #1 and #2 on being empty by `\ifx$#1$' and `\ifx$#2$'. +%% If #2 is empty, is \emph{not} in . +%% If #1 is empty at the same time, is empty. +%% If #1 is empty and #2 is not, \emph{starts} ! +%% This can be used to implement +%% Wikipedia-like lists %% TODO 2009/04/11 +%% and to distinguish package code from comments in 'makedoc'. +%% +%% If #2 is \emph{not} empty, occurs in ---or this once +%% was \emph{thought}, some time in developping the present package, +%% as well as in the version of 'substr.sty' marked +%% `2005-11-29',\footnote{\hspace{1sp}'substr' does not change +%% category codes +%% % as 'fifinddo' does +%% and uses \cs{@nil} as delimiter instead of our &&.} try +%% \[`\IfSubStringInString{}{}{YES}{NO}'\] +%% which works \emph{verbatim} as well as considering and +%% \emph{placeholders}, e.g., for +%% \begin{center} +%% `\IfSubStringInString{day after day}{day after }{YES}{NO}'\footnote{% +%% Likewise \texttt{t\string\^ete-\string\`a-t\string\^te} ...}\\ +%% `\IfSubStringInString{AMSTERDAM}{AMSTERD}{YES}{NO}'\\ +%% `\IfSubStringInString{TORONTO}{TORON}{YES}{NO}'\\ +%% `\IfSubStringInString{bonbon}{bon}{YES}{NO}'\footnote{% +%% Polynesian: `aku aku', `rongorongo', `wiki wiki' ...}\\ +%% `\IfSubStringInString{bonobo}{bono}{YES}{NO}' +%% (an ape) +%% \end{center} +%% or `\IfSubStringInString{ionization}{ionizat}{YES}{NO}'.\footnote{% +%% Read 'substr.sty' or try ``normal'' things to convince yourself +%% that the syntax indeed is +%% &\IfSubStringInString{}{}{}{}.} +%% Same with \LaTeX's internal `\in@': +%% \[`\makeatletter \in@{bonbon}{bon}\ifin@ YES\else NO\fi \makeatother'\] +%% %% \makeatletter \in@{bonbon}{bon}\ifin@ YES\else NO\fi \makeatother +%% %% \IfSubStringInString{ionization}{ionizat}{YES}{NO} +%% +%% In general, the previous approach \emph{fails if and exactly if} +%% has a \emph{period} $p$---less than its length---in the sense of that +%% the $p$th token to the right or left of each token in +%% is the \emph{same} token. +%% `AMSTERDAM' has a period 8, `day after day' 10, `bonbon' 3, `bonobo' 4. +%% There is a counterexample of length $p$ iff +%% has period $p$, namely the first substring of +%% having length $p$. If the length of exceeds a multiple +%% $mp$ of its period, the first $mp$ tokens of form +%% a counterexample . +%% +%% Therefore, a sandbox must have something between and +%% . We choose |\find~$&| as standard. +%% The `$' will be used as an argument delimiter to get rid of the dummy +%% in , as well as to decide whether the match was +%% in or in the dummy part of the sandbox. +%% The `$' can be replaced by another tilde `~' in order to +%% test whether \emph{ends} on a , defining a macro +%% like `\findatend' whose parameter text starts with `#1~#2&'. +%% +%% === Plan for proceeding === +%% When we check a file for several patterns, we seem to need +%% \emph{two} macros for each pattern: one that has the pattern +%% in its parameter text and one that stores the pattern for building +%% the sandbox.\footnote{If it were for the pattern only, the parsing +%% macro might suffice and the macro calling it might extract the +%% pattern from a ``dummy expansion.'' Somewhat too much for me now; +%% on the other hand the calling macro also hands some ``current'' +%% informations to the parsing macro---oh, even this could be +%% handled by a general ``calling'' macro \dots} +%% %% TODO 2009/04/15 +%% We use a separate \emph{``name space''} for each of +%% both kinds. The parsing macro and the macro building the sandbox +%% will have a common \emph{``identifier''} by which the user or +%% programmer calls them. Actually, she will usually (first) call +%% the sandbox box builder. The sandbox builder calls the parsing +%% macro. When \emph{all} occurrences of a pattern in the target are +%% looked for, the parser may call itself. +%% +%% Actually, the parsing macro will execute certain actions +%% depending on what it finds in the sandbox, so we call it a +%% \emph{``substring conditional''}. It may read additional arguments +%% after the sandbox that store information gathered before. +%% This is especially useful for designing \emph{``expandable''} +%% chains (sequences) of conditionals where macros cannot store information in +%% macros. The macro setting up the sandbox will initialize such +%% extra arguments at the same time. +%% +%% It may be more efficient \emph{not} to use the following setup +%% macros but to type the macros yourself, just using the following +%% as templates. The setup macros are especially useful with patterns +%% that contain ``special characters,'' as when you are looking for +%% lines that might be package comments. +%% +%% === Set up conditionals === +%% `substr_cond' is the ``name space'' for substring conditionals. +%% A colon separates it from \emph{``job identifiers''} in the actual +%% macro names. +\def\substr_cond{substr_cond:} +%% |\MakeSubstringConditional{}[]{}| +%% starts the definition of a conditional with \emph{identifier} +%% and pattern . optionally add commands to +%% be executed after `\PatternCodes' in a local group. +%% It may be more safe to redefine `\PatternCodes' instead. +\newcommand*{\MakeSubstringConditional}{% + \afterassignment\mk_substr_cond_san \def\cond_id} +\newcommand*{\mk_substr_cond_san}[1][]{% + \begingroup \PatternCodes #1\mk_substr_cond} + %% #1 more changes +%% `\begingroup' |\mk_substr_cond{}| +%% can be directly called by other programmer setup commands when +%% `\cond_id' and have been read. +\def\mk_substr_cond #1{%% #1 pattern string + \endgroup \@namedef{\substr_cond \cond_id}##1#1##2&} +%% This really is not \LaTeX. We are starting defining a macro +%% `\substr_cond:' in primitive \TeX\ with `\def' in the form +%% \[`\def\substr_cond:#1#2&'\] +%% where `\csname' etc. render \lq`:'\rq\ part of the macro name. +%% The user or programmer macro produces the part of the definition +%% until the delimiter `&' to match the sandbox. You have to add +%% (maybe) #3 etc. and the `{}' +%% just as with primitive \TeX. +%% +%% === Set up sandboxes === +%% There was a \emph{question:} will we rather see +%% \emph{string macros} or \emph{strings from macro arguments}? +%% The input file content always comes +%% as `\fdInputLine' first, so we at least \emph{must account} for +%% the possibility of string macros as input. +%% +%% One easy way to apply several checks and substitutions to +%% `\fdInputLine' before the result is written to is +%% `\let\OutputString\fdInputLine' and then let `\OutputString' +%% be to what each job refers as \emph{its} +%% input and output, finally `\WriteResult{\OutputString}'. +%% (`\fdInputLine' might better not be touched, it could be used +%% for a final test whether any change applied for some message on +%% screen, even with an entirely expandable chain of actions.) +%% This way each job, indeed each recursive substitution of a single +%% string must start with expanding `\OutputString'. +%% +%% On the other hand, there is the idea of \emph{``expandable'' +%% chains of substitutions}. We may, e.g., define a macro, say, +%% `\manysubstitutions{}', such that +%% `\WriteResult{\manysubstitutions{\fdInputLine}}' +%% writes to the result of applying many expandable +%% substitutions to `\fdInputLine'. +%% Such a macro `\manysubstitutions' may read `\fdInputLine', +%% but it must not redefine any macros. +%% Instead, the substitution macros it calls must read results +%% of previous substitutions as \emph{arguments}. +%% +%% Another aspect: +%% the order of substitutions should be easy to +%% change. Therefore expanding of string macros should rather be +%% controlled by the way a job is \emph{called}, not right here +%% at the \emph{definition} of the job. For this reason, +%% a variant of the sandbox builder expanding some macro was given up. + +%% `setup_substr_cond' is the name space for macros that build +%% sandboxes and initialize arguments for conditional macros. +\def\setup_substr_cond{setup_substr_cond:} +%% |\MakeSetupSubstringCondition{}[]{}{}| +%% % <- TODO allow `%' and ` ' for breaking code lines. +%% ---same , , as for +%% `\MakeSubstringConditional' (this is bad, there may be +%% |\MakeSubstringConditional*{}|)---creates the +%% % <- TODO: store args in \Make...Conditional +%% corresponding sandbox, by default without tilde wrap. +%% may contain `{#1}' to store the string that was tested, +%% also `{}' for calling repetitions and `{}' for screen +%% or log informations. +\newcommand*{\MakeSetupSubstringCondition}{% + \afterassignment\mk_setup_substr_cond_san \def\cond_id} +\newcommand*{\mk_setup_substr_cond_san}[1][]{% + \begingroup \PatternCodes #1\mk_setup_substr_cond} +%% `\begingroup' |\mk_setup_substr_cond{}{}| +%% can be directly called by other programmer setup commands after +%% `\cond_id' and have been read: +\def\mk_setup_substr_cond #1#2{%% #1 pattern string, + %% #2 additional arguments, e.g., `{#1}' to keep tested string + \endgroup + \expandafter \edef + \csname \setup_substr_cond \cond_id \endcsname ##1{% +% \expandafter \noexpand +% \csname \substr_cond \cond_id \endcsname %% 2009/04/10: + \make_not_expanding_cs{\substr_cond \cond_id}% +%% By `\edef', the name of the substring conditional is stored here +%% as a single token. The rest of the sandbox follows. + ##1\noexpand~#1\dollar_tilde}% + \let\dollar_tilde\sandbox_dollar} +%% If a tilde `~' has been used instead of `$', the default +%% is restored. +\def\sandbox_dollar{$} +\let\dollar_tilde\sandbox_dollar +%% The following general tool |\make_not_expanding_cs| has been used +%% (many definitions in 'latex.ltx' could have used it): %% 2009/04/10 +\def\make_not_expanding_cs#1{% + \expandafter \noexpand \csname #1\endcsname} +%% +%% === Getting rid of the tildes === +%% |\let~\TildeGobbles| can be used to suppress dummy patterns +%% (contained in ) +%% in `\write'ing or with `\edef'. ... will probably become obsolete +%% ... however, it is helpful in that you needn't care +%% whether there is a dummy wrap left at all. (2009/04/13) +\newcommand{\TildeGobbles}{} \def\TildeGobbles#1${} +%% |\RemoveDummyPattern| is used to remove the dummy pattern +%% \emph{immediately}, not waiting for `\write'ing +%% or other ``total'' expansion: %% 2009/04/13 +\newcommand{\RemoveDummyPattern}{} \def\RemoveDummyPattern#1~#2${#1} +%% |\RemoveDummyPatternArg{}| executes +%% `\RemoveDummyPattern' in the next argument: +\newcommand*{\RemoveDummyPatternArg}[2]{% + \expandafter #1\expandafter {\RemoveDummyPattern #2}} +%% |\RemoveTilde| is used to remove the tilde that separated +%% the dummy pattern from . +% %% An alternative policy is to pass +% %% (as an argument) to the parsing macro. +\newcommand{\RemoveTilde}{} \def\RemoveTilde#1~{#1} +%% |\RemoveTildeArg{}| executes `\RemoveTilde' +%% in the next argument: +\newcommand*{\RemoveTildeArg}[2]{% + \expandafter #1\expandafter {\RemoveTilde #2}} +%% +%% === Calling conditionals === +%% |\ProcessStringWith{}{}| builds the sandbox +%% to search for the associated with the +%% parser-conditional that is identified by , the sandbox then +%% calls the parser. +\newcommand*{\ProcessStringWith}[2]{% + \csname \setup_substr_cond #2\endcsname{#1}} +%% |\ProcessExpandedWith{}{}| does the same but with +%% a \emph{macro} (like `\fdInputLine' or `\OutputString') in which +%% the string to be tested is stored. +\newcommand*{\ProcessExpandedWith}[2]{% + \csname \setup_substr_cond #2\expandafter \endcsname + \expandafter{#1}} +%% I would have preferred the reversed order of arguments which seems +%% to be more natural, but the present is more efficient. +%% Macros with reversed order are currently stored after `\endinput' +%% in section~\ref{sec:pondered}, may be they once return. +%% +%% Anyway, most desired will be |\ProcessInputWith{}| just +%% applying to `\fdInputLine': +\newcommand*{\ProcessInputWith}[1]{% + \csname \setup_substr_cond #1\expandafter \endcsname + \expandafter{\fdInputLine}} +%% (Definition almost copied for efficiency.) + %% TODO: error when undefined 2009/04/07 +%% +%% === Copy jobs === +%% A job identifier may also be considered a mere \emph{hook}, +%% a \emph{placeholder} for a parsing job. What function actually is +%% called may depend on conditions that change while reading the +%% file. %%% On a certain condition, +%% |\CopyFDconditionFromTo{}{}| +%% \emph{creates or redefines a sandbox builder} with identifier +%% that afterwards behaves like the sandbox builder . +%% So you can store a certain behaviour as in advance in order +%% once to change the behaviour of into that of . +\newcommand*{\CopyFDconditionFromTo}[2]{% + \expandafter \let + \csname \setup_substr_cond #2\expandafter \endcsname + \csname \setup_substr_cond #1\endcsname} +%% (Only the \emph{sandbox} is copied here---what about +%% changing conditionals?) %% TODO +%% +%% An ``almost'' example is typesetting documentation from a package +%% file where the ``Legalese'' header might be typeset verbatim +%% although it is marked as ``comment.'' (The present %% 2009/04/07 +%% example changes ``hand-made'' macros instead.) +%% +%% This feature could have been placed more below as a ``programming +%% tool.'' +%% +%% == Programming tools == +%% === Tails of conditionals === +%% \label{sec:tails} +%% When creating complex \emph{expandable} conditionals, +%% this may amount to have primitive `\if' ... `\fi' conditionals +%% nested quite deeply, once perhaps too deep for \TeX's memory. +%% To avoid this, you can apply the common `\expandafter' trick +%% which finishes the current `\if' ... `\fi' before an inside +%% macro is executed (cf. \TeX book p.~219 on ``tail recursion''). +%% +%% Internally tests whether certain strings are present at certain +%% places will be carried out by tests on emptiness or +%% onwards) on starting with `~'. E.g., +%% ``#1~=~ empty'' indicates that either the +%% starts a line or the line is empty altogether (this must be +%% decided by another test). +%% +%% |\IfFDempty{}{}{}| +%% is used to test on emptyness (without expanding it): +\newcommand*{\IfFDempty}[1]{% + \ifx$#1$\expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} +%% |\IfFDinputEmpty{}{}| is a variant of +%% the previous to execute if the loop processing +%% finds an empty line---otherwise . +\newcommand*{\IfFDinputEmpty}{% + \ifx\fdInputLine\@empty \expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} +%% |\IfFDdollar{}{}{}| +%% is another variant, testing for being `$', +%% main indicator of there is a match anywhere in +%% (as opposed to starting or ending match): +\newcommand*{\IfFDdollar}[1]{% + \ifx$#1\expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} +%% It is exemplified and explained in section~\ref{sec:replchain}. +%% (The whole policy requires that `~' remains active in any +%% testing macros here!) +%% +%% However, you might always just type the replacement text +%% (in one line) instead of +%% such an `\If'\,... (for efficiency \dots) +%% +%% If expandability is not desired, you can just chain macros that +%% rework (so re-define) `\OutputString' or so. +%% +%% 2009/04/11: tending towards combining ... +%% Keeping empty input and empty arguments apart is useful in that +%% \emph{one} test of emptiness per input line should suffice---it +%% may be left open whether this should be the first of all tests +%% \dots +%% +%% === Line counter === +%% A \LaTeX\ counter |fdInputLine| may be useful for screen or log +%% messages, moreover you can use it to control processing of the +%% file ``from outside,'' not dependent on what the parsing +%% macros find. The header of the file might be typeset verbatim, +%% but we may be too lazy to define the ``header'' in terms of +%% what is in the file. We just decide that the first ... lines +%% are the ``header,'' even without counting just trying whether +%% the output is fine. It may be necessary to change that number +%% manually when the header changes. +%% +%% You also can insert lines in +%% which have no counterpart in ---if you know what you are +%% doing. With 'makedoc', there is a hook `\EveryComment' that can +%% be used to issue commands ``from outside'' at a place where +%% executing the command is safe or appropriate. +\newcounter{fdInputLine} +%% You then must insert |\CountInputLines| in the second argument +%% of `\ProcessFileWith' (or in a macro called from there) +%% so that the counter is stepped. %% TODO!? 2009/04/07 +\newcommand*{\CountInputLines}{\global\advance\c@fdInputLine\@ne} +%% At present %% 2009/04/07 TODO +%% the counter is reset by `\ProcessFileWith', this may change. +%% +%% |\IfInputLine{}{}{}|, when called +%% from the processing loop (second argument of `\ProcessFileWith') +%% issues commands if `\value{fdInputLine}' +%% is true, otherwise . may usually be just `='. +\newcommand*{\IfInputLine}[1]{% + \ifnum\c@fdInputLine#1\relax \expandafter \@firstoftwo + \else \expandafter \@secondoftwo \fi} +%% +%% === The ``identity job'' `LEAVE' === +%% \label{sec:LEAVE} +%% The job with identifier |LEAVE| +%% \emph{leaves} an (expandable) chain of jobs +%% (as expandable replacement in section~\ref{sec:replchain}) +%% and \emph{leaves} the processed string without changing it +%% and without the braces enclosing it: +\expandafter \let + \csname \setup_substr_cond LEAVE\endcsname \@firstofone +%% I.e., `\ProcessStringWith{}{LEAVE}' expands to +%% ... \ProcessStringWith{(Indeed!)}{LEAVE} + +%% == Setup for expandable chains of replacements == +%% \label{sec:replchain}%% TODO makedoc: provide less visible label/ref 2009/04/11 +%% By the following means, you can create macros +%% (`\Transform' among them) such that, e.g., +%% \[`\edef\OutputString{\Transform{}}'\] renders `\OutputString' +%% the result of applying a chain (sequence) of stringwise replacements +%% to . +%% You can even write a transformed input to a file +%% without defining anything anything after `\read to'\,.\,.\,. +%% In this case however, you don't get any statistical message +%% about what happened or not. With `\edef\OutputString' you can at +%% least issue some `changed!' or `left!' (maybe `\message{!}' vs.\ +%% `\message{.}'). +%% There is an application in 'makedoc' for ``typographical upgrading'' +%% from plain text to \TeX\ input. +%% +%% |\repl_all_chain_expandable| will be the backbone of the +%% replacements. It is called by some parsing macro +%% and receives from the latter ~=~#1 and ~=~#2. +%% #3 is the result of what happened so far. +\def\repl_all_chain_expandable#1#2#3#4#5#6{% + %% #1, #2 splits, #3 past, #4 substitute, + %% #5 repeat parser, #6 pass to +% \ifx~#2\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi +%% The previous line would be somewhat faster, but let us exemplify +%% `\IfFDdollar' from section~\ref{sec:tails} instead: + \IfFDdollar{#2}% +%% If #2 starts with `$'---with category code 3, ``math shift''!, +%% it \emph{is} `$', due to not reading `$' +%% from input with its standard category code 3 +%% and the sandbox construction (where `$' appears with its standard +%% category code). %% TODO might be explained earlier 2009/04/11 +%% %% or refer to here. +%% And this is the case \emph{exactly} when the from +%% didn't match, again due to the input category codes. +%% Now on \emph{no} match, the sandbox builder #6 is called +%% with target string #3#1 where the last tested string is attached +%% to previous results. The ending `~' is removed, #6 inserts a new +%% wrap for the new dummy pattern. + {\RemoveTildeArg #6{#3#1}}% +%% Otherwise ... the \emph{sandbox builder} +%% (that will be shown below) that called +%% initialized #5 to be that itself. ( otherwise +%% wouldn't know who it is.) So calls itself with another sandbox +%% `#2&'. Note that #2 contains \lq`~$'\rq\ due to the initial +%% building. + {#5#2&{#3#1#4}{#4}#5#6}} +%% #4 is the replacement string that passed to . +%% The first argument after the `&' is previous stuff plus +%% the recently skipped +%% plus #4 replacing the string that was matched. +%% +%% Finally, #5 and #6 again ``recall'' and the sandbox +%% builder to which to change in case of no other match. +%% +%% % TODO move following up!? 2009/04/11 +%% |\MakeExpandableAllReplacer{}{}{}{}| +%% creates sandbox and parser with common identifier and search +%% pattern . Each occurrence of will be replaced by +%% . When is not found, the sandbox builder for +%% is called. This may be another replacing macro of the +%% same kind. To return the result without further transformations, +%% call job `LEAVE' (section~\ref{sec:LEAVE}). +\newcommand*{\MakeExpandableAllReplacer}{% + \afterassignment\mk_setup_xpdbl_all_repl_san + \def\cond_id} +%% ... usual intermezzo for reading patterns with non-standard +%% category codes, this time we read \emph{two} patterns \dots +\newcommand*{\mk_setup_xpdbl_all_repl_san}[1][]{% + \begingroup \PatternCodes #1\mk_setup_xpdbl_all_repl} +%% Here comes the real work. +\newcommand*{\mk_setup_xpdbl_all_repl}[3]{% + %% #1 pattern, #2 substitute, #3 pass to + \endgroup +%% We take pains to call next jobs by single +%% command strings and store them this way, not by `\csname', +%% as `\ProcessStringWith' would do it. `\edef\@tempa' +%% is used for this purpose, but \dots + \edef\@tempa{% + \noexpand\mk_setup_substr_cond{#1}{% + {}{#2}% + \noexpand\noexpand +%% That `\edef\@tempa' must \emph{not expand} the controll +%% words after they have been computed from `\csname' etc. +%% Moreover, expansion of the parser commands +%% must be avoided another time, when `\@tempa' is executed. + \make_not_expanding_cs{\substr_cond\cond_id}% + \noexpand\noexpand + \make_not_expanding_cs{\setup_substr_cond #3}}}% +%% Those internal setup commands start with `\endgroup' to switch back +%% to standard category codes. We must match them here by +%% `\begingroup'. + \begingroup \@tempa + \begingroup \mk_substr_cond{#1}{% + \repl_all_chain_expandable{##1}{##2}}} +%% The final command is the one that we explained first. %% TODO 2009/04/11 +%% +%% Support for dozens of replacements in one sequence +%% and for screen messages +%% must wait for another release, sorry! %% TODO 2009/04/11 +%% +%% == Leave package mode == +%% We restore the underscore `_' for math subscripts. +%% (This might better depend on something \dots) %% TODO 2009/04/07 +\catcode`\_=8 %% restores underscore use for subscripts + +\endinput +%% \TeX\ ignores the rest of the file when it is \emph{input} +%% ``in the sense of `\input''', as opposed to just reading +%% the file line by line to a macro like `\fdInputLine'. +%% +%% == Pondered == +%% \label{sec:pondered} + %% TODO abbreviated commands (aliases) \MkSubstrCond... + %% TODO \@onlypreamble!? +\newcommand*{\ApplySubstringConditional}[1]{% + %% #1 identifier; text to be searched expected next + \csname setup_substr_cond:#1\endcsname} +\newcommand*{\ApplySubstringConditionalToExpanded}[1]{% 2009/03/31+ + \csname setup_substr_cond:#1\expandafter \endcsname \expandafter} +\newcommand*{\ApplySubstringConditionalToInputString}[1]{% 2009/03/31+ + \csname setup_substr_cond:#1\expandafter \endcsname + \expandafter {\fdInputLine}} + %% TODO or `\OutputString', even `\read' to `\OutputString'!? +% \newcommand*{\ApplySubstringConditionalToExpanded}[2]{% +% %% note: without assignments, robust! +% %% BUT the `\csname ... \expandafter \endcsname' method is faster +% \expandafter \reversed_apply_substr_cond +% \expandafter {#2}{#1}} +% \newcommand*{\reversed_apply_substr_cond}[2]{% +% \ApplySubstringConditional{#2}{#1}} + %% ODER: +% \newcommand*{\expand_attach_arg}[2]{%% 2009/03/31 +% %% #1 command with previous args, TODO cf. LaTeX3 +% \expandafter \attach_arg \expandafter {#1}{#2}} +% %% actually #1 may contain more than one token, +% %% only first expanded +% \newcommand*{\attach_arg}[2]{#2{#1}} +% \newcommand*{\ApplySubstringConditionalToExpanded}[2]{% +% \expandafter \attach_arg \expandafter +% {#2}{\ApplySubstringConditional{#1}}} +%% +%% +%% +%% == VERSION HISTORY == +%% +v0.1 2009/04/03 very first version, tested on morgan.sty +v0.2 2009/04/05 counter fdInputLine, \ProvidesFile moved from + \ProcessFile to \ResultFile, \CopyFD..., + category section first, more sectioning, + suppressing empty code lines before section + titles; discussion, \Delimiters + 2009/04/06 more discussion + 2009/04/07 more discussion, factored \WriteProvides out from + \ResultFile, \ProcessExpandedWith corrected + 2009/04/08 \InputString -> \fdInputline; + removed \ignorespaces + 2009/04/09 \WhenInputLine[2] -> \IfInputline[3], + \ProcessInputWith, typos, + \WriteProvides message `with' + 2009/04/10 \make_not_expanding_cs + DISCOVERED ``IF SUBSTRING'' ALGORITHM WRONG + ( in ) +v0.3 2009/04/11 SOME THINGS GIVEN UP EARLIER WILL BE REMOVED, + TO BE STORED IN THE COPY AS OF 2009/04/10 + mainly: sandbox setup (tilde/dollar) + REAL ADDITION: setup for expandable replacing + 2009/04/12 played with `chain' vs. `sequence'; + plain `...', `cf.', `etc.' for `mdcorr.cfg' + 2009/04/13 \RemoveTilde... + 2009/04/15 reworked text, same mistake \in@ diff --git a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty new file mode 100644 index 00000000000..7fb78c662a1 --- /dev/null +++ b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty @@ -0,0 +1,367 @@ +%% Macro package `makedoc.sty' for LaTeX2e, +%% copyright (C) 2009 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.2} \def\filedate{2009/04/13} + +%% 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 `~' 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 +\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 make it ``other'' at their end (functionality as with +%% ``at'' and `\RequirePackage' is missing here). So after loading +%% 'fifinddo', I must restore the new private letter. +\catcode`\_=11 %% underscore used in control words +%% +%% \subsection{&\MakeDocCorrectHook} +%% |\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 +%% `...', 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{}}'\] +%% ... provided (sometimes) `\MakeOther\ ' ... +%% You can even change it using `\IfInputLine' from 'fifinddo' in the +%% midst of preprocessing a package documentation. +%% +%% \subsection{Distinguish package code from comments}%% <- wiki style breaks in self-doc. +%% Use of comment marks is a matter of personal style. Only lines +%% starting with the sequence `%% ' 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 \dots +%% +%% 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|. +\renewcommand*{\PatternCodes}{\MakeOther\%\MakeOther\ }%% 2009/04/02 +%% Look here: the line became too long and could not be broken. +%% Must we really introduce new comment marks? +% \MakeSetupSubstringCondition{comment}[\MakeOther\%\MakeOther\ ] +%% 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{comment}[\MakeOther\%\MakeOther\ ] +\MakeSubstringConditional{PPScomment}{%% }#3{%% #3 entire test string + \IfFDinputEmpty{\OnEmptyInputLine}{% +%% The empty line test comes early to offer control with +%% `\OnEmptyInputLine' both code and comment mode. +%% Maybe it should always? %% TODO 2009/04/13 + \IfFDempty{#1}%% + {\TreatAsComment{% + \RemoveDummyPatternArg\MakeDocCorrectHook{#2}}}% + {\ifx\fdInputLine\PPstring + \ifPackageCode\else \WriteResult{}\fi%% 2009/04/05 + %% <- allow paragraphs in comments + \else \TreatAsCode{#3}\fi}}} +% \expandafter \show \csname \substr_cond PPScomment\endcsname +%% |\PPstring| stores the line suppressing empty code lines. +\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 ``undifined'' error; +%% however this release predefines it to behave like `PPScomment'. +\CopyFDconditionFromTo{PPScomment}{comment} +%% Alternative still to be considered: +% \@namedef{\setup_substr_cond comment}{% +% \PackageError{makedoc}{Job `comment' not defined}% +% {Use \string\CopyFDconditionFromTo{comment}}} +%% +%% \subsection{Dealing with comments} +%% |\TreatAsComment{}| writes 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{packagecode\@empty}}% +%% The `\@empty' here is a lazy trick to save self-documentation +%% fighting 'verbatim''s ``highlight'' of finding ends of listings +%% (to be improved). %% +%% +%% 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' \dots %% 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. +\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 +%% `====', `======', and `========' (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 +%% |\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{}{}| replaces an input line +%% with a line \[`{\hspace{1sp}\ignorespaces \unskip }'\] +%% in the documentation file and switches into ``comment mode.'' +%% `\hspace{1sp}' ensures that 'niceverb''s package name feature works. +%% `\ignorespaces' and `\unskip' undo the spaces between title text and +%% the `=' symbols that usually are typed for readability. +\newcommand*{\WriteSection}[2]{% + \TreatAsComment{% + ^^J#1{\string\hspace{1sp}\ignorespaces + \MakeDocCorrectHook{#2}\unskip}^^J}} +%% 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 'makedoc.sty' since the +%% \emph{definitions} of the parsing macros fool the same macros \dots +%% +%% \subsection{Commented code} +%% |\TreatAsCode{}| is the opposite to `\TreatAsComment{}': +\newcommand*{\TreatAsCode}[1]{% + \ifPackageCode +% \_empty_code_lines_true + \else + \WriteResult{\string\begin{packagecode}}% + \PackageCodeTrue + \fi + \WriteResult{#1}% +% \WriteResult{\maybe_result_empty_line #1}% +% \let\maybe_result_empty_line\empty +} +%% +%% \subsection{Dealing with empty input lines} +%% |\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 \dots +%% +%% \subsection{Bundling typical things: script commands} +%% \label{sec:script} +%% First practical experiences suggest the following shorthands. +%% They should simplify matters so much that the 'makedoc' script +%% for a single package really should need about five lines only, +%% %% <- TODO check 2009/04/08 +%% and even \emph{they} should be so simple that you should hardly +%% spend a minute about them. +%% +%% |\LaTeXresultFile{}| saves you the extra line for inserting +%% the `\ProvidesFile' line ... no, actually it is 'makedoc' +%% that wants to be mentioned with `\ProvidesFile' ... +%% (otherwise copied from 'fifinddo') \dots +\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]}}% +%% |\MakeDoc{}| preprocesses to render input for +%% \LaTeX, considering what is typical for a \LaTeX\ package as the +%% one here: +\newcommand*{\MakeDoc}[1]{% +%% In case of a ``header'' (see below) we change into ``code mode'': + \ifnum\header_lines>\z@ + \WriteResult{\string\begin{packagecode}}% + \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 +%% file. + \ProcessFileWith{#1}{% + \CountInputLines %% stepping line counter is standard + \make_doc_line_body + \process_line_message}% +%% Currently the ``VERSION HISTORY'' is typeset verbatim +%% (for ``tabbing''), we then must leave ``code mode'' here: + \ifPackageCode + \WriteResult{\string\end{packagecode\@empty}}%% self-doc-trick + \PackageCodeFalse %% TODO both lines makedoc command!? 2009/04/08 + \fi +%% When the file has been processed, certain default settings +%% might be restored---in case another file is processed for the +%% same documentation document: +% \HeaderLines{0}% +% \MainDocParser{\SectionLevelThreeParseInput}%% TODO!? 2009/04/08 +} +%% \subsubsection{File preamble} +%% 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 is declared by +%% |\HeaderLines{}|: +\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 after the ``header'' is set by +%% |\MainDocParser{}|. +\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'. +\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 +%% |\ProcessLineMessage{}| is designed to define a screen +%% (or log) message . +%% % 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{.}} +%% +%% \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 diff --git a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty index c82ae3deaa0..4ea1d7fda1d 100644 --- a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty +++ b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty @@ -1,5 +1,5 @@ \NeedsTeXFormat{LaTeX2e}[1994/12/01] -\ProvidesPackage{niceverb}[2009/02/21 +\ProvidesPackage{niceverb}[2009/04/15 v0.2 minimize \string\verb\space code (UL)] %% Copyright (C) 2009 Uwe Lueck, @@ -32,23 +32,29 @@ \MakeLetter\_ -\newcommand*{\make_iii_other}{\MakeOther\\\MakeOther\{\MakeOther\}} - -%% === Parsimonious version of &\verb === +% \newcommand*{\make_iii_other}{\MakeOther\\\MakeOther\{\MakeOther\}} + %% <- replaced 2009/04/05 +%% === Sloppy variant of &\verb === \newcommand*{\begin_min_verb}{% \relax \ifmmode \hbox \else \leavevmode\null \fi - %% standard, for $$...$$ + %% <- standard, for $$...$$ \bgroup \tt %%%\let\do\MakeOther \dospecials \MakeLetter\_\MakeLetter\@} \newcommand*{\SimpleVerb}[1]{% - %% mainly avoid \verb's noligs list which overrides definitions - %% of some active characters, while cmtt doesn't have any - %% ligatures anyway. +%% Mainly avoid `\verb''s noligs list which overrides definitions +%% of some active characters, while 'cmtt' doesn't have any +%% ligatures anyway. \ifx\protect\@typeset@protect - \begin_min_verb \make_iii_other \MakeActiveLet#1\egroup + \begin_min_verb %%%\make_iii_other %% much usual 2009/04/05 + \let\do\MakeOther \dospecials %% 2009/04/06 + \MakeOther\|%% probably 'niceverb' + \MakeActiveLet#1\niceverb_egroup %% 2009/04/11 + \verb@eol@error %% TODO change message 2009/04/09 \else \string\SimpleVerb \string#1\fi} - -%% === Single quotes make code === +%% 2009/04/11: about `etc.' +\newcommand*{\niceverb_egroup}{\egroup\ifmmode\else\@\fi} +%% +%% === Single quotes typeset meta-code === \newcommand*{\lq_verb}{% \ifx\protect\@typeset@protect \expandafter \lq_double_test @@ -57,7 +63,7 @@ % \expandafter\expandafter\expandafter % \protect_corresp_quotes % \else -% \RqVerb +% \rq_verb % \fi % \fi} \newcommand*{\lq_double_test}{% @@ -69,21 +75,21 @@ \ifx\let_token\lq_verb \endgroup \lq\lq \expandafter \@gobble - %% corresponding right quotes will become ``other'' due to - %% having no space at the left. TODO to be changed with - %% wiki.sty +%% Corresponding right quotes will become ``other'' due to +%% having no space at the left. + %%TODO to be changed with 'wiki.sty'. \else \endgroup % \expandafter \rq_verb \expandafter \SimpleVerb \expandafter \'% \fi} % \newcommand*{\rq_verb}{\SimpleVerb\'} -% \AtBeginDocument{\MakeActiveLet\`\RqVerb} +% \AtBeginDocument{\MakeActiveLet\`\rq_verb} \AtBeginDocument{\MakeActiveLet\`\lq_verb} %% Strings referred to will be code %% TODO to be changed with wiki.sty - -%% === Single mark for reference to commands === +%% +%% === Ampersand typesets meta-code === \newcommand*{\CmdSyntaxVerb}{% \ifx\protect\@typeset@protect \expandafter \cmd_syntax_verb @@ -118,11 +124,8 @@ \def\braces_verb#1{\string{#1\string}\test_more_verb} \def\brackets_verb[#1]{[#1]\test_more_verb} \def\star_verb*{*\test_more_verb} - - -\makeatletter - -%% === Escape makes meta-code === +%% +%% === Escape character typesets meta-code === \DeclareRobustCommand*{\BuildCsSyntax}{% \futurelet\let_token \build_cs_syntax_sp} \newcommand*{\build_cs_syntax_sp}{% @@ -161,50 +164,76 @@ \newcommand*{\EndAutoCmdSyntaxVerb}{\CatCode\\\z@} \newcommand*{\NormalCommand}{} \let\NormalCommand\@nameuse -%% Were tests: + %% Were tests: % \futurelet\LetToken\relax \relax % \show\LetToken \typeout{\ifcat\noexpand\LetToken aa\else x\fi} \newcommand*{\niceverbNoVerbList}{% \begin\end\item\verb\EndAutoCmdSyntaxVerb\NormalCommand - \section\subsection}%% TODO!? - + \section\subsection\subsubsection}%% TODO!? +\providecommand*{\AddToMacro}[1]{% + \expandafter \def \expandafter #1\expandafter} +%% %% === Meta-variables === \def\niceverb_meta#1>{% \mbox{\normalfont\itshape $\langle$#1\/$\rangle$}} %% TODO offer without angles as well \AtBeginDocument{\MakeActiveLet\<\niceverb_meta} %% difference to ltxguide.cls: also outside verbatim - -%% === Hash mark must be code === +%% +%% === Hash mark is code === \newcommand*{\param_verb}[1]{{\tt\##1}} \AtBeginDocument{\MakeActiveLet\#\param_verb} - -%% === Single right quote for &\sf === -%% TODO fails in parentheses due to preserving apostrophes +%% +%% === Single right quote for &\textsf === \newcommand*{\niceverb_rq_sf}{% +% \relax %% in case of \hskip1sp 2009/04/08 + %% but spoils ligature 2009/04/09 \ifx\protect\@typeset@protect \expandafter \niceverb_rq_sf_test \else \rq \fi} - %% introduced another macro just to avoid more sequences - %% of \expandafter ... +%% Another macro just to avoid more sequences of `\expandafter': \newcommand*{\niceverb_rq_sf_test}{% - \ifhmode \ifdim\lastskip>\z@ - \expandafter\expandafter\expandafter \niceverb_rq_sf_exec - %% TODO but after `('!? make \( active, also for \after_cs!? - \else \rq \fi + \ifhmode + \ifdim\lastskip>\z@ + \expandafter\expandafter\expandafter \niceverb_rq_sf_exec + \else + \ifnum\spacefactor=1001 %% in parentheses 2009/04/10 + \expandafter\expandafter\expandafter\expandafter + \expandafter\expandafter\expandafter + \niceverb_rq_sf_exec + \else \rq \fi +% \rq + \fi \else \ifvmode \expandafter\expandafter\expandafter \niceverb_rq_sf_exec \else \rq \fi \fi} +\sfcode`\(=1001 %% enable in parentheses 2009/04/10 {\CatCode\'\active \gdef\niceverb_rq_sf_exec#1'{\textsf{#1}}} -%% TODO to be changed with wiki.sty: + %% TODO to be changed with wiki.sty: \AtBeginDocument{\MakeActiveLet\'\niceverb_rq_sf} -%% TODO \niceverbswitch{}{} (bzw. Doku ohne {}) - + %% TODO \niceverbswitch{}{} (bzw. Doku ohne {}) +%% %% === Leave package mode === -\makeatother \MakeSub\_ \endinput +%% +%% === VERSION HISTORY === + +v0.1 2009/02/21 very first, sent to CTAN +v0.2 2009/04/04 ...NoVerbList: \subsubsection, \AddToMacro, + 2009/04/05 \SimpleVerb makes more other than iii + 2009/04/06 just uses \dospecials + 2009/04/08 debugging code for rq/sf, +\relax + 2009/04/09 +\verb@eol@error, prepared for new doc method, + removed spurious \makeat..., -\relax (ligature), + 2009/04/10 ('-trick + 2009/04/11 \@ after \SimpleVerb + 2009/04/14 noted TODO below + 2009/04/15 change v0.1 to 2009/02/21 + +TODO: choose expansions of active characters by options 2009/04/10 +TODO: &\@tempa and &\_tempa fail 2009/04/14 -- cgit v1.2.3