diff options
| author | Karl Berry <karl@freefriends.org> | 2010-04-05 23:24:55 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2010-04-05 23:24:55 +0000 |
| commit | c8341d201aa8f8dfccefe14289a4c9031ae066e4 (patch) | |
| tree | 7db3e7ff43954af7b8ef72053236f10dcb5df41b /Master | |
| parent | 90664c2e19fef7f53b58df6203416e812e98661d (diff) | |
nicetext update (5apr10)
git-svn-id: svn://tug.org/texlive/trunk@17725 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
31 files changed, 548 insertions, 4965 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG index dec717b4a07..b13f2a0df41 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG +++ b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG @@ -1,234 +1,133 @@ ______________________________________________________________________ +nicetext RELEASE v0.41 2010/04/05 SUMMARY: documentation changes, + corrected `niceverb.sty', + added third-party example + + FILES.txt 2010/04/05 changed name (for ...), updated, + corrected + README(.txt) 2010/04/05 typo fix ("http."), correction + CHANGE.LOG 2010/04/05 updated + CHANGE.txt 2010/04/05 new copy of CHANGE.LOG + arseneau.tex/pdf 2010/04/05 added `optional.sty' + fifinddo.sty v0.4a 2010/04/04 copyright updated + niceverb.sty v0.41 2010/04/05 stamp v0.33 -> v0.4, + corrected \AutoCmdInput + nicetext.tex/pdf 2010/04/05 corrected +______________________________________________________________________ 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/CHANGE.txt b/Master/texmf-dist/doc/latex/nicetext/CHANGE.txt new file mode 100644 index 00000000000..b13f2a0df41 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/CHANGE.txt @@ -0,0 +1,133 @@ +______________________________________________________________________ +nicetext RELEASE v0.41 2010/04/05 SUMMARY: documentation changes, + corrected `niceverb.sty', + added third-party example + + FILES.txt 2010/04/05 changed name (for ...), updated, + corrected + README(.txt) 2010/04/05 typo fix ("http."), correction + CHANGE.LOG 2010/04/05 updated + CHANGE.txt 2010/04/05 new copy of CHANGE.LOG + arseneau.tex/pdf 2010/04/05 added `optional.sty' + fifinddo.sty v0.4a 2010/04/04 copyright updated + niceverb.sty v0.41 2010/04/05 stamp v0.33 -> v0.4, + corrected \AutoCmdInput + nicetext.tex/pdf 2010/04/05 corrected + +______________________________________________________________________ +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/FILES b/Master/texmf-dist/doc/latex/nicetext/FILES.txt index 9752edc9f14..21a8c5d6f2b 100644 --- a/Master/texmf-dist/doc/latex/nicetext/FILES +++ b/Master/texmf-dist/doc/latex/nicetext/FILES.txt @@ -1,92 +1,47 @@ FILES IN CTAN DIRECTORY /macros/latex/contrib/nicetext: - - -FILES present file - + FILES.txt 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 - - +|____substr.pdf of Harald Harders' substr.sty doc documentation - |____CHANGE.LOG bundle changes - +|____CHANGE.txt copy of CHANGE.LOG in case |___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. - +this file 2010/04/05, U.L. diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt index 3c3da46d584..acc9f8f74f5 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt +++ b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt @@ -1,48 +1,24 @@ `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 - +* Extended formatting of Harald Harders' `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/README b/Master/texmf-dist/doc/latex/nicetext/README index 69123cc5c54..252dc30865b 100644 --- a/Master/texmf-dist/doc/latex/nicetext/README +++ b/Master/texmf-dist/doc/latex/nicetext/README @@ -1,250 +1,125 @@ The NICETEXT bundle - - (c) 2009 2010 Uwe Lueck http://contact-ednotes.sty.de.vu - - - == General Idea == - - The NICETEXT bundle supports "minimal" markup syntax for rather - simple kinds of text. The code you type should show little more - characters than are printed, though you get LaTeX quality. We try - to do away with backslashes, technical terms, and curly braces - (which also are so clumsy to type on PC keyboards). - - Main focus is easy documentation of LaTeX packages. Preprocessing - by Perl or so is replaced by TeX macros (reviving/generalizing the - 'docstrip' idea), including expandable, safe, correct string - substitution and typographical enhancements of plain text for - LaTeX input. - - - == Packages == - - 'wiki.sty' addresses general kinds of texts. 'niceverb.sty' is - made for documenting LaTeX packages. 'niceverb.sty' especially - offers [almost-]WYSIWIG for meta-variables (macro arguments) and - for referring to commands (and their syntax) in footnotes, - section titles etc. E.g., to get the syntax description - - \foo[<opt-arg>]{<mand-arg>} - you just type - \foo[<opt-arg>]{<mand-arg>} - !-) - - 'fifinddo.sty' provides basic setup for text filtering, especially - string substitution. 'makedoc.sty' extends it to provide a simple - script language for transforming plain text package files into LaTeX - input files [manual!?]. One LaTeX run can perform preprocessing and - typesetting. - - - == Comparisons == - - One source of inspiration is the markup syntax of editing Wikipedia - pages. 'wiki.sty' of the bundle offers something similar as a LaTeX - front-end for italics, boldface, sectioning, and certain list-like - environments. This is also similar to 'easylatex', - - - http.//www.ctan.org/pkg/easylatex - - + 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 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.tex' should typeset the version of Harald Harders' `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/30 Uwe Lueck] - + [This file 2010/04/05 Uwe Lueck] diff --git a/Master/texmf-dist/doc/latex/nicetext/README.txt b/Master/texmf-dist/doc/latex/nicetext/README.txt index 69123cc5c54..252dc30865b 100644 --- a/Master/texmf-dist/doc/latex/nicetext/README.txt +++ b/Master/texmf-dist/doc/latex/nicetext/README.txt @@ -1,250 +1,125 @@ The NICETEXT bundle - - (c) 2009 2010 Uwe Lueck http://contact-ednotes.sty.de.vu - - - == General Idea == - - The NICETEXT bundle supports "minimal" markup syntax for rather - simple kinds of text. The code you type should show little more - characters than are printed, though you get LaTeX quality. We try - to do away with backslashes, technical terms, and curly braces - (which also are so clumsy to type on PC keyboards). - - Main focus is easy documentation of LaTeX packages. Preprocessing - by Perl or so is replaced by TeX macros (reviving/generalizing the - 'docstrip' idea), including expandable, safe, correct string - substitution and typographical enhancements of plain text for - LaTeX input. - - - == Packages == - - 'wiki.sty' addresses general kinds of texts. 'niceverb.sty' is - made for documenting LaTeX packages. 'niceverb.sty' especially - offers [almost-]WYSIWIG for meta-variables (macro arguments) and - for referring to commands (and their syntax) in footnotes, - section titles etc. E.g., to get the syntax description - - \foo[<opt-arg>]{<mand-arg>} - you just type - \foo[<opt-arg>]{<mand-arg>} - !-) - - 'fifinddo.sty' provides basic setup for text filtering, especially - string substitution. 'makedoc.sty' extends it to provide a simple - script language for transforming plain text package files into LaTeX - input files [manual!?]. One LaTeX run can perform preprocessing and - typesetting. - - - == Comparisons == - - One source of inspiration is the markup syntax of editing Wikipedia - pages. 'wiki.sty' of the bundle offers something similar as a LaTeX - front-end for italics, boldface, sectioning, and certain list-like - environments. This is also similar to 'easylatex', - - - http.//www.ctan.org/pkg/easylatex - - + 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 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.tex' should typeset the version of Harald Harders' `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/30 Uwe Lueck] - + [This file 2010/04/05 Uwe Lueck] diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt b/Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt index 26cb5fab553..2c1905a37e2 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt +++ b/Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt @@ -1,95 +1,48 @@ `makedoc' + `niceverb' - an alternative documentation system for LaTeX - ====================================================================== - The `nicetext' bundle offers "minimal" markup syntax for restricted - kinds of text: There should not be much more characters typed than - printed! -- mainly: quick documentation of (smaller) LaTeX packages - -- achieved by active characters and preprocessing similar to - `docstrip' ("opposite direction" however, incl. some txt to TeX). - - New with release 0.3: - - * `substr.tex' should typeset LaTeX quality documentation from - next available (on your install) substry.sty's ASCII/UTF-8 input - (works with me) -- first application of `niceverb''s "auto mode" - and `makedoc.sty' to a third-party package! - - * `makedoc' simplified: single - - \MakeInputJobDoc[<in>][<out>]{<header>}{<parser>} - - generates a documentation file from the package file and - typesets it immediately (kind of \DocInput equivalent) - -- see `Using makedoc the simplest way' in `makedoc.pdf' - - * `|...|' from `niceverb' typesets an inline frame box for setting-off - a command description, modifiable by hooks (e.g., \colorbox) - - * `niceverb' syntax works in page headers, PDF bookmarks, and - `hyperref' labels and otherwise much better than before, - dis-/re-enableable featurewise as well as altogether - - * documentation extended, lists of script commands - - * configurable txt to TeX functionality or other replacements like - ASCII-arrows to arrow commands or inserting \index entries - (setting up expandable replacement chains slightly more comfortable) - -- try with templates and dialogue - - * `fifinddo' works with character codes > 127, improved setup - - * `makedoc' requires the `moreverb' package. - - ______________________________________________________________________ - CATALOGUE: These packages may be compared with: - * easylatex, txt2latex, txt2tex - (typographical and TeX input enhancement); - * doc, gmdoc, lineno (awk in place of \DocInput); - * substr, datatool, ted, xstring, stringstrings, makematch, ... - (parsing)
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf b/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf Binary files differindex 7cc3ec6201e..664f570a989 100644 --- a/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf Binary files differindex 5d924a106ac..70f723d2b3d 100644 --- a/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex index 59484968382..91234d2b73c 100644 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex @@ -1,650 +1,325 @@ \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/docsrc/makedoc.cfg b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg index cd488b9b482..418482a3a34 100644 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg @@ -1,58 +1,29 @@ \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 index 2007e41d3ac..28cdf0e4c85 100644 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.tex @@ -1,1286 +1,643 @@ \typeout{makedoc.tex 2010/03/30 documentation for `makedoc.sty'} - \listfiles - \RequirePackage{makedoc} - \documentclass{article} - \input{makedoc.cfg} %% with pdf stuff and 'niceverb' - %% removed for niceverb v0.31 TODO!? 2010/03/20: - \sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21 - % \makeatletter %% TEST for hyperref compatibility 2010/03/11 - % \def\@testdef #1#2#3{% - % \def\reserved@a{#3}% - % \expandafter \ifx \csname #1@#2\endcsname - % \reserved@a \else \@tempswatrue \fi - % \if@tempswa - % \typeout{^^J*** Type `r' <input> to get around - % \string\label\space issues! ***^^J} - % \errorcontextlines=0 - % \show\reserved@a - % \expandafter \show \csname #1@#2\endcsname - % \fi - % } - % \makeatother - \begin{document} - \title{'makedoc'---Preprocessing documentation by \TeX} - %% 2009/04/10: \\---\\\ breaks TOC - \maketitle - \begin{abstract}\noindent - 'makedoc' provides commands for generating \LaTeX\ input from a - package file in order to typeset the latter's documentation - (somewhat similar and opposite to 'docstrip')---with - v0.3 \emph{a single one usually suffices}. - Certain comment marks are removed, listing commands are inserted, - and some (configurable) typographical `txt'$\to$\TeX\ corrections - are applied.---This - continues the policy of 'niceverb' to minimize documentation markup in - package files. 'makedoc' extends and exemplifies the parsing package - 'fifinddo'. After an edit (and test) of your package, you get the new - documentation in one run (or the usual number of runs) of the - documentation driver file.---The present approach is meant to be an - \emph{alternative} to the standard 'doc' package and its `\DocInput'. - It provides \emph{less} than 'doc' does, rather deliberately. It may - be helpful at least for the development of small packages, or at least - at early stages. - \end{abstract} - \tableofcontents - \section{Introduction} - \emph{The abstract will not be repeated in this section.} Let me add - instead that I was in dire need of such a package, I got stuck with my - packages because I lost orientation in them, and I was unhappy with - the forms of documentations of my other packages, and documenting them - with the standard \LaTeX\ 'doc' system was not attractive for me - (neither considered helpful). %% clarified 2010/03/13 - I also worked on \emph{Windows} until September 2008, and I - find a system like the present one still more attractive then using - (learning!\@) other filtering utilities (see below on 'awk'). And I - may work on \emph{Windows} once again and don't want to depend on - installing some $\dots$ there---\emph{I really would like to have - powerful tools for everything depending on nothing but \TeX\slash - \LaTeX!} - - \section{Prior work and what is new} - It is, of course, not a new idea to get around comment marks `%' to - typeset the documentation. 'doc''s `\DocInput' does this by making `%' - an ``ignored" character. This way you cannot use `%' for commenting - comments (so 'doc' offers a ``new comment mark" - `^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!? - You also cannot use `%' for commenting out code (that you are - pondering---or using for debugging---only). %% clarified 2010/03/13 - - Moreover, 'doc' requires enclosing package code explicitly by - environment commands (behind comment marks). Stephan I. B\"ottcher - with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}' - and Grzegorz Murzynowski in \ctanpkgref{gmdoc} - aimed at doing away with this requirement. - 'lineno.sty' contains 'awk' scripts - to remove starting comment marks and to insert listing commands. - A file 'lineno.tex' is generated that typesets the documentation. - By the way, 'lineno.sty' is full of discussions, but it is not - 'docstrip'ped---the maintainers never have received a complaint - that inputting 'lineno.sty' were too slow. - - 'gmdoc' seems to get around comment marks and insert listing commands - \emph{while typesetting} by a refined version of `\DocInput', - through some careful detecting and analysing comment marks, - the approach resembles detection of lists in 'wiki.sty'.\footnote{See - 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages - document! I also find - \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.} - And this is a matter of principles---comparing the approaches of - \emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"} - ('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler, - sometimes detecting while typesetting. - (Another example is the preprocessor - \ctanpkgref{easylatex} - of which 'wiki.sty' is a much reduced ``while typesetting" variant.) - ``While typesetting" may be easier when single characters or - sequences of two or three encode markup - information---but such detection can badly interfere with other - packages etc. ``Preprocessing" may be easier when entire ``strings" - of characters decide, which may be anywhere in a file line. - - 'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by - \emph{\TeX}. There is a general discussion of this choice in the - documentation of 'fifinddo'. Preprocessing here can be done in the - same \LaTeX\ run as typesetting, though you can avoid - incompatabilities with packages needed for typesetting - (by inputting them only \emph{after} preprocessing). - - 'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be - preferable to preprocessing with other utilities: - When I took over maintenance of 'lineno.sty', - I needed hard work to get the 'awk' script running. - The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel} - 'awk' (I chose a Munich 'nawk' and reworked the script a little). - \TeX\ seems to have better fixed functionality than other utilities! - - A different alternative to \LaTeX's 'doc' system is - Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}' - where the code environments extract package code in typesetting the - documentation. %% added 2010/03/10 - - \section{Styles supported (parsers provided)}\label{sec:styles} - % \section{Styles of commenting '.sty's} - We find different styles of documenting \LaTeX\ packages. - As the main aspects I consider - (i)~\emph{telling code from comments} - and (ii)~\emph{markup in comments}. - (You may find more details on the next matters in the - ``implementation" section.) - - \subsection{Telling code from comments} - \emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX) - probably were named so to mark \emph{``comments"} as opposed - to code $\dots$ great, but actually, in ``daily practice," - they are so handy---and used---for ``commenting out" \emph{code}, - i.e., \emph{managing code versions} in a simple way: - one does not actually want to \emph{delete} code, - one might want to use it another time, maybe for debugging - $\dots$ or to remind of earlier attempts that should not be tried - again $\dots$ - - This is a problem for \emph{high-quality typesetting} of - documentation. \emph{Code} should be typeset about as you see it on - the \emph{screen}---\emph{monospaced}, this allows structuring by - indenting, it is common practice to use a typewriter typeface for - this. Real \emph{comments} should be typeset in \emph{high quality} as - usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden - code"} (``commented-out"). A comment mark starts the line, but - obviously it is not really a comment and rather should be typeset - like code (and otherwise they may break). %% 2010/03/22 - Another problem are comments at the \emph{end} of a - \emph{code} line. Sometimes they are ``real comments" ('gmdoc' - supports this style). But sometimes - this is only another version of ``version management," code - ``commented-out." - - 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 <main-parser> as described below, - or you can switch to it by - \[`\CopyFDconditionFromTo{PScomment}{comment}'\] - - \subsection{Markup in comments} - Packages using the 'doc'\slash '.dtx' system as well as alternative - highly developed systems mentioned above use (enhanced) usual - \emph{\LaTeX} syntax for markup of comments. Other packages just use - an \emph{ASCII} style \emph{without} any markup. My idea was to - support the latter style by some `txt'$\to$\LaTeX\ functionality. - 'makedoc' does this using a file 'mdoccorr.cfg' which is very small - right now. - - I also thought of introducing another sort of ``decent" markup not - needing much more space than the ``ASCII kernel" of the comments. - This is to some extent implemented in 'niceverb.sty'. I thought of the - syntax of editing \textit{Wikipedia} pages; this is partially - implemented in 'wiki.sty' which unfortunately is not yet compatible - with 'niceverb'. - - But 'makedoc' implements one \textit{Wikipedia} feature in a different - way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows: - \begin{eqnarray*} - \endcell\endcell`%% == Section =='\\ - \endcell\endcell`%% === Subsection ==='\\ - \endcell\endcell`%% ==== Subsubsection ====' - \end{eqnarray*} - i.e., you type `== <title> ==' in place of `\section{<title>}' etc. - The parser must replace `====<title3>===' before `===<title2>===' and - the latter before `==<title1>=='. In fact, 'makedoc' provides three - parsers for these situations: - \begin{description} - \cmdboxitem|\SectionLevelThreeParseInput| is the most general parser - offered. If it does not find two strings \lq`===='\rq\ enclosing - \emph{something}, it passes to - \cmdboxitem|\SectionLevelTwoParseInput| which unless finding - two strings `===' enclosing something passes to - \cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment - detector |comment|. - \end{description} - - - \section{Requirements} - 'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand' - etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same - directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the - \LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it - should be installed anyway, or you can get its latest version - (v2.3, 2008/06/03?) from CTAN. - - 'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file - 'mdoccorr.cfg' that should have come along with 'makedoc.sty' and - 'fifinddo.sty'. You may need to have a modified copy of it in the - directory of your main `.tex' file `<jobname>.tex' fitting special - needs of your project. - - \section{Using 'makedoc' the simplest way} - In the most simple case, you are preparing documentation for a package - file `<jobname>.sty' only, and you prepare a file `<jobname>.tex' - containing - \[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\] - and `\maketitle' etc.\ about your package.\footnote{With 'niceverb' - and &\title\ after &\begin{document}, you may replace - \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.} - The documentation will be produced by running `<jobname>.tex' with - \LaTeX\ (e.g., \texttt{latex <jobname>.tex}). - - First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble. - There are no package options. - - Second, to typeset the commented implementation from `<jobname>.sty', - include in <jobname>.tex's `document' environment a line - \[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\] - <header-lines> refers to a non-negative integer as follows: - We think the most simple and useful way of typesetting the first lines - of a package file including license and copyrights is ``depicting them - as image," i.e., \textit{verbatim}. We could try to determine the - number of these lines by parsing, but we won't do so soon. Please just - count them and enter the number as <header-lines>---and change it - until you can accept the outcome. - - \section{Steps of advanced usage} - \subsection{Different main parsers (second mandatory argument)} - - `\MakeInputJobDoc''s mandatory syntax actually is - \[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\] - <main-parser> refers to the parsing macro that is applied to each - input line whose number is greater than <header-lines>. - Examples for <main-parser> are named in section~\ref{sec:styles} above. - %% TODO above/below macro 2010/03/15 - `\SectionLevelThreeParseInput' is just the most general one. - For \emph{efficiency} (!? or also to avoid problems?) you may - replace `Three' by `Two' or by `One', if the `====' or the `===' - feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia} - sectioning" feature is not used at all, use - \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\] - ---provided you want to adopt the \lq`%% '\rq\ style of marking - comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style - instead, use - \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\] - - \subsection{Different extensions (optional arguments)} - If your package to be documented is a \emph{class} `<jobname>.cls', - a local configuration file `<jobname>.cfg' or something - else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg', - use - \[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\] - Moreover, `\MakeInputJobDoc' writes an intermediate file - `<jobname>.doc' and then `\input's it. If you do not like `doc' - as extension for the written file name (maybe you use - `<jobname>.doc' for something different already), preferring extension - <ext-out>, use - \[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\] - Yes, you must state <ext-in> then as well, I can't help $\dots$ - - If even <jobname> is wrong in your view, see next step $\dots$ - - \subsection{Commands modifying &\MakeInputJobDoc's behaviour} - \label{sec:modimake} - Already <jobname> may not be what you want. E.g., you may want - to collect documentations of some other files <job-1>, <job-2>, - $\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc' - with - \[`\renewcommand*{\mdJobName}{<job-1>}'\] - etc.\ (please reason yourself about additional requirements \dots) - As a matter of fact, `\MakeInputJobDoc' reads - \[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad} - `\mdJobName.<ext-out>'\] - Stated another way, <jobname> above referred to |\mdJobName|. - - `\MakeInputJobInput' moreover (by default) produces one dot - per input line processed on screen to show progress. - The reason is that `makedoc' issues the command - |\ProcessLineMessage{\message{.}}|. - Already this trivial thing seems to slow down processing considerably - (nowadays). `\MakeInputJobInput' will run faster if preceded by - \[|\ProcessLineMessage{}|\] - which will suppress any message about processing. - However, the message may be helpful in trouble-shooting. - - \subsection{Separating preprocessing from typesetting} - %% extended 2010/03/16 - To some surprise, I observe that `\MakeInputJobDoc' \emph{works.} - This is quite a new discovery of mine (2010/03/13); - before I thought that, for safety, preprocessing should happen - inside a local group \emph{preceding} `\documentclass'. - |\MakeJobDoc| works like `\MakeInputJobDoc' described above, - yet it just \emph{preprocesses} the package to be documented, - waiting for an - \[`\input{<jobname>.<ext-out>}'\] - in the `document' environment to \emph{typeset} the documentation. - So 'makedoc.tex' once had in its preamble - % \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\] - % at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later. - \begin{eqnarray*}\endcell\endcell - `{\RequirePackage{makedoc}'\cr \endcell\endcell - ` \ProcessLineMessage{}'\cr \endcell\endcell - ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr - \endcell\endcell - `\documentclass{article}' - \end{eqnarray*} - I did experience some truth in my earlier safety policy: - With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used - in the `document' environment. `\MakeInputJobDoc' in fact does some - 'niceverb' switching (provided 'niceverb' has been loaded) - when making use of `\MakeJobDoc'. - %% <- verbose to improve line breaks 2010/03/16 - - Thinking of this ``safety" approach, especially grouping (`{\code}'), - I had not much cared for compatibility with other packages - in choosing 'makedoc' macro names. - - \subsection{Other 'makedoc' (and 'fifindo') script commands} - The next script commands may be considered of a lower level than - `\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter - commands. We also list commands from 'fifinddo.sty' that may be useful - or, indeed, are needed for preparing package documentations. - This may result in ideas on how do use the script commands for - different purposes than for preparing package documentations---e.g., - apply `txt'$\to$\TeX\ preprocessing to arbitrary text files. - - \subsubsection{Choosing parameter values for next preprocessing run} - - This actually continues section~\ref{sec:modimake}. - - \begin{description} - \cmdboxitem|\ResultFile{<output>}| (from 'fifinddo') - determines (and opens through the \TeX\ primitive `\openout') - the file <output> which will contain the result of - preprocessing the package file. - \cmdboxitem|\LaTeXresultFile{<output>}|---see next section. - \cmdboxitem|\Headerlines{<number>}| determines the <number> of lines - starting the input file to be copied \emph{verbatim} - (the first mandatory argument of `\MakeJobDoc'). - \cmdboxitem|\MainDocParser{<parser>}| determines the <parser> - as in the \emph{second} mandatory argument of `\MakeJobDoc'. - \end{description} - - We are now describing some parameters which rather must be switched - ``manually" instead of being modifiable by comfortable 'makedoc' - script commands. - - With the \emph{``Wikipedia sectioning"} feature, you may change the outcome - regarding levels. Assume, e.g., the package file has titles along the - scheme `== <title> ==' only, but these should become - \emph{subsections} of the ``implementation" section of the - corresponding `.tex' file. Then - \[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\] - -- see the implementation of the sectioning feature for details. - - There is a command - \[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad} - |\OnEmptyInputLine|\] - which is modified by the former. However, I cannot say much about them - right now, I think they just were a difficult matter that I soon - decided no longer to think about for a while (cf.\ the - implementation). About the same holds for the hook |\EveryComment|. - - The `txt'$\to$\TeX\ functionality is implemented through a hook - \[|\MakeDocCorrectHook{<characters>}|\] - 'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e., - it won't change <characters>. 'mdoccorr.cfg' should redefine it so it - really ``corrects" <characters>. You might try other definitions of - `\MakeDocCorrectHook' for different ``correcting" functions. - It should be \emph{noted} that (currently) - `\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty' - provides setup for (expandable) chains of expandable replacements. - The ``Wikipedia" sectioning feature moreover uses expandable - trimming (single) surrounding spaces, this might be provided in a more - general way.\footnote{%% TODO 2010/03/16 - The \ctanpkgref{trimspaces} package - has been a \emph{model} for this feature here. It cannot be used - directly here because it reads blank spaces as \TeX\ characters with - category code 10 while 'makedoc' reads blank spaces as ``other" - characters (category code 12) in order to \emph{keep} all blank spaces.} - - \subsubsection{``Manual" insertions to the output file} - \begin{description} - \cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes - <balanced> to <output> according to the earlier command - `\ResultFile{<output>}'. - \cmdboxitem|\WriteProvides| (from 'fifindo') writes a - `\ProvidesFile' line into <output> that declares the file - to be generated by 'fifindo'. - \cmdboxitem|\LaTeXresultFile{<output>}| issues - `\ResultFile{<output>}' and then writes a - `\ProvidesFile' line into <output> that declares the file - to be generated by 'makedoc'. - \end{description} - - \subsubsection{Processing input and closing output} - \begin{description} - \cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em - reads 'mdoccorr.cfg' - (for `\MakeDocCorrectHook', see above), - %% removed \LaTeXresult... 2010/03/17 - copies <number> according to `\HeaderLines' (see above) - from <input> into <output> (according to `\ResultFile'), - then processes the remaining lines of <input> according - to `\MainDocParser' (writing several things to <output>). - `\MakeDoc' invokes{\sloppy\par} - \cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}| - (from 'fifindo') reads <input> line by line---each one stored as - macro |\fdInputLine| and applies <loop-body> to it. - \TeX's ``special" character codes (of characters listed in - macro `\dospecials') are replaced by 12 (``other") by - default---see the 'fifinddo' documentation. - \cmdboxitem|\CloseResultFile| (from 'fifinddo') - \hskip 0pt plus 1em - \emph{closes} - <output> (using \TeX's primitive `\closeout'). - \cmdboxitem|\MakeCloseDoc{<input>}| issues - `\MakeDoc{<input>}\CloseResultFile'. - \end{description} - % - Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing - additional <input> files writing into the same <output>. Or maybe you - want to add some additional lines manually to <output> using - `\WriteResult'. - - %% removed 2010/03/09: - % At least in the long run, using 'makedoc' should not imply commitment - % to a certain design or to certain \LaTeX\ packages for typesetting - % listings and documentations. Therefore, 'makedoc.cfg' (currently) - % contains \emph{local} or \emph{personal choices}, but also - % \emph{experiments} with future features of 'niceverb'. - % Especially, (at present) the `packagecode' - % environment that 'makedoc' `\write's must be chosen. - % Currently this is the `listing' environment from 'moreverb' - % with some modifications or extra settings. - % It may be vital to `\MakeOther' the active characters from 'niceverb' - % in the setup of `packagecode'. See the \emph{example} in - % section~\ref{sec:fifinddo}. - % - % Finally, - % Each package file to be typeset needs its own little - % \emph{script} of 'makedoc' commands. - % With v0.3, one or two of these should suffice. - - % It should fit into the preamble - % of the main file for documenting the package (currently %% 2009/04/09 - % just 5 commands seem to suffice, see the \emph{example} in - % section~\ref{sec:fifinddo}). - % The script commands are described - % in the \dqtd{File handling} section of 'fifinddo.pdf' and in the - % present section~\ref{sec:script} (and \ref{sec:emptylines}). - % As an alternative, you may prefer to have ``content only" (as much as - % possible) in the main typesetting file and in its preamble only - % `\input' a separate script file. - %% removed 2010/03/10: - % Yes, the idea of documenting a package \emph{here} is to have a - % separate ``driver" file for typsetting the documentation. - % It may contain an introduction and a guide for users. - % The documentation of the package code that has been prepared by the - % 'makedoc' script will be `\input'. Alternatively, the ``driver file" - % could have title etc.\ only, or preamble and a minimal `document' - % environment only. - % - % So there may be many files, which may look confusing, especially as - % compared with the 'doc' procedure. However, - % \begin{enumerate} - % \item ``One file distribution" still is possible thanks to the - % `filecontents' environment. - % \item The 'makedoc' script can create a batch file (fitting the - % system, maybe using Will Robertson's 'ifplatform', or - % 'texsys.cfg', or \dots) - % that removes certain auxiliary files or moves them to a - % certain directory. - % \item I find it helpful to have rather little ``contentual" text - % in the package file. - % \item The procedure now runs very smoothly, once the stumbling blocks - % have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'! - % 'niceverb' v0.1 was too sloppy with - % some things, and self-documentation of 'makedoc.sty' was - % difficult---its parsing and that from 'verbatim' cannot - % distinguish between markup code and typeset code.} - % \end{enumerate} - - \section{Examples}%%% (documentation of 'mdoccorr.cfg')} - %% 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 index bf191c53617..029bf243bf8 100644 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex @@ -1,208 +1,104 @@ \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 index 0bcddd9ae04..08358f3fd71 100644 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/niceverb.tex @@ -1,874 +1,438 @@ -\typeout{niceverb.tex 2010/03/29 documenting niceverb.sty} - +\typeout{niceverb.tex 2010/04/05 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 - +Harald Harders' '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 - +2010/04/05 Harder -> Harders diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex index 4f04ff16bce..e56bff99120 100644 --- a/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex +++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/wikicheat.tex @@ -1,296 +1,148 @@ \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/doc/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf Binary files differindex 6a209273e90..b7652e34cba 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf Binary files differindex 8c9a8d1753e..eab15048fec 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf Binary files differindex 2a34ce5492d..1ead8986302 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf Binary files differindex 3aa00be21ef..fd2e0bd90c8 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf diff --git a/Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex b/Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex deleted file mode 100644 index 2a1874bf912..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex +++ /dev/null @@ -1,220 +0,0 @@ -\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 deleted file mode 100644 index e36edd2bbfd..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex +++ /dev/null @@ -1,116 +0,0 @@ - \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 deleted file mode 100644 index c9b03b314bc..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl +++ /dev/null @@ -1,26 +0,0 @@ -\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 deleted file mode 100644 index e250cc9f41e..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl +++ /dev/null @@ -1,33 +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/run/sample.txt b/Master/texmf-dist/doc/latex/nicetext/run/sample.txt deleted file mode 100644 index 782297c0c05..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/run/sample.txt +++ /dev/null @@ -1,5 +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/run/substr.tex b/Master/texmf-dist/doc/latex/nicetext/run/substr.tex deleted file mode 100644 index 371045696a6..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/run/substr.tex +++ /dev/null @@ -1,184 +0,0 @@ -\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/doc/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf Binary files differindex 2b915d38155..481c7e314d4 100644 --- a/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf +++ b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf diff --git a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty index 456ddd1a67f..3bdd7c4ff3b 100644 --- a/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty +++ b/Master/texmf-dist/tex/latex/nicetext/fifinddo.sty @@ -1,1612 +1,807 @@ %% Macro package `fifinddo.sty' for LaTeX2e, %% FIDO, FIND! - -%% copyright (C) 2009 Uwe L\"uck, - +%% copyright (C) 2009 2010 Uwe L\"uck, %% http://www.contact-ednotes.sty.de.vu - %% -- author-maintained in the sense of LPPL below -- - %% for processing tex(t) files - %% (checking, filtering, converting, substituting, expanding, ...) - - -\def\fileversion{0.4} \def\filedate{2010/03/29} - - +\def\fileversion{0.4a} \def\filedate{2010/04/04} %% 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*{\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. (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 %% 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} - %% |\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> 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 - - +v0.4a 2010/04/04 copyright 2010 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 292a44242d0..250d65d1fe1 100644 --- a/Master/texmf-dist/tex/latex/nicetext/makedoc.sty +++ b/Master/texmf-dist/tex/latex/nicetext/makedoc.sty @@ -1,1148 +1,574 @@ %% Macro package `makedoc.sty' for LaTeX2e, - %% copyright (C) 2009 2010 Uwe L\"uck, - %% http://www.contact-ednotes.sty.de.vu - %% -- author-maintained in the sense of LPPL below -- - %% for preparing documentations from packages. - - \def\fileversion{0.4} \def\filedate{2010/03/30} - - %% This file can be redistributed and/or modified under - %% the terms of the LaTeX Project Public License; either - %% version 1.3a of the License, or any later version. - %% The latest version of this license is in - %% http://www.latex-project.org/lppl.txt - %% We did our best to help you, but there is NO WARRANTY. - %% - %% Please report bugs, problems, and suggestions via - %% - %% http://www.contact-ednotes.sty.de.vu - %% - \NeedsTeXFormat{LaTeX2e}[1994/12/01] - % 1994/12/01: \newcommand* etc. - \ProvidesPackage{makedoc}[\filedate\space v\fileversion\space - TeX input from *.sty (UL)] - %% - %% |\PackageCodeTrue| and |\PackageCodeFalse| set `\ifPackageCode' - %% globally, so redefinition of `~' (playing a key role in 'fifinddo') - %% may be kept local. Note the capital `T' and `F'! - \newcommand*{\PackageCodeTrue} {\global\let\ifPackageCode\iftrue} - \newcommand*{\PackageCodeFalse}{\global\let\ifPackageCode\iffalse} - %% |\ifPackageCode| is used to determine whether a listing environment - %% must be `\beg'un or `\end'ed. You may also want to suppress empty - %% code lines, while empty lines should issue a `\par' break in - %% ``comment" mode. - %% - %% Since `\newif' is not used, `\ifPackageCode' must be declared - %% explicitly. Declaration of new `\if's must be early in case - %% they occur in code that is skipped by another `\if'\dots - %% [TODO!? cf. others 2010/03/15] - \PackageCodeFalse - %% - %% 'makedoc' is an extension of 'fifinddo' on which it depends. - \RequirePackage{fifinddo}[2009/04/13] - %% Both 'fifinddo' and 'makedoc' use the ``underscore" `_' - %% as ``private letter" and restore its standard ``subscript" - %% function ({\it \TeX book Chap.\,7}) at their end. - %% Push\slash pop functionality as with `@' and `\RequirePackage' - %% is missing here. So after loading 'fifinddo', - %% we need to declare our private letter (again). - \catcode`\_=11 %% underscore used in control words - %% - %% \subsection{&\MakeDocCorrectHook\ (\dqtd{`txt2TeX'})} - %% |\MakeDocCorrectHook| is predefined to leave its argument without - %% the enclosing braces, otherwise unchanged: - \let\MakeDocCorrectHook\@firstofone - %% Less efficiently, the same could have been set up as - % \newcommand*{\MakeDocCorrectHook}[1]{\ProcessStringWith{#1}{LEAVE}} - %% according to 'fifinddo'. - %% - %% It may be \emph{redefined} in a \emph{configuration} file like - %% 'makedoc.cfg' or the 'makedoc' script file applying to a single - %% package file in order to, e.g., converting plain text to \TeX\ input - %% conforming to typographical conventions, making `$\dots$' from - %% \qtd{&.&.&.}, %% dots should not be replaced! - %% e.g. - %% Replace `LEAVE' in the previous suggestion by an identifier - %% whose job you have defined before, and use `\renewcommand' - %% in place of `\newcommand'. - %% See an example in 'makedoc.cfg'. - %% - %% You can \emph{test} your own `\MakeDocCorrectHook' by - %% \[`\typeout{\MakeDocCorrectHook{<test-string>}}'\] - %% ... provided (sometimes) `\MakeOther\ ' ... - %% You can even change it using `\IfInputLine' from 'fifinddo' in the - %% midst of preprocessing a package documentation. - %% - %% \subsection{Distinguishing package code from comments}%% <- wiki style breaks in self-doc. - %% \label{sec:distinguish} - %% Use of comment marks is a matter of personal style. Only lines - %% starting with the sequence |%% | %% box 2010/03/16 - %% are typeset in \TeX\ quality - %% under the present release. Lines just containing |%%| - %% (without the space) are used to suppress empty code lines - %% preceding section titles (while keeping some visual space - %% in the package file). There is a preferable way to do this, - %% however not in the present release ... - %% - %% The parsing macros must be set up reading `%' and ` ' as ``other" - %% characters. Using the optional arguments for this creates - %% difficulties that can be somewhat avoided by redefining - %% |\PatternCodes|. - \SetPatternCodes{\MakeOther\%\MakeOther\ }%% 2010/03/30 - %% - %% The next line sets the ``sandbox" for the detecting macro, as it - %% is coined in the documentation of 'fifinddo', with ``identifier" - %% |PPScomment|. - \MakeSetupSubstringCondition{PPScomment}{%% }{{#1}} - %% The last argument stores the expanded input line for reference by - %% macros called. The next line is a test whether the setup works. - % \expandafter \show \csname \setup_substr_cond PPScomment\endcsname - %% Here comes the definition of the corresponding testing macro. - %% #3 is the expanded input line from above. The `\If'\dots commands, - %% `\fdInputLine', `\fdInputLine', and `\RemoveDummyPatternArg' - %% are from 'fifinddo'. - \MakeSubstringConditional{PPScomment}{%% }#3{%% #3 entire test string - \DecideCommentCode{#1}{#2}{#3}\PPstring} - %% |\DecideCommentCode{#1}{#2}{#3}{#4}| is shared with the parser - %% for the \lq`% '\rq\ commenting style. %% new 2010/03/28 - \newcommand*{\DecideCommentCode}[4]{% - \IfFDinputEmpty{\OnEmptyInputLine}{% - %% The empty line test comes early to offer control with - %% `\OnEmptyInputLine' both in code and comment mode. - %% Maybe it should always? %% TODO 2009/04/13 - \IfFDempty{#1}% - {\TreatAsComment{% - \RemoveDummyPatternArg\MakeDocCorrectHook{#2}}}% - {\ifx\fdInputLine#4% - \ifPackageCode\else \WriteResult{}\fi% - %% ... allows paragraphs in comments. - \else \TreatAsCode{#3}\fi}}} - %% Job |PScomment| deals with the |% | commenting style: - \MakeSetupSubstringCondition{PScomment}{% }{{#1}} - \MakeSubstringConditional{PScomment}{% }#3{% - \DecideCommentCode{#1}{#2}{#3}\PercentChar} - %% `\PercentChar' is from 'fifinddo'.---Return to `\fdPatternCodes': - \ResetPatternCodes %% 2010/03/30 - %% - %% |\PPstring| stores the line suppressing empty code lines with - %% the \lq`%% '\rq\ style: - \newcommand*{\PPstring}{} \xdef\PPstring{\PercentChar\PercentChar} - %% - %% |comment| will be a ``generic" identifier to call a comment line - %% detector. It might be predefined to issue an ``undefined" error; - %% however this release predefines it to behave like `PPScomment': - \CopyFDconditionFromTo{PPScomment}{comment} - %% This means that the \lq`%% '\rq\ commenting style is assumed by - %% default. \[`\CopyFDconditionFromTo{PScomment}{comment}'\] - %% switches to the \lq`% '\rq\ style (with the {\it Wikipedia} - %% sectioning parser). - %% Or just choose \[`\ProcessInputWith{PScomment}'\] as <main-parser> - %% (without the {\it Wikipedia} feature). - %% - %% Alternative still to be considered: - % \@namedef{\setup_substr_cond comment}{% - % \PackageError{makedoc}{Job `comment' not defined}% - % {Use \string\CopyFDconditionFromTo{comment}}} - %% - %% \subsection{Choice of package code environment} - %% With v0.3, we adopt the solution for typesetting package code - %% that was implemented in the former 'makedoc.cfg'. So we rely - %% on the `listing' and `listingcont' environments of the - %% 'moreverb' package. - %% - %% The earlier idea was that 'makedoc.sty' uses an undefined \LaTeX\ - %% environment `packagecode' that will be defined in 'makedoc.cfg'. - %% An accompanying idea was that 'makedoc' works before the - %% `\documentclass' line inside a group, while 'makedoc.cfg' - %% is read \emph{after} the `\documentclass' line. - %% - %% We now want to simplify things. We replace - %% \[`packagecode' \mbox{\quad by\quad } `mdPackageCode'\] - %% and define the new environment globally here. 'moreverb' - %% and our choice for `\listinglabel' are - %% called at `\begin{document}'---outside the possible group. - \gdef\mdPackageCode{% - \small - %% Get rid of 'niceverb' stuff: - % \MakeOther\`\MakeOther\'%% probably OK with moreverb - \MakeOther\<\MakeOther\|% - %% From the next occurrence of the environment onwards, - %% `listing' must be replaced by `listingcont'. We must - %% copy the previous code diligently. - \gdef\mdPackageCode{\small \MakeOther\<\MakeOther\|% - \listingcont}% - \listing{1}} - \gdef\endmdPackageCode{% - \endlisting - \global\let\endmdPackageCode\endlistingcont} - \AtBeginDocument{% - \RequirePackage{moreverb}% - \renewcommand*{\listinglabel}[1]{% - \llap{\scriptsize\rmfamily\the#1}\hskip\listingoffset\relax}% - } - %% |\ResetCodeLineNumbers| may be needed to \emph{reset} - %% 'moreverb''s (global!) code line number settings - %% (\emph{first} line number + {\it modulo} for displaying) - %% when combining documentations of \emph{more} than one package - %% with the present solution for implementing `mdPackageCode': - \newcommand*{\ResetCodeLineNumbers}{% - \global\listing@line\@ne \gdef\listing@step{\@ne}} - %% - %% \subsection{Dealing with comments} - %% |\TreatAsComment{<text>}| writes <text> to the documentation - %% file. If we had ``package code" (were in ``code mode") so far, - %% the listing environment is ended first. - \newcommand*{\TreatAsComment}[1]{% - \ifPackageCode - \WriteResult{\string\end{mdPackageCode\@empty}}% - %% The `\@empty' here is a lazy trick to save self-documentation - %% fighting 'verbatim''s ``highlight" of finding ends of listings - %% (to be improved). %% TODO 2010/03/09 - %% - %% We always use `\string' to prevent macro expansion in `\write'ing - %% in place of \LaTeX's `\protect', - %% as long as 'fifinddo' simply uses the primitive `\write' in place - %% of \LaTeX's `\proteced@write' ... %% todo 2009/04/08 - \PackageCodeFalse - \EveryComment - % \_empty_code_lines_false - \fi - \WriteResult{#1}} - %% Here, |\EveryComment| is a macro hook for inserting material that should - %% not appear in a listing environment, I had tried this %% 2010/03/18 - %% successfully: - %% \begin{verbatim} - %% \gdef\EveryComment{% - %% \global\let\EveryComment\relax - %% \WriteResult{\string\AutoCmdVerbSyntax}} - %% \end{verbatim} - %% Initialized: - \global\let\EveryComment\relax %% should be changed globally. - %% - %% \subsection{Sectioning} - %% \label{sec:secparsers} - %% We provide a facility from 'wiki.sty' that imitates the sectioning - %% syntax used in editing \emph{Wikipedia} pages, in a different - %% implementation (better compatibility) and in a more general way. - %% On Wikipedia, `== Definition ==' works similar as - %% `\section{Definition}' does with \LaTeX. With the present - %% implementation, you can type, e.g., - %% \[`%%%%%%%%%%%%%%%%%%%%%% == Definition == %%%%%%%%%%%%%%%%%%%%%%'\] - %% to get a similar result. The number of `%' characters doesn't - %% matter, and there can be other stuff, however: additional `=' - %% symbols may harm. Three sectioning levels are supported, through - %% `==<text>==', `===<text>===', and `====<text>====' (deepest). - %% - %% There are three detector macros made for programmers. - %% The most general one is - %% In the following definitions, there is a single tilde to prevent - %% `=' symbols being gobbled by the test (realized by accident). - %% %% 2009/04/13 - %% \par\noindent %% 2010/03/11 - %% |\SectionLevelThreeParseInput|: - \newcommand*{\SectionLevelThreeParseInput}{% - \expandafter \test_sec_level_iii \fdInputLine ~========&} - %% |\SectionLevelTwoParseInput| - \newcommand*{\SectionLevelTwoParseInput}{% - \expandafter \test_sec_level_ii \fdInputLine ~======&} - %% and |\SectionLevelOneParseInput| - \newcommand*{\SectionLevelOneParseInput}{% - \expandafter \test_sec_level_i \fdInputLine ~====&} - %% allow skipping deeper levels for efficiency. - %% % TODO in fifinddo: setup for 2 strings in 1 line 2009/04/13 - %% - %% In the terminology of the 'fifinddo' documentation, the previous - %% three commands are ``sandbox builders." The following three - %% commands are the corresponding ``substring conditionals." - %% However, 'fifinddo' so far %% todo 2009/04/08 - %% only deals with \emph{single} substrings, while here we are - %% dealing with \emph{pairs} of substrings. We are not using - %% general setup macros, but define the parsing macros ``manually," - %% as it is typical in many other macros in 'latex.ltx' and other - %% \LaTeX\ packages. You can fool our macros easily, there is - %% no syntax check. %% todo 2009/04/08 - \def\test_sec_level_iii#1====#2====#3&{% - \IfFDempty{#2}% - {\test_sec_level_ii #1======&}% - {\WriteSection\mdSectionLevelThree{#2}}} - \def\test_sec_level_ii#1===#2===#3&{% - \IfFDempty{#2}% - {\test_sec_level_i #1====&}% - {\WriteSection\mdSectionLevelTwo{#2}}} - \def\test_sec_level_i#1==#2==#3&{% - \IfFDempty{#2}% - {\RemoveTildeArg \ProcessStringWith{#1}{comment}}% - {\WriteSection\mdSectionLevelOne{#2}}} - %% `\ProcessStringWith' here passes the expanded `\fdInputLine' - %% to the general comment detector. - %% - %% |\WriteSection{<command>}{<text>}| replaces an input line - %% with a line \[`<command>{<text>}'\] - %% in the documentation file and switches into ``comment mode." - %% One possible space between `=' and the beginning of <text> - %% and one possible space between the end of <text> and `=' - %% are removed. - %% The method of dealing with surrounding blank - %% spaces is new with v0.3, moreover we now rely on a new method in - %% 'niceverb.sty' v0.3 to support its single right quote feature in - %% section titles.\footnote{&\ignorespaces\ and &\unskip\ used - %% previously do not work in PDF bookmarks.} - \newcommand*{\WriteSection}[2]{% - \TreatAsComment{^^J#1{\trim_correct{#2}}^^J}} - %% Trimming ``other" spaces is a little more clumsy than - %% what the 'trimspaces' package does whose code is by - %% Morten H\o gholm. It still has inspired the following. - \begingroup \MakeOther\ %% CARE! we must not indent ... - \long\gdef\trim_correct#1{\trim_fosp$#1$ $} - \long\gdef\trim_fosp#1$ {% - \IfFDempty{#1}{\trim_losp$}{\trim_losp#1$ }} - %% So we have a string \lq`\trim_losp$<text>$ $'\rq. - \long\gdef\trim_losp$#1 ${\tidy_sp_trim#1$} - %% So we have a string \lq`\tidy_sp_trim<text>$ $'\rq - %% or \lq`\tidy_sp_trim<text>$$'\rq. - \long\gdef\tidy_sp_trim#1$#2${\MakeDocCorrectHook{#1}} - \endgroup - %% We insert `\section' using |\mdSectionLevelOne| etc.\ - %% which the programmer can redefine, e.g., when the - %% documentation is part of a `\section' (or even deeper) - %% according to the ``documentation driver" file. - \newcommand*\mdSectionLevelOne {\string\section} - \newcommand*\mdSectionLevelTwo {\string\subsection} - \newcommand*\mdSectionLevelThree{\string\subsubsection} - %% - %% This sectioning feature is not used in (the documentation) of - %% 'makedoc.sty'---\emph{definitions} of the parsing macros fool - %% the same macros ... - %% - %% \subsection{Commented code} - %% |\TreatAsCode{<text>}| is the opposite to `\TreatAsComment{<text>}': - \newcommand*{\TreatAsCode}[1]{% - \ifPackageCode - % \_empty_code_lines_true - \else - \WriteResult{\string\begin{mdPackageCode}}% - \PackageCodeTrue - \fi - \WriteResult{#1}% - % \WriteResult{\maybe_result_empty_line #1}% - % \let\maybe_result_empty_line\empty - } - %% - %% \subsection{Dealing with empty input lines} %% TODO use!? 2010/03/09 - %% \label{sec:emptylines} - %% |\OnEmptyInputLine| is a default setting (or hook) for what to do - %% with empty lines in the input file. The default is to insert an - %% empty line in the output file: - \newcommand*{\OnEmptyInputLine}{\WriteResult{}} - %% |\NoEmptyCodeLines| changes the setting to suppressing empty code - %% lines, while in ``comment mode" an empty input line \emph{does} - %% insert an empty line, for starting a new paragraph: - \newcommand*{\NoEmptyCodeLines}{%% suppress empty code lines - \renewcommand*{\OnEmptyInputLine}{% - \ifPackageCode \else \WriteResult{}\fi}} - %% There is a better policy---didn't work so far ... - %% - %% \subsection{Bundling typical things: script commands} - %% \label{sec:script} - %% Practical experience suggested the following shorthands, - %% combining commands from 'makedoc' and 'fifinddo'. - %% - %% \subsubsection{Output file and &\filelist\ entry} - %% |\LaTeXresultFile{<output>}| chooses <output> as name - %% for the output file and saves you the extra line for inserting - %% the `\ProvidesFile' line as with 'fifinddo''s - %% `\WriteProvides'---however, it differs, actually it is 'makedoc' - %% that wants to be mentioned with `\ProvidesFile' ... - %% %% (otherwise copied from 'fifinddo') ... - \newcommand*{\LaTeXresultFile}[1]{% - \ResultFile{#1}%%% \WriteProvides} - \WriteResult{% - \string\ProvidesFile{\result_file_name}% - [\the\year/\two@digits\month/\two@digits\day\space - automatically generated with makedoc.sty]}}% - %% \subsubsection{Choose input file and run!} - %% |\MakeDoc{<input>}| preprocesses <input> to render input for - %% \LaTeX, considering what is typical for a \LaTeX\ package as the - %% <input> one here: - \newcommand*{\MakeDoc}[1]{% - %% In case of a ``header" (see below) we change into ``code mode": - \ifnum\header_lines>\z@ - \WriteResult{\string\begin{mdPackageCode}}% - \PackageCodeTrue %% TODO both lines makedoc command!? - %% 2009/04/08 - \else \PackageCodeFalse \fi - %% The loop follows. There is a placeholder `\makd_doc_line_body' - %% that is predefined below and can be changed while processing the - %% <input> file. - \ProcessFileWith{#1}{% - \CountInputLines %% stepping line counter is standard - \make_doc_line_body - \process_line_message}% - %% Currently the ``VERSION HISTORY" or, more generally, - %% a final part of the <input> file is typeset verbatim - %% (for ``tabbing" in the version history), - %% so we must leave ``code mode" finally: - \ifPackageCode - \WriteResult{\string\end{mdPackageCode\@empty}}%% self-doc-trick - \PackageCodeFalse %% TODO both lines makedoc command!? 2009/04/08 - \fi - %% When the <input> file has been processed, certain default settings - %% might be restored---in case another <input> file is processed for the - %% same documentation document: - % \HeaderLines{0}% - % \MainDocParser{\SectionLevelThreeParseInput}%% TODO!? 2009/04/08 - } - %% |\MakeCloseDoc{<input>}| %% 2010/03/11 - %% just is a shorthand for - %% \[`\MakeClose{<input>}\CloseResultFile'\] - %% where `\CloseResultFile' is from 'fifinddo'. - \newcommand*{\MakeCloseDoc}[1]{\MakeDoc{#1}\CloseResultFile} - %% `\MakeDoc' and `\MakeCloseDoc' actually \emph{process} - %% the <input> file, - %% depending on certain \emph{parameters} some of which are set - %% by the commands described next. - %% - %% \subsubsection{Preamble vs.\ main part of input file} - %% A \LaTeX\ package typically has a ``header" or ``preamble" - %% (automatically inserted by 'docstrip') with very scarce information - %% on which file it is and what it provides, and with much more Legalese. - %% Typesetting it in \TeX\ quality may be more misleading than - %% typesetting it \emph{verbatim}. So we typeset it \emph{verbatim}. - %% Now: where does the ``header" end? - %% `\NeedsTeXFormat' might be considered the border.---Yet it seems - %% to be more simple and reliable just to act in terms of the - %% \emph{number of lines} - %% that the header should be long. This length <how-many-lines> is declared by - %% |\HeaderLines{<how-many-lines>}|: - \newcommand*{\HeaderLines}{\def\header_lines} - \HeaderLines{0} - %% So the default is that there aren't any header lines, unless - %% another `\HeaderLines' is issued before some `\MakeDoc'. - %% The way input is parsed \emph{after} the ``header" is set by - %% |\MainDocParser{<parsing-command>}|. - \newcommand*{\MainDocParser}{\def\main_doc_parser} - %% `\SectionLevelThreeParseInput' from section~\ref{sec:secparsers} - %% is the default, two alternatives are defined there, another one is - %% `\ProcessInputWith{comment}' from 'fifinddo' and - %% %% clarified 2010/03/09 `\ref' 2010/03/10 - %% section~\ref{sec:distinguish} - %% (general dividing into code and comments). - \MainDocParser{\SectionLevelThreeParseInput} - %% Here is how `\HeaderLines' and `\MainDocParser' act: - \def\make_doc_line_body{% - \IfInputLine{>\header_lines}% - {\let\make_doc_line_body\main_doc_parser - \make_doc_line_body}% %% switch to deciding - {\TreatAsCode{\fdInputLine}}} %% header verbatim - %% \subsubsection{Screen messages} - %% |\ProcessLineMessage{<command>}| is designed to choose a screen - %% (or log) message <command>. - %% % A simple setting may be \[`\ProcessLineMessage{\message{.}}'\] with - %% `\ProcessLineMessage{\message{.}}' has a result like with 'docstrip'. - %% You just get one dot on screen per input line - %% as a simple confirmation that - %% the program is not hung up. %% TODO phrase!? 2009/04/08 - %% However, the message may slow down a run considerably - %% (if so, choose `\ProcessLineMessage{}' in the script). - %% % , you really have to - %% % wait about a second while you hardly notice the 'makedoc' run - %% % without screen messages. Therefore, the default is \emph{not} - %% % to issue any screen message.%% TODO more complex procedures!? 2009/04/08 - %% %---No! - %% But it is better for beginner users of the package, - %% so made default. %% 2009/04/09 - \newcommand*{\ProcessLineMessage}{\def\process_line_message} - % % \ProcessLineMessage{} %% no, still more efficient: - % \let\process_line_message\relax - \ProcessLineMessage{\message{.}} - %% - %% \subsubsection{Bundling-bundling Standalones} - %% |\MakeInputJobDoc{<header-lines>}{<main-parser>}| - %% by default produces a file - %% \[`\jobname.doc' \mbox{\quad from\quad } `\jobname.sty'\] - %% with some standard settings.\footnote{This command is new with v0.3.} - %% 'mdoccorr.cfg' (for `.txt'$\to$\LaTeX\ functionality) is read, - %% `\HeaderLines{<header-lines>}' - %% and `\MainDocParser{<main-parser>}' and finally - %% `\MakeCloseDoc{\jobname.sty}{\jobname.doc}' - %% % (with the arguments named before) - %% are executed. - %% Here `\jobname' expands to the file name base of the - %% `.tex' file you are running. It is assumed that you are preparing - %% documentation for `\jobname.tex' for your `\jobname.sty'. - %% In order to produce `<my-job>.doc' from `<my-job>.sty' instead, - %% \[`\renewcommand{\mdJobName}{<my-job>}'\] - %% If your input file has a different file name extension - %% <in-ext> than \qtd{`sty'}, use an optional argument - %% of `\MakeInputJobDoc': - %% \[|\MakeInputJobDoc[<in-ext>]{<header>}{<parser>}|\] - %% If the output file - %% should have a different extension <out-ext> than \qtd{`doc'}, - %% you must use \emph{two} optional arguments as follows: - %% \[|\MakeInputJobDoc[<in-ext>][<out-ext>]{<header>}{<parser>}|\] - %% `\MakeInputJobDoc' does \emph{not} execute `\ProcessLineMessage', - %% you can use the latter before so `\MakeInputJobDoc' respects it. - %% - %% |\MakeJobDoc| does the same as `\MakeInputJobDoc' apart from - %% typesetting the <created> file, so the latter needs an additional - %% `\input{<created>}'. - %% - %% My original idea was that all preprocessing of package files - %% to be documented should <happen> \emph{before} - %% `\documentclass'---loading - %% 'makedoc.sty' included---inside a group (\lq`{<happen>}'\rq---in - %% order to avoid compatibility issues). - %% However, it now appears to me that loading 'makedoc' the usual way - %% in the document \emph{preamble} - %% and processing the package file (that is to be documented) - %% within the `document' environment works well enough and - %% will be easier to comprehend. - %% - %% This is the code for both `\MakeJobDoc' and `\MakeInputJobDoc': - \@ifdefinable{\mdJobName}{\let\mdJobName\jobname} - \newif\if_makedoc_input_ - \newcommand*{\MakeInputJobDoc}{\_makedoc_input_true - \make_job_doc_read} - \newcommand*{\MakeJobDoc} {\_makedoc_input_false - \make_job_doc_read} - \newcommand*{\make_job_doc_read}[1][sty] - {\@testopt{\make_job_doc[#1]}{doc}} - %% Reading files as follows would fail with active 'niceverb' settings, - %% so we issue `\noNiceVerb' if it is defined. We do it inside a group - %% in case 'niceverb' settings are to be restored afterwards. - \def\make_job_doc[#1][#2]#3#4{% - \begingroup - \@ifundefined{noNiceVerb}{}% - {\let\MakeNormal\MakeNormalHere \noNiceVerb}% - \input{mdoccorr.cfg}% - %% <- TODO warning if not found!? - %% or if one from TEXMF/ used inadvertently!? - %% avoid reading twice!? 2010/03/11 - %% <- TODO stack danger in group!? 2010/03/13 - %% <- TODO or read it from 'makedoc' already! 2010/03/13 - \LaTeXresultFile{\mdJobName.#2}% - \HeaderLines{#3}% - \MainDocParser{#4}% - \MakeCloseDoc{\mdJobName.#1}% - %% For typesetting the file just created, some 'nicetext' features - %% may be needed ... so restore the previous ones ... - \endgroup - \if_makedoc_input_\input{\mdJobName.#2}\fi - } - %% This feature may \emph{change}. - %% - %% \subsection{Leave the package} - \catcode`\_=8 %% restores underscore use for subscripts - \endinput - %% - %% \subsection{VERSION HISTORY} - - v0.1 2009/04/03 very first version, tested on morgan.sty - v0.2 2009/04/05 \OnEmptyInputLine, \NoEmptyCodeLines - comment -> PPScomment, \IfFDinputEmpty, - \EveryComment, \PPstring may be par break - 2009/04/08 \InputString -> \fdInputLine, - \section -> \subsection; documentation! - 2009/04/08f. \MakeDoc - 2009/04/12 ``line too long'' w/o redefining \PatternCodes; - \MakeDocCorrectHook - 2009/04/13 tilde with sectioning - v0.3 2010/03/08 \WriteSection 'trimspaces'-like - 2010/03/09 "fool" ("wiki" sectioning) nicer worded, - more use of `...' in place of `\dots'; - different treatment of package code environment - (new separate subsection); clarification on - \ProcessInputWith{comment} - 2010/03/10 supplied `\ref' - 2010/03/11 \MakeCloseDoc; corrected "undifined"; - \par\noindent in ``Sectioning"; \MakeJobDoc - 2010/03/12 &.&.&.; updated copyright - 2010/03/13 corr.: `_' not ``other"; tried to explain my - earlier reasoning about `\ifPackageCode'; - \MakeInputJobDoc - 2010/03/14 \make_doc_job without \niceverb_aux_cat - 2010/03/15 another remark to \ifPackageCode - 2010/03/16 use box with comment line markers; - mdcorr -> mdoccorr - 2010/03/18 report on using \EveryComment - 2010/03/19 '' -> " - v0.4 2010/03/23 "Distinguishing" - 2010/03/24 "both in" - 2010/03/27 switch back to \fdPatternCodes - 2010/03/28 include `% ' commenting style - 2010/03/29 \ResetCodeLineNumbers - 2010/03/30 use \SetPatternCodes, \ResetPatternCodes - diff --git a/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg b/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg index 665b037b0af..79d3172b34f 100644 --- a/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg +++ b/Master/texmf-dist/tex/latex/nicetext/mdoccorr.cfg @@ -1,80 +1,40 @@ \ProvidesFile{mdoccorr.cfg}[2010/03/29 - local typographical corrections - with `makedoc.sty'] - %% ... also demonstrates 'niceverb.sty'---see the typeset - %% documentation of the present file in `makedoc.pdf'. - %% - %% |\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| (silently) - %% enters through a default variant |\SetCorrectHookJobLast| - %% of |\SetCorrectHookJob{<id>}|: - \SetCorrectHookJobLast - %% - %% |\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 22e0ad3aa2a..a2f7b104f65 100644 --- a/Master/texmf-dist/tex/latex/nicetext/niceverb.sty +++ b/Master/texmf-dist/tex/latex/nicetext/niceverb.sty @@ -1,1546 +1,775 @@ \NeedsTeXFormat{LaTeX2e}[1994/12/01] - -\ProvidesPackage{niceverb}[2010/03/29 v0.4 - +\ProvidesPackage{niceverb}[2010/04/05 v0.41 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.---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\_ - -%% Restoring \qtd{&_} more carefully with v0.33 - +%% Restoring \qtd{&_} more carefully with v0.4 %% (`\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 - + \AddToMacro\niceverbNoVerbList{\ProvidesFile}% + %% <- removed `\endinput', will be code! 2010/04/05 \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 +SENT TO CTAN +v0.41 2010/04/03 v0.33 -> v0.4 + 2010/04/05 corrected \AutoCmdInput list diff --git a/Master/texmf-dist/tex/latex/nicetext/wiki.sty b/Master/texmf-dist/tex/latex/nicetext/wiki.sty new file mode 100644 index 00000000000..6fe7b4e4b46 --- /dev/null +++ b/Master/texmf-dist/tex/latex/nicetext/wiki.sty @@ -0,0 +1,376 @@ +\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. + + + |