diff options
34 files changed, 5183 insertions, 531 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/FILES b/Master/texmf-dist/doc/latex/nicetext/FILES index d6d5cba5fd1..9752edc9f14 100644 --- a/Master/texmf-dist/doc/latex/nicetext/FILES +++ b/Master/texmf-dist/doc/latex/nicetext/FILES @@ -1,39 +1,92 @@ -FILES IN CTAN DIRECTORY nicetext:
-
-FILES present file
-README summary
-README.txt copy of README
-
-fifinddo.sty parsing and file handling
- makedoc.sty package to doc preprocessing
-mdoccorr.cfg txt to TeX macros
-niceverb.sty minimal doc markup
- wiki.sty Wikimedia-like markup
-
-SUBDIRECTORIES:
-
-doc documentation
-|____CHANGE.LOG bundle changes
-|__fifinddo.pdf for fifinddo.sty
-|___makedoc.pdf for makedoc.sty
-|_mdoccheat.pdf lists makedoc+fifinddo commands
-|__niceverb.pdf for niceverb.sty
-|_wikicheat.pdf lists wiki.sty features
-
-docsrc
-|__fifinddo.tex
-|___makedoc.tex
-|___makedoc.cfg shared style settings
-|__MDOCCHEA.TEX
-|__niceverb.tex
-|__WIKICHEA.TEX
-
-run dialogues/templates/example
-|__fdtxttex.tex dialogue for txt to TeX etc.
-|__fdtxttex.tpl fifinddo script
-|___makedoc.tpl makedoc script
-|____sample.txt watch its TeX enhancement
-|____substr.tex typesets substr.sty documentation
-
-__________________________
-this file 2010/03/22, U.L.
+FILES IN CTAN DIRECTORY /macros/latex/contrib/nicetext: + + + +FILES present file + +README summary + +README.txt copy of README + + + +fifinddo.sty parsing and file handling + + makedoc.sty package to documentation preprocessing + +mdoccorr.cfg txt to TeX macros + +niceverb.sty minimal documentation markup + + wiki.sty Wikimedia-like markup + + + +SUBDIRECTORIES: + + + +demo automatically generated documentation ... + +|__arseneau.pdf of packages by Donald Arseneau + +|____substr.pdf of Harald Harder's substr.sty + + + +doc documentation + +|____CHANGE.LOG bundle changes + +|___NNOUNCE.txt announcement for present release + +|__RELEAS03.txt announcement for previous release + +|__fifinddo.pdf for fifinddo.sty + +|___makedoc.pdf for makedoc.sty + +|_mdoccheat.pdf lists makedoc+fifinddo commands + +|__niceverb.pdf for niceverb.sty + +|_wikicheat.pdf lists wiki.sty features + + + +docsrc documentation sources + +|__fifinddo.tex + +|___makedoc.tex + +|___makedoc.cfg shared style settings + +|__mdocchea.tex + +|__niceverb.tex + +|_wikicheat.tex + + + +run dialogues/templates/examples + +|__arseneau.tex typesets documentation of ... + +|__fdtxttex.tex dialogue for txt to TeX etc. + +|__fdtxttex.tpl fifinddo script for txt to TeX etc. + +|___makedoc.tpl makedoc script for txt to TeX + +|____sample.txt watch its TeX enhancement + +|____substr.tex typesets substr.sty documentation + + + +__________________________ + +this file 2010/03/30, U.L. + diff --git a/Master/texmf-dist/doc/latex/nicetext/README b/Master/texmf-dist/doc/latex/nicetext/README index 611e8837055..69123cc5c54 100644 --- a/Master/texmf-dist/doc/latex/nicetext/README +++ b/Master/texmf-dist/doc/latex/nicetext/README @@ -1,123 +1,250 @@ The NICETEXT bundle + + (c) 2009 2010 Uwe Lueck http://contact-ednotes.sty.de.vu + + + == General Idea == + + The NICETEXT bundle supports "minimal" markup syntax for rather + simple kinds of text. The code you type should show little more + characters than are printed, though you get LaTeX quality. We try + to do away with backslashes, technical terms, and curly braces + (which also are so clumsy to type on PC keyboards). + + Main focus is easy documentation of LaTeX packages. Preprocessing + by Perl or so is replaced by TeX macros (reviving/generalizing the + 'docstrip' idea), including expandable, safe, correct string + substitution and typographical enhancements of plain text for + LaTeX input. + + + == Packages == + + 'wiki.sty' addresses general kinds of texts. 'niceverb.sty' is + made for documenting LaTeX packages. 'niceverb.sty' especially + offers [almost-]WYSIWIG for meta-variables (macro arguments) and + for referring to commands (and their syntax) in footnotes, + section titles etc. E.g., to get the syntax description + + \foo[<opt-arg>]{<mand-arg>} + you just type + \foo[<opt-arg>]{<mand-arg>} + !-) + + 'fifinddo.sty' provides basic setup for text filtering, especially + string substitution. 'makedoc.sty' extends it to provide a simple + script language for transforming plain text package files into LaTeX + input files [manual!?]. One LaTeX run can perform preprocessing and + typesetting. + + + == Comparisons == + + One source of inspiration is the markup syntax of editing Wikipedia + pages. 'wiki.sty' of the bundle offers something similar as a LaTeX + front-end for italics, boldface, sectioning, and certain list-like + environments. This is also similar to 'easylatex', + + http.//www.ctan.org/pkg/easylatex + + which is more powerful and uses Perl. NICETEXT, by contrast, consists + just of LaTeX packages, working on any TeX installation [!? note + restrictions in 'fifinddo.pdf']. Cf. also preprocessor packages + 'txt2tex' and 'txt2latex'. + + Regarding "self-documentation," there is a difference to current + `\DocInput', similar ideas are in 'gmdoc' and 'lineno.sty', + see 'niceverb.pdf' and 'makedoc.pdf'. Standard 'doc.sty' and + 'contrib' extensions of it are rather avoided. + + There are several *LaTeX macro* packages for processing text or + databases or for editing TeX's input stream while typesetting + -- see 'fifinddo.pdf'. What seems to be new here is + *expandable string substitution* and safe, correct detection of + substrings -- discussed in 'fifinddo.pdf'. + + + == Documentation == + + 'fifinddo.pdf' describes 'fifinddo.sty', typeset from 'fifinddo.tex'. + 'makedoc.pdf' describes 'makedoc.sty', typeset from 'makedoc.tex'. + 'mdoccheat.pdf' is a list of script commands, typeset from 'mdocchea.tex'. + 'niceverb.pdf' describes 'niceverb.sty', typeset from 'niceverb.tex'. + Typesetting them anew (for customizing printout) requires + 'makedoc.cfg', 'mdoccorr.cfg', and the *.sty files. + + 'wikicheat.pdf' is a one-page manual of 'wiki.sty'. The file + 'wiki.sty' contains additional documentation as plain text. + Note that certain features must be activated by commands in the + document environment. + + + == Templates/Dialogue == -txt to TeX functionality throught \MakeDocCorrectHook can be tried + + +txt to TeX functionality through \MakeDocCorrectHook can be tried + and applied with templates `fdtxttex.tpl' and `makedoc.tpl' and in + a dialogue started by running `fdtxttex.tex'. + + `substr.tex' should typeset the version of Harald Harder's -`substr.sty' next at your TeX installation. + +`substr.sty' next at your TeX installation. `arseneau.tex' + +should typeset documentation of a few packages by Donald Arseneau. + +My results are `substr.pdf' and `arseneau.pdf'. + + + == Required == + + `makedoc.sty' requires the `moreverb' package from + + CTAN:/macros/latex/contrib/moreverb + + + == License == + + Copying, distributing, modifying, using the files of the `nicetext' + bundle are allowed under the terms of the LaTeX Project Public + License, either version 1.3a or any later version, the latest version + is at + + http://www.latex-project.org/lppl.txt + + There is NO WARRANTY, and you must CARE indeed with `fifinddo' and + `makedoc', they will OVERWRITE existing files without warning because + their main purpose is updating. + + The bundle is AUTHOR-MAINTAINED in the sense of the LPPL. + + Copyright (C) 2009, 2010 Uwe Lueck, + + http://www.contact-ednotes.sty.de.vu + + Please report bugs, problems, and suggestions via the previous web + form. + + + ________________________________ - [This file 2010/03/23 Uwe Lueck] + + [This file 2010/03/30 Uwe Lueck] + diff --git a/Master/texmf-dist/doc/latex/nicetext/README.txt b/Master/texmf-dist/doc/latex/nicetext/README.txt index 611e8837055..69123cc5c54 100644 --- a/Master/texmf-dist/doc/latex/nicetext/README.txt +++ b/Master/texmf-dist/doc/latex/nicetext/README.txt @@ -1,123 +1,250 @@ The NICETEXT bundle + + (c) 2009 2010 Uwe Lueck http://contact-ednotes.sty.de.vu + + + == General Idea == + + The NICETEXT bundle supports "minimal" markup syntax for rather + simple kinds of text. The code you type should show little more + characters than are printed, though you get LaTeX quality. We try + to do away with backslashes, technical terms, and curly braces + (which also are so clumsy to type on PC keyboards). + + Main focus is easy documentation of LaTeX packages. Preprocessing + by Perl or so is replaced by TeX macros (reviving/generalizing the + 'docstrip' idea), including expandable, safe, correct string + substitution and typographical enhancements of plain text for + LaTeX input. + + + == Packages == + + 'wiki.sty' addresses general kinds of texts. 'niceverb.sty' is + made for documenting LaTeX packages. 'niceverb.sty' especially + offers [almost-]WYSIWIG for meta-variables (macro arguments) and + for referring to commands (and their syntax) in footnotes, + section titles etc. E.g., to get the syntax description + + \foo[<opt-arg>]{<mand-arg>} + you just type + \foo[<opt-arg>]{<mand-arg>} + !-) + + 'fifinddo.sty' provides basic setup for text filtering, especially + string substitution. 'makedoc.sty' extends it to provide a simple + script language for transforming plain text package files into LaTeX + input files [manual!?]. One LaTeX run can perform preprocessing and + typesetting. + + + == Comparisons == + + One source of inspiration is the markup syntax of editing Wikipedia + pages. 'wiki.sty' of the bundle offers something similar as a LaTeX + front-end for italics, boldface, sectioning, and certain list-like + environments. This is also similar to 'easylatex', + + http.//www.ctan.org/pkg/easylatex + + which is more powerful and uses Perl. NICETEXT, by contrast, consists + just of LaTeX packages, working on any TeX installation [!? note + restrictions in 'fifinddo.pdf']. Cf. also preprocessor packages + 'txt2tex' and 'txt2latex'. + + Regarding "self-documentation," there is a difference to current + `\DocInput', similar ideas are in 'gmdoc' and 'lineno.sty', + see 'niceverb.pdf' and 'makedoc.pdf'. Standard 'doc.sty' and + 'contrib' extensions of it are rather avoided. + + There are several *LaTeX macro* packages for processing text or + databases or for editing TeX's input stream while typesetting + -- see 'fifinddo.pdf'. What seems to be new here is + *expandable string substitution* and safe, correct detection of + substrings -- discussed in 'fifinddo.pdf'. + + + == Documentation == + + 'fifinddo.pdf' describes 'fifinddo.sty', typeset from 'fifinddo.tex'. + 'makedoc.pdf' describes 'makedoc.sty', typeset from 'makedoc.tex'. + 'mdoccheat.pdf' is a list of script commands, typeset from 'mdocchea.tex'. + 'niceverb.pdf' describes 'niceverb.sty', typeset from 'niceverb.tex'. + Typesetting them anew (for customizing printout) requires + 'makedoc.cfg', 'mdoccorr.cfg', and the *.sty files. + + 'wikicheat.pdf' is a one-page manual of 'wiki.sty'. The file + 'wiki.sty' contains additional documentation as plain text. + Note that certain features must be activated by commands in the + document environment. + + + == Templates/Dialogue == -txt to TeX functionality throught \MakeDocCorrectHook can be tried + + +txt to TeX functionality through \MakeDocCorrectHook can be tried + and applied with templates `fdtxttex.tpl' and `makedoc.tpl' and in + a dialogue started by running `fdtxttex.tex'. + + `substr.tex' should typeset the version of Harald Harder's -`substr.sty' next at your TeX installation. + +`substr.sty' next at your TeX installation. `arseneau.tex' + +should typeset documentation of a few packages by Donald Arseneau. + +My results are `substr.pdf' and `arseneau.pdf'. + + + == Required == + + `makedoc.sty' requires the `moreverb' package from + + CTAN:/macros/latex/contrib/moreverb + + + == License == + + Copying, distributing, modifying, using the files of the `nicetext' + bundle are allowed under the terms of the LaTeX Project Public + License, either version 1.3a or any later version, the latest version + is at + + http://www.latex-project.org/lppl.txt + + There is NO WARRANTY, and you must CARE indeed with `fifinddo' and + `makedoc', they will OVERWRITE existing files without warning because + their main purpose is updating. + + The bundle is AUTHOR-MAINTAINED in the sense of the LPPL. + + Copyright (C) 2009, 2010 Uwe Lueck, + + http://www.contact-ednotes.sty.de.vu + + Please report bugs, problems, and suggestions via the previous web + form. + + + ________________________________ - [This file 2010/03/23 Uwe Lueck] + + [This file 2010/03/30 Uwe Lueck] + diff --git a/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf b/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf Binary files differnew file mode 100644 index 00000000000..7cc3ec6201e --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf Binary files differnew file mode 100644 index 00000000000..5d924a106ac --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG index f49709e4d7d..dec717b4a07 100644 --- a/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG +++ b/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG @@ -1,71 +1,234 @@ ______________________________________________________________________ + +nicetext RELEASE v0.4 2010/03/30 SUMMARY: `% ' commenting style + + supported, applied to packages + + by Donald Arseneau, extended + + formatting through specific + + replacements, also with + + substr.sty, improved setup for + + \MakeDocCorrHook + + + +- FILES 2010/03/30 updated + + README 2010/03/30 updated + + CHANGE.LOG 2010/03/30 updated + + NNOUNCE.txt 2010/03/30 updated + + RELEA03.txt 2010/03/30 renamed + + + +- fifinddo.sty v0.4 2010/03/29 setup for replacement chaining + + and \MakeDocCorrectHook + + improved: \SetPatternCodes, + + \ResetPatternCodes, + + \SetCorrectHookJob, + + \SetCorrectHookJobLast + + fifinddo.pdf 2010/03/29 updated + + fdtxttex.tex 2010/03/30 updated + + fdtxttex.tpl 2010/03/30 updated + + + +- makedoc.sty v0.4 2010/03/30 `% ' commenting style supported, + + \ResetCodeLineNumbers, + + use \ResetPatternCodes + + makedoc.pdf 2010/03/30 updated, fixed + + makedoc.cfg 2010/03/29 unchanged + + makedoc.tpl 2010/03/23 unchanged + + mdoccheat.pdf 2010/03/30 updated, renamed mdoccheat.tex + + mdoccorr.cfg 2010/03/29 uses new fifinddo commands + + + +- niceverb.sty v0.4 2010/03/29 auto mode: \AddToNoVerbList, + + safer restoring of underscore + + niceverb.pdf 2010/03/29 updated + + + +- arseneau.tex 2010/03/30 first CTAN release + + arseneau.pdf 2010/03/30 first CTAN release + + sample.txt 2010/03/22 unchanged + + substr.tex 2010/03/30 extended formatting by specific + + replacments using new fifinddo + + commands; corrections + + substr.pdf 2010/03/30 first CTAN release + + + +______________________________________________________________________ + nicetext RELEASE v0.3 2010/03/23 SUMMARY: `makedoc' simplified, + `niceverb' robustified, + `fifinddo' re-implemented + & slightly enhanced, + txt to TeX dialogue & templates + + - FILES 2010/03/23 first CTAN release + README 2010/03/23 updated + CHANGE.LOG 2010/03/23 updated + NNOUNCE.TXT 2010/03/23 updated + + - fifinddo.sty v0.31 2010/03/23 replacement chaining improved: + \PrependExpandableAllReplacer; + works with character codes > 127; + setup-setup unified + fifinddo.pdf 2010/03/23 updated + fdtxttex.tex 2010/03/22 first CTAN release + fdtxttex.tpl 2010/03/23 first CTAN release + mkfddoc.tex removed + + - makedoc.sty v0.3 2010/03/19 bundling to standalone commands + makedoc.pdf 2010/03/23 updated & much extended + (list of script commands) + makedoc.cfg 2010/03/20 no longer essential + makedoc.tpl 2010/03/23 first CTAN release + mdoccheat.pdf 2010/03/21 first CTAN release + mdoccorr.cfg 2010/03/23 replaces `mdcorr.cfg', uses + \Prepend... + + - niceverb.sty v0.32 2010/03/23 robustified, incl. + `hyperref' compatibility + & dis-/re-enabling + niceverb.pdf 2010/03/23 much extended + + - sample.txt 2010/03/22 first CTAN release + substr.tex 2010/03/18 first CTAN release + + ______________________________________________________________________ + nicetext RELEASE 0.2 2009/04/15 add `fifinddo' and `makedoc' for + txt -> latex preprocessing + + - README 2009/04/15 updated + CHANGE.LOG 2009/04/15 new + + - fifinddo.sty v0.3 2009/04/15 first CTAN release + fifinddo.pdf 2009/04/15 + mkfddoc.tex 2009/04/15 + + - makedoc.sty v0.2 2009/04/13 first CTAN release + makedoc.pdf 2009/04/15 + makedoc.cfg 2009/04/15 + mdcorr.cfg 2009/04/15 + + - niceverb.sty v0.2 2009/04/15 strengthened \SimpleVerb, + \sf detection after `(', + more for \niceverbNoVerList + niceverb.pdf 2009/04/15 adjusted to new doc generation + method, mentioning it, + motivation extended, + more examples + + ______________________________________________________________________ + nicetext RELEASE 0.1 2009/02/23: first CTAN releases of + `niceverb' and `wiki' + + - niceverb.sty v0.1 2009/02/21 + niceverb.pdf 2009/02/23 + + - wiki.sty v0.2 2008/07/02 + wikicheat.pdf 2009/01/17 + diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt b/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt new file mode 100644 index 00000000000..3c3da46d584 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt @@ -0,0 +1,48 @@ +`makedoc' + `niceverb' - an alternative documentation system for LaTeX + +---------------------------------------------------------------------- + +Step 2 of txt to TeX processing of third-party package documentations + +====================================================================== + +New with release 0.4: + + + +* Additionally to the `%% ' commenting style (allowing + + "commenting out") the usual `% ' commenting style is supported -- + + applied to packages by Donald Arseneau, see abstract in + + `arseneau.pdf'. + + + +* Extended formatting of Harald Harder's `substr.sty' through specific + + preprocessing replacements (\MakeDocCorrectHook) -- see abstract in + + `substr.pdf'. + + + +* Setup of \MakeDocCorrectHook (txt to TeX) easier with + + \SetPatternCodes, \ResetPatternCodes, \SetCorrectHookJob, + + \SetCorrectHookJobLast + + + + + + + + + + + + + diff --git a/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.TXT b/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt index 2c1905a37e2..26cb5fab553 100644 --- a/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.TXT +++ b/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt @@ -1,48 +1,95 @@ `makedoc' + `niceverb' - an alternative documentation system for LaTeX + ====================================================================== + The `nicetext' bundle offers "minimal" markup syntax for restricted + kinds of text: There should not be much more characters typed than + printed! -- mainly: quick documentation of (smaller) LaTeX packages + -- achieved by active characters and preprocessing similar to + `docstrip' ("opposite direction" however, incl. some txt to TeX). + + New with release 0.3: + + * `substr.tex' should typeset LaTeX quality documentation from + next available (on your install) substry.sty's ASCII/UTF-8 input + (works with me) -- first application of `niceverb''s "auto mode" + and `makedoc.sty' to a third-party package! + + * `makedoc' simplified: single + + \MakeInputJobDoc[<in>][<out>]{<header>}{<parser>} + + generates a documentation file from the package file and + typesets it immediately (kind of \DocInput equivalent) + -- see `Using makedoc the simplest way' in `makedoc.pdf' + + * `|...|' from `niceverb' typesets an inline frame box for setting-off + a command description, modifiable by hooks (e.g., \colorbox) + + * `niceverb' syntax works in page headers, PDF bookmarks, and + `hyperref' labels and otherwise much better than before, + dis-/re-enableable featurewise as well as altogether + + * documentation extended, lists of script commands + + * configurable txt to TeX functionality or other replacements like + ASCII-arrows to arrow commands or inserting \index entries + (setting up expandable replacement chains slightly more comfortable) + -- try with templates and dialogue + + * `fifinddo' works with character codes > 127, improved setup + + * `makedoc' requires the `moreverb' package. + + ______________________________________________________________________ + CATALOGUE: These packages may be compared with: + * easylatex, txt2latex, txt2tex + (typographical and TeX input enhancement); + * doc, gmdoc, lineno (awk in place of \DocInput); + * substr, datatool, ted, xstring, stringstrings, makematch, ... + (parsing)
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf Binary files differnew file mode 100644 index 00000000000..6a209273e90 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf Binary files differnew file mode 100644 index 00000000000..8c9a8d1753e --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf Binary files differindex d51d4fb96af..2a34ce5492d 100644 --- a/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf Binary files differindex 4f0d9279550..3aa00be21ef 100644 --- a/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf Binary files differindex 481c7e314d4..2b915d38155 100644 --- a/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex index 91234d2b73c..59484968382 100644 --- a/Master/texmf-dist/doc/latex/nicetext/fifinddo.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex @@ -1,325 +1,650 @@ \ProvidesFile{fifinddo.tex}[2010/03/23 documentation for `fifinddo'] + \title{\textsf{fifinddo}\\---\\Filtering \TeX(t) Files by \TeX} + \author{Uwe L\"uck\,---\,{\tt http://contact-ednotes.sty.de.vu}} + % \listfiles + \documentclass{article} + \usepackage{makedoc} + % \usepackage{substr} %% for failure examples TODO 2010/03/17 + \input{makedoc.cfg} + \begin{document} + \maketitle + + \begin{flushright}\small\it FIDO, FIND!\\or:\\FIND FIDO!\\oder:\\FIFI, + SUCH!\end{flushright} + \begin{abstract}\noindent\hspace{1sp}%% for niceverb-apostrophe + 'fifinddo' starts implementing parsing of plain text or \TeX\ files + using \TeX, generalizing the philosophy behind 'docstrip', + based on how \TeX\ reads macro arguments. + Rather than typsetting the edited input stream immediately, + results are written to another file, + in the first instance as input for \TeX. + Rather than presenting a ``complete study" of a computer-scientific + idea, it aims at practical applications. + The main one at present is '\mbox{makedoc}' which removes certain comment + marks from package files and inserts listing commands. + Parsing macros are not defined anew at every input chunk, + but once before a file is processed. + This also allows for \emph{expandable} sequences of replacements, + e.g., with `txt'$\to$\TeX\ functionality. + The method of testing for substrings is carefully discussed, + revealing an earlier mistake (then) shared with 'substr.sty' + and \LaTeX's internal `\in@'. + \end{abstract} + \tableofcontents + + \section{Introduction: The Gnome of the Aim} + \subsection{Parsing by \TeX---are you mad?} + The package name 'fifinddo' is a &\listfiles-compatible abbreviation + of \lq file-find-do\rq\footnote{\lq file\rq\ possibly for ``searching + \TeX(t) files" (I don't remember my thoughts!), + while there were requests for doing replacements on + \LaTeX\ \emph{environments} on 'texhax'. However, the package might + be enhanced in this direction $\dots$ so the name may be wrong + $\dots$ but now I like it so much .\,.\,. Or the reason was that + results are written to a \emph{separate file}, not typeset + immediately.---Let me also mention that \emph{\lq Fifi\rq} (as the + package name starts) is a kind of German equivalent to the + ``English" \emph{\lq Fido\rq}, or may have been.} + (or think of \lq if found do\rq). + 'fifinddo' implements (or aims at) general parsing + (extracting, replacing [converting], expanding, \dots) + using \TeX\ where 'texhax' posters strongly urge to use 'sed', + 'awk', or 'Perl'. + 'fifinddo''s opposed rationales are: + \begin{itemize} + \item It works instantly on any \TeX\ installation. + (\emph{Restrictions:} Some \TeX\ versions &\write certain hex + codes for certain characters, cf.\ \TeX book p.~45, + I have seen this with PC\TeX. However, some applications of + 'fifinddo' are nothing but technical steps where you will read + the result files rarely anyway. + %% And I have not yet explored extended encodings.) + %% <- done meanwhile 2010/03/22 + \item You can apply and customize it like any \TeX\ macros, knowing + just \TeX\ (or even only the documentation of some user-friendly + extension of 'fifinddo'), without the need of learning any + additional script language. + \item The syntax of usual utilities (e.g., ``wildcards") + is sometimes difficult with \emph{\TeX} files + with all their backslashes, square brackets, stars, + question marks \dots + \end{itemize} + % + At least the first item is just the philosophy of the 'docstrip' program, + standard for installing \TeX\ packages; + and while I am typing this, I find at least 14 other similar packages + in J\"urgen Fenn's \emph{Topic Index} of the \emph{\TeX\ Catalogue:} + % \begin{quote}\small + \[\texttt{% + % \hbox\bgroup\url{% %% \url impossible!? 2010/03/19 + http://mirror.ctan.org/help/Catalogue/bytopic.html\string#parsingfiles}% + \footnotemark + % \egroup\] + \] + \footnotetext{% + \href{http://mirror.ctan.org/help/Catalogue/bytopic.html\string#parsingfiles}% + {Click here!}} + % \end{quote} + (Some of them may have been \emph{reactance} to 'texhax' and other + postings urging not to try something like this; some seem just to be + celebrations of the power of \TeX---yes, celebrate!) + + Actually, \TeX's mechanism of collecting macro arguments is hard-wired + parsing at quite a high level. \LaTeX\ hides this from + ``simple-minded" users by a convention \emph{not} to use that full + power of \TeX\ for \emph{end-user macros}. + \emph{Internally}, \LaTeX\ \emph{does} use it in reading + lists of options and file dates as well as to implement certain + `FOR'- and `WHILE'-like loop programming structures. + \LaTeX's `\in@'/`\ifin@' construction is an implementation of a + ``<string1> occurs in <string2>" test. More packages seem to use + this idea for extracting file informations, like + 'texshade'.\footnote{\url{http://ctan.org/pkg/texshade}} + + + However, such packages don't make much ado about parsing, + there seems to be no general setup mechanism as are presented by + 'fifinddo'. Indeed, tayloring parsing macros to specific applications + may often be more efficient than a general approach. + + \subsection{Useful for \dots} + My main application of 'fifinddo' at present is typesetting + documentations of packages using 'makedoc' which removes certain + percent marks and inserts listing commands, so you edit a package file + with as little documentation markup as possible. + This may be extended to other kinds of documents as an alternative + to 'easylatex' or 'wiki' (the approach of which is dangerous and + incompatible with certain other things). + + I have used a similar own package 'txtproc' successfully, + where more features were implemented for practical purposes + than are here so far, yet I don't like its implementation, want to + improve it here. This package also \emph{created batch files}, e.g., + to remove temporary files. + This could be used for package handling: + typset the documentation at the desired place in the tree, + write the packages to another, write a batch file to remove + files that are not needed any more after installation + (cf.\ 'make'). %%% !? cf. Wiki `Make (software) 2009/04/11 + + I used 'txtproc' also for \emph{large-scale substitutions} + (it had been decided to change the orthography in a part of a book). + Other large-scale substitutions may be: + \begin{itemize} + \item inserting &\index commands; + \item inserting (soft) hyphenation commands near accents; + \item manual umlaut-conversion.\footnote{If you know the ``names" + of the encodings, Heiko Oberdiek's + \ctanpkgref{stringenc} + may be preferable.} + \item typographical (or even orthographical) corrections (same mistake + many times on each of hundreds of pages). + You may turn `...' into `$\dots$' and `etc.' into `etc.\' + etc.\footnote{But what when a new sentence is starting indeed? + Well, `cf.' is an easier example.---`etc.' even showed + a problem in 'niceverb'. 'mdoccorr.cfg' replaces `etc. ' + only, so you can keep the extra space by a code line break.} + This could replace packages like + 'easylatex',\footnote{\url{http://ctan.org/pkg/easylatex}} + 'txt2latex',\footnote{\url{http://ctan.org/pkg/txt2latex}} + 'txt2tex'\footnote{\url{http://ctan.org/pkg/txt2tex}} + in a customizable way, using, e.g., the ``correct" + hook from 'makedoc.sty' as exemplified in 'mdoccorr.cfg' + (see examples section of 'makedoc.pdf'). + You should find 'fdtxttex.tpl', a 'fifinddo' script + to try or apply `\MakeDocCorrectHook' from 'mdoccorr.cfg', + as well as 'fdtxttex.tex' that runs a dialogue for the + same purpose if you can manage to run it ('WinShell'?). + You can then try to create your own `\MakeDocCorrectHook'. + Section~\ref{sec:replchain} provides setup for macros + of this kind. + \item as to 'easylatex' again, \emph{lists} could be detected and + transformed into \LaTeX\ list commands. This could re-implement + the lists functionality of 'wiki.sty' that is somewhat + dangerous. %% TODO 2009/04/15 + \item introduce your own \emph{shorthands} to be expanded not as \TeX\ macros, + but by text substitution; + \end{itemize} + %% % <- TODO present macros/"jobs" doing this. + %% %% <- TOOD single quote tests could be used for + %% double quote character as well + %% to turn it into left quotes if ... 2010/03/19 + % + In certain cases, insertions deteriorate readability, hyphenation + corrections even make text search difficult. + It is therefore suggested to + \begin{enumerate} + \item keep editing the file without the insertions, + \item run the script (commands based on 'fifinddo') for insertions + in the preamble of the main file + (```\jobname.tex'", maybe &\input the script file) and + \item &\input the result file within the `document' environment. + \end{enumerate} + + In general, differences to ``manual" replacing by the substitution + function of your \emph{text editor} is that + \begin{itemize} + \item you first keep the original version, + \item you can check the resulting file before you replace the original + file by it, + \item you can store the replacement script in order to check for + mistakes at a later stage of your work, + \item you can do \emph{all} the replacements in \emph{one run} + (by \emph{one} script to check for mistakes), + \item you can store replacement scripts for future applications, + so you needn't type the patterns and replacement strings anew. + \end{itemize} + + + \subsubsection{Comparisons} %% was `Missing' 2010/03/18 + % \subsection{To implement or not to implement \dots} %% TODO!? 2009/04/13 + % Actually, 'fifinddo' doesn't implement very much, and this possibly + % won't change, even if I am lucky. ``Practical applications" tend to + % show (in my view) that there is a very complex space of possibilities + % what parsing macros could do. If I try to ``attack" 'Perl' or so, + % cf.\ 'CPAN'\@. If I am lucky and become famous, 'fifinddo' will get many + % extensions in separate packages, cf.\ 'pstricks'. I also like it when + % you can choose among packages for similar purposes, and this may apply + % to extensions of 'fifinddo' as well. + % + % What \emph{really} is missing very badly at present is matching + % \emph{sequences} of strings. However, 'makedoc' contains a practical + % application of this for the case that both strings appear \emph{in the same + % line}. A better algorithm would have to read more lines from the input + % file etc. + % + % As it just comes to my frightened mind, there is even a problem with + % ``strings"/``patterns" that are \emph{phrases} of words, containing + % spaces \dots + % + % Clearly much comfort concerning \emph{routine} jobs is missing now, + % 'txtproc' has more. Please sponsor (or otherwise support) the work for + % improving this. + % + It should be noted (perhaps here) that the present approach to parsing + is a quite \emph{simple} one and in this respect much different to the + string handling mechanisms of + 'stringstrings',\footnote{\url{http://ctan.org/pkg/stringstrings}} + 'ted',\footnote{\url{http://ctan.org/pkg/ted}} + 'xstrings'\footnote{\url{http://ctan.org/pkg/xstrings}} + (as I understand them, perhaps also + 'coolstr'\footnote{\url{http://ctan.org/pkg/coolstr}}) + which are \emph{much more powerful} than what is offered here---but + perhaps slow and for practical applications possibly replaceable by + the present approach. + \emph{Expandable replacement} seems not to exist outside 'fifinddo' + (2009/04/13). + + Much is missing, I know.\footnote{There + is more in my badly implemented 'txtproc.sty'.} + I am just implementing what I actually need + and what could show that this approach is worth being pursued. + %% removed 2010/03/18: + % It may need being sponsored or otherwise supported. + + \subsection{For insiders} + + \emph{Warning:} You may (at least at the present state of the work) + have little success with this package, if you don't know about + \TeX's category codes and how \TeX\ macros are defined. + The package rather provides tools for package writers. + You may, however, be able to run other packages which just load + 'fifinddo' as required background. + + That 'fifinddo' acts on ``\TeX(t)" files or so means that + (at present) I think of applications on ``plain text" files which + will usually be \TeX\ input files. ``At present" they are read + without ``special characters," so essentially category codes of input + characters are either 11 (``letter") or 12 (``other"). + This way some things are easier than with usual \TeX\ applications: + \begin{enumerate} + \item You can ``look into" curly braces and ``behind" comment characters. + \item There are exact or safe tests especially of \emph{empty macro arguments} + that are ``expandable," i.e., they are ``robust," + don't need assignments, can be executed in `\write'ing and in + `\edef' definitions. ``Usually," the safe way to test emptiness + is storing a macro argument as a macro, say `\tempo', in order + to test `\ifx\tempo\empty' where `\empty' has been defined + by `\def\empty{}' in the format. But this requires some + `\def\tempo{#<n>}' which breaks in ``mere expanding" + (\TeX\ \emph{evaluates} `\tempo' instead of defining it). + An \emph{expandable} test on emptiness is, e.g. `\ifx$#<n>$', + where we hope that it becomes `\iftrue' just if macro argument + `#<n>' is empty indeed. However, ``usually" it may \emph{also} + become `\iftrue' when `#<n>' starts with `$'---if the latter + has category code 3 (``math shift"). But 'fifinddo' does + not assign category code 3 to any character from the input file! + Therefore `\ifx$#<n>$' is `\iftrue' \emph{exactly} if `#<n>' is + empty. + \item You can avoid interference with packages that are needed for + typesetting. You can do the ``preprocessing" in one run with + typesetting, but you should do the preprocessing before you + load packages needed for typesetting. One may even try to keep + the macros and settings for preprocessing local to a group. + \end{enumerate} + % + Once there may be an option to read input with some usual \TeX\ + category codes as well, it may be useful to (some of) + \begin{itemize} + \item avoid matching substrings of control words, + \item skip blank spaces as \TeX\ does it usually, + \item catch \emph{balanced} input pieces, + \item ignore comments, + \item ignore certain characters. + \end{itemize} + + The essential approach of 'fifinddo' to looking for single strings is + described in some detail in section~\ref{sec:theory}. + + The implementation of 'fifinddo' is as follows. + User commands are specially highlighted (boxed\slash coloured), + together with their syntax description. + + % \end{document} + + \section{Preliminaries} + \subsection{Head of file (Legalese)} + \sloppy + \ProcessLineMessage{} + \MakeInputJobDoc{23}{\SectionLevelTwoParseInput} + \end{document} + + TODO cf. Kastrup 'makematch' and others 2009/04/09 + + 2009/04/10: title break, by -> with(!?); `boxed/coloured' + 2009/04/12: useful: own shorthands + 2009/04/13: substr.sty, \emph{expandable}, w/o `implement'!? + 2009/04/15: same with \in@ + 2010/03/08: EPS application removed + 2010/03/17: use \MakeInputJobDoc + 2010/03/18: `Missing' -> `Comparisons' etc.; \Require... + 2010/03/19: Catalogue \url; '' -> " + 2010/03/20: \ctanpkgref + 2010/03/22: debugging; done ... + 2010/03/23: more URLs; abstract "then shared"; + removed dates from 2009, fdtxttex.tex/tpl + diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.cfg b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg index 418482a3a34..cd488b9b482 100644 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.cfg +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg @@ -1,29 +1,58 @@ \ProvidesFile{makedoc.cfg}[2010/03/20 + doc formatting settings] + + \RequirePackage{ifpdf} + \ifpdf + % \usepackage[bookmarksnumbered]{hyperref} + % \usepackage[bookmarks=false]{hyperref} + % \usepackage[bookmarks=false,pdfstartview=FitH]{hyperref} + %% <- 2010/03/12 -> + \usepackage[bookmarksnumbered,pdfstartview=FitH]{hyperref} + % \usepackage[pdfpagemode=UseNone]{hyperref} + \else + \usepackage[draft]{hyperref} + %% <- 2010/03/11 -> + % \let\url\texttt \def\href#1#2{#2} %% \@secondoftwo + \fi + \author{Uwe L\"uck\thanks{\url{http://contact-ednotes.sty.de.vu}}} + % \author{Uwe L\"uck---{\tt http://contact-ednotes.sty.de.vu}} + + \RequirePackage{niceverb}[2010/03/10] + %% <- TODO move!? (\DeclareRobust...) -> + \providecommand*{\ctanpkgref}[1] + {\href{http://ctan.org/pkg/#1}{\textsf{#1}}} + + \errorcontextlines=4 + \pagestyle{headings} + + \endinput + + diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex index 5de416ecd53..2007e41d3ac 100644 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex @@ -1,616 +1,1286 @@ -\typeout{makedoc.tex 2010/03/23 documentation for `makedoc.sty'} -% \listfiles +\typeout{makedoc.tex 2010/03/30 documentation for `makedoc.sty'} + +\listfiles + \RequirePackage{makedoc} + \documentclass{article} + \input{makedoc.cfg} %% with pdf stuff and 'niceverb' + %% removed for niceverb v0.31 TODO!? 2010/03/20: + \sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21 + % \makeatletter %% TEST for hyperref compatibility 2010/03/11 + % \def\@testdef #1#2#3{% + % \def\reserved@a{#3}% + % \expandafter \ifx \csname #1@#2\endcsname + % \reserved@a \else \@tempswatrue \fi + % \if@tempswa + % \typeout{^^J*** Type `r' <input> to get around + % \string\label\space issues! ***^^J} + % \errorcontextlines=0 + % \show\reserved@a + % \expandafter \show \csname #1@#2\endcsname + % \fi + % } + % \makeatother + \begin{document} + \title{'makedoc'---Preprocessing documentation by \TeX} + %% 2009/04/10: \\---\\\ breaks TOC + \maketitle + \begin{abstract}\noindent + 'makedoc' provides commands for generating \LaTeX\ input from a + package file in order to typeset the latter's documentation + (somewhat similar and opposite to 'docstrip')---with + v0.3 \emph{a single one usually suffices}. + Certain comment marks are removed, listing commands are inserted, + and some (configurable) typographical `txt'$\to$\TeX\ corrections + are applied.---This + continues the policy of 'niceverb' to minimize documentation markup in + package files. 'makedoc' extends and exemplifies the parsing package + 'fifinddo'. After an edit (and test) of your package, you get the new + documentation in one run (or the usual number of runs) of the + documentation driver file.---The present approach is meant to be an + \emph{alternative} to the standard 'doc' package and its `\DocInput'. + It provides \emph{less} than 'doc' does, rather deliberately. It may + be helpful at least for the development of small packages, or at least + at early stages. + \end{abstract} + \tableofcontents + \section{Introduction} + \emph{The abstract will not be repeated in this section.} Let me add + instead that I was in dire need of such a package, I got stuck with my + packages because I lost orientation in them, and I was unhappy with + the forms of documentations of my other packages, and documenting them + with the standard \LaTeX\ 'doc' system was not attractive for me + (neither considered helpful). %% clarified 2010/03/13 + I also worked on \emph{Windows} until September 2008, and I + find a system like the present one still more attractive then using + (learning!\@) other filtering utilities (see below on 'awk'). And I + may work on \emph{Windows} once again and don't want to depend on + installing some $\dots$ there---\emph{I really would like to have + powerful tools for everything depending on nothing but \TeX\slash + \LaTeX!} + + \section{Prior work and what is new} + It is, of course, not a new idea to get around comment marks `%' to + typeset the documentation. 'doc''s `\DocInput' does this by making `%' + an ``ignored" character. This way you cannot use `%' for commenting + comments (so 'doc' offers a ``new comment mark" + `^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!? + You also cannot use `%' for commenting out code (that you are + pondering---or using for debugging---only). %% clarified 2010/03/13 + + Moreover, 'doc' requires enclosing package code explicitly by + environment commands (behind comment marks). Stephan I. B\"ottcher + with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}' + and Grzegorz Murzynowski in \ctanpkgref{gmdoc} + aimed at doing away with this requirement. + 'lineno.sty' contains 'awk' scripts + to remove starting comment marks and to insert listing commands. + A file 'lineno.tex' is generated that typesets the documentation. + By the way, 'lineno.sty' is full of discussions, but it is not + 'docstrip'ped---the maintainers never have received a complaint + that inputting 'lineno.sty' were too slow. + + 'gmdoc' seems to get around comment marks and insert listing commands + \emph{while typesetting} by a refined version of `\DocInput', + through some careful detecting and analysing comment marks, + the approach resembles detection of lists in 'wiki.sty'.\footnote{See + 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages + document! I also find + \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.} + And this is a matter of principles---comparing the approaches of + \emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"} + ('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler, + sometimes detecting while typesetting. + (Another example is the preprocessor + \ctanpkgref{easylatex} + of which 'wiki.sty' is a much reduced ``while typesetting" variant.) + ``While typesetting" may be easier when single characters or + sequences of two or three encode markup + information---but such detection can badly interfere with other + packages etc. ``Preprocessing" may be easier when entire ``strings" + of characters decide, which may be anywhere in a file line. + + 'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by + \emph{\TeX}. There is a general discussion of this choice in the + documentation of 'fifinddo'. Preprocessing here can be done in the + same \LaTeX\ run as typesetting, though you can avoid + incompatabilities with packages needed for typesetting + (by inputting them only \emph{after} preprocessing). + + 'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be + preferable to preprocessing with other utilities: + When I took over maintenance of 'lineno.sty', + I needed hard work to get the 'awk' script running. + The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel} + 'awk' (I chose a Munich 'nawk' and reworked the script a little). + \TeX\ seems to have better fixed functionality than other utilities! + + A different alternative to \LaTeX's 'doc' system is + Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}' + where the code environments extract package code in typesetting the + documentation. %% added 2010/03/10 + + \section{Styles supported (parsers provided)}\label{sec:styles} + % \section{Styles of commenting '.sty's} + We find different styles of documenting \LaTeX\ packages. + As the main aspects I consider + (i)~\emph{telling code from comments} + and (ii)~\emph{markup in comments}. + (You may find more details on the next matters in the + ``implementation" section.) + + \subsection{Telling code from comments} + \emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX) + probably were named so to mark \emph{``comments"} as opposed + to code $\dots$ great, but actually, in ``daily practice," + they are so handy---and used---for ``commenting out" \emph{code}, + i.e., \emph{managing code versions} in a simple way: + one does not actually want to \emph{delete} code, + one might want to use it another time, maybe for debugging + $\dots$ or to remind of earlier attempts that should not be tried + again $\dots$ + + This is a problem for \emph{high-quality typesetting} of + documentation. \emph{Code} should be typeset about as you see it on + the \emph{screen}---\emph{monospaced}, this allows structuring by + indenting, it is common practice to use a typewriter typeface for + this. Real \emph{comments} should be typeset in \emph{high quality} as + usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden + code"} (``commented-out"). A comment mark starts the line, but + obviously it is not really a comment and rather should be typeset + like code (and otherwise they may break). %% 2010/03/22 + Another problem are comments at the \emph{end} of a + \emph{code} line. Sometimes they are ``real comments" ('gmdoc' + supports this style). But sometimes + this is only another version of ``version management," code -``commented-out". + +``commented-out." + + I like the style of writing packages described before and use it all + the time. I mark ``real comments" with \emph{two} adjacent comment + marks and an ensuing space to distinguish them clearly from code + commented out. -\emph{Only this style is presently supported by \textup{'makedoc'}!} -More precisely, 'makedoc' at present has only \emph{one} method to -distinguish code from comment: Only a line starting with + +%% Adapted to v0.4 2010/03/29: + +\emph{This style is presently the one supported by \textup{'makedoc'} + + as default.} + +This way only a line starting with + |%% | is considered a ``real" comment line. The first three + characters are removed, and the rest is typeset in high quality. + Any other lines are typeset verbatim. The 'makedoc' \emph{parser} + doing this has an ``identifier" |PPScomment| (``percent, percent, -space"). Another identifier |comment| is planned to be placeholder for -the parser to be used, but currently is just an alias for + +space"). Another identifier |comment| is a placeholder for + +the comment parser to be used, by default it is an alias for + `PPScomment'. Lines just containing |%%| (without the space) may be + used to suppress empty code lines preceding section titles and for + keeping some visual, relieving space between code and comment lines. + + The style I described previously may be considered ``unprofessional." + The many \LaTeX\ packages documented using the 'doc'\slash'.dtx' + system don't use comment marks for \emph{``commenting-out"}. + Or one may mark code commented out by putting no space between the -percent mark and the code. I could add a parser |PScomment| to deal -with this kind of packages later. + +percent mark and the code. + +With v0.4 of 'makedoc', this style is supported as |PScomment|. + +You can directly call this as <main-parser> as described below, + +or you can switch to it by + +\[`\CopyFDconditionFromTo{PScomment}{comment}'\] + + \subsection{Markup in comments} + Packages using the 'doc'\slash '.dtx' system as well as alternative + highly developed systems mentioned above use (enhanced) usual + \emph{\LaTeX} syntax for markup of comments. Other packages just use + an \emph{ASCII} style \emph{without} any markup. My idea was to + support the latter style by some `txt'$\to$\LaTeX\ functionality. + 'makedoc' does this using a file 'mdoccorr.cfg' which is very small + right now. + + I also thought of introducing another sort of ``decent" markup not + needing much more space than the ``ASCII kernel" of the comments. + This is to some extent implemented in 'niceverb.sty'. I thought of the + syntax of editing \textit{Wikipedia} pages; this is partially + implemented in 'wiki.sty' which unfortunately is not yet compatible + with 'niceverb'. + + But 'makedoc' implements one \textit{Wikipedia} feature in a different + way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows: + \begin{eqnarray*} + \endcell\endcell`%% == Section =='\\ + \endcell\endcell`%% === Subsection ==='\\ + \endcell\endcell`%% ==== Subsubsection ====' + \end{eqnarray*} + i.e., you type `== <title> ==' in place of `\section{<title>}' etc. + The parser must replace `====<title3>===' before `===<title2>===' and + the latter before `==<title1>=='. In fact, 'makedoc' provides three + parsers for these situations: + \begin{description} + \cmdboxitem|\SectionLevelThreeParseInput| is the most general parser + offered. If it does not find two strings \lq`===='\rq\ enclosing + \emph{something}, it passes to + \cmdboxitem|\SectionLevelTwoParseInput| which unless finding + two strings `===' enclosing something passes to + \cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment + detector |comment|. + \end{description} + + + \section{Requirements} + 'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand' + etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same + directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the + \LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it + should be installed anyway, or you can get its latest version + (v2.3, 2008/06/03?) from CTAN. + + 'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file + 'mdoccorr.cfg' that should have come along with 'makedoc.sty' and + 'fifinddo.sty'. You may need to have a modified copy of it in the + directory of your main `.tex' file `<jobname>.tex' fitting special + needs of your project. + + \section{Using 'makedoc' the simplest way} + In the most simple case, you are preparing documentation for a package + file `<jobname>.sty' only, and you prepare a file `<jobname>.tex' + containing + \[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\] + and `\maketitle' etc.\ about your package.\footnote{With 'niceverb' + and &\title\ after &\begin{document}, you may replace + \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.} + The documentation will be produced by running `<jobname>.tex' with + \LaTeX\ (e.g., \texttt{latex <jobname>.tex}). + + First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble. + There are no package options. + + Second, to typeset the commented implementation from `<jobname>.sty', + include in <jobname>.tex's `document' environment a line + \[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\] + <header-lines> refers to a non-negative integer as follows: + We think the most simple and useful way of typesetting the first lines + of a package file including license and copyrights is ``depicting them + as image," i.e., \textit{verbatim}. We could try to determine the + number of these lines by parsing, but we won't do so soon. Please just + count them and enter the number as <header-lines>---and change it + until you can accept the outcome. + + \section{Steps of advanced usage} + \subsection{Different main parsers (second mandatory argument)} + + `\MakeInputJobDoc''s mandatory syntax actually is + \[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\] + <main-parser> refers to the parsing macro that is applied to each + input line whose number is greater than <header-lines>. + Examples for <main-parser> are named in section~\ref{sec:styles} above. + %% TODO above/below macro 2010/03/15 + `\SectionLevelThreeParseInput' is just the most general one. + For \emph{efficiency} (!? or also to avoid problems?) you may + replace `Three' by `Two' or by `One', if the `====' or the `===' + feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia} + sectioning" feature is not used at all, use + \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\] +---provided you want to adopt the \lq`%% '\rq\ style of marking + +comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style + +instead, use + +\[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\] + + + \subsection{Different extensions (optional arguments)} + If your package to be documented is a \emph{class} `<jobname>.cls', + a local configuration file `<jobname>.cfg' or something + else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg', + use + \[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\] + Moreover, `\MakeInputJobDoc' writes an intermediate file + `<jobname>.doc' and then `\input's it. If you do not like `doc' + as extension for the written file name (maybe you use + `<jobname>.doc' for something different already), preferring extension + <ext-out>, use + \[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\] + Yes, you must state <ext-in> then as well, I can't help $\dots$ + + If even <jobname> is wrong in your view, see next step $\dots$ + + \subsection{Commands modifying &\MakeInputJobDoc's behaviour} + \label{sec:modimake} + Already <jobname> may not be what you want. E.g., you may want + to collect documentations of some other files <job-1>, <job-2>, + $\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc' + with + \[`\renewcommand*{\mdJobName}{<job-1>}'\] + etc.\ (please reason yourself about additional requirements \dots) + As a matter of fact, `\MakeInputJobDoc' reads + \[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad} + `\mdJobName.<ext-out>'\] + Stated another way, <jobname> above referred to |\mdJobName|. + + `\MakeInputJobInput' moreover (by default) produces one dot + per input line processed on screen to show progress. + The reason is that `makedoc' issues the command + |\ProcessLineMessage{\message{.}}|. + Already this trivial thing seems to slow down processing considerably + (nowadays). `\MakeInputJobInput' will run faster if preceded by + \[|\ProcessLineMessage{}|\] + which will suppress any message about processing. + However, the message may be helpful in trouble-shooting. + + \subsection{Separating preprocessing from typesetting} + %% extended 2010/03/16 + To some surprise, I observe that `\MakeInputJobDoc' \emph{works.} + This is quite a new discovery of mine (2010/03/13); + before I thought that, for safety, preprocessing should happen + inside a local group \emph{preceding} `\documentclass'. + |\MakeJobDoc| works like `\MakeInputJobDoc' described above, + yet it just \emph{preprocesses} the package to be documented, + waiting for an + \[`\input{<jobname>.<ext-out>}'\] + in the `document' environment to \emph{typeset} the documentation. + So 'makedoc.tex' once had in its preamble + % \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\] + % at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later. + \begin{eqnarray*}\endcell\endcell + `{\RequirePackage{makedoc}'\cr \endcell\endcell + ` \ProcessLineMessage{}'\cr \endcell\endcell + ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr + \endcell\endcell + `\documentclass{article}' + \end{eqnarray*} + I did experience some truth in my earlier safety policy: + With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used + in the `document' environment. `\MakeInputJobDoc' in fact does some + 'niceverb' switching (provided 'niceverb' has been loaded) + when making use of `\MakeJobDoc'. + %% <- verbose to improve line breaks 2010/03/16 + + Thinking of this ``safety" approach, especially grouping (`{\code}'), + I had not much cared for compatibility with other packages + in choosing 'makedoc' macro names. + + \subsection{Other 'makedoc' (and 'fifindo') script commands} + The next script commands may be considered of a lower level than + `\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter + commands. We also list commands from 'fifinddo.sty' that may be useful + or, indeed, are needed for preparing package documentations. + This may result in ideas on how do use the script commands for + different purposes than for preparing package documentations---e.g., + apply `txt'$\to$\TeX\ preprocessing to arbitrary text files. + + \subsubsection{Choosing parameter values for next preprocessing run} + + This actually continues section~\ref{sec:modimake}. + + \begin{description} + \cmdboxitem|\ResultFile{<output>}| (from 'fifinddo') + determines (and opens through the \TeX\ primitive `\openout') + the file <output> which will contain the result of + preprocessing the package file. + \cmdboxitem|\LaTeXresultFile{<output>}|---see next section. + \cmdboxitem|\Headerlines{<number>}| determines the <number> of lines + starting the input file to be copied \emph{verbatim} + (the first mandatory argument of `\MakeJobDoc'). + \cmdboxitem|\MainDocParser{<parser>}| determines the <parser> + as in the \emph{second} mandatory argument of `\MakeJobDoc'. + \end{description} + + We are now describing some parameters which rather must be switched + ``manually" instead of being modifiable by comfortable 'makedoc' + script commands. + + With the \emph{``Wikipedia sectioning"} feature, you may change the outcome + regarding levels. Assume, e.g., the package file has titles along the + scheme `== <title> ==' only, but these should become + \emph{subsections} of the ``implementation" section of the + corresponding `.tex' file. Then + \[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\] + -- see the implementation of the sectioning feature for details. + + There is a command + \[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad} + |\OnEmptyInputLine|\] + which is modified by the former. However, I cannot say much about them + right now, I think they just were a difficult matter that I soon + decided no longer to think about for a while (cf.\ the + implementation). About the same holds for the hook |\EveryComment|. + + The `txt'$\to$\TeX\ functionality is implemented through a hook + \[|\MakeDocCorrectHook{<characters>}|\] + 'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e., + it won't change <characters>. 'mdoccorr.cfg' should redefine it so it + really ``corrects" <characters>. You might try other definitions of + `\MakeDocCorrectHook' for different ``correcting" functions. + It should be \emph{noted} that (currently) + `\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty' + provides setup for (expandable) chains of expandable replacements. + The ``Wikipedia" sectioning feature moreover uses expandable + trimming (single) surrounding spaces, this might be provided in a more + general way.\footnote{%% TODO 2010/03/16 + The \ctanpkgref{trimspaces} package + has been a \emph{model} for this feature here. It cannot be used + directly here because it reads blank spaces as \TeX\ characters with + category code 10 while 'makedoc' reads blank spaces as ``other" + characters (category code 12) in order to \emph{keep} all blank spaces.} + + \subsubsection{``Manual" insertions to the output file} + \begin{description} + \cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes + <balanced> to <output> according to the earlier command + `\ResultFile{<output>}'. + \cmdboxitem|\WriteProvides| (from 'fifindo') writes a + `\ProvidesFile' line into <output> that declares the file + to be generated by 'fifindo'. + \cmdboxitem|\LaTeXresultFile{<output>}| issues + `\ResultFile{<output>}' and then writes a + `\ProvidesFile' line into <output> that declares the file + to be generated by 'makedoc'. + \end{description} + + \subsubsection{Processing input and closing output} + \begin{description} + \cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em + reads 'mdoccorr.cfg' + (for `\MakeDocCorrectHook', see above), + %% removed \LaTeXresult... 2010/03/17 + copies <number> according to `\HeaderLines' (see above) + from <input> into <output> (according to `\ResultFile'), + then processes the remaining lines of <input> according + to `\MainDocParser' (writing several things to <output>). + `\MakeDoc' invokes{\sloppy\par} + \cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}| + (from 'fifindo') reads <input> line by line---each one stored as + macro |\fdInputLine| and applies <loop-body> to it. + \TeX's ``special" character codes (of characters listed in + macro `\dospecials') are replaced by 12 (``other") by + default---see the 'fifinddo' documentation. + \cmdboxitem|\CloseResultFile| (from 'fifinddo') + \hskip 0pt plus 1em + \emph{closes} + <output> (using \TeX's primitive `\closeout'). + \cmdboxitem|\MakeCloseDoc{<input>}| issues + `\MakeDoc{<input>}\CloseResultFile'. + \end{description} + % + Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing + additional <input> files writing into the same <output>. Or maybe you + want to add some additional lines manually to <output> using + `\WriteResult'. + + %% removed 2010/03/09: + % At least in the long run, using 'makedoc' should not imply commitment + % to a certain design or to certain \LaTeX\ packages for typesetting + % listings and documentations. Therefore, 'makedoc.cfg' (currently) + % contains \emph{local} or \emph{personal choices}, but also + % \emph{experiments} with future features of 'niceverb'. + % Especially, (at present) the `packagecode' + % environment that 'makedoc' `\write's must be chosen. + % Currently this is the `listing' environment from 'moreverb' + % with some modifications or extra settings. + % It may be vital to `\MakeOther' the active characters from 'niceverb' + % in the setup of `packagecode'. See the \emph{example} in + % section~\ref{sec:fifinddo}. + % + % Finally, + % Each package file to be typeset needs its own little + % \emph{script} of 'makedoc' commands. + % With v0.3, one or two of these should suffice. + + % It should fit into the preamble + % of the main file for documenting the package (currently %% 2009/04/09 + % just 5 commands seem to suffice, see the \emph{example} in + % section~\ref{sec:fifinddo}). + % The script commands are described + % in the \dqtd{File handling} section of 'fifinddo.pdf' and in the + % present section~\ref{sec:script} (and \ref{sec:emptylines}). + % As an alternative, you may prefer to have ``content only" (as much as + % possible) in the main typesetting file and in its preamble only + % `\input' a separate script file. + %% removed 2010/03/10: + % Yes, the idea of documenting a package \emph{here} is to have a + % separate ``driver" file for typsetting the documentation. + % It may contain an introduction and a guide for users. + % The documentation of the package code that has been prepared by the + % 'makedoc' script will be `\input'. Alternatively, the ``driver file" + % could have title etc.\ only, or preamble and a minimal `document' + % environment only. + % + % So there may be many files, which may look confusing, especially as + % compared with the 'doc' procedure. However, + % \begin{enumerate} + % \item ``One file distribution" still is possible thanks to the + % `filecontents' environment. + % \item The 'makedoc' script can create a batch file (fitting the + % system, maybe using Will Robertson's 'ifplatform', or + % 'texsys.cfg', or \dots) + % that removes certain auxiliary files or moves them to a + % certain directory. + % \item I find it helpful to have rather little ``contentual" text + % in the package file. + % \item The procedure now runs very smoothly, once the stumbling blocks + % have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'! + % 'niceverb' v0.1 was too sloppy with + % some things, and self-documentation of 'makedoc.sty' was + % difficult---its parsing and that from 'verbatim' cannot + % distinguish between markup code and typeset code.} + % \end{enumerate} -\section{Examples (documentation of 'mdoccorr.cfg')} + + +\section{Examples}%%% (documentation of 'mdoccorr.cfg')} + %% moved here 2010/03/23 + +\subsection{'nicetext', especially 'mdoccorr.cfg'} + The documentations of 'fifinddo', 'makedoc', and 'niceverb' + themselves are typeset using 'makedoc'. + 'fifinddo.pdf' documents 'fifinddo.sty', typeset + from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'. + % Section~\ref{sec:fifinddo} contains a listing of + % 'makedoc.cfg' and + % the 'makedoc' script file 'mkfddoc.tex' + % especially made for 'fifinddo.pdf'. + % 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input + % files that were made with 'makedoc.sty'---I have only looked at them + % when something was wrong (often syntax mistakes in typing). + The Wikipedia syntax feature + \begin{quote} + `%% === subsection ===' + \end{quote} + is used in 'fifinddo.sty' and 'niceverb.sty' only. + + Along with 'makedoc' should come files `makedoc.tpl'---a template + 'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue + on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?). + With other definitions of `\MakeDocCorrectHook'---see below---you can + use this dialogue for arbitrary replacement jobs (as an application of + 'fifinddo' rather than 'makedoc').{\sloppy\par} + + 'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following + typographical corrections in 'mdoccorr.cfg' that defines + `\MakeDocCorrectHook': + \strut\hrule + \begingroup + \hfuzz=\textwidth \advance \hfuzz by 28pt + \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< + \listinginput[5]{1}{mdoccorr.cfg} + \endgroup + \hrule\noindent\strut + This code also exemplifies the syntax 'niceverb' provides for writing + about \LaTeX\ macros. It is typeset here with 'makedoc.sty' + and then looks thus: + +% \sloppy %% 2010/03/29 + \strut\hrule + \renewcommand*{\mdJobName}{mdoccorr} + \MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}} + \hrule \noindent\strut + And this is the content of the intermediate generated file: + \hrule + \begingroup + \hfuzz=\textwidth \advance \hfuzz by 28pt + \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< + \listinginput[5]{1}{mdoccorr.doc} + \endgroup + \hrule +% \fussy %% 2010/03/29 + + + +\subsection{Packages from other authors} + +`substr.tex' should typeset a nicely formatted documentation + +of Harald Har\-der's 'substr.sty', see my own result `substr.pdf'. + +'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style + +that 'nicetext' has used itself. + + + +`arseneau.tex' should typeset nicely formatted documentations + +of a few packages by Donald Arseneau, see my own result `arseneau.pdf'. + +This demonstrates the usual \lq`% '\rq\ commenting style + +that 'makedoc' supports with v0.4. + + + +\pagebreak %% 2010/03/29 + +\ResetCodeLineNumbers %% 2010/03/29 + \section{Implementation} + \subsection{Preliminaries} + Head of file (Legalese): + \sloppy + \renewcommand*{\mdJobName}{makedoc} + \ProcessLineMessage{} + \MakeInputJobDoc{22}{\ProcessInputWith{comment}} + The previous empty code line is the one \TeX\ insists to add at every + end of a file it writes. %% todo TeXbook where? 2009/04/08 + + %% removed (TODO) 2010/03/15: + % \section{Examples: documentation of 'fifinddo'} + % \label{sec:fifinddo} + %% removed 2010/03/10: + % \subsection{'makedoc.cfg'} + % 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following + % configuration file 'makedoc.cfg': + % \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< + % %% <- TODO should be 'niceverb' command 2009/04/08 + % \listinginput[5]{1}{makedoc.cfg} + % \endgroup + % + %% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15 + % \subsection{'mkfddoc.tex'} + % 'fifinddo.pdf' was typeset with the following 'makedoc' script file + % 'mkfddoc.tex': + % \begingroup + % \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< + % \listinginput[5]{1}{mkfddoc.tex} + % \endgroup + % + % + \end{document} + + 2009/04/12 more on examples + 2009/04/15 exemplification of niceverb.sty by mdcorr.cfg + 2009/04/21 === subsubsection -> === subsection + 2010/03/08 moved `only' for better line break + 2010/03/09 removed something from "Basics" + 2010/03/10 more changes in "Basics", pdf stuff to makedoc.cfg, + makedoc.cfg no longer example; CodeDoc + 2010/03/11 use \MakeCloseDoc; \hfuzz with \listinginput; + tracing spurious `Label(s) may have changed' + 2010/03/12 tests for hyperref compatibility completed + 2010/03/13 use \MakeInputJobDoc; clarified ...; ctan.org/pkg + 2010/03/14 updated ``Examples" and abstract; \href...easylatex + 2010/03/15 ``styles supported"; abstract: txt->TeX; usage + 2010/03/16 more on usage; mdcorr -> mdoccorr + 2010/03/17 corr. mistake with \MakeDoc + 2010/03/19 '' -> " + 2010/03/20 for niceverb v0.31 + 2010/03/21 for niceverb v0.32 + 2010/03/22 "may break" + 2010/03/23 \noindent in example, moved, added mdoccorr.doc, + makedoc.tpl + +2010/03/29 \ResetCodeLineNumbers, + + examples and explanations for v0.4 + +2010/03/30 \listfiles test + diff --git a/Master/texmf-dist/doc/latex/nicetext/mdocchea.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex index 2f8658e9815..bf191c53617 100644 --- a/Master/texmf-dist/doc/latex/nicetext/mdocchea.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex @@ -1,100 +1,208 @@ -\typeout{mdocchea.tex 2010/03/21 cheat sheat for `makedoc.sty'} +\typeout{mdoccheat.tex 2010/03/30 cheat sheat for `makedoc.sty'} + % \listfiles + \documentclass{article} + \input{makedoc.cfg} %% with pdf stuff and 'niceverb' + \makeatletter + \def\today{\the\year/\two@digits\month/\two@digits\day} + % \let\sofar@arraycr\@arraycr + \newenvironment*{displines} + {\def\ccr{\\&}% + \csname eqnarray*\endcsname&} + {\csname endeqnarray*\endcsname} + \def\@listi{\leftmargin\leftmargini + \parsep 3\p@ \@plus2\p@ \@minus\p@ + \topsep 6\p@ \@plus2\p@ \@minus4\p@ + \itemsep3\p@ \@plus2\p@ \@minus\p@} + \let\@listI\@listi + \makeatother + \newcommand*{\defto}[2]{$#1\to_{\mathit{default}}#2$} + % \sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/15 + \sloppy + \begin{document} + + \enlargethispage{1\baselineskip} %% 2010/03/29 + % \null\kern-1\baselineskip + \begin{center} + \bfseries \Large + 'makedoc' \& 'fifinddo'\footnote{\url{http://ctan.org/pkg/nicetext}} + File Handling Commands + \\[.4ex] \mdseries \large + Uwe L\"uck, \today + \\[10pt] \normalsize + |\usepackage{makedoc}|, see 'makedoc.pdf' for details + \end{center} + \thispagestyle{empty} + \par\kern5pt + \noindent \textbf{Most simple:} |\MakeInputJobDoc| + in `<jobname>.tex' \emph{after} &\begin{document} + \begin{displines} + `\MakeInputJobDoc{<header-lines>}{<main-parser>}' + \ccr + `\MakeInputJobDoc[<in-ext>]{<header-lines>}{<main-parser>}' + \ccr + `\MakeInputJobDoc[<out-ext>][<in-ext>]{<header-lines>}{<main-parser>}' + \end{displines} + documents `\mdJobName.<in-ext>' via `\mdJobName.<out-ext>', + \defto{<in-ext>}{`sty'}, \defto{&\mdJobName}{<jobname>}, + \defto{<out-ext>}{`doc'}, + \par\kern-5pt + \begin{center} %% Parsers: + \begin{tabular}{@{}l@{\hskip4pt }l@{\hskip4pt }l@{}} + <main-parser>\endcell detects\endcell involves\\\hline + `\SectionLevelThreeParseInput'\endcell + `==== <title> ===='\endcell`\mdSectionLevelThree'\\ + `\SectionLevelTwoParseInput'\endcell + `=== <title> ==='\endcell`\mdSectionLevelTwo'\\ + `\SectionLevelOneParseInput'\endcell + `== <title> =='\endcell`\mdSectionLevelOne'\\ -`\ProcessInputWith{comment}'\endcell %% removed `}' 2010/03/21 - `%% <comment>'\endcell `%%<nothing>', 'mdoccorr.cfg' + +%% 2010/03/29: + +`\ProcessInputWith{PPScomment}'\endcell + + `%% <comment>'\endcell `%%<empty>', 'mdoccorr.cfg'\\ + +`\ProcessInputWith{PScomment}'\endcell + + `% <comment>'\endcell `%<empty>', 'mdoccorr.cfg' + \end{tabular} + \end{center} + + % \par\kern-2pt + \noindent \textbf{Preprocessing before} &\begin{document}: + |\MakeJobDoc| (same parameters) + + \vskip10pt \raggedright + \noindent \textbf{More fine-grained:}\\ + \textbf{a.~Choices for next preprocessing run:} + \begin{description} + \cmdboxitem|\ResultFile{<output>}| opens <output> + % \cmdboxitem|\LaTeXresultFile{<output>}| see below + \cmdboxitem|\Headerlines{<header-lines>}| + `\MakeJobDoc''s first mandatory argument + \cmdboxitem|\MainDocParser{<main-parser>}| + `\MakeJobDoc''s second mandatory \rlap{argument} + \cmdboxitem|\ProcessLineMessage{<message>}| + \defto{<message>}{&\message{.}} + \cmdboxitem|\input{mdoccorr.cfg}| chooses `\MakeDocCorrectHook' + \end{description} + \textbf{b.~Manual insertions to <output>:} + \begin{description} + \cmdboxitem|\WriteResult{<balanced>}| writes <balanced> to <output> -\cmdboxitem|\WriteProvides| writes `\ProvidesFile' line from 'fifindo'. + +\cmdboxitem|\WriteProvides| writes `\ProvidesFile' line from 'fifindo' + \cmdboxitem|\LaTeXresultFile{<output>}| issues - `\ResultFile{<output>}', writes `\ProvidesFile' line from 'makedoc'. + + `\ResultFile{<output>}', writes `\ProvidesFile' line from 'makedoc' + \end{description} + \textbf{c.~Processing <input>, closing <output>:} + \begin{description} + \cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}| + reads each <input> line to macro |\fdInputLine|, + applies <loop-body> + \cmdboxitem|\MakeDoc{<input>}| + copies <header-lines> from <input> to <output>, + applies <main-parser> + \cmdboxitem|\CloseResultFile| closes <output> + \cmdboxitem|\MakeCloseDoc{<input>}| issues - `\MakeDoc{<input>}\CloseResultFile'. + + `\MakeDoc{<input>}\CloseResultFile' + \end{description} + + \end{document} + + diff --git a/Master/texmf-dist/doc/latex/nicetext/niceverb.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex index b1c1addef88..0bcddd9ae04 100644 --- a/Master/texmf-dist/doc/latex/nicetext/niceverb.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex @@ -1,427 +1,874 @@ -\typeout{niceverb.tex 2010/03/23 documenting niceverb.sty} +\typeout{niceverb.tex 2010/03/29 documenting niceverb.sty} + \title{\textsf{niceverb.sty}\\---\\Minimizing + Markup\\for Documenting \LaTeX\ packages%%% \thanks{This + % manual describes package version + % version 0.2 as of April 09, 2009%%%\fileversion\ as of \filedate\ + % .}}%%%of the package.}% + } + % \listfiles 2010/03/19 + { \RequirePackage{makedoc} \ProcessLineMessage{} %% 2010/03/11 + \MakeJobDoc{19}{\SectionLevelThreeParseInput} } + \documentclass{article}%% TODO paper dimensions!? + \input{makedoc.cfg} %% shared formatting settings + \begin{document} + \maketitle + \begin{abstract}\noindent + 'niceverb.sty' provides very decent syntax (through active characters) + for describing \LaTeX\ packages and the syntax of macros conforming to + \LaTeX\ syntax conventions. + \end{abstract} + \tableofcontents + + %% TODO table listing of active characters + %% Were tests 2010/03/08: + % \section{Presenting Nasty's `Nasty' ``Nasty'' &\NVerb\ 'niceverb'} + % \section{Presenting \cs{NVerb} 'niceverb'} + \section{Presenting 'niceverb'} + \subsection{Purpose} + % \begin{abstract}\noindent + % The 'nicetext' bundle provides ``minimal" markup + The 'niceverb' package provides ``minimal" markup for documenting \LaTeX\ + packages, reducing the number of keystrokes/visible characters needed + % .\,.\,. %%% ... %% TODO nicedots + (kind of poor man's WYSIWYG).\footnote{``What you see is what you + get." Novices are always warned that WYSIWYG is essentially + impossible with \LaTeX.} %% TODO UK FAQ 2010/03/11 + % One feature---\verb'&\foo'%%% badly self-documenting, `&' fails + It conveniently handles command names in arguments of macros + such as &\footnote or even of sectioning commands. + % (`.aux'/`.toc' entries). + % + % This is done by making some characters active. + % 'niceverb.sty' thus resembles 'wiki.sty'; both are siblings. + % \end{abstract} + If you use 'makedoc.sty' additionally, commands for typesetting a + package's code are inserted automatically (just using \TeX). + %%% \footnote{Stephan I. B\"ottcher used + %%% 'awk' instead to typeset the documentation of his 'lineno.sty'.} + As opposed to tools that are rather common on UNIX/Linux, this + operation should work at any \TeX\ installation, irrespective of + platform. + + Both packages may at least be useful while working at a very new package + and may suffice with small, simple packages. After having edited your + package's code + %% <jobname> 2010/02/28: + (typically in a `.sty' file---<jobname>`.sty'), + you just ``{`latex'}" the manual file + (maybe some `.tex' file---<jobname>`.tex') + and get instantly the corresponding updated documentation. + + 'niceverb' and 'makedoc' may also help to generate without much effort + documentations of nowadays commonly expected typographical quality for + packages that so far only had plain text documentations. + + \subsection{Acknowledgement/Basic Ideas} + Three ideas of Stephan I. B\"ottcher's in documenting his + \ctanpkgref{lineno} + inspired the present work: + \begin{enumerate} + \item + The markup and its definitions are short and simple, + markup commands are placed at the right ``margin" + of the ASCII file, + so you hardly see them in reading the source file, + you rather just read the text that will be printed. + \item + An 'awk' script removes the `%'s starting \emph{documentation} lines + and inserts the commands for typesetting the package's \emph{code} + (you don't see these commands in the source).\footnote{The + corresponding part of the ``present work" is 'makedoc.sty'.} + %% <- clarified 2010/03/11 + \item + An active character (\lq&|\rq) issues a `\string' \emph{and} switches + to typewriter typeface for typesetting a command verbatim---so this + works without changing category codes (which is the usual idea of + typesetting code), therefore it works even in macro arguments. + \end{enumerate} + + \subsection{The Commands and Features of 'niceverb'} + Actually, it is the main purpose of 'niceverb' to save you from + ``commands" $\dots$\par + Single quotes &`, &', ``less than" &< (accompanied + with `>'), the ``vertical" &|, the hash mark `#', ampersand `&', + and in an extended ``auto mode" even backslash `\' become `\active' + characters with ``special effects." + % \qtd{&|$\dots$&|} (i.e., \GenCmdBox+|<code>|+) in general + % should highlight descriptions of user commands and their syntax. + + The package mainly aims at typesetting commands and descriptions of their + syntax \emph{if the latter is ``standard \LaTeX-like"}, + using ``meta-variables." A string to be + typeset ``verbatim" thus is assumed to start with a single command like + &\foo, maybe followed by stars (\lq`*'\rq) and pairs of + square brackets (\lq`['<opt-arg>`]'\rq) + or curly braces (\lq`{'<mand-arg>`}'\rq), + where those pairs contain strings indicating the typical + kinds of contents for the respective arguments of that command. + A typical example is this: + \[\InlineCmdBox{&\foo*[<opt-arg>]{<mand-arg>}}\] + This was achieved by typing + \[\HardVerbBox+&\foo*[<opt-arg>]{<mand-arg>}+\] + In ``auto mode" of the package, even typing + \[\HardVerbBox+\foo*[<opt-arg>]{<mand-arg>}+\] + would have sufficed---WYSIWYG! I call such mixtures of + \emph{verbatim} and ``meta-variables" \textit{\qtd{meta-code}}. + + Outside macro arguments, you obtain the same by typing + % \[\verb+`\foo*[<opt-arg>]{<mand-arg>}'+\] + \[\HardVerbBox+`\foo*[<opt-arg>]{<mand-arg>}'+\] + + Details: + \begin{description} + + \item[``Meta-variables:"] The package supports the ``angle + brackets" style of ``meta-variables" (as with <meta-variable>). + You just type \lq\verb'<bar>'\rq\ to get \lq<bar>\rq. + + This works due to a sloppy variant `\NVerb' of `\verb' + which doesn't care about possible ligatures and definitions of active + characters. Instead, it assumes that the ``verbatim" font doesn't + contain ligatures anyway.\footnote{On the other hand, &\NVerb is more + \emph{careful} with 'niceverb''s special characters.} + \lq\verb'\verb+<foo>+'\rq, by contrast, just yields \lq\verb'<foo>'\rq. + + Almost the same feature is offered by 'ltxguide.cls' which formats the + basic guides from the \LaTeX\ Project Team. The present feature, + however, also works in plain text outside verbatim mode. + % On the other hand: without << feature + + \item[Single quotes (left/right) for ``short verb:"] + The package ``assumes" that \emph{quoting} refers to + \emph{code}, therefore \lq\verb+`foo'+\rq\ is typeset as + \lq`foo'\rq, or (generally) |`<content>'| turns <content> + into meta-code with the meta-variable feature as above. + This somewhat resembles the &\MakeShortVerb feature of 'doc.sty'. + %% Moved up here 2010/02/28: + You can ``abuse" our %%% ``single quotes" + feature just to get typewriter + typeface.{\sloppy\par}%% not so useful here 2010/02/28: + % \footnote{In macro arguments this requires that the right + % single quote &' is &\active.} + + Problems with this feature will typically arise %%% fail %% 2010/02/28 + when you try + to typeset commands (and their syntax) in \emph{macro arguments}---e.g., + $$\verb+\footnote{`\bar' is a celebrated fake example!}+$$ + will try to \emph{execute} &\bar instead of typesetting it, giving + an ``undefined" error or so. %% TODO try! 2010/02/28 + \verb+\verb+ fails in the same situation, for the same reason. + \lq\verb+&+\rq\ (&\footnote{&&&\bar<remaining>}) or + ``auto mode" (see below) may then work better.\footnote{&\bar indeed!} + More generally, the quoting feature still works in macro arguments in + the sense that you then have to mark difficult characters with `&' + (simply as short for `\string'). However, it still won't work with + curly braces that don't follow a command name + (such \emph{pairs} of braces will simply get lost, + \emph{single} braces will give errors or so).%%%\footnote{`{group}'} + + Double quotes and apostrophes should still work the usual way. + % %% TODO doesn't work, inside runs into `}' 2010/02/28: + % otherwise you could control the parsing mechanisms using curly braces + % (outside and inside don't interact: `Harry{'}s' for \qtd{Harry's}). + For difficult cases, you can still use the standard `\verb' + command from \LaTeX. + To get \emph{usual} single quotes, you can use their standard substitutes + `\lq' and `\rq', or for pairs of them, + |\qtd{<text>}| in place of `\lq <text>\rq'---or even `\lq <text>\rq\ '. + + \item[Single right quotes for &\textsf:] + Package names are (by some convention I often yet not always + see working) + typeset with `\textsf'; + it was natural to use a remaining case of using single quotes + for abbreviating $$&\textsf{<text>}$$ by |'<text>'|. + % \footnote{% + % Font switching by sequences of single quotes is a feature of the + % syntax for editing \textit{Wikipedia} pages and of 'wiki.sty'.} + %% <- undoubled 2010/02/28 -> + This idea of switching fonts continues font switching of 'wiki.sty' + which uses the syntax for editing {\it Wikipedia} pages + (font switching by sequences of right single quotes). + + \item[Verticals for setting-off command descriptions:]%%% + \hskip0pt plus 2em + \GenCmdBox+|<code>|+ works like \qtd{&`<code>&'} except putting + the result into a \emph{framed box} (just as all around + here)---or something else that you can achieve using some \emph{hooks} + described with the implementation. There are variants like + \GenCmdBox+\cmdboxitem|<code>|+. + + \item[Ampersand shows command syntax \&c. even in arguments:] + \hfil E.g., type \lq\verb+&\foo{<arg>}+\rq\ to get + \lq`\foo{<arg>}'\rq. This may be even more convenient for typing than + the single quotes method, although looking somewhat strange. + However, in macro arguments this does not work with + \emph{private letters} (`@' and `_' here), for this case, + use |\cs{<characters>}| or |\cstx{<characters>}<parameters>|.%%% + % `&' may terminate \textit{verbatim} unexpectedly, being designed for + % displaying ``\LaTeX-like command syntax" in the first instance. + \footnote{Moreover, && currently has a limited 'xspace' + functionality only.}%%%\footnote{You can even use && for referring to + % active characters like && in footnotes etc.!} + %% <- said elsewhere now 2010/03/07 + + \begin{sloppypar} + This choice of `&' rests on the assumption that there won't be many + tables in the documenation. You can restore the usual meaning of `&' + by `\MakeNormal\&' and turn the present special meaning on again by + \[`\MakeActive\&' \mbox{\quad or\quad } + `\MakeActiveLet\&\CmdSyntaxVerb'\] + You could also + redefine (&\renewcommand) &\descriptionlabel using `\CmdSyntaxVerb' + (the ``normal command" that is equivalent to `&', its ``permanent + alias") + so \verb+\item[\foo]+ works as wanted. + \end{sloppypar} + + \textbf{Another} feature of 'niceverb''s `&' is getting + (some of the) special characters %% 2010/03/20 + (as listed in the standard macro `\dospecials') verbatim in arguments + (where `\verb' and the like fail). It just acts similarly as \TeX's + (as listed in the standard macro `\dospecials') verbatim in arguments + (where `\verb' and the like fail). It just acts similarly as \TeX's + primitive `\string' (which it actually invokes---cf. discussion on the + left quote feature above). + + \item[``Auto mode" typesets commands verbatim unless .\,.\,.] + \begin{sloppypar} -In~``auto mode", the backslash \lq`\'\rq\ is an active character that + +In~``auto mode," the backslash \lq`\'\rq\ is an active character that + builds a command name from the ensuing letters and typesets the + command (and its syntax, allowing meta-variables) verbatim. + However, there are some exceptions, which are collected in a macro + |\niceverbNoVerbList|. &\begin, &\end, and &\item belong to this list, + you can redefine (`\renewcommand') it, or add <macros> to it by + |\AddToMacro{\niceverbNoVerbList}{<macros>}| + There is also a command |\NormalCommand{<letters>}| \emph{issuing} the + command `\<letters>' instead of typesetting it. + Since auto mode is somewhat dangerous, you have to start it explicitly + by |\AutoCmdSyntaxVerb|. You can end it by |\EndAutoCmdSyntaxVerb|. + |\AutoCmdInput{<file>}| is probably most important. + \end{sloppypar} + + Auto mode is motivated by the observation that there are package files + containing their documentation as pure (well-readable) ASCII + text---contain\-ing the names of the new commands without any kind of + quotation marks or verbatim commands. + Auto mode should typeset such documentation just from the same ASCII + text. + + \item[Hash mark \lq&#\rq\ comes verbatim.] + No macro definitions are expected in the `document' + environment.\footnote{This idea appeared 2009 on the 'LATEX-L' + mailing list. It may be wrong, + as I have sometimes experienced $\dots$} + %% <- changed 2010/03/11 + Rather, \lq`#'\rq\ is an active character for taking the next + character (assuming it is a digit) to form a reference to a + \emph{macro parameter}---\lq`#1'\rq\ becomes \lq#1\rq\---WYSIWYG + indeed! (So the general syntax is |#<digit>|.) + \item[Escaping from 'niceverb' (generally).] + To get rid of the functionality of some active character <char> + (\qtd{&&}, single quote, ampersand, hash mark---not - ``auto mode", see above) here, use |\MakeNormal\<char>|---may + + ``auto mode," see above) here, use |\MakeNormal\<char>|---may + be within a group. To revive it again, use |\MakeActive\<char>|. + This may fail when a different package overtook the active <char> + (but I expect more failures then), in this case + |\MakeActiveLet\<char>\<perm-alias>| + revives the 'niceverb' meaning of <char> + where `\<perm-alias>' is the ``permanent alias" for that active + <char> according to the documentation below. + E.g., `\LQverb' is the ``permanent alias" for active single left + quote, 'niceverb' activates it by + \NVerb+\MakeActiveLet\'\LQverb+.---You can turn off 'niceverb' + syntax \emph{alltogether} by |\noNiceVerb| and revive it + by |\useNiceVerb| (without ``auto mode").{\sloppy\par} + + \textbf{Right Quotes:} Disabling\slash reviving replacement + of `\textsf' by single right quotes requires + \[|\nvRightQuoteNormal| \mbox{\quad or\quad } |\nvRightQuoteSansSerif|\] + respectively. + \end{description} + + \subsection{Examples} + The file 'mdoccorr.cfg' providing some `.txt'$\to$\LaTeX\ + functionality---i.e., typographical corrections---documents itself + using 'niceverb' syntax. Its code and the documentation that is + typeset from it are in the \qtd{examples} section of + 'makedoc.pdf'.---Moreover, + the documentation 'niceverb.pdf' of 'niceverb.sty' was + typeset from 'niceverb.tex' and 'niceverb.sty' using 'niceverb' + syntax, likewise 'fifinddo.pdf' and 'makedoc.pdf'. + The example of 'niceverb' shows the most frequent use of the `&' + feature.{\sloppy\par} -'nicetext' bundle release v0.3 contains a file 'substr.tex' + + +'nicetext' bundle release v0.4 contains a file 'substr.tex' + that should typeset the documentation of the version of + Harald Harder's + 'substr.sty'\footnote{\url{http://ctan.org/pkg/substr}} -that your \TeX\ finds first. This is the first application of -'niceverb''s ``auto mode" to a third-party package -(without manual modification). + +that your \TeX\ finds first, as well as 'arseneau.tex' + +typesetting a few packages by Donald Arseneau. + +The outcomes (with me) are 'substr.pdf' and 'arseneau.pdf'. + +These are the first applications of 'niceverb''s ``auto mode" to + +(unmodified) third-party package files. + +(I also made a more ambitious documentation of Donald Arseneau's + + 'import.sty v3.0' before I found that CTAN already has a nicely + + typeset documentation of 'import.sty v5.2'.) + + %% removed 2010/03/11: + % It seems to me that I could type so many pages on 'fifinddo' and + % 'makedoc' in little more than a week + % % (2009/04/12, much of which was needed for debugging and reworking concepts) + % only due to the ``minimal" \emph{verbatim} and syntax-display syntax. + % + \subsection{What is Wrong with the Present Version} + \begin{enumerate} + \item 'niceverb.sty' should be an extension of 'wiki.sty'; + yet their font selection mechanisms are currently not compatible. + %% 2010/02/28: - Especially, the feature of $$\mbox{|''<text>''|}$$ replacing + + Especially, the feature of \[\hbox\bgroup|''<text>''|\egroup\] + + %% <- failed with \mbox as of 2010/03/23, first two rq missing + + %% 2010/03/29 + + replacing + `\textit{<text>}' or `\emph{<text>}' may be considered missing. + \item Font switching or horizontal spacing may fail in certain + situations. + % (parentheses, titles, footnotes; + You can correct spacing by \lq`\ '\rq. + %% <- \qtd{`&\ '}. + % \item + % The feature of mixing high-quality-typeset comments into the + % package code listing is implemented in a very rudimentary way only. + % % just allowing for `\subsection's. + % The ``comment detector" detects Wikipedia-style subsection titles + % instead of lines beginning with percent characters.\footnote{% + % Percent characters will definitely not be ``ignored" as with &\DocInput, + % rather they will hide rests of \emph{documentation} lines as usually, + % while they will be typeset verbatim in \emph{package code} lines.} + % Switching between plain and verbatim typesetting in the package + % listings isn't settled yet, since there are different styles of using + % percent symbols. I have sometimes used double percent symbols + % (\lq\verb+%%+\rq) + % for commenting text and single ones just for ``reversible deletion of + % code," while usually single percent symbols indicate commenting text + % indeed. Double percent symbols may, by contrast, mean that the text remains + % visible in the `.sty' file only, suppressed in the typeset + % documentation ('lineno.sty'). + % For a while, it may be necessary to provide replacing macros for each + % package separately instead of providing a single macro package + % managing all of them. + % \item + % The code listing currently uses the `listing' and `listingcont' + % environments of 'moreverb.sty'; + % the code font and the line numbers may be too large. + \item The ``vertical" character \qtd{&|} produces inline boxes + only at present. It might as well provide a version of the + `decl' tabular environment of 'ltxguide.cls'. + %% changes 2010/03/10 + % coloured\slash framed boxes instead (2009/04/09). They have + % their merits! See 'fifinddo.pdf' and 'makedoc.pdf'. However, + % they + The inline boxes + badly deal with long command names and many arguments. + Doubled verticals could ensure the `decl' mode. + Moreover, such a box might issue an \emph{index} entry. + \item One may have \emph{opposite} ideas about using quotes---maybe + rather `"<code>"' should typeset <code> \textit{verbatim}. + There might be a package option for this. If ordinary + \qtd{\NVerb'``<text>"'} still should work, awful tricks as now with + the right quote feature would be needed. %% TODO 2010/03/06 + % \item ``Auto mode" has \emph{not} been tested on a serious application yet. + %% partially improved 2010/02/28: + % \item % 'niceverb''s font switching tricks sometimes turn against their + % % inventor (and other users?). There must be some switching + % % ``off'' (and ``on'' again).% + % % \footnote{\hspace{1sp}'fifinddo'\slash\hspace{1sp}'makedoc' + % % %% <- TODO oh, oh! 2009/04/11 + % % allow inserting such commands from a driver script, + % % invisible in the file that contains the ``contentual'' + % % documentation.} + % % Also, there + % There + % might better help with weird errors, + % some syntax checks might intercept earlier. + % + % Similarly, some choices reflect a %% rather OK 2010/02/28 + % personal style and should be modifiable, especially by package + % options.\footnote{Please sponsor the project or support it + % otherwise!} + \item Certain difficulties with typesetting code in macro arguments + may be overcome easily using $\varepsilon$\mbox{-}\TeX\ + features, I need to find out $\dots$ + \end{enumerate} + + \section{Implementation of the Markup Syntax} + \input{niceverb.doc} + \end{document} + + HISTORY + + 2009/04/09 adjusted to new doc-generation method + 2009/04/12 examples, 'awk' lower-case + 2009/04/15 example 'mdcorr.cfg', abstract, + \pagebreak to implementation + 2010/02/27 replaced `|' by `+' with \verb + so `|' works as announced + 2010/02/28 "Missing:" ''...'' 'wiki' feature, + somethings aren't missing anymore + (or otherwise removed); more on quotes; + applying |...| + 2010/03/05 \SimpleVerb -> \NVerb; after intro on `&' quotes as well + 2010/03/06 typo in ``examples''; removed makedoc.cfg sample; + more on `&' + 2010/03/07 without \listfiles + 2010/03/09 hyperref ... \input{mdcorr.cfg}!, |...| settled + 2010/03/10 moved pdf stuff to 'makedoc.cfg'; + do use 'mdcorr.cfg' for demo; future of | + 2010/03/11 applied \MakeJobDoc and shortened preamble; + various minor doc changes + 2010/03/12 ``Ampersand" improved; \noNiceVerb + \useNiceVerb + 2010/03/14 use \InlineCmdBox and \HardVerbBox; |...| described + 2010/03/18 \AddToMacro; ``auto mode" tested seriously (substr.sty) + - \AutoCmdInput + 2010/03/19 line break changes; '' -> " + 2010/03/20 testing niceverb v0.31 + 2010/03/23 `mdoccorr.cfg' example again + +2010/03/27 ``auto mode," + +2010/03/29 \mbox -> \hbox in display; arseneau.tex/pdf + diff --git a/Master/texmf-dist/doc/latex/nicetext/wikichea.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex index e56bff99120..4f04ff16bce 100644 --- a/Master/texmf-dist/doc/latex/nicetext/wikichea.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex @@ -1,148 +1,296 @@ \ProvidesFile{wikicheat}[2008/07/10 Cheatsheet for wiki.sty] + % \def\title{Cheatsheet for the \textsf{wiki} Package} + \def\title{\textbf{Cheatsheet} for the \textbf{\textsf{wiki}} Package} + \def\author{Uwe L\"uck} + \documentclass[12pt,a4paper]{article} + \nofiles + \pagestyle{empty} + \makeatletter + \@ifundefined{UndeclareTextCommand}{}{\usepackage{upquote}} %% 2008/07/02 + \makeatother + \usepackage{wiki} + % \let\WE\relax \let\WF\relax \let\WH\relax + \let\WE\wikiEnvironments + \let\WF\wikiFonts + \let\WH\wikiHeadings + \def\SP#1{\multicolumn{3}{\VR c\VR}{% + % \parbox{11cm}{% + \parbox{13cm}{% + \footnotesize\it\sloppy\SU#1\SD}}} + \def\SL{/\hskip.16667em} + % \setbox0\hbox{(}\showthe\ht0\showthe\dp0 %% height = 3x depth + \def\SU{\rule{0pt}{.99em}}%%%{1.1em}} + \def\HSU{\rule{0pt}{.75em}} + \def\SD{\rule[-.33em]{0pt}{0pt}}%%%45em]{0pt}{0pt}} + % \def\CS#1{{\tt\textbackslash #1}} %% 2008/07/02 + {\makeatletter \gdef\CS#1{{\tt\@backslashchar#1}}} + \let\VR| \catcode`\|\active \def|{\verb|} + \begin{document} + % \maketitle + + \enlargethispage{3\normalbaselineskip} + \vspace*{-\topmargin} %% !? + \vspace*{-\headheight}\vspace*{-\headsep}\vspace*{-\topsep}\vspace*{-\partopsep} + \begin{center} + \large \title\\[.4ex] \normalsize + Some \LaTeX-Markup through some Wiki-Markup\\[.8ex] + \author, \today + % \end{center} + + \vspace{\topsep} + \vspace*{\partopsep} + % \vspace{1.5ex} + % \vspace{1ex} + % \hrule + % \vspace{1ex} + + % \begin{center} + \leavevmode\kern-1em + \begin{tabular}{\VR l\VR l\VR l\VR} + \hline\hline + \SU\SD\bf Code for \textsf{wiki.sty}&\bf What you get& \bf like \LaTeX-code\\ + \hline\hline + |''italic''|&\WF ''italic''&|\textit{italic}|\SU\\ + |'''bold'''|&\WF '''bold'''&|\textbf{bold}|%%%\\ + \SD\\ + % |'''''bf+it'''''|&\WF '''''bf+it''''' + % &|\textbf{\textit{bf+it}}|\SD\\ + % |'''''B+I'''''|&\WF '''''B+I''''' &|\textbf{\textit{B+I}}|\SD\\ + \hline + \SP{``Italic'' and ``bold'' may be combined, nested, overlap. + % Automatic italic correction cannot be suppressed by \CS{nocorr}. + % Implementation uses \LaTeX\ internals; no groups are formed. + Quotation marks + % (even German) + usually are not + affected.---Turn + % {\tt '\string{\string}''} may help with + % apostrophes.---Turn + font feature on/off by \CS{wikiFonts}\SL\CS{nowikiFonts}; disable feature + entirely by package option {\tt noFonts}.}\\ + \hline\hline + |== Level 1 ==|&\Large\bf\HSU 1\quad Level 1&|\section{Level 1}|\SU\\ + |=== Level 2 ===|&\large\bf 1.1\quad Level 2&|\subsection{Level 2}|\SU\\ + |==== Level 3 ====|&\bf 1.1.1\quad Level 3&|\subsubsection{Level 3}|\\ + |===== Level 4 =====|&\bf Level 4 &|\paragraph{Level 4}|\SD\\ + |====== Level 5 ======|&\bf Level 5 &|\subparagraph{Level 5}|\SD\\ + \hline + \SP{Turn heading feature on/off by \CS{wikiHeadings}\SL\CS{nowikiHeadings}; + disable feature entirely by package option {\tt noHeadings}.}\\ + \hline\hline + &&|\begin{itemize}|\SU\\ + |* One|&\textbullet\hspace\labelsep One &|\item One|\\[2\parsep] + |* Two|&\textbullet\hspace\labelsep Two &|\item Two|\\ + &&|\end{itemize}|\SD\\ + \hline + &&|\begin{enumerate}|\SU\\ + |# One|&1.\hspace\labelsep One &|\item One|\\[2\parsep] + |# Two|&2.\hspace\labelsep Two &|\item Two|\\ + &&|\end{enumerate}|\SD\\ + \hline + &&|\begin{description}|\SU\\ + |;[club] explain|&\textbf{club}\hspace\labelsep explain + &|\item[club] explain|\\[2\parsep] + |;[widow] explain|&\textbf{widow}\hspace\labelsep explain + &|\item[widow] explain|\\ + &&|\end{description}|\SD\\ + \hline + & &|She wrote:|\SU\\ + |She wrote:|&\smash{\raisebox{\topsep}{She wrote:}}&|\begin{quote}|\\ + |:Indeed| &\hspace\leftmargini Indeed&|Indeed|\\ + & &|\end{quote}|\SD\\ + \hline + & &|Type|\SU\\ + |Type| &\smash{\raisebox{\topsep}{Type}}&|\begin{verbatim}|\\ + | \typeout{OK!}| &|\typeout{OK!}|&|\typeout{OK!}|\\ + & &|\end{verbatim}|\SD\\ + \hline + \SP{A \CS{begin} is executed when {\tt*} etc.\ is first character of a + code line; an indent starts {\tt verbatim}. + \CS{end} is executed at code line without indent and not beginning with + {\tt*} etc.---Turn this feature on by \CS{wikiEnvironments}; turn off by + \CS{nowikiEnvironments}, e.g., to get around incompatibilities + (lists feature is most dangerous). + Disable feature entirely by package option {\tt noEnvironments}. + Package option {\tt noVerbatim} instead may usually suffice, + if you don't want to have any {\tt verbatim}.}\\ + \hline + \end{tabular} + \kern-1em + \end{center} + + % \section{Test}\subsection{Sub-Test}\subsubsection{Subsub-Test} + % \paragraph{Para}\subparagraph{Sub-Para} + + \footnotesize + % \vspace{2ex} + \sloppy + \noindent \WE\WF %%% '''Please note:''' + ''Note:'' + % * + Explicit '''turning on''' by %%% one of + % \[|\wikiEnvironments|,\quad |\wikiFonts|,\quad |\wikiHeadings|\] + |\wikiEnvironments| %%% , |\wikiFonts|, |\wikiHeadings|, + etc.\ + % or by |\wikimarkup| (which executes the former three) is ''required''; + is '''required'''; + e.g., after %%% |\maketitle| and + |\tableofcontents|. + |\wikimarkup| '''activates ''all''''' the features. + % * + |\nowikimarkup| %%% executes all of + % \[|\nowikiEnvironments|,\quad |\nowikiFonts|,\quad |\nowikiHeadings|.\] + % |\nowikiEnvironments|, |\nowikiFonts|, |\nowikiHeadings|. + % Use them to get around incompatible code. + '''''dis''ables all''' of them, e.g., to get around incompatibilities. + + \end{document} + + diff --git a/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf Binary files differdeleted file mode 100644 index aeeed3be256..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf Binary files differdeleted file mode 100644 index 0d8f4e7d09c..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/nicetext/mkfddoc.tex b/Master/texmf-dist/doc/latex/nicetext/mkfddoc.tex deleted file mode 100644 index c4a4937a963..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/mkfddoc.tex +++ /dev/null @@ -1,21 +0,0 @@ -\ProvidesFile{mkfddoc.tex}[2009/04/15 - prepare typesetting fifinddo.sty] - - \begingroup %% generate fifinddo.doc -\RequirePackage{makedoc}[2009/04/13] -\input{mdcorr.cfg} - -% \NoEmptyCodeLines %% TODO -\ProcessLineMessage{} -\LaTeXresultFile{fifinddo.doc} -\HeaderLines{23} -\MainDocParser{% -% \IfInputLine{=33}{\tracingmacros=1 }{} -% \IfInputLine{=35}{\tracingmacros=0 }{} - \SectionLevelTwoParseInput} -% \tracingmacros=1 -\MakeDoc{fifinddo.sty} -\CloseResultFile - \endgroup %% fifinddo.doc ready -\endinput - diff --git a/Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex b/Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex new file mode 100644 index 00000000000..2a1874bf912 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex @@ -0,0 +1,220 @@ +\typeout{arseneau.tex 2010/03/30 some packages by D. Arseneau} + +\title{A Few (just Two) Packages by Donald Arseneau} + +\author{Uwe L\"uck\thanks{applying \url{http://ctan.org/pkg/nicetext}}} + +% \listfiles + + + +%% Preprocessing: + +\RequirePackage{makedoc} + +% \CopyFDconditionFromTo{PScomment}{comment} + +\MainDocParser{\ProcessInputWith{PScomment}} + +%% nolbreaks: + +%% Replacements: + +\SetPatternCodes{\MakeOther\\\MakeOther\ } + +\MakeExpandableAllReplacer{LaTeX}{LaTeX }{\LaTeX{} }{LEAVE} + +% \MakeExpandableAllReplacer{TeX}{\TeX }{\TeX{} }{LEAVE} + +\PrependExpandableAllReplacer{opt}{[ragged]}{`[ragged]'} + +\PrependExpandableAllReplacer{braces}[\Delimiters<>]<{ }><`{ }'> + +\SetCorrectHookJobLast + + + +\HeaderLines{2} + +\LaTeXresultFile{nolbreaks.doc} + +\MakeCloseDoc{nolbreaks.sty} + + + +%% notoccite: + +\MakeExpandableAllReplacer{LaTeX}{LaTeX }{\LaTeX{} }{LEAVE} + +\PrependExpandableAllReplacer{caption}% + +{ \caption [}{\DISPLAY\caption[} + +\PrependExpandableAllReplacer{unsrt}{unsrt}{`unsrt'} + +\PrependExpandableAllReplacer{toc}{ toc}{ `.toc'} + +\PrependExpandableAllReplacer{lof}{lof}{`.lof'} + +\PrependExpandableAllReplacer{latex}{latex}{`latex'} + +\PrependExpandableAllReplacer{NOTE}{*NOTE*}{\textbf{NOTE:\enspace}} + +\PrependExpandableAllReplacer{does}{*does*}{\emph{does}} + +\PrependExpandableAllReplacer{bibtex}{bibtex}{`bibtex'} + +\ResetPatternCodes + +\SetCorrectHookJobLast + + + +\HeaderLines{3} + +\LaTeXresultFile{notoccite.doc} + +\MakeCloseDoc{notoccite.sty} + + + +%% Typesetting: + +\documentclass{article} + +\usepackage{hyperref,niceverb} %% niceverb after hyperref! + +\AddToNoVerbList{\DISPLAY\textbf\enspace\emph\LaTeX} + +\newcommand*{\DISPLAY}{% + + \\[\smallskipamount]\leavevmode\null\hfil} + +\makeatletter \MakeLetter\_ + +% {\MakeActive\"\gdef\DQcode#1"{\dqtd{\texttt{#1}}}} + +{\MakeActive\"\gdef\DQcode#1"{\texttt{#1}}} + +%% weird problems: + +% \newcommand*{\startDQcode} + +% {``\begingroup\MakeActiveLetHere\"\enddQcode\tt} + +% \def\endDQcode{\endgroup"} + +\pagestyle{headings} + +\usepackage{parskip} + +\begin{document} + +\maketitle + + + +\begin{abstract}\noindent + + This document demonstrates the present + + (i.e., 'nicetext' bundle release v0.4) + + capabilities of 'makedoc' and 'niceverb' + + to typeset \LaTeX\ quality documentation from + + third-party package files having ASCII comments only, + + without modifying such package files manually.\footnote{See + + \url{http://ctan.org/pkg/nicetext} + + for more on these packages.} + + Such packages usually mark comments by lines starting with + + \lq`% '\rq. This is somewhat difficult when the ``comment mark" + + \lq`%'\rq\ + + may at the same time be used for ``commenting out" in place of + + ``true commenting." As opposed to 'substr.sty' that conforms to the + + easier \lq`%% '\rq\ style, the packages 'nolbreaks' and 'notoccite' + + by Donald Arseneau exemplify the \lq`% '\rq\ commenting style. + + + + The ASCII documentation of packages of this kind + + does not always clearly indicate when switching to `\tt' is appropriate. + + This problem is solved here by string replacements very specific + + to the package files. + + The setup for these replacements + + (in the source file 'arseneau.tex') + + still may be simplified. + + %% <- 2010/03/29 + + + + Moreover, some similar packages cannot be properly typeset with + + 'nicetext' at present because 'makedoc''s loop is too rigid to deal with + + (i)~ASCII indents, displays, lists and with (ii)~instructions + + after `\endinput'. + + + + It should be clear that all the package desriptions are Donald Arseneau's, + + 'nicetext' just formats them. + +\end{abstract} + +\tableofcontents + +\pagebreak + + + +\sloppy + + + +\section{'nolbreaks'} + +% \MakeActiveLet\_\textunderscore + +% \MakeActive\*\def*{\texttt{\string*}} + +% \MakeActiveLetHere\"\startDQcode + +\MakeActiveLetHere\"\DQcode + +% \errorcontextlines=6 + +\AutoCmdInput{nolbreaks.doc} + + + +\section{'notoccite'} + +\ResetCodeLineNumbers + +\AutoCmdInput{notoccite.doc} + + + +\end{document} + diff --git a/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex index 9e5e3dda35a..e36edd2bbfd 100644 --- a/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex +++ b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex @@ -1,59 +1,116 @@ \makeatletter -\typeout{^^J*fdtxttex.tex* 2010/03/22 txt to TeX by dialogue^^J + +\typeout{^^J*fdtxttex.tex* 2010/03/30 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/doc/latex/nicetext/fdtxttex.tpl b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl index 3ea325c46c0..c9b03b314bc 100644 --- a/Master/texmf-dist/doc/latex/nicetext/fdtxttex.tpl +++ b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl @@ -1,14 +1,26 @@ -\typeout{fdtxttex.tpl 2010/03/23 fifinddo correction template} +\typeout{fdtxttex.tpl 2010/03/30 fifinddo correction template} + \RequirePackage{fifinddo} -\def\MakeDocCorrectHook#1{#1} + \input{mdoccorr.cfg} + \ResultFile{sample.tex} + \WriteProvides + \ProcessFileWith{sample.txt}{% + \typeout{\expandafter \MakeDocCorrectHook + \expandafter{\fdInputLine}}% + \WriteResult{\expandafter \MakeDocCorrectHook + \expandafter{\fdInputLine}}% + } + \CloseResultFile -\stop
\ No newline at end of file + +\stop + diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.tpl b/Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl index e508d8cded5..e250cc9f41e 100644 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.tpl +++ b/Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl @@ -1,17 +1,33 @@ \typeout{makedoc.tpl 2010/03/23 makedoc correction template} + \RequirePackage{makedoc} + \renewcommand*{\mdJobName}{SAMPLE} + \input{mdoccorr.cfg} + \LaTeXresultFile{\mdJobName.doc} + \HeaderLines{0} + \ProcessLineMessage{} + \MainDocParser{% + % \typeout{\ProcessInputWith{dots}}% + % \WriteResult{\ProcessInputWith{dots}}% + \typeout{\expandafter \MakeDocCorrectHook + \expandafter{\fdInputLine}}% + \WriteResult{\expandafter \MakeDocCorrectHook + \expandafter{\fdInputLine}}% + } + \MakeCloseDoc{\mdJobName.TEX} + \stop
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/nicetext/sample.txt b/Master/texmf-dist/doc/latex/nicetext/run/sample.txt index 69408f90fd8..782297c0c05 100644 --- a/Master/texmf-dist/doc/latex/nicetext/sample.txt +++ b/Master/texmf-dist/doc/latex/nicetext/run/sample.txt @@ -1,3 +1,5 @@ blabla ... blabla + blabla cf. bla + etc. bla bla
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/nicetext/run/substr.tex b/Master/texmf-dist/doc/latex/nicetext/run/substr.tex new file mode 100644 index 00000000000..371045696a6 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/run/substr.tex @@ -0,0 +1,184 @@ +\typeout{substr.tex 2010/03/30 documentation for substr.sty} + +\title{\textsf{substr.sty}\thanks{See + + \url{http://ctan.org/pkg/substr} for more about + + \textsf{substr.sty}.}---Substring + + Functions with \LaTeX} + +\author{Harald Harders\thanks{Joint work with Heiko Oberdiek, + + one line + documentation tool + + by Uwe L\"uck.}} + +% \listfiles + + + +%% Preprocessing 'substr.sty': + +\RequirePackage{makedoc} + + + +%% Replacements: + +\SetPatternCodes{\MakeOther\\} + +\MakeExpandableAllReplacer{Cmds} + + {Commands:}{\SECT{Commands:}}{LEAVE} + +\PrependExpandableAllReplacer{Change}{ChangeLog}{\SECT{ChangeLog}} + +\PrependExpandableAllReplacer{CR}{Copyright}{\COPYRIGHT} + +\PrependExpandableAllReplacer{LaTeX} + + [\MakeOther\ ]{LaTeX }{\LaTeX{} } + +\PrependExpandableAllReplacer{HH@} + + {h.harders@tu-bs.de} + + {`h.harders@tu-bs.de'\MEDSK} + +\PrependExpandableAllReplacer{COMP} + + {de.comp.text.tex} + + {`de.comp.text.tex'} + +\PrependExpandableAllReplacer{LPPL} + + {macros/latex/base/lppl.txt} + + {`macros/latex/base/lppl.txt'} + +\PrependExpandableAllReplacer{Hist}[\MakeOther\ ]% + +{History of this package:}{\SECT{History of this package:}} + +\ResetPatternCodes + +\SetCorrectHookJobLast + + + +\HeaderLines{3} + +\MainDocParser{\ProcessInputWith{comment}} + +\LaTeXresultFile{substr.doc} + +\MakeCloseDoc{substr.sty} + + + +\documentclass{article} + + + +\usepackage{hyperref,makedoc,niceverb} %% niceverb after hyperref! + +\AddToNoVerbList{\MEDSK\SECT\textbf\COPYRIGHT,\LaTeX} + +\newcommand*{\MEDSK}{\par\medskip} + +\newcommand*{\SECT}[1]{\MEDSK\textbf{#1}\nopagebreak\par} + +\newcommand*{\COPYRIGHT}{\MEDSK\textbf{Copyright} } + +\usepackage[utf8]{inputenc} %% for v1.2 + + + +\pagestyle{myheadings} + +\markboth{\textsf{substr.sty}}{\textsf{substr.sty}} + +\usepackage{parskip} + + + +\begin{document} + +\maketitle + + + +\begin{abstract}\noindent + + This documentation of 'substr.sty' has been typeset + + by automatical ASCII\slash UTF\hbox{-}8~$\to$ \LaTeX\ + + enhancement provided by 'makedoc.sty' and 'niceverb.sty''s + + ``auto mode."\footnote{See + + \url{http://ctan.org/pkg/nicetext} + + for more on these packages.} + + Some extended formatting---kind of sectioning, + + switches to `\tt'---have been achieved by string replacements + + specific to the comment text of the package file + + (see source file 'substr.tex'). + + + + 'substr.sty' especially demonstrates the rather rare + + \lq`%% '\rq\ style of package comments that is somewhat + + favoured by 'makedoc' because this way ``true comments" + + are easily distinguishable from mere ``commenting out." + +% + +% The idea to use 'parskip.sty' for formatting the documentation + +% (as opposed to the version of the present file of one week ago) + +% is due to the quite recent + +% 'import.tex'\footnote{\url{http://ctan.org/pkg/import}} + +% that + +%% ??? + +\end{abstract} + +\sloppy + +% \MakeJobDoc{3}{\ProcessInputWith{comment}} + +\AutoCmdInput{substr.doc} + +\end{document} + + + +%% HISTORY + +2010/03/18 sent to CTAN + +2010/03/27 removed `\usepackage{substr}' + +2010/03/28 extended formatting by replacing words + +2010/03/29 \SetPatternCodes etc. + +2010/03/30 import -> substr; see source file + + + diff --git a/Master/texmf-dist/doc/latex/nicetext/substr.tex b/Master/texmf-dist/doc/latex/nicetext/substr.tex deleted file mode 100644 index b927bf2abbd..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/substr.tex +++ /dev/null @@ -1,29 +0,0 @@ -\typeout{substr.tex 2010/03/18 documentation for substr.sty} -\title{\textsf{substr.sty}\thanks{See - \url{http://ctan.org/pkg/substr} for more about - \textsf{substr.sty}.}---Substring - Functions with \LaTeX} -\author{Harald Harders\thanks{Joint work with Heiko Oberdiek, - one line + documentation tool - by Uwe L\"uck.}} -% \listfiles -\documentclass{article} -\usepackage{hyperref,makedoc,niceverb} %% niceverb after hyperref! -\usepackage{substr} -\renewcommand*{\mdJobName}{substr} %% TODO for Atari 2010/03/18 -\usepackage[utf8]{inputenc} %% for v1.2 -\begin{document} -\maketitle - -\begin{abstract}\noindent - This documentation of 'substr.sty' has been typeset - by automatical ASCII\slash UTF\hbox{-}8~$\to$ \LaTeX\ - enhancement provided by 'makedoc.sty' and 'niceverb.sty''s - ``auto mode."\footnote{See - \url{http://ctan.org/pkg/nicetext} - for more on these packages.} -\end{abstract} -\sloppy -\MakeJobDoc{3}{\ProcessInputWith{comment}} -\AutoCmdInput{\mdJobName.doc} -\end{document} diff --git a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty index 5ae6dab9f0c..456ddd1a67f 100644 --- a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty +++ b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty @@ -1,760 +1,1612 @@ %% 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.31} \def\filedate{2010/03/23} + +\def\fileversion{0.4} \def\filedate{2010/03/29} + + %% 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. + +%% We offer |\SetPatternCodes{<commands>}| + +%% (redefining `\PatternCodes') + +%% and |\ResetPatternCodes| + +%% (for returning to `\fdPatternCodes') + +%% so setup scripts such as 'mdoccorr.cfg' have shorter lines. + \@ifundefined{MakeOther}{\let\MakeOther\@makeother}{} + \newcommand*{\fdPatternCodes}{\MakeOther\&\MakeOther\$} -\newcommand*{\PatternCodes}{} \let\PatternCodes\fdPatternCodes - %% TODO adding/removing + +\newcommand*{\SetPatternCodes}{\def\PatternCodes} + +\newcommand*{\ResetPatternCodes}{\let\PatternCodes\fdPatternCodes} + +\newcommand*{\PatternCodes}{} \ResetPatternCodes + + %% TODO adding/removing; `*' may be wrong 2010/03/29 + +%% + %% 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 + +%% setup macros. (With `\MakeOther\ ' you must not indent within a + +%% setup command, and if you add `\MakeOther\%' the setup command + +%% must stay in one line.) + +%% 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{<output>}| opens (and empties) a file + %% <output> to be written into. + \newcommand*{\ResultFile}[1]{% + \def\result_file_name{#1}% + \immediate\openout\result_file=#1} + %% |\WriteResult{<balanced>}| writes a <balanced> line into + %% <output> (or more lines with `^^J'). + \newcommand*{\WriteResult}[1]{% + \immediate\write\result_file{#1}} + %% |\WriteProvides| writes a `\ProvidesFile' command to the + %% opened <output> file. This should be used when <output> + %% 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{<input>}{<loop-body>}| opens a file <input> + %% and runs a loop on its lines the main body of which is <loop-body>. + %% 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% + % \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!? + %% 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% + \repeat + \endgroup + % \fi + \closein\@inputcheck} + %% |\CloseResultFile| closes <output>. + \newcommand*{\CloseResultFile}{\immediate\closeout\result_file} + %% + %% 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 + +%% %% \pagebreak %% removed 2010/03/24 + +%% 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<pattern>#2&' stops \TeX\ with an error if it does + %% not find <pattern> and then `&'. Otherwise we have a situation + %% `\find<split1><pattern><split2>&', and `\find' reads <split1> as + %% #1 and <split2> as #2. An important point to note is that <split1> + %% will not contain <pattern>, but possibly <pattern> has more + %% occurrences in <split2>. In this sense, `\find' uses the + %% \emph{first} occurrence of <pattern> it finds in order to delimit #1. + %% Finding the \emph{last} occurrence of <pattern> therefore needs a + %% special idea. + %% + %% In order to use `\find' for a test whether <pattern> is in + %% <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 + %% <pattern> either in <target> or somewhere else before `&'. + %% + %% Consider the simple sandbox |\find<target><pattern>&|. + %% We can test #1 and #2 on being empty by `\ifx$#1$' and `\ifx$#2$'. + %% If #2 is empty, <pattern> is \emph{not} in <target>. + %% If #1 is empty at the same time, <target> is empty. + %% If #1 is empty and #2 is not, <pattern> \emph{starts} <target>! + %% 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, <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{\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\^ete} ...}\\ + %% %% <- `e' was missing 2010/03/17 + %% `\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{<pattern>}{<target>}{<yes>}{<no>}.} + %% 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} + %% + %% In general, the previous approach \emph{fails if and exactly if} + %% <pattern> 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 <pattern> + %% is the \emph{same} token. + %% `AMSTERDAM' has a period 8, `day after day' 10, `bonbon' 3, `bonobo' 4. + %% There is a counterexample <target> of length $p$ iff + %% <pattern> has period $p$, namely the first substring of <pattern> + %% having length $p$. If the length of <pattern> exceeds a multiple + %% $mp$ of its period, the first $mp$ tokens of <pattern> form + %% a counterexample <target>. + %% + %% Therefore, a sandbox must have something between <target> and + %% <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. + %% The `$' can be replaced by another tilde `~' in order to + %% test whether <target> \emph{ends} on a <pattern>, defining a macro + %% like `\findatend' whose parameter text starts with `#1<pattern>~#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 + %% %% TODO repetition of single right quote not working 2010/03/19 + %% lines that might be package comments. + %% + %% === 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 identifier <id> + %% and pattern <pattern>. <changes> optionally add commands to + %% be executed after `\PatternCodes' in a local group. + %% + \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 + %% `\fdParserId' and <pattern> have been read. + \def\mk_substr_cond #1{%% #1 pattern string + \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&'\] + %% where `\csname' etc. render \lq`:<id>'\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 `{<definition text>}' + %% just as with primitive \TeX. + %% + %% === 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 + %% 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 <output> 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{<macro-name>}', such that + %% `\WriteResult{\manysubstitutions{\fdInputLine}}' + %% writes to <output> 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. +%% %% <- TODO!? 2010/03/25 + + + %% `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>}|\] + %% % <- TODO allow `%' and ` ' for breaking code lines. + %% ---same <id>, <changes>, <pattern> as for + %% `\MakeSubstringConditional' (this is bad, there may be + %% |\MakeSubstringConditional*{<more-args>}|)---creates the + %% % <- TODO: store args in \Make...Conditional + %% corresponding sandbox, by default without tilde wrap. + %% <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} + {\StartFDsetup\mk_setup_substr_cond} -%% `\begingroup' |\mk_setup_substr_cond{<pattern>}{<more-args>}| + +%% |\mk_setup_substr_cond{<pattern>}{<more-args>}| + +%% %% without \begingroup 2010/03/29 + %% can be directly called by other programmer setup commands after + %% `\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 \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}% + \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 <split2>) + %% 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<macro>{<arg>}| 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 <split1>. + % %% An alternative policy is to pass + % %% <target> (as an argument) to the parsing macro. + \newcommand{\RemoveTilde}{} \def\RemoveTilde#1~{#1} + %% |\RemoveTildeArg<macro>{<arg>}| executes `\RemoveTilde' + %% in the next argument: + \newcommand*{\RemoveTildeArg}[2]{% + \expandafter #1\expandafter {\RemoveTilde #2}} + %% + %% === Calling conditionals === + %% |\ProcessStringWith{<target-string>}{<id>}| builds the sandbox + %% to search <target-string> for the <pattern> associated with the + %% parser-conditional that is identified by <id>, the sandbox then + %% calls the parser. + +%% % Finally, the command \emph{``returns"} the + +%% % result of applying job <id> to <target-string>---in the sense of + +%% % \emph{expanding} to it. %% more precisely 2010/03/25 + +%% %% <- removed again, wrong 2010/03/26 + \newcommand*{\ProcessStringWith}[2]{% + \csname \setup_substr_cond #2\endcsname{#1}} + %% |\ProcessExpandedWith{<string-macro>}{<id>}| does the same but with + %% a \emph{macro} (like `\fdInputLine' or `\OutputString') in which + %% the string to be tested is stored. + +%% %% TODO or \the<tok-reg> 2010/03/25 + \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{<id>}| 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 <id> 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 + %% <input> file. %%% On a certain condition, + %% |\CopyFDconditionFromTo{<id1>}{<id2>}| + %% \emph{creates or redefines a sandbox builder} with identifier <id2> + %% that afterwards behaves like the sandbox builder <id1>. + %% So you can store a certain behaviour as <id1> in advance in order + %% once to change the behaviour of <id2> into that of <id1>. + \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) %% !? 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). + %% + %% |\IfFDempty{<arg>}{<when-empty>}{<when-not-empty>}| + %% is used to test <arg> on emptyness (without expanding it): + \newcommand*{\IfFDempty}[1]{% + \ifx$#1$\expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} + %% |\IfFDinputEmpty{<when-empty>}{<when-not-empty>}| is a variant of + %% the previous to execute <when-empty> if the loop processing <input> + %% finds an empty line---otherwise <when-not-empty>. + \newcommand*{\IfFDinputEmpty}{% + \ifx\fdInputLine\@empty \expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} + %% |\IfFDdollar{<arg>}{<when-empty>}{<when-not-empty>}| + %% is another variant, testing <split2> for being `$', + %% main indicator of there is a match anywhere in <target> + %% (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 + %% <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 + %% 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 <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 + %% 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{<relation><number>}{<true>}{<false>}|, when called + %% from the processing loop (second argument of `\ProcessFileWith') + %% issues <true> commands if `\value{fdInputLine}<relation><number>' -%% is true, otherwise <false>. <relation> may usually be just `='. + +%% is true, otherwise <false>. <relation> is one out of + +%% \HardNVerb+<+, `=', `>'. %% 2010/03/24 2010/03/29 + \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{<string>}{LEAVE}' expands to <string> + %% ... \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{<string>}}'\] renders `\OutputString' + %% the result of applying a chain (sequence) of stringwise replacements + %% to <string>. + %% You can even write a transformed input <string> 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 <parser> + %% and receives from the latter <split1>~=~#1 and <split2>~=~#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 <pattern> from + %% <parser> 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} <sandbox> + %% (that will be shown below) that called <parser> + %% initialized #5 to be that <parser> itself. (<parser> otherwise + %% wouldn't know who it is.) So <parser> calls itself with another sandbox + %% `#2&'. Note that #2 contains \lq`~<pattern>$'\rq\ due to the initial + %% <sandbox> building. + {#5#2&{#3#1#4}{#4}#5#6}} + %% #4 is the replacement string that <sandbox> passed to <parse>. + %% The first argument after the `&' is previous stuff plus + %% the recently skipped <split1> + %% plus #4 replacing the string <pattern> that was matched. + %% + %% 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>}[<chng>]{<find>}{<replace>}{<id-next>}|\] + %% creates sandbox and parser with common identifier <id> and search + %% 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}). + %% 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 + %% 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\fdParserId}% + \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 + %% + %% \[|\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}}% + +%% + +%% %% 2010/03/29: + +%% |\MakeDocCorrectHook{<string>}| belongs to 'makedoc', + +%% but in the meantime ('nicetext' release 0.3) + +%% I have proposed to use it with 'fifinddo' only as well + +%% (running files `fdtxttex.tpl', `fdtxttex.tex'). + +%% Therefore I offer some simplification |\SetCorrectHookJob{<job-id>}| + +%% for defining `\MakeDocCorrectHook' \emph{here.} + +\newcommand*{\SetCorrectHookJob}[1]{% + + \def\MakeDocCorrectHook##1{\ProcessStringWith{##1}{#1}}} + +%% |\SetCorrectHookJobLast| just uses the job that was set up + +%% most recently. + +\newcommand*{\SetCorrectHookJobLast} + + {\SetCorrectHookJob\fdParserId} + %% + %% == 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 + (<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 + 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@ + 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' +SENT TO CTAN + + + +v0.4 2010/03/24 removed \pagebreak before "substrings"; + + <relation> with \IfInputLine precisely + + 2010/03/25 todo \ProcessExp... more precisely, etc. + + 2010/03/26 ... was wrong, removed + + 2010/03/29 \SetPatternCodes, \ResetPatternCodes, + + \SetCorrectHookJob, \SetCorrectHookJobLast; + + <relation> with \HardNVerb; + + don't mention \begingroup with + + \mk_setup_substr_cond; renamed v0.4 + + + 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 948c1b59b5e..292a44242d0 100644 --- a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty +++ b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty @@ -1,543 +1,1148 @@ %% Macro package `makedoc.sty' for LaTeX2e, + %% copyright (C) 2009 2010 Uwe L\"uck, + %% http://www.contact-ednotes.sty.de.vu + %% -- author-maintained in the sense of LPPL below -- + %% for preparing documentations from packages. -\def\fileversion{0.3} \def\filedate{2010/03/19} + + +\def\fileversion{0.4} \def\filedate{2010/03/30} + + %% This file can be redistributed and/or modified under + %% the terms of the LaTeX Project Public License; either + %% version 1.3a of the License, or any later version. + %% The latest version of this license is in + %% http://www.latex-project.org/lppl.txt + %% We did our best to help you, but there is NO WARRANTY. + %% + %% Please report bugs, problems, and suggestions via + %% + %% http://www.contact-ednotes.sty.de.vu + %% + \NeedsTeXFormat{LaTeX2e}[1994/12/01] + % 1994/12/01: \newcommand* etc. + \ProvidesPackage{makedoc}[\filedate\space v\fileversion\space + TeX input from *.sty (UL)] + %% + %% |\PackageCodeTrue| and |\PackageCodeFalse| set `\ifPackageCode' + %% globally, so redefinition of `~' (playing a key role in 'fifinddo') + %% may be kept local. Note the capital `T' and `F'! + \newcommand*{\PackageCodeTrue} {\global\let\ifPackageCode\iftrue} + \newcommand*{\PackageCodeFalse}{\global\let\ifPackageCode\iffalse} + %% |\ifPackageCode| is used to determine whether a listing environment + %% must be `\beg'un or `\end'ed. You may also want to suppress empty + %% code lines, while empty lines should issue a `\par' break in + %% ``comment" mode. + %% + %% Since `\newif' is not used, `\ifPackageCode' must be declared + %% explicitly. Declaration of new `\if's must be early in case + %% they occur in code that is skipped by another `\if'\dots + %% [TODO!? cf. others 2010/03/15] + \PackageCodeFalse + %% + %% 'makedoc' is an extension of 'fifinddo' on which it depends. + \RequirePackage{fifinddo}[2009/04/13] + %% Both 'fifinddo' and 'makedoc' use the ``underscore" `_' + %% as ``private letter" and restore its standard ``subscript" + %% function ({\it \TeX book Chap.\,7}) at their end. + %% Push\slash pop functionality as with `@' and `\RequirePackage' + %% is missing here. So after loading 'fifinddo', + %% we need to declare our private letter (again). + \catcode`\_=11 %% underscore used in control words + %% + %% \subsection{&\MakeDocCorrectHook\ (\dqtd{`txt2TeX'})} + %% |\MakeDocCorrectHook| is predefined to leave its argument without + %% the enclosing braces, otherwise unchanged: + \let\MakeDocCorrectHook\@firstofone + %% Less efficiently, the same could have been set up as + % \newcommand*{\MakeDocCorrectHook}[1]{\ProcessStringWith{#1}{LEAVE}} + %% according to 'fifinddo'. + %% + %% It may be \emph{redefined} in a \emph{configuration} file like + %% 'makedoc.cfg' or the 'makedoc' script file applying to a single + %% package file in order to, e.g., converting plain text to \TeX\ input + %% conforming to typographical conventions, making `$\dots$' from + %% \qtd{&.&.&.}, %% dots should not be replaced! + %% e.g. + %% Replace `LEAVE' in the previous suggestion by an identifier + %% whose job you have defined before, and use `\renewcommand' + %% in place of `\newcommand'. + %% See an example in 'makedoc.cfg'. + %% + %% You can \emph{test} your own `\MakeDocCorrectHook' by + %% \[`\typeout{\MakeDocCorrectHook{<test-string>}}'\] + %% ... provided (sometimes) `\MakeOther\ ' ... + %% You can even change it using `\IfInputLine' from 'fifinddo' in the + %% midst of preprocessing a package documentation. + %% -%% \subsection{Distinguish package code from comments}%% <- wiki style breaks in self-doc. + +%% \subsection{Distinguishing package code from comments}%% <- wiki style breaks in self-doc. + %% \label{sec:distinguish} + %% Use of comment marks is a matter of personal style. Only lines + %% starting with the sequence |%% | %% box 2010/03/16 + %% are typeset in \TeX\ quality + %% under the present release. Lines just containing |%%| + %% (without the space) are used to suppress empty code lines + %% preceding section titles (while keeping some visual space + %% in the package file). There is a preferable way to do this, + %% however not in the present release ... + %% + %% The parsing macros must be set up reading `%' and ` ' as ``other" + %% characters. Using the optional arguments for this creates + %% difficulties that can be somewhat avoided by redefining + %% |\PatternCodes|. + +\SetPatternCodes{\MakeOther\%\MakeOther\ }%% 2010/03/30 + %% -\renewcommand*{\PatternCodes}{\MakeOther\%\MakeOther\ }%% 2009/04/02 -%% + %% The next line sets the ``sandbox" for the detecting macro, as it + %% is coined in the documentation of 'fifinddo', with ``identifier" + %% |PPScomment|. + \MakeSetupSubstringCondition{PPScomment}{%% }{{#1}} + %% The last argument stores the expanded input line for reference by + %% macros called. The next line is a test whether the setup works. + % \expandafter \show \csname \setup_substr_cond PPScomment\endcsname + %% Here comes the definition of the corresponding testing macro. + %% #3 is the expanded input line from above. The `\If'\dots commands, + %% `\fdInputLine', `\fdInputLine', and `\RemoveDummyPatternArg' + %% are from 'fifinddo'. -\MakeSubstringConditional{PPScomment}{%% }#3{%% #3 entire test string + +\MakeSubstringConditional{PPScomment}{%% }#3{%% #3 entire test string + + \DecideCommentCode{#1}{#2}{#3}\PPstring} + +%% |\DecideCommentCode{#1}{#2}{#3}{#4}| is shared with the parser + +%% for the \lq`% '\rq\ commenting style. %% new 2010/03/28 + +\newcommand*{\DecideCommentCode}[4]{% + \IfFDinputEmpty{\OnEmptyInputLine}{% + %% The empty line test comes early to offer control with -%% `\OnEmptyInputLine' both code and comment mode. + +%% `\OnEmptyInputLine' both in code and comment mode. + %% Maybe it should always? %% TODO 2009/04/13 - \IfFDempty{#1}%% + + \IfFDempty{#1}% + {\TreatAsComment{% + \RemoveDummyPatternArg\MakeDocCorrectHook{#2}}}% - {\ifx\fdInputLine\PPstring - \ifPackageCode\else \WriteResult{}\fi%% 2009/04/05 - %% <- allow paragraphs in comments + + {\ifx\fdInputLine#4% + + \ifPackageCode\else \WriteResult{}\fi% + +%% ... allows paragraphs in comments. + \else \TreatAsCode{#3}\fi}}} -% \expandafter \show \csname \substr_cond PPScomment\endcsname -%% |\PPstring| stores the line suppressing empty code lines. + +%% Job |PScomment| deals with the |% | commenting style: + +\MakeSetupSubstringCondition{PScomment}{% }{{#1}} + +\MakeSubstringConditional{PScomment}{% }#3{% + + \DecideCommentCode{#1}{#2}{#3}\PercentChar} + +%% `\PercentChar' is from 'fifinddo'.---Return to `\fdPatternCodes': + +\ResetPatternCodes %% 2010/03/30 + +%% + +%% |\PPstring| stores the line suppressing empty code lines with + +%% the \lq`%% '\rq\ style: + \newcommand*{\PPstring}{} \xdef\PPstring{\PercentChar\PercentChar} + +%% + %% |comment| will be a ``generic" identifier to call a comment line + %% detector. It might be predefined to issue an ``undefined" error; -%% however this release predefines it to behave like `PPScomment'. + +%% however this release predefines it to behave like `PPScomment': + \CopyFDconditionFromTo{PPScomment}{comment} + +%% This means that the \lq`%% '\rq\ commenting style is assumed by + +%% default. \[`\CopyFDconditionFromTo{PScomment}{comment}'\] + +%% switches to the \lq`% '\rq\ style (with the {\it Wikipedia} + +%% sectioning parser). + +%% Or just choose \[`\ProcessInputWith{PScomment}'\] as <main-parser> + +%% (without the {\it Wikipedia} feature). + +%% + %% Alternative still to be considered: + % \@namedef{\setup_substr_cond comment}{% + % \PackageError{makedoc}{Job `comment' not defined}% + % {Use \string\CopyFDconditionFromTo{comment}}} + %% + %% \subsection{Choice of package code environment} + %% With v0.3, we adopt the solution for typesetting package code + %% that was implemented in the former 'makedoc.cfg'. So we rely + %% on the `listing' and `listingcont' environments of the + %% 'moreverb' package. + %% + %% The earlier idea was that 'makedoc.sty' uses an undefined \LaTeX\ + %% environment `packagecode' that will be defined in 'makedoc.cfg'. + %% An accompanying idea was that 'makedoc' works before the + %% `\documentclass' line inside a group, while 'makedoc.cfg' + %% is read \emph{after} the `\documentclass' line. + %% + %% We now want to simplify things. We replace + %% \[`packagecode' \mbox{\quad by\quad } `mdPackageCode'\] + %% and define the new environment globally here. 'moreverb' + %% and our choice for `\listinglabel' are + %% called at `\begin{document}'---outside the possible group. + \gdef\mdPackageCode{% + \small + %% Get rid of 'niceverb' stuff: + % \MakeOther\`\MakeOther\'%% probably OK with moreverb + \MakeOther\<\MakeOther\|% + %% From the next occurrence of the environment onwards, + %% `listing' must be replaced by `listingcont'. We must + %% copy the previous code diligently. + \gdef\mdPackageCode{\small \MakeOther\<\MakeOther\|% + \listingcont}% + \listing{1}} + \gdef\endmdPackageCode{% + \endlisting + \global\let\endmdPackageCode\endlistingcont} + \AtBeginDocument{% + \RequirePackage{moreverb}% + \renewcommand*{\listinglabel}[1]{% + \llap{\scriptsize\rmfamily\the#1}\hskip\listingoffset\relax}% + } + +%% |\ResetCodeLineNumbers| may be needed to \emph{reset} + +%% 'moreverb''s (global!) code line number settings + +%% (\emph{first} line number + {\it modulo} for displaying) + +%% when combining documentations of \emph{more} than one package + +%% with the present solution for implementing `mdPackageCode': + +\newcommand*{\ResetCodeLineNumbers}{% + + \global\listing@line\@ne \gdef\listing@step{\@ne}} + %% + %% \subsection{Dealing with comments} + %% |\TreatAsComment{<text>}| writes <text> to the documentation + %% file. If we had ``package code" (were in ``code mode") so far, + %% the listing environment is ended first. + \newcommand*{\TreatAsComment}[1]{% + \ifPackageCode + \WriteResult{\string\end{mdPackageCode\@empty}}% + %% The `\@empty' here is a lazy trick to save self-documentation + %% fighting 'verbatim''s ``highlight" of finding ends of listings + %% (to be improved). %% TODO 2010/03/09 + %% + %% We always use `\string' to prevent macro expansion in `\write'ing + %% in place of \LaTeX's `\protect', + %% as long as 'fifinddo' simply uses the primitive `\write' in place + %% of \LaTeX's `\proteced@write' ... %% todo 2009/04/08 + \PackageCodeFalse + \EveryComment + % \_empty_code_lines_false + \fi + \WriteResult{#1}} + %% Here, |\EveryComment| is a macro hook for inserting material that should + %% not appear in a listing environment, I had tried this %% 2010/03/18 + %% successfully: + %% \begin{verbatim} + %% \gdef\EveryComment{% + %% \global\let\EveryComment\relax + %% \WriteResult{\string\AutoCmdVerbSyntax}} + %% \end{verbatim} + %% Initialized: + \global\let\EveryComment\relax %% should be changed globally. + %% + %% \subsection{Sectioning} + %% \label{sec:secparsers} + %% We provide a facility from 'wiki.sty' that imitates the sectioning + %% syntax used in editing \emph{Wikipedia} pages, in a different + %% implementation (better compatibility) and in a more general way. + %% On Wikipedia, `== Definition ==' works similar as + %% `\section{Definition}' does with \LaTeX. With the present + %% implementation, you can type, e.g., + %% \[`%%%%%%%%%%%%%%%%%%%%%% == Definition == %%%%%%%%%%%%%%%%%%%%%%'\] + %% to get a similar result. The number of `%' characters doesn't + %% matter, and there can be other stuff, however: additional `=' + %% symbols may harm. Three sectioning levels are supported, through + %% `==<text>==', `===<text>===', and `====<text>====' (deepest). + %% + %% There are three detector macros made for programmers. + %% The most general one is + %% In the following definitions, there is a single tilde to prevent + %% `=' symbols being gobbled by the test (realized by accident). + %% %% 2009/04/13 + %% \par\noindent %% 2010/03/11 + %% |\SectionLevelThreeParseInput|: + \newcommand*{\SectionLevelThreeParseInput}{% + \expandafter \test_sec_level_iii \fdInputLine ~========&} + %% |\SectionLevelTwoParseInput| + \newcommand*{\SectionLevelTwoParseInput}{% + \expandafter \test_sec_level_ii \fdInputLine ~======&} + %% and |\SectionLevelOneParseInput| + \newcommand*{\SectionLevelOneParseInput}{% + \expandafter \test_sec_level_i \fdInputLine ~====&} + %% allow skipping deeper levels for efficiency. + %% % TODO in fifinddo: setup for 2 strings in 1 line 2009/04/13 + %% + %% In the terminology of the 'fifinddo' documentation, the previous + %% three commands are ``sandbox builders." The following three + %% commands are the corresponding ``substring conditionals." + %% However, 'fifinddo' so far %% todo 2009/04/08 + %% only deals with \emph{single} substrings, while here we are + %% dealing with \emph{pairs} of substrings. We are not using + %% general setup macros, but define the parsing macros ``manually," + %% as it is typical in many other macros in 'latex.ltx' and other + %% \LaTeX\ packages. You can fool our macros easily, there is + %% no syntax check. %% todo 2009/04/08 + \def\test_sec_level_iii#1====#2====#3&{% + \IfFDempty{#2}% + {\test_sec_level_ii #1======&}% + {\WriteSection\mdSectionLevelThree{#2}}} + \def\test_sec_level_ii#1===#2===#3&{% + \IfFDempty{#2}% + {\test_sec_level_i #1====&}% + {\WriteSection\mdSectionLevelTwo{#2}}} + \def\test_sec_level_i#1==#2==#3&{% + \IfFDempty{#2}% + {\RemoveTildeArg \ProcessStringWith{#1}{comment}}% + {\WriteSection\mdSectionLevelOne{#2}}} + %% `\ProcessStringWith' here passes the expanded `\fdInputLine' + %% to the general comment detector. + %% + %% |\WriteSection{<command>}{<text>}| replaces an input line + %% with a line \[`<command>{<text>}'\] + %% in the documentation file and switches into ``comment mode." + %% One possible space between `=' and the beginning of <text> + %% and one possible space between the end of <text> and `=' + %% are removed. + %% The method of dealing with surrounding blank + %% spaces is new with v0.3, moreover we now rely on a new method in + %% 'niceverb.sty' v0.3 to support its single right quote feature in + %% section titles.\footnote{&\ignorespaces\ and &\unskip\ used + %% previously do not work in PDF bookmarks.} + \newcommand*{\WriteSection}[2]{% + \TreatAsComment{^^J#1{\trim_correct{#2}}^^J}} + %% Trimming ``other" spaces is a little more clumsy than + %% what the 'trimspaces' package does whose code is by + %% Morten H\o gholm. It still has inspired the following. + \begingroup \MakeOther\ %% CARE! we must not indent ... + \long\gdef\trim_correct#1{\trim_fosp$#1$ $} + \long\gdef\trim_fosp#1$ {% + \IfFDempty{#1}{\trim_losp$}{\trim_losp#1$ }} + %% So we have a string \lq`\trim_losp$<text>$ $'\rq. + \long\gdef\trim_losp$#1 ${\tidy_sp_trim#1$} + %% So we have a string \lq`\tidy_sp_trim<text>$ $'\rq + %% or \lq`\tidy_sp_trim<text>$$'\rq. + \long\gdef\tidy_sp_trim#1$#2${\MakeDocCorrectHook{#1}} + \endgroup + %% We insert `\section' using |\mdSectionLevelOne| etc.\ + %% which the programmer can redefine, e.g., when the + %% documentation is part of a `\section' (or even deeper) + %% according to the ``documentation driver" file. + \newcommand*\mdSectionLevelOne {\string\section} + \newcommand*\mdSectionLevelTwo {\string\subsection} + \newcommand*\mdSectionLevelThree{\string\subsubsection} + %% + %% This sectioning feature is not used in (the documentation) of + %% 'makedoc.sty'---\emph{definitions} of the parsing macros fool + %% the same macros ... + %% + %% \subsection{Commented code} + %% |\TreatAsCode{<text>}| is the opposite to `\TreatAsComment{<text>}': + \newcommand*{\TreatAsCode}[1]{% + \ifPackageCode + % \_empty_code_lines_true + \else + \WriteResult{\string\begin{mdPackageCode}}% + \PackageCodeTrue + \fi + \WriteResult{#1}% + % \WriteResult{\maybe_result_empty_line #1}% + % \let\maybe_result_empty_line\empty + } + %% + %% \subsection{Dealing with empty input lines} %% TODO use!? 2010/03/09 + %% \label{sec:emptylines} + %% |\OnEmptyInputLine| is a default setting (or hook) for what to do + %% with empty lines in the input file. The default is to insert an + %% empty line in the output file: + \newcommand*{\OnEmptyInputLine}{\WriteResult{}} + %% |\NoEmptyCodeLines| changes the setting to suppressing empty code + %% lines, while in ``comment mode" an empty input line \emph{does} + %% insert an empty line, for starting a new paragraph: + \newcommand*{\NoEmptyCodeLines}{%% suppress empty code lines + \renewcommand*{\OnEmptyInputLine}{% + \ifPackageCode \else \WriteResult{}\fi}} + %% There is a better policy---didn't work so far ... + %% + %% \subsection{Bundling typical things: script commands} + %% \label{sec:script} + %% Practical experience suggested the following shorthands, + %% combining commands from 'makedoc' and 'fifinddo'. + %% + %% \subsubsection{Output file and &\filelist\ entry} + %% |\LaTeXresultFile{<output>}| chooses <output> as name + %% for the output file and saves you the extra line for inserting + %% the `\ProvidesFile' line as with 'fifinddo''s + %% `\WriteProvides'---however, it differs, actually it is 'makedoc' + %% that wants to be mentioned with `\ProvidesFile' ... + %% %% (otherwise copied from 'fifinddo') ... + \newcommand*{\LaTeXresultFile}[1]{% + \ResultFile{#1}%%% \WriteProvides} + \WriteResult{% + \string\ProvidesFile{\result_file_name}% + [\the\year/\two@digits\month/\two@digits\day\space + automatically generated with makedoc.sty]}}% + %% \subsubsection{Choose input file and run!} + %% |\MakeDoc{<input>}| preprocesses <input> to render input for + %% \LaTeX, considering what is typical for a \LaTeX\ package as the + %% <input> one here: + \newcommand*{\MakeDoc}[1]{% + %% In case of a ``header" (see below) we change into ``code mode": + \ifnum\header_lines>\z@ + \WriteResult{\string\begin{mdPackageCode}}% + \PackageCodeTrue %% TODO both lines makedoc command!? + %% 2009/04/08 + \else \PackageCodeFalse \fi + %% The loop follows. There is a placeholder `\makd_doc_line_body' + %% that is predefined below and can be changed while processing the + %% <input> file. + \ProcessFileWith{#1}{% + \CountInputLines %% stepping line counter is standard + \make_doc_line_body + \process_line_message}% + %% Currently the ``VERSION HISTORY" or, more generally, + %% a final part of the <input> file is typeset verbatim + %% (for ``tabbing" in the version history), + %% so we must leave ``code mode" finally: + \ifPackageCode + \WriteResult{\string\end{mdPackageCode\@empty}}%% self-doc-trick + \PackageCodeFalse %% TODO both lines makedoc command!? 2009/04/08 + \fi + %% When the <input> file has been processed, certain default settings + %% might be restored---in case another <input> file is processed for the + %% same documentation document: + % \HeaderLines{0}% + % \MainDocParser{\SectionLevelThreeParseInput}%% TODO!? 2009/04/08 + } + %% |\MakeCloseDoc{<input>}| %% 2010/03/11 + %% just is a shorthand for + %% \[`\MakeClose{<input>}\CloseResultFile'\] + %% where `\CloseResultFile' is from 'fifinddo'. + \newcommand*{\MakeCloseDoc}[1]{\MakeDoc{#1}\CloseResultFile} + %% `\MakeDoc' and `\MakeCloseDoc' actually \emph{process} + %% the <input> file, + %% depending on certain \emph{parameters} some of which are set + %% by the commands described next. + %% + %% \subsubsection{Preamble vs.\ main part of input file} + %% A \LaTeX\ package typically has a ``header" or ``preamble" + %% (automatically inserted by 'docstrip') with very scarce information + %% on which file it is and what it provides, and with much more Legalese. + %% Typesetting it in \TeX\ quality may be more misleading than + %% typesetting it \emph{verbatim}. So we typeset it \emph{verbatim}. + %% Now: where does the ``header" end? + %% `\NeedsTeXFormat' might be considered the border.---Yet it seems + %% to be more simple and reliable just to act in terms of the + %% \emph{number of lines} + %% that the header should be long. This length <how-many-lines> is declared by + %% |\HeaderLines{<how-many-lines>}|: + \newcommand*{\HeaderLines}{\def\header_lines} + \HeaderLines{0} + %% So the default is that there aren't any header lines, unless + %% another `\HeaderLines' is issued before some `\MakeDoc'. + %% The way input is parsed \emph{after} the ``header" is set by + %% |\MainDocParser{<parsing-command>}|. + \newcommand*{\MainDocParser}{\def\main_doc_parser} + %% `\SectionLevelThreeParseInput' from section~\ref{sec:secparsers} + %% is the default, two alternatives are defined there, another one is + %% `\ProcessInputWith{comment}' from 'fifinddo' and + %% %% clarified 2010/03/09 `\ref' 2010/03/10 + %% section~\ref{sec:distinguish} + %% (general dividing into code and comments). + \MainDocParser{\SectionLevelThreeParseInput} + %% Here is how `\HeaderLines' and `\MainDocParser' act: + \def\make_doc_line_body{% + \IfInputLine{>\header_lines}% + {\let\make_doc_line_body\main_doc_parser + \make_doc_line_body}% %% switch to deciding + {\TreatAsCode{\fdInputLine}}} %% header verbatim + %% \subsubsection{Screen messages} + %% |\ProcessLineMessage{<command>}| is designed to choose a screen + %% (or log) message <command>. + %% % A simple setting may be \[`\ProcessLineMessage{\message{.}}'\] with + %% `\ProcessLineMessage{\message{.}}' has a result like with 'docstrip'. + %% You just get one dot on screen per input line + %% as a simple confirmation that + %% the program is not hung up. %% TODO phrase!? 2009/04/08 + %% However, the message may slow down a run considerably + %% (if so, choose `\ProcessLineMessage{}' in the script). + %% % , you really have to + %% % wait about a second while you hardly notice the 'makedoc' run + %% % without screen messages. Therefore, the default is \emph{not} + %% % to issue any screen message.%% TODO more complex procedures!? 2009/04/08 + %% %---No! + %% But it is better for beginner users of the package, + %% so made default. %% 2009/04/09 + \newcommand*{\ProcessLineMessage}{\def\process_line_message} + % % \ProcessLineMessage{} %% no, still more efficient: + % \let\process_line_message\relax + \ProcessLineMessage{\message{.}} + %% + %% \subsubsection{Bundling-bundling Standalones} + %% |\MakeInputJobDoc{<header-lines>}{<main-parser>}| + %% by default produces a file + %% \[`\jobname.doc' \mbox{\quad from\quad } `\jobname.sty'\] + %% with some standard settings.\footnote{This command is new with v0.3.} + %% 'mdoccorr.cfg' (for `.txt'$\to$\LaTeX\ functionality) is read, + %% `\HeaderLines{<header-lines>}' + %% and `\MainDocParser{<main-parser>}' and finally + %% `\MakeCloseDoc{\jobname.sty}{\jobname.doc}' + %% % (with the arguments named before) + %% are executed. + %% Here `\jobname' expands to the file name base of the + %% `.tex' file you are running. It is assumed that you are preparing + %% documentation for `\jobname.tex' for your `\jobname.sty'. + %% In order to produce `<my-job>.doc' from `<my-job>.sty' instead, + %% \[`\renewcommand{\mdJobName}{<my-job>}'\] + %% If your input file has a different file name extension + %% <in-ext> than \qtd{`sty'}, use an optional argument + %% of `\MakeInputJobDoc': + %% \[|\MakeInputJobDoc[<in-ext>]{<header>}{<parser>}|\] + %% If the output file + %% should have a different extension <out-ext> than \qtd{`doc'}, + %% you must use \emph{two} optional arguments as follows: + %% \[|\MakeInputJobDoc[<in-ext>][<out-ext>]{<header>}{<parser>}|\] + %% `\MakeInputJobDoc' does \emph{not} execute `\ProcessLineMessage', + %% you can use the latter before so `\MakeInputJobDoc' respects it. + %% + %% |\MakeJobDoc| does the same as `\MakeInputJobDoc' apart from + %% typesetting the <created> file, so the latter needs an additional + %% `\input{<created>}'. + %% + %% My original idea was that all preprocessing of package files + %% to be documented should <happen> \emph{before} + %% `\documentclass'---loading + %% 'makedoc.sty' included---inside a group (\lq`{<happen>}'\rq---in + %% order to avoid compatibility issues). + %% However, it now appears to me that loading 'makedoc' the usual way + %% in the document \emph{preamble} + %% and processing the package file (that is to be documented) + %% within the `document' environment works well enough and + %% will be easier to comprehend. + %% + %% This is the code for both `\MakeJobDoc' and `\MakeInputJobDoc': + \@ifdefinable{\mdJobName}{\let\mdJobName\jobname} + \newif\if_makedoc_input_ + \newcommand*{\MakeInputJobDoc}{\_makedoc_input_true + \make_job_doc_read} + \newcommand*{\MakeJobDoc} {\_makedoc_input_false + \make_job_doc_read} + \newcommand*{\make_job_doc_read}[1][sty] + {\@testopt{\make_job_doc[#1]}{doc}} + %% Reading files as follows would fail with active 'niceverb' settings, + %% so we issue `\noNiceVerb' if it is defined. We do it inside a group + %% in case 'niceverb' settings are to be restored afterwards. + \def\make_job_doc[#1][#2]#3#4{% + \begingroup + \@ifundefined{noNiceVerb}{}% + {\let\MakeNormal\MakeNormalHere \noNiceVerb}% + \input{mdoccorr.cfg}% + %% <- TODO warning if not found!? + %% or if one from TEXMF/ used inadvertently!? + %% avoid reading twice!? 2010/03/11 + %% <- TODO stack danger in group!? 2010/03/13 + %% <- TODO or read it from 'makedoc' already! 2010/03/13 + \LaTeXresultFile{\mdJobName.#2}% + \HeaderLines{#3}% + \MainDocParser{#4}% + \MakeCloseDoc{\mdJobName.#1}% + %% For typesetting the file just created, some 'nicetext' features + %% may be needed ... so restore the previous ones ... + \endgroup + \if_makedoc_input_\input{\mdJobName.#2}\fi + } + %% This feature may \emph{change}. + %% + %% \subsection{Leave the package} + \catcode`\_=8 %% restores underscore use for subscripts + \endinput + %% + %% \subsection{VERSION HISTORY} + + v0.1 2009/04/03 very first version, tested on morgan.sty + v0.2 2009/04/05 \OnEmptyInputLine, \NoEmptyCodeLines + comment -> PPScomment, \IfFDinputEmpty, + \EveryComment, \PPstring may be par break + 2009/04/08 \InputString -> \fdInputLine, + \section -> \subsection; documentation! + 2009/04/08f. \MakeDoc + 2009/04/12 ``line too long'' w/o redefining \PatternCodes; + \MakeDocCorrectHook + 2009/04/13 tilde with sectioning + v0.3 2010/03/08 \WriteSection 'trimspaces'-like + 2010/03/09 "fool" ("wiki" sectioning) nicer worded, + more use of `...' in place of `\dots'; + different treatment of package code environment + (new separate subsection); clarification on + \ProcessInputWith{comment} + 2010/03/10 supplied `\ref' + 2010/03/11 \MakeCloseDoc; corrected "undifined"; + \par\noindent in ``Sectioning"; \MakeJobDoc + 2010/03/12 &.&.&.; updated copyright + 2010/03/13 corr.: `_' not ``other"; tried to explain my + earlier reasoning about `\ifPackageCode'; + \MakeInputJobDoc + 2010/03/14 \make_doc_job without \niceverb_aux_cat + 2010/03/15 another remark to \ifPackageCode + 2010/03/16 use box with comment line markers; + mdcorr -> mdoccorr + 2010/03/18 report on using \EveryComment + 2010/03/19 '' -> " + +v0.4 2010/03/23 "Distinguishing" + + 2010/03/24 "both in" + + 2010/03/27 switch back to \fdPatternCodes + + 2010/03/28 include `% ' commenting style + + 2010/03/29 \ResetCodeLineNumbers + + 2010/03/30 use \SetPatternCodes, \ResetPatternCodes + diff --git a/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg b/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg index 1d3ba475e95..665b037b0af 100644 --- a/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg +++ b/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg @@ -1,32 +1,80 @@ -\ProvidesFile{mdoccorr.cfg}[2010/03/23 +\ProvidesFile{mdoccorr.cfg}[2010/03/29 + local typographical corrections + with `makedoc.sty'] -%% ... also demonstrates 'niceverb.sty'. Some sanitizing: + +%% ... also demonstrates 'niceverb.sty'---see the typeset + +%% documentation of the present file in `makedoc.pdf'. + %% -\renewcommand*{\PatternCodes}{\MakeOther\\\MakeOther\ } + +%% |\SetPatternCodes{<commands>}| redefines + +%% `\PatternCodes' to be used in parsing and replacing + +%% (some ``sanitizing"). %% improved line breaks 2010/03/29 + +\SetPatternCodes{\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}} + +%% ... chain starts here, and here |\MakeDocCorrectHook| (silently) + +%% enters through a default variant |\SetCorrectHookJobLast| + +%% of |\SetCorrectHookJob{<id>}|: + +\SetCorrectHookJobLast + %% -\renewcommand*{\PatternCodes}{\fdPatternCodes} + +%% |\ResetPatternCodes| resets `\PatternCodes' to their default + +%% value (which is `\fdPatternCodes'): + +\ResetPatternCodes + %% ... 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' + +2010/03/29 use \SetPatternCodes etc. + diff --git a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty index 823093a1020..22e0ad3aa2a 100644 --- a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty +++ b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty @@ -1,756 +1,1546 @@ \NeedsTeXFormat{LaTeX2e}[1994/12/01] -\ProvidesPackage{niceverb}[2010/03/23 v0.32 + +\ProvidesPackage{niceverb}[2010/03/29 v0.4 + minimize doc markup (UL)] + + %% Copyright (C) 2009, 2010 Uwe Lueck, + %% http://www.contact-ednotes.sty.de.vu + %% -- author-maintained in the sense of LPPL below -- + %% + %% 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 + %% + %% === 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 + %% |\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 + \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. + \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 + }{\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}{% + %% 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\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'. + \else + \ifx\let_token\protect + \expandafter\expandafter\expandafter \lq_double_decide_ii + \else + \endgroup + \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]{% + \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}{% + \jumpteg_on_with\bgroup\braces_verb + \jumpteg_on_with[\brackets_verb + \jumpteg_on_with*\star_verb + \egroup} + %% CAUTION/TODO wrong before (... if cmd without arg + %% use \ then or choose usual verb... + %% 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. %% 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 === + %% |\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}{% + \ifx\let_token\@sptoken \else %% TODO ^^M!? + \expandafter \start_build_cs_syntax + \fi} + \newcommand*{\start_build_cs_syntax}[1]{% - \edef\string_built{\string#1}%% #1 may be active + + \edef\string_built{\string#1}% + +%% #1 may be active.---With Donald Arseneau's 'import.sty' (e.g.), + +%% \qtd{&_} may be needed to be `\active' with the meaning of + +%% `\textunderscore', therefore restoring its category code + +%% needs some more care than with v0.32 and earlier: + + \edef\before_build_cs_sub{\the\CatCode\_}% + \MakeLetter\_\MakeLetter\@%% CAUTION, cf. ... + \test_more_cs} + \newcommand*{\test_more_cs}{% + \futurelet\let_token \decide_more_cs} + \newcommand*{\decide_more_cs}{% + \ifcat\noexpand\let_token a\expandafter \add_to_cs + \else - \MakeNormalHere\_\MakeOther\@% + +% \MakeNormalHere\_ + +%% Restoring \qtd{&_} more carefully with v0.33 + +%% (`\begingroup' ... `\endgroup'!?): + +%% %% 2010/03/27 + + \CatCode\_\before_build_cs_sub + + \MakeOther\@% + \expandafter \in@ \expandafter + {\csname \string_built \expandafter \endcsname + \expandafter}\expandafter{\niceverbNoVerbList}% + \ifin@ + \csname \string_built + \expandafter\expandafter\expandafter \endcsname + \else + \begin_min_verb \backslash_verb\string_built + \expandafter\expandafter\expandafter \test_more_verb + \fi + \fi} + %% TODO such \if nestings with ifthen!? + %% cf.: + % \let\let_token,\typeout{\meaning\let_token} + %% TEST TODO fuer xspace!? (\ifin@) + \newcommand*{\add_to_cs}[1]{% + \edef\string_built{\string_built#1}\test_more_cs} + %% + %% |\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 + %% %% 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!? + %% |\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 + +%% Hey, or just |\AddToNoVerbList{<macros>}|: %% 2010/03/28 + +\newcommand*{\AddToNoVerbList}{\AddToMacro\niceverbNoVerbList} + +%% + %% ``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 === + %% |\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 + %% 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 \DoRQsansserif + \else + \ifnum\niceverb_spacefactor + \expandafter\expandafter\expandafter\expandafter + \expandafter\expandafter\expandafter + \DoRQsansserif + \else '\fi + \fi + \else \ifvmode + \expandafter\expandafter\expandafter \DoRQsansserif + \else '\fi + \fi} + %% |\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} + %% + %% 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 === + + 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 + 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 +SENT TO CTAN + + + +v0.4 2010/03/27 restoring `_' with "auto mode" safer + + 2010/03/28 \AddToNoVerbList + + 2010/03/29 note above, renamed v0.4 + diff --git a/Master/texmf-dist/tex/latex/nicetext/wiki.sty b/Master/texmf-dist/tex/latex/nicetext/wiki.sty deleted file mode 100644 index 6fe7b4e4b46..00000000000 --- a/Master/texmf-dist/tex/latex/nicetext/wiki.sty +++ /dev/null @@ -1,376 +0,0 @@ -\ProvidesPackage{wiki}[2008/07/02 v0.2 LaTeX through Wiki markup] -%% <- vorige Aenderungen gg. 2008/06/25 verworfen -%% -%% == Legal == -%% (C) 2008 Uwe Lueck http://contact-ednotes.sty.de.vu -%% License: http://www.latex-project.org/lppl/ -%% -- AUTHOR-MAINTAINED, NO WARRANTY! -%% -%% == Features == -%% -%% The `wiki' package enables LaTeX users to use some of the -%% markup used in editing Wikipedia pages, cf. -%% -%% http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet -%% -%% or German: -%% -%% http://de.wikipedia.org/wiki/Hilfe:Bearbeitungshilfe -%% http://de.wikipedia.org/wiki/Hilfe:Textgestaltung -%% -%% Advantages of such a kind of markup are: -%% -%% 1. easier and faster to type than LaTeX code; -%% -%% 2. intuitive, understandable at a glance; -%% -%% 3. in reading the source code of the document, -%% the markup doesn't much distract from the ''text'' -%% to be printed. -%% -%% There is a binary `easylatex' available on CTAN which is more -%% powerful than the `wiki' package; the idea here is that a ''macro -%% package'' doing something similar is easier to use and to customize. -%% -%% -%% === What the Package Supports === -%% -%% 1. ''Italics'' are marked up by surrounding pairs of apostrophes, -%% '''boldface''' needs one apostrophe more on each side. -%% Boldface and italics may be nested or overlap. -%% (This endangers quoting, but I have dealt with it.) -%% -%% 2. Surrounding ``equals'' symbols (`=') mark up section headings -%% etc.: `== Section ==', `=== Subsection ===', down to -%% `===== Subparagraph ====='. -%% -%% 3. If a line starts with `*', it becomes an item in an -%% `itemize' environment. Likewise, `#' creates an `enumerate' -%% environment, and `;' makes an item in a `discription' -%% environment (differs from Wiki! -- since I don't understand -%% what the Wiki version is good for). `:' makes a `quote' -- -%% while on Wikipedia instead is used for comments on talk -%% pages. But it is also used for indented math displays, -%% so it may be combined with $...$ here. -%% An indented line is typeset ''verbatim''. Each of these -%% environments is ended by a code line without leading blank -%% spaces. -%% -%% -%% === Limitations === -%% -%% 1. The markup ``language'' provided here replaces a few most -%% common LaTeX commands only in their most simple versions. -%% (Yet I think that already this makes the code more readable; -%% the more special cases are very rare.) E.g., it's not -%% possible to suppress the italic correction as with -%% `\textit{...\nocorr}'. However, in ``normal'' cases it -%% should be possible to use the more powerful LaTeX markup -%% mixed with ``Wiki'' markup. -%% -%% 2. The parsing algorithms employed here differ in outcome to -%% those of Wikipedia in difficult cases. -%% -%% 3. Tables, nesting lists, links, Wiki templates and tags -%% are not supported -- and I don't expect that I can afford -%% improving this soon! -%% -%% 4. I still have encountered problems that I didn't understand ... -%% -%% == Package Options and User Commands == -%% -%% \usepackage[<options>]{wiki}, of course. There are <options> -%% `noEnvironments', `noFonts', `noHeadings' giving up -%% functionality for lists etc., for italics and boldface, -%% for section headings etc., respectively. -%% -%% There are commands \wikimarkup, \wikiEnvironments, -%% \wikiFonts, \wikiHeadings to turn respective functionality on -%% (unless disabled by package option). \nowikimarkup, -%% \nowikiEnvironments, \nowikiFonts, \nowikiHeadings turn them -%% off. -%% -%% '''Vital:''' The package does ''not'' execute \wikimarkup -%% because this would have strange effects, e.g., packages -%% loaded later may break. The user must put activating -%% commands into the `document' environment, maybe just preceding -%% the first heading. -%% -%% Dangers to be avoided by \nowiki... are: -%% * \wikiHeadings (which also is executed by \wikimarkup) -%% disables TeX assignments using `='. -%% * \wikiEnvironments (executed by \wikimarkup) executes macros -%% at every end of a code line (containing no comment marke), -%% and it tries to typeset a following line verbatim if it is -%% indented. -%% -%% -%% == Implementation and Further Remarks == - -%% === Commands for Category Codes === -% \RequirePackage{fdcodes} - %% <- TODO -- or do away ... -> -\providecommand*\AssignCatCode[2]{\catcode`#1=#2\relax} -\providecommand*\MakeActive[1]{\catcode`#1=\active} -% \providecommand*\MakeLetter[1]{\catcode`#1=11\relax} - %% <- Declaring characters usable in command strings - %% Todo: print arrow indicators like ``->'' as real arrows -\providecommand*\MakeOther [1]{\catcode`#1=12\relax} - -\AssignCatCode{\_}{11} -% \MakeLetter\_ %% own macros somewhat LaTeX3-style -%% Todo \newcommand <-> \def !? - -%% === Package Options === -\DeclareOption{noFonts} {\let\wikiFonts \empty - \let\nowikiFonts \relax} -\DeclareOption{noHeadings} {\let\wikiHeadings \empty - \let\nowikiHeadings \relax} -\DeclareOption{noEnvironments}{\let\wikiEnvironments \empty - \let\nowikiEnvironments\relax} -\DeclareOption{noVerbatim}{% - \def\W_active_return{ \futurelet\@let@token\W_on_firsttoken}} - %% \[no]wikiVerbatim must wait, too complex 2008/07/01 -\ProcessOptions - -%% === Auxiliaries for both Fonts and Headings === - - \@tempswafalse - \ifx\wikiFonts \empty \else \@tempswatrue \fi - \ifx\wikiHeadings\empty \else \@tempswatrue \fi - \if@tempswa -\def\W_start_samecnt{\futurelet\@let@token\W_process_samecnt} -\def\W_init_samecnt#1#2#3{% - \let\W_samesymb =#1%% repeated symbol - \def\W_repllist {#2}% replacing strings - \def\W_incase_all{#3}% final replacement - \def\W_next##1{\W_start_samecnt}} -\def\W_process_samecnt{% - \expandafter \W_splitlist \W_repllist \@nil - \W_next} -\def\W_splitlist#1#2\@nil{% - \def\W_repllist{#2}% - \ifx\@let@token\W_samesymb - \ifx\W_repllist\empty \def\W_next##1{\W_incase_all}\fi - \else - \def\W_next{#1}% - \fi} - \fi - -%% === Italics and Boldface === - -%% ==== Code ==== - \ifx\wikiFonts\empty \else -\def\W_toggle#1#2#3{\def#1{\W_toggle#1{#3}{#2}}#2} -%% Cf. LaTeX's `\DeclareTextFontCommand': -\def\W_bf_toggle{% - \W_toggle\W_bf_toggle{\bfseries\W_maybe@ic}{\mdseries\W_maybe@ic}} -\def\W_maybe@ic{\futurelet\@let@token\W_maybe_maybe@ic} -\def\W_maybe_maybe@ic{% - \ifx\@let@token\W_rq_robust \else \expandafter \maybe@ic \fi} -\def\W_it_toggle{% - \W_toggle\W_it_toggle{\itshape\maybe@ic}{\upshape\maybe@ic}} -%% <- Doesn't support \nocorr. - -\def\W_rq_robust{%% will become meaning of single right quote. - \ifx\protect\@typeset@protect - \ifmmode \rq \else - \W_init_samecnt{\W_rq_robust}% - {\rq\W_it_toggle}% - {\W_bf_toggle}% - \expandafter\expandafter\expandafter \W_start_samecnt - \fi - \else \rq \fi} -%% Remark: -%% LaTeX's \rq expands to ``other'' apostrophe: -\CheckCommand*\rq{'} %% Must be before `\catcode`\' -%% \wikiFonts -- restoring `...' and ``...'' -- + \nowikiFonts: -%% requiring single left quote \active as well: -\CheckCommand*{\lq}{`} -\MakeActive\`\MakeActive\' -\def\wikiFonts{% - \MakeActive\`\MakeActive\'% - \def`##1'{\lq ##1\rq}% - \let'\W_rq_robust} -\def\nowikiFonts{\MakeOther`\MakeOther\'} -\MakeOther\` \MakeOther\' - \fi - -%% ==== Remarks ==== -%% Wiki: a''b'''cd typesets `b' in italic with an apostrophe, -%% a''b'''c'''d typsets all after `a' in italic with bold `b'. -%% One might use make a difference depending on \lastskip. -%% Wikimedia seems to read more ahead, maybe entire paragraphs. -%% %% <- Todo: try here!? (Test!) -%% -%% Todo: Variants using \textit and \textbf (option, switching -%% command) -%% -%% german.sty's "` and "' are not affected. -%% -%% Merit: ``...'' resembles ''...''; indeed Wikipedia Guidelines -%% demand to think which of both is appropriate in a -%% certain situation. - -%% A test about \ifx with active characters: -%\catcode`\`=\active \let`\rq \let'\rq -%\ifx`'\typeout{OHHH}\else \typeout{OCH}\fi %% OHHH -%% <- how typeset code commented out!? (^!? diff. comment char.!?) -%% indent %! TODO or no space after %!! TODO!! -%% xEDIT: dann Alt C/D fuer Kommentar/Dok./auskomm. (!?) !! - -%% === Section Headings === - - \ifx\wikiHeadings\empty \else -\providecommand*{\normalequals}{=} -\MakeActive\= -\def\wikiHeadings{\MakeActive\=\let=\W_eq_robust} -\def\nowikiHeadings{\MakeOther\=} -\def\W_eq_robust{% - \ifx\protect\@typeset@protect - %% in case without math mode in heading - \ifmmode \normalequals \else - \W_init_samecnt{\W_eq_robust}% - {\normalequals\W_sec\W_subsec\W_subsubsec - \W_para\W_subpara}% - {\W_bf_toggle}% - \expandafter\expandafter\expandafter \W_start_samecnt - \fi - \else \normalequals \fi} - -\def\W_sec #1=={\section{#1}} -\def\W_subsec #1==={\subsection{#1}} -\def\W_subsubsec #1===={\subsubsection{#1}} -\def\W_para #1====={\paragraph{#1}} -\def\W_subpara #1======{\subparagraph{#1}} - -\MakeOther\= - \fi - -%% Todo: think of reimplementation by the start-line -%% mechanism which is going to be used for lists. - -%% === Environments === -%% - \ifx\wikiEnvironments\empty \else - -%% ==== Prepare Dealing with Indents ==== - -\MakeActive{\^^M}% -\def\wikiEnvironments{\MakeActive{\^^M}\let^^M\W_active_return}% -\def\nowikiEnvironments{\AssignCatCode{\^^M}{5}}% -\nowikiEnvironments%% TeX <return> restored - -\MakeActive{\ }% -\@ifundefined{W_active_return}{% -\expandafter\def\expandafter\W_active_return\expandafter{% -\space\catcode`\ \active\let \W_indent% -%% <- \W_indent will start verbatim -\futurelet\@let@token\W_on_firsttoken}% -}{}%% end of \@ifundefined which is true without noVerbatim -%% Much doubling for saving time (!??): -\expandafter\def\expandafter\W_list_activereturn\expandafter{% -\space\catcode`\ \active\let \W_restore_space% -%% <- \W_indent will start verbatim -\futurelet\@let@token\W_maybe_newitem}% -% \def\W_restore_space{\catcode`\ 10\relax}% - %% <- was vital for a math display in a list -> -\def\W_restore_space{\catcode`\ 10\ignorespaces}% -\W_restore_space%% TeX blank space restored - -%% ==== Start and End List-Like Environments ==== - -%% \W_on_firsttoken may be edited (preamble or .cfg): -\def\W_on_firsttoken{% - % \show\@let@token - \W_restore_space - \let\W_next\relax %% must be before \W_skip... works - \ifx\@let@token\W_active_return \expandafter \W_par \fi - %% <- found by guessing/with \show\@let@token - \let\W_item\item - \W_on_startenv{*}{itemize}% - \W_on_startenv{\W_hash}{enumerate}% - \W_on_startenv{;}{description}% - \let\W_item\relax %% must precede `quote' - \W_on_startenv{:}{quote}%% instead of quotation 2008/07/01 - \W_next} -\let\W_hash=# -\def\W_par#1\W_next{\par} -\def\W_skiprest_item#1\W_next#2{\W_item} - -\MakeActive{\^^M}% -\def\W_on_startenv#1#2{% - \ifx#1\@let@token% - \begin{#2}% - \let\W_itemsymbol#1% - \let^^M\W_list_activereturn% - \expandafter \W_skiprest_item% - \fi}% -\nowikiEnvironments% - -\def\W_maybe_newitem{% - \W_restore_space - \ifx\@let@token\W_itemsymbol - \expandafter \W_gobbling_item - \else - \ifx\@let@token\W_restore_space - \else - \ifx\@let@token\W_list_activereturn - \par - \else - \edef\W_next{\noexpand\end{\@currenvir}}% - \W_next - \fi - \fi - \fi} -\def\W_gobbling_item#1{\item} - -%% ==== Verbatim Environment ==== - -\def\W_indent{\begin{W_verbatim}} -\def\W_verbatim{% - \let\obeylines\W_obeylines - \@verbatim \frenchspacing\@vobeyspaces} -\let\endW_verbatim\endverbatim - -\MakeActive{\^^M} -\def\W_obeylines{% - \catcode`\^^M\active% - \def^^M{\par\futurelet\@let@token\W_check_verbcont}}% -\nowikiEnvironments% - -\def\W_check_verbcont{% - \ifx\@let@token\@xobeysp - \expandafter \@gobble %% gobble one space - \else - \def\W_next{\end{W_verbatim}}% - \expandafter \W_next - \fi} - -%% TODO: enable user to switch between environment ``encodings'' -%% or to disable some of them (edit \W_on_firsttoken) - - \fi %% from \ifx\wikiEnvironments \else - - -%% === Turning Wiki Markup On and Off === - -\def\wikimarkup{\wikiFonts\wikiHeadings\wikiEnvironments} -\def\nowikimarkup{% - \MakeOther\`\MakeOther\'\MakeOther\=\AssignCatCode{\^^M}{5}} - -% \wikimarkup %% strange effects here, to be put into document - -\AssignCatCode\_{8} -\endinput - -%% todo: tables, links, templates, (pseudo-)html-tags ... -%% TODO: credits: easylatex etc. -%% TODO: useful for: ... intuitive markup, ``poor man's WYSIWYG'', -%% ASCII-WYSIWYG. -%% Todo: improve Wiki markup: ``tab'' indents instead of `:' -%% as in testing for end of list: after finding one -%% leading space, test for another. - - - |