From 14b154c49df4af70e973eeafb54e2f31250aff0e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 3 Apr 2010 15:42:12 +0000 Subject: nicetext 0.4 (30mar10) git-svn-id: svn://tug.org/texlive/trunk@17661 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG | 71 -- Master/texmf-dist/doc/latex/nicetext/FILES | 131 +- Master/texmf-dist/doc/latex/nicetext/NNOUNCE.TXT | 48 - Master/texmf-dist/doc/latex/nicetext/README | 133 +- Master/texmf-dist/doc/latex/nicetext/README.txt | 133 +- .../doc/latex/nicetext/demo/arseneau.pdf | Bin 0 -> 115296 bytes .../texmf-dist/doc/latex/nicetext/demo/substr.pdf | Bin 0 -> 124124 bytes .../texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG | 234 ++++ .../texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt | 48 + .../texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt | 95 ++ .../texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf | Bin 0 -> 296501 bytes .../texmf-dist/doc/latex/nicetext/doc/makedoc.pdf | Bin 0 -> 308142 bytes .../doc/latex/nicetext/doc/mdoccheat.pdf | Bin 0 -> 70489 bytes .../texmf-dist/doc/latex/nicetext/doc/niceverb.pdf | Bin 0 -> 277816 bytes .../doc/latex/nicetext/doc/wikicheat.pdf | Bin 0 -> 79395 bytes .../doc/latex/nicetext/docsrc/fifinddo.tex | 650 ++++++++++ .../doc/latex/nicetext/docsrc/makedoc.cfg | 58 + .../doc/latex/nicetext/docsrc/makedoc.tex | 1286 ++++++++++++++++++++ .../doc/latex/nicetext/docsrc/mdoccheat.tex | 208 ++++ .../doc/latex/nicetext/docsrc/niceverb.tex | 874 +++++++++++++ .../doc/latex/nicetext/docsrc/wikicheat.tex | 296 +++++ Master/texmf-dist/doc/latex/nicetext/fdtxttex.tpl | 14 - Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf | Bin 290342 -> 0 bytes Master/texmf-dist/doc/latex/nicetext/fifinddo.tex | 325 ----- Master/texmf-dist/doc/latex/nicetext/makedoc.cfg | 29 - Master/texmf-dist/doc/latex/nicetext/makedoc.pdf | Bin 298922 -> 0 bytes Master/texmf-dist/doc/latex/nicetext/makedoc.tex | 616 ---------- Master/texmf-dist/doc/latex/nicetext/makedoc.tpl | 17 - Master/texmf-dist/doc/latex/nicetext/mdocchea.tex | 100 -- Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf | Bin 69740 -> 0 bytes Master/texmf-dist/doc/latex/nicetext/mkfddoc.tex | 21 - Master/texmf-dist/doc/latex/nicetext/niceverb.pdf | Bin 272413 -> 0 bytes Master/texmf-dist/doc/latex/nicetext/niceverb.tex | 427 ------- .../texmf-dist/doc/latex/nicetext/run/arseneau.tex | 220 ++++ .../texmf-dist/doc/latex/nicetext/run/fdtxttex.tex | 116 ++ .../texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl | 26 + .../texmf-dist/doc/latex/nicetext/run/makedoc.tpl | 33 + .../texmf-dist/doc/latex/nicetext/run/sample.txt | 5 + .../texmf-dist/doc/latex/nicetext/run/substr.tex | 184 +++ Master/texmf-dist/doc/latex/nicetext/sample.txt | 3 - Master/texmf-dist/doc/latex/nicetext/substr.tex | 29 - Master/texmf-dist/doc/latex/nicetext/wikichea.tex | 148 --- Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf | Bin 78545 -> 0 bytes Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex | 59 - Master/texmf-dist/tex/latex/nicetext/fifinddo.sty | 866 ++++++++++++- Master/texmf-dist/tex/latex/nicetext/makedoc.sty | 631 +++++++++- Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg | 62 +- Master/texmf-dist/tex/latex/nicetext/niceverb.sty | 796 +++++++++++- Master/texmf-dist/tex/latex/nicetext/wiki.sty | 376 ------ 49 files changed, 7010 insertions(+), 2358 deletions(-) delete mode 100644 Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG delete mode 100644 Master/texmf-dist/doc/latex/nicetext/NNOUNCE.TXT create mode 100644 Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg create mode 100644 Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/fdtxttex.tpl delete mode 100644 Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/fifinddo.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/makedoc.cfg delete mode 100644 Master/texmf-dist/doc/latex/nicetext/makedoc.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/makedoc.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/makedoc.tpl delete mode 100644 Master/texmf-dist/doc/latex/nicetext/mdocchea.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/mkfddoc.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/niceverb.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/niceverb.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl create mode 100644 Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl create mode 100644 Master/texmf-dist/doc/latex/nicetext/run/sample.txt create mode 100644 Master/texmf-dist/doc/latex/nicetext/run/substr.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/sample.txt delete mode 100644 Master/texmf-dist/doc/latex/nicetext/substr.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/wikichea.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf delete mode 100644 Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex delete mode 100644 Master/texmf-dist/tex/latex/nicetext/wiki.sty (limited to 'Master/texmf-dist') diff --git a/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG deleted file mode 100644 index f49709e4d7d..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG +++ /dev/null @@ -1,71 +0,0 @@ -______________________________________________________________________ -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/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/NNOUNCE.TXT b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.TXT deleted file mode 100644 index 2c1905a37e2..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.TXT +++ /dev/null @@ -1,48 +0,0 @@ -`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[][]{
}{} - - 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/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[]{} + you just type + \foo[]{} + !-) + + '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[]{} + you just type + \foo[]{} + !-) + + '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 new file mode 100644 index 00000000000..7cc3ec6201e Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf new file mode 100644 index 00000000000..5d924a106ac Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG new file mode 100644 index 00000000000..dec717b4a07 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG @@ -0,0 +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/doc/RELEAS03.txt b/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt new file mode 100644 index 00000000000..26cb5fab553 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt @@ -0,0 +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[][]{
}{} + + + + 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 new file mode 100644 index 00000000000..6a209273e90 Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf new file mode 100644 index 00000000000..8c9a8d1753e Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf new file mode 100644 index 00000000000..2a34ce5492d Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf new file mode 100644 index 00000000000..3aa00be21ef Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf new file mode 100644 index 00000000000..2b915d38155 Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex new file mode 100644 index 00000000000..59484968382 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex @@ -0,0 +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 + +`` occurs in " 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{#}' which breaks in ``mere expanding" + + (\TeX\ \emph{evaluates} `\tempo' instead of defining it). + + An \emph{expandable} test on emptiness is, e.g. `\ifx$#$', + + where we hope that it becomes `\iftrue' just if macro argument + + `#' is empty indeed. However, ``usually" it may \emph{also} + + become `\iftrue' when `#' 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$#$' is `\iftrue' \emph{exactly} if `#' 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/docsrc/makedoc.cfg b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg new file mode 100644 index 00000000000..cd488b9b482 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg @@ -0,0 +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/docsrc/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex new file mode 100644 index 00000000000..2007e41d3ac --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex @@ -0,0 +1,1286 @@ +\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' 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." + + + +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. + +%% 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 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. + +With v0.4 of 'makedoc', this style is supported as |PScomment|. + +You can directly call this as 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 `== ==' 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')} + +%% 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/docsrc/mdoccheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex new file mode 100644 index 00000000000..bf191c53617 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex @@ -0,0 +1,208 @@ +\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'\\ + +%% 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|\LaTeXresultFile{<output>}| issues + + `\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' + +\end{description} + + + +\end{document} + + + diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex new file mode 100644 index 00000000000..0bcddd9ae04 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex @@ -0,0 +1,874 @@ +\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 + +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 + + 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.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, 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 \[\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/docsrc/wikicheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex new file mode 100644 index 00000000000..4f04ff16bce --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex @@ -0,0 +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/fdtxttex.tpl b/Master/texmf-dist/doc/latex/nicetext/fdtxttex.tpl deleted file mode 100644 index 3ea325c46c0..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/fdtxttex.tpl +++ /dev/null @@ -1,14 +0,0 @@ -\typeout{fdtxttex.tpl 2010/03/23 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 diff --git a/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf deleted file mode 100644 index aeeed3be256..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/fifinddo.tex deleted file mode 100644 index 91234d2b73c..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/fifinddo.tex +++ /dev/null @@ -1,325 +0,0 @@ -\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/makedoc.cfg deleted file mode 100644 index 418482a3a34..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.cfg +++ /dev/null @@ -1,29 +0,0 @@ -\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.pdf b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf deleted file mode 100644 index 0d8f4e7d09c..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.tex b/Master/texmf-dist/doc/latex/nicetext/makedoc.tex deleted file mode 100644 index 5de416ecd53..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.tex +++ /dev/null @@ -1,616 +0,0 @@ -\typeout{makedoc.tex 2010/03/23 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". - -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 -|%% | 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 -`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. - -\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}}|\] - -\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')} -%% moved here 2010/03/23 -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: -\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 - -\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 diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.tpl b/Master/texmf-dist/doc/latex/nicetext/makedoc.tpl deleted file mode 100644 index e508d8cded5..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/makedoc.tpl +++ /dev/null @@ -1,17 +0,0 @@ -\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/mdocchea.tex b/Master/texmf-dist/doc/latex/nicetext/mdocchea.tex deleted file mode 100644 index 2f8658e9815..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/mdocchea.tex +++ /dev/null @@ -1,100 +0,0 @@ -\typeout{mdocchea.tex 2010/03/21 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} -% \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' -\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|\LaTeXresultFile{<output>}| issues - `\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'. -\end{description} - -\end{document} - diff --git a/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf deleted file mode 100644 index d51d4fb96af..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf and /dev/null differ 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/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf deleted file mode 100644 index 4f0d9279550..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/niceverb.tex b/Master/texmf-dist/doc/latex/nicetext/niceverb.tex deleted file mode 100644 index b1c1addef88..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/niceverb.tex +++ /dev/null @@ -1,427 +0,0 @@ -\typeout{niceverb.tex 2010/03/23 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 -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 - 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' -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). - -%% 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 - `\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 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/doc/latex/nicetext/run/fdtxttex.tex b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex new file mode 100644 index 00000000000..e36edd2bbfd --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex @@ -0,0 +1,116 @@ + \makeatletter + +\typeout{^^J*fdtxttex.tex* 2010/03/30 txt to TeX by dialogue^^J + + (apply \string\MakeDocCorrectHook) + + ^^J} + + + +\RequirePackage{fifinddo} + + + +\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/run/fdtxttex.tpl b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl new file mode 100644 index 00000000000..c9b03b314bc --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl @@ -0,0 +1,26 @@ +\typeout{fdtxttex.tpl 2010/03/30 fifinddo correction template} + +\RequirePackage{fifinddo} + +\input{mdoccorr.cfg} + +\ResultFile{sample.tex} + +\WriteProvides + +\ProcessFileWith{sample.txt}{% + + \typeout{\expandafter \MakeDocCorrectHook + + \expandafter{\fdInputLine}}% + + \WriteResult{\expandafter \MakeDocCorrectHook + + \expandafter{\fdInputLine}}% + +} + +\CloseResultFile + +\stop + diff --git a/Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl b/Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl new file mode 100644 index 00000000000..e250cc9f41e --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl @@ -0,0 +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/run/sample.txt b/Master/texmf-dist/doc/latex/nicetext/run/sample.txt new file mode 100644 index 00000000000..782297c0c05 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/run/sample.txt @@ -0,0 +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/sample.txt b/Master/texmf-dist/doc/latex/nicetext/sample.txt deleted file mode 100644 index 69408f90fd8..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/sample.txt +++ /dev/null @@ -1,3 +0,0 @@ -blabla ... blabla -blabla cf. bla -etc. bla bla \ No newline at end of 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/doc/latex/nicetext/wikichea.tex b/Master/texmf-dist/doc/latex/nicetext/wikichea.tex deleted file mode 100644 index e56bff99120..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/wikichea.tex +++ /dev/null @@ -1,148 +0,0 @@ -\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/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf deleted file mode 100644 index 481c7e314d4..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf and /dev/null differ diff --git a/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex b/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex deleted file mode 100644 index 9e5e3dda35a..00000000000 --- a/Master/texmf-dist/tex/latex/nicetext/fdtxttex.tex +++ /dev/null @@ -1,59 +0,0 @@ - \makeatletter -\typeout{^^J*fdtxttex.tex* 2010/03/22 txt to TeX by dialogue^^J - (apply \string\MakeDocCorrectHook) - ^^J} - -\RequirePackage{fifinddo} - -\def\MakeDocCorrectHook#1{#1} -\catcode`\_=11 -\def\CorrectionFile{\def\mdoc_corr} -\CorrectionFile{mdoccorr.cfg} -\ResultFile{sample.tex} -\def\InputFile{\def\input_file_name} -\InputFile{sample.txt} -\newif\iftoscreen - -\def\FD_dialogue{% - \typeout{^^J% - ===========================================================^^J% - \string\CorrectionFile{\mdoc_corr} - \space (define \@backslashchar MakeDocCorrectHook)^^J% - \string\InputFile {\input_file_name}^^J% - \string\ResultFile{\result_file_name} - \space\space\space\space\space\space\space - \string\toscreen\iftoscreen true\else false\fi ^^J% - ===========================================================% - }% - \typein[\action]% - {Run with these settings? (Y)es? (C)hange? (Otherwise quit.)}% - \csname action_\action \endcsname -} -\def\run_with_settings{% - \input{\mdoc_corr}% - \WriteProvides - \ProcessFileWith{\input_file_name}{% - \WriteResult{\expandafter \MakeDocCorrectHook - \expandafter{\fdInputLine}}% - \iftoscreen - \typeout{\expandafter \MakeDocCorrectHook - \expandafter{\fdInputLine}}% - \else - \message{.}% - \fi} - \CloseResultFile - \typeout{Done.}% - \FD_dialogue -} -\expandafter\let\csname action_y\endcsname \run_with_settings -\expandafter\let\csname action_Y\endcsname \run_with_settings - -\def\change_settings{% - \typein[\change]{^^JType setting command(s).}% - \change \FD_dialogue} -\expandafter\let\csname action_c\endcsname \change_settings -\expandafter\let\csname action_C\endcsname \change_settings - -\FD_dialogue - -\stop diff --git a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty index 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. - - - -- cgit v1.2.3