diff options
Diffstat (limited to 'Master/texmf-dist/tex/latex')
| -rw-r--r-- | Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex | 59 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/nicetext/fifinddo.sty | 254 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/nicetext/makedoc.sty | 314 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg | 32 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/nicetext/niceverb.sty | 751 |
5 files changed, 1139 insertions, 271 deletions
diff --git a/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex b/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex new file mode 100644 index 00000000000..9e5e3dda35a --- /dev/null +++ b/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex @@ -0,0 +1,59 @@ + \makeatletter +\typeout{^^J*fdtxttex.tex* 2010/03/22 txt to TeX by dialogue^^J + (apply \string\MakeDocCorrectHook) + ^^J} + +\RequirePackage{fifinddo} + +\def\MakeDocCorrectHook#1{#1} +\catcode`\_=11 +\def\CorrectionFile{\def\mdoc_corr} +\CorrectionFile{mdoccorr.cfg} +\ResultFile{sample.tex} +\def\InputFile{\def\input_file_name} +\InputFile{sample.txt} +\newif\iftoscreen + +\def\FD_dialogue{% + \typeout{^^J% + ===========================================================^^J% + \string\CorrectionFile{\mdoc_corr} + \space (define \@backslashchar MakeDocCorrectHook)^^J% + \string\InputFile {\input_file_name}^^J% + \string\ResultFile{\result_file_name} + \space\space\space\space\space\space\space + \string\toscreen\iftoscreen true\else false\fi ^^J% + ===========================================================% + }% + \typein[\action]% + {Run with these settings? (Y)es? (C)hange? (Otherwise quit.)}% + \csname action_\action \endcsname +} +\def\run_with_settings{% + \input{\mdoc_corr}% + \WriteProvides + \ProcessFileWith{\input_file_name}{% + \WriteResult{\expandafter \MakeDocCorrectHook + \expandafter{\fdInputLine}}% + \iftoscreen + \typeout{\expandafter \MakeDocCorrectHook + \expandafter{\fdInputLine}}% + \else + \message{.}% + \fi} + \CloseResultFile + \typeout{Done.}% + \FD_dialogue +} +\expandafter\let\csname action_y\endcsname \run_with_settings +\expandafter\let\csname action_Y\endcsname \run_with_settings + +\def\change_settings{% + \typein[\change]{^^JType setting command(s).}% + \change \FD_dialogue} +\expandafter\let\csname action_c\endcsname \change_settings +\expandafter\let\csname action_C\endcsname \change_settings + +\FD_dialogue + +\stop diff --git a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty index 1f03ae4c4ab..5ae6dab9f0c 100644 --- a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty +++ b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty @@ -5,7 +5,7 @@ %% for processing tex(t) files %% (checking, filtering, converting, substituting, expanding, ...) -\def\fileversion{0.3} \def\filedate{2009/04/15} +\def\fileversion{0.31} \def\filedate{2010/03/23} %% This file can be redistributed and/or modified under %% the terms of the LaTeX Project Public License; either @@ -30,7 +30,7 @@ %% %% === Category codes === %% -%% We use the ``underscore'' as ``compound identifier.'' +%% We use the ``underscore" as ``compound identifier." \catcode`\_=11 %% underscore used in control words %% %% |\MakeOther| is a synonym for `\@makeother', needed for matching @@ -50,7 +50,7 @@ %% 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'' +%% 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?): @@ -78,7 +78,8 @@ automatically generated with fifinddo.sty]}}% %% |\ProcessFileWith{<input>}{<loop-body>}| opens a file <input> %% and runs a loop on its lines the main body of which is <loop-body>. -%% When it starts, a new line of <input> is stored as macro +%% When the <loop> starts, a new line of <input> is stored as macro +%% %% <- the <loop> 2010/03/10 %% |\fdInputLine|. \newcommand*{\ProcessFileWith}[2]{% \openin\@inputcheck=#1% @@ -95,6 +96,13 @@ %% <- cf. TeXbook "extended keyboards" up-/downarrow %% -> "math specials", cf. "space specials" \MakeOther\^^I% ASCII horizontal tab -- guessed!? ^^L!? +%% With v3.1, we support non-ASCII: + \count@=128 + \loop + \ifnum\count@<\@cclvi + \catcode\count@=12 + \advance\count@\@ne + \repeat \loop \ifeof\@inputcheck \else \read\@inputcheck to \fdInputLine \ignorespaces #2% @@ -104,13 +112,16 @@ \closein\@inputcheck} %% |\CloseResultFile| closes <output>. \newcommand*{\CloseResultFile}{\immediate\closeout\result_file} -%% Peter Wilson's 'newfile' provides more powerful file handling. +%% +%% TODO: write EOF for debugging!?---%% 2010/03/18 +%% Peter Wilson's \ctanpkgref{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'' === +%% === ``Substring Theory" === %% \begin{flushright}\it %% I wished I could study string theory,\\ %% but I only could study substring theory. @@ -128,9 +139,9 @@ %% special idea. %% %% In order to use `\find' for a test whether <pattern> is in -%% <target>, we build a ``sandbox'' |\find<sand>&|, where <sand> +%% <target>, we build a ``sandbox" |\find<sand>&|, where <sand> %% contains <target> \emph{and additionally} <pattern>---as a -%% ``dummy;'' so `&' delimits the search and `\find' finds +%% ``dummy;" so `&' delimits the search and `\find' finds %% <pattern> either in <target> or somewhere else before `&'. %% %% Consider the simple sandbox |\find<target><pattern>&|. @@ -145,16 +156,21 @@ %% If #2 is \emph{not} empty, <pattern> occurs in <target>---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 +%% `2005-11-29',\footnote{\url{http://ctan.org/pkg/substr}. +%% 'substr' does not change category codes +%% as 'fifinddo' does +%% and uses \cs{@nil} as delimiter instead of +%% our &&.} try +%% (if that version still is installed)\footnote{The ``feature" has +%% been fixed with v1.2 as of 2009/10/20 of +%% 'substr.sty'.} %% \[`\IfSubStringInString{<str1><str2><str1>}{<str1><str2>}{YES}{NO}'\] %% which works \emph{verbatim} as well as considering <str1> and %% <str2> \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} ...}\\ +%% Likewise \texttt{t\string\^ete-\string\`a-t\string\^ete} ...}\\ +%% %% <- `e' was missing 2010/03/17 %% `\IfSubStringInString{AMSTERDAM}{AMSTERD}{YES}{NO}'\\ %% `\IfSubStringInString{TORONTO}{TORON}{YES}{NO}'\\ %% `\IfSubStringInString{bonbon}{bon}{YES}{NO}'\footnote{% @@ -163,10 +179,18 @@ %% (an ape) %% \end{center} %% or `\IfSubStringInString{ionization}{ionizat}{YES}{NO}'.\footnote{% -%% Read 'substr.sty' or try ``normal'' things to convince yourself +%% Read 'substr.sty' or try ``normal" things to convince yourself %% that the syntax indeed is %% &\IfSubStringInString{<pattern>}{<target>}{<yes>}{<no>}.} -%% Same with \LaTeX's internal `\in@': +%% Same with \LaTeX's internal `\in@':\footnote{\cs{in@} has been +%% fixed after my warning on Heiko Oberdiek's proposal---at +%% least in the repository.---On 2009/04/21 +%% I learn from Manuel P\'egouri\'e-Gonnard +%% that the first versions of his 'ted' +%% had a similar bug, fixed on v1.05 essentially like here; +%% Steven Segletes confirms that his 'stringstrings' doesn't +%% suffer the problem (returning positions of substrings and +%% numbers of occurrences).} %% \[`\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} @@ -183,7 +207,9 @@ %% a counterexample <target>. %% %% Therefore, a sandbox must have something between <target> and -%% <pattern>. We choose |\find<target>~<pattern>$&| as standard. +%% <pattern>.\footnote{Must? Actually, I preferred this solution to +%% other ideas like measuring the length of <split2>.} +%% We choose |\find<target>~<pattern>$&| as standard. %% The `$' will be used as an argument delimiter to get rid of the dummy %% <pattern> in <split2>, as well as to decide whether the match was %% in <target> or in the dummy part of the sandbox. @@ -197,14 +223,14 @@ %% 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'' +%% 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} +%% handled by a general ``calling" macro \dots} %% %% TODO 2009/04/15 -%% We use a separate \emph{``name space''} for each of +%% 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 +%% 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 @@ -212,9 +238,9 @@ %% %% 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 +%% \emph{``substring conditional"}. It may read additional arguments %% after the sandbox that store information gathered before. -%% This is especially useful for designing \emph{``expandable''} +%% 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. @@ -222,29 +248,63 @@ %% 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 +%% that contain ``special characters," as when you are looking for +%% %% TODO repetition of single right quote not working 2010/03/19 %% 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 +%% === Meta-Setup === +%% +%% A setup command <setup-cmd> will have the following syntax: +%% \[|<setup-cmd>{<job-id>}[<changes>]{<pattern>}<more-args>|\] +%% <changes> will, in the first instance, be category code changes +%% for reading <pattern> overriding the settings in `\PatternCodes'. +%% They are executed after the latter in a local group. +%% It may be safer to redefine `\PatternCodes' instead +%% of using the optional <changes> argument. +%% +%% A macro +%% \[|\StartFDsetup{<do-setup>}{<job-id>}[<changes>]|\] +%% shared by setup commands +%% may read <job-id> and <changes> for <setup-cmd>. +%% |<do-setup>| will be the macro that reads <pattern> (and more) +%% and processes it. It must contain `\endgroup' to match +%% `\begingroup' from `\FD_prepare_pattern'. +%% <job-id> is stored in a macro |\fdParserId|. +%% The default for <changes> is \emph{nothing}. +\newcommand*{\StartFDsetup}[1]{% + \let\FD_do_setup#1% + \afterassignment\FD_prepare_pattern + \def\fdParserId} +\newcommand*{\FD_prepare_pattern}[1][]{% + \begingroup \PatternCodes #1\FD_do_setup} +%% So <setup-cmd> should be set up about as follows: +%% \begin{quote} +%% `\newcommand*{<setup-cmd>}{\StartFDsetup<do-setup>}'\\ +%% `\newcommand*{<do-setup>}[<args>]{<action>}' +%% \end{quote} +%% <do-setup>'s first argument will be the <pattern> argument +%% of <setup-cmd>. +%% +%% === Setup for 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{<id>}[<changes>]{<pattern>}| -%% starts the definition of a conditional with \emph{identifier} <id> +%% starts the definition of a conditional with identifier <id> %% and pattern <pattern>. <changes> 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{<pattern>}| +%% +\newcommand*{\MakeSubstringConditional} + {\StartFDsetup\mk_substr_cond} +%% +%% `\begingroup' |\mk_substr_cond{<pattern>}| %% TODO!? 2010/03/22 %% can be directly called by other programmer setup commands when -%% `\cond_id' and <pattern> have been read. +%% `\fdParserId' and <pattern> have been read. \def\mk_substr_cond #1{%% #1 pattern string - \endgroup \@namedef{\substr_cond \cond_id}##1#1##2&} + \endgroup \@namedef{\substr_cond \fdParserId}##1#1##2&} +%% %% This really is not \LaTeX. We are starting defining a macro %% `\substr_cond:<id>' in primitive \TeX\ with `\def' in the form %% \[`\def\substr_cond:<id>#1<pattern>#2&'\] @@ -254,7 +314,7 @@ %% (maybe) #3 etc. and the `{<definition text>}' %% just as with primitive \TeX. %% -%% === Set up sandboxes === +%% === Setup for 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 @@ -272,7 +332,7 @@ %% 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'' +%% On the other hand, there is the idea of \emph{``expandable" %% chains of substitutions}. We may, e.g., define a macro, say, %% `\manysubstitutions{<macro-name>}', such that %% `\WriteResult{\manysubstitutions{\fdInputLine}}' @@ -293,7 +353,7 @@ %% `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{<id>}[<changes>]{<pattern>}{<more-args>}| +%% \[|\MakeSetupSubstringCondition{<id>}[<changes>]{<pattern>}{<more-args>}|\] %% % <- TODO allow `%' and ` ' for breaking code lines. %% ---same <id>, <changes>, <pattern> as for %% `\MakeSubstringConditional' (this is bad, there may be @@ -303,21 +363,17 @@ %% <more-args> may contain `{#1}' to store the string that was tested, %% also `{<id>}' for calling repetitions and `{<pattern>}' 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} +\newcommand*{\MakeSetupSubstringCondition} + {\StartFDsetup\mk_setup_substr_cond} %% `\begingroup' |\mk_setup_substr_cond{<pattern>}{<more-args>}| %% can be directly called by other programmer setup commands after -%% `\cond_id' and <pattern> have been read: +%% `\fdParserId' and <pattern> 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}% + \csname \setup_substr_cond \fdParserId \endcsname ##1{% + \make_not_expanding_cs{\substr_cond \fdParserId}% %% 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}% @@ -329,7 +385,7 @@ %% 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} + \expandafter \noexpand \csname #1\endcsname} %% %% === Getting rid of the tildes === %% |\let~\TildeGobbles| can be used to suppress dummy patterns @@ -340,7 +396,7 @@ \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 +%% or other ``total" expansion: %% 2009/04/13 \newcommand{\RemoveDummyPattern}{} \def\RemoveDummyPattern#1~#2${#1} %% |\RemoveDummyPatternArg<macro>{<arg>}| executes %% `\RemoveDummyPattern' in the next argument: @@ -399,13 +455,13 @@ %% (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.) +%% 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.'' +%% tool." %% %% == Programming tools == %% === Tails of conditionals === @@ -415,12 +471,13 @@ %% 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''). +%% 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~=~<split1> empty'' indicates that either the <pattern> +%% %% onwards) %% !? 2009/12/28 +%% on starting with `~'. E.g., +%% ``#1~=~<split1> empty" indicates that either the <pattern> %% starts a line or the line is empty altogether (this must be %% decided by another test). %% @@ -462,18 +519,18 @@ %% === Line counter === %% A \LaTeX\ counter |fdInputLine| may be useful for screen or log %% messages, moreover you can use it to control processing of the -%% <input> file ``from outside,'' not dependent on what the parsing +%% <input> 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 +%% 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 +%% 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 <output> %% which have no counterpart in <input>---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 +%% 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 @@ -491,7 +548,7 @@ \ifnum\c@fdInputLine#1\relax \expandafter \@firstoftwo \else \expandafter \@secondoftwo \fi} %% -%% === The ``identity job'' `LEAVE' === +%% === The ``identity job" `LEAVE' === %% \label{sec:LEAVE} %% The job with identifier |LEAVE| %% \emph{leaves} an (expandable) chain of jobs @@ -516,7 +573,7 @@ %% 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'' +%% 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 @@ -530,7 +587,7 @@ %% 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''!, +%% 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 @@ -555,25 +612,23 @@ %% the recently skipped <split1> %% plus #4 replacing the string <pattern> that was matched. %% -%% Finally, #5 and #6 again ``recall'' <parser> and the sandbox +%% Finally, #5 and #6 again ``recall" <parser> and the sandbox %% builder to which to change in case of no other match. %% +%% \pagebreak[3] %% 2010/03/22 %% % TODO move following up!? 2009/04/11 -%% |\MakeExpandableAllReplacer{<id>}{<pattern>}{<replace>}{<id-next>}| +%% \[|\MakeExpandableAllReplacer{<id>}[<chng>]{<find>}{<replace>}{<id-next>}|\] %% creates sandbox and parser with common identifier <id> and search -%% pattern <pattern>. Each occurrence of <pattern> will be replaced by -%% <replace>. When <pattern> is not found, the sandbox builder for +%% pattern <find>. Each occurrence of <find> will be replaced by +%% <replace>. When <find> is not found, the sandbox builder for %% <id-next> 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. +%% Optional argument <chng> changes category codes locally +%% for reading <find> and <replace>. +%% %% <- added <cat>, <pattern> -> <find> 2010/03/19 +\newcommand*{\MakeExpandableAllReplacer} + {\StartFDsetup\mk_setup_xpdbl_all_repl} \newcommand*{\mk_setup_xpdbl_all_repl}[3]{% %% #1 pattern, #2 substitute, #3 pass to \endgroup @@ -589,7 +644,7 @@ %% 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}% + \make_not_expanding_cs{\substr_cond\fdParserId}% \noexpand\noexpand \make_not_expanding_cs{\setup_substr_cond #3}}}% %% Those internal setup commands start with `\endgroup' to switch back @@ -600,18 +655,35 @@ \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 +%% \[|\PrependExpandableAllReplacer{<id>}[<cat>]{<find>}{<replace>}|\] +%% is hoped to be a slight relief in composing replacement chains. +%% It does something like invoking `\MakeExpandableAllReplacer' +%% with <prev-setup-id> for the last <next-id> argument +%% where <prev-setup-id> is the <id> of the job that was set up most +%% recently. If you have adjacent lines +%% \begin{quote} +%% \leavevmode\hbox to 0pt\bgroup +%% `\MakeExpandableAllReplacer{<id-0>}{<find-0>}{<subst-0>}{LEAVE}'% +%% \hss\egroup \\ +%% `\PrependExpandableAllReplacer{<id-1>}{<find-1>}{<subst-1>}'\\ +%% `\PrependExpandableAllReplacer{<id-2>}{<find-2>}{<subst-2>}' +%% \end{quote} +%% and call <id-2>, it will call <id-1>, and the latter will call +%% <id-0>. So you can reorder the chain my moving `\Prepend'... lines. +\newcommand*{\PrependExpandableAllReplacer}{% + \let\fdParserId_before\fdParserId + \StartFDsetup\prep_xpdbl_all_repl} +\newcommand*{\prep_xpdbl_all_repl}[2]{% + \mk_setup_xpdbl_all_repl{#1}{#2}{\fdParserId_before}}% %% %% == 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 +%% ``in the sense of `\input'", as opposed to just reading %% the file line by line to a macro like `\fdInputLine'. %% %% == Pondered == @@ -664,7 +736,7 @@ v0.2 2009/04/05 counter fdInputLine, \ProvidesFile moved from \ProcessInputWith, typos, \WriteProvides message `with' 2009/04/10 \make_not_expanding_cs - DISCOVERED ``IF SUBSTRING'' ALGORITHM WRONG + DISCOVERED ``IF SUBSTRING" ALGORITHM WRONG (<str1><str2><str1> in <str1><str2>) v0.3 2009/04/11 SOME THINGS GIVEN UP EARLIER WILL BE REMOVED, TO BE STORED IN THE COPY AS OF 2009/04/10 @@ -674,3 +746,15 @@ v0.3 2009/04/11 SOME THINGS GIVEN UP EARLIER WILL BE REMOVED, plain `...', `cf.', `etc.' for `mdcorr.cfg' 2009/04/13 \RemoveTilde... 2009/04/15 reworked text, same mistake \in@ +v0.31 2009/04/21f. comments on ted, stringstrings + 2009/12/28 "onwards)" !? "safer", not "more safe" + 2010/03/10 the loop starts + 2010/03/17 corr. t^ete; set up -> setup for + 2010/03/18 TODO EOF, ctan.org/pkg/newfile; non-ASCII + 2010/03/19 extended description of \MakeExpandableAll...; + '' -> " + 2010/03/20 \ctanpkgref + 2010/03/22 \StartFDsetup, \Prepend... + 2010/03/23 URL for `substr.sty' + +TODO: cleveref 2010/03/18 diff --git a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty index 7fb78c662a1..948c1b59b5e 100644 --- a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty +++ b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty @@ -1,10 +1,10 @@ %% Macro package `makedoc.sty' for LaTeX2e, -%% copyright (C) 2009 Uwe L\"uck, +%% 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.2} \def\filedate{2009/04/13} +\def\fileversion{0.3} \def\filedate{2010/03/19} %% This file can be redistributed and/or modified under %% the terms of the LaTeX Project Public License; either @@ -22,30 +22,33 @@ \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'! +%% |\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. +%% ``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 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. +%% 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} +%% \subsection{&\MakeDocCorrectHook\ (\dqtd{`txt2TeX'})} %% |\MakeDocCorrectHook| is predefined to leave its argument without %% the enclosing braces, otherwise unchanged: \let\MakeDocCorrectHook\@firstofone @@ -57,7 +60,8 @@ %% '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. +%% \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'. @@ -70,24 +74,25 @@ %% midst of preprocessing a package documentation. %% %% \subsection{Distinguish 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 `%% ' are typeset in \TeX\ quality -%% under the present release. Lines just containing `%%' +%% 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 \dots +%% however not in the present release ... %% -%% The parsing macros must be set up reading `%' and ` ' as ``other'' +%% 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'' +%% +%% 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 @@ -97,7 +102,6 @@ %% #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 @@ -113,8 +117,8 @@ % \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; +%% |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} %% Alternative still to be considered: @@ -122,28 +126,72 @@ % \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}% +} +%% %% \subsection{Dealing with comments} %% |\TreatAsComment{<text>}| writes <text> to the documentation -%% file. If we had ``package code'' (were in ``code mode'') so far, +%% 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}}% + \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). %% +%% 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' \dots %% todo 2009/04/08 +%% 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. +%% 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} @@ -165,6 +213,7 @@ %% 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 ~========&} @@ -178,12 +227,12 @@ %% % 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.'' +%% 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,'' +%% 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 @@ -203,25 +252,42 @@ %% to the general comment detector. %% %% |\WriteSection{<command>}{<text>}| replaces an input line -%% with a line \[`<command>{\hspace{1sp}\ignorespaces <text>\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. +%% 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{\string\hspace{1sp}\ignorespaces - \MakeDocCorrectHook{#2}\unskip}^^J}} + \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. +%% 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 +%% 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>}': @@ -229,7 +295,7 @@ \ifPackageCode % \_empty_code_lines_true \else - \WriteResult{\string\begin{packagecode}}% + \WriteResult{\string\begin{mdPackageCode}}% \PackageCodeTrue \fi \WriteResult{#1}% @@ -237,45 +303,46 @@ % \let\maybe_result_empty_line\empty } %% -%% \subsection{Dealing with empty input lines} +%% \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} +%% 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 +%% There is a better policy---didn't work so far ... %% %% \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. +%% Practical experience suggested the following shorthands, +%% combining commands from 'makedoc' and 'fifinddo'. %% -%% |\LaTeXresultFile{<output>}| saves you the extra line for inserting -%% the `\ProvidesFile' line ... no, actually it is 'makedoc' +%% \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') \dots +%% %% (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'': +%% In case of a ``header" (see below) we change into ``code mode": \ifnum\header_lines>\z@ - \WriteResult{\string\begin{packagecode}}% + \WriteResult{\string\begin{mdPackageCode}}% \PackageCodeTrue %% TODO both lines makedoc command!? %% 2009/04/08 \else \PackageCodeFalse \fi @@ -286,10 +353,12 @@ \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: +%% 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{packagecode\@empty}}%% self-doc-trick + \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 @@ -298,13 +367,23 @@ % \HeaderLines{0}% % \MainDocParser{\SectionLevelThreeParseInput}%% TODO!? 2009/04/08 } -%% \subsubsection{File preamble} -%% A \LaTeX\ package typically has a ``header'' or ``preamble'' +%% |\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? +%% 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} @@ -314,12 +393,15 @@ \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 +%% 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'. +%% `\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{% @@ -327,7 +409,8 @@ {\let\make_doc_line_body\main_doc_parser \make_doc_line_body}% %% switch to deciding {\TreatAsCode{\fdInputLine}}} %% header verbatim -%% |\ProcessLineMessage{<command>}| is designed to define a screen +%% \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'. @@ -348,9 +431,83 @@ % \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} @@ -365,3 +522,22 @@ v0.2 2009/04/05 \OnEmptyInputLine, \NoEmptyCodeLines 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 '' -> " diff --git a/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg b/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg new file mode 100644 index 00000000000..1d3ba475e95 --- /dev/null +++ b/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg @@ -0,0 +1,32 @@ +\ProvidesFile{mdoccorr.cfg}[2010/03/23 + local typographical corrections + with `makedoc.sty'] +%% ... also demonstrates 'niceverb.sty'. Some sanitizing: +%% +\renewcommand*{\PatternCodes}{\MakeOther\\\MakeOther\ } +%% +%% |\MakeExpandableAllReplacer{<id>}{<find>}{<subst>}{<id-next>}|% +%% \footnote{Yes, +%% &\MakeExpandableAllReplacer{<id>}{<find>}{<subst>}{<id-next>}.} +\MakeExpandableAllReplacer{etc}{etc. }{etc.\ }{LEAVE} +%% So you can keep inter-sentence space after `etc.' +%% by a code line break. +%% +%% |\PrependExpandableAllReplacer{<id>}{<find>}{<subst>}|: +\PrependExpandableAllReplacer{cf}{cf. }{cf.\ } %% corr. 2010/03/23 +%% ... but think of `cf.~'. Don't leave `cf.' at code line end! +\PrependExpandableAllReplacer{dots}{...}{$\dots$} +%% ... chain starts here, and here |\MakeDocCorrectHook| enters: +\renewcommand*{\MakeDocCorrectHook}[1] + {\ProcessStringWith{#1}{dots}} +%% +\renewcommand*{\PatternCodes}{\fdPatternCodes} +%% ... restores 'fifinddo' default. +\endinput + +HISTORY +2009/04/05 with makedoc v0.2 +2010/03/11 broke some too long code lines +2010/03/16 rendered `mdoccorr.cfg' +2010/03/22 try \Prepend... +2010/03/23 corrected `cf' diff --git a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty index 4ea1d7fda1d..823093a1020 100644 --- a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty +++ b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty @@ -1,8 +1,8 @@ \NeedsTeXFormat{LaTeX2e}[1994/12/01] -\ProvidesPackage{niceverb}[2009/04/15 v0.2 - minimize \string\verb\space code (UL)] +\ProvidesPackage{niceverb}[2010/03/23 v0.32 + minimize doc markup (UL)] -%% Copyright (C) 2009 Uwe Lueck, +%% Copyright (C) 2009, 2010 Uwe Lueck, %% http://www.contact-ednotes.sty.de.vu %% -- author-maintained in the sense of LPPL below -- %% @@ -17,98 +17,233 @@ %% %% http://www.contact-ednotes.sty.de.vu %% -%% === Switching category codes === -\providecommand{\CatCode}{\catcode`} -% \providecommand*{\MakeActive}[1]{\CatCode#1\active} -\providecommand*{\MakeAlign} [1]{\CatCode#14\relax} -\providecommand*{\MakeLetter}[1]{\CatCode#111\relax} -\providecommand*{\MakeOther} [1]{\CatCode#112\relax} -\providecommand*{\MakeSub} [1]{\CatCode#18\relax} - -\newcommand*{\MakeActiveLet}[2]{%% cf. \@sverb & \do@noligs - \CatCode#1\active +%% === Switching Category Codes === +%% v0.3 introduces `\AssignCatCodeTo' and `\MakeNormal'. +%% +%% |\CatCode{\<character>}| +%% (or simply |\CatCode\<character>|) +%% saves one token per use and works when the category code +%% of \qtd{&`} (``single left quote") has changed. +\newcommand*{\CatCode}{\catcode`} +% \newcommand*{\CatCode}[1]{\catcode`#1 } %% no better 2010/02/27 +%% With |\AssignCatCodeTo{<number>}{\<char>}|, +%% `\CatCode' may still be useful for displaying +%% (debugging or playing). +%% Note that `\<char>' is the {\it second} argument here. +\newcommand*{\AssignCatCodeTo}[2]{\catcode`#2=#1\relax} +%% |\MakeLetter\<char>| is used for \emph{private letters}, i.e., +%% to allow <char> in ``internal", non-user control sequences +%% ({\it\TeX book} Chap.\,3). +%% |\MakeOther| is just a different implementation of +%% \LaTeX's \cs{@makeother}. +\newcommand*\MakeLetter{\AssignCatCodeTo{11}} +\def \MakeOther {\AssignCatCodeTo{12}} +%% ... overriding 'fifinddo' if ... %% TODO 2010/03/12 +%% +%% |\MakeActive\<char>| just revives the meaning of <char> +%% it had most recently +%% (as an &\active character ... +%% maybe ``Undefined control sequence" unless ...) +%% This is fine for reviving 'niceverb' functionality +%% after having disabled it by `\MakeNormal'\linebreak[0]---provided +%% no other package used <char> actively in the meantime ... +\providecommand*{\MakeActive}{\AssignCatCodeTo\active} %% used v0.3 +%% We take a copy |\MakeActiveHere| of `\MakeActive' +%% as the latter may become a dangerous thing for compatibility +%% with 'hyperref'. +\@ifdefinable\MakeActiveHere{% + \let\MakeActiveHere\MakeActive} + %% <- TODO aliascid + elsewhere 2010/03/12 +%% |\MakeActiveLet\<char><macro name>| activates <char> +%% and then gives it the meaning of <macro name>. +\newcommand*{\MakeActiveLet}[2]{%% cf. \@sverb/\do@noligs (doc.sty) + \MakeActiveHere#1% %% 2010/03/12 \begingroup \lccode`\~`#1\relax \lowercase{\endgroup \let~#2}} - +%% We take a copy |\MakeActiveLetHere| as well. +\@ifdefinable\MakeActiveLetHere{% + \let\MakeActiveLetHere\MakeActiveLet} +%% %% |\MakeAlign\&| can be used to restore the meaning of `&' after we +%% %% have made it `\active'. +%% % \providecommand*{\MakeAlign} {\AssignCatCodeTo4} +%% We use the ``underscore" as a private letter +%% (the \LaTeX2 Project Team likes it as well). +%% Its usual meaning can be restored by |\MakeNormal\_| +%% For restoring the usual category codes of \TeX's special +%% characters later, we store them now. +%% (I.e., these characters are listed in the macro `\dospecials' +%% that expands to +%% $$\mbox{\tt\def\do{\string\do\unskip\string}\dospecials}$$ +%% their category codes are +%% {\AssignCatCodeTo{6}{\#}% +%% \AssignCatCodeTo{3}{\$}%% fifinddo-interference!? TODO 2010/02/27 +%% \AssignCatCodeTo{4}{\&}%% fifinddo-interference!? TODO 2010/02/27 +%% \def\do#1{\def\do##1{, +%% \the\CatCode##1}\the\CatCode#1}\dospecials} +%% respectively; ``end of line", ``ignored", ``letter", ``other", and +%% ``invalid" are missing---cf. {\it \TeX book} Chap.\,7.) +\def\do#1{\expandafter + \chardef \csname normal_catcode_\string#1\expandafter \endcsname + \CatCode#1\relax} +\dospecials +%% Tests: +%% ``normal category code" of `\' is +%% \expandafter\the\csname normal_catcode_\string\\\endcsname, +%% ``normal category code" of `$' is +%% \expandafter\the\csname normal_catcode_\string\$\endcsname; +%% ``normal category code" of `&' is +%% \expandafter\the\csname normal_catcode_\string\&\endcsname.%%% +%% \footnote{\LaTeX's \cs{nfss@catcodes} is similar, +%% but it makes space-like characters ignored. +%% Also cf. 'ltfinal.dtx'. +%% TODO: &\RestoreNormalCatcodes.} %% 2010/03/06 +%% +%% Here we switch to the ``underscore" as a ``letter" indeed +%% (for the rest of the package): \MakeLetter\_ % \newcommand*{\make_iii_other}{\MakeOther\\\MakeOther\{\MakeOther\}} %% <- replaced 2009/04/05 -%% === Sloppy variant of &\verb === +%% |\MakeNormal\<char>| saves you from remembering ... +\newcommand*{\MakeNormal}[1]{% + \@ifundefined{\norm_catc_str#1}% + {\MakeOther#1}% + {\AssignCatCodeTo{\csname\norm_catc_str#1\endcsname}#1}} +\newcommand*{\norm_catc_str}{normal_catcode_\string} + %% TODO add ^^I and ^^M +%% We take a copy |\MakeNormalHere| of `\MakeNormal' as +%% with `\MakeActive'. +\@ifdefinable\MakeNormalHere{\let\MakeNormalHere\MakeNormal} +%% +%% === Robustness by &\IfTypesetting === +%% It seems we need some own ways to achieve various +%% compatibilities---using |\IfTypesetting{<if>}{<unless>}|. +%% It also saves some `\expandafter's. +\providecommand*{\IfTypesetting}{% +% \relax +%% This `\relax' suppressed ligatures of single right quotes! +%% %% removed 2010/03/23 + \ifx \protect\@typeset@protect + \expandafter \@firstoftwo + \else \expandafter \@secondoftwo \fi} +%% +%% === &\NVerb === +%% `\begin_min_verb' is a beginning shared by some macros here. +%% It begins like \LaTeX's `\verb', apart from the final `\tt'. \newcommand*{\begin_min_verb}{% \relax \ifmmode \hbox \else \leavevmode\null \fi - %% <- standard, for $$...$$ - \bgroup \tt %%%\let\do\MakeOther \dospecials - \MakeLetter\_\MakeLetter\@} -\newcommand*{\SimpleVerb}[1]{% + \bgroup \tt} +%% |\NVerb<char><code><char>| +\newcommand*{\NVerb}{% + \_no_nice_meta_verb_false \nice_maybe_meta_verb} +%% |\HardNVerb<char><code><char>| does not recognize meta-variables: +\newcommand*{\HardNVerb}{% + \_no_nice_meta_verb_true \nice_maybe_meta_verb} +\newif\if_no_nice_meta_verb_ +\newcommand*{\nice_maybe_meta_verb}[1]{% %% 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 %% much usual 2009/04/05 - \let\do\MakeOther \dospecials %% 2009/04/06 - \MakeOther\|%% probably 'niceverb' - \MakeActiveLet#1\niceverb_egroup %% 2009/04/11 + \IfTypesetting{% + \begin_min_verb + \let\do\MakeOther \dospecials +%% Turn off 'niceverb' specials: + \MakeOther\|\MakeOther\`\MakeOther\'% + \if_no_nice_meta_verb_\MakeOther\<\fi + \MakeActiveLetHere #1\niceverb_egroup \verb@eol@error %% TODO change message 2009/04/09 - \else \string\SimpleVerb \string#1\fi} -%% 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 - \else \lq \fi} -% \ifcat\noexpand'\noexpand~% -% \expandafter\expandafter\expandafter -% \protect_corresp_quotes -% \else -% \rq_verb -% \fi -% \fi} + }{\string\NVerb \string#1}} +%% 2009/04/11: about `etc.' [preceding a box!? 2010/03/14] +\newcommand*{\niceverb_normal_egroup}{\egroup \ifmmode\else\@\fi} +\@ifdefinable\niceverb_egroup + {\let\niceverb_egroup\niceverb_normal_egroup} +%% +%% === Single Quotes Typeset Meta-Code === +%% |\LQverb| will be a ``permanent alias" +%% for the active left single quote. +%% +%% The verbatim feature must not act when another single left +%% quote is ahead---we assume a double quote is intended then +%% (thus the left quote feature does not allow to typeset +%% something verbatim that starts with a single left quote). +%% Rather, double quotes should be typeset then. +%% In page headers, a `\protect' may be in the way. +%% (A hook for `\relax'ing certain things in +%% `\markboth' and `\markright' would have been an alternative.) +\MakeActive\` + \newcommand*{\LQverb}{% + \IfTypesetting{\lq_double_test}{\protect`}} +\MakeOther\` \newcommand*{\lq_double_test}{% - %% test settles next catcode, better switch to ``other'' - %% in advance: - \begingroup \let\do\MakeOther \dospecials +%% This test settles the next catcode, so better switch to ``other" +%% in advance (won't harm if left quote isn't next): + \begingroup + \let\do\MakeOther \dospecials + \MakeOther\|%% 2010/03/09! \futurelet\let_token \lq_double_decide} \newcommand*{\lq_double_decide}{% - \ifx\let_token\lq_verb - \endgroup - \lq\lq \expandafter \@gobble -%% Corresponding right quotes will become ``other'' due to + \ifx\let_token\LQverb + \endgroup + ``\expandafter \@gobble +%% Corresponding right quotes will become ``other" due to %% having no space at the left. - %%TODO to be changed with 'wiki.sty'. +%% TODO to be changed with 'wiki.sty'. \else + \ifx\let_token\protect + \expandafter\expandafter\expandafter \lq_double_decide_ii + \else \endgroup -% \expandafter \rq_verb - \expandafter \SimpleVerb \expandafter \'% - \fi} -% \newcommand*{\rq_verb}{\SimpleVerb\'} -% \AtBeginDocument{\MakeActiveLet\`\rq_verb} -\AtBeginDocument{\MakeActiveLet\`\lq_verb} - %% Strings referred to will be code - %% TODO to be changed with wiki.sty -%% -%% === Ampersand typesets meta-code === -\newcommand*{\CmdSyntaxVerb}{% - \ifx\protect\@typeset@protect - \expandafter \cmd_syntax_verb - \else %% thinking of .aux only - \string\CmdSyntaxVerb \expandafter \string + \expandafter\expandafter\expandafter \NVerb + \expandafter\expandafter\expandafter \'% + \fi \fi} +%% `\lq_double_decide_ii' continues test behind `\protect'. +\newcommand*{\lq_double_decide_ii}[1]{% + \futurelet\let_token \lq_double_decide} +%% +%% === Ampersand (or &\cstx) Typesets Meta-Code === +%% |\CmdSyntaxVerb| will be a permanent alias for the active `&'. +\MakeActive\& + \newcommand*{\CmdSyntaxVerb}{% + \IfTypesetting{% + \begin_min_verb +%% v0.3 moves the previous line from &\cmd_syntax_verb +%% %% <- shows bug is fixed 2010/03/09 +%% where it is too late to establish private letters +%% according to next line which was in `\begin_min_verb' +%% earlier---an important bug fix! + \MakeLetter\@\MakeLetter\_% + \cmd_syntax_verb + }{\protect&\string}} +\MakeNormal\& \newcommand*{\cmd_syntax_verb}[1]{% - \begin_min_verb \string#1\futurelet\let_token \after_cs} - -\AtBeginDocument{\MakeActiveLet\&\CmdSyntaxVerb} - %% not needed with \Auto... OTHERWISE useful in args! - %% TODO \MakeAmpCmdSyntax - %% TODO \let\endcell& (wie \endline, \endgraf) \MakeEndCell + \string#1\futurelet\let_token \after_cs} +%% However, `&' (or `\CmdSyntaxVerb') +%% may fail with private letters +%% (there should be a hook for them), %% TODO 2010/02/28 +%% especially in \emph{macro arguments} %% 2010/03/05 +%% and with 'hyperref' in titles of %% 2010/03/11 +%% \emph{sections bearing \cs{label}s}, +%% so we provide something like |\cs{<characters>}| from 'doc.sty'. +\DeclareRobustCommand*{\cs}[1]{% + \begin_min_verb \backslash_verb #1\egroup} +\newcommand*{\backslash_verb}{\char`\\} +%% Moreover, typing `&\par' in ``short" \emph{macro arguments} +%% fails, you better type `\cs{par}' then. Likewise, +%% `\cs{if<letters>}' and `\cs{fi}' is safer in case +%% you want to skip some part of the documentation +%% (e.g., a package option skips commented code) +%% by \cs{if}`<letters>'\cs{fi}. +%% Finally, there will be PDF bookmarks support for `\cs' +%% rather than for a real `&' or `\CmdSyntaxVerb' analogue like +%% |\cstx{<charcters>}*[<opt>]{<mand>}| as follows. +\DeclareRobustCommand*{\cstx}[1]{% %% corr. 2010/03/17 + \begin_min_verb \backslash_verb #1\futurelet\let_token \after_cs} \newcommand*{\after_cs}{% \ifcat\noexpand\let_token a\egroup \space \else \expandafter \decide_verb \fi} \newcommand*{\test_more_verb}{\futurelet\let_token \decide_verb} \newcommand*{\decide_verb}{% -% \show\let_token \jumpteg_on_with\bgroup\braces_verb \jumpteg_on_with[\brackets_verb \jumpteg_on_with*\star_verb @@ -118,14 +253,22 @@ %% or \MakeLetter\( etc. ... or \xspace \newcommand*{\jumpteg_on_with}[2]{% \ifx\let_token#1\do_jumpteg_with#2\fi} - %% TODO cf. xfor, xspace (break@loop); - %% \DoOrBranch#1...#1 or so +%% TODO cf. 'xfor', 'xspace' (&\break@loop); +%% `\DoOrBranch#1...#1' or so. %% found 2010/03/05 \def\do_jumpteg_with#1#2\egroup{\fi#1} \def\braces_verb#1{\string{#1\string}\test_more_verb} \def\brackets_verb[#1]{[#1]\test_more_verb} \def\star_verb*{*\test_more_verb} + %% not needed with \Auto... OTHERWISE useful in args! +%% %%2010/03/15: +%% As 'latex.ltx' has `\endgraf' as a permanent alias for the +%% primitive version of `\par' and `\endline' for `\cr', +%% we offer |\endcell| as a replacement for the original `&': +\let\endcell& %% -%% === Escape character typesets meta-code === +%% === Escape Character Typesets Meta-Code === +%% |\BuildCsSyntax| will be a permanent alias for the active escape +%% character. \DeclareRobustCommand*{\BuildCsSyntax}{% \futurelet\let_token \build_cs_syntax_sp} \newcommand*{\build_cs_syntax_sp}{% @@ -141,7 +284,7 @@ \newcommand*{\decide_more_cs}{% \ifcat\noexpand\let_token a\expandafter \add_to_cs \else - \MakeSub\_\MakeOther\@% + \MakeNormalHere\_\MakeOther\@% \expandafter \in@ \expandafter {\csname \string_built \expandafter \endcsname \expandafter}\expandafter{\niceverbNoVerbList}% @@ -149,7 +292,7 @@ \csname \string_built \expandafter\expandafter\expandafter \endcsname \else - \begin_min_verb \@backslashchar\string_built + \begin_min_verb \backslash_verb\string_built \expandafter\expandafter\expandafter \test_more_verb \fi \fi} @@ -159,66 +302,393 @@ %% TEST TODO fuer xspace!? (\ifin@) \newcommand*{\add_to_cs}[1]{% \edef\string_built{\string_built#1}\test_more_cs} -\newcommand*{\AutoCmdSyntaxVerb}{\MakeActiveLet\\\BuildCsSyntax} - %% TODO or \niceverbswitch... - +%% +%% |\AutoCmdSyntaxVerb| starts, |\EndAutoCmdSyntaxVerb| \emph{ends} +%% ``auto mode." +\newcommand*{\AutoCmdSyntaxVerb}{% + \MakeActiveLetHere\\\BuildCsSyntax} \newcommand*{\EndAutoCmdSyntaxVerb}{\CatCode\\\z@} +%% |\NormalCommand{<characters>}| executes `\<characters>' +%% in ``auto mode." \newcommand*{\NormalCommand}{} \let\NormalCommand\@nameuse - %% Were tests: +%% %% 2010/03/11: +%% Once I may want to use this feature in {\it Wikipedia}-like +%% section titles as supported by 'makedoc', yet I cannot really +%% apply the present feature soon, so this must wait ... +%% (There is a special problem with `\newlabel' and 'hyperref' ...) +%% +%% Former tests: % \futurelet\LetToken\relax \relax % \show\LetToken \typeout{\ifcat\noexpand\LetToken aa\else x\fi} - +%% +%% |\niceverbNoVerbList| is the list of macros that will be +%% \emph{executed} instead of being typeset. \newcommand*{\niceverbNoVerbList}{% \begin\end\item\verb\EndAutoCmdSyntaxVerb\NormalCommand - \section\subsection\subsubsection}%% TODO!? -\providecommand*{\AddToMacro}[1]{% - \expandafter \def \expandafter #1\expandafter} + \section\subsection\subsubsection} %% TODO!? +%% |\AddToMacro{\niceverbNoVerbList}{<macros>}| can be used to +%% add <macros> to that list. +\providecommand*{\AddToMacro}[2]{% %% TODO move to ... 2010/03/05 + \expandafter \def \expandafter #1\expandafter {#1#2}} + %% <- was very wrong 2010/03/18 +%% ``Auto mode" probably ain't mean a thing if it ain't invoked using +%% \[|\AutoCmdInput{<file>}|\] for typesetting <file> in ``auto mode:" +\newcommand*{\AutoCmdInput}[1]{% +%% I am not yet sure whether `\input' etc. should be in the exception +%% list permanently: %% TODO 2010/03/18 + \begingroup + \AddToMacro\niceverbNoVerbList{\ProvidesFile\endinput}% + %% <- TODO? 2010/03/18 + \AutoCmdSyntaxVerb + \input{#1}% + \EndAutoCmdSyntaxVerb + \endgroup +} %% -%% === Meta-variables === -\def\niceverb_meta#1>{% +%% === Meta-Variables === +%% |\MetaVar<var-id>>| will be a permanent alias for the active \qtd{&<}. +\def\MetaVar#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 is code === -\newcommand*{\param_verb}[1]{{\tt\##1}} -\AtBeginDocument{\MakeActiveLet\#\param_verb} -%% -%% === 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} +%% As opposed to 'ltxguide.cls', this works outside verbatim as well. +%% +%% === Hash Mark is Code === +%% |\HashVerb<digit>| will be a permanent alias for the active hash mark. +\newcommand*{\HashVerb}[1]{{\tt\##1}} +%% +%% === Single Right Quotes for &\textsf === +%% |\RQsansserif| will be a permanent alias for the active single +%% right quote. +%% +%% The basic problem with the ``single right quote feature" +%% is that a single right quote may be meant to be an apostrophe. +%% This is certainly the case at the right of a letter. +%% On the other hand, we assume that it is \emph{not} an apostrophe +%% (i)~in vertical mode (opening a new paragraph), +%% (ii)~after a horizontal skip. +%% +%% For page headers, in expanding without typesetting, +%% the expansion of `\RQsansserif' must contain another active +%% single right quote.{\sloppy\par} +\MakeActive\' + \newcommand*{\RQsansserif}{% + \IfTypesetting{\niceverb_rq_sf_test}{\protect'}} +\MakeOther\' %% 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 + \expandafter\expandafter\expandafter \DoRQsansserif \else - \ifnum\spacefactor=1001 %% in parentheses 2009/04/10 + \ifnum\niceverb_spacefactor \expandafter\expandafter\expandafter\expandafter \expandafter\expandafter\expandafter - \niceverb_rq_sf_exec - \else \rq \fi -% \rq + \DoRQsansserif + \else '\fi \fi \else \ifvmode - \expandafter\expandafter\expandafter \niceverb_rq_sf_exec - \else \rq \fi + \expandafter\expandafter\expandafter \DoRQsansserif + \else '\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: -\AtBeginDocument{\MakeActiveLet\'\niceverb_rq_sf} - - %% TODO \niceverbswitch{<mode>}{<on/off>} (bzw. Doku ohne {}) +%% |\DoRQsansserif| %% 2010/03/10 +%% is \emph{another} (possible) alias for the +%% active single right quote, see below. +\MakeActive\' + \@ifdefinable\DoRQsansserif + {\def\DoRQsansserif#1'{\textsf{#1}}} +\MakeOther\' +%% The following cases are typical and cannot be decided by the +%% previous criteria: +%% (i)~parenthesis, (ii)~footnotes and after ``horizontal" +%% environments like `\[<math>\]', (iii)~section titles, +%% (iv)~`\noindent'. +%% We introduce some dangerous tricks---redefinitions of +%% % \LaTeX's internals `\@footnotetext' and `\@sect' +%% %% <- 2010/03/16 -> +%% \LaTeX's internal `\@sect' and of \TeX's primitives +%% `\noindent' and `\ignorespaces' as well as by +%% a signal `\spacefactor' value of 1001. +%% In page headers, \LaTeX\ equips the single right quote with the +%% meaning of `\active@math@prime' which must be overridden. +\newcommand*{\nvAllowRQSS}{% + \MakeActiveLetHere\'\RQsansserif + \niceverb_ignore} %% 2010/03/16 +%% These and the entire right quote functionality are +%% activated by %% removed todo 2010/03/10 +%% \[|\nvRightQuoteSansSerif| +%% \mbox{\quad and disabled by\quad} +%% |\nvRightQuoteNormal|\]---at +%% `\begin{document}'---where we collect previous settings---or +%% later: +\AtBeginDocument{% + \edef\before_niceverb_parenthesis{\the\sfcode`\(}% + \let \before_niceverb_ignore \ignorespaces %% 2010/03/16 + \let \before_niceverb_sect \@sect + \let \before_niceverb_noindent \noindent} %% 2010/03/08 +%% We assume that `\@sect' has the same +%% % We assume that `\@footnotetext' and `\@sect' have the same +%% parameters there as in \LaTeX\ +%% (even if redefined by another package, like 'hyperref'). +\def\niceverb_sect#1#2#3#4#5#6[#7]#8{% + \before_niceverb_sect{#1}{#2}{#3}{#4}{#5}{#6}% + [{\protect\nvAllowRQSS #7}]% + {\protect\nvAllowRQSS #8}} +%% 2010/03/20: +\newcommand*{\niceverb_spacefactor}{\spacefactor=1001\relax} +\newcommand*{\niceverb_noindent}{% + \before_niceverb_noindent \niceverb_spacefactor} +\newcommand*{\niceverb_ignore}{% + \ifhmode \niceverb_spacefactor \fi \before_niceverb_ignore} %% -%% === Leave package mode === -\MakeSub\_ - +%% Here are the main switches: +\newcommand*{\nvRightQuoteSansSerif}{% + \MakeActiveLet\'\RQsansserif + \sfcode`\(=1001 %% enable in parentheses 2009/04/10 +%% I also added \HardNVerb+\sfcode`/=1001+ in the preamble +%% of 'makedoc.tex'. %% 2010/03/15 +% \let\@footnotetext\niceverb_footnotetext + \let\ignorespaces\niceverb_ignore %% 2010/03/16 + \let\@sect\niceverb_sect + \let\noindent\niceverb_noindent} %% 2010/03/08 +\newcommand*{\nvRightQuoteNormal}{% + \MakeNormal\'% %% 2010/03/21 + \sfcode`\(=\before_niceverb_parenthesis\relax + \let\ignorespaces\before_niceverb_ignore %% 2010/03/16 + \let\@sect\before_niceverb_sect + \let\noindent\before_niceverb_noindent} %% 2010/03/08 +%% |\nvAllRightQuotesSansSerif| %% 2010/03/10 +%% (after `\begin{document}'!) +%% forces the `\textsf' feature +%% \emph{without} testing for apostrophes. You then must be +%% sure---DANGER! CARE!---to +%% use \qtd{&\rq} only for obtaining an apostrophe and the +%% double quote character \qtd{&"} for closing double quotes, +%% or our `\dqtd{<text>}' for the entire quoting. +\newcommand*{\nvAllRightQuotesSansSerif}{% + \nvRightQuoteNormal + \MakeActiveLet\'\DoRQsansserif} +%% I started v0.31 (signal `\sfcode'=1000, lowercase letters +%% get `\sfcode'=1001) because +%% \NVerb+\href{http://ctan.org/pkg/<pkg>}{<pkg>}+ failed. +%% However, what I actually needed was |\ctanpkgref{<pack-name>}|: +\DeclareRobustCommand*{\ctanpkgref}[1]{% + \href{http://ctan.org/pkg/#1}{\textsf{#1}}} +%% +%% === Command-Highlighting Boxes === +%% With v0.3, we include one kind of command syntax boxes +%% whose <content> is (in 'niceverb' syntax) +%% delimited as \GenCmdBox+|<content>|+. +%% %% 2010/03/14: +\newsavebox\niceverb_savebox +%% |\GenCmdBox<char><content><char>}| works like +%% `\NVerb<char><content><char>' except putting the latter's result +%% into a framed (or coloured or ...) box.{\sloppy\par} +\newcommand*{\GenCmdBox} {\_no_nice_meta_verb_false \gen_cmd_box} +%% |\HardVerbBox| is a variant of `\GenCmdBox' with the meta-variable +%% feature disabled +%% (for the documentation of the present package). +\newcommand*{\HardVerbBox}{\_no_nice_meta_verb_true \gen_cmd_box} +\newcommand*{\gen_cmd_box}{% + \bgroup + \let\niceverb_egroup\nice_collect_verb_egroup + \global %% TODO!? for \cmdboxitem 2010/03/15 + %% <- TODO replace \niceverb_egroup by parameter, + %% save one nesting level 2010/03/15 + \setbox\niceverb_savebox \hbox\bgroup + \if_no_nice_meta_verb_ + \expandafter \HardNVerb + \else \expandafter \NVerb \fi} +\newcommand*{\nice_collect_verb_egroup}{% + \egroup \egroup + \ifvmode \expandafter \VerticalCmdBox + \else \ifmmode \hbox \fi + \expandafter \InlineCmdBox \fi + {\box\niceverb_savebox}% + \niceverb_normal_egroup} +%% |\nvCmdBox| will be the permanent alias for \qtd{&|}. +\newcommand*{\nvCmdBox}{\GenCmdBox\|} +%% |\VerticalCmdBox{<content>}| +%% may eventually start a `decl' environment +%% as in 'ltxguide.cls', looking ahead for another \qtd{&|} +%% in order to (perhaps) append another row. +%% Another possibility is first to do some +%% \[`\if@nobreak\else \pagebreak[2]\fi'\] +%% etc. and then invoke `\InlineCmdBox'. +%% The user can choose later by some `\renewcommand'. +%% We do the perhaps most essential thing here +%% (again cf. `\begin_min_verb'):{\sloppy\par} +\newcommand*{\VerticalCmdBox}{\leavevmode\null\InlineCmdBox} +%% The command declaration boxes in the documentation of +%% Nicola Talbot's \ctanpkgref{datatool} +%% would be an especially nice realization of `\VerticalCmdBox'. +%% +%% |\InlineCmdBox{<content>}|, according to our idea, should not +%% change baseline skip, even with some `\fboxsep' and `\fboxrule'. +%% (However, it may be a good idea to increase the overall +%% normal baseline skip.) +%% We therefore replace actual height and depth of the content by +%% the height and depth of math parentheses. +\newcommand*{\InlineCmdBox}[1]{% + \bgroup +%% ... needed in math mode with `\begin_min_verb'. + \fboxsep 1pt + \kern\SetOffInlineCmdBoxOuter + \smash{\SetOffInlineCmdBox{\kern\SetOffInlineCmdBoxInner + \InlineCmdBoxArea{#1}% + \kern\SetOffInlineCmdBoxInner}}% + \mathstrut + \kern\SetOffInlineCmdBoxOuter + \egroup +} +%% The default choice for |\SetOffInlineCmdBox| is `\fbox': +\@ifdefinable\SetOffInlineCmdBox{\let\SetOffInlineCmdBox\fbox} +%% You can `\renewcommand' it to change `\fboxsep', `\fboxrule' +%% etc. or to use a `\colorbox' with the 'color' package, e.g., +%% I used the following setting so far: +%% %% 2010/03/10 +%% \begin{verbatim} +%% \RequirePackage{color} +%% \renewcommand*{\SetOffInlineCmdBox} +%% {\colorbox[cmyk]{.1,0,.2,.05}} +%% \end{verbatim} +%% |\SetOffInlineCmdBoxInner| enables controlling the inner +%% horizontal space to the box margin independently of +%% `\fboxsep'. +%% %% We set it to 0\,pt. as default (it is a macro only, +%% %% for a while). +\newcommand*{\SetOffInlineCmdBoxInner}{-\fboxsep\thinspace} +%% This choice is inspired by `\cstok' for ``boxed" things +%% in Knuth's 'manmac.tex' which formats {\it The \TeX book}. +%% %% <- 2010/03/10 +%% +%% |\SetOffInlineCmdBoxOuter| allows that the box hangs out into the +%% margin horizontally. +%% We set it to 0\,pt as default (it is a macro only, for a while). +\newcommand*{\SetOffInlineCmdBoxOuter}{\z@} +%% The height and depth of the frame should be the same for all +%% inline boxes, we think. +%% The present choice |\InnerCmdBoxArea| for the spacing +%% respects code characters rather than the height and depth +%% of the angle brackets that surround meta-variable names. +\newcommand*{\InlineCmdBoxArea}[1]{% + \smash{#1}\vphantom{gjpq\backslash_verb}} +%% \GenCmdBox+\cmdboxitem|<content>|+ is another variant of +%% `\GenCmdBox'. It should replace `\item[<content>]' in the +%% `description' environment. %% 2010/03/15 +\newcommand*{\cmdboxitem}{% + \bgroup + \let\niceverb_egroup\cmd_item_egroup + \global %% TODO!? 2010/03/15 + \setbox\niceverb_savebox \hbox\bgroup + \NVerb} +\newcommand*{\cmd_item_egroup}{% + \egroup \egroup \egroup + \item[\InlineCmdBox{\box\niceverb_savebox}]} +%% +%% === When 'niceverb' Gets Nasty === +%% These things are new with v0.3. +%% ==== Quotes ==== +%% %% WRONG 2010/03/05: +%% % The left quote feature for meta-code requires that the right quote +%% % feature---for replacing `\textsf'---is activated---no, rather: +%% % that the right quote \qtd{&'} is `\active'. +%% % +%% In order to get \emph{real} single quotes, you could use `\lq <text>\rq', +%% maybe appending a `\ ', but the code |\qtd{<text>}| may look better +%% and be easier to type. +\newcommand*{\qtd}[1]{`#1'} +%% However, here we get the problem that the left quote in +%% \NVerb\+\qtd{`<code>'}+ will be unable to switch into +%% verbatim mode entirely---then use `&', +%% e.g., \qtd{&\qtd{&&&&}} typesets \qtd{\qtd{&&}}, i.e., +%% the ampersand in single (non-verbatim) quotes. +% TODO \qtdverb!? alternative meaning for \LQverb!? 2010/03/06 +% rather rare, & takes less space 2010/03/09 +%% |\dqtd{<text>}| can be used for enclosing in \emph{double} quotes +%% with the dangerous `\nvAllRightQuotesSansSerif' (see above). +\newcommand*{\dqtd}[1]{``#1"} +%% +%% ==== 'hyperref' ==== +%% This is for\slash about compatibility with the 'hyperref' package. +%% (One preliminary thing: in doubt, don't load 'niceverb' earlier +%% than 'hyperref'.) %% TODO 2010/03/14 +%% +%% We need some substitutions for PDF bookmarks with +%% 'hyperref'. We issue them at `\begin{document}' when we know +%% if 'hyperref' is at work.\footnote{An alternative approach would be +%% using +%% \ctanpkgref{afterpackage} +%% by Alex Rozhenko.} +\AtBeginDocument{% + \@ifpackageloaded{hyperref}{% + \newcommand*{\PDFcstring}{% %% moved here 2010/03/09 + \134\expandafter\@gobble\string}% %% ASCII octal encoding + \pdfstringdefDisableCommands{% + \let\nvAllowRQSS\empty %% not \relax 2010/03/12 + %% 2010/03/12 + \MakeActiveLetHere\`\lq \MakeActiveLetHere\'\rq + \MakeActiveLetHere\&\PDFcstring + \def\cs{\134}% %% 2010/03/17 + }% +%% Moreover, in order to avoid spurious %% 2010/03/14 +%% \texttt{Label(s) may have changed} with 'hyperref', +%% a single right quote must be \emph{read} as active +%% by a `\newlabel' if and only if it has been active when +%% `\@currentlabelname' was formed.\footnote{This uses +%% \cs{@onelevelsanitize}, therefore &\protect doesn't +%% change the behaviour of ``active" characters.} +%% as `\active'. We use `\protected@write' as this cares for +%% `\nofiles'. `\@auxout' may be `\@partaux' for `\include'. + \newcommand*{\niceverb_aux_cat}[2]{% %% 2010/03/14 + \protected@write\@auxout{}{\string#1\string#2}}% + \renewcommand*{\MakeActive}[1]{% + \MakeActiveHere#1% + \niceverb_aux_cat\MakeActiveHere#1}% + \renewcommand*{\MakeActiveLet}[2]{% + \MakeActiveLetHere#1#2% + \niceverb_aux_cat\MakeActiveHere#1}% + \renewcommand*{\MakeNormal}[1]{% + \MakeNormalHere#1% + \niceverb_aux_cat\MakeNormalHere#1}% + }{}% +} +%% TODO doesn't 'babel' have the same problem? 2010/03/12 +%% ==== 'hyper-xr' ==== %% 2010/03/21 +%% With the 'hyper-xr' package creating links into external documents, +%% preceding `\externaldocument{<file>}' with +%% `\MakeActiveLet\&\CmdSyntaxVerb' may be needed. +%% I do not want to redefine something here right now as I +%% I have too little experience with this situation. +%% +%% ==== Turning off and on altogether ==== +%% These commands are new with v0.3. +%% +%% |\noNiceVerb| \emph{disables} all 'niceverb' features. +\newcommand*{\noNiceVerb} {\MakeNormal\`% + \MakeNormal\&% + \MakeNormal\<% + \MakeNormal\#% + \nvRightQuoteNormal + \MakeNormal\|} +%% |\useNiceVerb| \emph{activates} all the 'niceverb' features +%% (apart from ``auto mode"). +\newcommand*{\useNiceVerb}{\MakeActiveLet\`\LQverb +%% TODO to be changed with 'wiki.sty' v0.2 + \MakeActiveLet\&\CmdSyntaxVerb + \MakeActiveLet\<\MetaVar + \MakeActiveLet\#\HashVerb + \nvRightQuoteSansSerif + \MakeActiveLet\|\nvCmdBox} +%% +%% === Activating the 'niceverb' Syntax === +%% 'niceverb' features are activated at `\begin{document}' +%% so (some) other packages can be loaded \emph{after} 'niceverb'. +%% For v0.3, we do this after possible settings for +%% compatibility with 'hyperref'. +\AtBeginDocument{\useNiceVerb} +%% +%% === Leave Package Mode === +\MakeNormalHere\_ %% 2010/03/12 \endinput %% %% === VERSION HISTORY === @@ -234,6 +704,53 @@ v0.2 2009/04/04 ...NoVerbList: \subsubsection, \AddToMacro, 2009/04/11 \@ after \SimpleVerb 2009/04/14 noted TODO below 2009/04/15 change v0.1 to 2009/02/21 +v0.30 2010/02/27 short, more explained, \AssignCatCodeTo, + use \MakeActive for re-activating, \MakeNormal + 2010/02/28 fixed @ and _ with & by moving \begin_min_verb; + replaced \lq by `; Capitals in Titles + 2010/03/05 \SimpleVerb -> \NVerb; + use \MakeActive + \MakeNormal; \rq -> '; + renamed some sections; \lq_verb -> \LQverb, + \niceverb_meta -> \MetaVar, + \param_verb -> \HashVerb + 2010/03/06 removed \MakeAlign; removed @ and _ todo below; + \NVerb makes ` and ' other; + \nvAllowRQSF allows ' in column titles, + 2010/03/08 \LQverb and & work in column titles, + \RQverb works with \noindent; + bookmark substitutions + 2010/03/09 extended notes on 'hyperref' (in)compatibility; + \MakeLetter\@ in \CmdSyntaxVerb only; + |...| implemented as \prepareCmdBox etc.! + 2010/03/10 \colorbox example, \thinspace; ltxguide!; + removed todo; ..._exec -> \DoRQsansserif; + minor doc changes in ``Nasty" + 2010/03/11 doc changes in ``Escape Character ..." and + ``Ampersand" + 2010/03/12 \niceverb_aux_cat, \MakeActiveHere etc., + \IfTypesetting, \noNiceVerb, \useNiceVerb, + corr. bracing mistake in \MakeNormal! + 2010/03/14 0.31 -> 0.3; \HardNVerb, \GenCmdBox, + \prepareCmdBox -> \nvCmdBox + 2010/03/15 \endcell; \cmdboxitem; remark on \sfcode`/ + 2010/03/16 corr. -> \endline; + advice on \cs{par}, \cs{if...}, \cs{fi}; + redefined \ignorespaces for RQ feature + 2010/03/17 corr. `\fututelet', corr. \cs PDF substitution + 2010/03/18 |\niceverbNoVerbList|, |\AddToMacro| etc.; + corr. \AddToMacro; + \lastskip-fix of \niceverb_ignore, + another fix of \niceverb_noindent + 2010/03/19 another fix of \niceverb_ignore: \spacefactor + 2010/03/20 ... again: \niceverb_spacefactor + +NOT DISTRIBUTED, just stored saved as separate version + +v0.31 2010/03/20 right quote feauture: letters get \sfcode=1001 + `column title' -> `page headers', \ctanpkgref + +NOT DISTRIBUTED, just stored as separate version + +v0.32 2010/03/21 taking best things from v0.30 and v0.31 + 2010/03/23 removed \relax from \IfTypesetting -TODO: choose expansions of active characters by options 2009/04/10 -TODO: &\@tempa and &\_tempa fail 2009/04/14 |