diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/nicetext |
Initial commit
Diffstat (limited to 'macros/latex/contrib/nicetext')
55 files changed, 7232 insertions, 0 deletions
diff --git a/macros/latex/contrib/nicetext/ANNOUNCE.txt b/macros/latex/contrib/nicetext/ANNOUNCE.txt new file mode 100644 index 0000000000..99ae915868 --- /dev/null +++ b/macros/latex/contrib/nicetext/ANNOUNCE.txt @@ -0,0 +1,6 @@ +nicetext: minimal markup for documentation, text filtering ... +================================================================= +Release 0.67, 2015/11/21: `niceverb.sty' v0.62 fix: + + "new \qtdnverb" was disabled! + diff --git a/macros/latex/contrib/nicetext/README b/macros/latex/contrib/nicetext/README new file mode 100644 index 0000000000..db49e02d30 --- /dev/null +++ b/macros/latex/contrib/nicetext/README @@ -0,0 +1,157 @@ + + README for the NICETEXT bundle + + Minimal Markup for Documenting, Text Filtering, ... + + (c) 2009-2015 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 (clumsy to type ... - "syntactic sugar"). + +Main focus is easy documentation of LaTeX packages. +Preprocessing by Perl or so is replaced by TeX macros +(reviving/generalizing the `docstrip' idea), including +expandable, safe, correct string substitution and typographical +enhancements of plain text for LaTeX input. + + + == Packages == + +`wiki.sty' addresses general kinds of texts. `niceverb.sty' is +made for documenting LaTeX packages. `niceverb.sty' especially +offers [almost-]WYSIWIG for meta-variables (macro arguments) +and for referring to commands (and their syntax) in footnotes, +section titles etc. E.g., to get the syntax description + + \foo[<opt-arg>]{<mand-arg>} +you just type + \foo[<opt-arg>]{<mand-arg>} +!-) + +`fifinddo.sty' provides basic setup for text filtering, +especially string substitution. `makedoc.sty' extends it to +provide a simple script language for transforming plain text +package files into LaTeX input files [manual!?]. One LaTeX run +can perform preprocessing and typesetting. + + + == Comparisons == + +One source of inspiration is the markup syntax of editing +Wikipedia pages. `wiki.sty' of the bundle offers something +similar as a LaTeX front-end for italics, boldface, sectioning, +and certain list-like environments. This is also similar to +`easylatex', + + http://www.ctan.org/pkg/easylatex + +which is more powerful and uses Perl. NICETEXT, by contrast, +consists just of LaTeX packages, working on any TeX +installation [!? note restrictions in `fifinddo.pdf']. +Cf. also preprocessor packages `txt2tex' and `txt2latex'. + +Regarding "self-documentation," there is a difference to +current `\DocInput', similar ideas are in `gmdoc' and +`lineno.sty', see `niceverb.pdf' and `makedoc.pdf'. Standard +`doc.sty' and `contrib' extensions of it are rather avoided. + +There are several *LaTeX macro* packages for processing text or +databases or for editing TeX's input stream while typesetting +-- see `fifinddo.pdf'. What seems to be new here is +*expandable string substitution* and safe, correct detection of +substrings -- discussed in `fifinddo.pdf'. + + + == Documentation == + +`fifinddo.pdf' describes `fifinddo.sty', typeset from +`fifinddo.tex'. `makedoc.pdf' describes `makedoc.sty', typeset +from `makedoc.tex'. `mdoccheat.pdf' is a list of script +commands, typeset from `mdocchea.tex'. `niceverb.pdf' describes +`niceverb.sty', typeset from `niceverb.tex'. Typesetting them +anew (for customizing printout) requires `makedoc.cfg', +`mdoccorr.cfg', and the *.sty files. + +`wikicheat.pdf' is a one-page manual of `wiki.sty'. The file +`wiki.sty' contains additional documentation as plain text. +Note that certain features must be activated by commands in the +document environment. + +`FILEs.txt' describes all the files contained in the bundle in one +line for each. Some descriptions too much for a line: + + * SrcFILEs.txt describes TeX source files (macros, documentation) + together with their most recent version strings and revision + dates. + + * nicetext.RLS summarizes each upload/release in a line or a + little more. With the `typeoutfileinfo' package, the command + line + + typeoutfileinfo nicetext.RLS + + produces a display of the most recent release that has been + installed on your system. `latexfileversion' and `ltxfileinfo' + probably provide a similar feature. + + + == 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'. Running `copyfile.tex', you get a dialogue +for "compressing" blank lines or text encoding conversion. + +`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'. + + + == 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-2012 Uwe Lueck, + + http://www.contact-ednotes.sty.de.vu + +Please report bugs, problems, and suggestions via the previous +web form. + + + == Installing/Required == + +`makedoc.sty' requires the `moreverb' package from + + CTAN:/macros/latex/contrib/moreverb + +You find the latest public version of the NICETEXT bundle at + + http://mirror.ctan.org/macros/latex/contrib/nicetext/ + +A TDS version `nictext.tds.zip' is available at + + http://mirror.ctan.org/install/macros/latex/contrib/ + + + ________________________________ + [This file 2015/11/09 Uwe Lueck] diff --git a/macros/latex/contrib/nicetext/README.pdf b/macros/latex/contrib/nicetext/README.pdf Binary files differnew file mode 100644 index 0000000000..f13216da46 --- /dev/null +++ b/macros/latex/contrib/nicetext/README.pdf diff --git a/macros/latex/contrib/nicetext/demo/arseneau.pdf b/macros/latex/contrib/nicetext/demo/arseneau.pdf Binary files differnew file mode 100644 index 0000000000..c928f5058f --- /dev/null +++ b/macros/latex/contrib/nicetext/demo/arseneau.pdf diff --git a/macros/latex/contrib/nicetext/demo/iso.txt b/macros/latex/contrib/nicetext/demo/iso.txt new file mode 100644 index 0000000000..455c8e2a79 --- /dev/null +++ b/macros/latex/contrib/nicetext/demo/iso.txt @@ -0,0 +1,3 @@ + + + diff --git a/macros/latex/contrib/nicetext/demo/lns.txt b/macros/latex/contrib/nicetext/demo/lns.txt new file mode 100644 index 0000000000..ff4f8b06e4 --- /dev/null +++ b/macros/latex/contrib/nicetext/demo/lns.txt @@ -0,0 +1,4 @@ +abba + +abba + diff --git a/macros/latex/contrib/nicetext/demo/sample.tex b/macros/latex/contrib/nicetext/demo/sample.tex new file mode 100644 index 0000000000..3264d37af5 --- /dev/null +++ b/macros/latex/contrib/nicetext/demo/sample.tex @@ -0,0 +1,5 @@ +\ProvidesFile{sample.tex}[2011/11/13 automatically generated with fifinddo.sty] +blabla \textellipsis\unkern\ blabla +blabla cf.\ bla +etc.\ bla bla + diff --git a/macros/latex/contrib/nicetext/demo/substr.pdf b/macros/latex/contrib/nicetext/demo/substr.pdf Binary files differnew file mode 100644 index 0000000000..f87d6966fa --- /dev/null +++ b/macros/latex/contrib/nicetext/demo/substr.pdf diff --git a/macros/latex/contrib/nicetext/doc/CHANGE.LOG b/macros/latex/contrib/nicetext/doc/CHANGE.LOG new file mode 100644 index 0000000000..212d542954 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/CHANGE.LOG @@ -0,0 +1,457 @@ +______________________________________________________________________ + +nicetext RELEASE 0.67 2015/11/21 + + CHANGE.LOG 2015/11/21 updated + niceverb.sty v0.62 2015/11/21 \qtdnverb was disabled! + niceverb.pdf 2015/11/21 updated + nicetext.RLS 2015/11/21 updated + SrcFILEs.txt 2015/11/21 updated +______________________________________________________________________ + +nicetext RELEASE 0.66 2015/11/09 + + CHANGE.LOG 2015/11/09 updated + makedoc.cfg 2013/03/25 usage of `filedate.sty' + makedoc.pdf 2015/11/09 updated + niceverb.sty v0.61 2015/11/09 \NVerb[..., \SetNiceVerbSaveBox, + `SelfProtect'tion & other + robustness, \active@math@prime in + \output, \qtdnverb; doc fixes + niceverb.tex 2014/03/28 local extensions of `makedoc.sty' + niceverb.pdf 2015/11/09 updated + nicetext.RLS 2015/11/09 updated + SrcFILEs.txt 2015/11/09 updated + +______________________________________________________________________ + +nicetext RELEASE 0.65 2012/11/30 `makedoc.cfg' ... + + CHANGE.LOG 2012/11/30 updated + makedoc.cfg 2012/11/30 \MDsamplecodeinput spacing corr., + \ctanpkgdref -> \urlfoot + makedoc.tex 2012/11/30 `makedoc.cfg' final section, + without raw code + makedoc.pdf 2012/11/30 updated + nicetext.RLS 2012/11/30 updated + srcfiles.tex 2012/11/30 applies new `filesdo.sty' + SrcFILEs.txt 2012/11/30 updated + +______________________________________________________________________ + +nicetext RELEASE 0.64 2012/11/27 `makedoc.cfg' without wrong + `pdfstartview', applying + `filesdo.sty', weaker \[d]qtd + + ANNOUNCE.txt 2012/11/27 back again + CHANGE.LOG 2012/11/27 updated + FILES.txt 2012/11/27 updated + README 2012/11/27 updated second (C) + README.pdf 2012/11/27 updated + fifinddo.pdf 2012/11/27 typeset with new `makedoc.cfg' + makedoc.cfg 2012/11/26 pdfstartview fixed + makedoc.pdf 2012/11/27 typeset with new `makedoc.cfg' + niceverb.sty v0.6 2012/11/27 \[d]qtd \provide'd only + niceverb.pdf 2012/11/27 typeset with new `makedoc.cfg' + nicetext.RLS 2012/11/27 updated + srcfiles.tex 2012/11/27 applies new `filesdo.sty' + SrcFILEs.txt 2012/11/27 updated + +______________________________________________________________________ + +nicetext RELEASE 0.63 2012/11/17 `fifinddo.sty' adjusted to + previous `mdoccorr.cfg'; `README' + updated, subtitle + + CHANGE.LOG 2012/11/17 updated + README 2012/11/17 updated (C), subtitle + README.pdf 2012/11/17 updated + SrcFILEs.txt 2012/11/17 updated + fifinddo.sty v0.61 2012/11/17 \gdef\do{\Prepend... + fifinddo.pdf 2012/11/17 updated + nicetext.RLS 2012/11/17 updated + +______________________________________________________________________ + +nicetext RELEASE 0.62 2012/11/13 `makedoc.cfg' enhanced + (`filedate', code input), + documented in `makedoc.pdf' + + CHANGE.LOG 2012/11/13 updated + SrcFILEs.txt 2012/11/13 updated + makedoc.cfg 2012/11/13 \MDdocnewline, + \MDfinaldatechecks, + \MDsamplecodeinput, + documentation code + makedoc.tex 2012/11/13 examples reformatted, + include `makedoc.cfg' + mdoccorr.cfg 2012/11/13 \do as shorthand, + code line breaks + makedoc.pdf 2012/11/13 updated + nicetext.RLS 2012/11/13 updated + srcfiles.tex 2012/11/13 some `filedate' checks + +______________________________________________________________________ + +nicetext RELEASE 0.61 2012/11/09 makedoc/mdoccorr.cfg + extended, use recent + `nicefilelist' + + CHANGE.LOG 2012/11/09 updated + FILEs.txt 2012/11/09 moved `nicetext.RLS' from + `use' to `doc, removed + `README.txt', `Announce.txt' + -> `RELEASE051.txt' + SrcFILEs.txt 2012/11/09 updated + srcfiles.tex 2012/11/09 use recent `nicefilelist' + makedoc.cfg 2012/11/09 `lmodern', \qtdcode, \TODO, + \MDsampleinput; + mdoccorr.cfg 2012/11/07 TODO -> \TODO{} + nicetext.RLS 2012/11/09 updated + +______________________________________________________________________ + +nicetext RELEASE 0.6a 2012/10/10 niceverb.pdf introduction + describes \[Dont]AddQuotes +______________________________________________________________________ + +nicetext RELEASE 0.6 2012/09/28 use & adapt to `catcodes', + makedoc.cfg: \pkgtitle + + CHANGE.LOG 2012/09/28 updated + SrcFILEs.txt 2012/09/28 updated + fifinddo.sty v0.6 2012/08/27 using `catcodes', \CatCode + fifinddo.pdf 2012/08/27 updated + makedoc.sty v0.52 2012/08/28 using `stacklet.sty' + makedoc.pdf 2012/08/28 updated + makedoc.cfg 2012/07/13 \do, \pkgtitle + niceverb.sty v0.5 2012/09/27 adapting to `catcodes', + rm. \AssignCatCodeTo, + \CatCode, \private_letters + niceverb.pdf 2012/09/27 updated + nicetext.RLS 2012/09/28 updated + +______________________________________________________________________ + +nicetext RELEASE 0.53 2012/05/27 makedoc.cfg, nicetext.RLS + + makedoc.cfg 2012/05/27 \MDaddtoabstract + nicetext.RLS 2012/05/27 new, access to release summary + CHANGE.LOG 2012/05/27 updated + FILEs.txt 2012/05/27 updated + SrcFILEs.txt 2012/05/27 updated + +______________________________________________________________________ +nicetext RELEASE 0.52 2012/04/03 bugfix + + makedoc.sty v0.51 2012/04/03 \_makedoc_autocorr_true default + makedoc.pdf 2012/04/03 updated + CHANGE.LOG 2012/04/03 updated + SrcFILEs.txt 2012/04/03 updated + +______________________________________________________________________ +nicetext RELEASE 0.51 2012/03/18 SUMMARY: fifinddo fix, + makedoc avoids mdoccorr.cfg by *, + affected documentation updated + + ANNOUNCE.txt 2012/03/18 updated + CHANGE.LOG 2012/03/18 updated + FILEs.txt 2012/03/18 updated + RELEAS05.txt 2012/03/18 renamed + SrcFILEs.txt 2012/03/18 uses longnamefilelist.sty, + updated + +- fifinddo.sty v0.51 2012/03/17 fix of setup alternatives, + affecting documentations + fifinddo.pdf 2012/03/17 updated + +- makedoc.sty v0.5 2010/03/30 \Make...* avoids inputting + mdoccorr.cfg + makedoc.tex 2012/03/18 summary updated + makedoc.pdf 2012/03/18 updated + mdoccheat.tex 2012/03/18 updated + mdoccheat.pdf 2012/03/18 updated + +- arseneau.tex 2012/03/18 uses \MakeCloseDoc* + arseneau.pdf 2012/03/18 updated + substr.tex 2012/03/18 uses \MakeCloseDoc* and ragged2e + substr.pdf 2012/03/18 updated + + srcfiles.tex 2012/03/18 uses longnamefilelist.sty + + +______________________________________________________________________ +nicetext RELEASE 0.5a 2011/12/07 corrects description of +fifinddo.sty v0.5 in ANNOUNCE.txt for bundle release 0.5 and here +below: support not for blogexec, but for "ligatures" in pending +blog.sty v0.7 (morehype bundle) + +______________________________________________________________________ +nicetext RELEASE 0.5 2011/12/05 + + DOC. + ANNOUNCE.txt 2011/12/05 most recent + CHANGE.LOG/txt 2011/12/05 updated + SrcFILEs.txt 2011/12/05 updated + fifinddo.pdf 2011/11/21 updated + makedoc.pdf 2011/12/03 updated + niceverb.pdf 2011/12/05 updated + + DOCSRC. + fifinddo.tex 2011/11/19 [fleqn], \pagebreak + makedoc.tex 2011/11/19 or \RequirePackage, + \MakeSingleDoc + niceverb.tex 2011/11/05 mod. pdftitle + srcfiles.tex 2011/12/05 cosmetic + + USE. + fifinddo.sty v0.5 2011/11/21 \PrependExpandableAllReplacer*, + + job `*' + \MakeSetupCommand + + \ifFinalInputFile + + \ProcessFinalFileWith + input check fixed, + \CloseResultFile message + "aligned", \protected@edef, + \ProcessInputWith reimplemented, + doc. mod.s + makedoc.cfg 2011/11/20 + \code + \pkg + makedoc.sty v0.42 2011/11/19 + \MakeSingleDoc; \MakeDoc + reads mdoccorr.cfg + mdoccorr.cfg 2011/12/03 fix `...', apply + \PrependExpandableAllReplacer* + niceverb.sty v0.44 2011/12/05 mod. \niceverb_collect_egroup/ + \VerticalCmdBox, doc. fix + +______________________________________________________________________ +nicetext RELEASE 0.47 2011/10/25 +`mdoccorr.cfg' uses `csquotes''s idea for symmetrical text ellipsis +(\unkern), no need for new macro as in r0.45; adds `...)' + +______________________________________________________________________ +nicetext RELEASE 0.46 2011/10/23 +`fifinddo' v0.44 sends messages from \ResultFile and \CloseResultFile + +______________________________________________________________________ +nicetext RELEASE 0.45 2011/10/14 +1. mdoccorr.cfg turns `...:' into `\dots:' (as opposed to symmetrical + versions of \dots inside or before words; needs new \MDtwodots) +2. typo fixes in makedoc.sty and niceverb.tex +3. -> makedoc.pdf, nicetext.pdf + +______________________________________________________________________ +nicetext RELEASE 0.44 2011/09/14 SUMMARY: niceverb + \AddQuotes, + enhancements for dialogues and + templates, mdoccheat.pdf back + RUN. +README-run.txt 2011/09/14 more accurate + copyfile.tex 2011/09/13 adjusted for fddial0g v0.2 + fdtxttex.tex 2011/09/13 adjusted for fddial0g/fifinddo + fdtxttex.tpl 2011/09/13 uses fifinddo v0.43 + makedoc.tpl 2011/08/23 uses fifinddo v0.43 + + RUNUSE. + atari.cfg 2011/09/13 adjusted for fddial0g v0.2 + u8atablg.fdf 2011/09/12 new + fddial0g.sty v0.2 2011/09/13 all ideas carried out + copyfile.cfg 2011/09/13 adjusted for fddial0g v0.2 + fdtxttex.cfg 2011/09/12 adjusted for fddial0g v0.2 + + USE. + fifinddo.sty v0.43 2011/09/13 + \CorrectedInputLine + mdoccorr.cfg 2011/09/13 reloadable in dialogues + niceverb.sty v0.44 2011/09/09 + \AddQuotes + +______________________________________________________________________ +r0.43a 2011/08/25 adds in ANNOUNCE.txt as of 2011/08/25 +that makedoc.cfg provides \MDkeywords and {MDabstract} + +______________________________________________________________________ +nicetext RELEASE 0.43 2011/08/23 SUMMARY: dialogues enhanced + (new copyfile.tex, fddial0g.sty), + makedoc.cfg enhanced, + niceverb.sty gets \gt+\lt + and an .aux bug fix. + + ANNOUNCE.txt 2011/08/23 announcing present release + CHANGE.LOG/txt 2011/08/23 updated + SrcFILEs.txt 2011/08/23 updated, was FileList.txt + README(.txt,.pdf) 2011/08/23 + .tds + copyfile.tex + README.tex 2010/02/14 moved by one line +README-run.txt 2011/08/23 new + atari.cfg 2011/08/23 new + atari.fdf 2010/08/23 new here + copyfile.cfg 2011/08/22 new + copyfile.tex 2011/08/22 + \Prov... for fileinfo + fddial0g.sty 2011/08/23 new + fdtxttex.tex 2011/08/23 uses fddial0g.sty + fdtxttex.tpl 2011/08/21 + \Prov... for fileinfo + fifinddo.sty v0.42a 2011/08/22 documentation fix + fifinddo.tex 2011/08/22 using new makedoc.cfg + makedoc.cfg 2011/08/22 + color.sty + \acro + \meta + makedoc.sty v0.41a 2011/08/22 documentation fix + makedoc.tex 2011/08/22 using new makedoc.cfg + makedoc.tpl 2011/08/23 + \Prov... for fileinfo + niceverb.sty v0.43 2011/08/20 + \gt + \lt, .aux fix + niceverb.tex 2011/08/22 using new makedoc.cfg + srcfiles.tex 2011/08/22 collects infos, was gather.tex + substr.tex 2011/08/20 + \Prov... for fileinfo + +______________________________________________________________________ +r0.42a 2011/01/30 moves makedoc.cfg to docsrc, changes name +`FILES.txt' into `FILEs.txt' and ordering within the file, +and uses the `source' tree in the .tds. +______________________________________________________________________ +nicetext RELEASE 0.42 2011/01/26 SUMMARY: corrected `makedoc.sty', + enhanced `fifinddo.sty' and + .txt->.tex, use `hypertoc.sty' + and `texlinks.sty', minor fixes, + documentation enhancements + + README(.txt) 2011/01/26 updated + README.pdf 2011/01/26 new, README version + README.tex 2011/02/14 moved by one line + CHANGE.LOG/txt 2011/01/26 updated + FileList.txt/gather.tex2011/01/26 new for source file versions + fifinddo.sty v0.42a 2011/08/22 + fifinddo.tex/pdf 2010/11/27 uses `readprov.sty', +TODO + makedoc.cfg 2011/01/24 uses `hypertoc' and `readprov' + makedoc.sty v0.41 2011/01/25 corrected! + makedoc.tex/pdf 2011/01/25 uses `readprov.sty' + mdoccorr.cfg 2011/01/12 `<-', `->'; `...' re-implem. + niceverb.sty v0.42 2011/01/26 fixes, code to `texlinks.sty' + nicetext.tex/pdf 2011/01/26 enhanced, uses `readprov.sty' + +______________________________________________________________________ +nicetext RELEASE 0.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 + README.tex 2010/11/27 new, generates README.pdf + 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 0.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 0.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/macros/latex/contrib/nicetext/doc/FILEs.txt b/macros/latex/contrib/nicetext/doc/FILEs.txt new file mode 100644 index 0000000000..7a104a522a --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/FILEs.txt @@ -0,0 +1,71 @@ +FILES IN CTAN DIRECTORY /macros/latex/contrib/nicetext: + + FILEs.txt present file +SrcFILEs.txt source file versions/descriptions + README summary + README.pdf PDF version of README + +SUBDIRECTORIES: + +demo automatically generated documentation ... +|___arseneau.pdf ... of packages by Donald Arseneau +|________iso.txt result from atari.txt +|________lns.txt result of "compressing" blank lines +|_____sample.tex result from sample.txt +|_____substr.pdf ... of Harald Harders' substr.sty + +doc documentation +|___ANNOUNCE.txt most recent announcement +|_____CHANGE.LOG bundle changes +|___RELEAS03.txt announcement for earlier release +|___RELEAS04.txt announcement for earlier release +|_RELEASE042.txt announcement for earlier release +|_RELEASE043.txt announcement for earlier release +|__RELEASE05.txt announcement for earlier release +|_RELEASE051.txt announcement for earlier release +|_RELEASE064.txt announcement for earlier release +|_RELEASE066.txt announcement for earlier release +|___fifinddo.pdf for fifinddo.sty +|____makedoc.pdf for makedoc.sty +|__mdoccheat.pdf lists makedoc+fifinddo commands +|___nicetext.RLS \Provides... brief release summaries +|___niceverb.pdf for niceverb.sty +|__wikicheat.pdf lists wiki.sty features + +docsrc documentation sources +|_____README.tex generates README.pdf [likewise:] +|___fifinddo.tex +|____makedoc.tex +|__mdoccheat.tex +|___niceverb.tex +|___srcfiles.tex gather source file versions +|__wikicheat.tex + +run dialogues/templates/examples +|_README-run.txt describes this subdirectory +|______atari.cfg Atari sample configuration for copyfile.tex +|______atari.fdf some Atari->ISO-8859-1 mappings +|______atari.txt Atari umlauts (sample for copyfile.tex) +|___arseneau.tex typesets documentation of ... +|___copyfile.cfg initializes copyfile.tex dialogue +|___copyfile.tex dialogue: compressing blank lines, conversion +|___fddial0g.sty macros for dialogues (to be improved ...) +|___fdtxttex.cfg initializes fdtxttex.tex dialogue +|___fdtxttex.tex dialogue for txt to TeX etc. +|___fdtxttex.tpl fifinddo script template for txt to TeX etc. +|______lines.txt initial/demo input for copyfile.tex +|____makedoc.tpl makedoc preprocessing script template +|_____sample.txt initial/demo input for fdtxttex.tex +|_____substr.tex typesets substr.sty documentation +|___u8atablg.fdf UTF-8->Atari/blog conversion with fdtxttex + +use macro packages +|___fifinddo.sty file handling and parsing +|____makedoc.cfg shared local style settings +|____makedoc.sty documentation preprocessing +|___mdoccorr.cfg txt to TeX macros +|___niceverb.sty minimal documentation markup +|_______wiki.sty Wikimedia-like markup + +__________________________ +this file 2015/11/09, U.L. diff --git a/macros/latex/contrib/nicetext/doc/RELEAS03.txt b/macros/latex/contrib/nicetext/doc/RELEAS03.txt new file mode 100644 index 0000000000..2c1905a37e --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/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[<in>][<out>]{<header>}{<parser>} + + generates a documentation file from the package file and + typesets it immediately (kind of \DocInput equivalent) + -- see `Using makedoc the simplest way' in `makedoc.pdf' + +* `|...|' from `niceverb' typesets an inline frame box for setting-off + a command description, modifiable by hooks (e.g., \colorbox) + +* `niceverb' syntax works in page headers, PDF bookmarks, and + `hyperref' labels and otherwise much better than before, + dis-/re-enableable featurewise as well as altogether + +* documentation extended, lists of script commands + +* configurable txt to TeX functionality or other replacements like + ASCII-arrows to arrow commands or inserting \index entries + (setting up expandable replacement chains slightly more comfortable) + -- try with templates and dialogue + +* `fifinddo' works with character codes > 127, improved setup + +* `makedoc' requires the `moreverb' package. + +______________________________________________________________________ +CATALOGUE: These packages may be compared with: +* easylatex, txt2latex, txt2tex + (typographical and TeX input enhancement); +* doc, gmdoc, lineno (awk in place of \DocInput); +* substr, datatool, ted, xstring, stringstrings, makematch, ... + (parsing)
\ No newline at end of file diff --git a/macros/latex/contrib/nicetext/doc/RELEAS04.txt b/macros/latex/contrib/nicetext/doc/RELEAS04.txt new file mode 100644 index 0000000000..acc9f8f74f --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEAS04.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/macros/latex/contrib/nicetext/doc/RELEAS05.txt b/macros/latex/contrib/nicetext/doc/RELEAS05.txt new file mode 100644 index 0000000000..a9c6ac2799 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEAS05.txt @@ -0,0 +1,32 @@ +nicetext: minimal markup for documentation, text filtering ... +================================================================= +Release 0.5 2011/12/05: + +`mdoccorr.cfg' + - bug fix for 2011/10/25: `...' at line ends + - applying new \PrependExpandableAllReplacer* from: + +`fifinddo.sty' v0.5 + - \PrependExpandableAllReplacer* uses automatically generated + job ids, job id `*' alias for most recent, + new \MakeSetupCommand another simplification + - new \ifFinalInputFile + \ProcessFinalFileWith simplify + typical applications + - support for "ligatures" like `--' and `---' with blog.sty + (from morehype bundle) + - input check fixed + - \CloseResultFile message "aligned" + - \ProcessInputWith reimplemented + - documentation modifications + + `makedoc.sty' v0.42 + - new \MakeSingleDoc simplifies typical application + - \MakeDoc reads mdoccorr.cfg + + `makedoc.cfg' + logical markup \code + \pkg + +`niceverb.sty' v0.44 + - modified \niceverb_collect_egroup/\VerticalCmdBox + (little success) + - doc. clarification diff --git a/macros/latex/contrib/nicetext/doc/RELEASE042.txt b/macros/latex/contrib/nicetext/doc/RELEASE042.txt new file mode 100644 index 0000000000..a39e9134ba --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEASE042.txt @@ -0,0 +1,26 @@ +Minimal markup for simple text (Wikipedia style) and documentation +================================================================== +New with release 0.42: + + `makedoc.sty' \small starting \mdPackageCode spoiled all + documentations 2009/2010! (fixed); + \ResetCodeLineNumbers fixed + +`mdoccorr.cfg' `<-' and `->' typeset arrows, `...' re-implemented + +`fifinddo.sty' new macros \IfFDpreviousInputEmpty ("compression" + of empty lines), \BasicNormalCatcodes, \CopyFile* + (compress), \CopyLine, \StartPrependingChain + (per-line jobs), documentation modified + +`niceverb.sty' fixed `\ ' in auto mode; + \ctanpkgref moves to `texlinks.sty'; + additions in introduction + + `makedoc.cfg' loads `hypertoc.sty' and `texlinks.sty' + +-- dedicated to my sister for her birthday! + + + + diff --git a/macros/latex/contrib/nicetext/doc/RELEASE043.txt b/macros/latex/contrib/nicetext/doc/RELEASE043.txt new file mode 100644 index 0000000000..ef40163b58 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEASE043.txt @@ -0,0 +1,36 @@ +Minimal markup for documentation, text filtering +================================================================= +Release 0.43 synchronizes references to here, +provides minor fixes, and enhances dialogues: + + `atari.cfg' settings for conversion with: + + `atari.fdf' from `morehype' exemplifies conversion with: + +`copyfile.cfg' initializes: + +`copyfile.tex' dialogue for compressing blank lines + (and text encoding conversion) + +`fdtxttex.cfg' initializes: + +`fdtxttex.tex' dialogue for .txt -> .tex conversion + +`fddial0g.sty' shared macros for the dialogues + +`fifinddo.sty' documentation fix \WriteResult -> \ResultFile + + `makedoc.cfg' loads `color.sty'; provides \acro by `relsize.sty' + (with a funny protection for hyperref bookmarks); + uses \meta as semantical alias for \textit; + [new with release r.0.43a:] + \MDkeywords passes keywords to \hypersetup + as well as to `MDabstract' environment + + `makedoc.sty' documentation fix makedoc.cfg -> mdoccorr.cfg + +`niceverb.sty' \gt for >, \lt for <; + fixed noisy catcode changing in .aux + + `README' adjusted, enhanced + diff --git a/macros/latex/contrib/nicetext/doc/RELEASE044.txt b/macros/latex/contrib/nicetext/doc/RELEASE044.txt new file mode 100644 index 0000000000..e1e514ba24 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEASE044.txt @@ -0,0 +1,27 @@ +Nice meta-verbatim, dialogues for .txt->.tex/encoding conversion +================================================================= +Release 0.44, 2011/09/14: + +`niceverb.sty' v0.44 copes with design issue: on "\AddQuotes", + "`...'" indeed surrounds inline TeX code + with single quotation marks automatically + (besides meta-verbatim) + +`fddial0g.sty' v0.2 all my ideas so far for dialogue programming + tools carried out (handling "variables", + displaying their values on a "screen", + "\Spaces{15}" [e.g.] counts when expanding + w/o e-TeX); not super-comfortable, but fine + +`fifinddo.sty' v0.43 new command useful in programming dialogues + +dialogues/templates adjusted + +`u8atablg.fdf' fifinddo rules for replacing UTF-8 chars + with TeX commands (and some extended ASCII) + +(I use all of this for converting my Xpad/Tomboy notes into input + for my great Atari editor) + +`mdoccheat.pdf' was missing in previous release, back again + diff --git a/macros/latex/contrib/nicetext/doc/RELEASE051.txt b/macros/latex/contrib/nicetext/doc/RELEASE051.txt new file mode 100644 index 0000000000..cc3ac31c0e --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEASE051.txt @@ -0,0 +1,21 @@ +nicetext: minimal markup for documentation, text filtering ... +================================================================= +Release 0.51 2012/03/18: + +- `fifinddo.sty' v0.51 + + fixes a bug related to support of some lightweight markup + in HTML generation by blog.sty. The bug had affected + documentation of previous fifinddo and makedoc releases. + Anyway ... + +- `makedoc.sty' v0.5 + + with all the \Make... commands for preprocessing packages + for documentation, a `*' avoids inputting mdoccorr.cfg + (replacement rules .txt -> .tex) + +- documentation samples `substr' and `arseneau' + + updated to use \MakeCloseDoc* for specific replacement rules + diff --git a/macros/latex/contrib/nicetext/doc/RELEASE064.txt b/macros/latex/contrib/nicetext/doc/RELEASE064.txt new file mode 100644 index 0000000000..16fe886c8c --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEASE064.txt @@ -0,0 +1,20 @@ +nicetext: minimal markup for documentation, text filtering ... +================================================================= +Release 0.64 2012/11/27: + +- `makedoc.cfg' without bad `pdfstartview' as on + + http://www.archivum.info/comp.text.tex/2006-10/00576/Re-hyperref-pdfstartview.html + +- ... applied to all the PDF documentation files + +- `srcfiles.tex' exemplifies + + \DoWithBasesExts{<cmd>}{<bases>}{<exts>} + + from new `filesdo.sty' + +- `niceverb.sty' v0.51 only "\providecommand"s \dqtd and \qtd + for better interaction with other packages providing + them too + diff --git a/macros/latex/contrib/nicetext/doc/RELEASE066.txt b/macros/latex/contrib/nicetext/doc/RELEASE066.txt new file mode 100644 index 0000000000..ef7be0c75e --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/RELEASE066.txt @@ -0,0 +1,14 @@ +nicetext: minimal markup for documentation, text filtering ... +================================================================= +Release 0.66, 2015/11/09 mainly: `niceverb.sty' + + - has `SelfProtect'ion and other improvements of robustness of + verbatim material (such as additionally:) + - deals with \active@math@prime when a page break occurs inside + a listing + - has \qtdnverb to deal with the downside of the `...' feature + - has several documentation fixes + +... and ideas on documentation in `niceverb.tex' + +(Returning!) diff --git a/macros/latex/contrib/nicetext/doc/SrcFILEs.txt b/macros/latex/contrib/nicetext/doc/SrcFILEs.txt new file mode 100644 index 0000000000..22146319cf --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/SrcFILEs.txt @@ -0,0 +1,38 @@ + + *File List* + DOCSRC.... -- -- -- -- + README.tex 2012/03/18 -- make README.pdf + fifinddo.tex 2011/11/19 -- documenting fifinddo.sty + makedoc.tex 2012/11/30 -- documenting makedoc.sty + niceverb.tex 2014/03/28 -- documenting niceverb.sty +mdoccheat.tex 2011/01/26 -- cheat sheet for `makedoc.sty' +wikicheat.tex 2011/01/26 -- cheatsheet for wiki.sty + srcfiles.tex 2012/11/27 -- file infos -> SrcFILEs.txt + RUN.... -- -- -- -- + arseneau.tex 2012/03/18 -- some packages by D. Arseneau (ul) + substr.tex 2012/03/18 -- documentation for substr.sty + copyfile.tex 2011/09/13 -- copy*ing/converting (UL) + fdtxttex.tex 2011/09/13 -- txt to TeX by dialogue (UL) + fdtxttex.tpl 2011/09/13 -- fifinddo correction template + makedoc.tpl 2011/09/14 -- makedoc preprocessing template + RUNUSE.... -- -- -- -- + atari.cfg 2011/09/13 -- sample for copyfile.tex + atari.fdf 2010/08/29 -- Atari German to ISO-8859 with blog.sty + u8atablg.fdf 2011/09/12 -- UTF-8->Atari/blog with fdtxttex + fddial0g.sty 2011/09/13 v0.2 dialogues with fifinddo (UL) + copyfile.cfg 2011/09/13 -- initializing copyfile.tex + fdtxttex.cfg 2011/09/12 -- initializing fdtxttex.tex + USE.... -- -- -- -- + fifinddo.sty 2012/11/17 v0.61 filtering TeX(t) files by TeX (UL) + makedoc.sty 2012/08/28 v0.52 TeX input from *.sty (UL) + makedoc.cfg 2013/03/25 -- documentation settings + mdoccorr.cfg 2012/11/13 -- `makedoc' local typographical corrections + niceverb.sty 2015/11/21 v0.62 minimize doc markup (UL) + wiki.sty 2008/07/02 v0.2 LaTeX through Wiki markup + BUNDLE.... -- -- -- -- + nicetext.RLS 2015/11/21 r0.67 `niceverb.sty' v0.62 \qtdnverb fixed + *********** + + List made at 2015/11/21, 02:43 + from script file srcfiles.tex + diff --git a/macros/latex/contrib/nicetext/doc/fifinddo.pdf b/macros/latex/contrib/nicetext/doc/fifinddo.pdf Binary files differnew file mode 100644 index 0000000000..785d77cd4b --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/fifinddo.pdf diff --git a/macros/latex/contrib/nicetext/doc/makedoc.pdf b/macros/latex/contrib/nicetext/doc/makedoc.pdf Binary files differnew file mode 100644 index 0000000000..f916aa1dbe --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/makedoc.pdf diff --git a/macros/latex/contrib/nicetext/doc/mdoccheat.pdf b/macros/latex/contrib/nicetext/doc/mdoccheat.pdf Binary files differnew file mode 100644 index 0000000000..d12a9be145 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/mdoccheat.pdf diff --git a/macros/latex/contrib/nicetext/doc/nicetext.RLS b/macros/latex/contrib/nicetext/doc/nicetext.RLS new file mode 100644 index 0000000000..1001954879 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/nicetext.RLS @@ -0,0 +1,22 @@ +\ProvidesFile{nicetext.RLS} %% >RELEASE INFO< + [2015/11/21 r0.67 `niceverb.sty' v0.62 \string\qtdnverb\space fixed] + [2015/11/09 r0.66 `niceverb.sty' robustness features] + [2012/11/30 r0.65 makedoc.cfg: \string\MDsamplecodeinput\space + corr., \string\ctanpkgdref] + [2012/11/27 r0.64 makedoc.cfg w/o bad pdfstartview, + use filesdo.sty,^^Jweaker \string\(d)qtd] + [2012/11/17 r0.63 `fifinddo' v0.61 adjusted for^^J + previous `mdoccorr.cfg';^^J %% rm. , 2012/11/21 + `README' updated, subtitle] + [2012/11/13 r0.62 `makedoc.cfg' uses `filedate',^^J% + \string\MDdocnewline, \string\MDsamplecodeinput,^^J% + documented in `makedoc.pdf';^^J% + `mdoccorr.cfg' nicer] + [2012/11/09 r0.61 `lmodern', \string\qtdcode, \string\TODO, + \string\MDsampleinput; + use recent `nicefilelist'; + corr. upload dirs] + [{2012/10/10 r0.6a \string\[Dont]AddQuotes -> intro}] + [2012/09/28 r0.6 use & adapt to `catcodes', \string\pkgtitle] + [2012/05/27 r0.53 makedoc.cfg \string\MDaddtoabstract] + [2012/04/03 r0.52 bug fix] %% 2012/05/26 diff --git a/macros/latex/contrib/nicetext/doc/niceverb.pdf b/macros/latex/contrib/nicetext/doc/niceverb.pdf Binary files differnew file mode 100644 index 0000000000..3d3dc7b196 --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/niceverb.pdf diff --git a/macros/latex/contrib/nicetext/doc/wikicheat.pdf b/macros/latex/contrib/nicetext/doc/wikicheat.pdf Binary files differnew file mode 100644 index 0000000000..481c7e314d --- /dev/null +++ b/macros/latex/contrib/nicetext/doc/wikicheat.pdf diff --git a/macros/latex/contrib/nicetext/docsrc/README.tex b/macros/latex/contrib/nicetext/docsrc/README.tex new file mode 100644 index 0000000000..a4bf82368f --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/README.tex @@ -0,0 +1,12 @@ +\ProvidesFile{README.tex}[2012/03/18 make README.pdf] +\listfiles + +\documentclass[12pt]{article} +\usepackage{verbatim} +\pagestyle{empty} +\begin{document} +\vspace*{-3\baselineskip} +\enlargethispage{2\baselineskip} +% \small %% 2011/02/14 +\verbatiminput{README.txt} +\end{document} diff --git a/macros/latex/contrib/nicetext/docsrc/fifinddo.tex b/macros/latex/contrib/nicetext/docsrc/fifinddo.tex new file mode 100644 index 0000000000..e026929dbf --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/fifinddo.tex @@ -0,0 +1,348 @@ +\ProvidesFile{fifinddo.tex}[2011/11/19 documenting fifinddo.sty] +\title{\textsf{fifinddo}\\---\\Filtering \TeX(t) Files by + \TeX\thanks{This file describes + version \fileversion\ of \textsf{\filename} as of \filedate.}} +% \listfiles +\documentclass[fleqn]{article} +\usepackage{makedoc} +% \usepackage{substr} %% for failure examples TODO 2010/03/17 +\input{makedoc.cfg} +\MDkeywords{text filtering, macro programming, + .txt to .tex enhancement} +\hypersetup{% + pdftitle=fifinddo.sty filters text by TeX, + pdfsubject=documenting fifinddo.sty +} +\ReadPackageInfos{fifinddo} +\begin{document} +\maketitle + +\begin{flushright}\small\it FIDO, FIND!\\or:\\FIND FIDO!\\oder:\\FIFI, + SUCH!\end{flushright} +\begin{MDabstract} +'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{MDabstract} +\tableofcontents + +\pagebreak %% 2011/11/19 +\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{center} %% 2011/11/13 +% \begin{quote}\small +% \[\texttt{% +% \hbox\bgroup\url{% %% \url impossible!? 2010/03/19 + \url{% + 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} +\end{center} +(Some of them may have been \emph{reactance} to 'texhax' and other +postings urging not to try something like this; some seem just to be +celebrations of the power of \TeX---yes, celebrate!) + +Actually, \TeX's mechanism of collecting macro arguments is hard-wired +parsing at quite a high level. \LaTeX\ hides this from +``simple-minded" users by a convention \emph{not} to use that full +power of \TeX\ for \emph{end-user macros}. +\emph{Internally}, \LaTeX\ \emph{does} use it in reading +lists of options and file dates as well as to implement certain +`FOR'- and `WHILE'-like loop programming structures. +\LaTeX's `\in@'/`\ifin@' construction is an implementation of a +``<string1> occurs in <string2>" test. More packages seem to use +this idea for extracting file informations, like +'texshade'.\footnote{\url{http://ctan.org/pkg/texshade}} + + +However, such packages don't make much ado about parsing, +there seems to be no general setup mechanism as are presented by +'fifinddo'. Indeed, tayloring parsing macros to specific applications +may often be more efficient than a general approach. + +\subsection{Useful for \dots} +My main application of 'fifinddo' at present is typesetting +documentations of packages using 'makedoc' which removes certain +percent marks and inserts listing commands, so you edit a package file +with as little documentation markup as possible. +This may be extended to other kinds of documents as an alternative +to 'easylatex' or 'wiki' (the approach of which is dangerous and +incompatible with certain other things). + +I have used a similar own package 'txtproc' successfully, +where more features were implemented for practical purposes +than are here so far, yet I don't like its implementation, want to +improve it here. This package also \emph{created batch files}, e.g., +to remove temporary files. +This could be used for package handling: +typset the documentation at the desired place in the tree, +write the packages to another, write a batch file to remove +files that are not needed any more after installation +(cf.\ 'make'). %%% !? cf. Wiki `Make (software) 2009/04/11 + +I used 'txtproc' also for \emph{large-scale substitutions} +(it had been decided to change the orthography in a part of a book). +Other large-scale substitutions may be: +\begin{itemize} +\item inserting &\index commands; +\item inserting (soft) hyphenation commands near accents; +\item manual umlaut-conversion.\footnote{If you know the ``names" + of the encodings, Heiko Oberdiek's + \ctanpkgref{stringenc} + may be preferable.} +\item typographical (or even orthographical) corrections (same mistake + many times on each of hundreds of pages). + You may turn `...' into `$\dots$' and `etc.' into `etc.\' + etc.\footnote{But what when a new sentence is starting indeed? + Well, `cf.' is an easier example.---`etc.' even showed + a problem in 'niceverb'. 'mdoccorr.cfg' replaces `etc. ' + only, so you can keep the extra space by a code line break.} + This could replace packages like + 'easylatex',\footnote{\url{http://ctan.org/pkg/easylatex}} + 'txt2latex',\footnote{\url{http://ctan.org/pkg/txt2latex}} + 'txt2tex'\footnote{\url{http://ctan.org/pkg/txt2tex}} + in a customizable way, using, e.g., the ``correct" + hook from 'makedoc.sty' as exemplified in 'mdoccorr.cfg' + (see examples section of 'makedoc.pdf'). + You should find 'fdtxttex.tpl', a 'fifinddo' script + to try or apply `\MakeDocCorrectHook' from 'mdoccorr.cfg', + as well as 'fdtxttex.tex' that runs a dialogue for the + same purpose if you can manage to run it ('WinShell'?). + You can then try to create your own `\MakeDocCorrectHook'. + Section~\ref{sec:replchain} provides setup for macros + of this kind. +\item as to 'easylatex' again, \emph{lists} could be detected and + transformed into \LaTeX\ list commands. This could re-implement + the lists functionality of 'wiki.sty' that is somewhat + dangerous. %% TODO 2009/04/15 +\item introduce your own \emph{shorthands} to be expanded not as \TeX\ macros, + but by text substitution; +\end{itemize} +%% % <- TODO present macros/"jobs" doing this. +%% %% <- TOOD single quote tests could be used for +%% double quote character as well +%% to turn it into left quotes if ... 2010/03/19 +% +In certain cases, insertions deteriorate readability, hyphenation +corrections even make text search difficult. +It is therefore suggested to +\begin{enumerate} +\item keep editing the file without the insertions, +\item run the script (commands based on 'fifinddo') for insertions + in the preamble of the main file + (```\jobname.tex'", maybe &\input the script file) and +\item &\input the result file within the `document' environment. +\end{enumerate} + +In general, differences to ``manual" replacing by the substitution +function of your \emph{text editor} is that +\begin{itemize} +\item you first keep the original version, +\item you can check the resulting file before you replace the original + file by it, +\item you can store the replacement script in order to check for + mistakes at a later stage of your work, +\item you can do \emph{all} the replacements in \emph{one run} + (by \emph{one} script to check for mistakes), +\item you can store replacement scripts for future applications, + so you needn't type the patterns and replacement strings anew. +\end{itemize} + + +\subsubsection{Comparisons} %% was `Missing' 2010/03/18 +% \subsection{To implement or not to implement \dots} %% TODO!? 2009/04/13 +% Actually, 'fifinddo' doesn't implement very much, and this possibly +% won't change, even if I am lucky. ``Practical applications" tend to +% show (in my view) that there is a very complex space of possibilities +% what parsing macros could do. If I try to ``attack" 'Perl' or so, +% cf.\ 'CPAN'\@. If I am lucky and become famous, 'fifinddo' will get many +% extensions in separate packages, cf.\ 'pstricks'. I also like it when +% you can choose among packages for similar purposes, and this may apply +% to extensions of 'fifinddo' as well. +% +% What \emph{really} is missing very badly at present is matching +% \emph{sequences} of strings. However, 'makedoc' contains a practical +% application of this for the case that both strings appear \emph{in the same +% line}. A better algorithm would have to read more lines from the input +% file etc. +% +% As it just comes to my frightened mind, there is even a problem with +% ``strings"/``patterns" that are \emph{phrases} of words, containing +% spaces \dots +% +% Clearly much comfort concerning \emph{routine} jobs is missing now, +% 'txtproc' has more. Please sponsor (or otherwise support) the work for +% improving this. +% +It should be noted (perhaps here) that the present approach to parsing +is a quite \emph{simple} one and in this respect much different to the +string handling mechanisms of +'stringstrings',\footnote{\url{http://ctan.org/pkg/stringstrings}} +'ted',\footnote{\url{http://ctan.org/pkg/ted}} +'xstrings'\footnote{\url{http://ctan.org/pkg/xstrings}} +(as I understand them, perhaps also +'coolstr'\footnote{\url{http://ctan.org/pkg/coolstr}}) +which are \emph{much more powerful} than what is offered here---but +perhaps slow and for practical applications possibly replaceable by +the present approach. +\emph{Expandable replacement} seems not to exist outside 'fifinddo' +(2009/04/13). + +Much is missing, I know.\footnote{There + is more in my badly implemented 'txtproc.sty'.} +I am just implementing what I actually need +and what could show that this approach is worth being pursued. + %% removed 2010/03/18: +% It may need being sponsored or otherwise supported. + +\subsection{For insiders} + +\emph{Warning:} You may (at least at the present state of the work) +have little success with this package, if you don't know about +\TeX's category codes and how \TeX\ macros are defined. +The package rather provides tools for package writers. +You may, however, be able to run other packages which just load +'fifinddo' as required background. + +That 'fifinddo' acts on ``\TeX(t)" files or so means that +(at present) I think of applications on ``plain text" files which +will usually be \TeX\ input files. ``At present" they are read +without ``special characters," so essentially category codes of input +characters are either 11 (``letter") or 12 (``other"). +This way some things are easier than with usual \TeX\ applications: +\begin{enumerate} +\item You can ``look into" curly braces and ``behind" comment characters. +\item There are exact or safe tests especially of \emph{empty macro arguments} + that are ``expandable," i.e., they are ``robust," + don't need assignments, can be executed in `\write'ing and in + `\edef' definitions. ``Usually," the safe way to test emptiness + is storing a macro argument as a macro, say `\tempo', in order + to test `\ifx\tempo\empty' where `\empty' has been defined + by `\def\empty{}' in the format. But this requires some + `\def\tempo{#<n>}' which breaks in ``mere expanding" + (\TeX\ \emph{evaluates} `\tempo' instead of defining it). + An \emph{expandable} test on emptiness is, e.g. `\ifx$#<n>$', + where we hope that it becomes `\iftrue' just if macro argument + `#<n>' is empty indeed. However, ``usually" it may \emph{also} + become `\iftrue' when `#<n>' starts with `$'---if the latter + has category code 3 (``math shift"). But 'fifinddo' does + not assign category code 3 to any character from the input file! + Therefore `\ifx$#<n>$' is `\iftrue' \emph{exactly} if `#<n>' is + empty. +\item You can avoid interference with packages that are needed for + typesetting. You can do the ``preprocessing" in one run with + typesetting, but you should do the preprocessing before you + load packages needed for typesetting. One may even try to keep + the macros and settings for preprocessing local to a group. +\end{enumerate} +%% done, moving to .sty 2010/04/06: +% 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, + 'parselines' 2010/11/13 + +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 +2010/04/06 possible uses of reading TeX category codes moved to .sty +2010/11/11 \thanks <- package version +2010/11/12 package date updated, \author -> makedoc.cfg +2010/11/13 package date updated; parselines +2010/11/24 debugging +2010/11/25f. using readprov.sty +2010/11/27 reworked \ProvidesFile +2011/08/22 PDF metadata; adjusting to makedoc.cfg +2011/11/13 [fleqn] +2011/11/19 \pagebreak diff --git a/macros/latex/contrib/nicetext/docsrc/makedoc.tex b/macros/latex/contrib/nicetext/docsrc/makedoc.tex new file mode 100644 index 0000000000..30b16c2ed9 --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/makedoc.tex @@ -0,0 +1,718 @@ +\ProvidesFile{makedoc.tex}[2012/11/30 documenting makedoc.sty] +\RequirePackage{makedoc} +\documentclass[fleqn]{article} %% fleqn 2011/10/12 +\input{makedoc.cfg} +%% 2011/08/22: +\MDkeywords{literate programming, .txt to .tex enhancement, + preprocessing documentation, macro programming} +\hypersetup{% + pdftitle=makedoc.sty preprocesses .sty for documentation, + pdfsubject=documenting makedoc.sty +}%% /2011/08/22 +\sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/21 niceverb!? 2011/01/25 +\makeatletter %% TEST for hyperref compatibility 2010/03/11 +% \def\@testdef #1#2#3{% +% \def\reserved@a{#3}% +% \expandafter \ifx \csname #1@#2\endcsname +% \reserved@a \else \@tempswatrue \fi +% \if@tempswa +% \typeout{^^J*** Type `r' <input> to get around +% \string\label\space issues! ***^^J} +% \errorcontextlines=0 +% \show\reserved@a +% \expandafter \show \csname #1@#2\endcsname +% \fi +% } +% \makeatother +\begin{document} +\title{'makedoc'---Preprocessing documentation by \TeX\thanks{% + This document describes %% 2011/01/25 + version~\textcolor{blue}{\UseVersionOf{makedoc.sty}} + of 'makedoc.sty' as of \UseDateOf{makedoc.sty}.}} +\maketitle +\begin{MDabstract} +'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{MDabstract} +\tableofcontents +\section{Introduction} +\emph{The abstract will not be repeated in this section.} Let me add +instead that I was in dire need of such a package, I got stuck with my +packages because I lost orientation in them, and I was unhappy with +the forms of documentations of my other packages, and documenting them +with the standard \LaTeX\ 'doc' system was not attractive for me +(neither considered helpful). %% clarified 2010/03/13 +I also worked on \emph{Windows} until September 2008, and I +find a system like the present one still more attractive then using +(learning!\@) other filtering utilities (see below on 'awk'). And I +may work on \emph{Windows} once again and don't want to depend on +installing some $\dots$ there---\emph{I really would like to have +powerful tools for everything depending on nothing but \TeX\slash +\LaTeX!} + +\section{Prior work and what is new} +It is, of course, not a new idea to get around comment marks `%' to +typeset the documentation. 'doc''s `\DocInput' does this by making `%' +an ``ignored" character. This way you cannot use `%' for commenting +comments (so 'doc' offers a ``new comment mark" +`^'`^'`A'). %% TODO `^^A' suddenly failed 2010/03/15 -- "ligature"!? +You also cannot use `%' for commenting out code (that you are +pondering---or using for debugging---only). %% clarified 2010/03/13 + +Moreover, 'doc' requires enclosing package code explicitly by +environment commands (behind comment marks). Stephan I. B\"ottcher +with his '\href{http://ctan.org/pkg/lineno}{lineno.sty}' +and Grzegorz Murzynowski in \ctanpkgref{gmdoc} +aimed at doing away with this requirement. +'lineno.sty' contains 'awk' scripts +to remove starting comment marks and to insert listing commands. +A file 'lineno.tex' is generated that typesets the documentation. +By the way, 'lineno.sty' is full of discussions, but it is not +'docstrip'ped---the maintainers never have received a complaint +that inputting 'lineno.sty' were too slow. + +'gmdoc' seems to get around comment marks and insert listing commands +\emph{while typesetting} by a refined version of `\DocInput', +through some careful detecting and analysing comment marks, +the approach resembles detection of lists in 'wiki.sty'.\footnote{See + 'gmdoc.pdf' on &\DocInput. You can learn a lot from this 220 pages + document! I also find + \ctanpkgref{pauldoc} and \ctanpkgref{xdoc} inspiring.} +And this is a matter of principles---comparing the approaches of +\emph{preprocessing} ('lineno.sty') and \emph{``smart typesetting"} +('gmdoc', 'wiki'). Sometimes preprocessing seems to be simpler, +sometimes detecting while typesetting. +(Another example is the preprocessor +\ctanpkgref{easylatex} +of which 'wiki.sty' is a much reduced ``while typesetting" variant.) +``While typesetting" may be easier when single characters or +sequences of two or three encode markup +information---but such detection can badly interfere with other +packages etc. ``Preprocessing" may be easier when entire ``strings" +of characters decide, which may be anywhere in a file line. + +'makedoc' chooses \emph{preprocessing}, as 'lineno.sty', but by +\emph{\TeX}. There is a general discussion of this choice in the +documentation of 'fifinddo'. Preprocessing here can be done in the +same \LaTeX\ run as typesetting, though you can avoid +incompatabilities with packages needed for typesetting +(by inputting them only \emph{after} preprocessing). + +'lineno.sty' exemplifies why preprocessing with \emph{\TeX} may be +preferable to preprocessing with other utilities: +When I took over maintenance of 'lineno.sty', +I needed hard work to get the 'awk' script running. +The \emph{Munich} 'awk' seemed \emph{not} to behave as the \emph{Kiel} +'awk' (I chose a Munich 'nawk' and reworked the script a little). +\TeX\ seems to have better fixed functionality than other utilities! + +A different alternative to \LaTeX's 'doc' system is +Paul Isambert's '\href{http://ctan.org/pkg/codedoc}{CodeDoc}' +where the code environments extract package code in typesetting the +documentation. %% added 2010/03/10 + +\section{Styles supported (parsers provided)}\label{sec:styles} +% \section{Styles of commenting '.sty's} +We find different styles of documenting \LaTeX\ packages. +As the main aspects I consider +(i)~\emph{telling code from comments} +and (ii)~\emph{markup in comments}. +(You may find more details on the next matters in the + ``implementation" section.) + +\subsection{Telling code from comments} +\emph{Comment marks} (usually \lq`%'\rq\ in the case of \TeX) +probably were named so to mark \emph{``comments"} as opposed +to code $\dots$ great, but actually, in ``daily practice," +they are so handy---and used---for ``commenting out" \emph{code}, +i.e., \emph{managing code versions} in a simple way: +one does not actually want to \emph{delete} code, +one might want to use it another time, maybe for debugging +$\dots$ or to remind of earlier attempts that should not be tried +again $\dots$ + +This is a problem for \emph{high-quality typesetting} of +documentation. \emph{Code} should be typeset about as you see it on +the \emph{screen}---\emph{monospaced}, this allows structuring by +indenting, it is common practice to use a typewriter typeface for +this. Real \emph{comments} should be typeset in \emph{high quality} as +usual with \LaTeX. Little dilemmas therefore occur with \emph{``hidden +code"} (``commented-out"). A comment mark starts the line, but +obviously it is not really a comment and rather should be typeset +like code (and otherwise they may break). %% 2010/03/22 +Another problem are comments at the \emph{end} of a +\emph{code} line. Sometimes they are ``real comments" ('gmdoc' +supports this style). But sometimes +this is only another version of ``version management," code +``commented-out." + +I like the style of writing packages described before and use it all +the time. I mark ``real comments" with \emph{two} adjacent comment +marks and an ensuing space to distinguish them clearly from code +commented out. +%% Adapted to v0.4 2010/03/29: +\emph{This style is presently the one supported by \textup{'makedoc'} + as default.} +This way only a line starting with +|%% | is considered a ``real" comment line. The first three +characters are removed, and the rest is typeset in high quality. +Any other lines are typeset verbatim. The 'makedoc' \emph{parser} +doing this has an ``identifier" |PPScomment| (``percent, percent, +space"). Another identifier |comment| is a placeholder for +the comment parser to be used, by default it is an alias for +`PPScomment'. Lines just containing |%%| (without the space) may be +used to suppress empty code lines preceding section titles and for +keeping some visual, relieving space between code and comment lines. + +The style I described previously may be considered ``unprofessional." +The many \LaTeX\ packages documented using the 'doc'\slash'.dtx' +system don't use comment marks for \emph{``commenting-out"}. +Or one may mark code commented out by putting no space between the +percent mark and the code. +With v0.4 of 'makedoc', this style is supported as |PScomment|. +You can directly call this as <main-parser> as described below, +or you can switch to it by +\[`\CopyFDconditionFromTo{PScomment}{comment}'\] + +\subsection{Markup in comments} +\label{sec:mdoccorr-tex} %% 2012/03/18 +Packages using the 'doc'\slash '.dtx' system as well as alternative +highly developed systems mentioned above use (enhanced) usual +\emph{\LaTeX} syntax for markup of comments. Other packages just use +an \emph{ASCII} style \emph{without} any markup. My idea was to +support the latter style by some `txt'$\to$\LaTeX\ functionality. +'makedoc' does this using a file 'mdoccorr.cfg' which is very small +right now. + +I also thought of introducing another sort of ``decent" markup not +needing much more space than the ``ASCII kernel" of the comments. +This is to some extent implemented in 'niceverb.sty'. I thought of the +syntax of editing \textit{Wikipedia} pages; this is partially +implemented in 'wiki.sty' which unfortunately is not yet compatible +with 'niceverb'. + +But 'makedoc' implements one \textit{Wikipedia} feature in a different +way than 'wiki.sty' (cf.~'wikicheat.pdf') that looks about as follows: +\begin{eqnarray*} + \endcell\endcell`%% == Section =='\\ + \endcell\endcell`%% === Subsection ==='\\ + \endcell\endcell`%% ==== Subsubsection ====' +\end{eqnarray*} +i.e., you type `== <title> ==' in place of `\section{<title>}' etc. +The parser must replace `====<title3>===' before `===<title2>===' and +the latter before `==<title1>=='. In fact, 'makedoc' provides three +parsers for these situations: +\begin{description} +\cmdboxitem|\SectionLevelThreeParseInput| is the most general parser + offered. If it does not find two strings \lq`===='\rq\ enclosing + \emph{something}, it passes to +\cmdboxitem|\SectionLevelTwoParseInput| which unless finding + two strings `===' enclosing something passes to +\cmdboxitem|\SectionLevelOneParseInput| $\dots$ passes to the comment + detector |comment|. +\end{description} + + +\section{Requirements} +'makedoc' requires \LaTeXe\ (supporting star forms of `\newcommand' +etc.)\ as \TeX-format, the package 'fifinddo.sty' from the same +directory (on CTAN etc.)\ as where 'makedoc.sty' is, and the +\LaTeX-package 'moreverb' by Robin Fairbairns (after others)---it +should be installed anyway, or you can get its latest version +(v2.3, 2008/06/03?) from CTAN. + +'makedoc''s `.txt'$\to$\TeX\ functionality moreover needs a file +'mdoccorr.cfg' that should have come along with 'makedoc.sty' and +'fifinddo.sty'. You may need to have a modified copy of it in the +directory of your main `.tex' file `<jobname>.tex' fitting special +needs of your project. + +\section{Using 'makedoc' the simplest way} +In the most simple case, you are preparing documentation for a package +file `<jobname>.sty' only, and you prepare a file `<jobname>.tex' +containing +\[`\title{\textsf{<jobname>}---a \LaTeX\ Package for <whatever>}'\] +and `\maketitle' etc.\ about your package.\footnote{With 'niceverb' + and &\title\ after &\begin{document}, you may replace + \lq&\textsf{<jobname>}\rq\ by \lq&'<jobname>&'\rq.} +The documentation will be produced by running `<jobname>.tex' with +\LaTeX\ (e.g., \texttt{latex <jobname>.tex}). + +First, `<jobname>.tex' must have +\[|\usepackage{makedoc}|\quad\mbox{or}\quad + |\RequirePackage{makedoc}|\] %% 2011/11/05 +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} +\label{sec:sep-pre-type} %% 2011/10/07 + %% 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>}'), %%% (`{\code}'), %% 2011/10/07 +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 %% \[...\] 2012/11/12 +\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'.---By contrast, you may want to make a single output +file from a single input file! Therefore: +%% <- 2011/11/05 -> +% +\begin{description} +\cmdboxitem|\MakeSingleDoc[<out-ext>]{<in-output>.<in-ext>}| \ + issues\\`\LaTeXresultFile{<in-output>.<out-ext>}'\quad + and\\`\MakeDocCloseDoc{<in-output>.<in-ext>}'.\\ + The default for <out-ext> is `doc'. +\end{description} + +%% 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} +\subsection{Star avoids &\input{mdoccorrhook}} +All the preprocessing commands described above---apart from the +'fifinddo' command `\ProcessFileWith'---input the file +'mdoccorr.cfg' with (typographical) replacement rules +(Sec.~\ref{sec:mdoccorr-tex}, Sec.~\ref{sec:mdoccorr}) +automatically. They have star variants that don't: +|\MakeInputJobDoc*|, |\MakeJobDoc*|, |\MakeDoc*|, +|\MakeCloseDoc*|, and |\MakeSingleDoc*|. +This is useful when rules very specific to a certain package +must be applied instead of the usual ones. +The examples named in Sec.~\ref{sec:otherauth} use this feature +for formatting other author's plain text documentation +without modifying their files. + +\section{Examples}%%% (documentation of 'mdoccorr.cfg')} +%% moved here 2010/03/23 +\subsection{Documenting 'nicetext''s `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 %% rm. those struts 2012/11/12 +% \listinginput[5]{1}{mdoccorr.cfg} + %% <- 2012/11/12 > +\MDsamplecodeinput{mdoccorr.cfg} +\noindent +This code also exemplifies the syntax 'niceverb' provides for writing +about \LaTeX\ macros. It is typeset here with 'makedoc.sty' +and then looks thus: +\bigskip +\hrule +\renewcommand*{\mdJobName}{mdoccorr} +\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}} +\hrule +\bigskip +\noindent +And this is the content of the intermediate generated file: +% \listinginput[5]{1}{mdoccorr.doc} +\MDsamplecodeinput[75pt]{mdoccorr.doc} +% \enlargethispage{8pt} %% 2011/09/14 keep rule on same page %% rm. 2011/10/25 +% \hrule +% \fussy %% 2010/03/29 + + \iffalse %% 2012/11/30 +%% 2012/11/12: +\pagebreak +\subsection{Documenting 'nicetext''s `makedoc.cfg'} +`makedoc.cfg' once was meant to be just ``configuration," +but then I introduced some definitions there that may be +more interesting and once become a package. +Its typeset documentation first: +\pagebreak[3] +\strut\bigskip +\hrule +\smallskip +\renewcommand*{\mdJobName}{makedoc} +\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}} +\hrule +\bigskip +\noindent\strut +The bare code of `makedoc.cfg' is: +\MDsamplecodeinput{makedoc.cfg} + + \fi +\subsection{Packages from other authors} +\label{sec:otherauth} +`substr.tex' should typeset a nicely formatted documentation +of Harald Har\-ders' '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; rm. 2011/09/14 +\ResetCodeLineNumbers %% 2010/03/29 +\section{Implementation} +\subsection{Preliminaries} +Head of file (Legalese): +\sloppy +\renewcommand*{\mdJobName}{makedoc} +\ProcessLineMessage{} +\MakeInputJobDoc{22}{\ProcessInputWith{comment}} +\enlargethispage{2\baselineskip} %% 2011/11/05 +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 + +%% 2012/11/30: +\section{`makedoc.cfg' Documented} +`makedoc.cfg' once was meant to be just ``configuration," +but then I introduced some definitions there that may be +more interesting and once become a package. +\renewcommand*{\mdJobName}{makedoc} +\MakeInputJobDoc[cfg]{0}{\ProcessInputWith{comment}} + +%% 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 +2010/11/27 \ProvidesFile for myfilist +2011/01/25 \thanks with readprov.sty +2011/08/22 using new makedoc.cfg features +2011/09/14 rm. \pagebreak +2011/10/07 "grouping" fix(?) + \label in "Separating" +2011/10/12 fleqn +2011/10/25 without \enlargethispage +2011/11/05 or \RequirePackage{makedoc}; \MakeSingleDoc +2011/11/19 debugging for fifinddo v0.5 +2012/03/18 * forms; Harald H. corrected +2012/11/12 reworked `mdoccorr' example (\MDsampleinput), + added `makedoc.cfg' documentation as sample +2012/11/13 using \MDsamplecodeinput from `makedoc.cfg' same day diff --git a/macros/latex/contrib/nicetext/docsrc/mdoccheat.tex b/macros/latex/contrib/nicetext/docsrc/mdoccheat.tex new file mode 100644 index 0000000000..4063fc275a --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/mdoccheat.tex @@ -0,0 +1,113 @@ +\ProvidesFile{mdoccheat.tex}[2011/01/26 cheat sheet 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$} +\usepackage[margin=3cm]{geometry} %% 2012/03/18 +% \sfcode`/=1001 %% TODO makedoc.cfg!? 2010/03/15 +\sloppy +\begin{document} +% \enlargethispage{1\baselineskip} %% 2010/03/29 %% rm. 2012/03/18 +% \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{<out-ext>}{`doc'}, \defto{&\mdJobName}{<jobname>} + \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>}| + inputs `mdoccorr.cfg' + copies <header-lines> from <input> to <output>, + applies <main-parser> +\cmdboxitem|\CloseResultFile| closes <output> +\cmdboxitem|\MakeCloseDoc{<input>}| issues + `\MakeDoc{<input>}\CloseResultFile' +\cmdboxitem|\MakeSingleDoc[<out-ext>]{<in-output>.<in-ext>}| + issues `\LaTeXresultFile{<in-output>.<out-ext>}' + and `\MakeDocCloseDoc{<in-output>.<in-ext>}', + \defto{<out-ext>}{`doc'}, +\end{description} +%% 2012/03/18: +\textbf{d.~Avoid &\input{mdoccorr.cfg} by} +|\MakeInputJobDoc*|, |\MakeJobDoc*|, |\MakeDoc*|, +|\MakeCloseDoc*|, or |\MakeSingleDoc*| + +\end{document} + diff --git a/macros/latex/contrib/nicetext/docsrc/niceverb.tex b/macros/latex/contrib/nicetext/docsrc/niceverb.tex new file mode 100644 index 0000000000..76b503cd8b --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/niceverb.tex @@ -0,0 +1,505 @@ +\ProvidesFile{niceverb.tex}[2014/03/28 documenting niceverb.sty] +\title{\textsf{niceverb.sty}\\---\\Minimizing + Markup\\for Documenting \LaTeX\ packages\thanks{This + document describes version + \textcolor{blue}{\UseVersionOf{niceverb.sty}} + of \pkgnamefmt{niceverb.sty} as of \UseDateOf{niceverb.sty}.} +} +% \listfiles 2010/03/19 +{ \RequirePackage{makedoc} \ProcessLineMessage{} %% 2010/03/11 + \MakeJobDoc{19}{\SectionLevelThreeParseInput} } +\documentclass[fleqn]{article}%% TODO paper dimensions!? +\input{makedoc.cfg} %% shared formatting settings +\newcommand*{\secref}[1]{Sec.~\ref{sec:#1}} %% 2014/03/27 +%% 2011/08/22: +\MDkeywords{literate programming, syntactic sugar, + .txt to .tex enhancement, macro programming} +\hypersetup{%% was `syntacic' 2011/10/07: +% pdftitle=syntactic sugar for LaTeX documentation by niceverb.sty, + %% <- 2011/11/05 -> + pdftitle=niceverb.sty: syntactic sugar for LaTeX documentation, + pdfsubject=documenting niceverb.sty +}%% /2011/08/22 +\begin{document} +\maketitle +\begin{MDabstract} +% \tracingmacros=1 \tracingonline=1 +'niceverb.sty' provides very decent syntax (through active characters) +for describing \LaTeX\ packages and the syntax of macros conforming to +\LaTeX\ syntax conventions. +\end{MDabstract} +\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 \acro{WYSIWYG}).\footnote{``What you see is what you + get." Novices are always warned that \acro{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} +\emph{Four} %% 2011/01/26 +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. +\item %% 2011/01/26 +\lq\HardNVerb+<meta-variable>+\rq\ produces \lq<meta-variable>\rq. +(\qtd{&\lt} stores the original \qtd{&<}.) %% was \lessthan 2014/03/28 +\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 +% \tracingmacros=1 \tracingonline=1 +\[\HardVerbBox+\foo*[<opt-arg>]{<mand-arg>}+\] +would have sufficed---\acro{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\ '. +To get single quotes around some verbatim <verb>, +often `\qtd{&<verb>}' works. +It is for this reason that I have refrained from different +solutions as in \ctanpkgref{newverbs} (so far). + +%% 2012/10/10: +v0.44 provides |\AddQuotes| after which single quotes \emph{both} +turn their content into metacode \emph{and print} single quotes +around them \emph{automatically.} This can be turned off again by +|\DontAddQuotes|. + +\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 + %% undoubled lines 2011/05/09 + 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 +|\AddToNoVerbList}{<macros>}| %% 2010/12/29 +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\---\acro{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} + + \strong{Right Quotes:} Disabling\slash reviving replacement + of `\textsf' by single right quotes requires + \[|\nvRightQuoteNormal| \mbox{\quad or\quad } |\nvRightQuoteSansSerif|\] + %% 2014/03/27: + respectively.---The feature fails in certain occasions + because a single right quote must not always be interpreted + as `\textsf', and deciding this by macros became quite + laborious for me and is most likely still not perfect. + There is a command |\nvAllRightQuotesSansSerif| + to be used with care that interpretes \emph{all} single + right quotes as `\textsf', which, e.g., means that you + must use `\rq' for apostrophes. + + \strong{``Moving" arguments:} %% 2014/03/27 + |\NiceVerbMove{<text>}| with v0.6 is for ``moving" arguments so that + 'niceverb' syntax operates \emph{locally} at the destination + (table of contents or page headings). + It is automatically used by 'niceverb''s variant of \LaTeX's + sectioning commands; while with `\markboth', `\markright', + `\addcontentsline' etc.\ you must it include yourself + (currently, \TODO?). +\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 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 ``auto mode" seems not to work in section titles. (2011/01/26) + %% <- noted with edtnotesc +\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} + +\newpage %% 2014/03/28 +\section{The Package File} %% 2014/03/19 +% \section{The ``Package" File} %% test for page heading 2014/03/24 +% \section{`nicetext.sty'} %% tests for pageheadings 2014/03/27 +\subsection{Preliminaries} %% 2014/03/19 +\subsubsection{File Header} %% 2014/03/19 +\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 +2010/11/27 \ProvidesFile for myfilist +2010/12/29 \AddToNoVerbList +2011/01/26 using color.sty and readprov.sty; + ack. Stephan B. for <...>; auto headings issue +2011/05/09 undoubled lines about `&' +2011/08/22 using new makedoc.cfg features +2011/10/07 `syntacic' +2011/11/05 modified pdftitle +2012/10/10 \AddQuotes, \DontAddQuotes + +FOR V0.6: +2014/03/19 subsec. Preliminaries, subsubsec. Header, `Implementation + of the Markup Syntax' -> `The Package File' +2014/03/24 experiment with former +2014/03/25 debugging in abstract +2014/03/26 trying class option `fleqn' / debugging again +2014/03/27 \secref; |\NiceVerbMove|, |\nvAllRightQuotesSansSerif|; + tests +2014/03/28 debugging; \lessthan -> \lt; \newpage diff --git a/macros/latex/contrib/nicetext/docsrc/srcfiles.tex b/macros/latex/contrib/nicetext/docsrc/srcfiles.tex new file mode 100644 index 0000000000..1d932df8fa --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/srcfiles.tex @@ -0,0 +1,37 @@ +\ProvidesFile{srcfiles.tex}[2012/11/27 file infos -> SrcFILEs.txt] +\RequirePackage{filedate} %% 2012-11-13 +\RequirePackage{filesdo} %% 2012-11-26 +%% wrap, short 2012/11/09: +\RequirePackage[r,wrap]{nicefilelist} +\MaxBaseEmptyList{mdoccheat}[srcfiles.tex] +\ReadFileInfos{DOCSRC....} %% updsfl.sh +\ReadFileInfos{README,fifinddo,makedoc,niceverb} +\ReadFileInfos{mdoccheat,wikicheat} %% updsfl.sh +\ReadFileInfos{srcfiles} +\ReadFileInfos{RUN....} +\ReadFileInfos{arseneau,substr} +\ReadFileInfos{copyfile,fdtxttex} +\ReadFileInfos{fdtxttex.tpl,makedoc.tpl} +\ReadFileInfos{RUNUSE....} +\ReadFileInfos{atari.cfg,atari.fdf,u8atablg.fdf} +% \ReadPackageInfos{fddialog} +\ReadPackageInfos{fddial0g} +\ReadFileInfos{copyfile.cfg,fdtxttex.cfg} +\ReadFileInfos{USE....} +\ReadPackageInfos{fifinddo,makedoc} +\ReadFileInfos{makedoc.cfg,mdoccorr.cfg} +\ReadPackageInfos{niceverb,wiki} +\ReadFileInfos{BUNDLE....} +%\ReadFileInfos{CHANGE.LOG} +\ReadFileInfos{nicetext.RLS} +\NoStopListInfos[SrcFILEs.txt] +\ModDates +\FileDateAutoChecks* +\EqualityMessages +%% "Bases" 2012/11/12: +\DoWithBasesExts\ReadFileInfos{makedoc}{ cfg, sty, tex } +\DoWithBasesExts\ReadFileInfos{fifinddo,niceverb}{sty,tex} +\ReadFileInfos{mdoccorr.cfg,nicetext.RLS} +\DatesDiffWarnings +\CheckDateOfToday{nicetext.RLS} +\stop diff --git a/macros/latex/contrib/nicetext/docsrc/updsfl.sh b/macros/latex/contrib/nicetext/docsrc/updsfl.sh new file mode 100755 index 0000000000..4e6735173e --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/updsfl.sh @@ -0,0 +1,30 @@ +## long names for srcfiles.tex, dummy files: +ln -s substr/DOCSRC/SUBSTR.TEX substr.tex +ln -s wiki/WIKICHEA.TEX wikicheat.tex +ln -s DOCSRC/MDOCCHEA.TEX mdoccheat.tex +ln -s Arseneau/SRC/ARSENEAU.TEX arseneau.tex +ln -s RUN/SOURCE/ATARI.CFG atari.cfg +ln -s RUN/SOURCE/ATARI.FDF atari.fdf +blogsrc='../../blog/convert/SRC' +ln -s $blogsrc/U8ATABLG.FDF u8atablg.fdf +ln -s RUN/SOURCE/COPYFILE.CFG copyfile.cfg +ln -s RUN/SOURCE/COPYFILE.TEX copyfile.tex +#ln -s RUN/SOURCE/fddialog.sty fddialog.sty +ln -s RUN/SOURCE/FDDIAL0G.STY fddial0g.sty +#ln -s RUN/SOURCE/FDTXTTEX.CFG fdtxttex.cfg +ln -s $blogsrc/FDTXTTEX.CFG fdtxttex.cfg +#ln -s RUN/SOURCE/FDTXTTEX.TEX fdtxttex.tex +ln -s $blogsrc/FDTXTTEX.TEX fdtxttex.tex +ln -s RUN/SOURCE/FDTXTTEX.TPL fdtxttex.tpl +ln -s RUN/SOURCE/MAKEDOC.TPL makedoc.tpl +ln -s substr/DOCSRC/SUBSTR.TEX substr.tex +ln -s wiki/wiki.sty wiki.sty +echo \\ProvidesFile{DOCSRC....}[] > DOCSRC.... +echo \\ProvidesFile{RUN....}[] > RUN.... +echo \\ProvidesFile{RUNUSE....}[] > RUNUSE.... +echo \\ProvidesFile{USE....}[] > USE.... +echo \\ProvidesFile{BUNDLE....}[] > BUNDLE.... +latex srcfiles.tex +rm *.... *.fdf *.tpl +rm atari.* copyfile.* fd*.* +rm *cheat.tex arseneau.tex substr.tex wiki.sty diff --git a/macros/latex/contrib/nicetext/docsrc/wikicheat.tex b/macros/latex/contrib/nicetext/docsrc/wikicheat.tex new file mode 100644 index 0000000000..f80251cd77 --- /dev/null +++ b/macros/latex/contrib/nicetext/docsrc/wikicheat.tex @@ -0,0 +1,148 @@ +\ProvidesFile{wikicheat.tex}[2011/01/26 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/macros/latex/contrib/nicetext/run/README-run.txt b/macros/latex/contrib/nicetext/run/README-run.txt new file mode 100644 index 0000000000..a953d293e8 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/README-run.txt @@ -0,0 +1,9 @@ +The .tex files can be run with latex ("script files"). +arseneau.tex and substr.tex demonstrate the "auto" feature +of makedoc.sty, see makedoc.pdf. +copyfile.tex and fdtxttex.tex are dialogues. +Replace copyfile.cfg by atari.cfg to get a conversion sample. +The .tpl files are templates for script files. See FILEs.txt, +fifinddo.pdf, and makedoc.pdffor additional informations. + +UL 2011-09-14 diff --git a/macros/latex/contrib/nicetext/run/arseneau.tex b/macros/latex/contrib/nicetext/run/arseneau.tex new file mode 100644 index 0000000000..c2a59f4555 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/arseneau.tex @@ -0,0 +1,153 @@ +\ProvidesFile{arseneau.tex} + [2012/03/18 some packages by D. Arseneau (ul)] +\title{A Few Packages by Donald Arseneau} +\author{Uwe L\"uck\thanks{applying \url{http://ctan.org/pkg/nicetext}}} +% \listfiles + +%% Preprocessing: +\RequirePackage{makedoc} +% \CopyFDconditionFromTo{PScomment}{comment} +\ProcessLineMessage{} +\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} + +\ProcessLineMessage{\message{.}} +%% optional: +% \SetPatternCodes{\MakeOther\\\MakeOther\ } +\SetPatternCodes{\MakeOther\\} +\MakeExpandableAllReplacer{LaTeX:}{LaTeX:}{\LaTeX:}{LEAVE} +\PrependExpandableAllReplacer{LaTeX}[\MakeOther\ ]% +{LaTeX }{\LaTeX{} } +\PrependExpandableAllReplacer{pkg}{optional.sty}{'optional.sty'} +\PrependExpandableAllReplacer{IS}{*IS*}{\emph{is}} +\PrependExpandableAllReplacer{tildes}[\MakeOther\ ]% +{HOW TO USE}{\SECT{How to Use}} +% \SetPatternCodes{\MakeOther\~} +% \PrependExpandableAllReplacer{tildes}[\MakeOther\~]{U}{X} + %% <- TODO \MakeOther\~ hangs up +\SetCorrectHookJobLast + +\HeaderLines{14} +\LaTeXresultFile{optional.doc} +\MakeCloseDoc*{optional.sty} + + +%% Typesetting: +\documentclass{article} +\usepackage{hyperref,niceverb,wiki} %% niceverb after hyperref! +\AddToNoVerbList{\DISPLAY\textbf\enspace\emph\LaTeX\SECT} +\newcommand*{\DISPLAY}{% + \\[\smallskipamount]\leavevmode\null\hfil} +\makeatletter + \newcommand*{\SECT}[1]{% + \par\medskip\textbf{#1}\par\smallskip\@afterheading} +\makeatother +\makeatletter \MakeLetter\_ +% {\MakeActive\"\gdef\DQcode#1"{\dqtd{\texttt{#1}}}} +% {\MakeActive\"\gdef\DQcode#1"{\texttt{#1}}} +{\MakeActive\" + \gdef\DQtt{\begingroup + \let\do\MakeOther \dospecials \tt \let"\endgroup} + \gdef\fineDQ{``\begingroup + \let\do\MakeOther \dospecials \tt \def"{\endgroup''}}} +%% 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'. (On 2010/04/05, we try addressing (i) with + 'wiki.sty', applied to Donald Arseneau's 'optional'. + A 'nicetext' bug with replacing tildes shows up.) + + It should be clear that all the package desriptions are Donald Arseneau's, + 'nicetext' just formats them. +\end{abstract} +\tableofcontents +\pagebreak + +\sloppy +\MakeNormal\| + +\section{'nolbreaks'} +% \MakeActiveLet\_\textunderscore +% \MakeActive\*\def*{\texttt{\string*}} +% \MakeActiveLetHere\"\startDQcode +\MakeActiveLetHere\"\DQtt +% \errorcontextlines=6 +\AutoCmdInput{nolbreaks.doc} + +\section{'notoccite'} +\ResetCodeLineNumbers +\AutoCmdInput{notoccite.doc} + +\section{'optional'} %% 2010/04/02 +\ResetCodeLineNumbers +\wikiEnvironments +\MakeActiveLet\"\DQtt +% \AddToNoVerbList{\tracingmacros} +\let~\relax %% TODO replacement bug 2010/04/05 +\AutoCmdInput{optional.doc} + +\end{document} diff --git a/macros/latex/contrib/nicetext/run/atari.cfg b/macros/latex/contrib/nicetext/run/atari.cfg new file mode 100644 index 0000000000..c226fd434c --- /dev/null +++ b/macros/latex/contrib/nicetext/run/atari.cfg @@ -0,0 +1,6 @@ +\ProvidesFile{atari.cfg}[2011/09/13 sample for copyfile.tex] +\catcode`\_=11 +\InputFile{atari.txt} +\TextCodesFile{atari.fdf} +\ResultFile{iso.txt} +\endinput diff --git a/macros/latex/contrib/nicetext/run/atari.txt b/macros/latex/contrib/nicetext/run/atari.txt new file mode 100644 index 0000000000..8a5ffe937c --- /dev/null +++ b/macros/latex/contrib/nicetext/run/atari.txt @@ -0,0 +1,2 @@ + + diff --git a/macros/latex/contrib/nicetext/run/copyfile.cfg b/macros/latex/contrib/nicetext/run/copyfile.cfg new file mode 100644 index 0000000000..63da90bfbc --- /dev/null +++ b/macros/latex/contrib/nicetext/run/copyfile.cfg @@ -0,0 +1,6 @@ +\ProvidesFile{copyfile.cfg}[2011/09/13 initializing copyfile.tex] +\catcode`\_=11 +\InputFile{lines.txt} +\TextCodesFile{} +\ResultFile{lns.txt} +\endinput diff --git a/macros/latex/contrib/nicetext/run/copyfile.tex b/macros/latex/contrib/nicetext/run/copyfile.tex new file mode 100644 index 0000000000..f532ed4c54 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/copyfile.tex @@ -0,0 +1,23 @@ +\ProvidesFile{copyfile.tex}[2011/09/13 copy*ing/converting (UL)] +\RequirePackage{fddial0g} +\MakeSet{codes-f}{\TextCodesFile} +\let\TextCodes\relax %% avoid errmessage +\TryDialogueCFG{copyfile}{% + \InputFile{lines.txt} + \TextCodesFile{atari.fdf} + \ResultFile{lns.txt}} +\Announce{ * copyfile.tex * compressing blank lines/converting^^J} +\newcommand*{\VarShowSettings}{% + \ShowSet{in-f}\LBrk + \ShowSet{codes-f}\LBrk + \ShowSet{out-f}} +\newcommand*{\VarRunSettings}{% + \typeout{`copyfile.tex' generating `\UseSet{out-f}'} + \UseResultFile{\UseSet{out-f}} + \IfEmptySet{codes-f}{}{\input{\UseSet{codes-f}}} + \CopyFile*[\TextCodes]{\UseSet{in-f}}% +} +\DialogueLoop + +\stop + diff --git a/macros/latex/contrib/nicetext/run/fddial0g.sty b/macros/latex/contrib/nicetext/run/fddial0g.sty new file mode 100644 index 0000000000..3e3a56ab83 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/fddial0g.sty @@ -0,0 +1,192 @@ +\ProvidesPackage{fddial0g}[2011/09/13 v0.2 dialogues with fifinddo (UL)] +%% copyright (C) 2011 Uwe L\"uck, +%% +%% http://www.contact-ednotes.sty.de.vu +%% +%% -- author-maintained in the sense of LPPL below -- +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3c of the License, or any later version. +%% The latest version of this license is in +%% +%% http://www.latex-project.org/lppl.txt +%% +%% We did our best to help you, but there is NO WARRANTY. +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +\RequirePackage{fifinddo} + +\catcode`\_=11 + +%% == Setting and Using Variables == +%% %% aus `fddialog.sty' in `blog/convert/' 2011/09/12: +\newcommand*{\FDD_set}{set:} +\newcommand*{\FDD_use}{use:} +%% |\MakeSet{<id>}{<set>}| declares an internal variable `<id>' +%% and defines a command `<set>' so that `<set>{<value>}' +%% will assign <value> to <id>: +\newcommand*{\MakeSet}[2]{% + \@namedef{\FDD_set#1}{#2}% + \newcommand*{#2}{\@namedef{\FDD_use#1}} +} +%% It would be nice if there were a warning when in an evaluation +%% of a variable it turns out that it has not been ``declared" by +%% `\MakeSet' or not been set by the according setting command. +%% However, all the evaluations seem to happen in expansion +%% (e.g., during `\typeout'), so \LaTeX's `\PackageError' +%% (not even `\GenericError') is not helpful, +%% and `\errhelp' cannot be set specifically (in time). +%% It may tell more generally about `\MakeSet', but I am not sure +%% about what errors can occur in processing the dialogues at all. +%% At least we can get a real `\errmessage' using something else +%% that has not been defined: +\newcommand*{\FDD_check_use}[1]{% + \@ifundefined{\FDD_use#1}% + {\@ifundefined{\FDD_set#1}% + {\FDD_undeclared_variable `#1'}% + {\FDD_undefined_variable `#1'}}% +} +%% |\UseSet{<id>}| expands to <id>'s value. +\newcommand*{\UseSet}[1]{% + \FDD_check_use{#1}{\csname\FDD_use#1\endcsname}} +%% |\EvalBooleanSet{<id>}|: +\newcommand*{\EvalBooleanSet}[1]{% + \FDD_check_use{#1}{% + \csname + \FDD_on_setstring\@gobble{#1}%% \if id + \csname\FDD_use#1\endcsname %% true/false + \endcsname + }% +} +\newcommand*{\FDD_on_setstring}[2]{% + \expandafter\FDD_double_xpa\expandafter + #1\expandafter\expandafter\expandafter + \string\csname\FDD_set#2\endcsname} +\def\FDD_double_xpa{\expandafter\expandafter\expandafter} +%% |\IfEmptySet{<id>}{<if>}{<unless>}|: +\newcommand*{\IfEmptySet}[1]{% + \if^^J\UseSet{#1}^^J\expandafter\@firstoftwo + \else\expandafter\@secondoftwo\fi} +%% TODO present variable names by tokens!? (namemod) +%% +%% |\DebugShowSet{<id>}|: +\newcommand*{\DebugShowVar}[1]{% + \expandafter\show\csname\FDD_use#1\endcsname} +%% +%% == In/Out Variables == +%% |\ResultFile| gets a different meaning here +%% in order to keep the dialogue nice. +\let\UseResultFile\ResultFile +\let\ResultFile\relax +\MakeSet{out-f}{\ResultFile} +\MakeSet {in-f}{\InputFile} +\MakeSet{cfg-f}{\CFGname} +%% == `.cfg' == +%% |\TryDialogue{<file-name-base>}{<settings>}| +%% loads file `<file-name-base>.cfg' if \TeX\ can find it, +%% otherwise executes <settings>: +\newcommand*{\TryDialogueCFG}[2]{% + \CFGname{#1}% + \InputIfFileExists{#1.cfg}% + {\typeout{^^J + * using settings from `#1.cfg'. * + ^^J}}% + {#2}% +} +%% +%% == Screen == +\newcommand*{\Announce}[1]{% + \typeout{% + \FD_dialogue_double_line + ^^J#1^^J% + The screen shows most recent settings commands.^^J% + You can modify initial settings in + `\UseSet{cfg-f}.cfg'.^^J}% +} +%% |\DialogueLoop| is the last mandatory command in the +%% main script file. It needs an earlier definition of +%% |\VarShowSettings|. |\LBrk| can be used for a +%% screen line break: %% TODO \MessageBreak \relax!? +\newcommand*{\DialogueLoop}{% + {\def\LBrk{^^J}% + \typeout{% + \FD_dialogue_double_line^^J% + \VarShowSettings %% specific to purpose + \FD_dialogue_double_line}% + }% + \typein[\action]% + {Run with these settings? + (Y)es? (C)hange? (Otherwise quit.)}% + \csname FDD_action_\action \endcsname +} +\def\FD_dialogue_double_line{% + ^^J% + ===========================================================} +%% For defining |\VarShowSettings|: +\newcommand*{\ShowSet}[1]{% + \FDD_check_use{#1}{% +% \expandafter\expandafter\expandafter +% \string\csname\FDD_set#1\endcsname + \FDD_on_setstring\@empty{#1}% + {\UseSet{#1}}% + }% +} +\newcommand*{\TimesDo}[2]{% + \ifnum\number#1>\z@ + #2\expandafter\@firstofone + \else + \expandafter\@gobble + \fi + {\expandafter\TimesDo\expandafter + {\number\predecessor_of{#1} }{#2}}% +} +\newcommand*{\predecessor_of}[1]{% + \ifnum#1>9 + \expandafter\twodig_predecessor_of + \else + \expandafter\onedig_predecessor_of + \fi + #1} +\newcommand*{\onedig_predecessor_of}[1]{% + \ifcase #1\or0\or1\or2\or3\or4\or5\or6\or7\or8\or9\fi} +\newcommand*{\twodig_predecessor_of}[2]{% + \ifcase #2 + \onedig_predecessor_of#19\or + #10\or#11\or#12\or#13\or#14\or#15\or#16\or#17\or#18\or#19\fi} + +\newcommand*{\Spaces}[1]{\TimesDo{#1}{\space}} + +%% +%% == Changing Settings == +%% When the user types `c' or `C', she is asked to input +%% replacement text for the macro |\change|. +%% This macro then is executed, and |\DialogueLoop| +%% is invoked again: +\newcommand*{\FDD_action_c}{\FDD_change_settings} +\newcommand*{\FDD_action_C}{\FDD_change_settings} +\newcommand*{\FDD_change_settings}{% + \typein[\change]{^^JType setting command(s).}% + \change \DialogueLoop} +%% == Running with Current Settings == +\newcommand*{\FDD_action_y}{\FDD_run_with_settings} +\newcommand*{\FDD_action_Y}{\FDD_run_with_settings} +%% When the user types `y' or `Y', the following macro is executed. +%% It invokes |\VarRunSettings| that must be defined +%% before `\DialogueLoop' is executed: +\newcommand*{\FDD_run_with_settings}{% + \VarRunSettings %% specific to purpose + \CloseResultFile + \typeout{Done.}% + \DialogueLoop} +%% +%% == The End == +\endinput + +== VERSION HISTORY == + +v0.1 2011/08/23 first, uploaded with NICETEXT r0.43 +v0.2 2011/09/12 merged with something earlier/better, messages + 2011/09/13 messages more carefully: ...undefined_var..., + \EvalBooleanSet, \TimesDo with two digits diff --git a/macros/latex/contrib/nicetext/run/fdtxttex.cfg b/macros/latex/contrib/nicetext/run/fdtxttex.cfg new file mode 100644 index 0000000000..452ea5173a --- /dev/null +++ b/macros/latex/contrib/nicetext/run/fdtxttex.cfg @@ -0,0 +1,9 @@ +\ProvidesFile{fdtxttex.cfg}[2011/09/13 initializing fdtxttex.tex] +\JobName{sample} +\InputExtension{txt} +\OutputExtension{tex} +\CorrectionFile{mdoccorr.cfg} +\FileHeader{\protect\WriteProvides} +\FileFooter{} +\ShowLines{false} +\endinput diff --git a/macros/latex/contrib/nicetext/run/fdtxttex.tex b/macros/latex/contrib/nicetext/run/fdtxttex.tex new file mode 100644 index 0000000000..0c17662f5d --- /dev/null +++ b/macros/latex/contrib/nicetext/run/fdtxttex.tex @@ -0,0 +1,54 @@ +\ProvidesFile{fdtxttex.tex}[2011/09/13 txt to TeX by dialogue (UL)] +\RequirePackage{fddial0g} +% \errorcontextlines=4 +\MakeSet{job-name}{\JobName} +\MakeSet{in-ext} {\InputExtension} +\MakeSet{out-ext} {\OutputExtension} +\MakeSet{corr-f} {\CorrectionFile} +\MakeSet{f-head} {\FileHeader} +\MakeSet{f-foot} {\FileFooter} +\newif\ifShowLines +\MakeSet{show-l} {\ShowLines} +\TryDialogueCFG{fdtxttex}{% + \JobName{sample} + \InputExtension{txt} + \OutputExtension{tex} + \CorrectionFile{mdoccorr.cfg} + \FileHeader{\protect\WriteProvides} + \FileFooter{} + \ShowLines{false} +} +% \DebugShowVar{cfg-f} +\Announce{ *fdtxttex.tex* txt to TeX by dialogue^^J + (apply \string\MakeDocCorrectHook)^^J} +\newcommand*{\VarShowSettings}{% + \ShowSet{job-name}\LBrk\Spaces{15} + \ShowSet{in-ext} \space + \ShowSet{out-ext}\LBrk + \ShowSet{corr-f} + (define \BackslashChar MakeDocCorrectHook)\LBrk + \ShowSet{f-head}\LBrk + \ShowSet{f-foot}\LBrk + \Spaces{15} + \ShowSet{show-l} +}% +\newcommand*{\VarRunSettings}{% + \input{\UseSet{corr-f}}% + \typeout{`fdtxttex.tex' generating + `\UseSet{job-name}.\UseSet{out-ext}'.}% + \UseResultFile{\UseSet{job-name}.\UseSet{out-ext}}% + \IfEmptySet{f-head}{}{\UseSet{f-head}}% + \EvalBooleanSet{show-l}% + \ProcessFileWith{\UseSet{job-name}.\UseSet{in-ext}}{% + \WriteResult{\CorrectedInputLine}% + \ifShowLines + \typeout{\CorrectedInputLine}% + \else + \message{.}% + \fi}% + \IfEmptySet{f-foot}{}{\UseSet{f-foot}}% +} + +\DialogueLoop + +\stop diff --git a/macros/latex/contrib/nicetext/run/fdtxttex.tpl b/macros/latex/contrib/nicetext/run/fdtxttex.tpl new file mode 100644 index 0000000000..b50b9f79c2 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/fdtxttex.tpl @@ -0,0 +1,11 @@ +\ProvidesFile{fdtxttex.tpl}[2011/09/13 fifinddo correction template] +\RequirePackage{fifinddo} +\input{mdoccorr.cfg} +\ResultFile{sample.tex} +\WriteProvides +\ProcessFileWith{sample.txt}{% + \typeout{\CorrectedInputLine}% + \WriteResult{\CorrectedInputLine}% +} +\CloseResultFile +\stop diff --git a/macros/latex/contrib/nicetext/run/lines.txt b/macros/latex/contrib/nicetext/run/lines.txt new file mode 100644 index 0000000000..6668143465 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/lines.txt @@ -0,0 +1,4 @@ +abba + + +abba
\ No newline at end of file diff --git a/macros/latex/contrib/nicetext/run/makedoc.tpl b/macros/latex/contrib/nicetext/run/makedoc.tpl new file mode 100644 index 0000000000..69b2b957a2 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/makedoc.tpl @@ -0,0 +1,14 @@ +\ProvidesFile{makedoc.tpl}[2011/09/14 + makedoc preprocessing template] +\RequirePackage{makedoc} +\renewcommand*{\mdJobName}{SAMPLE} +\input{mdoccorr.cfg} +\LaTeXresultFile{\mdJobName.doc} +\HeaderLines{0} +\ProcessLineMessage{} +\MainDocParser{% +% \WriteResult{\ProcessInputWith{dots}}% + \WriteResult{\CorrectedInputLine}% +} +\MakeCloseDoc{\mdJobName.TEX} +\stop diff --git a/macros/latex/contrib/nicetext/run/sample.txt b/macros/latex/contrib/nicetext/run/sample.txt new file mode 100644 index 0000000000..69408f90fd --- /dev/null +++ b/macros/latex/contrib/nicetext/run/sample.txt @@ -0,0 +1,3 @@ +blabla ... blabla +blabla cf. bla +etc. bla bla
\ No newline at end of file diff --git a/macros/latex/contrib/nicetext/run/substr.tex b/macros/latex/contrib/nicetext/run/substr.tex new file mode 100644 index 0000000000..64f202f0e9 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/substr.tex @@ -0,0 +1,97 @@ +\ProvidesFile{substr.tex}[2012/03/18 documentation for substr.sty] +\title{\textsf{substr.sty}\thanks{See + \url{http://ctan.org/pkg/substr} for more about + \textsf{substr.sty}.}---Substring + Functions with \LaTeX} +\author{Harald Harders\thanks{Joint work with Heiko Oberdiek, + one line + documentation tool + by Uwe L\"uck.}} +% \listfiles + +%% 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} +\usepackage{ragged2e} %% 2012/03/18 + +\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 +\RaggedRight +% \MakeJobDoc{3}{\ProcessInputWith{comment}} +\AutoCmdInput{substr.doc} +\enlargethispage{\baselineskip} +\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 +2011/08/20 \ProvidesFile for fileinfo +2012/03/18 use \MakeCloseDoc*, \enlargethispage, ragged2e + diff --git a/macros/latex/contrib/nicetext/run/u8atablg.fdf b/macros/latex/contrib/nicetext/run/u8atablg.fdf new file mode 100644 index 0000000000..17a28555e6 --- /dev/null +++ b/macros/latex/contrib/nicetext/run/u8atablg.fdf @@ -0,0 +1,34 @@ +\ProvidesFile{u8atablg.fdf}[2011/09/12 UTF-8->Atari/blog with fdtxttex] +\SetPatternCodes{\MakeOther\&\MakeOther\\\MakeOther\ } +\StartPrependingChain +\PrependExpandableAllReplacer{amp} {&}{\&} +%% <- for blog.sty. Next are Atari umlauts, +%% cf. 'umlaute' documentation: +\PrependExpandableAllReplacer{auml} {ä}{} +\PrependExpandableAllReplacer{ouml} {ö}{} +\PrependExpandableAllReplacer{uuml} {ü}{} +\PrependExpandableAllReplacer{szlig}{ß}{} +\PrependExpandableAllReplacer{Auml} {Ä}{} +\PrependExpandableAllReplacer{Ouml} {Ö}{} +\PrependExpandableAllReplacer{Uuml} {Ü}{} +%% ... TODO as \TextCodes!? `' one-parameter macro +%% there must be no space left of last argument. +%% `\endash{}' is not a solution because 'blog.sty' +%% then would display the braces: +\PrependExpandableAllReplacer{apostr} {’}{'} +\PrependExpandableAllReplacer{item} {•}{\item } +\PrependExpandableAllReplacer{item } {• }{\item\ } +\PrependExpandableAllReplacer{endash} {–}{\endash } +\PrependExpandableAllReplacer{endash }{– }{\endash\ } +\PrependExpandableAllReplacer{hellip} {…}{\dots } +\PrependExpandableAllReplacer{hellip }{… }{\dots\ } +\PrependExpandableAllReplacer{to} {→}{\to } +\PrependExpandableAllReplacer{to } {→ }{\to\ } +% \newcommand*{\PXAR}{\PrependExpandableAllReplacer} +% \PXAR{dots}{...}{.\kern\fontdimen3\font.\kern\fontdimen3\font.} +%% Tomboy 2011/09/12: +% \PrependExpandableAllReplacer {it} {<italic>}{<i>} +% \PrependExpandableAllReplacer{/it}{</italic>}{</i>} +\SetCorrectHookJobLast +\endinput + diff --git a/macros/latex/contrib/nicetext/use/fifinddo.sty b/macros/latex/contrib/nicetext/use/fifinddo.sty new file mode 100644 index 0000000000..3094a930a8 --- /dev/null +++ b/macros/latex/contrib/nicetext/use/fifinddo.sty @@ -0,0 +1,1153 @@ +%% Macro package `fifinddo.sty' for LaTeX2e, %% FIDO, FIND! +%% copyright (C) 2009-2012 Uwe L\"uck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% for processing tex(t) files +%% (checking, filtering, converting, substituting, expanding, ...) + +\def\fileversion{0.61} \def\filedate{2012/11/17} + +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3c of the License, or any later version. +%% The latest version of this license is in +%% +%% http://www.latex-project.org/lppl.txt +%% +%% We did our best to help you, but there is NO WARRANTY. +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +%% For the full documentation, look for `fifinddo.pdf'. +%% Its source starts in `fifinddo.tex'. +%% +%% === Format and package version === +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +% 1994/12/01: \newcommand* etc. +\ProvidesPackage{fifinddo}[\filedate\space v\fileversion\space + filtering TeX(t) files by TeX (UL)] +%% +%% === Category codes === +%% We use the ``underscore" as ``compound identifier:" +\RequirePackage{stacklet} \PushCatMakeLetter\_ %% 2012/08/27 +%% v0.6 moves definition of |\MakeActiveDef| to 'actcodes' +%% in the 'catcodes' bundle: +\RequirePackage{actcodes} +%% 'fifinddo' uses \TeX's feature of delimited macro parameters +%% for matching \emph{strings} of characters. +%% In order to get expected results, \emph{category codes} must match as well. +%% |\PatternCodes| is used in setup macros for reading patterns +%% for this purpose. It defaults to |\fdPatternCodes|. +%% We offer |\SetPatternCodes{<commands>}| +%% for redefining `\PatternCodes' +%% and |\ResetPatternCodes| for returning to `\fdPatternCodes', +%% so setup scripts such as 'mdoccorr.cfg' have shorter lines. +\newcommand*{\fdPatternCodes}{\MakeOther\&\MakeOther\$} +\newcommand*{\SetPatternCodes}{\def\PatternCodes} +\newcommand*{\ResetPatternCodes}{\let\PatternCodes\fdPatternCodes} +\newcommand*{\PatternCodes}{} \ResetPatternCodes + %% TODO adding/removing; `*' may be wrong 2010/03/29 +%% +%% It would be bad to have `\MakeOther\%' and `\MakeOther\ ' here in +%% that this may have unexpected, weird effects with arguments of +%% setup macros. (With `\MakeOther\ ' you must not indent within a +%% setup command, and if you add `\MakeOther\%' the setup command +%% must stay in one line.) +%% Therefore neither `\dospecials' nor `\@sanitize' are +%% used. Curly braces remain untouched as default delimiters in setup +%% macros. For matching them, you must use `\MakeOther\{' and +%% `\MakeOther\}' %% corr. 2010/11/09 +%% in your `\PatternCodes', or |\Delimiters| to introduce +%% new ones at the same time, e.g., `\Delimiters\[\]': +\newcommand*{\Delimiters}[2]{% + \MakeOther\{\MakeOther\}\CatCode#1\@ne \CatCode#2=\tw@} +%% |\CatCode\<char>| is introduced for v0.6. +%% It should appear in a package 'manycats' of the 'catcodes' +%% bundle, but that's to much for 2012/08/27---TODO. +\providecommand*{\CatCode}{\catcode`} +%% For replacing strings or for defining other strings of ``other" +%% characters by `\edef', you can use some \LaTeX\ constructs---here +%% are copies |\PercentChar| and |\BackslashChar| of them +%% (do you need more?): +\newcommand*{\PercentChar}{} \let\PercentChar\@percentchar +\newcommand*{\BackslashChar}{} \let\BackslashChar\@backslashchar +%% %% <- corr. typo 2010/11/25 +%% +%% |\BasicNormalCatcodes| restores Plain~\TeX's +%% \textbf{macro parsing} and comment character: +\newcommand*{\BasicNormalCatCodes}{% + \CatCode\\\z@ \Delimiters\{\}% +% \restorecr !? + \CatCode\ =10 \CatCode\%=14} +%% However, reading files \emph{line by line} makes parsing of +%% macro parameters somewhat difficult +%% when the parameter code spans code lines. +%% A line must not end with a curly brace when a macro requires +%% another parameter; instead, it must contain the curly left +%% brace for the next parameter. +%% +%% `\BasicNormalCatCodes' may be reimplemented by a package +%% 'normcats' in the 'catcodes' bundle---TODO~... +%% +%% %% rm. \MakeActiveDef 2012/08/27 +%% +%% == File handling == +%% %% structured 2011/11/19 +%% Peter Wilson's \ctanpkgref{newfile} +%% provides more powerful file handling. +%% % <- TODO relevant? 2009/04/12 +%% +%% === Opening, Writing to, Closing Output === +%% \label{sec:output} +\newwrite\result_file %% or write to \@mainaux!? TODO +%% |\ResultFile{<output>}| opens (and empties) a file +%% <output> to be written into. +\newcommand*{\ResultFile}[1]{% + \def\result_file_name{#1}% + \typeout{`fifinddo' generating `\result_file_name'}% %% 2011/10/23 + \immediate\openout\result_file=#1} +%% |\WriteResult{<balanced>}| writes a <balanced> line into +%% <output> (or more lines with `^^J'). +\newcommand*{\WriteResult}[1]{% + \immediate\write\result_file{#1}} +%% |\WriteProvides| writes a `\ProvidesFile' command to the +%% opened <output> file. This should be used when <output> +%% is made as \LaTeXe\ input. +\newcommand*{\WriteProvides}{% + \WriteResult{% + \string\ProvidesFile{\result_file_name}% + [\the\year/\two@digits\month/\two@digits\day\space + automatically generated with fifinddo.sty]}}% +%% |\CloseResultFile| closes <output>: +\newcommand*{\CloseResultFile}{% + \immediate\closeout\result_file + \typeout{`fifinddo' %% 2011/10/23 + \space\space\space %% 2011/10/26 + closing `\result_file_name'}} +%% +%% === Processing Input === +%% \label{sec:input} +%% %% opt arg 2010/04/06: +%% |\ProcessFileWith[<changes>]{<input>}{<loop-body>}| +%% opens a file <input> +%% and runs a loop on its lines the main body of which is <loop-body>. +%% When the <loop> starts, a new line of <input> is stored as macro +%% |\fdInputLine|. The optional argument <changes> may change +%% category codes used in reading <input>. It may be useful to +%% read macros with arguments and active characters expanding +%% in writing to the output file. Even these expansions may be +%% defined here (local to the group like everything else +%% happening here, unless ...). +%% Macros |\BasicNormalCatcodes| and |\MakeActiveDef| +%% have been created for this purpose (see previous section TODO). +%% (It may be better to store +%% these <changes> in another macro <macro> and to call +%% `\ProcessFileWith[<macro>]{<input>}{<loop-body>}'). +%% More possible uses of some usual \TeX\ category codes may be +%% (some of) +%% \begin{itemize} +%% \item avoiding matching substrings of control words, +%% \item skipping blank spaces as \TeX\ does it usually, +%% %% <- macro parsing + ...!? +%% \item catching \emph{balanced} input pieces, +%% \item ignoring comments, +%% \item ignoring certain characters. +%% \end{itemize} +\newcommand*{\ProcessFileWith}[3][]{% +%% v0.5: Variant of \LaTeX's `\IfFileExists'---failed so far +%% because I had omitted the blank space: + \openin\@inputcheck#2 % space essential! 2011/11/19 + \ifeof\@inputcheck + \PackageError{fifinddo}{File `#2' not here}% + {Mistyped?}% + \else + \typeout{`fifinddo' processing `#2'}%% 2010/04/15 +%% %% 2011/11/19: +%% ... moves into conditional with v0.5. Resetting line counter: + \global\c@fdInputLine=\z@ + \begingroup + \MakeOther\{\MakeOther\}\@sanitize +%% ... switching into ``plain text mode"; from `docstrip.tex': + % \MakeOther\^^A\MakeOther\^^K%% irrelevant, not LaTeX +%% <- cf. \TeX book +%% pp.~43ff., 368ff., %% 2011/11/19 +%% ``extended keyboards", up-/downarrow; +%% -> ``math specials", cf. ``space specials" + \endlinechar\m@ne + \MakeOther\^^I% ASCII horizontal tab -- guessed!? ^^L!? +%% With v0.31, we support non-ASCII: + \count@=128 + \loop + \ifnum\count@<\@cclvi + \catcode\count@=12 + \advance\count@\@ne + \repeat + #1% + \loop \ifeof\@inputcheck \else + \read\@inputcheck to \fdInputLine + \ignorespaces #3% +%% v0.42 supports |\IfFDpreviousInputEmpty|, +%% cf. section \ref{sec:tails}: + \expandafter \let + \expandafter \IfFDpreviousInputEmpty + \ifx\fdInputLine\@empty \@firstoftwo + \else \@secondoftwo \fi + \repeat + \endgroup + \fi + \closein\@inputcheck +%% Added for v0.5, cf. Sec.~\ref{sec:final-input} + \ifFinalInputFile + \CloseResultFile \FinalInputFilefalse + \fi +} +%% % TODO: write EOF for debugging!?---%% 2010/03/18 +%% % Another difference to some \ctanpkgref{verbatimcopy} +%% % is that `\CopyFile' really was meant to +%% % be used for creating a \acro{HTML} file from some \emph{number} of +%% % sources, especially for shared head sections (however, +%% % I have used macros for this purpose so far), a navigation column, +%% % the main varying ``blog-like" content, and finally a shared +%% % footer section. +%% % In the meantime, however, I have chosen another variant +%% % for generating \acro{HTML} that +%% % replaces an empty line by a line consisting of \verb+<p>+. +%% % +%% |\CopyFile[<changes>]{<file>}| +%% is an application of `\ProcessFileWith' +%% that ``copies" the content of file <file> +%% into the file specified by +%% `\ResultFile'. %% was `\WriteResult'. 2011/08/06 +%% However, optional <changes> allows some +%% ``modifications" while ``copying"---especially, +%% conversion of text encodings by active characters +%% and expanding macros for generating \acro{HTML} +%% or other code. The ``starred" variant +%% |\CopyFile*| copies one empty line only +%% when one empty line in the input file is followed +%% by more of them. +\newcommand*{\CopyFile}{% + \@ifstar{\let\FD@copy@style\FD@compress@voids \FD@copyfile}% + {\let\FD@copy@style\CopyLine \FD@copyfile}} +\newcommand*{\FD@copyfile}[2][]{% + \ProcessFileWith[#1]{#2}{\FD@copy@style\message{.}}} +%% % <- message 2010/11/13; 2011/08/22: +%% You should find a file `copyfile.tex' providing a dialogue +%% for ``compressing" files this way. As soon as you have a +%% useful conversion mapping file (defining |\TextCodes|), +%% you can also use it for text encoding conversions. +%% +%% |\CopyLine|: +\newcommand*{\CopyLine}{\WriteResult\fdInputLine} +%% (... added `\space' without success with macro arguments +%% 2010/04/26 --- `\BlogCodes' has used a better solution +%% later). +\newcommand*{\FD@compress@voids}{% + \IfFDinputEmpty{\IfFDpreviousInputEmpty\relax\CopyLine}% + \CopyLine} +%% +%% === A Combining Shorthand === +%% \label{sec:final-input} +%% Before v0.5, the general idea was that some number of \strong{input} +%% files would be combined for creating a single \strong{output} file +%% (e.g., as opposed to \ctanpkgref{verbatimcopy}, regarding +%% `\CopyFile'). +%% According to experience, however, a \strong{single} input file +%% typically suffices for generating an output file. +%% Then |\CloseResultFile| (Sec.~\ref{sec:output}) +%% may be called ``implicitly". The flag |\ifFinalInputFile| +%% will control (and generalize!) this +%% (in `\ProcessFileWith', Sec.~\ref{sec:input}), +%% and will be reset if changed +%% (thinking of generating another file in the same \TeX\ run). +%% +%% So +%% |\ProcessFinalFileWith[<changes>]{<input>}{<loop-body>}| +%% % |\ProcessFinalFileWith| works like `\ProcessFileWith' +%% works as with `\ProcessFileWith' +%% except that `\CloseResultFile' is issued after processing, +%% so you can omit the latter. +\newif\ifFinalInputFile +\newcommand*{\ProcessFinalFileWith}{% + \FinalInputFiletrue \ProcessFileWith} +%% +%% \pagebreak %% 2011/11/19 again +%% == Basic handling of substring conditionals == +%% \label{sec:theory} +%% %% TODO move theory to fifinddo.tex 2009/04/12 +%% === ``Substring Theory" === +%% \begin{flushright}\it +%% I wished I could study string theory,\\ +%% but I only could study substring theory. +%% \end{flushright} +%% A \TeX\ macro, say, `\find' whose parameter text +%% (cf. \TeX book p.~203) +%% starts with `#1<pattern>#2&' stops \TeX\ with an error if it does +%% not find <pattern> and then `&'. Otherwise we have a situation +%% `\find<split1><pattern><split2>&', and `\find' reads <split1> as +%% #1 and <split2> as #2. An important point to note is that <split1> +%% will not contain <pattern>, but possibly <pattern> has more +%% occurrences in <split2>. In this sense, `\find' uses the +%% \emph{first} occurrence of <pattern> it finds in order to delimit #1. +%% Finding the \emph{last} occurrence of <pattern> therefore needs a +%% special idea. +%% +%% In order to use `\find' for a test whether <pattern> is in +%% <target>, we build a ``sandbox" |\find<sand>&|, where <sand> +%% contains <target> \emph{and additionally} <pattern>---as a +%% ``dummy;" so `&' delimits the search and `\find' finds +%% <pattern> either in <target> or somewhere else before `&'. +%% +%% Consider the simple sandbox |\find<target><pattern>&|. +%% We can test #1 and #2 on being empty by `\ifx$#1$' and `\ifx$#2$'. +%% If #2 is empty, <pattern> is \emph{not} in <target>. +%% If #1 is empty at the same time, <target> is empty. +%% If #1 is empty and #2 is not, <pattern> \emph{starts} +%% <target>!\footnote{%% 2011/01/25: +%% This is just as wrong as the next claim.} +%% This can be used to implement +%% Wikipedia-like lists %% TODO 2009/04/11 +%% and to distinguish package code from comments in +%% 'makedoc'.\footnote{%% 2011/01/25: +%% Due to the special substrings to test in this +%% application, this is true although the +%% surrounding claims are wrong.} +%% +%% If #2 is \emph{not} empty, <pattern> occurs in <target>---or this once +%% was \emph{thought}, some time in developping the present package, +%% as well as in the version of 'substr.sty' marked +%% `2005-11-29',\footnote{\url{http://ctan.org/pkg/substr}. +%% 'substr' does not change category codes +%% as 'fifinddo' does +%% and uses \cs{@nil} as delimiter instead of +%% our &&.} try +%% (if that version still is installed)\footnote{The ``feature" has +%% been fixed with v1.2 as of 2009/10/20 of +%% 'substr.sty'.} +%% \[`\IfSubStringInString{<str1><str2><str1>}{<str1><str2>}{YES}{NO}'\] +%% which works \emph{verbatim} as well as considering <str1> and +%% <str2> \emph{placeholders}, e.g., for +%% \begin{center} +%% `\IfSubStringInString{day after day}{day after }{YES}{NO}'\footnote{% +%% Likewise \texttt{t\string\^ete-\string\`a-t\string\^ete} ...}\\ +%% %% <- `e' was missing 2010/03/17 +%% `\IfSubStringInString{AMSTERDAM}{AMSTERD}{YES}{NO}'\\ +%% `\IfSubStringInString{TORONTO}{TORON}{YES}{NO}'\\ +%% `\IfSubStringInString{bonbon}{bon}{YES}{NO}'\footnote{% +%% Polynesian: `aku aku', `rongorongo', `wiki wiki' ...}\\ +%% `\IfSubStringInString{bonobo}{bono}{YES}{NO}' +%% (an ape) +%% \end{center} +%% or `\IfSubStringInString{ionization}{ionizat}{YES}{NO}'.\footnote{% +%% Read 'substr.sty' or try ``normal" things to convince yourself +%% that the syntax indeed is +%% &\IfSubStringInString{<pattern>}{<target>}{<yes>}{<no>}.} +%% Same with \LaTeX's internal `\in@':\footnote{\cs{in@} has been +%% fixed after my warning on Heiko Oberdiek's proposal---at +%% least in the repository.---On 2009/04/21 +%% I learn from Manuel P\'egouri\'e-Gonnard +%% that the first versions of his 'ted' +%% had a similar bug, fixed on v1.05 essentially like here; +%% Steven Segletes confirms that his 'stringstrings' doesn't +%% suffer the problem (returning positions of substrings and +%% numbers of occurrences).} +%% \begin{center} +%% % \[ +%% `\makeatletter \in@{bonbon}{bon}\ifin@ YES\else NO\fi \makeatother' +%% %% \makeatletter \in@{bonbon}{bon}\ifin@ YES\else NO\fi \makeatother +%% %% \IfSubStringInString{ionization}{ionizat}{YES}{NO} +%% % \] +%% \end{center} +%% +%% In general, the previous approach \emph{fails if and exactly if} +%% <pattern> has a \emph{period} $p$---less than its length---in the sense of that +%% the $p$th token to the right or left of each token in <pattern> +%% is the \emph{same} token. +%% `AMSTERDAM' has a period 7, %% was 8 2011/01/20 +%% `day after day' 10, `bonbon' 3, `bonobo' 4. +%% There is a counterexample <target> of length $p$ iff +%% <pattern> has period $p$, namely the first substring of <pattern> +%% having length $p$. If the length of <pattern> exceeds a multiple +%% $mp$ of its period, the first $mp$ tokens of <pattern> form +%% a counterexample <target>. +%% +%% Therefore, a sandbox must have something between <target> and +%% <pattern>.\footnote{Must? Actually, I preferred this solution to +%% other ideas like measuring the length of <split2>.} +%% We choose |\find<target>~<pattern>$&| as standard. +%% The `$' will be used as an argument delimiter to get rid of the dummy +%% <pattern> in <split2>, as well as to decide whether the match was +%% in <target> or in the dummy part of the sandbox. +%% The `$' can be replaced by another tilde `~' in order to +%% test whether <target> \emph{ends} on a <pattern>, defining a macro +%% like `\findatend' whose parameter text starts with `#1<pattern>~#2&'. +%% +%% === Plan for proceeding === +%% When we check a file for several patterns, we seem to need +%% \emph{two} macros for each pattern: one that has the pattern +%% in its parameter text and one that stores the pattern for building +%% the sandbox.\footnote{If it were for the pattern only, the parsing +%% macro might suffice and the macro calling it might extract the +%% pattern from a ``dummy expansion." Somewhat too much for me now; +%% on the other hand the calling macro also hands some ``current" +%% informations to the parsing macro---oh, even this could be +%% handled by a general ``calling" macro \dots} +%% %% TODO 2009/04/15 +%% We use a separate \emph{``name space"} for each of +%% both kinds. The parsing macro and the macro building the sandbox +%% will have a common \emph{``identifier"} by which the user or +%% programmer calls them. Actually, she will usually (first) call +%% the sandbox box builder. The sandbox builder calls the parsing +%% macro. When \emph{all} occurrences of a pattern in the target are +%% looked for, the parser may call itself. +%% +%% Actually, the parsing macro will execute certain actions +%% depending on what it finds in the sandbox, so we call it a +%% \emph{``substring conditional"}. It may read additional arguments +%% after the sandbox that store information gathered before. +%% This is especially useful for designing \emph{``expandable"} +%% chains (sequences) of conditionals where macros cannot store information in +%% macros. The macro setting up the sandbox will initialize such +%% extra arguments at the same time. +%% +%% It may be more efficient \emph{not} to use the following setup +%% macros but to type the macros yourself, just using the following +%% as templates. The setup macros are especially useful with patterns +%% that contain ``special characters," as when you are looking for +%% %% TODO repetition of single right quote not working 2010/03/19 +%% lines that might be package comments. +%% +%% === Meta-Setup === +%% +%% A setup command <setup-cmd> will have the following syntax: +%% \[|<setup-cmd>{<job-id>}[<changes>]{<pattern>}<more-args>|\] +%% <changes> will, in the first instance, be category code changes +%% for reading <pattern> overriding the settings in `\PatternCodes'. +%% They are executed after the latter in a local group. +%% It may be safer to redefine `\PatternCodes' instead +%% of using the optional <changes> argument. +%% +%% A macro +%% \[|\StartFDsetup{<do-setup>}{<job-id>}[<changes>]|\] +%% shared by setup commands +%% may read <job-id> and <changes> for <setup-cmd>. +%% |<do-setup>| will be the macro that reads <pattern> (and more) +%% and processes it. It must contain `\endgroup' to match +%% `\begingroup' from `\FD_prepare_pattern'. +%% <job-id> is stored in a macro |\fdParserId|. +%% The default for <changes> is \emph{nothing}. +\newcommand*{\StartFDsetup}[1]{% + \let\FD_do_setup#1% + \afterassignment\FD_prepare_pattern + \def\fdParserId} +\newcommand*{\FD_prepare_pattern}[1][]{% + \begingroup \PatternCodes #1\FD_do_setup} +%% So <setup-cmd> should be set up about as follows: +%% \begin{quote} +%% `\newcommand*{<setup-cmd>}{\StartFDsetup<do-setup>}'\\ +%% `\newcommand*{<do-setup>}[<args>]{<action>}' +%% \end{quote} +%% <do-setup>'s first argument will be the <pattern> argument +%% of <setup-cmd>.---With v0.5, we learn from the previous and provide +%% \[|\MakeSetupCommand{<setup-cmd>}{<do-setup>}[<args>]{<action>}|\] +\newcommand*{\MakeSetupCommand}[2]{\newcommand*#1{\StartFDsetup#2}% + \newcommand*#2} +%% +%% === Setup for conditionals === +%% `substr_cond' is the ``name space" for substring conditionals. +%% A colon separates it from \emph{``job identifiers"} in the actual +%% macro names. +\def\substr_cond{substr_cond:} +%% +%% |\MakeSubstringConditional{<id>}[<changes>]{<pattern>}| +%% starts the definition of a conditional with identifier <id> +%% and pattern <pattern>. <changes> optionally add commands to +%% be executed after `\PatternCodes' in a local group. +%% `\begingroup' |\mk_substr_cond{<pattern>}| %% TODO!? 2010/03/22 +%% can be directly called by other programmer setup commands when +%% `\fdParserId' and <pattern> have been read. +\MakeSetupCommand{\MakeSubstringConditional}{\mk_substr_cond}[1]{% + %% #1 pattern string + \endgroup \@namedef{\substr_cond \fdParserId}##1#1##2&} +%% This really is not \LaTeX. We are starting defining a macro +%% `\substr_cond:<id>' in primitive \TeX\ with `\def' in the form +%% \[`\def\substr_cond:<id>#1<pattern>#2&'\] +%% where `\csname' etc. render \lq`:<id>'\rq\ part of the macro +%% name.\footnote{%% 2010/11/27: +%% Loosely speaking of ``the parser" <parser> around +%% here somehow refers to this macro---but rather to +%% its ``parameter text" only, +%% according to \TeX book p.~203. Such a macro, +%% however, won't ``parse" only, but it will also +%% execute some job on the results of parsing. +%% Or: a ``mere parsing" macro might be macro that +%% transforms a ``weird" Plain \TeX\ parameter text +%% into a ``simple" parameter text of another macro, +%% consisting of hash marks and digits only. E.g.: +%% &\def&\Foo#1<pattern>#2&&{&\foo{#1}{#2}}.} +%% The user or programmer macro produces the part of the definition +%% until the delimiter `&' to match the sandbox. You have to add +%% (maybe) #3 etc. and the `{<definition text>}' +%% just as with primitive \TeX. +%% +%% === Setup for sandboxes === +%% There was a \emph{question:} will we rather see +%% \emph{string macros} or \emph{strings from macro arguments}? +%% The input file content always comes +%% as `\fdInputLine' first, so we at least \emph{must account} for +%% the possibility of string macros as input. +%% +%% One easy way to apply several checks and substitutions to +%% `\fdInputLine' before the result is written to <output> is +%% `\let\OutputString\fdInputLine' and then let `\OutputString' +%% be to what each job refers as \emph{its} +%% input and output, finally `\WriteResult{\OutputString}'. +%% (`\fdInputLine' might better not be touched, it could be used +%% for a final test whether any change applied for some message on +%% screen, even with an entirely expandable chain of actions.) +%% This way each job, indeed each recursive substitution of a single +%% string must start with expanding `\OutputString'. +%% +%% On the other hand, there is the idea of \emph{``expandable" +%% chains of substitutions}. We may, e.g., define a macro, say, +%% `\manysubstitutions{<macro-name>}', such that +%% `\WriteResult{\manysubstitutions{\fdInputLine}}' +%% writes to <output> the result of applying many expandable +%% substitutions to `\fdInputLine'. +%% Such a macro `\manysubstitutions' may read `\fdInputLine', +%% but it must not redefine any macros. +%% Instead, the substitution macros it calls must read results +%% of previous substitutions as \emph{arguments}. +%% +%% Another aspect: +%% the order of substitutions should be easy to +%% change. Therefore expanding of string macros should rather be +%% controlled by the way a job is \emph{called}, not right here +%% at the \emph{definition} of the job. For this reason, +%% a variant of the sandbox builder expanding some macro was given up. +%% %% <- TODO!? 2010/03/25 + +%% `setup_substr_cond' is the name space for macros that build +%% sandboxes and initialize arguments for conditional macros. +\def\setup_substr_cond{setup_substr_cond:} +%% \begin{center} %% 2011/11/13 +%% |\MakeSetupSubstringCondition{<id>}[<changes>]{<pattern>}{<more-args>}| +%% \end{center} +%% % <- TODO allow `%' and ` ' for breaking code lines. +%% ---same <id>, <changes>, <pattern> as for +%% `\MakeSubstringConditional' (this is bad, there may be +%% |\MakeSubstringConditional*{<more-args>}|)---creates the +%% % <- TODO: store args in \Make...Conditional +%% corresponding sandbox, by default without tilde wrap. +%% <more-args> may contain `{#1}' to store the string that was tested, +%% also `{<id>}' for calling repetitions and `{<pattern>}' for screen +%% or log informations. +\MakeSetupCommand{\MakeSetupSubstringCondition} + {\mk_setup_substr_cond}[2]{% +%% |\mk_setup_substr_cond{<pattern>}{<more-args>}| +%% %% without \begingroup 2010/03/29 +%% can be directly called by other programmer setup commands after +%% `\fdParserId' and <pattern> have been read. + %% #1 pattern string + %% #2 additional arguments, e.g., `{#1}' to keep tested string + \endgroup + \expandafter \protected@edef %% protected 2011/11/21 +%% ... keeps `\protect' instead of just not expanding, +%% but I cannot implement `\UseBlogLigs' otherwise right now. + \csname \setup_substr_cond \fdParserId \endcsname ##1{% + \noexpandcsname \substr_cond \fdParserId \endcsname +%% By `\edef', the name of the substring conditional is stored here +%% as a single token. The rest of the sandbox follows. + ##1\FD_noexpand~#1\dollar_tilde}% +%% <- `\noexpand~' as before v0.5 replaced for v0.51 according to +%% Sec.~\ref{sec:pseudo-tilde}. + \let\dollar_tilde\sandbox_dollar} +%% If a tilde `~' has been used instead of `$', the default +%% is restored. +\def\sandbox_dollar{$} +\let\dollar_tilde\sandbox_dollar +%% % The following general tool |\make_not_expanding_cs| has been used +%% The following general tool |\noexpandcsname| has been used +%% (many definitions in 'latex.ltx' could have used it): %% 2009/04/10 +% \def\make_not_expanding_cs#1{% +% \expandafter \noexpand \csname #1\endcsname} +%% <- 2011/11/20 -> +\def\noexpandcsname{\expandafter\noexpand\csname} +%% +%% === Getting rid of the tildes === +%% |\let~\TildeGobbles| can be used to suppress dummy patterns +%% (contained in <split2>) +%% in `\write'ing or with `\edef'. ... will probably become obsolete +%% ... however, it is helpful in that you needn't care +%% whether there is a dummy wrap left at all. (2009/04/13) +\newcommand{\TildeGobbles}{} \def\TildeGobbles#1${} +%% |\RemoveDummyPattern| is used to remove the dummy pattern +%% \emph{immediately}, not waiting for `\write'ing +%% or other ``total" expansion: %% 2009/04/13 +\newcommand{\RemoveDummyPattern}{} \def\RemoveDummyPattern#1~#2${#1} +%% |\RemoveDummyPatternArg<macro>{<arg>}| executes +%% `\RemoveDummyPattern' in the next argument: +\newcommand*{\RemoveDummyPatternArg}[2]{% + \expandafter #1\expandafter {\RemoveDummyPattern #2}} +%% |\RemoveTilde| is used to remove the tilde that separated +%% the dummy pattern from <split1>. +%% %% An alternative policy is to pass %% TODO 2011/01/25 +%% %% <target> (as an argument) to the parsing macro. +\newcommand{\RemoveTilde}{} \def\RemoveTilde#1~{#1} +%% |\RemoveTildeArg<macro>{<arg>}| executes `\RemoveTilde' +%% in the next argument: +\newcommand*{\RemoveTildeArg}[2]{% + \expandafter #1\expandafter {\RemoveTilde #2}} +%% +%% === Alternative Setup === +%% \label{sec:pseudo-tilde} +%% 'blog.sty' v0.7---``ligatures"---has problems with the tilde. +%% We call a different setup by |\FDpseudoTilde| and go back +%% to the original one by |\FDnormalTilde| +%% (which, however, works only for new processing jobs and +%% processing another file---at present, TODO 2011/11/21): +\newcommand*{\FDnormalTilde}{% + \let\FD_noexpand\noexpand %% v0.51 +%% v0.5 had a modification of `~' that corrupted typesetting. + \let\RemoveTilde\FD_remove_normal_tilde} +\let\FD_remove_normal_tilde\RemoveTilde +\FDnormalTilde +\newcommand*{\FDpseudoTilde}{% + \def\FD_noexpand~{\noexpand\pseudo_tilde}% %% v0.51 + \let\RemoveTilde\FD_remove_pseudo_tilde} +\def\FD_remove_pseudo_tilde#1\pseudo_tilde{#1} +%% TODO 2012/01/20: This way outer braces of splits or the +%% target token list are removed. With 'blog.sty', this has been +%% relevant for displaying code only (where using source braces +%% for displaying braces, instead of using `\{' and `\}', +%% it was a bad habit anyway). In order to fix this, the target +%% token list must be surrounded with some additional dummy things, +%% and `\RemoveTildeArg' must add another trick. +%% %% <- stored in "bad" directory. +%% +%% === Calling conditionals === +%% |\ProcessStringWith{<target-string>}{<id>}| \ builds the sandbox +%% to search <target-string> for the <pattern> associated with the +%% parser-conditional that is identified by <id>, the sandbox then +%% calls the parser. +%% % Finally, the command \emph{``returns"} the +%% % result of applying job <id> to <target-string>---in the sense of +%% % \emph{expanding} to it. %% more precisely 2010/03/25 +%% %% <- removed again, wrong 2010/03/26 +\newcommand*{\ProcessStringWith}[2]{% + \csname \setup_substr_cond #2\endcsname{#1}} +%% |\ProcessExpandedWith{<string-macro>}{<id>}| does the same but with +%% %% changed, intro toks 2010/04/06: +%% a \emph{macro} <string-macro> +%% (like `\fdInputLine' or `\OutputString') +%% that stores the string to be tested. +%% |\ProcessExpandedWith{\the<toks>}{<id>}| with a token list +%% parameter or register <toks> may be used as well. +\newcommand*{\ProcessExpandedWith}[2]{% + \csname \setup_substr_cond #2\expandafter \endcsname + \expandafter{#1}} +%% I would have preferred the reversed order of arguments which seems +%% to be more natural, but the present one is more efficient. +%% Macros with reversed order are currently stored after `\endinput' +%% in section~\ref{sec:pondered}, maybe they once return. +%% %% <- minor corr.s 2010/11/27 +%% +%% Anyway, most desired will be |\ProcessInputWith{<id>}| just +%% applying to `\fdInputLine': +\newcommand*{\ProcessInputWith}[1]{% +% \csname \setup_substr_cond #1\expandafter \endcsname +% \expandafter{\fdInputLine}} +% %% (Definition almost copied for efficiency.) + \ProcessExpandedWith\fdInputLine{#1}} %% 2011/11/21 +%% TODO: error when undefined 2009/04/07 +%% +%% === Copy jobs === +%% A job identifier <id> may also be considered a mere \emph{hook}, +%% a \emph{placeholder} for a parsing job. What function actually is +%% called may depend on conditions that change while reading the +%% <input> file. %%% On a certain condition, +%% |\CopyFDconditionFromTo{<id1>}{<id2>}| +%% \emph{creates or redefines a sandbox builder} with identifier <id2> +%% that afterwards behaves like the sandbox builder <id1>. +%% So you can store a certain behaviour as <id1> in advance in order +%% once to change the behaviour of <id2> into that of <id1>. +\newcommand*{\CopyFDconditionFromTo}[2]{% + \expandafter \let + \csname \setup_substr_cond #2\expandafter \endcsname + \csname \setup_substr_cond #1\endcsname} +%% (Only the \emph{sandbox} is copied here---what about +%% changing conditionals?) %% TODO +%% +%% An ``almost" example is typesetting documentation from a package +%% file where the ``Legalese" header might be typeset verbatim +%% although it is marked as ``comment." (The present %% 2009/04/07 +%% example changes ``hand-made" macros instead.) +%% +%% This feature could have been placed more below as a ``programming +%% tool." +%% +%% +%% == Programming tools == +%% === Tails of conditionals === +%% \label{sec:tails} +%% When creating complex \emph{expandable} conditionals, +%% this may amount to have primitive `\if' ... `\fi' conditionals +%% nested quite deeply, once perhaps too deep for \TeX's memory. +%% To avoid this, you can apply the common `\expandafter' trick +%% which finishes the current `\if' ... `\fi' before an inside +%% macro is executed (cf. \TeX book p.~219 on ``tail recursion"). +%% +%% Internally tests whether certain strings are present at certain +%% places will be carried out by tests on emptiness or +%% %% onwards) %% !? 2009/12/28 +%% on starting with `~'. E.g., +%% ``#1~=~<split1> empty" indicates that either the <pattern> +%% starts a line or the line is empty altogether (this must be +%% decided by another test). +%% +%% |\IfFDempty{<arg>}{<when-empty>}{<when-not-empty>}| \ +%% is used to test <arg> on emptyness (without expanding it): +\newcommand*{\IfFDempty}[1]{% + \ifx$#1$\expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} +%% |\IfFDinputEmpty{<when-empty>}{<when-not-empty>}| is a variant of +%% the previous to execute <when-empty> if the loop processing <input> +%% finds an empty line---otherwise <when-not-empty>. +\newcommand*{\IfFDinputEmpty}{% + \ifx\fdInputLine\@empty \expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} +%% |\IfFDdollar{<arg>}{<when-dollar>}{<when-not-dollar>}| +%% %% <- dollar<-empty +%% is another variant, testing <split2> for being `$', +%% main indicator of there is a match anywhere in <target> +%% (as opposed to starting or ending match): +\newcommand*{\IfFDdollar}[1]{% + \ifx$#1\expandafter \@firstoftwo \else + \expandafter \@secondoftwo \fi} +%% It is exemplified and explained in section~\ref{sec:replchain}. +%% (The whole policy requires that `~' remains active in any +%% testing macros here!) +%% +%% However, you might always just type the replacement text +%% (in one line) instead of +%% such an `\If'\,... (for efficiency \dots) +%% +%% If expandability is not desired, you can just chain macros that +%% rework (so re-define) `\OutputString' or so. +%% +%% 2009/04/11: tending towards combining ... +%% Keeping empty input and empty arguments apart is useful in that +%% \emph{one} test of emptiness per input line should suffice---it +%% may be left open whether this should be the first of all tests +%% \dots +%% +%% |\IfFDpreviousInputEmpty{<when-empty>}{<when-not-empty>}| +%% (v0.42) +%% is a companion of `\IfFDpreviousInputEmpty' referring to +%% `\fdInputLine' as of the \emph{previous} run of the loop +%% in `\ProcessFileWith', cf. section~\ref{sec:input}, +%% where its choice among its two arguments is determined. +%% It is initialized as follows: +\newcommand*{\IfFDpreviousInputEmpty}[2]{#2} +%% ---which is same as +\let\IfFDpreviousInputEmpty\@secondoftwo +%% ... working like `false', somewhat. +%% Together with `\IfFDinputEmpty', it can be used to compress +%% multiple adjacent empty lines into a single one +%% when copying a file. +%% +%% === Line counter === +%% A \LaTeX\ counter |fdInputLine| may be useful for screen or log +%% messages, moreover you can use it to control processing of the +%% <input> file ``from outside," not dependent on what the parsing +%% macros find. The header of the file might be typeset verbatim, +%% but we may be too lazy to define the ``header" in terms of +%% what is in the file. We just decide that the first ... lines +%% are the ``header," even without counting just trying whether +%% the output is fine. It may be necessary to change that number +%% manually when the header changes. +%% +%% You also can insert lines in <output> +%% which have no counterpart in <input>---if you know what you are +%% doing. With 'makedoc', there is a hook `\EveryComment' that can +%% be used to issue commands ``from outside" at a place where +%% executing the command is safe or appropriate. +\newcounter{fdInputLine} +%% You then must insert \ |\CountInputLines| \ in the second argument +%% of `\ProcessFileWith' (or in a macro called from there) +%% so that the counter is stepped. %% TODO!? 2009/04/07 +\newcommand*{\CountInputLines}{\global\advance\c@fdInputLine\@ne} +%% At present %% 2009/04/07 TODO +%% the counter is reset by `\ProcessFileWith', this may change. +%% +%% |\IfInputLine{<relation><number>}{<true>}{<false>}|, when called +%% from the processing loop (second argument of `\ProcessFileWith') +%% issues <true> commands if `\value{fdInputLine}<relation><number>' +%% is true, otherwise <false>. <relation> is one out of +%% \HardNVerb+<+, `=', `>'. %% 2010/03/24 2010/03/29 +\newcommand*{\IfInputLine}[1]{% + \ifnum\c@fdInputLine#1\relax \expandafter \@firstoftwo + \else \expandafter \@secondoftwo \fi} +%% +%% === ``Identity job" `LEAVE' and ``default job" `*' === +%% \label{sec:LEAVE}\label{sec:*} +%% The job with identifier |LEAVE| +%% \emph{leaves} an (expandable) chain of jobs +%% (as expandable replacement in section~\ref{sec:replchain}) +%% and \emph{leaves} the processed string without changing it +%% and without the braces enclosing it: +\expandafter \let + \csname \setup_substr_cond LEAVE\endcsname \@firstofone +%% I.e., `\ProcessStringWith{<string>}{LEAVE}' expands to <string> +%% ... \ProcessStringWith{(Indeed!)}{LEAVE} +%% +%% |LEAVE| is used for ``chaining" jobs---there will be a routine +%% (Sec.~\ref{sec:auto-chain}) +%% to define the action of a job, including what job to run +%% \emph{next} after the present one has been finished. +%% Using this routine, the final job will call `LEAVE'. +%% +%% |*| may be considered a ``meta-job"---it does not directly +%% set up a sandbox, it just ``redirects" to the job that has been +%% declared most recently. When job ids are assigned automatically, +%% with `*' you can call that job without knowing its actual id: +\@namedef{\setup_substr_cond*}{% + \csname \setup_substr_cond \fdParserId \endcsname} +%% As an important example, when all the jobs in the chain are +%% expandable, you can call the chain by +%% \[|\WriteResult{\ProcessInputWith{*}}|\] +%% in the body of the file processing loop (Sec.~\ref{sec:input}). +%% TODO: test! %% 2011/11/21 +%% +%% == Setup for expandable chains of replacements == +%% \label{sec:replchain}%% TODO makedoc: provide less visible label/ref 2009/04/11 +%% By the following means, you can create macros +%% (`\Transform' among them) such that, e.g., +%% \[`\edef\OutputString{\Transform{<string>}}'\] renders `\OutputString' +%% the result of applying a chain (sequence) of stringwise replacements +%% to <string>. +%% You can even write a transformed input <string> to a file +%% without defining anything after `\read to'\,.\,.\,. %% corr. 2010/11/24 +%% In this case however, you don't get any statistical message +%% about what happened or not. With `\edef\OutputString' you can at +%% least issue some `changed!' or `left!' (maybe `\message{!}' vs.\ +%% `\message{.}'). +%% There is an application in 'makedoc' for ``typographical upgrading" +%% from plain text to \TeX\ input. +%% +%% === The backbone macro === +%% |\repl_all_chain_expandable| will be the backbone of the +%% replacements. It is called by some parsing macro <parser> +%% and receives from the latter <split1>~=~#1 and <split2>~=~#2. +%% #3 is the result of what happened so far. +\def\repl_all_chain_expandable#1#2#3#4#5#6{% + %% #1, #2 splits, #3 past, #4 substitute, + %% #5 repeat parser, #6 pass to +% \ifx~#2\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi +%% The previous line (or something similar!?) %% add. 2010/11/24 +%% would be somewhat faster, but let us exemplify +%% `\IfFDdollar' from section~\ref{sec:tails} instead: + \IfFDdollar{#2}% +%% If #2 starts with `$'---with category code 3, ``math shift"!, +%% it \emph{is} `$', due to not reading `$' +%% from input with its standard category code 3 +%% and the sandbox construction (where `$' appears with its standard +%% category code). %% TODO might be explained earlier 2009/04/11 +%% %% or refer to here. +%% And this is the case \emph{exactly} when the <pattern> from +%% <parser> didn't match, again due to the input category codes. +%% Now on \emph{no} match, the sandbox builder #6 is called +%% with target string #3#1 where the last tested string is attached +%% to previous results. The ending `~' is removed, #6 inserts a new +%% wrap for the new dummy pattern. + {\RemoveTildeArg #6{#3#1}}% +%% Otherwise ... the \emph{sandbox builder} <sandbox> +%% (that will be shown below) that called <parser> +%% initialized #5 to be that <parser> itself. (<parser> otherwise +%% wouldn't know who it is.) So <parser> calls itself with another sandbox +%% `#2&'. Note that #2 contains \lq`~<pattern>$'\rq\ due to the initial +%% <sandbox> building. + {#5#2&{#3#1#4}{#4}#5#6}} +%% #4 is the replacement string that <sandbox> passed to <parse>. +%% The first argument after the `&' is previous stuff plus +%% the recently skipped <split1> +%% plus #4 replacing the string <pattern> that was matched. +%% +%% Finally, #5 and #6 again ``recall" <parser> and the sandbox +%% builder to which to change in case of no other match. +%% +%% % TODO move following up!? 2009/04/11 +%% === The basic setup interface macro === +%% |\MakeExpandableAllReplacer{<id>}[<chng>]{<find>}{<replace>}{<id-next>}|\\ +%% [\topsep] +%% %% \[|\MakeExpandableAllReplacer{<id>}[<chng>]{<find>}{<replace>}{<id-next>}|\] +%% creates sandbox and parser with common identifier <id> and search +%% pattern <find>. Each occurrence of <find> will be replaced by +%% <replace>. When <find> is not found, the sandbox builder for +%% <id-next> is called. This may be another replacing macro of the +%% same kind. To return the result without further transformations, +%% call job `LEAVE' (section~\ref{sec:LEAVE}). +%% Optional argument <chng> changes category codes locally +%% for reading <find> and <replace>. +%% %% <- added <cat>, <pattern> -> <find> 2010/03/19 +\MakeSetupCommand{\MakeExpandableAllReplacer} + {\mk_setup_xpdbl_all_repl}[3]{% + %% #1 pattern, #2 substitute, #3 pass to + \endgroup +%% We take pains to call next jobs by single +%% command strings and store them this way, not by `\csname', +%% as `\ProcessStringWith' would do it. `\edef\@tempa' +%% is used for this purpose, but \dots + \protected@edef\@tempa{% %% protected 2011/11/21 + \noexpand\mk_setup_substr_cond{#1}{% + {}{#2}% + \noexpand\noexpand +%% That `\edef\@tempa' must \emph{not expand} +%% tokens %%% the controll words after they have been %% 2011/11/20 +%% computed from `\csname' etc. +%% Moreover, expansion of the parser commands +%% must be avoided another time when `\@tempa' is executed. + \noexpandcsname \substr_cond \fdParserId \endcsname + \noexpand\noexpand + \noexpandcsname \setup_substr_cond #3\endcsname}}% +%% Those internal setup commands start with `\endgroup' to switch back +%% to standard category codes. We must match them here by +%% `\begingroup'. + \begingroup \@tempa + \begingroup \mk_substr_cond{#1}{% + \repl_all_chain_expandable{##1}{##2}}} +%% The final command is the one that we explained first. %% TODO 2009/04/11 +%% +%% === Automatic chaining === +%% \label{sec:auto-chain} +%% With v0.31, %% "Half-automatic" \Prepend... +%% \[|\PrependExpandableAllReplacer{<id>}[<cat>]{<find>}{<replace>}|\] +%% % |\PrependExpandableAllReplacer{<id>}[<cat>]{<find>}{<replace>}| +%% % \\[\topsep] +%% was hoped to be a slight relief in composing replacement chains. +%% It does something like invoking `\MakeExpandableAllReplacer' +%% with <prev-setup-id> for the last <next-id> argument +%% where <prev-setup-id> is the <id> of the job that was set up most +%% recently. If you have adjacent lines +%% \begin{quote} +%% \leavevmode\hbox to 0pt\bgroup +%% `\MakeExpandableAllReplacer{<id-0>}{<find-0>}{<subst-0>}{LEAVE}'% +%% \hss\egroup \\ +%% `\PrependExpandableAllReplacer{<id-1>}{<find-1>}{<subst-1>}'\\ +%% `\PrependExpandableAllReplacer{<id-2>}{<find-2>}{<subst-2>}' +%% \end{quote} +%% and call <id-2>, it will call <id-1>, and the latter will call +%% <id-0>. So you can reorder the chain by moving `\Prepend'... lines. +%% +%% With v0.5, +%% |\PrependExpandableAllReplacer*[<cat>]{<find>}{<replace>}| +%% saves you from inventing and typing <id>, it is automatically +%% generated; or the `*' replaces the <id> argument. +\newcommand*{\PrependExpandableAllReplacer}{% + \let\fdParserId_before\fdParserId + \@ifstar{\stepcounter{fd_line_job}% + \edef\@tempa{% + \noexpand\StartFDsetup + \noexpand\prep_xpdbl_all_repl + {\number\value{fd_line_job}}}% + \@tempa}% + {\StartFDsetup\prep_xpdbl_all_repl}} +\newcommand*{\prep_xpdbl_all_repl}[2]{% + \mk_setup_xpdbl_all_repl{#1}{#2}{\fdParserId_before}}% + %% #1 pattern, #2 substitute, #3 pass to +%% As of 2012/11/13, `mdoccorr.cfg' uses `\do' as a shorthand +%% for \[`\PrependExpandableAllReplacer*'\] `\do' sometimes has +%% not been defined at that moment, then +%% \[`\renewcommand*{\do}{\PrependExpandableAllReplacer*}'\] fails. +%% To make it working (or superfluous): %% 2012/11/17 +\gdef\do{\PrependExpandableAllReplacer*} +%% |\StartPrependingChain| makes `\MakeExpandableReplacer' +%% superfluous, in the sense that +%% the above chain setup can be achieved as well like this: +%% \begin{quote} +%% `\StartPrependingChain'\\ +%% `\PrependExpandableAllReplacer{<id-0>}{<find-0>}{<subst-0>}'\\ +%% `\PrependExpandableAllReplacer{<id-1>}{<find-1>}{<subst-1>}'\\ +%% `\PrependExpandableAllReplacer{<id-2>}{<find-2>}{<subst-2>}' +%% \end{quote} +%% or with v0.5: +%% \begin{quote} +%% `\StartPrependingChain'\\ +%% `\PrependExpandableAllReplacer*{<find-0>}{<subst-0>}'\\ +%% `\PrependExpandableAllReplacer*{<find-1>}{<subst-1>}'\\ +%% `\PrependExpandableAllReplacer{<start>}{<find-2>}{<subst-2>}' +%% \end{quote} +%% This adds a code line, but this way you can choose +%% the final ``real" job more easily. So you can think of +%% `\StartPrependingChain' as ``initializing a chain of +%% prependments." As to the `*' version, the example suggests +%% using an explicit <id> argument finally if you want to invoke +%% the chain explicitly by a line job identity +%% (without counting the declaration lines---however, +%% note job `*' according to Sec.~\ref{sec:*}). +\newcommand*{\StartPrependingChain}{% + \def\fdParserId{LEAVE}% + \setcounter{fd_line_job}{0}} %% 2011/11/13; TODO \Nameprefix... +\newcounter{fd_line_job} +%% +%% === `CorrectHook' launching the replacement chain === +%% %% 2010/03/29: +%% |\MakeDocCorrectHook{<string>}| belongs to 'makedoc', +%% but in the meantime ('nicetext' release 0.3) +%% I have proposed to use it with 'fifinddo' only as well +%% (running files `fdtxttex.tpl', `fdtxttex.tex'). +%% Therefore I offer some simplification |\SetCorrectHookJob{<job-id>}| +%% for defining `\MakeDocCorrectHook' \emph{here.} +\newcommand*{\SetCorrectHookJob}[1]{% + \def\MakeDocCorrectHook##1{\ProcessStringWith{##1}{#1}}} +%% |\SetCorrectHookJobLast| just uses the job that was set up +%% most recently. +\newcommand*{\SetCorrectHookJobLast} + {\SetCorrectHookJob\fdParserId} +%% |\CorrectedInputLine| results from `\MakeDocCorrectHook' when the +%% latter is applied to `\fdInputLine': %% reworded for breaking 2011/09/13 +\newcommand*{\CorrectedInputLine}{% + \expandafter \MakeDocCorrectHook \expandafter{\fdInputLine}} +%% +%% == Leave package mode == +%% We restore the underscore `_' for math subscripts. +%% (This might better depend on something \dots) %% TODO 2009/04/07 +\PopLetterCat\_ %% 2012/08/27 +%% +\endinput +%% \TeX\ ignores the rest of the file when it is \emph{input} +%% ``in the sense of `\input'", as opposed to just reading +%% the file line by line to a macro like `\fdInputLine'. +%% +%% == Pondered == +%% \label{sec:pondered} + %% TODO abbreviated commands (aliases) \MkSubstrCond... + %% TODO \@onlypreamble!? +\newcommand*{\ApplySubstringConditional}[1]{% + %% #1 identifier; text to be searched expected next + \csname setup_substr_cond:#1\endcsname} +\newcommand*{\ApplySubstringConditionalToExpanded}[1]{% 2009/03/31+ + \csname setup_substr_cond:#1\expandafter \endcsname \expandafter} +\newcommand*{\ApplySubstringConditionalToInputString}[1]{% 2009/03/31+ + \csname setup_substr_cond:#1\expandafter \endcsname + \expandafter {\fdInputLine}} + %% TODO or `\OutputString', even `\read' to `\OutputString'!? +% \newcommand*{\ApplySubstringConditionalToExpanded}[2]{% +% %% note: without assignments, robust! +% %% BUT the `\csname ... \expandafter \endcsname' method is faster +% \expandafter \reversed_apply_substr_cond +% \expandafter {#2}{#1}} +% \newcommand*{\reversed_apply_substr_cond}[2]{% +% \ApplySubstringConditional{#2}{#1}} + %% ODER: +% \newcommand*{\expand_attach_arg}[2]{%% 2009/03/31 +% %% #1 command with previous args, TODO cf. LaTeX3 +% \expandafter \attach_arg \expandafter {#1}{#2}} +% %% actually #1 may contain more than one token, +% %% only first expanded +% \newcommand*{\attach_arg}[2]{#2{#1}} +% \newcommand*{\ApplySubstringConditionalToExpanded}[2]{% +% \expandafter \attach_arg \expandafter +% {#2}{\ApplySubstringConditional{#1}}} +%% +%% +%% +%% == VERSION HISTORY == +%% +v0.1 2009/04/03 very first version, tested on morgan.sty +v0.2 2009/04/05 counter fdInputLine, \ProvidesFile moved from + \ProcessFile to \ResultFile, \CopyFD..., + category section first, more sectioning, + suppressing empty code lines before section + titles; discussion, \Delimiters + 2009/04/06 more discussion + 2009/04/07 more discussion, factored \WriteProvides out from + \ResultFile, \ProcessExpandedWith corrected + 2009/04/08 \InputString -> \fdInputline; + removed \ignorespaces + 2009/04/09 \WhenInputLine[2] -> \IfInputline[3], + \ProcessInputWith, typos, + \WriteProvides message `with' + 2009/04/10 \make_not_expanding_cs + DISCOVERED ``IF SUBSTRING" ALGORITHM WRONG + (<str1><str2><str1> in <str1><str2>) +v0.3 2009/04/11 SOME THINGS GIVEN UP EARLIER WILL BE REMOVED, + TO BE STORED IN THE COPY AS OF 2009/04/10 + mainly: sandbox setup (tilde/dollar) + REAL ADDITION: setup for expandable replacing + 2009/04/12 played with `chain' vs. `sequence'; + plain `...', `cf.', `etc.' for `mdcorr.cfg' + 2009/04/13 \RemoveTilde... + 2009/04/15 reworked text, same mistake \in@ +v0.31 2009/04/21f. comments on ted, stringstrings + 2009/12/28 "onwards)" !? "safer", not "more safe" + 2010/03/10 the loop starts + 2010/03/17 corr. t^ete; set up -> setup for + 2010/03/18 TODO EOF, ctan.org/pkg/newfile; non-ASCII + 2010/03/19 extended description of \MakeExpandableAll...; + '' -> " + 2010/03/20 \ctanpkgref + 2010/03/22 \StartFDsetup, \Prepend... + 2010/03/23 URL for `substr.sty' +SENT TO CTAN + +v0.4 2010/03/24 removed \pagebreak before "substrings"; + <relation> with \IfInputLine precisely + 2010/03/25 todo \ProcessExp... more precisely, etc. + 2010/03/26 ... was wrong, removed + 2010/03/29 \SetPatternCodes, \ResetPatternCodes, + \SetCorrectHookJob, \SetCorrectHookJobLast; + <relation> with \HardNVerb; + don't mention \begingroup with + \mk_setup_substr_cond; renamed v0.4 +belonged to nicetext RELEASE 0.4 +v0.4a 2010/04/04 copyright 2010 +belonged to nicetext RELEASE 0.41 + +v0.41 2010/04/06 more on \ProcessExpanded...; + \ProcessFile... gets opt arg + 2010/04/13 \ProcessFile{<file>}... shows <file> +used by blog.sty v0.1, v0.2 +v0.42 2010/11/09 typo corr. + 2010/11/10 \IfFDpreviousInputEmpty + 2010/11/11 \BasicNormalCatcodes from blog.sty, + \CopyFile*, \CopyLine; v3. -> v0.3; + LPPL v1.3c + 2010/11/12 \CatCode replaced (implemented in niceverb only) + 2010/11/13 \CopyFile with \message{.} + 2010/11/24 reworked doc. of replacement setup; + \StartPrependingChain + 2010/11/25 corr. typo \@backslash...; doc. changes; + \CopyLine indeed, not \fdCopyLine + 2010/11/27 footnote on "parser", other doc. corr.s + 2011/01/20 corr. "period" AMSTERDAM + 2011/01/25 updated (C); footnotes to `substring theory'; + TODO with \RemoveTilde; some manual line spacings + (adding `\ ') + -> r0.42 +v0.43 2011/08/06 doc.: mistake \WriteResult/\ResultFile, + 2011/08/22 use \acro + 2011/09/12f. \CorrectedInputLine - reworded for breaking + -> r0.44 +v0.44 2011/10/23 messages from \ResultFile and \CloseResultFile + -> r0.46 +v0.45 2011/10/26 little modification of \CloseResultFile message, + "sacrificing" \pagebreak before Sec. 4 -- fine! + +v0.5 2011/11/13 \PrependExpandableAllReplacer*, \MakeSetupCommand; + doc.: {center} with too long verbatim quote + 2011/11/19 input check fixed, doc. there adjusted, + \ifFinalInputFile, \ProcessFinalFileWith, job `*' + 2011/11/20 \noexpandcsname; "default job" lowercase + 2011/11/21 \ProcessInputWith "less efficient", + \protected@edef, "pseudo-tilde" + -> r0.5 +v0.51 2012/01/20 updated (C); TODO on pseudo-tilde + 2012/03/17 fixed \FDnormalTilde/\FDpseudoTilde + -> r0.53 +v0.6 2012/08/27 using 'catcodes', introducing \CatCode + -> r0.62 +v0.61 2012/11/17 . \gdef\do... + +TODO: cleveref 2010/03/18 diff --git a/macros/latex/contrib/nicetext/use/makedoc.cfg b/macros/latex/contrib/nicetext/use/makedoc.cfg new file mode 100644 index 0000000000..666c87706e --- /dev/null +++ b/macros/latex/contrib/nicetext/use/makedoc.cfg @@ -0,0 +1,150 @@ +\ProvidesFile{makedoc.cfg}[{2013/03/25 documentation settings}] +%% +\author{Uwe L\"uck\thanks{% + \url{http://contact-ednotes.sty.de.vu}}} +%% +%% 'hyperref': +\RequirePackage{ifpdf} +\usepackage[% + \ifpdf +% bookmarks=false, %% 2010/12/22 +% bookmarksnumbered, + bookmarksopen, %% 2011/01/24!? + bookmarksopenlevel=2, %% 2011/01/23 +% pdfpagemode=UseNone, +% pdfstartpage=10, + pdfstartview=FitH, %% 2012/11/26 again +% pdfstartview=0 0 100, %% 2011/08/22 +% pdfstartview={XYZ null null 1}, %% 2011/08/25 +% pdfstartview={XYZ null null null},%% 2011/08/25 +% pdfstartview={XYZ null null .5}, %% 2011/08/26 +% pdffitwindow=true, %% 2011/08/22 + citebordercolor={ .6 1 .6}, + filebordercolor={1 .6 1}, + linkbordercolor={1 .9 .7}, + urlbordercolor={ .7 1 1}, %% playing 2011/01/24 + \else + draft + \fi +]{hyperref} +\hypersetup{% + pdfauthor={Uwe L\374ck}% +} +%% metadata, |\MDkeywords{<text>}|, |\MDkeywordsstring|: +%% %% 2011/08/22: +\makeatletter + \newcommand*{\MDkeywords}[1]{% + \gdef\MDkeywordsstring{#1}% + \hypersetup{pdfkeywords=\MDkeywordsstring}%% TODO!? + } + \@onlypreamble\MDkeywords +%% |\MDaddtoabstract{<par-head>}|, `:' added: + \newcommand*{\MDaddtoabstract}[1]{% %% 2012/05/10 + \par\smallskip\noindent + \strong{#1:}\quad\ignorespaces} +%% \pagebreak[2] +%% |\printMDkeywords|: + \newcommand*{\printMDkeywords}{% + \MDaddtoabstract{Keywords}% + \MDkeywordsstring +% \global\let\MDkeywordsstring\relax %% `%' 2012/11/12 + } +%% The previous definitions mainly are useful with a variant +%% |\begin{MDabstract}| of \LaTeX's `{abstract}' environment: + \newenvironment{MDabstract} + {\abstract\noindent + \hspace{1sp}%% for niceverb + \ignorespaces} + {\@ifundefined{MDkeywordsstring}% + {}% + {\printMDkeywords}% + \global\let\MDabstract\relax %% 2012/11/12 + \global\let\endMDabstract\relax %% 2012/11/12 + \endabstract} +%% |\[MD]docnewline| 2012/11/12 from `readprov.tex': + \newcommand*{\MDdocnewline}{\leavevmode\@normalcr[\topsep]} +%% <- `\leavevmode' for use with `\paragraph'. +%% Sometimes needs to be preceded by a space. +%% +%% |\MDfinaldatechecks[<tex-script>]| with \ctanpkgref{filedate}: + \newcommand*{\MDfinaldatechecks}[1][fdatechk]{% + \AtEndDocument{% +% \clearpage %% 2013/03/25 no avail -- with `filedate'! + \def\@pkgextension{sty}% + \def\NeedsTeXFormat##1[##2]{}% + \noNiceVerb %% 2013/03/22 + \input{#1}% + }} + \@onlypreamble\MDfinaldatechecks +\makeatother +%% Use other packages: +\RequirePackage{niceverb}[2011/01/24] +\RequirePackage{readprov} %% 2010/12/08 +\RequirePackage{hypertoc} %% 2011/01/23 +\RequirePackage{texlinks} %% 2011/01/24 +\RequirePackage{relsize} %% 2011/06/27 +\RequirePackage{color} %% 2011/08/06 +\RequirePackage{lmodern} %% 2012/10/29 +\RequirePackage{filedate} %% 2012/11/12 +\RequirePackage{filesdo} %% 2013/03/22 +%% \pagebreak[3] +%% Logical markup:\qquad |\strong{<chars>}|, |\meta{<chars>}|, +%% |\acro{<chars>}|, |\pkg{<chars>}|, +%% |\code{<chars>}|, |\file{<chars>}|:{\sloppy\par} +\makeatletter + \def\do#1#2{\@ifdefinable#1{\let#1#2}}%% 2012/07/13 + \do\strong\textbf \do\file\texttt \do\acro\textsmaller + %% <- wrong tests before 2012/07/13 + \do\meta\textit \do \pkg\textsf \do\code\texttt + \ifpdf + \pdfstringdefDisableCommands{% + \let\acro\textrm + \let\file\textrm %% 2011/11/09 + \let\code\textrm %% 2011/11/20 + \let\pkg \textrm %% 2012/03/23 + } + \fi + %% TODO 2011/07/22 -> `htlogml.sty' +\makeatother +%% |\qtdcode{<text>}|: 2012/10/24: + \newcommand*{\qtdcode}[1]{`\code{#1}'} +%% |\pkgtitle{<package-name>}{<caption>}| +\newcommand*{\pkgtitle}[2]{% %% 2012/07/13 + \global\let\pkgtitle\relax + \pkg{\huge #1}\\---\\#2\thanks{This + document describes version + \textcolor{blue}{\UseVersionOf{\jobname.sty}} + of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}} +%% TODO: %% |\TODO| bad with `mdoccorr.cfg' +\newcommand*{\TODO}{\textcolor{blue}{\acro{TODO}}} %% 2012/11/06 +%% `\MDsampleinput[{<file>}' was added 2012/11/06. +%% Problems with `myfilist.tex' were due to 'parskip.sty' +%% there. On 2012/11/12, we change the former simple macro to a +%% much more complex +%% |\MDsamplecodeinput[<add-hfuss>]{<file>}| +\newcommand*{\MDsamplecodeinput}[2][]{% + \begingroup + \vskip\bigskipamount \hrule + \nobreak\vskip-\parskip +% \nobreak\vskip\medskipamount +%% Previous mistake (same below) due to manual change +%% of `\topsep' in the file `myfilist.tex' (2012/11/30). + \ifx\\#1\\\else + \hfuzz=\textwidth \advance\hfuzz#1\relax + \fi + \noNiceVerb \verbatiminput{#2}% +% \nobreak\vskip\medskipamount + \hrule \vskip-\parskip + \bigskip %%% \bigbreak +%% `\bigbreak' made much larger space in `myfilist.tex'. + \endgroup +} +%% |\ctanpkgdref{<pkg-id>}| adds the printed link to +%% `ctan.org/pkg' as a footnote. There is a little space +%% for coloured link borders: +\newcommand*{\ctanpkgdref}[1]{% + \ctanpkgref{#1}\,\urlfoot{CtanPkgRef}{#1}} +\errorcontextlines=4 +\pagestyle{headings} + +\endinput diff --git a/macros/latex/contrib/nicetext/use/makedoc.sty b/macros/latex/contrib/nicetext/use/makedoc.sty new file mode 100644 index 0000000000..2c52945662 --- /dev/null +++ b/macros/latex/contrib/nicetext/use/makedoc.sty @@ -0,0 +1,642 @@ +%% Macro package `makedoc.sty' for LaTeX2e, +%% copyright (C) 2009-2012 Uwe L\"uck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% for preparing documentations from packages. + +\def\fileversion{0.52} \def\filedate{2012/08/28} + +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3a of the License, or any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% We did our best to help you, but there is NO WARRANTY. +%% +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +% 1994/12/01: \newcommand* etc. +\ProvidesPackage{makedoc}[\filedate\space v\fileversion\space + TeX input from *.sty (UL)] +%% +%% |\PackageCodeTrue| and |\PackageCodeFalse| set `\ifPackageCode' +%% globally, so redefinition of `~' (playing a key role in 'fifinddo') +%% may be kept local. Note the capital `T' and `F'! +\newcommand*{\PackageCodeTrue} {\global\let\ifPackageCode\iftrue} +\newcommand*{\PackageCodeFalse}{\global\let\ifPackageCode\iffalse} +%% |\ifPackageCode| is used to determine whether a listing environment +%% must be `\beg'un or `\end'ed. You may also want to suppress empty +%% code lines, while empty lines should issue a `\par' break in +%% ``comment" mode. +%% +%% Since `\newif' is not used, `\ifPackageCode' must be declared +%% explicitly. Declaration of new `\if's must be early in case +%% they occur in code that is skipped by another `\if'\dots +%% [TODO!? cf. others 2010/03/15] +\PackageCodeFalse +%% +%% 'makedoc' is an extension of 'fifinddo' on which it depends. +\RequirePackage{fifinddo}[2012/08/27] +%% 'fifinddo' v0.6 loads 'stacklet.sty', so we can use %% 2012/08/28 +%% the underscore as a ``private letter" by the following: +\PushCatMakeLetter\_ %% 2012/08/28 +%% +%% \subsection{&\MakeDocCorrectHook\ (\dqtd{`txt2TeX'})} +%% \label{sec:mdoccorr} %% 2012/03/17 +%% |\MakeDocCorrectHook| is predefined to leave its argument without +%% the enclosing braces, otherwise unchanged: +\let\MakeDocCorrectHook\@firstofone +%% Less efficiently, the same could have been set up as +% \newcommand*{\MakeDocCorrectHook}[1]{\ProcessStringWith{#1}{LEAVE}} +%% according to 'fifinddo'. +%% +%% It may be \emph{redefined} in a \emph{configuration} file like +%% 'mdoccorr.cfg' %% was makedoc.cfg 2011/08/22 +%% or the 'makedoc' script file applying to a single +%% package file in order to, e.g., converting plain text to \TeX\ input +%% conforming to typographical conventions, making `$\dots$' from +%% \qtd{&.&.&.}, %% dots should not be replaced! +%% e.g. +%% Replace `LEAVE' in the previous suggestion by an identifier +%% whose job you have defined before, and use `\renewcommand' +%% in place of `\newcommand'. +%% See an example in 'mdoccorr.cfg'. %% fixed 2011/08/22 +%% +%% You can \emph{test} your own `\MakeDocCorrectHook' by +%% \[`\typeout{\MakeDocCorrectHook{<test-string>}}'\] +%% ... provided (sometimes) `\MakeOther\ ' ... +%% You can even change it using `\IfInputLine' from 'fifinddo' in the +%% midst of preprocessing a package documentation. +%% +%% \subsection{Distinguishing package code from comments}%% <- wiki style breaks in self-doc. +%% \label{sec:distinguish} +%% Use of comment marks is a matter of personal style. Only lines +%% starting with the sequence |%% | %% box 2010/03/16 +%% are typeset in \TeX\ quality +%% under the present release. Lines just containing |%%| +%% (without the space) are used to suppress empty code lines +%% preceding section titles (while keeping some visual space +%% in the package file). There is a preferable way to do this, +%% however not in the present release ... +%% +%% The parsing macros must be set up reading `%' and ` ' as ``other" +%% characters. Using the optional arguments for this creates +%% difficulties that can be somewhat avoided by redefining +%% |\PatternCodes|. +\SetPatternCodes{\MakeOther\%\MakeOther\ }%% 2010/03/30 +%% +%% The next line sets the ``sandbox" for the detecting macro, as it +%% is coined in the documentation of 'fifinddo', with ``identifier" +%% |PPScomment|. +\MakeSetupSubstringCondition{PPScomment}{%% }{{#1}} +%% The last argument stores the expanded input line for reference by +%% macros called. The next line is a test whether the setup works. +% \expandafter \show \csname \setup_substr_cond PPScomment\endcsname +%% Here comes the definition of the corresponding testing macro. +%% #3 is the expanded input line from above. The `\If'\dots commands, +%% `\fdInputLine', `\fdInputLine', and `\RemoveDummyPatternArg' +%% are from 'fifinddo'. +\MakeSubstringConditional{PPScomment}{%% }#3{%% #3 entire test string + \DecideCommentCode{#1}{#2}{#3}\PPstring} +%% |\DecideCommentCode{#1}{#2}{#3}{#4}| is shared with the parser +%% for the \lq`% '\rq\ commenting style. %% new 2010/03/28 +\newcommand*{\DecideCommentCode}[4]{% + \IfFDinputEmpty{\OnEmptyInputLine}{% +%% The empty line test comes early to offer control with +%% `\OnEmptyInputLine' both in code and comment mode. +%% Maybe it should always? %% TODO 2009/04/13 + \IfFDempty{#1}% + {\TreatAsComment{% + \RemoveDummyPatternArg\MakeDocCorrectHook{#2}}}% + {\ifx\fdInputLine#4% + \ifPackageCode\else \WriteResult{}\fi% +%% ... allows paragraphs in comments. + \else \TreatAsCode{#3}\fi}}} +%% Job |PScomment| deals with the |% | commenting style: +\MakeSetupSubstringCondition{PScomment}{% }{{#1}} +\MakeSubstringConditional{PScomment}{% }#3{% + \DecideCommentCode{#1}{#2}{#3}\PercentChar} +%% `\PercentChar' is from 'fifinddo'.---Return to `\fdPatternCodes': +\ResetPatternCodes %% 2010/03/30 +%% +%% |\PPstring| stores the line suppressing empty code lines with +%% the \lq`%% '\rq\ style: +\newcommand*{\PPstring}{} \xdef\PPstring{\PercentChar\PercentChar} +%% +%% |comment| will be a ``generic" identifier to call a comment line +%% detector. It might be predefined to issue an ``undefined" error; +%% however this release predefines it to behave like `PPScomment': +\CopyFDconditionFromTo{PPScomment}{comment} +%% This means that the \lq`%% '\rq\ commenting style is assumed by +%% default. \[`\CopyFDconditionFromTo{PScomment}{comment}'\] +%% switches to the \lq`% '\rq\ style (with the {\it Wikipedia} +%% sectioning parser). +%% Or just choose \[`\ProcessInputWith{PScomment}'\] as <main-parser> +%% (without the {\it Wikipedia} feature). +%% +%% Alternative still to be considered: +% \@namedef{\setup_substr_cond comment}{% +% \PackageError{makedoc}{Job `comment' not defined}% +% {Use \string\CopyFDconditionFromTo{comment}}} +%% +%% \subsection{Choice of package code environment} +%% With v0.3, we adopt the solution for typesetting package code +%% that was implemented in the former 'makedoc.cfg'. So we rely +%% on the `listing' and `listingcont' environments of the +%% 'moreverb' package. +%% +%% The earlier idea was that 'makedoc.sty' uses an undefined \LaTeX\ +%% environment `packagecode' that will be defined in 'makedoc.cfg'. +%% An accompanying idea was that 'makedoc' works before the +%% `\documentclass' line inside a group, while 'makedoc.cfg' +%% is read \emph{after} the `\documentclass' line. +%% +%% We now want to simplify things. We replace +%% \[`packagecode' \mbox{\quad by\quad } `mdPackageCode'\] +%% and define the new environment globally here. 'moreverb' +%% and our choice for `\listinglabel' are +%% called at `\begin{document}'---outside the possible group. +\gdef\mdPackageCode{% +% \small +%% 2011/01/19, v0.41: `\small' has affected the `\baselineskip' +%% above the code. So a `\par' must be executed before `\small'. +%% But we don't want to have the extra `\partopsep'---forced ... + \mdStartPackageCode %% 2011/01/19 v0.41 +%% From the next occurrence of the environment onwards, +%% `listing' must be replaced by `listingcont'. + \gdef\mdPackageCode{\mdStartPackageCode %% 2011/01/19 v0.41 + \listingcont}% + \listing{1}} +\gdef\mdStartPackageCode{% %% 2011/01/19 v0.41 +%% Smart `\small'---we might once allow `\partopsep' +%% in `vmode'---not this time: + \par \small \partopsep\z@skip +%% Get rid of 'niceverb' stuff: + % \MakeOther\`\MakeOther\'%% probably OK with moreverb + \MakeOther\<\MakeOther\|% +} +\gdef\endmdPackageCode{% + \endlisting + \global\let\endmdPackageCode\endlistingcont} +\AtBeginDocument{% + \RequirePackage{moreverb}% + \renewcommand*{\listinglabel}[1]{% + \llap{\scriptsize\rmfamily\the#1}\hskip\listingoffset\relax}% +} +%% |\ResetCodeLineNumbers| may be needed to \emph{reset} +%% 'moreverb''s (global!) code line number settings +%% (\emph{first} line number + {\it modulo} for displaying) +%% when combining documentations of \emph{more} than one package +%% with the present solution for implementing `mdPackageCode'. +%% %% 2010/12/20, rm. 2010/12/21: +%% % (With v0.41, the definition is global, so it can be used +%% % outside a group in a `.tex' preamble that does the preprocessing.) +\@ifdefinable\ResetCodeLineNumbers{%% global as above, v0.41 + \gdef\ResetCodeLineNumbers{% + \global\listing@line\@ne \gdef\listing@step{\@ne}}} +%% +%% \subsection{Dealing with comments} +%% |\TreatAsComment{<text>}| writes <text> to the documentation +%% file. If we had ``package code" (were in ``code mode") so far, +%% the listing environment is ended first. +\newcommand*{\TreatAsComment}[1]{% + \ifPackageCode + \WriteResult{\string\end{mdPackageCode\@empty}}% +%% The `\@empty' here is a lazy trick to save self-documentation +%% fighting 'verbatim''s ``highlight" of finding ends of listings +%% (to be improved). %% TODO 2010/03/09 +%% +%% We always use `\string' to prevent macro expansion in `\write'ing +%% in place of \LaTeX's `\protect', +%% as long as 'fifinddo' simply uses the primitive `\write' in place +%% of \LaTeX's `\proteced@write' ... %% todo 2009/04/08 + \PackageCodeFalse + \EveryComment +% \_empty_code_lines_false + \fi + \WriteResult{#1}} +%% Here, |\EveryComment| is a macro hook for inserting material that should +%% not appear in a listing environment, I had tried this %% 2010/03/18 +%% successfully: +%% \begin{verbatim} +%% \gdef\EveryComment{% +%% \global\let\EveryComment\relax +%% \WriteResult{\string\AutoCmdVerbSyntax}} +%% \end{verbatim} +%% Initialized: +\global\let\EveryComment\relax %% should be changed globally. +%% +%% \subsection{Sectioning} +%% \label{sec:secparsers} +%% We provide a facility from 'wiki.sty' that imitates the sectioning +%% syntax used in editing \emph{Wikipedia} pages, in a different +%% implementation (better compatibility) and in a more general way. +%% On Wikipedia, `== Definition ==' works similar as +%% `\section{Definition}' does with \LaTeX. With the present +%% implementation, you can type, e.g., +%% % \[`%%%%%%%%%%%%%%%%%%%%%% == Definition == %%%%%%%%%%%%%%%%%%%%%%'\] +%% $$`%%%%%%%%%%%%%%%%%%%%%% == Definition == %%%%%%%%%%%%%%%%%%%%%%'$$ +%% to get a similar result. The number of `%' characters doesn't +%% matter, and there can be other stuff, however: additional `=' +%% symbols may harm. Three sectioning levels are supported, through +%% `==<text>==', `===<text>===', and `====<text>====' (deepest). +%% +%% There are three detector macros made for programmers. +%% The most general one is +%% In the following definitions, there is a single tilde to prevent +%% `=' symbols being gobbled by the test (realized by accident). +%% %% 2009/04/13 +%% \par\noindent %% 2010/03/11 +%% |\SectionLevelThreeParseInput|: +\newcommand*{\SectionLevelThreeParseInput}{% + \expandafter \test_sec_level_iii \fdInputLine ~========&} +%% |\SectionLevelTwoParseInput| +\newcommand*{\SectionLevelTwoParseInput}{% + \expandafter \test_sec_level_ii \fdInputLine ~======&} +%% and |\SectionLevelOneParseInput| +\newcommand*{\SectionLevelOneParseInput}{% + \expandafter \test_sec_level_i \fdInputLine ~====&} +%% allow skipping deeper levels for efficiency. +%% % TODO in fifinddo: setup for 2 strings in 1 line 2009/04/13 +%% +%% In the terminology of the 'fifinddo' documentation, the previous +%% three commands are ``sandbox builders." The following three +%% commands are the corresponding ``substring conditionals." +%% However, 'fifinddo' so far %% todo 2009/04/08 +%% only deals with \emph{single} substrings, while here we are +%% dealing with \emph{pairs} of substrings. We are not using +%% general setup macros, but define the parsing macros ``manually," +%% as it is typical in many other macros in 'latex.ltx' and other +%% \LaTeX\ packages. You can fool our macros easily, there is +%% no syntax check. %% todo 2009/04/08 +\def\test_sec_level_iii#1====#2====#3&{% + \IfFDempty{#2}% + {\test_sec_level_ii #1======&}% + {\WriteSection\mdSectionLevelThree{#2}}} +\def\test_sec_level_ii#1===#2===#3&{% + \IfFDempty{#2}% + {\test_sec_level_i #1====&}% + {\WriteSection\mdSectionLevelTwo{#2}}} +\def\test_sec_level_i#1==#2==#3&{% + \IfFDempty{#2}% + {\RemoveTildeArg \ProcessStringWith{#1}{comment}}% + {\WriteSection\mdSectionLevelOne{#2}}} +%% `\ProcessStringWith' here passes the expanded `\fdInputLine' +%% to the general comment detector. +%% +%% |\WriteSection{<command>}{<text>}| replaces an input line +%% with a line \[`<command>{<text>}'\] +%% in the documentation file and switches into ``comment mode." +%% One possible space between `=' and the beginning of <text> +%% and one possible space between the end of <text> and `=' +%% are removed. +%% The method of dealing with surrounding blank +%% spaces is new with v0.3, moreover we now rely on a new method in +%% 'niceverb.sty' v0.3 to support its single right quote feature in +%% section titles.\footnote{&\ignorespaces\ and &\unskip\ used +%% previously do not work in PDF bookmarks.} +\newcommand*{\WriteSection}[2]{% + \TreatAsComment{^^J#1{\trim_correct{#2}}^^J}} +%% Trimming ``other" spaces is a little more clumsy than +%% what the 'trimspaces' package does whose code is by +%% Morten H\o gholm. It still has inspired the following. +\begingroup \MakeOther\ %% CARE! we must not indent ... +\long\gdef\trim_correct#1{\trim_fosp$#1$ $} +\long\gdef\trim_fosp#1$ {% +\IfFDempty{#1}{\trim_losp$}{\trim_losp#1$ }} +%% So we have a string \lq`\trim_losp$<text>$ $'\rq. +\long\gdef\trim_losp$#1 ${\tidy_sp_trim#1$} +%% So we have a string \lq`\tidy_sp_trim<text>$ $'\rq +%% or \lq`\tidy_sp_trim<text>$$'\rq. +\long\gdef\tidy_sp_trim#1$#2${\MakeDocCorrectHook{#1}} +\endgroup +%% We insert `\section' using |\mdSectionLevelOne| etc.\ +%% which the programmer can redefine, e.g., when the +%% documentation is part of a `\section' (or even deeper) +%% according to the ``documentation driver" file. +\newcommand*\mdSectionLevelOne {\string\section} +\newcommand*\mdSectionLevelTwo {\string\subsection} +\newcommand*\mdSectionLevelThree{\string\subsubsection} +%% +%% This sectioning feature is not used in (the documentation) of +%% 'makedoc.sty'---\emph{definitions} of the parsing macros fool +%% the same macros ... +%% +%% \subsection{Commented code} +%% |\TreatAsCode{<text>}| is the opposite to `\TreatAsComment{<text>}': +\newcommand*{\TreatAsCode}[1]{% + \ifPackageCode +% \_empty_code_lines_true + \else + \WriteResult{\string\begin{mdPackageCode}}% + \PackageCodeTrue + \fi + \WriteResult{#1}% +% \WriteResult{\maybe_result_empty_line #1}% +% \let\maybe_result_empty_line\empty +} +%% +%% \subsection{Dealing with empty input lines} %% TODO use!? 2010/03/09 +%% \label{sec:emptylines} +%% |\OnEmptyInputLine| is a default setting (or hook) for what to do +%% with empty lines in the input file. The default is to insert an +%% empty line in the output file: +\newcommand*{\OnEmptyInputLine}{\WriteResult{}} +%% |\NoEmptyCodeLines| changes the setting to suppressing empty code +%% lines, while in ``comment mode" an empty input line \emph{does} +%% insert an empty line, for starting a new paragraph: +\newcommand*{\NoEmptyCodeLines}{%% suppress empty code lines + \renewcommand*{\OnEmptyInputLine}{% + \ifPackageCode \else \WriteResult{}\fi}} +%% There is a better policy---didn't work so far ... +%% +%% \subsection{Bundling typical things: script commands} +%% \label{sec:script} +%% Practical experience suggested the following shorthands, +%% combining commands from 'makedoc' and 'fifinddo'. +%% +%% \subsubsection{Output file and &\filelist\ entry} +%% |\LaTeXresultFile{<output>}| chooses <output> as name +%% for the output file and saves you the extra line for inserting +%% the `\ProvidesFile' line as with 'fifinddo''s +%% `\WriteProvides'---however, it differs, actually it is 'makedoc' +%% that wants to be mentioned with `\ProvidesFile' ... +%% %% (otherwise copied from 'fifinddo') ... +\newcommand*{\LaTeXresultFile}[1]{% + \ResultFile{#1}%%% \WriteProvides} + \WriteResult{% + \string\ProvidesFile{\result_file_name}% + [\the\year/\two@digits\month/\two@digits\day\space + automatically generated with makedoc.sty]}}% +%% \subsubsection{Choose input file and run!} +%% |\MakeDoc{<input>}| preprocesses <input> to render input for +%% \LaTeX, considering what is typical for a \LaTeX\ package as the +%% <input> one here. It reads 'mdoccorr.cfg' (Sec.~\ref{sec:mdoccorr}) +%% automatically. +%% % [`input{mdoccorr.cfg}'] added for what `makedoc.tex' says about it. +%% % See `\make_job_doc' for TODOs about it. +%% % Now also wondering: \ (i)~there are other ways to get the +%% % correcting hook, so why forcing this here? \ +%% % (ii)~different correcting hooks for different input files?---% +%% % In case of a ``header" (see below) we change into ``code mode": +%% |\MakeDoc*{<input>}| \emph{avoids} inputting 'mdoccorr.cfg' +%% (e.g., for allowing replacements specific for the single package). +%% All similar commands (including those invoking `\MakeDoc') +%% get this ``my way" feature as of v0.5: +\newif\if_makedoc_autocorr_ +\_makedoc_autocorr_true %% 2012/04/03 +\newcommand*{\makedoc_maybe_autocorr}{% + \if_makedoc_autocorr_ \input{mdoccorr.cfg}% + \else \_makedoc_autocorr_true \fi} +%% <- TODO warning if one from `TEXMF/' used inadvertently!? +%% avoid reading twice!? %% 2010/03/11 +%% % or read it from 'makedoc' already? %% 2010/03/13 +%% +%% |\makedoc_star<next-cmd>| abbreviates star version definitions: +\newcommand*{\makedoc_star}[1]{% + \@ifstar{\_makedoc_autocorr_false#1}#1} +\newcommand*{\MakeDoc}{\makedoc_star\make_doc_arg} +\newcommand*{\make_doc_arg}[1]{% + \makedoc_maybe_autocorr + \ifnum\header_lines>\z@ + \WriteResult{\string\begin{mdPackageCode}}% + \PackageCodeTrue %% TODO both lines makedoc command!? + %% 2009/04/08 + \else \PackageCodeFalse \fi +%% The loop follows. There is a placeholder `\makedoc_line_body' +%% that is predefined below and can be changed while processing the +%% <input> file. + \ProcessFileWith{#1}{% + \CountInputLines %% stepping line counter is standard + \makedoc_line_body + \process_line_message}% +%% Currently the ``VERSION HISTORY" or, more generally, +%% a final part of the <input> file is typeset verbatim +%% (for ``tabbing" in the version history), +%% so we must leave ``code mode" finally: + \ifPackageCode + \WriteResult{\string\end{mdPackageCode\@empty}}%% self-doc-trick + \PackageCodeFalse %% TODO both lines makedoc command!? 2009/04/08 + \fi +%% When the <input> file has been processed, certain default settings +%% might be restored---in case another <input> file is processed for the +%% same documentation document: +% \HeaderLines{0}% +% \MainDocParser{\SectionLevelThreeParseInput}%% TODO!? 2009/04/08 +} +%% |\MakeCloseDoc{<input>}| %% 2010/03/11 +%% is a kind of shorthand for +%% \[`\MakeDoc{<input>}\CloseResultFile'\] %% was MakeClose 2011/10/12 +%% where `\CloseResultFile' is from 'fifinddo'. +%% The star version \[|\MakeCloseDoc*{<input>}|\] %% 2012/03/18 +%% \emph{avoids} reading 'mdoccorr.cfg': +\newcommand*{\MakeCloseDoc} {\makedoc_star\make_close_doc} +\newcommand*{\make_close_doc}[1]{\MakeDoc{#1}\CloseResultFile} +%% Reimplementation using 'fifinddo' v0.5 failed 2011/11/19: +% \newcommand*{\MakeCloseDoc}{\FinalInputFiletrue\MakeDoc} +%% `\MakeDoc' and `\MakeCloseDoc' actually \emph{process} +%% the <input> file, +%% depending on certain \emph{parameters} some of which are set +%% by the commands described next. +%% +%% \subsubsection{Combining input and output} +%% \[|\MakeSingleDoc[<out-ext>]{<in-output>.<in-ext>}|\] %% 2011/11/05 +%% generates `<in-output>.<out-ext>' from `<in-output>.<in-ext>', +%% using settings like `\MakeDoc'. The default for <out-ext> is `doc'. +%% `\MakeSingleDoc' combines `\LaTeXresultFile' +%% and `\MakeCloseDoc' with appropriate arguments. +%% The star version %% 2012/03/18 +%% \[|\MakeSingleDoc*[<out-ext>]{<in-output>.<in-ext>}|\] +%% \emph{avoids} reading 'mdoccorr.cfg'. +%% (TODO: not so sure about dot vs.\ optional <in-ext>.) +\newcommand*{\MakeSingleDoc}{\makedoc_star\make_single_doc_args} +\newcommand*{\make_single_doc_args}[2][doc]{% + \make_single_doc[#1]#2\@nil} +\def\make_single_doc[#1]#2.#3\@nil{% + \LaTeXresultFile{#2.#1}\MakeCloseDoc{#2.#3}} +%% +%% \subsubsection{Preamble vs.\ main part of input file} +%% A \LaTeX\ package typically has a ``header" or ``preamble" +%% (automatically inserted by 'docstrip') with very scarce information +%% on which file it is and what it provides, and with much more Legalese. +%% Typesetting it in \TeX\ quality may be more misleading than +%% typesetting it \emph{verbatim}. So we typeset it \emph{verbatim}. +%% Now: where does the ``header" end? +%% `\NeedsTeXFormat' might be considered the border.---Yet it seems +%% to be more simple and reliable just to act in terms of the +%% \emph{number of lines} +%% that the header should be long. This length <how-many-lines> is declared by +%% |\HeaderLines{<how-many-lines>}|: +\newcommand*{\HeaderLines}{\def\header_lines} +\HeaderLines{0} +%% So the default is that there aren't any header lines, unless +%% another `\HeaderLines' is issued before some `\MakeDoc'. +%% The way input is parsed \emph{after} the ``header" is set by +%% |\MainDocParser{<parsing-command>}|. +\newcommand*{\MainDocParser}{\def\main_doc_parser} +%% `\SectionLevelThreeParseInput' from section~\ref{sec:secparsers} +%% is the default, two alternatives are defined there, another one is +%% `\ProcessInputWith{comment}' from 'fifinddo' and +%% %% clarified 2010/03/09 `\ref' 2010/03/10 +%% section~\ref{sec:distinguish} +%% (general dividing into code and comments). +\MainDocParser{\SectionLevelThreeParseInput} +%% Here is how `\HeaderLines' and `\MainDocParser' act: +\newcommand*{\makedoc_line_body}{% + \IfInputLine{>\header_lines}% + {\let\makedoc_line_body\main_doc_parser + \makedoc_line_body}% %% switch to deciding + {\TreatAsCode{\fdInputLine}}} %% header verbatim +%% \subsubsection{Screen messages} +%% |\ProcessLineMessage{<command>}| is designed to choose a screen +%% (or log) message <command>. +%% % A simple setting may be \[`\ProcessLineMessage{\message{.}}'\] with +%% `\ProcessLineMessage{\message{.}}' has a result like with 'docstrip'. +%% You just get one dot on screen per input line +%% as a simple confirmation that +%% the program is not hung up. %% TODO phrase!? 2009/04/08 +%% However, the message may slow down a run considerably +%% (if so, choose `\ProcessLineMessage{}' in the script). +%% % , you really have to +%% % wait about a second while you hardly notice the 'makedoc' run +%% % without screen messages. Therefore, the default is \emph{not} +%% % to issue any screen message.%% TODO more complex procedures!? 2009/04/08 +%% %---No! +%% But it is better for beginner users of the package, +%% so made default. %% 2009/04/09 +\newcommand*{\ProcessLineMessage}{\def\process_line_message} +% % \ProcessLineMessage{} %% no, still more efficient: +% \let\process_line_message\relax +\ProcessLineMessage{\message{.}} +%% +%% \subsubsection{Bundling-bundling Standalones} +%% |\MakeInputJobDoc{<header-lines>}{<main-parser>}| +%% by default produces a file +%% \[`\jobname.doc' \mbox{\quad from\quad } `\jobname.sty'\] +%% with some standard settings. %%% \footnote{This command is new with v0.3.} +%% 'mdoccorr.cfg' (for `.txt'$\to$\LaTeX\ functionality) is read, +%% `\HeaderLines{<header-lines>}' +%% and `\MainDocParser{<main-parser>}' and finally +%% `\MakeCloseDoc{\jobname.sty}{\jobname.doc}' +%% % (with the arguments named before) +%% are executed. +%% Here `\jobname' expands to the file name base of the +%% `.tex' file you are running. It is assumed that you are preparing +%% documentation for `\jobname.tex' for your `\jobname.sty'. +%% In order to produce `<my-job>.doc' from `<my-job>.sty' instead, +%% \[`\renewcommand{\mdJobName}{<my-job>}'\] +%% If your input file has a different file name extension +%% <in-ext> than \qtd{`sty'}, use an optional argument +%% of `\MakeInputJobDoc': +%% \[|\MakeInputJobDoc[<in-ext>]{<header>}{<parser>}|\] +%% If the output file +%% should have a different extension <out-ext> than \qtd{`doc'}, +%% you must use \emph{two} optional arguments as follows: +%% \[|\MakeInputJobDoc[<in-ext>][<out-ext>]{<header>}{<parser>}|\] +%% `\MakeInputJobDoc' does \emph{not} execute `\ProcessLineMessage', +%% you can use the latter before so `\MakeInputJobDoc' respects it. +%% +%% |\MakeJobDoc| does the same as `\MakeInputJobDoc' apart from +%% typesetting the <created> file, so the latter needs an additional +%% `\input{<created>}'. +%% The star forms |\MakeInputJobDoc*| and %% 2012/03/18 +%% |\MakeJobDoc*| \emph{avoid} reading 'mdoccorr.cfg'. +%% +%% My original idea was that all preprocessing of package files +%% to be documented should <happen> \emph{before} +%% `\documentclass'---loading +%% 'makedoc.sty' included---inside a group (\lq`{<happen>}'\rq---in +%% order to avoid compatibility issues). +%% However, it now appears to me that loading 'makedoc' the usual way +%% in the document \emph{preamble} +%% and processing the package file (that is to be documented) +%% within the `document' environment works well enough and +%% will be easier to comprehend. +%% +%% This is the code for both `\MakeJobDoc' and `\MakeInputJobDoc': +\@ifdefinable{\mdJobName}{\let\mdJobName\jobname} +\newif\if_makedoc_input_ +\newcommand*{\MakeInputJobDoc}{% + \_makedoc_input_true \makedoc_star\make_job_doc_arg} +\newcommand*{\MakeJobDoc} {% + \_makedoc_input_false \makedoc_star\make_job_doc_arg} +\newcommand*{\make_job_doc_arg}[1][sty] + {\@testopt{\make_job_doc[#1]}{doc}} +%% Reading files as follows would fail with active 'niceverb' settings, +%% so we issue `\noNiceVerb' if it is defined. We do it inside a group +%% in case 'niceverb' settings are to be restored afterwards. +\def\make_job_doc[#1][#2]#3#4{% + \begingroup + \@ifundefined{noNiceVerb}{}% + {\let\MakeNormal\MakeNormalHere \noNiceVerb}% + \makedoc_maybe_autocorr %% 2012/03/17 +%% <- TODO stack danger in group!? 2010/03/13 + \LaTeXresultFile{\mdJobName.#2}% + \HeaderLines{#3}% + \MainDocParser{#4}% + \MakeCloseDoc{\mdJobName.#1}% +%% For typesetting the file just created, some 'nicetext' features +%% may be needed ... so restore the previous ones ... + \endgroup + \if_makedoc_input_\input{\mdJobName.#2}\fi +} +%% This feature may \emph{change}. +%% +%% \subsection{Leaving the package} %% mod. 2012/03/18 +\PopLetterCat\_ %% 2012/08/28 +\endinput +%% +%% \subsection{VERSION HISTORY} + +v0.1 2009/04/03 very first version, tested on morgan.sty +v0.2 2009/04/05 \OnEmptyInputLine, \NoEmptyCodeLines + comment -> PPScomment, \IfFDinputEmpty, + \EveryComment, \PPstring may be par break + 2009/04/08 \InputString -> \fdInputLine, + \section -> \subsection; documentation! + 2009/04/08f. \MakeDoc + 2009/04/12 ``line too long'' w/o redefining \PatternCodes; + \MakeDocCorrectHook + 2009/04/13 tilde with sectioning +v0.3 2010/03/08 \WriteSection 'trimspaces'-like + 2010/03/09 "fool" ("wiki" sectioning) nicer worded, + more use of `...' in place of `\dots'; + different treatment of package code environment + (new separate subsection); clarification on + \ProcessInputWith{comment} + 2010/03/10 supplied `\ref' + 2010/03/11 \MakeCloseDoc; corrected "undifined"; + \par\noindent in ``Sectioning"; \MakeJobDoc + 2010/03/12 &.&.&.; updated copyright + 2010/03/13 corr.: `_' not ``other"; tried to explain my + earlier reasoning about `\ifPackageCode'; + \MakeInputJobDoc + 2010/03/14 \make_doc_job without \niceverb_aux_cat + 2010/03/15 another remark to \ifPackageCode + 2010/03/16 use box with comment line markers; + mdcorr -> mdoccorr + 2010/03/18 report on using \EveryComment + 2010/03/19 '' -> " +v0.4 2010/03/23 "Distinguishing" + 2010/03/24 "both in" + 2010/03/27 switch back to \fdPatternCodes + 2010/03/28 include `% ' commenting style + 2010/03/29 \ResetCodeLineNumbers + 2010/03/30 use \SetPatternCodes, \ResetPatternCodes +v0.41 2010/12/20 \ResetCodeLineNumbers defined globally + 2010/12/21 ... rather presented as a bug-fix + 2011/01/19 \mdStartPackageCode + 2011/01/25 updated (C) +v0.41a 2011/08/22 doc.: makedoc.cfg -> mdoccorr.cfg +v0.41b 2011/10/12 doc.: MakeClose -> MakeDoc +v0.42 2011/11/05 \MakeDoc reads mdoccorr.cfg, \MakeSingleDoc + 2011/11/19 failing reimplementation of \MakeCloseDoc +v0.5 2012/03/17 removing 1 \make_job_doc TODO; star versions; + a few make_doc -> makedoc + 2012/03/18 star variants completed, copyright updated, + doc. "Leaving" +v0.51 2012/04/03 \_makedoc_autocorr_true +v0.52 2012/08/28 using `stacklet.sty' diff --git a/macros/latex/contrib/nicetext/use/mdoccorr.cfg b/macros/latex/contrib/nicetext/use/mdoccorr.cfg new file mode 100644 index 0000000000..6a6a701229 --- /dev/null +++ b/macros/latex/contrib/nicetext/use/mdoccorr.cfg @@ -0,0 +1,61 @@ +\ProvidesFile{mdoccorr.cfg}[2012/11/13 + `makedoc' local typographical corrections] +%% ... also demonstrates 'niceverb.sty'---see the typeset +%% documentation of the present file in `makedoc.pdf'. +%% +%% |\SetPatternCodes{<commands>}| redefines +%% `\PatternCodes' to be used in parsing and replacing +%% (some ``sanitizing"). %% improved line breaks 2010/03/29 +\SetPatternCodes{\MakeOther\\\MakeOther\ } +%% |\StartPrependingChain| initializes setup of a replacement +%% chain: +\StartPrependingChain +%% |\PrependExpandableAllReplacer*{<find>}{<subst>}|: +\PrependExpandableAllReplacer*{etc. }{etc.\ } +%% ... you can keep inter-sentence space after `etc.' +%% by a code line break.---Now we use |\do| as a shorthand: +\renewcommand*{\do}{\PrependExpandableAllReplacer*} +\do{Cf. }{Cf.\ } %% 2011/01/12 +\do{cf. }{cf.\ } %% corr. 2010/03/23 +%% ... but think of `cf.~'. Don't leave `cf.' at code line end! +\do{->}{$\to$} %% 2010/11/06 +\do{<-}{$\gets$} %% 2010/11/06 +% \PrependExpandableAllReplacer{...}{...}{$\dots$} +%% Allow extra space at line end (bug fix `{}' 2011/12/03): +\do{...}{\textellipsis\unkern{}} +%% 2011/10/13: original `\dots' correct before punctuation: +% \PrependExpandableAllReplacer{dots,}{...,}{\dots,} +\do{...)}{\dots)} %% 2011/10/25 +\do{...:}{\dots:} %% 2012/11/07 +\do{... }{\textellipsis\unkern\ } +\do{TODO}{\TODO{}} +%% ... chain starts here, and here |\MakeDocCorrectHook| +%% (silently) enters through a default variant +%% |\SetCorrectHookJobLast| of |\SetCorrectHookJob{<id>}|: +\SetCorrectHookJobLast +%% |\ResetPatternCodes| resets `\PatternCodes' to their default +%% value (which is `\fdPatternCodes'): +\ResetPatternCodes +%% ... restores 'fifinddo' default. +\endinput + +HISTORY +2009/04/05 with makedoc v0.2 +2010/03/11 broke some too long code lines +2010/03/16 rendered `mdoccorr.cfg' +2010/03/22 try \Prepend... +2010/03/23 corrected `cf' +2010/03/29 use \SetPatternCodes etc. +2010/11/06 <- and -> +2010/11/24 `...' ``symmetric variant" of `\textellipsis'; + \StartPrependingChain, no more + \MakeExpandableAllreplacer +2011/01/27 blue "TODO" +2011/09/13 \providecommand for dialogues +2011/10/13 \MDtwodots, without \PXAR, `...,' `...:' +2011/10/25 \textellipsis\unkern from csquotes instead, `...)' +2011/11/13 \PrependExpandableAllReplacer* +2011/12/03 bug fix for 2011/10/25 at line ends +2012/11/07 TODO -> \TODO{} +2012/11/12 using \do +2012/11/13 shorter code lines diff --git a/macros/latex/contrib/nicetext/use/niceverb.sty b/macros/latex/contrib/nicetext/use/niceverb.sty new file mode 100644 index 0000000000..2a24202c90 --- /dev/null +++ b/macros/latex/contrib/nicetext/use/niceverb.sty @@ -0,0 +1,1311 @@ +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +\ProvidesPackage{niceverb}[2015/11/21 v0.62 + minimize doc markup (UL)] + +%% Copyright (C) 2009-2012, 2014 2015 Uwe Lueck, +%% http://www.contact-ednotes.sty.de.vu +%% -- author-maintained in the sense of LPPL below -- +%% +%% This file can be redistributed and/or modified under +%% the terms of the LaTeX Project Public License; either +%% version 1.3a of the License, or any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% We did our best to help you, but there is NO WARRANTY. +%% +%% Please report bugs, problems, and suggestions via +%% +%% http://www.contact-ednotes.sty.de.vu +%% +%% ==== &\newlet ==== +%% |\newlet<cmd><cnd>| counters the risk of mistyping <cmd> +%% with `\@ifdefinable', and even saves some code lines: +\providecommand*{\newlet}[2]{\@ifdefinable#1{\let#1#2}} +\@onlypreamble\newlet +%% +%% ==== Switching Category Codes ==== +%% Underscore as a ``private letter," using 'stacklet' with v0.5: +\RequirePackage{stacklet} \PushCatMakeLetter\_ %% 2012/08/27 +%% v0.3 introduced `\AssignCatCodeTo' and `\MakeNormal'. +%% v0.5 abolishes the former again and uses %% former 2012/08/28 +%% 'actcodes' for some part of `\catcode' switching: +\RequirePackage{actcodes} +%% |\CatCode{\<character>}| +%% (or simply |\CatCode\<character>|) +%% saves one token per use and works when the category code +%% of \qtd{&`} (``single left quote") has changed. +%% As of v0.5, it may be defined by a different package: +\providecommand*{\CatCode}{\catcode`} %% \provi... 2012/08/27 +% \newcommand*{\CatCode}[1]{\catcode`#1 } %% no better 2010/02/27 +%% `\CatCode' is near to be moved into the 'catcodes' bundle, +%% and basic commands from 'stacklet' and 'actcodes' +%% may be reimplemented using it +%% ('manycats'; 'allcats' for loading entire 'catcodes' +%% in good order). +%% +%% |\AssignCatCodeTo{<number>}{\<char>}| \ %% \ 2012/08/28 +%% no longer is considered +%% useful (counted tokens in `memory.tex') and replaced by +%% `\CatCode'. +% \newcommand*{\AssignCatCodeTo}[2]{\catcode`#2=#1\relax} +%% |\MakeLetter\<char>| is replaced by the 'stacklet' package---I +%% thought, but \emph{here} it is also needed to declare +%% the ``private letters" of the package that is documented. +%% This should be ``variable." OK, the new (v0.5) `\private_letters' +%% is a step towards this: +\newcommand*{\private_letters}{\CatCode\@11\CatCode\_11\relax} +%% |\MakeOther\<char>| and |\MakeActive\<char>| were implemented +%% here before v0.5, now they are in 'actcodes'~... +% \def \MakeOther {\AssignCatCodeTo{12}} +%% % |\MakeActive\<char>| just revives the meaning of <char> +%% % it had most recently +%% % (as an &\active character ... +%% % maybe ``Undefined control sequence" unless ...) +%% % This is fine for reviving 'niceverb' functionality +%% % after having disabled it by `\MakeNormal'\linebreak[0]---provided +%% % no other package used <char> actively in the meantime ... +%% % % \providecommand*{\MakeActive}[1]{\CatCode#1\active} +%% % We take a copy |\MakeActiveHere| of `\MakeActive' +%% % as the latter may become a dangerous thing for compatibility +%% % with 'hyperref'. +%% % % \@ifdefinable\MakeActiveHere{% +%% % % \let\MakeActiveHere\MakeActive} +%% % % %% <- TODO aliascid + elsewhere 2010/03/12 +%% |\MakeActiveLet\<char>\<macro name>| +%% % is provided by 'actcodes' +%% % (which does not provide `\MakeActive'). %% rm. 2012/09/27 +%% % We take a copy |\MakeActiveLetHere| as well: +%% likewise is in 'actcodes'. 'niceverb' takes a copy +%% |\MakeActiveLetHere| of it for dealing with 'hyperref' +%% (see \secref{hyperref}). +%% 'hyperref'-compatibility of mere `\MakeActive' +%% is not provided any longer: +\newlet\MakeActiveLetHere\MakeActiveLet +%% %% |\MakeAlign\&| can be used to restore the meaning of `&' after we +%% %% have made it `\active'. +%% % \providecommand*{\MakeAlign} {\AssignCatCodeTo4} +%% For restoring the usual category codes of \TeX's special +%% characters later, we store them now. +%% (I.e., these characters are listed in the macro `\dospecials' +%% that expands to +%% $$\mbox{\tt\def\do{\string\do\unskip\string}\dospecials}$$ +%% their category codes are +%% {\CatCode\#6%% was \AssignCat... 2012/08/27 +%% \CatCode\$3%% fifinddo-interference!? TODO 2010/02/27 +%% \CatCode\&4%% fifinddo-interference!? TODO 2010/02/27 +%% \def\do#1{\def\do##1{, +%% \the\CatCode##1}\the\CatCode#1}\dospecials} +%% respectively; ``end of line", ``ignored", ``letter", ``other", and +%% ``invalid" are missing---cf. {\it \TeX book} Chap.\,7.) +\def\do#1{\expandafter +% \chardef \csname normal_catcode_\string#1\expandafter \endcsname +%% <- v0.6 2014/03/22: First I thought ``too few `\expandafter's"; +%% actually the original `\expandafter' has no effect -> + \chardef \csname normal_catcode_\string#1\endcsname + \CatCode#1\relax} +\dospecials +%% Tests: +%% %\withcsname\show normal_catcode_\string\\\endcsname %% 2014/03/22 +%% ``normal category code" of `\' is +%% \expandafter\the\csname normal_catcode_\string\\\endcsname, +%% ``normal category code" of `$' is +%% \expandafter\the\csname normal_catcode_\string\$\endcsname; +%% ``normal category code" of `&' is +%% \expandafter\the\csname normal_catcode_\string\&\endcsname.%%% +%% \footnote{\LaTeX's \cs{nfss@catcodes} is similar, +%% but it makes space-like characters ignored. +%% Also cf. 'ltfinal.dtx'. +%% TODO: &\RestoreNormalCatcodes.} %% 2010/03/06 +%% +% \newcommand*{\make_iii_other}{\MakeOther\\\MakeOther\{\MakeOther\}} + %% <- replaced 2009/04/05 +%% |\MakeNormal\<char>| saves you from remembering ... +\newcommand*{\MakeNormal}[1]{% + \@ifundefined{\norm_catc_str#1}% + {\MakeOther#1}% + {\CatCode#1\csname\norm_catc_str#1\endcsname\relax}} +\newcommand*{\norm_catc_str}{normal_catcode_\string} + %% TODO add ^^I and ^^M + %% TODO save char tokens %% 2012/08/27 +%% We take a copy |\MakeNormalHere| of `\MakeNormal' as +%% with `\MakeActive'. +\newlet\MakeNormalHere\MakeNormal +%% +%% ==== Robustness by &\IfTypesetting\ or So ==== +%% \label{sec:iftype} +%% It seems we need some own ways +%% of robustifying (as opposed to \LaTeX's `\protect' and %% 2014/03/20 +%% `\DeclareRobustCommand'---sometimes, +%% especially for certain active characters) +%% to achieve various +%% compatibilities---using +%% %\begin{center} +%% \[|\IfTypesetting{<if>}{<unless>}|\]%%%. +%% %\end{center} +%% It also saves some `\expandafter's. +\providecommand*{\IfTypesetting}{% +% \relax +%% <- This `\relax' suppressed ligatures of single right quotes! +%% %%^ arrow 2014/03/20 +%% %% removed 2010/03/23 + \ifx \protect\@typeset@protect + \expandafter \@firstoftwo + \else \expandafter \@secondoftwo \fi} +%% %\begin{center} +%% \[|\nvSelfProtect{<cmd-char>}{<typeset>}|\] +%% %\end{center} +%% is another idea. +%% In ``typesetting mode," <typeset> is run. +%% Otherwise a single unexpanded token <cmd-char> remains. +%% TODO bad at `\shipout'. +%% No `\protect' appears, and as opposed to \LaTeX's +%% protection mechanism, running <typeset> does not +%% require a second macro name. +%% The idea is that +%% %`\nvSelfProtect{<cmd-char>}{<typeset>}' +%% `\nvSelfProtect{#1}{#2}' +%% is the \emph{definition} (substitution text---on +%% token level) of <cmd-char>.\footnote{This +%% may go into a separate package under a different name later.} +\newcommand*{\nvSelfProtect}[2]{% + \ifx \protect\@typeset@protect + \nv_expand_else{#2}% %% braces 2014/03/26 +% \else \protect#1\fi} + \else \noexpand#1\fi} %% works 2014/03/28 +\def\nv_expand_else#1\else#2\fi{\fi#1} +%% %% 2014/03/27 +%% Sometimes ``control sequences" get definitions with +%% `\svSelfProtect' below whose first argument then is +%% an active character---the ``control sequence" then +%% is the ``permanent alias" of the active character. +%% This is a somewhat ``indirect self"-protection. +%% At other places, the ``self"-protection is more +%% direct. Then |\NewSelfProtectedCommand{<cmd>}{<def>}| avoids +%% mistakes from mistyping <cmd> and saves some code. +%% It works like `\newcommand*', provides the +%% `\svSelfProtect', and your definition <def> needs to contain +%% the second argument of `\svSelfProtect' only. +%% \emph{Arguments} are not supported currently +%% (TODO---well, 3 applications 2014/03/27):{\sloppy\par} +\newcommand*{\NewSelfProtectedCommand}[2]{% + \newcommand*#1{\nvSelfProtect#1{#2}}} +\@onlypreamble\NewSelfProtectedCommand +%% TODO 3 applications for the permanent alias case, +%% saving catcode changes ... %% 2014/03/28 +%% +%% \strong{Testing:} +\newcommand*{\nvShowProtectedEdef}[1]{% + \protected@edef\@tempa{#1}\show\@tempa} +%% +%% ==== Shared Shorthand Macros ==== +%% |\begin_min_verb| is a beginning shared by some macros here. +%% It begins like \LaTeX's `\verb', apart from the final `\tt'. +%% %% 2014/03/18: +%% `\bgroup' is needed for `\hbox' and must be balanced by +%% an `\egroup' counterpart later. +\newcommand*{\begin_min_verb}{% + \relax \ifmmode \hbox \else \leavevmode\null \fi + \bgroup \tt} +%% For typographical additions (``decorations") to the verbatim material, +%% we collect it in a box register addressed by |\niceverb_savebox|: +\newsavebox\niceverb_savebox +%% |\SetNiceVerbSaveBox| starts reading the (``meta-")verbatim +%% material: +\newcommand*{\SetNiceVerbSaveBox}{% + \setbox\niceverb_savebox\hbox\bgroup} +%% |\NVerb|, |\HardNVerb|, or |\NiceMaybeMetaVerb| +%% with an optional argument about as `[\<id>_egroup]' should follow, cf. +%% \secref{nverb}.---There have been two applications +%% only up to now (2014/03/19), but this may change soon.%%%\footnote{% +%% % Thought of &\qtdnverb, but this doesn't need this kind +%% % of treatment.} %% 2014/03/20 +%% %% introduced in v0.6 +%% +%% |\TheNiceVerbSaveBox| allows referring to the verbatim material +%% collected, in order to place it a \emph{single time}---and no +%% surrounding braces are needed: +\newcommand*{\TheNiceVerbSaveBox}{\box\niceverb_savebox} +%% TODO: +%% \begin{center} +%% |\NewNiceVerbDecoration{\<deco>}{\<end-name>}{<start>}{<end-code>}| +%% \end{center} +%% might save from typing `\<end-name>' twice and from typing +%% the two `\egroup's. +%% +%% %\section{&\+*[<opt>]{<mand>} `{verbatim}' ``o''} %% 2014/03/28 +%% TODO left quote verb moving: braces get lost. %% 2014/03/28 +%% %\nvShowProtectedEdef{``''&\+<name>} +%% === Implementation of the ``Nice" Syntax === +%% ==== &\NVerb ==== +%% \label{sec:nverb} +%% Discovered mistakes in this section 2014/03/19, %% 2014/03/20 +%% with respect to robustness. \ +%% (i)~`\NVerb' not really was meant to be a user command, +%% to appear in documentation code (rather to be internal). \ +%% (ii)~The attempt to make it robust was incomplete. \ +%% (iii)~The code for ``not typesetting" was strange. \ +%% (iv)~It is difficult to imagine that somebody attempts +%% to use ``verbatim" code, e.g., in a section title +%% (while with our `&'/`\string' it's ok). +%% \emph{At least handy replacement for &\textsf.} \ %% 2014/03/28 +%% Well, let's see. May be I once find a useful application. +%% So I repair the code---`\protect' before &\_...`_false'. +%% |\NVerb<char><code><char>|: +\newcommand*{\NVerb}{% + \protect\_no_nice_meta_verb_false \NiceMaybeMetaVerb} +%% |\HardNVerb<char><code><char>| does not recognize meta-variables: +\newcommand*{\HardNVerb}{% + \protect\_no_nice_meta_verb_true \NiceMaybeMetaVerb} +\newif\if_no_nice_meta_verb_ +%% v0.6 equips both |\NVerb[<end-cmd>]| and %% 2014/03/18 +%% |\HardNVerb[<end-cmd>]| with an optional argument for a single +%% parameter-less macro for what to do after reading +%% verbatim text---for boxing or quoting etc.\footnote{The +%% goal resembles that of &\collectverb in Martin Scharrer's +%% \ctanpkgref{newverbs}. A difference in implementation is +%% that the character delimiting the verbatim text +%% is used as a parameter delimiter for a new/temporary macro. +%% So the verbatim characters are fixed. Our approach will be +%% collecting the verbatim material in a box, if we need +%% something more complex than %&\niceverb_normal_egroup. +%% \cs{niceverb_mormal_egroup}. +%% This allows changing category codes with &\MetaVar again, +%% although there hasn't been a need for this so far. +%% It might be useful for allowing shorthand macros in +%% &\MetaVar's argument.} +%% |\niceverb_egroup| then is useless and removed. +%% Macros that were assigned to it before v0.6 move into +%% the new optional arguments.---Actually, the next macro +%% |\NiceMaybeMetaVerb| shared by `\NVerb' and `\HardNVerb' +%% gets the optional argument: TODO!? +% \newcommand*{\nice_maybe_meta_verb}[1]{% +\newcommand*{\NiceMaybeMetaVerb}[2][\niceverb_normal_egroup]{% +%% `\newcommand' with v0.6 must suffice for robustness, +%% so removing 2014/03/20: +% \IfTypesetting{% +%% Mainly avoid `\verb''s noligs list which overrides definitions +%% of some active characters, while 'cmtt' doesn't have any +%% ligatures anyway. + \begin_min_verb + \let\do\MakeOther \dospecials +%% Turn off 'niceverb' specials: + \MakeOther\|\MakeOther\`\MakeOther\'% + \if_no_nice_meta_verb_ \MakeOther\<% + %%% \else \MakeActiveLet\<\MetaVar %% 2010/12/31 + \else \MakeActiveLetHere\<\MetaVar %% 2011/06/20 + \fi +% \MakeActiveLetHere #2\niceverb_egroup + \MakeActiveLetHere #2#1% %% 2014/03/18 +%% After the previous line has worked, we use `\def' +%% instead of `\let', so there is no longer a need +%% to choose a command name for the verbatim delimiter +%% -- well, \strong{no}, don't define the same +%% macro several times. Also, the same ``end" macro +%% might be used for different purposes, e.g., +%% when a macro in an eventual expansion of the ``end" macro +%% is modified. +% \MakeActiveDef #2{#1}% %% 2014/03/18 + \verb@eol@error %% TODO change message 2009/04/09 +% }{\string\NVerb \string#1}} +%% <- both `\string' very strange +%% (second one finds <char>---maybe it's active---but +%% then its next occurrence delimiting the verbatim code +%% will harm too!), +%% also redirecting to `\NVerb'. +%% (May have been ok for entries to auxiliary files.) +%% New difficulties come from the optional argument, +%% which needs protection as well.---Ok, the optional +%% argument is not protected, and active characters +%% <char> must ``protect themselves," so use of +%% `\IfTypesetting' changes, cf. \secref{iftype}. +} +%% %2009/04/11: about `etc.' [preceding a box!? 2010/03/14] +%% [2014/03/19 removing/hiding +%% remarks from 2009f. that I don't understand anymore~...] +\newcommand*{\niceverb_normal_egroup}{% + \egroup + \niceverb_maybe_rq %% 2011/09/09 for \AddQuotes + \ifmmode\else\@\fi} +% \@ifdefinable\niceverb_egroup %% rm 2014/03/18 +% {\let\niceverb_egroup\niceverb_normal_egroup} +%% +%% ==== Single Quotes Typeset Meta-Code ==== +%% |\LQverb| will be a ``permanent alias" +%% for the active left single quote. +%% +%% The verbatim feature must not act when another single left +%% quote is ahead---we assume a double quote is intended then, +%% and we typeset it +%% (thus the left quote feature does not allow to typeset +%% something verbatim that starts with a single left quote). +%% %Rather, double quotes should be typeset then. rm. 2014/03/25 +%% In page headers, a `\protect' +%% could %%% may %% 2014/03/28 +%% be in the way %%%.\footnote{% +%% % See \code{\string\show\cs{let_token}} below---tried %% 2014/03/24 +%% % with section title in `niceverb.tex'.} +%% before v0.6. +%% (A hook for `\relax'ing certain things in +%% `\markboth' and `\markright' would have been an alternative. +%% TODO) %% 2014/03/24 +\MakeActive\` + \newcommand*{\LQverb}{% +% \IfTypesetting{\lq_double_test}{\protect`}} +%% New approach v0.6: + \nvSelfProtect`\lq_double_test} +% \IfTypesetting{\lq_double_test}{\noexpand`}} +\MakeOther\` +\newcommand*{\lq_double_test}{% +%% This test settles the next catcode, so better switch to ``other" +%% in advance (won't harm if left quote isn't next): +%% TODO switch what? %% 2014/03/27 + \begingroup + \let\do\MakeOther \dospecials + \MakeOther\|%% 2010/03/09! + \futurelet\let_token \lq_double_decide} +\newcommand*{\lq_double_decide}{% + \ifx\let_token\LQverb + \endgroup + ``\expandafter \@gobble +%% ... alternative ... +% \expandafter `% +%% does not recognize next left quote---why? TODO---Corresponding +%% right quotes will become ``other" due to +%% having no space at the left. +%% TODO to be changed with 'wiki.sty'. + \else +% \ifx\let_token\protect %% rm. 2014/03/28 +% % \show\let_token %% indeed before v0.6, 2014/03/24 +% \expandafter\expandafter\expandafter \lq_double_decide_ii +% \else + \endgroup + \niceverb_maybe_qs %% 2011/09/09 +% \expandafter\expandafter\expandafter \NVerb +% \expandafter\expandafter\expandafter \'% +%% <- 2015/11/20 with one conditional less, less \expandafter -> + \expandafter \NVerb \expandafter \'% +% \fi + \fi} +%% `\lq_double_decide_ii' continues test behind `\protect'. +\newcommand*{\lq_double_decide_ii}[1]{% + \futurelet\let_token \lq_double_decide} +%% +%% ==== Ampersand (or &\cstx) Typesets Meta-Code ==== +%% |\CmdSyntaxVerb| will be a permanent alias for the active `&'. +\MakeActive\& + \newcommand*{\CmdSyntaxVerb}{% + \IfTypesetting{% + \begin_min_verb +%% v0.3 moves the previous line from &\cmd_syntax_verb +%% %% <- shows bug is fixed 2010/03/09 +%% where it is too late to establish private letters +%% according to next line which was in `\begin_min_verb' +%% earlier---an important bug fix! + \private_letters %% v0.5 + \cmd_syntax_verb +% }{\protect&\string}} +% }{\noexpand&\string}} +%% ... with `\string', in an `\edef', the following +%% command cannot be properly typeset, so + }{\noexpand&\noexpand}} %% 2014/03/26 +%% TODO actually test non-typesetting, maybe introduce +%% macros that perform tests anywhere ... +%% %e.g., `\typeout'~... %%% \typeout{``}\show& %% 2014/03/27 +\MakeNormal\& +\newcommand*{\cmd_syntax_verb}[1]{% + \string#1\futurelet\let_token \after_cs} +%% However, `&' (or `\CmdSyntaxVerb') +%% may fail with private letters, +%% % (there should be a hook for them), %% todo 2010/02/28, +%% %% rm 2014/03/17 after v0.5 +%% especially in \emph{macro arguments}\footnote{%% 2010/03/05 +%% TODO: 'vfoot2e.sty' -- see notes.} +%% and with 'hyperref' in titles of %% 2010/03/11 +%% \emph{sections bearing \cs{label}s}, +%% so we provide something like |\cs{<characters>}| from +%% '\ctanpkgref{tugboat}.sty'. %% 'doc.sty'.%% corr. 2011/05/27 +\DeclareRobustCommand*{\cs}[1]{% +% \begin_min_verb \backslash_verb #1\egroup} +%% ... fails with `_' in footnote today (2014/03/19) so: + \begin_min_verb \withcsname\string#1\endcsname\egroup} %% v0.6 +\newcommand*{\backslash_verb}{\char`\\} +%% %% 2011/06/27: undid 2011/05/27 +%% Moreover, typing `&\par' in ``short" \emph{macro arguments} +%% fails, you better type `\cs{par}' then. Likewise, +%% `\cs{if<letters>}' and `\cs{fi}' is safer in case +%% you want to skip some part of the documentation +%% (e.g., a package option skips commented code) +%% by \cs{if}`<letters>'\cs{fi}. +%% Finally, there will be PDF bookmarks support for `\cs' +%% rather than for a real `&' or `\CmdSyntaxVerb' analogue like +%% |\cstx{<characters>}*[<opt>]{<mand>}| as follows. %% corr. 2014/03/27 +\DeclareRobustCommand*{\cstx}[1]{% %% corr. 2010/03/17 +% \begin_min_verb \backslash_verb #1% +%% v0.6 like above: + \begin_min_verb \withcsname\string#1\endcsname + \futurelet\let_token \after_cs} +\newcommand*{\after_cs}{% + \ifcat\noexpand\let_token a\egroup \space + \else \expandafter \decide_verb \fi} +\newcommand*{\test_more_verb}{\futurelet\let_token \decide_verb} +\newcommand*{\decide_verb}{% + \jumpteg_on_with\bgroup\braces_verb + \jumpteg_on_with[\brackets_verb + \jumpteg_on_with*\star_verb + \egroup} + %% CAUTION/TODO wrong before (... if cmd without arg + %% use \ then or choose usual verb... + %% or \MakeLetter\( etc. ... or \xspace +\newcommand*{\jumpteg_on_with}[2]{% + \ifx\let_token#1\do_jumpteg_with#2\fi} +%% TODO cf. 'xfor', 'xspace' (&\break@loop); +%% `\DoOrBranch#1'\,...\,`#1' or so. %% found 2010/03/05 +%% %% <- `...' fix 2011/01/19 +\def\do_jumpteg_with#1#2\egroup{\fi#1} +\def\braces_verb#1{\string{#1\string}\test_more_verb} +\def\brackets_verb[#1]{[#1]\test_more_verb} +\def\star_verb*{*\test_more_verb} + %% not needed with \Auto... OTHERWISE useful in args! +%% %%2010/03/15: +%% As 'latex.ltx' has `\endgraf' as a permanent alias for the +%% primitive version of `\par' and `\endline' for `\cr', +%% we offer |\endcell| as a replacement for the original `&': +\let\endcell& +%% +%% ==== Escape Character Typesets Meta-Code ==== +%% \label{sec:esc} +%% |\BuildCsSyntax| will be a permanent alias for the active escape +%% character. +\DeclareRobustCommand*{\BuildCsSyntax}{% + \futurelet\let_token \build_cs_syntax_sp} +\newcommand*{\build_cs_syntax_sp}{% + \ifx\let_token\@sptoken + \@% %% 2010/12/30 + \else %% TODO ^^M!? + \expandafter \start_build_cs_syntax + \fi} +\newcommand*{\start_build_cs_syntax}[1]{% + \edef\string_built{\string#1}% +%% #1 may be active.---With Donald Arseneau's 'import.sty' (e.g.), +%% \qtd{&_} may be needed to be `\active' with the meaning of +%% `\textunderscore', therefore restoring its category code +%% needs some more care than with v0.32 and earlier: + \edef\before_build_cs_sub{\the\CatCode\_}% + \private_letters %% v0.5 + \test_more_cs} +\newcommand*{\test_more_cs}{% + \futurelet\let_token \decide_more_cs} +\newcommand*{\decide_more_cs}{% + \ifcat\noexpand\let_token a\expandafter \add_to_cs + \else +% \MakeNormalHere\_ +%% Restoring \qtd{&_} more carefully with v0.4 +%% (`\begingroup' ... `\endgroup'!?): +%% %% 2010/03/27 + \CatCode\_\before_build_cs_sub + \MakeOther\@% +% \expandafter \in@ \expandafter +% {\csname \string_built \expandafter \endcsname +% \expandafter}\expandafter{\niceverbNoVerbList}% + %% <- useless braces 2014/07/17 -> + \expandafter \in@ \csname \string_built \expandafter + \endcsname \expandafter {\niceverbNoVerbList}% + \ifin@ + \csname \string_built + \expandafter\expandafter\expandafter \endcsname + \else + \begin_min_verb \backslash_verb\string_built + \expandafter\expandafter\expandafter \test_more_verb + \fi + \fi} + %% TODO such \if nestings with ifthen!? + %% cf.: +% \let\let_token,\typeout{\meaning\let_token} + %% TEST TODO fuer xspace!? (\ifin@) +\newcommand*{\add_to_cs}[1]{% + \edef\string_built{\string_built#1}\test_more_cs} +%% +%% |\AutoCmdSyntaxVerb| starts, |\EndAutoCmdSyntaxVerb| \emph{ends} +%% ``auto mode." +\newcommand*{\AutoCmdSyntaxVerb}{% + \MakeActiveLetHere\\\BuildCsSyntax} +\newcommand*{\EndAutoCmdSyntaxVerb}{\CatCode\\\z@} +%% |\NormalCommand{<characters>}| executes `\<characters>' +%% in ``auto mode." +\newcommand*{\NormalCommand}{} \let\NormalCommand\@nameuse +%% %% 2010/03/11: +%% Once I may want to use this feature in {\it Wikipedia}-like +%% section titles as supported by 'makedoc', yet I cannot really +%% apply the present feature soon, so this must wait ... +%% (There is a special problem with `\newlabel' and 'hyperref' ...) +%% +%% Former tests: +% \futurelet\LetToken\relax \relax +% \show\LetToken \typeout{\ifcat\noexpand\LetToken aa\else x\fi} +%% +%% |\niceverbNoVerbList| is the list of macros that will be +%% \emph{executed} instead of being typeset. +\newcommand*{\niceverbNoVerbList}{% + \begin\end\item\verb\EndAutoCmdSyntaxVerb\NormalCommand + \section\subsection\subsubsection} %% TODO!? +%% |\AddToMacro{\niceverbNoVerbList}{<macros>}| can be used to +%% add <macros> to that list. +\providecommand*{\AddToMacro}[2]{% %% TODO move to ... 2010/03/05 + \expandafter \def \expandafter #1\expandafter {#1#2}} + %% <- was very wrong 2010/03/18 +%% Hey, or just |\AddToNoVerbList{<macros>}|: %% 2010/03/28 +\newcommand*{\AddToNoVerbList}{\AddToMacro\niceverbNoVerbList} +%% +%% ``Auto mode" probably ain't mean a thing if it ain't invoked using +%% \[|\AutoCmdInput{<file>}|\] for typesetting <file> in ``auto mode:" +\newcommand*{\AutoCmdInput}[1]{% + \begingroup + \AddToMacro\niceverbNoVerbList{\ProvidesFile}% + %% <- removed `\endinput', will be code! 2010/04/05 + \AutoCmdSyntaxVerb + \input{#1}% + \EndAutoCmdSyntaxVerb + \endgroup +} +%% +%% ==== Meta-Variables ==== +%% |\MetaVar<var-id>>| will be a permanent alias for the active \qtd{&<}. +%% v0.6 simplifies `\pdfstringdefDisableCommands'. %% was \PDF... +% \def\MetaVar#1>{% +\MakeActive\< +\newcommand*{\MetaVar}{\nvSelfProtect>\nvMetaVar} +\MakeOther\< +\def\nvMetaVar#1>{% + \mbox{\normalfont\itshape $\langle$#1\/$\rangle$}} +%% As opposed to 'ltxguide.cls', this works outside verbatim as well. +%% TODO: offer without angles as well %% moved down 2014/03/25 +%% +%% ==== Hash Mark is Code ==== +%% |\HashVerb<digit>| will be a permanent alias for the active hash mark. +\newcommand*{\HashVerb}[1]{{\tt\##1}} +%% +%% ==== Single Right Quotes for &\textsf ==== +%% \label{sec:rqsf} +%% |\RQsansserif| will be a permanent alias for the active single +%% right quote. +%% +%% One essential %% 2014/03/25 +%% problem with the single right quote feature +%% %problem with the ``single right quote feature" +%% is that a single right quote may be meant to be an apostrophe. +%% This is certainly the case at the right of a letter. +%% On the other hand, we assume that it is \emph{not} an apostrophe +%% (i)~in vertical mode (opening a new paragraph), +%% (ii)~after a horizontal skip. +%% +%% %% 2014/03/25: +%% Another problem is that with and \LaTeX\ +%% (as with Plain \TeX---\meta{The \TeX book}\ p.~357), +%% the right single quote is needed for primes in math mode, +%% and \LaTeX\ enforces this in `\@outputpage' preparing +%% `\write's (why? TODO) as well as page headers. +\MakeActive\' + \newcommand*{\niceverb_rq_choice}[1]{% %% 2014/03/27 +%% We make a deal with `\active@math@prime': in math mode, +%% the prime functionality acts; outside, the ``right quote +%% sansserif mode" acts. +%% Test: $a'$ now works with 'niceverb'.---For +%% page headers, in expanding without typesetting, +%% the expansion of `\RQsansserif' must contain another active +%% single right quote. + \nvSelfProtect'{\ifmmode + \expandafter\active@math@prime + \else + \expandafter#1% + \fi}} +%% The following `\do_rq_sansserif' is what |\DoRQsansserif| +%% below was before v0.6. This, too, must be changed for +%% `\active@math@char', and earlier use of `\DoRQsansserif' +%% in `\niceverb_rq_sf_test' must be replaced. + \@ifdefinable\do_rq_sansserif + {\def\do_rq_sansserif#1'{\textsf{#1}}} + \newcommand*{\RQsansserif}{% +% \IfTypesetting{\niceverb_rq_sf_test}{\protect'}} + \niceverb_rq_choice\niceverb_rq_sf_test} +\MakeOther\' +%% Another macro just to avoid more sequences of `\expandafter': +\newcommand*{\niceverb_rq_sf_test}{% + \ifhmode + \ifdim\lastskip>\z@ +% \expandafter\expandafter\expandafter \DoRQsansserif + \expandafter\expandafter\expandafter \do_rq_sansserif + \else + \ifnum\niceverb_spacefactor + \expandafter\expandafter\expandafter\expandafter + \expandafter\expandafter\expandafter + \do_rq_sansserif %%% \DoRQsansserif + \else '\fi + \fi + \else \ifvmode +% \expandafter\expandafter\expandafter \DoRQsansserif + \expandafter\expandafter\expandafter \do_rq_sansserif + \else '\fi + \fi} +% \nvShowProtectedEdef{'niceverb'} +\MakeOther\' +%% |\DoRQsansserif| %% 2010/03/10 +%% is \emph{another} (possible) alias for the +%% active single right quote, below. +\newcommand*{\DoRQsansserif}{% + \niceverb_rq_choice\do_rq_sansserif} %% 2014/03/27 +%% The following cases are typical and cannot be decided by the +%% previous criteria: +%% (i)~parenthesis, (ii)~footnotes and after ``horizontal" +%% environments like `\[<math>\]', (iii)~section titles, +%% (iv)~`\noindent'. +%% We introduce some dangerous tricks---redefinitions of +%% % \LaTeX's internals `\@footnotetext' and `\@sect' +%% %% <- 2010/03/16 -> +%% \LaTeX's internal `\@sect' and of \TeX's primitives +%% `\noindent' and `\ignorespaces' as well as by +%% a signal `\spacefactor' value of 1001. +%% %In page headers, \LaTeX\ equips the single right quote with the +%% %meaning of `\active@math@prime' which must be overridden. +%% %TODO more serious! v0.6 +%% +%% |\nvAllowRQSS| becomes more powerful with v0.6, +%% for \secref{listmv}: +\NewSelfProtectedCommand{\nvAllowRQSS}{% + \MakeActiveLetHere\'\RQsansserif + \niceverb_rqsf %% 2014/03/27 + \niceverb_ignore} %% 2010/03/16 +%% These and the entire right quote functionality are +%% activated by %% removed todo 2010/03/10 +%% \[|\nvRightQuoteSansSerif| +%% \mbox{\quad and disabled by\quad} +%% |\nvRightQuoteNormal|\]---at +%% `\begin{document}'---where we collect previous settings---or +%% later: +\AtBeginDocument{% + \edef\before_niceverb_parenthesis{\the\sfcode`\(}% + \newlet \before_niceverb_ignore \ignorespaces %% 2010/03/16 + \newlet \before_niceverb_sect \@sect %% \newlet 2014/03/25 + \newlet \before_niceverb_noindent \noindent} %% 2010/03/08 +%% We assume that `\@sect' has the same +%% % We assume that `\@footnotetext' and `\@sect' have the same +%% parameters there as in \LaTeX\ +%% (even if redefined by another package, like 'hyperref'). +\def\niceverb_sect#1#2#3#4#5#6[#7]#8{% + \before_niceverb_sect{#1}{#2}{#3}{#4}{#5}{#6}% +% [{\protect\nvAllowRQSS #7}]% +% {\protect\nvAllowRQSS #8}} +%% With v0.6, a more general |\NiceVerbMove{<text>}| +%% is introduced, defined in \secref{listmv}: + [\NiceVerbMove{#7}]% + {\NiceVerbMove{#8}}} +%% 2010/03/20: +\newcommand*{\niceverb_spacefactor}{\spacefactor=1001\relax} +\newcommand*{\niceverb_noindent}{% + \before_niceverb_noindent \niceverb_spacefactor} +\newcommand*{\niceverb_ignore}{% + \ifhmode \niceverb_spacefactor \fi \before_niceverb_ignore} +%% +%% Here are the main switches. With v0.6, |\nvRightQuoteSansSerif| +%% is divided into two parts, for \secref{listmv}: +\newcommand*{\niceverb_rqsf}{% %% 2014/03/27 +% \MakeActiveLet\'\RQsansserif + \sfcode`\(=1001 %% enable in parentheses 2009/04/10 +%% I also added \HardNVerb+\sfcode`/=1001+ in the preamble +%% of 'makedoc.tex'. %% 2010/03/15 +% \let\@footnotetext\niceverb_footnotetext + \let\ignorespaces\niceverb_ignore %% 2010/03/16 +% \let\@sect\niceverb_sect + \let\noindent\niceverb_noindent} %% 2010/03/08 +\newcommand*{\nvRightQuoteSansSerif}{% + \niceverb_rqsf + \MakeActiveLet\'\RQsansserif + \let\@sect\niceverb_sect + \def\niceverb_rqsf_kind{\nvAllowRQSS}} +%% <- It really must be `\def' in order to transmit the +%% choice to the table of contents. +%% +%% With v0.6, in dealing with moving things in +%% \secref{listmv}, section titles are handled +%% in a more complex way. We divide the former +%% |\nvRightQuoteNormal| into two parts: +\newcommand*{\niceverb_rq_normal}{% +% \MakeNormal\'% %% 2010/03/21 + \sfcode`\(=\before_niceverb_parenthesis\relax + \let\ignorespaces\before_niceverb_ignore %% 2010/03/16 + \let\noindent\before_niceverb_noindent} %% 2010/03/08 +\MakeActive\` +\newcommand*{\nvRightQuoteNormal}{% + \MakeNormal\'% %% 2010/03/21 + \niceverb_rq_normal + \let\nv_rqsf_kind\@empty + \ifnum\CatCode\`=\active %% `=' missing 2015/11/09 + \ifx`\LQverb \else + \let\@sect\before_niceverb_sect + \fi + \else + \let\@sect\before_niceverb_sect + \fi} +\MakeOther\` +%% |\nvAllRightQuotesSansSerif| %% 2010/03/10 +%% (after `\begin{document}'!) +%% forces the `\textsf' feature +%% \emph{without} testing for apostrophes. You then must be +%% sure---DANGER! CARE!---to +%% use \qtd{&\rq} only for obtaining an apostrophe and the +%% double quote character \qtd{&"} for closing double quotes, +%% or our `\dqtd{<text>}' for the entire quoting.{\sloppy\par} +\newcommand*{\nvAllRightQuotesSansSerif}{% + \niceverb_rq_normal %%% \nvRightQuoteNormal %% 2014/03/27 +%% That's one use of |\DoRQsansserif| with v0.6: + \MakeActiveLet\'\DoRQsansserif + \def\niceverb_rqsf_kind{\nvAllRQSS}} %% 2014/03/27 +%% <- must be `\def' for transmissions. +\NewSelfProtectedCommand{\nvAllRQSS}{% + \niceverb_rq_normal +%% That's the other use of |\DoRQsansserif| with v0.6: + \MakeActiveLetHere\'\DoRQsansserif} +%% [Hiding remarks from 2010f.\ (`\ctanpkgref') 2014/03/23] +%% %I started v0.31 (signal `\sfcode'=1000, lowercase letters +%% %get `\sfcode'=1001) because +%% %\NVerb+\href{http://ctan.org/pkg/<pkg>}{<pkg>}+ failed. +%% %However, what I actually needed was |\ctanpkgref{<pack-name>}|: +%% % \DeclareRobustCommand*{\ctanpkgref}[1]{% +%% % \href{http://ctan.org/pkg/#1}{\textsf{#1}}} +%% %... moves to 'texlinks.sty' 2011/01/24. +%% +%% ==== Boxes Highlighting Commands and Syntax ==== +%% With v0.3, we include one kind of command syntax boxes +%% whose <content> is (in 'niceverb' syntax) +%% delimited as \GenCmdBox+|<content>|+. +%% %% 2010/03/14: %% \newsavebox!? moves up 2014/03/19 +%% |\GenCmdBox<char><content><char>}| works like +%% `\NVerb<char><content><char>' except putting the latter's result +%% into a framed (or coloured or ...) box.{\sloppy\par} +\newcommand*{\GenCmdBox} {\_no_nice_meta_verb_false \gen_cmd_box} +%% |\HardVerbBox| is a variant of `\GenCmdBox' with the meta-variable +%% feature disabled +%% (for the documentation of the present package). +\newcommand*{\HardVerbBox}{\_no_nice_meta_verb_true \gen_cmd_box} +\newcommand*{\gen_cmd_box}{% +% \let\niceverb_egroup\nice_collect_verb_egroup %% rm 2014/03/18 +% \setbox\niceverb_savebox \hbox\bgroup +%% <- 2014/03/19 -> + \SetNiceVerbSaveBox +% \if_no_nice_meta_verb_ +% \expandafter \HardNVerb +% \else \expandafter \NVerb \fi +%% <- 2014/03/19 -> [TODO use generalization] + \NiceMaybeMetaVerb[\nice_collect_verb_egroup]% +} +\newcommand*{\nice_collect_verb_egroup}{% + \egroup \egroup + \ifvmode \expandafter \VerticalCmdBox + \else \ifmmode \hbox \fi + \expandafter \InlineCmdBox \fi +% {\box\niceverb_savebox}% +%% <- 2014/03/19 -> + \TheNiceVerbSaveBox +%% %Modifying invocation of `\niceverb_normal_egroup' 2011/11/05 +%% %according to remark of 2010/03/15 for saving nesting level: +%% (Removing a remark that I don't understand 2014/03/19.) + \ifmmode\else\@\fi +% \let\niceverb_egroup\niceverb_normal_egroup %% rm 2014/03/19 +} +%% |\nvCmdBox| will be the permanent alias for \qtd{&|}. +\newcommand*{\nvCmdBox}{\GenCmdBox\|} +%% |\VerticalCmdBox{<content>}| +%% may eventually start a `decl' environment +%% as in 'ltxguide.cls', looking ahead for another \qtd{&|} +%% in order to (perhaps) append another row. +%% Another possibility is first to do some +%% \[`\if@nobreak\else \pagebreak[2]\fi'\] +%% etc. and then invoke `\InlineCmdBox'. +%% The user can choose later by some `\renewcommand'. +%% We do the perhaps most essential thing here +%% (again cf. `\begin_min_verb'):{\sloppy\par} +\newcommand*{\VerticalCmdBox}{% +%% v0.6 encourages a page break here +%% according to the above idea, in order to avoid +%% a page break after explaining subsequent code +%% (TODO: that's a major functionality change): + \if@nobreak\else \pagebreak[2]\fi + \leavevmode\InlineCmdBox} +%% (2011/11/05 removing `\null'.) +%% The command declaration boxes in the documentation of +%% Nicola Talbot's \ctanpkgref{datatool} +%% would be an especially nice realization of +%% `\VerticalCmdBox'.\footnote{I find the documentation +%% of Martin Scharrer's \ctanpkgref{newverbs} package +%% similarly impressive.} +%% +%% |\InlineCmdBox{<content>}|, according to our idea, should not +%% change baseline skip, even with some `\fboxsep' and `\fboxrule'. +%% (However, it may be a good idea to increase the overall +%% normal baseline skip.) +%% We therefore replace actual height and depth of the content by +%% the height and depth of math parentheses. +\newcommand*{\InlineCmdBox}[1]{% + \bgroup +%% ... needed in math mode with `\begin_min_verb'. + \fboxsep 1pt + \kern\SetOffInlineCmdBoxOuter + \smash{\SetOffInlineCmdBox{\kern\SetOffInlineCmdBoxInner + \InlineCmdBoxArea{#1}% + \kern\SetOffInlineCmdBoxInner}}% + \mathstrut + \kern\SetOffInlineCmdBoxOuter + \egroup +} +%% The default choice for |\SetOffInlineCmdBox| is `\fbox': +\newlet\SetOffInlineCmdBox\fbox +%% You can `\renewcommand' it to change `\fboxsep', `\fboxrule' +%% etc. or to use a `\colorbox' with the 'color' package, e.g., +%% I used the following setting so far: +%% %% 2010/03/10 +%% \begin{verbatim} +%% \RequirePackage{color} +%% \renewcommand*{\SetOffInlineCmdBox} +%% {\colorbox[cmyk]{.1,0,.2,.05}} +%% \end{verbatim} +%% |\SetOffInlineCmdBoxInner| enables controlling the inner +%% horizontal space to the box margin independently of +%% `\fboxsep'. +%% %% We set it to 0\,pt. as default (it is a macro only, +%% %% for a while). +\newcommand*{\SetOffInlineCmdBoxInner}{-\fboxsep\thinspace} +%% This choice is inspired by `\cstok' for ``boxed" things +%% in Knuth's 'manmac.tex' which formats {\it The \TeX book}. +%% %% <- 2010/03/10 +%% +%% |\SetOffInlineCmdBoxOuter| allows that the box hangs out into the +%% margin horizontally. +%% We set it to 0\,pt as default (it is a macro only, for a while). +\newcommand*{\SetOffInlineCmdBoxOuter}{\z@} +%% The height and depth of the frame should be the same for all +%% inline boxes, we think. +%% The present choice |\InnerCmdBoxArea| for the spacing +%% respects code characters rather than the height and depth +%% of the angle brackets that surround meta-variable names. +\newcommand*{\InlineCmdBoxArea}[1]{% + \smash{#1}\vphantom{gjpq\backslash_verb}} +%% \GenCmdBox+\cmdboxitem|<content>|+ is another variant of +%% `\GenCmdBox'. It should replace `\item[<content>]' in the +%% `description' environment. %% 2010/03/15 +\newcommand*{\cmdboxitem}{% +% \bgroup +% \let\niceverb_egroup\cmd_item_egroup +% \global %% TODO!? 2010/03/15 +% \setbox\niceverb_savebox \hbox\bgroup +%% <- 2014/03/19 -> + \SetNiceVerbSaveBox +% \NVerb} +%% <- 2014/03/19 -> + \NVerb[\cmd_item_egroup]} +\newcommand*{\cmd_item_egroup}{% + \egroup \egroup %%% \egroup %% 1 less 2014/03/19 + \item[\InlineCmdBox\TheNiceVerbSaveBox]} +%% %% 2014/03/19: +%% Does it work? +%% \begin{description} +%% \cmdboxitem+\foo{<arg>}+ could be defined for a test. +%% \cmdboxitem+\bar{<arg>}+ could be defined for a test as well. +%% \end{description} +%% +%% === When 'niceverb' Gets Nasty === +%% These things are new with v0.3. +%% ==== Meta-Variables ==== +%% This is even newer than v0.3. %% 2011/05/09 +%% +%% In case you actually need $\lt$ and $\gt$ in math mode, +%% |\lt| and |\gt| are ``provided" as aliases: +\providecommand*{\gt}{>} +\providecommand*{\lt}{<} +%% +%% ==== Quotes ==== +%% %% WRONG 2010/03/05: +%% % The left quote feature for meta-code requires that the right quote +%% % feature---for replacing `\textsf'---is activated---no, rather: +%% % that the right quote \qtd{&'} is `\active'. +%% % +%% In order to get \emph{real} single quotes, you could use `\lq <text>\rq', +%% maybe appending a `\ ', but the code |\qtd{<text>}| may look better +%% and be easier to type. +\providecommand*{\qtd}[1]{`#1'} %% provide 2012/11/27 +%% However, here we get the problem that the left quote in +%% \NVerb\+\qtd{`<code>'}+ will be unable to switch into +%% verbatim mode entirely---then use `&', +%% e.g., \qtd{&\qtd{&&&&}} typesets \qtd{\qtd{&&}}, i.e., +%% the ampersand in single (non-verbatim) quotes. +% todo \qtdverb!? alternative meaning for \LQverb!? 2010/03/06 +% rather rare, & takes less space 2010/03/09 +%% ... see approaches below~... +%% +%% |\AddQuotes| automatically surrounds code with single quotes. +%% I have so often felt that it was a design mistake +%% to drop them (2011/09/09): +\newcommand*{\AddQuotes}{% + \let\niceverb_maybe_qs\niceverb_add_qs} +\newcommand*{\niceverb_add_qs}{% +%% In a math display, quotes are suppressed even with `\AddQuotes': + \ifmmode\else + `\let\niceverb_maybe_rq\niceverb_rq + \fi} +\newlet\niceverb_maybe_rq\relax +\newcommand*{\niceverb_rq}{'\let\niceverb_maybe_rq\relax} +%% You can undo this by |\DontAddQuotes|: +\newcommand*{\DontAddQuotes}{\let\niceverb_maybe_qs\relax} +%% The default will be the behaviour that we had before: +\DontAddQuotes +%% With v0.6, |\qtdnverb<char><m-verb><char>| encloses the +%% ``meta-verbatim" material with single quotes: +\newcommand*{\qtdnverb}{% +%% Useless after `\AddQuotes': %% mod. 2015/11/20 + \ifx\niceverb_maybe_qs\niceverb_add_qs + \expandafter \NVerb + \else + \lq + \expandafter\NVerb\expandafter + [\expandafter\niceverb_egroup_rq\expandafter]% +%% <- The comment mark proved essential 2015/11/20. +%% The line was commented out previously, obviously I had forgotten +%% that the feature didn't work. + \fi} +%% Completing the work v0.62: +\newcommand*{\niceverb_egroup_rq}{\niceverb_normal_egroup\rq} +%% |\dqtd{<text>}| can be used for enclosing in \emph{double} quotes +%% with the dangerous `\nvAllRightQuotesSansSerif' (see above). +\providecommand*{\dqtd}[1]{``#1"} %% 2012/11/27 +%% +%% ==== 'hyperref' ==== +%% \label{sec:hyperref} +%% This is for\slash about compatibility with the 'hyperref' package. +%% (One preliminary thing: in doubt, don't load 'niceverb' earlier +%% than 'hyperref'.) %% TODO 2010/03/14 +%% +%% We need some substitutions for PDF bookmarks with +%% 'hyperref'. We issue them at `\begin{document}' when we know +%% if 'hyperref' is at work.\footnote{An alternative approach would be +%% using +%% \ctanpkgref{afterpackage} +%% by Alex Rozhenko.} +\AtBeginDocument{% + \@ifpackageloaded{hyperref}{% + \newcommand*{\PDFcstring}{% %% moved here 2010/03/09 + \134\expandafter\@gobble\string}% %% ASCII octal encoding + \pdfstringdefDisableCommands{% + \let\nvAllowRQSS\empty %% not \relax 2010/03/12 + \let\NiceVerbGeneral\empty %% 2014/03/27 + \let\nvAllRQSS\empty %% 2014/03/27 + \MakeActiveLetHere\<<% %% 2014/03/28 + %% 2010/03/12 + \MakeActiveLetHere\`\lq \MakeActiveLetHere\'\rq + \MakeActiveLetHere\&\PDFcstring + \def\cs{\134}% %% 2010/03/17, 2011/06/27 +%% The typesetting version of `\BuildCsSyntax' (\secref{esc}): 2014/07/16 +%% %% showfile.tex 2014/07/12 + \withcsname\def BuildCsSyntax \endcsname{\cs}% +%% ... disables `\niceverbNoVerbList'; better switch off +%% auto mode with section headings TODO %% 2014/07/17 +%% (modify `\@startsection') + \let\decide_more_cs\bookmark_more_cs + }% +%% Moreover, in order to avoid spurious %% 2010/03/14 +%% \texttt{Label(s) may have changed} with 'hyperref', +%% a single right quote must be \emph{read} as active +%% by a `\newlabel' if and only if it has been active when +%% `\@currentlabelname' was formed.\footnote{This uses +%% \cs{@onelevelsanitize}, therefore &\protect doesn't +%% change the behaviour of ``active" characters.} +%% as `\active'. We use `\protected@write' as this cares for +%% `\nofiles'. `\@auxout' may be `\@partaux' for `\include'. + \newcommand*{\niceverb_aux_cat}[2]{% %% 2010/03/14 + \protected@write\@auxout{}{\string#1\string#2}}% +%% v0.5 restricts ``activating" to `\MakeActiveLet': +% \renewcommand*{\MakeActive}[1]{% +% \MakeActiveHere#1% +% \niceverb_aux_cat\MakeActiveHere#1}% + \renewcommand*{\MakeActiveLet}[2]{% + \MakeActiveLetHere#1#2% +% \niceverb_aux_cat\MakeActiveHere#1}% + \protected@write\@auxout{}{% + \string\MakeActiveLetHere\string#1\string#2}}% + \renewcommand*{\MakeNormal}[1]{% + \MakeNormalHere#1% + \niceverb_aux_cat\MakeNormalHere#1}% + }{}% +} +%% % todo doesn't 'babel' have the same problem? 2010/03/12 +%% ==== 'hyper-xr' ==== %% 2010/03/21 +%% With the 'hyper-xr' package creating links into external documents, +%% preceding `\externaldocument{<file>}' with +%% `\MakeActiveLet\&\CmdSyntaxVerb' may be needed. +%% I do not want to redefine something here right now as %% typo 2010/11/09 +%% I have too little experience with this situation. +%% +%% ==== Listings and Moving ==== %% 2014/03/26f. +%% \label{sec:listmv} +%% Working on v0.6, in testing I discovered a problem with +%% the \emph{listing environments}. The present documentation +%% uses code listings with 'makedoc', which build on the +%% 'moreverb' package and eventually call \LaTeX's +%% `\@noligs' macro.\footnote{\ctanpkgref{moreverb} +%% is used, and its listing environments use \cs{@verbatim} +%% from the \ctanpkgref{verbatim} package, then +%% \cs{verbatim@font} calls \cs{@noligs}~...} +%% The problem also appears with the `{verbatim}' environment +%% from the \LaTeX\ kernel ('latex.ltx') as well as from the +%% \ctanpkgref{verbatim} package---with anything that calls +%% \LaTeX's `\@noligs'. The latter assigns special meangings +%% to the active characters listed in the `\verbatim@nolig@list', +%% three of them need a different meaning with 'niceverb'. +%% When a page break happens after such an environment has been +%% entered (this may well be when the environment falls to the +%% beginning of the next page), these settings are used in +%% \LaTeX's `\@outputpage' for running the `\write's of the page +%% as well as for page headers. And this happens quite often +%% in a package documentation! +%% +%% The problem was reported by Walter Schmidt with respect to +%% math primes as `latex/3104' in 1999. I cannot reproduce %% rm. to 2015/11/09 +%% it, and I see two reasons in recent `latex.ltx' code +%% why it cannot happen anymore. However, one remedy in `latex.ltx' +%% is activating `\active@math@prime' in `\@resetactivechars' +%% of `\@outputpage'. +%% But this is bad for 'niceverb''s single right quote. +%% We override the `\active@math@prime' functionality and +%% verbatim `\@noligs' by appending +%% some protection of the characters collected +%% in `\verbatim@nolig@list' +%% % local restorement |\useNiceVerbHere| of our syntax. +%% to `\@resetactivechars'. +%% This solves the problem for `\write's at `\shipout'. +%% |\do_protect_noligs| is used for this purpose; +%% actually it is applied in |\useNiceVerb| +%% (\secref{allonoff}):{\sloppy\par} +\newcommand*{\do_protect_noligs}[1]{% %% 2014/03/28 + \MakeActiveLetHere#1\relax} %% `Here' missing 2015/11/09 +%% |\nvResetPages| can be used to restore \LaTeX's +%% `\@resetactivechars'. I don't add it to `\noNiceVerb' +%% because it could corrupt `\write's, so should be used with care. +%% % Actually I think that our new version of `\@resetactivechars' +%% % is better than \LaTeX's, I think I can recommend to use it +%% % always and even to modify `latex.ltx' accordingly. +%% % TODO!? math headings? without 'niceverb' restore right +%% % single quote for math prime after `\shipout'. +\AtBeginDocument{% + \newlet\latex_reset_actives\@resetactivechars} +\newcommand*{\nvResetPages}{% + \let\@resetactivechars\latex_reset_actives} +%% |\NiceVerbMove{<text>}| with v0.6 is for ``moving" arguments so that +%% 'niceverb' syntax operates \emph{locally} at the destination, +%% I think of table of contents and page headers. +%% It is automatically used by 'niceverb''s variant of \LaTeX's +%% sectioning commands (\secref{rqsf}); while with `\markboth', `\markright', +%% `\addcontentsline' etc. you must it include yourself (currently, TODO?). +%% This is meant as a remedy against \LaTeX's and \ctanpkgref{verbatim}'s +%% `\@noligs' with respect to page headers. However, +%% another purpose is that you could switch off the 'niceverb' +%% syntax at the beginning of your document (by `\noNiceVerb'), +%% though certain entries to the table of contents can use +%% 'niceverb' syntax without affecting other entries +%% (where some active characters may have different meanings, +%% perhaps from a different package). +\newcommand*{\NiceVerbMove}[1]{% +%% What goes to `.aux' files must not have underscores: + {\NiceVerbGeneral\niceverb_rqsf_kind#1}} +\NewSelfProtectedCommand{\NiceVerbGeneral}{% +%% %... TODO only 2 applications of `\NewSelfProtectedCommand'!? +%% % +%% % Here is |\useNiceVerbHere|: +% \newcommand*{\useNiceVerbHere}{% %% 2014/03/28 + \let\MakeActiveLet\MakeActiveLetHere \useNiceVerbI} +% \newcommand*{\NiceVerbGeneral}{% +% \nvSelfProtect\NiceVerbGeneral\useNiceVerbHere} +%% +%% ==== Turning off and on altogether ==== +%% \label{sec:allonoff} +%% These commands are new with v0.3. +%% +%% |\noNiceVerb| \emph{disables} all 'niceverb' features. +\newcommand*{\noNiceVerb} {\MakeNormal\`% + \MakeNormal\&% + \MakeNormal\<% + \MakeNormal\#% + \nvRightQuoteNormal + \MakeNormal\|% + \let\@sect\niceverb_before_sect} %% 2014/03/27 +%% |\useNiceVerb| \emph{activates} all the 'niceverb' features +%% (apart from ``auto mode"). With v0.6, it is divided +%% into two parts for `\NiceVerbMove' in \secref{listmv}: +\newcommand*{\useNiceVerbI}{\MakeActiveLet\`\LQverb +%% TODO to be changed with 'wiki.sty' v0.2 + \MakeActiveLet\&\CmdSyntaxVerb + \MakeActiveLet\<\MetaVar + \MakeActiveLet\#\HashVerb + \nvRightQuoteSansSerif + \MakeActiveLet\|\nvCmdBox} +\newcommand*{\useNiceVerb} {\useNiceVerbI %% 2014/03/27 + \let\@sect\niceverb_sect + \g@addto@macro\@resetactivechars{% +% \useNiceVerbHere %% 2014/03/28 + \let\do\do_protect_noligs \verbatim@nolig@list %% 2014/03/28 +}} +%% +%% +%% === Minor Final Things === +%% ==== Activating the 'niceverb' Syntax ==== +%% 'niceverb' features are activated at `\begin{document}' +%% so (some) other packages can be loaded \emph{after} 'niceverb'. +%% For v0.3, we do this after possible settings for +%% compatibility with 'hyperref'. +\AtBeginDocument{\useNiceVerb} +%% +%% ==== Leave Package Mode ==== +\PopLetterCat\_ %% 2012/08/27 +\endinput +%% +%%==== VERSION HISTORY ==== + +v0.1 2009/02/21 very first, sent to CTAN +v0.2 2009/04/04 ...NoVerbList: \subsubsection, \AddToMacro, + 2009/04/05 \SimpleVerb makes more other than iii + 2009/04/06 just uses \dospecials + 2009/04/08 debugging code for rq/sf, +\relax + 2009/04/09 +\verb@eol@error, prepared for new doc method, + removed spurious \makeat..., -\relax (ligature), + 2009/04/10 ('-trick + 2009/04/11 \@ after \SimpleVerb + 2009/04/14 noted TODO below + 2009/04/15 change v0.1 to 2009/02/21 +v0.30 2010/02/27 short, more explained, \AssignCatCodeTo, + use \MakeActive for re-activating, \MakeNormal + 2010/02/28 fixed @ and _ with & by moving \begin_min_verb; + replaced \lq by `; Capitals in Titles + 2010/03/05 \SimpleVerb -> \NVerb; + use \MakeActive + \MakeNormal; \rq -> '; + renamed some sections; \lq_verb -> \LQverb, + \niceverb_meta -> \MetaVar, + \param_verb -> \HashVerb + 2010/03/06 removed \MakeAlign; removed @ and _ todo below; + \NVerb makes ` and ' other; + \nvAllowRQSF allows ' in column titles, + 2010/03/08 \LQverb and & work in column titles, + \RQverb works with \noindent; + bookmark substitutions + 2010/03/09 extended notes on 'hyperref' (in)compatibility; + \MakeLetter\@ in \CmdSyntaxVerb only; + |...| implemented as \prepareCmdBox etc.! + 2010/03/10 \colorbox example, \thinspace; ltxguide!; + removed todo; ..._exec -> \DoRQsansserif; + minor doc changes in ``Nasty" + 2010/03/11 doc changes in ``Escape Character ..." and + ``Ampersand" + 2010/03/12 \niceverb_aux_cat, \MakeActiveHere etc., + \IfTypesetting, \noNiceVerb, \useNiceVerb, + corr. bracing mistake in \MakeNormal! + 2010/03/14 0.31 -> 0.3; \HardNVerb, \GenCmdBox, + \prepareCmdBox -> \nvCmdBox + 2010/03/15 \endcell; \cmdboxitem; remark on \sfcode`/ + 2010/03/16 corr. -> \endline; + advice on \cs{par}, \cs{if...}, \cs{fi}; + redefined \ignorespaces for RQ feature + 2010/03/17 corr. `\fututelet', corr. \cs PDF substitution + 2010/03/18 |\niceverbNoVerbList|, |\AddToMacro| etc.; + corr. \AddToMacro; + \lastskip-fix of \niceverb_ignore, + another fix of \niceverb_noindent + 2010/03/19 another fix of \niceverb_ignore: \spacefactor + 2010/03/20 ... again: \niceverb_spacefactor + +NOT DISTRIBUTED, just stored saved as separate version + +v0.31 2010/03/20 right quote feauture: letters get \sfcode=1001 + `column title' -> `page headers', \ctanpkgref + +NOT DISTRIBUTED, just stored as separate version + +v0.32 2010/03/21 taking best things from v0.30 and v0.31 + 2010/03/23 removed \relax from \IfTypesetting +SENT TO CTAN + +v0.4 2010/03/27 restoring `_' with "auto mode" safer + 2010/03/28 \AddToNoVerbList + 2010/03/29 note above, renamed v0.4 +SENT TO CTAN + +v0.41 2010/04/03 v0.33 -> v0.4 + 2010/04/05 corrected \AutoCmdInput list +SENT TO CTAN as part of NICETEXT release r0.41 + +v0.41a 2010/11/09 typo corrected +v0.42 2010/12/30 corr. `\ ' emulation in auto mode + 2010/12/31 \MetaVar in ...maybe_meta... + 2011/01/19 `...' fix + 2011/01/24 \ctanpkgref moves to texlinks.sty + 2011/01/26 update (C) +with nicetext RELEASE r0.42 +v0.43 2011/05/09 \gt, \lt + 2011/05/27 \cs uses \@backslashchar + 2011/06/20 \MakeActiveLetHere in \nice_maybe_meta_verb !!! + 2011/06/27 2011/05/27 undone + 2011/08/20 `r0.42', `v0.43' +with nicetext RELEASE r0.43 +v0.44 2011/09/09 \AddQuotes, \DontAddQuotes +with nicetext RELEASE r0.44 +v0.45 2011/11/05 mod. \niceverb_collect_egroup/\VerticalCmdBox, + tried \output problem without avail + 2011/12/05 clarified "r0.44" +with nicetext RELEASE r0.5 + +v0.5 2012/08/27 using 'catcodes', \providecommand\CatCode, + rm. \AssignCatCodeTo, \private_letters + 2012/08/28 fixed \private_letters; + rewording for filling lines + 2012/09/27 corrections about \MakeActive... +with nicetext RELEASE r0.6 + +v0.6 2012/11/27 \[d]qtd only \provide'd +v0.61 2014/03/18 doc.: rm. TODO on private letters hook, + folding history tighter, + RM CODE COMMENTED OUT IN 2011; + \VerticalCmdBox gets \pagebreak[2] + 2014/03/19 doc.: strange replaced, restructured, + Command-Highlighting Boxes -> Boxes + Highlighting ...; + opt. arg. for \NVerb etc. replaces + \niceverb_egroup, \cs/\cstx enhanced, + reimpl.s with \SetNiceVerbSaveBox, + \nice_maybe_meta_verb -> \NiceMaybeMetaVerb + 2014/03/20 reworking robustness -- doc., ...; doc. on + `Shared ...', \qtdnverb + 2014/03/21 "debugging": \noexpand vs. \protect + 2014/03/22 ... continued; mod. \MakeNormal + 2014/03/23 ..., hiding ... + 2014/03/24 TODO on left quotes, doc. test there, + rm. babel-TODO + 2014/03/25 doc. about left quotes shorter, rm. earlier page + breaks, doc. problems with right quotes; \newlet; + dealing with \active@math@prime + 2014/03/26 corr. test for right single quote, more about + \active@math@prime, corr. \CmdSyntaxVerb + 2014/03/27 different treatment of \active@math@prime ... + main work for sec:listmv and independent + switching for rqsf, \NewSelfProtectedCommand + (3 applications); doc. corr., TODO; + \typeout test + 2014/03/28 test section; [TODO?]; \nvShowProtectedEdef, + \MetaVar: protection and hyperref version; + remark \NVerb; [\NiceVerbHere]; \protect test + with RQ removed; \do_protect_noligs fixed + and used + 2014/07/16 \BuildCsSyntax with hyperref + 2014/07/17 remarks on \BuildCsSyntax and removing useless + braces there (hours of trying better) + 2015/02/23 doc.: \PDFstring -> \pdfstring + 2015/04/07 doc.: page headings -> page headers + 2015/11/09 bugfixes \nvRightQuoteNormal and + \do_protect_noligs; doc. typo fix +with nicetext RELEASE r0.66 +v0.62 2015/11/20f. \qtdnverb was disabled! + doc.: fn. on \qtdnverb obsolete + diff --git a/macros/latex/contrib/nicetext/use/wiki.sty b/macros/latex/contrib/nicetext/use/wiki.sty new file mode 100644 index 0000000000..6fe7b4e4b4 --- /dev/null +++ b/macros/latex/contrib/nicetext/use/wiki.sty @@ -0,0 +1,376 @@ +\ProvidesPackage{wiki}[2008/07/02 v0.2 LaTeX through Wiki markup] +%% <- vorige Aenderungen gg. 2008/06/25 verworfen +%% +%% == Legal == +%% (C) 2008 Uwe Lueck http://contact-ednotes.sty.de.vu +%% License: http://www.latex-project.org/lppl/ +%% -- AUTHOR-MAINTAINED, NO WARRANTY! +%% +%% == Features == +%% +%% The `wiki' package enables LaTeX users to use some of the +%% markup used in editing Wikipedia pages, cf. +%% +%% http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet +%% +%% or German: +%% +%% http://de.wikipedia.org/wiki/Hilfe:Bearbeitungshilfe +%% http://de.wikipedia.org/wiki/Hilfe:Textgestaltung +%% +%% Advantages of such a kind of markup are: +%% +%% 1. easier and faster to type than LaTeX code; +%% +%% 2. intuitive, understandable at a glance; +%% +%% 3. in reading the source code of the document, +%% the markup doesn't much distract from the ''text'' +%% to be printed. +%% +%% There is a binary `easylatex' available on CTAN which is more +%% powerful than the `wiki' package; the idea here is that a ''macro +%% package'' doing something similar is easier to use and to customize. +%% +%% +%% === What the Package Supports === +%% +%% 1. ''Italics'' are marked up by surrounding pairs of apostrophes, +%% '''boldface''' needs one apostrophe more on each side. +%% Boldface and italics may be nested or overlap. +%% (This endangers quoting, but I have dealt with it.) +%% +%% 2. Surrounding ``equals'' symbols (`=') mark up section headings +%% etc.: `== Section ==', `=== Subsection ===', down to +%% `===== Subparagraph ====='. +%% +%% 3. If a line starts with `*', it becomes an item in an +%% `itemize' environment. Likewise, `#' creates an `enumerate' +%% environment, and `;' makes an item in a `discription' +%% environment (differs from Wiki! -- since I don't understand +%% what the Wiki version is good for). `:' makes a `quote' -- +%% while on Wikipedia instead is used for comments on talk +%% pages. But it is also used for indented math displays, +%% so it may be combined with $...$ here. +%% An indented line is typeset ''verbatim''. Each of these +%% environments is ended by a code line without leading blank +%% spaces. +%% +%% +%% === Limitations === +%% +%% 1. The markup ``language'' provided here replaces a few most +%% common LaTeX commands only in their most simple versions. +%% (Yet I think that already this makes the code more readable; +%% the more special cases are very rare.) E.g., it's not +%% possible to suppress the italic correction as with +%% `\textit{...\nocorr}'. However, in ``normal'' cases it +%% should be possible to use the more powerful LaTeX markup +%% mixed with ``Wiki'' markup. +%% +%% 2. The parsing algorithms employed here differ in outcome to +%% those of Wikipedia in difficult cases. +%% +%% 3. Tables, nesting lists, links, Wiki templates and tags +%% are not supported -- and I don't expect that I can afford +%% improving this soon! +%% +%% 4. I still have encountered problems that I didn't understand ... +%% +%% == Package Options and User Commands == +%% +%% \usepackage[<options>]{wiki}, of course. There are <options> +%% `noEnvironments', `noFonts', `noHeadings' giving up +%% functionality for lists etc., for italics and boldface, +%% for section headings etc., respectively. +%% +%% There are commands \wikimarkup, \wikiEnvironments, +%% \wikiFonts, \wikiHeadings to turn respective functionality on +%% (unless disabled by package option). \nowikimarkup, +%% \nowikiEnvironments, \nowikiFonts, \nowikiHeadings turn them +%% off. +%% +%% '''Vital:''' The package does ''not'' execute \wikimarkup +%% because this would have strange effects, e.g., packages +%% loaded later may break. The user must put activating +%% commands into the `document' environment, maybe just preceding +%% the first heading. +%% +%% Dangers to be avoided by \nowiki... are: +%% * \wikiHeadings (which also is executed by \wikimarkup) +%% disables TeX assignments using `='. +%% * \wikiEnvironments (executed by \wikimarkup) executes macros +%% at every end of a code line (containing no comment marke), +%% and it tries to typeset a following line verbatim if it is +%% indented. +%% +%% +%% == Implementation and Further Remarks == + +%% === Commands for Category Codes === +% \RequirePackage{fdcodes} + %% <- TODO -- or do away ... -> +\providecommand*\AssignCatCode[2]{\catcode`#1=#2\relax} +\providecommand*\MakeActive[1]{\catcode`#1=\active} +% \providecommand*\MakeLetter[1]{\catcode`#1=11\relax} + %% <- Declaring characters usable in command strings + %% Todo: print arrow indicators like ``->'' as real arrows +\providecommand*\MakeOther [1]{\catcode`#1=12\relax} + +\AssignCatCode{\_}{11} +% \MakeLetter\_ %% own macros somewhat LaTeX3-style +%% Todo \newcommand <-> \def !? + +%% === Package Options === +\DeclareOption{noFonts} {\let\wikiFonts \empty + \let\nowikiFonts \relax} +\DeclareOption{noHeadings} {\let\wikiHeadings \empty + \let\nowikiHeadings \relax} +\DeclareOption{noEnvironments}{\let\wikiEnvironments \empty + \let\nowikiEnvironments\relax} +\DeclareOption{noVerbatim}{% + \def\W_active_return{ \futurelet\@let@token\W_on_firsttoken}} + %% \[no]wikiVerbatim must wait, too complex 2008/07/01 +\ProcessOptions + +%% === Auxiliaries for both Fonts and Headings === + + \@tempswafalse + \ifx\wikiFonts \empty \else \@tempswatrue \fi + \ifx\wikiHeadings\empty \else \@tempswatrue \fi + \if@tempswa +\def\W_start_samecnt{\futurelet\@let@token\W_process_samecnt} +\def\W_init_samecnt#1#2#3{% + \let\W_samesymb =#1%% repeated symbol + \def\W_repllist {#2}% replacing strings + \def\W_incase_all{#3}% final replacement + \def\W_next##1{\W_start_samecnt}} +\def\W_process_samecnt{% + \expandafter \W_splitlist \W_repllist \@nil + \W_next} +\def\W_splitlist#1#2\@nil{% + \def\W_repllist{#2}% + \ifx\@let@token\W_samesymb + \ifx\W_repllist\empty \def\W_next##1{\W_incase_all}\fi + \else + \def\W_next{#1}% + \fi} + \fi + +%% === Italics and Boldface === + +%% ==== Code ==== + \ifx\wikiFonts\empty \else +\def\W_toggle#1#2#3{\def#1{\W_toggle#1{#3}{#2}}#2} +%% Cf. LaTeX's `\DeclareTextFontCommand': +\def\W_bf_toggle{% + \W_toggle\W_bf_toggle{\bfseries\W_maybe@ic}{\mdseries\W_maybe@ic}} +\def\W_maybe@ic{\futurelet\@let@token\W_maybe_maybe@ic} +\def\W_maybe_maybe@ic{% + \ifx\@let@token\W_rq_robust \else \expandafter \maybe@ic \fi} +\def\W_it_toggle{% + \W_toggle\W_it_toggle{\itshape\maybe@ic}{\upshape\maybe@ic}} +%% <- Doesn't support \nocorr. + +\def\W_rq_robust{%% will become meaning of single right quote. + \ifx\protect\@typeset@protect + \ifmmode \rq \else + \W_init_samecnt{\W_rq_robust}% + {\rq\W_it_toggle}% + {\W_bf_toggle}% + \expandafter\expandafter\expandafter \W_start_samecnt + \fi + \else \rq \fi} +%% Remark: +%% LaTeX's \rq expands to ``other'' apostrophe: +\CheckCommand*\rq{'} %% Must be before `\catcode`\' +%% \wikiFonts -- restoring `...' and ``...'' -- + \nowikiFonts: +%% requiring single left quote \active as well: +\CheckCommand*{\lq}{`} +\MakeActive\`\MakeActive\' +\def\wikiFonts{% + \MakeActive\`\MakeActive\'% + \def`##1'{\lq ##1\rq}% + \let'\W_rq_robust} +\def\nowikiFonts{\MakeOther`\MakeOther\'} +\MakeOther\` \MakeOther\' + \fi + +%% ==== Remarks ==== +%% Wiki: a''b'''cd typesets `b' in italic with an apostrophe, +%% a''b'''c'''d typsets all after `a' in italic with bold `b'. +%% One might use make a difference depending on \lastskip. +%% Wikimedia seems to read more ahead, maybe entire paragraphs. +%% %% <- Todo: try here!? (Test!) +%% +%% Todo: Variants using \textit and \textbf (option, switching +%% command) +%% +%% german.sty's "` and "' are not affected. +%% +%% Merit: ``...'' resembles ''...''; indeed Wikipedia Guidelines +%% demand to think which of both is appropriate in a +%% certain situation. + +%% A test about \ifx with active characters: +%\catcode`\`=\active \let`\rq \let'\rq +%\ifx`'\typeout{OHHH}\else \typeout{OCH}\fi %% OHHH +%% <- how typeset code commented out!? (^!? diff. comment char.!?) +%% indent %! TODO or no space after %!! TODO!! +%% xEDIT: dann Alt C/D fuer Kommentar/Dok./auskomm. (!?) !! + +%% === Section Headings === + + \ifx\wikiHeadings\empty \else +\providecommand*{\normalequals}{=} +\MakeActive\= +\def\wikiHeadings{\MakeActive\=\let=\W_eq_robust} +\def\nowikiHeadings{\MakeOther\=} +\def\W_eq_robust{% + \ifx\protect\@typeset@protect + %% in case without math mode in heading + \ifmmode \normalequals \else + \W_init_samecnt{\W_eq_robust}% + {\normalequals\W_sec\W_subsec\W_subsubsec + \W_para\W_subpara}% + {\W_bf_toggle}% + \expandafter\expandafter\expandafter \W_start_samecnt + \fi + \else \normalequals \fi} + +\def\W_sec #1=={\section{#1}} +\def\W_subsec #1==={\subsection{#1}} +\def\W_subsubsec #1===={\subsubsection{#1}} +\def\W_para #1====={\paragraph{#1}} +\def\W_subpara #1======{\subparagraph{#1}} + +\MakeOther\= + \fi + +%% Todo: think of reimplementation by the start-line +%% mechanism which is going to be used for lists. + +%% === Environments === +%% + \ifx\wikiEnvironments\empty \else + +%% ==== Prepare Dealing with Indents ==== + +\MakeActive{\^^M}% +\def\wikiEnvironments{\MakeActive{\^^M}\let^^M\W_active_return}% +\def\nowikiEnvironments{\AssignCatCode{\^^M}{5}}% +\nowikiEnvironments%% TeX <return> restored + +\MakeActive{\ }% +\@ifundefined{W_active_return}{% +\expandafter\def\expandafter\W_active_return\expandafter{% +\space\catcode`\ \active\let \W_indent% +%% <- \W_indent will start verbatim +\futurelet\@let@token\W_on_firsttoken}% +}{}%% end of \@ifundefined which is true without noVerbatim +%% Much doubling for saving time (!??): +\expandafter\def\expandafter\W_list_activereturn\expandafter{% +\space\catcode`\ \active\let \W_restore_space% +%% <- \W_indent will start verbatim +\futurelet\@let@token\W_maybe_newitem}% +% \def\W_restore_space{\catcode`\ 10\relax}% + %% <- was vital for a math display in a list -> +\def\W_restore_space{\catcode`\ 10\ignorespaces}% +\W_restore_space%% TeX blank space restored + +%% ==== Start and End List-Like Environments ==== + +%% \W_on_firsttoken may be edited (preamble or .cfg): +\def\W_on_firsttoken{% + % \show\@let@token + \W_restore_space + \let\W_next\relax %% must be before \W_skip... works + \ifx\@let@token\W_active_return \expandafter \W_par \fi + %% <- found by guessing/with \show\@let@token + \let\W_item\item + \W_on_startenv{*}{itemize}% + \W_on_startenv{\W_hash}{enumerate}% + \W_on_startenv{;}{description}% + \let\W_item\relax %% must precede `quote' + \W_on_startenv{:}{quote}%% instead of quotation 2008/07/01 + \W_next} +\let\W_hash=# +\def\W_par#1\W_next{\par} +\def\W_skiprest_item#1\W_next#2{\W_item} + +\MakeActive{\^^M}% +\def\W_on_startenv#1#2{% + \ifx#1\@let@token% + \begin{#2}% + \let\W_itemsymbol#1% + \let^^M\W_list_activereturn% + \expandafter \W_skiprest_item% + \fi}% +\nowikiEnvironments% + +\def\W_maybe_newitem{% + \W_restore_space + \ifx\@let@token\W_itemsymbol + \expandafter \W_gobbling_item + \else + \ifx\@let@token\W_restore_space + \else + \ifx\@let@token\W_list_activereturn + \par + \else + \edef\W_next{\noexpand\end{\@currenvir}}% + \W_next + \fi + \fi + \fi} +\def\W_gobbling_item#1{\item} + +%% ==== Verbatim Environment ==== + +\def\W_indent{\begin{W_verbatim}} +\def\W_verbatim{% + \let\obeylines\W_obeylines + \@verbatim \frenchspacing\@vobeyspaces} +\let\endW_verbatim\endverbatim + +\MakeActive{\^^M} +\def\W_obeylines{% + \catcode`\^^M\active% + \def^^M{\par\futurelet\@let@token\W_check_verbcont}}% +\nowikiEnvironments% + +\def\W_check_verbcont{% + \ifx\@let@token\@xobeysp + \expandafter \@gobble %% gobble one space + \else + \def\W_next{\end{W_verbatim}}% + \expandafter \W_next + \fi} + +%% TODO: enable user to switch between environment ``encodings'' +%% or to disable some of them (edit \W_on_firsttoken) + + \fi %% from \ifx\wikiEnvironments \else + + +%% === Turning Wiki Markup On and Off === + +\def\wikimarkup{\wikiFonts\wikiHeadings\wikiEnvironments} +\def\nowikimarkup{% + \MakeOther\`\MakeOther\'\MakeOther\=\AssignCatCode{\^^M}{5}} + +% \wikimarkup %% strange effects here, to be put into document + +\AssignCatCode\_{8} +\endinput + +%% todo: tables, links, templates, (pseudo-)html-tags ... +%% TODO: credits: easylatex etc. +%% TODO: useful for: ... intuitive markup, ``poor man's WYSIWYG'', +%% ASCII-WYSIWYG. +%% Todo: improve Wiki markup: ``tab'' indents instead of `:' +%% as in testing for end of list: after finding one +%% leading space, test for another. + + + |