From c8341d201aa8f8dfccefe14289a4c9031ae066e4 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 5 Apr 2010 23:24:55 +0000 Subject: nicetext update (5apr10) git-svn-id: svn://tug.org/texlive/trunk@17725 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG | 133 +++++ Master/texmf-dist/doc/latex/nicetext/CHANGE.txt | 133 +++++ Master/texmf-dist/doc/latex/nicetext/FILES | 92 --- Master/texmf-dist/doc/latex/nicetext/FILES.txt | 47 ++ Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt | 24 + Master/texmf-dist/doc/latex/nicetext/README | 131 +---- Master/texmf-dist/doc/latex/nicetext/README.txt | 131 +---- Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt | 48 ++ .../doc/latex/nicetext/demo/arseneau.pdf | Bin 115296 -> 136653 bytes .../texmf-dist/doc/latex/nicetext/demo/substr.pdf | Bin 124124 -> 122690 bytes .../texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG | 234 -------- .../texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt | 48 -- .../texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt | 95 --- .../texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf | Bin 296501 -> 0 bytes .../texmf-dist/doc/latex/nicetext/doc/makedoc.pdf | Bin 308142 -> 0 bytes .../doc/latex/nicetext/doc/mdoccheat.pdf | Bin 70489 -> 0 bytes .../texmf-dist/doc/latex/nicetext/doc/niceverb.pdf | Bin 277816 -> 0 bytes .../doc/latex/nicetext/doc/wikicheat.pdf | Bin 79395 -> 0 bytes .../doc/latex/nicetext/docsrc/fifinddo.tex | 325 ----------- .../doc/latex/nicetext/docsrc/makedoc.cfg | 29 - .../doc/latex/nicetext/docsrc/makedoc.tex | 643 --------------------- .../doc/latex/nicetext/docsrc/mdoccheat.tex | 104 ---- .../doc/latex/nicetext/docsrc/niceverb.tex | 442 +------------- .../doc/latex/nicetext/docsrc/wikicheat.tex | 148 ----- Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf | Bin 0 -> 292557 bytes Master/texmf-dist/doc/latex/nicetext/makedoc.pdf | Bin 0 -> 304044 bytes Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf | Bin 0 -> 69681 bytes Master/texmf-dist/doc/latex/nicetext/niceverb.pdf | Bin 0 -> 274072 bytes .../texmf-dist/doc/latex/nicetext/run/arseneau.tex | 220 ------- .../texmf-dist/doc/latex/nicetext/run/fdtxttex.tex | 116 ---- .../texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl | 26 - .../texmf-dist/doc/latex/nicetext/run/makedoc.tpl | 33 -- .../texmf-dist/doc/latex/nicetext/run/sample.txt | 5 - .../texmf-dist/doc/latex/nicetext/run/substr.tex | 184 ------ Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf | Bin 0 -> 78545 bytes 35 files changed, 394 insertions(+), 2997 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG create mode 100644 Master/texmf-dist/doc/latex/nicetext/CHANGE.txt delete mode 100644 Master/texmf-dist/doc/latex/nicetext/FILES create mode 100644 Master/texmf-dist/doc/latex/nicetext/FILES.txt create mode 100644 Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt create mode 100644 Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/makedoc.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf create mode 100644 Master/texmf-dist/doc/latex/nicetext/niceverb.pdf delete mode 100644 Master/texmf-dist/doc/latex/nicetext/run/arseneau.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tex delete mode 100644 Master/texmf-dist/doc/latex/nicetext/run/fdtxttex.tpl delete mode 100644 Master/texmf-dist/doc/latex/nicetext/run/makedoc.tpl delete mode 100644 Master/texmf-dist/doc/latex/nicetext/run/sample.txt delete mode 100644 Master/texmf-dist/doc/latex/nicetext/run/substr.tex create mode 100644 Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG new file mode 100644 index 00000000000..b13f2a0df41 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/CHANGE.LOG @@ -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/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 deleted file mode 100644 index 9752edc9f14..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/FILES +++ /dev/null @@ -1,92 +0,0 @@ -FILES IN CTAN DIRECTORY /macros/latex/contrib/nicetext: - - - -FILES present file - -README summary - -README.txt copy of README - - - -fifinddo.sty parsing and file handling - - makedoc.sty package to documentation preprocessing - -mdoccorr.cfg txt to TeX macros - -niceverb.sty minimal documentation markup - - wiki.sty Wikimedia-like markup - - - -SUBDIRECTORIES: - - - -demo automatically generated documentation ... - -|__arseneau.pdf of packages by Donald Arseneau - -|____substr.pdf of Harald Harder's substr.sty - - - -doc documentation - -|____CHANGE.LOG bundle changes - -|___NNOUNCE.txt announcement for present release - -|__RELEAS03.txt announcement for previous release - -|__fifinddo.pdf for fifinddo.sty - -|___makedoc.pdf for makedoc.sty - -|_mdoccheat.pdf lists makedoc+fifinddo commands - -|__niceverb.pdf for niceverb.sty - -|_wikicheat.pdf lists wiki.sty features - - - -docsrc documentation sources - -|__fifinddo.tex - -|___makedoc.tex - -|___makedoc.cfg shared style settings - -|__mdocchea.tex - -|__niceverb.tex - -|_wikicheat.tex - - - -run dialogues/templates/examples - -|__arseneau.tex typesets documentation of ... - -|__fdtxttex.tex dialogue for txt to TeX etc. - -|__fdtxttex.tpl fifinddo script for txt to TeX etc. - -|___makedoc.tpl makedoc script for txt to TeX - -|____sample.txt watch its TeX enhancement - -|____substr.tex typesets substr.sty documentation - - - -__________________________ - -this file 2010/03/30, U.L. - diff --git a/Master/texmf-dist/doc/latex/nicetext/FILES.txt b/Master/texmf-dist/doc/latex/nicetext/FILES.txt new file mode 100644 index 00000000000..21a8c5d6f2b --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/FILES.txt @@ -0,0 +1,47 @@ +FILES IN CTAN DIRECTORY /macros/latex/contrib/nicetext: + + 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 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/04/05, U.L. diff --git a/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt new file mode 100644 index 00000000000..acc9f8f74f5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/NNOUNCE.txt @@ -0,0 +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 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[]{} - you just type - \foo[]{} - !-) - - 'fifinddo.sty' provides basic setup for text filtering, especially - string substitution. 'makedoc.sty' extends it to provide a simple - script language for transforming plain text package files into LaTeX - input files [manual!?]. One LaTeX run can perform preprocessing and - typesetting. - - - == Comparisons == - - One source of inspiration is the markup syntax of editing Wikipedia - pages. 'wiki.sty' of the bundle offers something similar as a LaTeX - front-end for italics, boldface, sectioning, and certain list-like - environments. This is also similar to 'easylatex', - - - http.//www.ctan.org/pkg/easylatex - - + 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[]{} - you just type - \foo[]{} - !-) - - 'fifinddo.sty' provides basic setup for text filtering, especially - string substitution. 'makedoc.sty' extends it to provide a simple - script language for transforming plain text package files into LaTeX - input files [manual!?]. One LaTeX run can perform preprocessing and - typesetting. - - - == Comparisons == - - One source of inspiration is the markup syntax of editing Wikipedia - pages. 'wiki.sty' of the bundle offers something similar as a LaTeX - front-end for italics, boldface, sectioning, and certain list-like - environments. This is also similar to 'easylatex', - - - http.//www.ctan.org/pkg/easylatex - - + 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/RELEAS03.txt b/Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt new file mode 100644 index 00000000000..2c1905a37e2 --- /dev/null +++ b/Master/texmf-dist/doc/latex/nicetext/RELEAS03.txt @@ -0,0 +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[][]{
}{} + + 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 index 7cc3ec6201e..664f570a989 100644 Binary files a/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf and b/Master/texmf-dist/doc/latex/nicetext/demo/arseneau.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf index 5d924a106ac..70f723d2b3d 100644 Binary files a/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf and b/Master/texmf-dist/doc/latex/nicetext/demo/substr.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG b/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG deleted file mode 100644 index dec717b4a07..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/doc/CHANGE.LOG +++ /dev/null @@ -1,234 +0,0 @@ -______________________________________________________________________ - -nicetext RELEASE v0.4 2010/03/30 SUMMARY: `% ' commenting style - - supported, applied to packages - - by Donald Arseneau, extended - - formatting through specific - - replacements, also with - - substr.sty, improved setup for - - \MakeDocCorrHook - - - -- FILES 2010/03/30 updated - - README 2010/03/30 updated - - CHANGE.LOG 2010/03/30 updated - - NNOUNCE.txt 2010/03/30 updated - - RELEA03.txt 2010/03/30 renamed - - - -- fifinddo.sty v0.4 2010/03/29 setup for replacement chaining - - and \MakeDocCorrectHook - - improved: \SetPatternCodes, - - \ResetPatternCodes, - - \SetCorrectHookJob, - - \SetCorrectHookJobLast - - fifinddo.pdf 2010/03/29 updated - - fdtxttex.tex 2010/03/30 updated - - fdtxttex.tpl 2010/03/30 updated - - - -- makedoc.sty v0.4 2010/03/30 `% ' commenting style supported, - - \ResetCodeLineNumbers, - - use \ResetPatternCodes - - makedoc.pdf 2010/03/30 updated, fixed - - makedoc.cfg 2010/03/29 unchanged - - makedoc.tpl 2010/03/23 unchanged - - mdoccheat.pdf 2010/03/30 updated, renamed mdoccheat.tex - - mdoccorr.cfg 2010/03/29 uses new fifinddo commands - - - -- niceverb.sty v0.4 2010/03/29 auto mode: \AddToNoVerbList, - - safer restoring of underscore - - niceverb.pdf 2010/03/29 updated - - - -- arseneau.tex 2010/03/30 first CTAN release - - arseneau.pdf 2010/03/30 first CTAN release - - sample.txt 2010/03/22 unchanged - - substr.tex 2010/03/30 extended formatting by specific - - replacments using new fifinddo - - commands; corrections - - substr.pdf 2010/03/30 first CTAN release - - - -______________________________________________________________________ - -nicetext RELEASE v0.3 2010/03/23 SUMMARY: `makedoc' simplified, - - `niceverb' robustified, - - `fifinddo' re-implemented - - & slightly enhanced, - - txt to TeX dialogue & templates - - - -- FILES 2010/03/23 first CTAN release - - README 2010/03/23 updated - - CHANGE.LOG 2010/03/23 updated - - NNOUNCE.TXT 2010/03/23 updated - - - -- fifinddo.sty v0.31 2010/03/23 replacement chaining improved: - - \PrependExpandableAllReplacer; - - works with character codes > 127; - - setup-setup unified - - fifinddo.pdf 2010/03/23 updated - - fdtxttex.tex 2010/03/22 first CTAN release - - fdtxttex.tpl 2010/03/23 first CTAN release - - mkfddoc.tex removed - - - -- makedoc.sty v0.3 2010/03/19 bundling to standalone commands - - makedoc.pdf 2010/03/23 updated & much extended - - (list of script commands) - - makedoc.cfg 2010/03/20 no longer essential - - makedoc.tpl 2010/03/23 first CTAN release - - mdoccheat.pdf 2010/03/21 first CTAN release - - mdoccorr.cfg 2010/03/23 replaces `mdcorr.cfg', uses - - \Prepend... - - - -- niceverb.sty v0.32 2010/03/23 robustified, incl. - - `hyperref' compatibility - - & dis-/re-enabling - - niceverb.pdf 2010/03/23 much extended - - - -- sample.txt 2010/03/22 first CTAN release - - substr.tex 2010/03/18 first CTAN release - - - -______________________________________________________________________ - -nicetext RELEASE 0.2 2009/04/15 add `fifinddo' and `makedoc' for - - txt -> latex preprocessing - - - -- README 2009/04/15 updated - - CHANGE.LOG 2009/04/15 new - - - -- fifinddo.sty v0.3 2009/04/15 first CTAN release - - fifinddo.pdf 2009/04/15 - - mkfddoc.tex 2009/04/15 - - - -- makedoc.sty v0.2 2009/04/13 first CTAN release - - makedoc.pdf 2009/04/15 - - makedoc.cfg 2009/04/15 - - mdcorr.cfg 2009/04/15 - - - -- niceverb.sty v0.2 2009/04/15 strengthened \SimpleVerb, - - \sf detection after `(', - - more for \niceverbNoVerList - - niceverb.pdf 2009/04/15 adjusted to new doc generation - - method, mentioning it, - - motivation extended, - - more examples - - - -______________________________________________________________________ - -nicetext RELEASE 0.1 2009/02/23: first CTAN releases of - - `niceverb' and `wiki' - - - -- niceverb.sty v0.1 2009/02/21 - - niceverb.pdf 2009/02/23 - - - -- wiki.sty v0.2 2008/07/02 - - wikicheat.pdf 2009/01/17 - diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt b/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt deleted file mode 100644 index 3c3da46d584..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/doc/NNOUNCE.txt +++ /dev/null @@ -1,48 +0,0 @@ -`makedoc' + `niceverb' - an alternative documentation system for LaTeX - ----------------------------------------------------------------------- - -Step 2 of txt to TeX processing of third-party package documentations - -====================================================================== - -New with release 0.4: - - - -* Additionally to the `%% ' commenting style (allowing - - "commenting out") the usual `% ' commenting style is supported -- - - applied to packages by Donald Arseneau, see abstract in - - `arseneau.pdf'. - - - -* Extended formatting of Harald Harder's `substr.sty' through specific - - preprocessing replacements (\MakeDocCorrectHook) -- see abstract in - - `substr.pdf'. - - - -* Setup of \MakeDocCorrectHook (txt to TeX) easier with - - \SetPatternCodes, \ResetPatternCodes, \SetCorrectHookJob, - - \SetCorrectHookJobLast - - - - - - - - - - - - - diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt b/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt deleted file mode 100644 index 26cb5fab553..00000000000 --- a/Master/texmf-dist/doc/latex/nicetext/doc/RELEAS03.txt +++ /dev/null @@ -1,95 +0,0 @@ -`makedoc' + `niceverb' - an alternative documentation system for LaTeX - -====================================================================== - -The `nicetext' bundle offers "minimal" markup syntax for restricted - -kinds of text: There should not be much more characters typed than - -printed! -- mainly: quick documentation of (smaller) LaTeX packages - --- achieved by active characters and preprocessing similar to - -`docstrip' ("opposite direction" however, incl. some txt to TeX). - - - -New with release 0.3: - - - -* `substr.tex' should typeset LaTeX quality documentation from - - next available (on your install) substry.sty's ASCII/UTF-8 input - - (works with me) -- first application of `niceverb''s "auto mode" - - and `makedoc.sty' to a third-party package! - - - -* `makedoc' simplified: single - - - - \MakeInputJobDoc[][]{
}{} - - - - generates a documentation file from the package file and - - typesets it immediately (kind of \DocInput equivalent) - - -- see `Using makedoc the simplest way' in `makedoc.pdf' - - - -* `|...|' from `niceverb' typesets an inline frame box for setting-off - - a command description, modifiable by hooks (e.g., \colorbox) - - - -* `niceverb' syntax works in page headers, PDF bookmarks, and - - `hyperref' labels and otherwise much better than before, - - dis-/re-enableable featurewise as well as altogether - - - -* documentation extended, lists of script commands - - - -* configurable txt to TeX functionality or other replacements like - - ASCII-arrows to arrow commands or inserting \index entries - - (setting up expandable replacement chains slightly more comfortable) - - -- try with templates and dialogue - - - -* `fifinddo' works with character codes > 127, improved setup - - - -* `makedoc' requires the `moreverb' package. - - - -______________________________________________________________________ - -CATALOGUE: These packages may be compared with: - -* easylatex, txt2latex, txt2tex - - (typographical and TeX input enhancement); - -* doc, gmdoc, lineno (awk in place of \DocInput); - -* substr, datatool, ted, xstring, stringstrings, makematch, ... - - (parsing) \ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf deleted file mode 100644 index 6a209273e90..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/doc/fifinddo.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf deleted file mode 100644 index 8c9a8d1753e..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/doc/makedoc.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf deleted file mode 100644 index 2a34ce5492d..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/doc/mdoccheat.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf deleted file mode 100644 index 3aa00be21ef..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/doc/niceverb.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf deleted file mode 100644 index 2b915d38155..00000000000 Binary files a/Master/texmf-dist/doc/latex/nicetext/doc/wikicheat.pdf and /dev/null differ 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 - `` occurs in " test. More packages seem to use - this idea for extracting file informations, like - 'texshade'.\footnote{\url{http://ctan.org/pkg/texshade}} - - - However, such packages don't make much ado about parsing, - there seems to be no general setup mechanism as are presented by - 'fifinddo'. Indeed, tayloring parsing macros to specific applications - may often be more efficient than a general approach. - - \subsection{Useful for \dots} - My main application of 'fifinddo' at present is typesetting - documentations of packages using 'makedoc' which removes certain - percent marks and inserts listing commands, so you edit a package file - with as little documentation markup as possible. - This may be extended to other kinds of documents as an alternative - to 'easylatex' or 'wiki' (the approach of which is dangerous and - incompatible with certain other things). - - I have used a similar own package 'txtproc' successfully, - where more features were implemented for practical purposes - than are here so far, yet I don't like its implementation, want to - improve it here. This package also \emph{created batch files}, e.g., - to remove temporary files. - This could be used for package handling: - typset the documentation at the desired place in the tree, - write the packages to another, write a batch file to remove - files that are not needed any more after installation - (cf.\ 'make'). %%% !? cf. Wiki `Make (software) 2009/04/11 - - I used 'txtproc' also for \emph{large-scale substitutions} - (it had been decided to change the orthography in a part of a book). - Other large-scale substitutions may be: - \begin{itemize} - \item inserting &\index commands; - \item inserting (soft) hyphenation commands near accents; - \item manual umlaut-conversion.\footnote{If you know the ``names" - of the encodings, Heiko Oberdiek's - \ctanpkgref{stringenc} - may be preferable.} - \item typographical (or even orthographical) corrections (same mistake - many times on each of hundreds of pages). - You may turn `...' into `$\dots$' and `etc.' into `etc.\' - etc.\footnote{But what when a new sentence is starting indeed? - Well, `cf.' is an easier example.---`etc.' even showed - a problem in 'niceverb'. 'mdoccorr.cfg' replaces `etc. ' - only, so you can keep the extra space by a code line break.} - This could replace packages like - 'easylatex',\footnote{\url{http://ctan.org/pkg/easylatex}} - 'txt2latex',\footnote{\url{http://ctan.org/pkg/txt2latex}} - 'txt2tex'\footnote{\url{http://ctan.org/pkg/txt2tex}} - in a customizable way, using, e.g., the ``correct" - hook from 'makedoc.sty' as exemplified in 'mdoccorr.cfg' - (see examples section of 'makedoc.pdf'). - You should find 'fdtxttex.tpl', a 'fifinddo' script - to try or apply `\MakeDocCorrectHook' from 'mdoccorr.cfg', - as well as 'fdtxttex.tex' that runs a dialogue for the - same purpose if you can manage to run it ('WinShell'?). - You can then try to create your own `\MakeDocCorrectHook'. - Section~\ref{sec:replchain} provides setup for macros - of this kind. - \item as to 'easylatex' again, \emph{lists} could be detected and - transformed into \LaTeX\ list commands. This could re-implement - the lists functionality of 'wiki.sty' that is somewhat - dangerous. %% TODO 2009/04/15 - \item introduce your own \emph{shorthands} to be expanded not as \TeX\ macros, - but by text substitution; - \end{itemize} - %% % <- TODO present macros/"jobs" doing this. - %% %% <- TOOD single quote tests could be used for - %% double quote character as well - %% to turn it into left quotes if ... 2010/03/19 - % - In certain cases, insertions deteriorate readability, hyphenation - corrections even make text search difficult. - It is therefore suggested to - \begin{enumerate} - \item keep editing the file without the insertions, - \item run the script (commands based on 'fifinddo') for insertions - in the preamble of the main file - (```\jobname.tex'", maybe &\input the script file) and - \item &\input the result file within the `document' environment. - \end{enumerate} - - In general, differences to ``manual" replacing by the substitution - function of your \emph{text editor} is that - \begin{itemize} - \item you first keep the original version, - \item you can check the resulting file before you replace the original - file by it, - \item you can store the replacement script in order to check for - mistakes at a later stage of your work, - \item you can do \emph{all} the replacements in \emph{one run} - (by \emph{one} script to check for mistakes), - \item you can store replacement scripts for future applications, - so you needn't type the patterns and replacement strings anew. - \end{itemize} - - - \subsubsection{Comparisons} %% was `Missing' 2010/03/18 - % \subsection{To implement or not to implement \dots} %% TODO!? 2009/04/13 - % Actually, 'fifinddo' doesn't implement very much, and this possibly - % won't change, even if I am lucky. ``Practical applications" tend to - % show (in my view) that there is a very complex space of possibilities - % what parsing macros could do. If I try to ``attack" 'Perl' or so, - % cf.\ 'CPAN'\@. If I am lucky and become famous, 'fifinddo' will get many - % extensions in separate packages, cf.\ 'pstricks'. I also like it when - % you can choose among packages for similar purposes, and this may apply - % to extensions of 'fifinddo' as well. - % - % What \emph{really} is missing very badly at present is matching - % \emph{sequences} of strings. However, 'makedoc' contains a practical - % application of this for the case that both strings appear \emph{in the same - % line}. A better algorithm would have to read more lines from the input - % file etc. - % - % As it just comes to my frightened mind, there is even a problem with - % ``strings"/``patterns" that are \emph{phrases} of words, containing - % spaces \dots - % - % Clearly much comfort concerning \emph{routine} jobs is missing now, - % 'txtproc' has more. Please sponsor (or otherwise support) the work for - % improving this. - % - It should be noted (perhaps here) that the present approach to parsing - is a quite \emph{simple} one and in this respect much different to the - string handling mechanisms of - 'stringstrings',\footnote{\url{http://ctan.org/pkg/stringstrings}} - 'ted',\footnote{\url{http://ctan.org/pkg/ted}} - 'xstrings'\footnote{\url{http://ctan.org/pkg/xstrings}} - (as I understand them, perhaps also - 'coolstr'\footnote{\url{http://ctan.org/pkg/coolstr}}) - which are \emph{much more powerful} than what is offered here---but - perhaps slow and for practical applications possibly replaceable by - the present approach. - \emph{Expandable replacement} seems not to exist outside 'fifinddo' - (2009/04/13). - - Much is missing, I know.\footnote{There - is more in my badly implemented 'txtproc.sty'.} - I am just implementing what I actually need - and what could show that this approach is worth being pursued. - %% removed 2010/03/18: - % It may need being sponsored or otherwise supported. - - \subsection{For insiders} - - \emph{Warning:} You may (at least at the present state of the work) - have little success with this package, if you don't know about - \TeX's category codes and how \TeX\ macros are defined. - The package rather provides tools for package writers. - You may, however, be able to run other packages which just load - 'fifinddo' as required background. - - That 'fifinddo' acts on ``\TeX(t)" files or so means that - (at present) I think of applications on ``plain text" files which - will usually be \TeX\ input files. ``At present" they are read - without ``special characters," so essentially category codes of input - characters are either 11 (``letter") or 12 (``other"). - This way some things are easier than with usual \TeX\ applications: - \begin{enumerate} - \item You can ``look into" curly braces and ``behind" comment characters. - \item There are exact or safe tests especially of \emph{empty macro arguments} - that are ``expandable," i.e., they are ``robust," - don't need assignments, can be executed in `\write'ing and in - `\edef' definitions. ``Usually," the safe way to test emptiness - is storing a macro argument as a macro, say `\tempo', in order - to test `\ifx\tempo\empty' where `\empty' has been defined - by `\def\empty{}' in the format. But this requires some - `\def\tempo{#}' which breaks in ``mere expanding" - (\TeX\ \emph{evaluates} `\tempo' instead of defining it). - An \emph{expandable} test on emptiness is, e.g. `\ifx$#$', - where we hope that it becomes `\iftrue' just if macro argument - `#' is empty indeed. However, ``usually" it may \emph{also} - become `\iftrue' when `#' starts with `$'---if the latter - has category code 3 (``math shift"). But 'fifinddo' does - not assign category code 3 to any character from the input file! - Therefore `\ifx$#$' is `\iftrue' \emph{exactly} if `#' is - empty. - \item You can avoid interference with packages that are needed for - typesetting. You can do the ``preprocessing" in one run with - typesetting, but you should do the preprocessing before you - load packages needed for typesetting. One may even try to keep - the macros and settings for preprocessing local to a group. - \end{enumerate} - % - Once there may be an option to read input with some usual \TeX\ - category codes as well, it may be useful to (some of) - \begin{itemize} - \item avoid matching substrings of control words, - \item skip blank spaces as \TeX\ does it usually, - \item catch \emph{balanced} input pieces, - \item ignore comments, - \item ignore certain characters. - \end{itemize} - - The essential approach of 'fifinddo' to looking for single strings is - described in some detail in section~\ref{sec:theory}. - - The implementation of 'fifinddo' is as follows. - User commands are specially highlighted (boxed\slash coloured), - together with their syntax description. - - % \end{document} - - \section{Preliminaries} - \subsection{Head of file (Legalese)} - \sloppy - \ProcessLineMessage{} - \MakeInputJobDoc{23}{\SectionLevelTwoParseInput} - \end{document} - - TODO cf. Kastrup 'makematch' and others 2009/04/09 - - 2009/04/10: title break, by -> with(!?); `boxed/coloured' - 2009/04/12: useful: own shorthands - 2009/04/13: substr.sty, \emph{expandable}, w/o `implement'!? - 2009/04/15: same with \in@ - 2010/03/08: EPS application removed - 2010/03/17: use \MakeInputJobDoc - 2010/03/18: `Missing' -> `Comparisons' etc.; \Require... - 2010/03/19: Catalogue \url; '' -> " - 2010/03/20: \ctanpkgref - 2010/03/22: debugging; done ... - 2010/03/23: more URLs; abstract "then shared"; - removed dates from 2009, fdtxttex.tex/tpl - diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg b/Master/texmf-dist/doc/latex/nicetext/docsrc/makedoc.cfg 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' to get around - % \string\label\space issues! ***^^J} - % \errorcontextlines=0 - % \show\reserved@a - % \expandafter \show \csname #1@#2\endcsname - % \fi - % } - % \makeatother - \begin{document} - \title{'makedoc'---Preprocessing documentation by \TeX} - %% 2009/04/10: \\---\\\ breaks TOC - \maketitle - \begin{abstract}\noindent - 'makedoc' provides commands for generating \LaTeX\ input from a - package file in order to typeset the latter's documentation - (somewhat similar and opposite to 'docstrip')---with - v0.3 \emph{a single one usually suffices}. - Certain comment marks are removed, listing commands are inserted, - and some (configurable) typographical `txt'$\to$\TeX\ corrections - are applied.---This - continues the policy of 'niceverb' to minimize documentation markup in - package files. 'makedoc' extends and exemplifies the parsing package - 'fifinddo'. After an edit (and test) of your package, you get the new - documentation in one run (or the usual number of runs) of the - documentation driver file.---The present approach is meant to be an - \emph{alternative} to the standard 'doc' package and its `\DocInput'. - It provides \emph{less} than 'doc' does, rather deliberately. It may - be helpful at least for the development of small packages, or at least - at early stages. - \end{abstract} - \tableofcontents - \section{Introduction} - \emph{The abstract will not be repeated in this section.} Let me add - instead that I was in dire need of such a package, I got stuck with my - packages because I lost orientation in them, and I was unhappy with - the forms of documentations of my other packages, and documenting them - with the standard \LaTeX\ 'doc' system was not attractive for me - (neither considered helpful). %% clarified 2010/03/13 - I also worked on \emph{Windows} until September 2008, and I - find a system like the present one still more attractive then using - (learning!\@) other filtering utilities (see below on 'awk'). And I - may work on \emph{Windows} once again and don't want to depend on - installing some $\dots$ there---\emph{I really would like to have - powerful tools for everything depending on nothing but \TeX\slash - \LaTeX!} - - \section{Prior work and what is new} - It is, of course, not a new idea to get around comment marks `%' to - typeset the documentation. 'doc''s `\DocInput' does this by making `%' - an ``ignored" character. This way you cannot use `%' for commenting - comments (so 'doc' offers a ``new comment mark" - `^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!? - You also cannot use `%' for commenting out code (that you are - pondering---or using for debugging---only). %% clarified 2010/03/13 - - Moreover, 'doc' requires enclosing package code explicitly by - environment commands (behind comment marks). Stephan I. B\"ottcher - with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}' - and Grzegorz Murzynowski in \ctanpkgref{gmdoc} - aimed at doing away with this requirement. - 'lineno.sty' contains 'awk' scripts - to remove starting comment marks and to insert listing commands. - A file 'lineno.tex' is generated that typesets the documentation. - By the way, 'lineno.sty' is full of discussions, but it is not - 'docstrip'ped---the maintainers never have received a complaint - that inputting 'lineno.sty' were too slow. - - 'gmdoc' seems to get around comment marks and insert listing commands - \emph{while typesetting} by a refined version of `\DocInput', - through some careful detecting and analysing comment marks, - the approach resembles detection of lists in 'wiki.sty'.\footnote{See - 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages - document! I also find - \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.} - And this is a matter of principles---comparing the approaches of - \emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"} - ('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler, - sometimes detecting while typesetting. - (Another example is the preprocessor - \ctanpkgref{easylatex} - of which 'wiki.sty' is a much reduced ``while typesetting" variant.) - ``While typesetting" may be easier when single characters or - sequences of two or three encode markup - information---but such detection can badly interfere with other - packages etc. ``Preprocessing" may be easier when entire ``strings" - of characters decide, which may be anywhere in a file line. - - 'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by - \emph{\TeX}. There is a general discussion of this choice in the - documentation of 'fifinddo'. Preprocessing here can be done in the - same \LaTeX\ run as typesetting, though you can avoid - incompatabilities with packages needed for typesetting - (by inputting them only \emph{after} preprocessing). - - 'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be - preferable to preprocessing with other utilities: - When I took over maintenance of 'lineno.sty', - I needed hard work to get the 'awk' script running. - The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel} - 'awk' (I chose a Munich 'nawk' and reworked the script a little). - \TeX\ seems to have better fixed functionality than other utilities! - - A different alternative to \LaTeX's 'doc' system is - Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}' - where the code environments extract package code in typesetting the - documentation. %% added 2010/03/10 - - \section{Styles supported (parsers provided)}\label{sec:styles} - % \section{Styles of commenting '.sty's} - We find different styles of documenting \LaTeX\ packages. - As the main aspects I consider - (i)~\emph{telling code from comments} - and (ii)~\emph{markup in comments}. - (You may find more details on the next matters in the - ``implementation" section.) - - \subsection{Telling code from comments} - \emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX) - probably were named so to mark \emph{``comments"} as opposed - to code $\dots$ great, but actually, in ``daily practice," - they are so handy---and used---for ``commenting out" \emph{code}, - i.e., \emph{managing code versions} in a simple way: - one does not actually want to \emph{delete} code, - one might want to use it another time, maybe for debugging - $\dots$ or to remind of earlier attempts that should not be tried - again $\dots$ - - This is a problem for \emph{high-quality typesetting} of - documentation. \emph{Code} should be typeset about as you see it on - the \emph{screen}---\emph{monospaced}, this allows structuring by - indenting, it is common practice to use a typewriter typeface for - this. Real \emph{comments} should be typeset in \emph{high quality} as - usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden - code"} (``commented-out"). A comment mark starts the line, but - obviously it is not really a comment and rather should be typeset - like code (and otherwise they may break). %% 2010/03/22 - Another problem are comments at the \emph{end} of a - \emph{code} line. Sometimes they are ``real comments" ('gmdoc' - supports this style). But sometimes - this is only another version of ``version management," code - ``commented-out." - - I like the style of writing packages described before and use it all - the time. I mark ``real comments" with \emph{two} adjacent comment - marks and an ensuing space to distinguish them clearly from code - commented out. - %% Adapted to v0.4 2010/03/29: - \emph{This style is presently the one supported by \textup{'makedoc'} - as default.} - This way only a line starting with - |%% | is considered a ``real" comment line. The first three - characters are removed, and the rest is typeset in high quality. - Any other lines are typeset verbatim. The 'makedoc' \emph{parser} - doing this has an ``identifier" |PPScomment| (``percent, percent, - space"). Another identifier |comment| is a placeholder for - the comment parser to be used, by default it is an alias for - `PPScomment'. Lines just containing |%%| (without the space) may be - used to suppress empty code lines preceding section titles and for - keeping some visual, relieving space between code and comment lines. - - The style I described previously may be considered ``unprofessional." - The many \LaTeX\ packages documented using the 'doc'\slash'.dtx' - system don't use comment marks for \emph{``commenting-out"}. - Or one may mark code commented out by putting no space between the - percent mark and the code. - With v0.4 of 'makedoc', this style is supported as |PScomment|. - You can directly call this as as described below, - or you can switch to it by - \[`\CopyFDconditionFromTo{PScomment}{comment}'\] - - \subsection{Markup in comments} - Packages using the 'doc'\slash '.dtx' system as well as alternative - highly developed systems mentioned above use (enhanced) usual - \emph{\LaTeX} syntax for markup of comments. Other packages just use - an \emph{ASCII} style \emph{without} any markup. My idea was to - support the latter style by some `txt'$\to$\LaTeX\ functionality. - 'makedoc' does this using a file 'mdoccorr.cfg' which is very small - right now. - - I also thought of introducing another sort of ``decent" markup not - needing much more space than the ``ASCII kernel" of the comments. - This is to some extent implemented in 'niceverb.sty'. I thought of the - syntax of editing \textit{Wikipedia} pages; this is partially - implemented in 'wiki.sty' which unfortunately is not yet compatible - with 'niceverb'. - - But 'makedoc' implements one \textit{Wikipedia} feature in a different - way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows: - \begin{eqnarray*} - \endcell\endcell`%% == Section =='\\ - \endcell\endcell`%% === Subsection ==='\\ - \endcell\endcell`%% ==== Subsubsection ====' - \end{eqnarray*} - i.e., you type `== ==' in place of `\section{<title>}' etc. - The parser must replace `====<title3>===' before `===<title2>===' and - the latter before `==<title1>=='. In fact, 'makedoc' provides three - parsers for these situations: - \begin{description} - \cmdboxitem|\SectionLevelThreeParseInput| is the most general parser - offered. If it does not find two strings \lq`===='\rq\ enclosing - \emph{something}, it passes to - \cmdboxitem|\SectionLevelTwoParseInput| which unless finding - two strings `===' enclosing something passes to - \cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment - detector |comment|. - \end{description} - - - \section{Requirements} - 'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand' - etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same - directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the - \LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it - should be installed anyway, or you can get its latest version - (v2.3, 2008/06/03?) from CTAN. - - 'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file - 'mdoccorr.cfg' that should have come along with 'makedoc.sty' and - 'fifinddo.sty'. You may need to have a modified copy of it in the - directory of your main `.tex' file `<jobname>.tex' fitting special - needs of your project. - - \section{Using 'makedoc' the simplest way} - In the most simple case, you are preparing documentation for a package - file `<jobname>.sty' only, and you prepare a file `<jobname>.tex' - containing - \[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\] - and `\maketitle' etc.\ about your package.\footnote{With 'niceverb' - and &\title\ after &\begin{document}, you may replace - \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.} - The documentation will be produced by running `<jobname>.tex' with - \LaTeX\ (e.g., \texttt{latex <jobname>.tex}). - - First, `<jobname>.tex' must have |\usepackage{makedoc}| in its preamble. - There are no package options. - - Second, to typeset the commented implementation from `<jobname>.sty', - include in <jobname>.tex's `document' environment a line - \[|\MakeInputJobDoc{<header-lines>}{\SectionLevelThreeParseInput}|\] - <header-lines> refers to a non-negative integer as follows: - We think the most simple and useful way of typesetting the first lines - of a package file including license and copyrights is ``depicting them - as image," i.e., \textit{verbatim}. We could try to determine the - number of these lines by parsing, but we won't do so soon. Please just - count them and enter the number as <header-lines>---and change it - until you can accept the outcome. - - \section{Steps of advanced usage} - \subsection{Different main parsers (second mandatory argument)} - - `\MakeInputJobDoc''s mandatory syntax actually is - \[|\MakeInputJobDoc{<header-lines>}{<main-parser>}|\] - <main-parser> refers to the parsing macro that is applied to each - input line whose number is greater than <header-lines>. - Examples for <main-parser> are named in section~\ref{sec:styles} above. - %% TODO above/below macro 2010/03/15 - `\SectionLevelThreeParseInput' is just the most general one. - For \emph{efficiency} (!? or also to avoid problems?) you may - replace `Three' by `Two' or by `One', if the `====' or the `===' - feature is not used in `<jobname>.sty'. If the ``\textit{Wikipedia} - sectioning" feature is not used at all, use - \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{comment}}|\] - ---provided you want to adopt the \lq`%% '\rq\ style of marking - comments, cf.~section~\ref{sec:styles}. For the \lq`% '\rq style - instead, use - \[|\MakeInputJobDoc{<header-lines>}{\ProcessInputWith{PScomment}}|\] - - \subsection{Different extensions (optional arguments)} - If your package to be documented is a \emph{class} `<jobname>.cls', - a local configuration file `<jobname>.cfg' or something - else---<jobname>.<ext-in>, e.g., <ext-in>=`cls' or <ext-in>=`cfg', - use - \[|\MakeInputJobDoc[<ext-in>]{<header>}{<parser>}|\] - Moreover, `\MakeInputJobDoc' writes an intermediate file - `<jobname>.doc' and then `\input's it. If you do not like `doc' - as extension for the written file name (maybe you use - `<jobname>.doc' for something different already), preferring extension - <ext-out>, use - \[|\MakeInputJobDoc[<ext-in>][<ext-out>]{<header>}{<parser>}|\] - Yes, you must state <ext-in> then as well, I can't help $\dots$ - - If even <jobname> is wrong in your view, see next step $\dots$ - - \subsection{Commands modifying &\MakeInputJobDoc's behaviour} - \label{sec:modimake} - Already <jobname> may not be what you want. E.g., you may want - to collect documentations of some other files <job-1>, <job-2>, - $\dots$ in a single <jobname>. Then precede `\MakeInputJobDoc' - with - \[`\renewcommand*{\mdJobName}{<job-1>}'\] - etc.\ (please reason yourself about additional requirements \dots) - As a matter of fact, `\MakeInputJobDoc' reads - \[`\mdJobName.<ext-in>' \mbox{\quad and writes\quad} - `\mdJobName.<ext-out>'\] - Stated another way, <jobname> above referred to |\mdJobName|. - - `\MakeInputJobInput' moreover (by default) produces one dot - per input line processed on screen to show progress. - The reason is that `makedoc' issues the command - |\ProcessLineMessage{\message{.}}|. - Already this trivial thing seems to slow down processing considerably - (nowadays). `\MakeInputJobInput' will run faster if preceded by - \[|\ProcessLineMessage{}|\] - which will suppress any message about processing. - However, the message may be helpful in trouble-shooting. - - \subsection{Separating preprocessing from typesetting} - %% extended 2010/03/16 - To some surprise, I observe that `\MakeInputJobDoc' \emph{works.} - This is quite a new discovery of mine (2010/03/13); - before I thought that, for safety, preprocessing should happen - inside a local group \emph{preceding} `\documentclass'. - |\MakeJobDoc| works like `\MakeInputJobDoc' described above, - yet it just \emph{preprocesses} the package to be documented, - waiting for an - \[`\input{<jobname>.<ext-out>}'\] - in the `document' environment to \emph{typeset} the documentation. - So 'makedoc.tex' once had in its preamble - % \[`{\RequirePackage{makedoc} \MakeJobDoc{<header>}{<parser>}}'\] - % at the top of `<jobname>.tex' and `\input{<jobname>.<out-ext>}' later. - \begin{eqnarray*}\endcell\endcell - `{\RequirePackage{makedoc}'\cr \endcell\endcell - ` \ProcessLineMessage{}'\cr \endcell\endcell - ` \MakeJobDoc{22}{\ProcessInputWith{comment}}}'\cr - \endcell\endcell - `\documentclass{article}' - \end{eqnarray*} - I did experience some truth in my earlier safety policy: - With 'niceverb' ``running," `\MakeJobDoc' cannot (easily) be used - in the `document' environment. `\MakeInputJobDoc' in fact does some - 'niceverb' switching (provided 'niceverb' has been loaded) - when making use of `\MakeJobDoc'. - %% <- verbose to improve line breaks 2010/03/16 - - Thinking of this ``safety" approach, especially grouping (`{\code}'), - I had not much cared for compatibility with other packages - in choosing 'makedoc' macro names. - - \subsection{Other 'makedoc' (and 'fifindo') script commands} - The next script commands may be considered of a lower level than - `\MakeJobDoc' and `\MakeInputJobDoc', they underlie the latter - commands. We also list commands from 'fifinddo.sty' that may be useful - or, indeed, are needed for preparing package documentations. - This may result in ideas on how do use the script commands for - different purposes than for preparing package documentations---e.g., - apply `txt'$\to$\TeX\ preprocessing to arbitrary text files. - - \subsubsection{Choosing parameter values for next preprocessing run} - - This actually continues section~\ref{sec:modimake}. - - \begin{description} - \cmdboxitem|\ResultFile{<output>}| (from 'fifinddo') - determines (and opens through the \TeX\ primitive `\openout') - the file <output> which will contain the result of - preprocessing the package file. - \cmdboxitem|\LaTeXresultFile{<output>}|---see next section. - \cmdboxitem|\Headerlines{<number>}| determines the <number> of lines - starting the input file to be copied \emph{verbatim} - (the first mandatory argument of `\MakeJobDoc'). - \cmdboxitem|\MainDocParser{<parser>}| determines the <parser> - as in the \emph{second} mandatory argument of `\MakeJobDoc'. - \end{description} - - We are now describing some parameters which rather must be switched - ``manually" instead of being modifiable by comfortable 'makedoc' - script commands. - - With the \emph{``Wikipedia sectioning"} feature, you may change the outcome - regarding levels. Assume, e.g., the package file has titles along the - scheme `== <title> ==' only, but these should become - \emph{subsections} of the ``implementation" section of the - corresponding `.tex' file. Then - \[`\renewcommand*{\mdSectionLevelOne}{\string\subsection}'\] - -- see the implementation of the sectioning feature for details. - - There is a command - \[|\NoEmptyInputLines| \mbox{\quad and a parameter macro\quad} - |\OnEmptyInputLine|\] - which is modified by the former. However, I cannot say much about them - right now, I think they just were a difficult matter that I soon - decided no longer to think about for a while (cf.\ the - implementation). About the same holds for the hook |\EveryComment|. - - The `txt'$\to$\TeX\ functionality is implemented through a hook - \[|\MakeDocCorrectHook{<characters>}|\] - 'makedoc' initializes it as an alias of \LaTeX's `\@firstofone', i.e., - it won't change <characters>. 'mdoccorr.cfg' should redefine it so it - really ``corrects" <characters>. You might try other definitions of - `\MakeDocCorrectHook' for different ``correcting" functions. - It should be \emph{noted} that (currently) - `\MakeDocCorrectHook' must be \emph{expandable}, 'fifinddo.sty' - provides setup for (expandable) chains of expandable replacements. - The ``Wikipedia" sectioning feature moreover uses expandable - trimming (single) surrounding spaces, this might be provided in a more - general way.\footnote{%% TODO 2010/03/16 - The \ctanpkgref{trimspaces} package - has been a \emph{model} for this feature here. It cannot be used - directly here because it reads blank spaces as \TeX\ characters with - category code 10 while 'makedoc' reads blank spaces as ``other" - characters (category code 12) in order to \emph{keep} all blank spaces.} - - \subsubsection{``Manual" insertions to the output file} - \begin{description} - \cmdboxitem|\WriteResult{<balanced>}| (from 'fifinddo') writes - <balanced> to <output> according to the earlier command - `\ResultFile{<output>}'. - \cmdboxitem|\WriteProvides| (from 'fifindo') writes a - `\ProvidesFile' line into <output> that declares the file - to be generated by 'fifindo'. - \cmdboxitem|\LaTeXresultFile{<output>}| issues - `\ResultFile{<output>}' and then writes a - `\ProvidesFile' line into <output> that declares the file - to be generated by 'makedoc'. - \end{description} - - \subsubsection{Processing input and closing output} - \begin{description} - \cmdboxitem|\MakeDoc{<input>}|\hskip 0pt plus 4em - reads 'mdoccorr.cfg' - (for `\MakeDocCorrectHook', see above), - %% removed \LaTeXresult... 2010/03/17 - copies <number> according to `\HeaderLines' (see above) - from <input> into <output> (according to `\ResultFile'), - then processes the remaining lines of <input> according - to `\MainDocParser' (writing several things to <output>). - `\MakeDoc' invokes{\sloppy\par} - \cmdboxitem|\ProcessFileWith{<input>}{<loop-body>}| - (from 'fifindo') reads <input> line by line---each one stored as - macro |\fdInputLine| and applies <loop-body> to it. - \TeX's ``special" character codes (of characters listed in - macro `\dospecials') are replaced by 12 (``other") by - default---see the 'fifinddo' documentation. - \cmdboxitem|\CloseResultFile| (from 'fifinddo') - \hskip 0pt plus 1em - \emph{closes} - <output> (using \TeX's primitive `\closeout'). - \cmdboxitem|\MakeCloseDoc{<input>}| issues - `\MakeDoc{<input>}\CloseResultFile'. - \end{description} - % - Using `\MakeDoc' \emph{instead} of `\MakeCloseDoc' allows processing - additional <input> files writing into the same <output>. Or maybe you - want to add some additional lines manually to <output> using - `\WriteResult'. - - %% removed 2010/03/09: - % At least in the long run, using 'makedoc' should not imply commitment - % to a certain design or to certain \LaTeX\ packages for typesetting - % listings and documentations. Therefore, 'makedoc.cfg' (currently) - % contains \emph{local} or \emph{personal choices}, but also - % \emph{experiments} with future features of 'niceverb'. - % Especially, (at present) the `packagecode' - % environment that 'makedoc' `\write's must be chosen. - % Currently this is the `listing' environment from 'moreverb' - % with some modifications or extra settings. - % It may be vital to `\MakeOther' the active characters from 'niceverb' - % in the setup of `packagecode'. See the \emph{example} in - % section~\ref{sec:fifinddo}. - % - % Finally, - % Each package file to be typeset needs its own little - % \emph{script} of 'makedoc' commands. - % With v0.3, one or two of these should suffice. - - % It should fit into the preamble - % of the main file for documenting the package (currently %% 2009/04/09 - % just 5 commands seem to suffice, see the \emph{example} in - % section~\ref{sec:fifinddo}). - % The script commands are described - % in the \dqtd{File handling} section of 'fifinddo.pdf' and in the - % present section~\ref{sec:script} (and \ref{sec:emptylines}). - % As an alternative, you may prefer to have ``content only" (as much as - % possible) in the main typesetting file and in its preamble only - % `\input' a separate script file. - %% removed 2010/03/10: - % Yes, the idea of documenting a package \emph{here} is to have a - % separate ``driver" file for typsetting the documentation. - % It may contain an introduction and a guide for users. - % The documentation of the package code that has been prepared by the - % 'makedoc' script will be `\input'. Alternatively, the ``driver file" - % could have title etc.\ only, or preamble and a minimal `document' - % environment only. - % - % So there may be many files, which may look confusing, especially as - % compared with the 'doc' procedure. However, - % \begin{enumerate} - % \item ``One file distribution" still is possible thanks to the - % `filecontents' environment. - % \item The 'makedoc' script can create a batch file (fitting the - % system, maybe using Will Robertson's 'ifplatform', or - % 'texsys.cfg', or \dots) - % that removes certain auxiliary files or moves them to a - % certain directory. - % \item I find it helpful to have rather little ``contentual" text - % in the package file. - % \item The procedure now runs very smoothly, once the stumbling blocks - % have been overcome.\footnote{\hspace{1sp}%% TODO help in 'niceverb'! - % 'niceverb' v0.1 was too sloppy with - % some things, and self-documentation of 'makedoc.sty' was - % difficult---its parsing and that from 'verbatim' cannot - % distinguish between markup code and typeset code.} - % \end{enumerate} - - \section{Examples}%%% (documentation of 'mdoccorr.cfg')} - %% moved here 2010/03/23 - \subsection{'nicetext', especially 'mdoccorr.cfg'} - The documentations of 'fifinddo', 'makedoc', and 'niceverb' - themselves are typeset using 'makedoc'. - 'fifinddo.pdf' documents 'fifinddo.sty', typeset - from 'fifinddo.tex', likewise 'makedoc.pdf' and 'niceverb.pdf'. - % Section~\ref{sec:fifinddo} contains a listing of - % 'makedoc.cfg' and - % the 'makedoc' script file 'mkfddoc.tex' - % especially made for 'fifinddo.pdf'. - % 'fifinddo.doc', 'makedoc.doc', and 'niceverb.doc' are the \TeX\ input - % files that were made with 'makedoc.sty'---I have only looked at them - % when something was wrong (often syntax mistakes in typing). - The Wikipedia syntax feature - \begin{quote} - `%% === subsection ===' - \end{quote} - is used in 'fifinddo.sty' and 'niceverb.sty' only. - - Along with 'makedoc' should come files `makedoc.tpl'---a template - 'makedoc' script, and a file `fdtxttex.tex' that should start a dialogue - on trying `\MakeDocCorrectHook' if you can manage to run it ('WinShell'?). - With other definitions of `\MakeDocCorrectHook'---see below---you can - use this dialogue for arbitrary replacement jobs (as an application of - 'fifinddo' rather than 'makedoc').{\sloppy\par} - - 'fifinddo.pdf', 'makedoc.pdf', and 'niceverb.pdf' were typeset with the following - typographical corrections in 'mdoccorr.cfg' that defines - `\MakeDocCorrectHook': - \strut\hrule - \begingroup - \hfuzz=\textwidth \advance \hfuzz by 28pt - \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< - \listinginput[5]{1}{mdoccorr.cfg} - \endgroup - \hrule\noindent\strut - This code also exemplifies the syntax 'niceverb' provides for writing - about \LaTeX\ macros. It is typeset here with 'makedoc.sty' - and then looks thus: - % \sloppy %% 2010/03/29 - \strut\hrule - \renewcommand*{\mdJobName}{mdoccorr} - \MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}} - \hrule \noindent\strut - And this is the content of the intermediate generated file: - \hrule - \begingroup - \hfuzz=\textwidth \advance \hfuzz by 28pt - \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< - \listinginput[5]{1}{mdoccorr.doc} - \endgroup - \hrule - % \fussy %% 2010/03/29 - - \subsection{Packages from other authors} - `substr.tex' should typeset a nicely formatted documentation - of Harald Har\-der's 'substr.sty', see my own result `substr.pdf'. - 'substr.sty' is a rare case of the \lq`%% '\rq\ commenting style - that 'nicetext' has used itself. - - `arseneau.tex' should typeset nicely formatted documentations - of a few packages by Donald Arseneau, see my own result `arseneau.pdf'. - This demonstrates the usual \lq`% '\rq\ commenting style - that 'makedoc' supports with v0.4. - - \pagebreak %% 2010/03/29 - \ResetCodeLineNumbers %% 2010/03/29 - \section{Implementation} - \subsection{Preliminaries} - Head of file (Legalese): - \sloppy - \renewcommand*{\mdJobName}{makedoc} - \ProcessLineMessage{} - \MakeInputJobDoc{22}{\ProcessInputWith{comment}} - The previous empty code line is the one \TeX\ insists to add at every - end of a file it writes. %% todo TeXbook where? 2009/04/08 - - %% removed (TODO) 2010/03/15: - % \section{Examples: documentation of 'fifinddo'} - % \label{sec:fifinddo} - %% removed 2010/03/10: - % \subsection{'makedoc.cfg'} - % 'fifinddo.pdf' and 'makedoc.pdf' were typeset with the following - % configuration file 'makedoc.cfg': - % \begingroup \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< - % %% <- TODO should be 'niceverb' command 2009/04/08 - % \listinginput[5]{1}{makedoc.cfg} - % \endgroup - % - %% TODO 'niceverb' example---to 'niceverb.tex'!? 2010/03/15 - % \subsection{'mkfddoc.tex'} - % 'fifinddo.pdf' was typeset with the following 'makedoc' script file - % 'mkfddoc.tex': - % \begingroup - % \MakeOther\|\MakeOther\`\MakeOther\'\MakeOther\< - % \listinginput[5]{1}{mkfddoc.tex} - % \endgroup - % - % - \end{document} - - 2009/04/12 more on examples - 2009/04/15 exemplification of niceverb.sty by mdcorr.cfg - 2009/04/21 === subsubsection -> === subsection - 2010/03/08 moved `only' for better line break - 2010/03/09 removed something from "Basics" - 2010/03/10 more changes in "Basics", pdf stuff to makedoc.cfg, - makedoc.cfg no longer example; CodeDoc - 2010/03/11 use \MakeCloseDoc; \hfuzz with \listinginput; - tracing spurious `Label(s) may have changed' - 2010/03/12 tests for hyperref compatibility completed - 2010/03/13 use \MakeInputJobDoc; clarified ...; ctan.org/pkg - 2010/03/14 updated ``Examples" and abstract; \href...easylatex - 2010/03/15 ``styles supported"; abstract: txt->TeX; usage - 2010/03/16 more on usage; mdcorr -> mdoccorr - 2010/03/17 corr. mistake with \MakeDoc - 2010/03/19 '' -> " - 2010/03/20 for niceverb v0.31 - 2010/03/21 for niceverb v0.32 - 2010/03/22 "may break" - 2010/03/23 \noindent in example, moved, added mdoccorr.doc, - makedoc.tpl - 2010/03/29 \ResetCodeLineNumbers, - examples and explanations for v0.4 - 2010/03/30 \listfiles test - diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/mdoccheat.tex 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/fifinddo.pdf b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf new file mode 100644 index 00000000000..b7652e34cba Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/fifinddo.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf new file mode 100644 index 00000000000..eab15048fec Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/makedoc.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf new file mode 100644 index 00000000000..1ead8986302 Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/mdoccheat.pdf differ diff --git a/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf new file mode 100644 index 00000000000..fd2e0bd90c8 Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/niceverb.pdf differ 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/wikicheat.pdf b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf new file mode 100644 index 00000000000..481c7e314d4 Binary files /dev/null and b/Master/texmf-dist/doc/latex/nicetext/wikicheat.pdf differ -- cgit v1.2.3