diff options
Diffstat (limited to 'tcllib/modules/doctools')
396 files changed, 24426 insertions, 0 deletions
diff --git a/tcllib/modules/doctools/ChangeLog b/tcllib/modules/doctools/ChangeLog new file mode 100644 index 0000000..f6df0a4 --- /dev/null +++ b/tcllib/modules/doctools/ChangeLog @@ -0,0 +1,1908 @@ +2013-11-07 Andreas Kupries <andreask@activestate.com> + + * mpformats/man.macros: [Ticket 369f67aeee] Updated to newest from + Tcl/Tk. + +2013-11-06 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff: [Ticket efe207eff1]: Applied + * mpformats/idx.nroff: patched by Stuart Casoff to + * mpformats/toc.nroff: unbreak manpage rendering on + * modules/doctools/tests/nroff/00: various BSD variants. + * modules/doctools/tests/nroff/01: Must include our + * modules/doctools/tests/nroff/02: macros after emitting + * modules/doctools/tests/nroff/03: .TH to avoid clashes. + * modules/doctools/tests/nroff/04: Updated test results. + * modules/doctools/tests/nroff/05: + * modules/doctools/tests/nroff/06: + * modules/doctools/tests/nroff/07: + * modules/doctools/tests/nroff/08: + +2013-06-05 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: Added dt_ibase command to the set + * mpformats/_common.tcl: available in formatters. + * pkgIndex.tcl: Extended file command emulation. + Used in the provenance code for shorter reference + to the proper input file. Bumped to 1.4.17. + +2013-02-26 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_nroff.tcl: Modified the formatting of dots ("."). + * pkgIndex.tcl: Always quote them with \& (zero-width escape). + * doctools.tcl: Updated test results. Version bumped to 1.4.16. + * doctools.man: + * modules/doctools/tests/nroff/00: + * modules/doctools/tests/nroff/01: + * modules/doctools/tests/nroff/02: + * modules/doctools/tests/nroff/03: + * modules/doctools/tests/nroff/04: + * modules/doctools/tests/nroff/05: + * modules/doctools/tests/nroff/06: + * modules/doctools/tests/nroff/07: + * modules/doctools/tests/nroff/08: + + +2013-02-25 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_nroff.tcl (nroff_postprocess): Followup fixes to + * mpformats/fmt.nroff: bugs found in branch "bug-3601370-td", + * pkgIndex.tcl: Missing markup of several nroff directives as + * doctools.tcl: such. Version bumped to 1.4.15. + * doctools.man: + +2013-02-04 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * changelog.tcl: flatten method added. Extension of for 'sak + * changelog.man: review'. Simpler structured output. Bumped + version to 1.1. + +2013-02-01 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.15 ======================== + * + +2013-01-29 Andreas Kupries <andreask@activestate.com> + + * doctools.man: Bumped version to 1.4.14 for the + * doctools.tcl: last change, see below. + * pkgIndex.tcl: + +2013-01-21 Andreas Kupries <andreask@activestate.com> + + * checker.tcl: Added check to manpage_begin, reject spaces in title. + * mpformats/c.msg: Message catalogs extended with new warning + * mpformats/de.msg: 'mptitle' for spaces in the manpage title. + * mpformats/en.msg: The french catalog contains the english + * mpformats/fr.msg: text, and needs a translation. + +2012-02-27 Andreas Kupries <aku@hephaistos> + + * tests/text/04: Update the expected the result to match the new + actual result. See the 2011-12-13 last-second bugfix in + textutil::adjust::undent for the cause. + +2011-12-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.14 ======================== + * + +2011-11-07 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * tests/nroff/04: Updated the test outputs to match the changes + * tests/nroff/07: introduced by the last two commits, below. + * tests/nroff/08: + +2011-02-23 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff: Moved the handling of the list nesting + * mpformats/_nroff.tcl: level a bit around to be consistent at + * checker.tcl: both begin and end. Fixed the long-standing + indentation bug where the rendered text got unindented after a + nested list or example. We simply had to start indented + paragraphs, via .IP after them, and for each paragraph in a list + element. This needed the consistent nesting level to correctly + know when to emit the commands. And while this may generate + empty paragraphs, these can be removed easily in the + post-processing. + * doctools.tcl: Bumped version to 1.4.13. + * doctools.man: + * pkgIndex.tcl: + +2011-02-23 Andreas Kupries <andreask@activestate.com> + + * mpformats/_nroff.tcl (nr_ce): [Bug 3167244]: Added \n after .CE + to prevent misformatting when examples are used in a sentence + without placement on a separate line of input. + * doctools.tcl: Bumped version to 1.4.12. + * doctools.man: + * pkgIndex.tcl: + +2011-01-24 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.13 ======================== + * + +2011-01-12 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Updated for the changes made per the entry below. + +2010-11-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.man: Bumped to version 1.4.11, fixing issues with + * doctools.tcl: resolution of relative include paths. -file had + * pkgIndex.tcl: overloaded semantics, used for both source paths + (include resolution) and destination paths (HTML relative + links). Added new option -ibase as primary for include + resolution, using -file only as fallback anymore. + +2010-09-15 Andreas Kupries <andreask@activestate.com> + + * tests/nroff/04: [Bug 3058654] and last entry. Updated + * tests/nroff/08: the affected testcases. + +2010-09-07 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff: [Bug 3058654]: Changed formatting of + * mpformats/_nroff.tcl: examples to .CS/.CE. + +2010-09-07 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff: [Bug 3058654]: Added code compacting + whitespace in various strings used for nroff comments and NAME + section. + +2010-07-06 Andreas Kupries <andreask@activestate.com> + + * checker.tcl: [RFE 2915921] Accepted the RFE, adding + * mpformats/fmt.wiki: commands to portably write em- and + * mpformats/fmt.text: en-dashes. Bumped version to 1.4.10. + * mpformats/fmt.latex: + * mpformats/fmt.tmml: + * mpformats/fmt.html: + * mpformats/fmt.nroff: + * mpformats/fmt.null: + * doctools.man: + * pkgIndex.tcl: + * doctools.tcl: + +2010-06-17 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.html: Tweaked formatting of images when no + * mpformats/fmt.latex: data was found. Especially for HTML + * mpformats/fmt.text: accept http and ftp uris and format + * mpformats/fmt.wiki: them as links, allowing the embedding + * mpformats/fmt.nroff: of images without requiring a local + * doctools.man: file. Bumped version to 1.4.9 + * pkgIndex.tcl: + * doctools.tcl: + +2010-06-10 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Extended the plugin API to the image map to + * mpformats/fmt.nroff: allow querying the image data instead of + * mpformats/fmt.wiki: its paths. Fixed the nroff, wiki, and text + * mpformats/fmt.text: plugins to use this new command, as they + * doctools_plugin_apiref.man: are in a restricted environment + * doctools.man: which does not allow them to 'open' files on their + * pkgIndex.tcl: own. Documented the command now. nroff further + extended to accept .txt images as well as .pic, and do a bit of + formatting of their own to make them fit (.nf/.fi). Version + bumped to 1.4.8. + + * ../../apps/dtplite: Fixes for problems with the handling of + relative paths. Version bumped to 1.0.2. + +2010-06-08 Andreas Kupries <andreask@activestate.com> + + * ../../apps/dtplite: Fix the min version requirements. + + * checker.tcl: Added 'image' command to doctools, and the + * doctools.man: various backends. Bumped to version 1.4.7. + * doctools_lang_cmdref.man: Images are specified through + * doctools.tcl: symbolic name. Tools like dtp(lite) specify + * pkgIndex.tcl: possible mappings, and the backends select + * mpformats/fmt.html: a proper variant (png, jpeg, text, ...) + * mpformats/fmt.latex: or fallback to a 'here should be this + * mpformats/fmt.nroff: image' markup, if no proper variant + * mpformats/fmt.null: for them was found. + * mpformats/fmt.wiki: + * mpformats/fmt.text: Future/Todo - Recognize uris as symbolic + * mpformats/_html.tcl: name and treat as external reference. + * ../../apps/dtplite: + + * docidx.man: Added missing dt_package and restricted 'file' + * docidx.tcl: support to doctool::toc and doctools::idx. Versions + * doctoc.man: bumped to 1.1.3 and 1.0.4. + * doctoc.tcl: + * pkgIndex.tcl: + + * mpformats/toc.text: Fixed command names using various textutil + * mpformats/idx.text: functionality. + +2010-02-05 Andreas Kupries <andreask@activestate.com> + + * checker.tcl: Gave the checking layer access to dt_file, + * doctools.tcl: and extended it to provide the file name + * doctools.man: as part of the location information in + * doctools.test: errors and warnings. Bumped version to + * pkgIndex.tcl: 1.4.6. + +2010-02-04 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: Extended with new plugin API command + * doctools.man: [dt_mainfile], which always returns + * doctools_plugin_apiref.man: the toplevel file currently + * pkgIndex.tcl: processed, in contrast to [dt_file] which + returns the currently processed file, which may be included. + Bumped version to 1.4.5. + + * mpformats/fmt.html: Fixed bug in inter-document link generation + caused by computing links relative to the active (include) file, + instead of the toplevel. + +2009-12-09 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: Bumped version to 1.4.4. + * doctools.man: + * pkgIndex.tcl: + + * mpformats/fmt.html: Extended to support the engine variable + * doctools.test: 'raw' (boolean flag). The default is off, causing + the engine to generate the full html, as usual. If set, the + engine will generate only the HTML normally between the <body> + and </body> tags, excluding these two tags. This allows for + easier embedding of the result in other HTML. Thanks to Jos + DeCoster for the idea. Extended the testsuite to cover raw mode + results. + + * mpformats/fmt.wiki: Thanks to Jos DeCoster for updating the Wiki + * tests/wiki/00: formatter to generate text making better use of + * tests/wiki/01: Wikit's new features, and also fixing bugs in the + * tests/wiki/02: use of the older features. Updated test results. + * tests/wiki/03: + * tests/wiki/04: + * tests/wiki/05: + * tests/wiki/06: + * tests/wiki/07: + * tests/wiki/08: + +2009-12-07 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.12 ======================== + * + +2009-07-21 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: Fixed @mdgen instructions, added forgotten + ownership reference to man.macros. See ActiveState Bug 83781, + reported by Nicolas Castagne. Bumped to version 1.4.3. + * docidx.tcl: See above, bumped to version 1.0.3. + * doctoc.tcl: See above, bumped to version 1.1.2. + +2009-03-30 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * checker.tcl (manpage): Added new markup command for document + references (manpage). For now formatted like a 'term'. + + * doctools.tcl: Fixed handling of include files. Search relative + * doctools.man: to processed file, and run the command through + 'subst' first, to resolve embedded commands (vset uses). Bumped + to version 1.4.2. + + * docidx.tcl: Fixed handling of include files. Search relative + * docidx.man: to processed file, and run the command through + 'subst' first, to resolve embedded commands (vset uses). Bumped + to version 1.0.2 + + * doctoc.tcl: Fixed handling of include files. Search relative + * doctoc.man: to processed file, and run the command through + 'subst' first, to resolve embedded commands (vset uses). Bumped + to version 1.1.1. + + * docidx_lang_syntax.man: Added notes about command arguments. + +2009-02-11 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * checker_toc.tcl: TOC language extended to allow empty tocs, empty + * docidx.test: divisions, and the mixing of items and divisions at + * doctoc.tcl: every level. Extended testsuite. Updated documentation. + * doctoc.test: Bumped version to 1.1. Fixed bug in the documentation + * doctoc_lang_cmdref.man: of markup command 'item' (arguments were + * doctoc_lang_intro.man: missing). + * doctoc_lang_syntax.man: + * doctoc.man: + * pkgIndex.tcl: + +2009-02-10 Andreas Kupries <andreask@activestate.com> + + * checker_idx.tcl (index_end): Allow empty index (no keys). + * docidx.tcl: Bumped package to vrsion 1.0.1. Updated the + * docidx.test: documentation, where not already in alignment. + * docidx_lang_intro.man: Extended testsuite. Fixed small typo + * docidx_lang_syntax.man: orthogonal to this change. + * pkgIndex.tcl: Fixes [SF Tcllib Bug 2557107]. + +2009-01-29 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * docidx.tcl: Extended the plugin APIs for all formats with a new + * docidx_plugin_apiref.man: command "dt_read" to read a file's + * doctoc.tcl: contents into a plugin. Modified the nroff plugins + * doctoc_plugin_apiref.man: to inline the man.macros file into + * doctools.tcl: their result instead of generating a + * doctools.test: '.so man.macros' command. Stuart Cassoff + * doctools_plugin_apiref.man: <stwo@users.sourceforge.net> did the + * mpformats/_nroff.tcl: work and provided the patches as part of + * mpformats/fmt.nroff: his effort on making a Tcllib OpenBSD port. + * mpformats/idx.nroff: + * mpformats/toc.nroff: + +2009-01-28 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * checker.tcl: Fixed bug in handling 'category' command. Bumped + * doctools.tcl: version to 1.4.1 + * doctools.man: + * pkgIndex.tcl: + + * changelog.man: Added 'category' information to all manpages. + * cvs.man: + * docidx.man: + * docidx_intro.man: + * docidx_lang_cmdref.man: + * docidx_lang_faq.man: + * docidx_lang_intro.man: + * docidx_lang_syntax.man: + * docidx_plugin_apiref.man: + * doctoc.man: + * doctoc_intro.man: + * doctoc_lang_cmdref.man: + * doctoc_lang_faq.man: + * doctoc_lang_intro.man: + * doctoc_lang_syntax.man: + * doctoc_plugin_apiref.man: + * doctools.man: + * doctools_intro.man: + * doctools_lang_cmdref.man: + * doctools_lang_faq.man: + * doctools_lang_intro.man: + * doctools_lang_syntax.man: + * doctools_plugin_apiref.man: + * mpexpand.man: + +2008-12-12 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.11.1 ======================== + * + +2008-12-01 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: New command in doctools language is extended API. + * doctools.man: Bumped minor version, to 1.4. + * pkgIndex.tcl: + +2008-11-26 Andreas Kupries <andreask@activestate.com> + + * api.tcl: Extended doctools language with a 'category' + * checker.tcl: command. This allows manpages to provide + * doctools.tcl: a category string, like they already + * doctools_lang_cmdref.man: provide keywords and see-also + * doctools_lang_syntax.man: references. Updated all engines + * mpformats/_common.tcl: to handle the command in some way. + * mpformats/fmt.html: Bumped package version to 1.3.6. + * mpformats/fmt.latex: Needed: Some tests to demo the + * mpformats/fmt.list: handling of 'category'. + * mpformats/fmt.nroff: + * mpformats/fmt.null: + * mpformats/fmt.text: + * mpformats/fmt.tmml: + * mpformats/fmt.wiki: + * doctools.test: + * tests/list/00: + * tests/list/01: + * tests/list/02: + * tests/list/03: + * tests/list/04: + * tests/list/05: + * tests/list/06: + * tests/list/07: + * tests/list/08: + +2008-10-16 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.11 ======================== + * + +2008-07-08 Andreas Kupries <andreask@activestate.com> + + * changelog.man: Bumped the packages to version 1. They have + * changelog.tcl: been on 0 long enough. + * cvs.man: + * cvs.tcl: + * docidx.man: + * docidx.tcl: + * doctoc.man: + * doctoc.tcl: + +2008-05-16 Andreas Kupries <andreask@activestate.com> + + * checker.tcl (sectref): The way it was documented confused me and + * doctools.tcl: the last change flipped identifying and text + * doctools.man: argument, changing the meaning of sectref. Should + * pkgIndex.tcl: have seen that quicker with how comm/comm_wire.man + had to be updated. Fixed this now, restoring the proper + order. Rewrote docs as well for better understanding. Bumped to + version 1.3.5. + + * ../comm/comm_wire.man: Fixed the sectref argument order issues. + * ../rcs/rcs.man: Fixed the sectref argument order issues. + * ../snit/snitfaq.man: Fixed the sectref argument order issues. + * ../tie/tie.man: Fixed the sectref argument order issues. + +2008-05-15 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Bumped version to 1.3.4. + * doctools.man: + * pkgIndex.tcl: + + * checker.tcl: Reworked the (sub)section handling, enabled the + * doctools_lang_cmdref.man: documentation writer to label + (sub)sections with logical names and use these in references. + Automatic logical names are improved, taking the current section + into account, making for a better ambiguity check. References + are now better as well. Backends are given unique physical + (sub)section ids. Added a new formatting command + 'sectref-external' for references to (sub)sections outside of + the current document, to disable checking, and documented it. + + * docidx_plugin_apiref.man: Fixed the external section references + * doctoc_plugin_apiref.man: in the manpages to prevent false warnings. + * doctools_plugin_apiref.man: + + * mpformats/c.msg: Message catalogs extended with new warning + * mpformats/de.msg: 'missingsect' for apparently dangling + * mpformats/en.msg: (sub)section references. + * mpformats/fr.msg: + + * mpformats/fmt.html: Updated the backends for the changes in the + * mpformats/fmt.latex: frontend/backend API, and updated testsuite + * mpformats/fmt.nroff: results. + * mpformats/fmt.text: + * mpformats/fmt.tmml: + * mpformats/fmt.wiki: + * mpformats/_common.tcl: + * tests/latex/00: + * tests/latex/01: + * tests/latex/02: + * tests/latex/03: + * tests/latex/04: + * tests/latex/05: + * tests/latex/06: + * tests/latex/07: + * tests/latex/08: + * tests/tmml/00: + * tests/tmml/01: + * tests/tmml/02: + * tests/tmml/03: + * tests/tmml/04: + * tests/tmml/05: + * tests/tmml/06: + * tests/tmml/07: + * tests/tmml/08: + * tests/html/00: + * tests/html/01: + * tests/html/02: + * tests/html/03: + * tests/html/04: + * tests/html/05: + * tests/html/06: + * tests/html/07: + * tests/html/08: + + * mpformats/_nroff.tcl: Modified the nroff backend to convert + * tests/nroff/03: (sub)section titles into uppercase in the + output. Updated testsuite results. + + * checker.tcl: Reworked the (sub)section handling, enabled the + documentation writer to label (sub)sections with logical names + and use these in references. Automatic logical names are + improved, taking the current section into account, making for a + better ambiguity check. References are now better as well. + Backends are given unique physical (sub)section ids. + + * mpformats/c.msg: Message catalogs extended with new warning + * mpformats/de.msg: 'missingsect' for apparently dangling + * mpformats/en.msg: (sub)section references. + * mpformats/fr.msg: + + * mpformats/fmt.html: Updated backends for the changes in the + * mpformats/fmt.latex: frontend/backend API. Nroff backend + * mpformats/fmt.nroff: additionally modified to automatically + * mpformats/fmt.text: convert (sub)section titles into uppercase. + * mpformats/fmt.tmml: + * mpformats/fmt.wiki: + * mpformats/_common.tcl: + * mpformats/_nroff.tcl: + + * mpformats/fmt.html (XrefLink): Now checking for and suppressing + * doctools.tcl: self-referential links from the current output + * doctools.man: file to itself exactly. Bumped version to 1.3.3. + * pkgIndex.tcl: + +2008-04-27 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Gave title h1 tag a class. Put a div around + * tests/html/*: the content of the synopsis section. Removed the + div around examples. Their pre tag has a class, that is enough. + Added default CSS styling to the code. Its definitions are + derived from the CSS Joe English <jenglish@users.sourceforge.net> + uses for the HTML generated by his TMML converter. Nice and + simple. Thank you. + + * tests/man/08: All possible list types are in testcase 5 already. + * tests/desc/08: Changed to demo all the commands in one file. + * tests/html/08: This makes trying out styles for the HTML easier too + * tests/latex/08: as everything can looked at in one file. + * tests/list/08: + * tests/nroff/08: + * tests/null/08: + * tests/text/08: + * tests/tmml/08: + * tests/wiki/08: + + * mpformats/fmt.html: Changed example formatting, removed the nested + * tests/html/*: table structure. Changed toc and synopsis + formatting to be more sematical, using classed unordered lists. + Added classes to the list formatting. Removed hardwired + linebreaks between last list element and end of list. Replaced + linebreaks in list items with proper paragraph formatting. Fixed + initialization error causing spurious para_close at the + beginning. Added foundation for an internal style-sheet. No + definitions yet however. + +2008-04-26 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * tests/man/08: Added test demonstrating all possible list types. + * tests/desc/08: + * tests/html/08: + * tests/latex/08: + * tests/list/08: + * tests/nroff/08: + * tests/null/08: + * tests/text/08: + * tests/tmml/08: + * tests/wiki/08: + +2008-04-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * tests/man/02: Added see_also and keyword references to this + * tests/html/02: example. Updated all changed results. + * tests/latex/02: + * tests/list/02: + * tests/nroff/02: + * tests/text/02: + * tests/tmml/02: + * tests/wiki/02: + +2008-04-21 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Modified to put sections and subsections + * mpformats/_html.tcl: into divisions a CSS can lock onto. Changed + * tests/html/*: to properly close paragraphs, sections, and sub- + sections. Changed to remove empty paragraphs, and empty lines. + Put the whole body into a division. Put text marked up as + optional into a span. Put section references into a span. Put + examples into a division. Some general cleanup of the internals. + +2008-04-19 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * tests/*/06: Extended for nested lists. + * tests/*/07: 2nd input and results for nested lists. + * mpformats/_nroff.tcl (nr_vspace): Added newlines to output for + proper formatting of text coming after it. + + * tests/syntax/e_*: Additional input and result files, completing + * tests/syntax/r_*: the list errors. Ditto the example commands, + sectref, and the commands for the semantic categories. + +2008-04-17 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Extended with loop to test response to the various + * tests/syntax/e_*: syntax errors we may find in doctools files, plus + * tests/syntax/r_*: first set of input files and error results. + * checker.tcl: Modified errors for commands which are allowed + everywhere in the header section since the extended syntax came + into effect. + +2008-04-14 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Fixed [Bug 1942472], reported by Michael + * tests/latex/00: Schlenker, in made with the new test cases. + * tests/latex/01: Now mapping the name of the user running + * tests/latex/02: the tests around in the expected and + * tests/latex/03: actual results as well. Modified the + * tests/latex/04: expected results for the one backend + * tests/latex/05: affected by the change. + * tests/latex/06: + +2008-04-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Added the remaining backends to the list of + backends checked. + + * tests/tmml/00: Expected results for TMML backend. + * tests/tmml/01: + * tests/tmml/02: + * tests/tmml/03: + * tests/tmml/04: + * tests/tmml/05: + * tests/tmml/06: + + * tests/text/00: Expected results for TEXT backend. + * tests/text/01: + * tests/text/02: + * tests/text/03: + * tests/text/04: + * tests/text/05: + * tests/text/06: + + * tests/wiki/00: Expected results for WIKI backend. + * tests/wiki/01: + * tests/wiki/02: + * tests/wiki/03: + * tests/wiki/04: + * tests/wiki/05: + * tests/wiki/06: + + * tests/latex/00: Expected results for LATEX backend. + * tests/latex/01: + * tests/latex/02: + * tests/latex/03: + * tests/latex/04: + * tests/latex/05: + * tests/latex/06: + + * tests/desc/00: Expected results for DESC backend. + * tests/desc/01: + * tests/desc/02: + * tests/desc/03: + * tests/desc/04: + * tests/desc/05: + * tests/desc/06: + + * tests/list/00: Expected results for LIST backend. + * tests/list/01: + * tests/list/02: + * tests/list/03: + * tests/list/04: + * tests/list/05: + * tests/list/06: + + * tests/null/00: Expected results for NULL backend. + * tests/null/01: + * tests/null/02: + * tests/null/03: + * tests/null/04: + * tests/null/05: + * tests/null/06: + + * tests/html/00: Replaced $ I d $ placeholder with @ID@. See + * tests/html/01: doctools.test. + * tests/html/02: + * tests/html/03: + + * tests/man/04: Replaced placeholder text with actual input to + * tests/man/05: run through the formatting backends. + * tests/man/06: + + * tests/html/04: Made results current. The handling of + * tests/html/05: backslashes is known to be wrong, noted + * tests/html/06: other ugliness. + + * tests/nroff/04: Made results current, fixed some formatting + * tests/nroff/05: problems, see below. + * tests/nroff/06: + + * mpformats/fmt.nroff (fmt_arg_def, fmt_opt_def): Added newlines + to output for proper formatting of elements in argument and + option lists. + + * doctools.test: Fix handling of $ I d $ placeholder used in input + files and expected results. Extended to handle errors, to catch + problems other than differences between expected and actual + results. Ignore CVS subdirectory and handle missing files for + expected results. + +2008-03-31 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Added tests to invoke the backends on a series of + input files and check the results against expectations. + * tests/man/00: First set of input files, and expected output for + * tests/man/01: the html and nroff backends. + * tests/man/02: + * tests/man/03: + * tests/man/04: + * tests/man/05: + * tests/man/06: + * tests/html/00: + * tests/html/01: + * tests/html/02: + * tests/html/03: + * tests/html/04: + * tests/html/05: + * tests/html/06: + * tests/nroff/00: + * tests/nroff/01: + * tests/nroff/02: + * tests/nroff/03: + * tests/nroff/04: + * tests/nroff/05: + * tests/nroff/06: + +2008-03-12 Andreas Kupries <andreask@activestate.com> + + * checker.tcl (widget): Fixed bad call propagation. + +2008-03-08 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Code cleanup, giving all upvar commands an + * docidx.tcl: explicit level argument. Bumped all version + * doctoc.tcl: numbers by one patchlevel. doctools -> 1.3.2, + * cvs.tcl: doctools::toc -> 0.3.1, doctools::idx -> 0.3.1, + * changelog.tcl: doctools::cvs -> 0.1.2, + * pkgIndex.tcl: doctools::changelog -> 0.1.2 + * docidx.man: + * doctoc.man: + * doctools.man: + * cvs.man: + * changelog.man: + +2007-09-25 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: Extended processor to pass the pass number to the + * checker.tcl: checker layer as well. Modified the checker layer + * pkgIndex.tcl: to suppress generation of warnings in all but the + * doctools.man: first pass, to avoid replication. Bumped version + to 1.3.1. This fixes [SF Tcllib Bug 1800413]. + + * mpformats/fmt.nroff: Fixed argument swap in fmt_arg_def, fixing + [SF Tcllib Bug 1800420]. + + * mpformats/fmt.html: Handled [SF Tcllib Bug 1800408] and [SF + Tcllib Bug 411], removing superfluous whitespace around link + text and adding more class names to semantic markup. + +2007-09-20 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.html: Added closing of paragraphs per the request + in [SF Tcllib Bug 1798427]. Tis more complicated. Paragraphs + inside of list elements are not yet closed. + + * mpformats/fmt.html: Reworking handling of list items a bit to + properly close the dt, dd, and li tags. Requested by [SF Tcllib + Bug 1798427]. + +2007-09-12 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.10 ======================== + * + +2007-08-20 Andreas Kupries <andreask@activestate.com> + + * doctools.tcl: Bumped versions to 1.3 and 0.3 respectively to + * docidx.tcl: reflect the extended syntax and bugfixes listed + * doctoc.tcl: below. + * doctools.man: + * docidx.man: + * doctoc.man: + * pkgIndex.tcl: + +2007-08-02 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.latex: Further reworking of the backend internals + for proper quoting of TeX special characters, prevention of + double-quoting, and markup of wanted special characters. Further + removed the use of 'quote' environments. Not needed for the + formatting and its use restricts the nesting of lists to three + levels. Without we can nest seven levels. Final fixes for + [Tcllib SF Bug 1766381]. + + * mpformats/fmt.text: Fixed handling of 'cmd_def'. + * mpformats/fmt.tmml: Fixed handling of nested lists. + * mpformats/fmt.latex: Fixed handling of list_end, was not updated + to the new list type codes. + * mpformats/fmt.latex: Fixed handling of ^ character. Has to be + escaped in regular text. Fixed handling of keywords and + references (see also). May contain special character in need of + escaping. Quote backslashes in paths. + Fixes for [Tcllib SF Bug 1766381.] + +2007-08-01 Andreas Kupries <andreask@activestate.com> + + * doctools.test: Updated test 8.4 for changes in the formatting of + warnings. + +2007-03-20 Andreas Kupries <andreask@activestate.com> + + * apps/dtplite: Added a block of meta data. + +2007-03-20 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.wiki: Added MD pragma excluding a bogus dependency + from consideration. + +2007-03-19 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctoc.tcl: Extended MD pragmas declaring the ownership of + * docidx.tcl: various non-code files. + * doctools.tcl: + + * support/devel/sak/doc/doc.tcl: Modified to print warnings even + if processed was stopped by an error. + + * mpformats/c.msg: Added messages for a set of newly deprecated + * mpformats/de.msg: commands and list types. Added proper umlauts + * mpformats/en.msg: to the german messages. + * mpformats/fr.msg: + + * doctools.tcl: Added a plugin API command (dt_where), providing + information about the current location, to provide location data + to warnings. + + * checker_toc.tcl: Language change (doctoc, docidx). Comments in + * checker_idx.tcl: the input are now swallowed by the checker + layer and not propagated to the backend anymore. + + * checker.tcl: Language changes. + -- Comments are swallowed, backends do not see them anymore. + -- 'require'ments an now go everywhere in the header, not only + after the 'desc'riptions. + -- Warnings now have location information. + -- The list types 'bullet', 'arg', 'opt', 'cmd', and 'tkoption' + are now deprecated. They are replaced by 'itemized', + 'arguments', 'options', 'commands', and 'tkoptions', and their + short forms 'items', 'args', 'opts', and 'cmds'. + -- 'para' can now be used inside of lists. Conversely 'nl' works + outside of lists too. The two commands are identical now, and + 'nl' is deprecated. + -- The list entry command 'lst_item' has been deprecated, + replaced by 'def'. Additionally the possible misspellings + 'list_item', 'listitem', and 'lstitem' of the old command are + recognized now too, albeit also considered to be deprecated. + -- The list entry command 'bullet' is deprecated, replaced + 'item'. + -- The commands 'see_also' and 'keywords' can now go anywhere in + the document, not only after the header. + + Note that everything which was made deprecated is still accepted + as valid input, however their use does cause the generation of + warnings. This means that the language after the changes is a + proper superset of the language before it. Old documents can be + processed just fine with the new code. + + * mpformats/fmt.html: Use the new list types for translation. + * mpformats/fmt.latex: + * mpformats/fmt.text: + * mpformats/fmt.tmml: + + * mpformats/fmt.nroff: Add a para when closing an inner list. + + * mpformats/idx.html: Rewritten to be single-pass, defering output + until the index is closed. Changed to ensure that keywords are + printed alpha-sorted (lsort -dict). Added navigation bar and + sectioning of the index. + + * apps/dtplite: Added a format 'validate' as alias for 'null', + * apps/dtplite.man: both of these now do not require an output + specification anymore. Added the collection and printing of + warnings. Replaced the homegrown commands for the reading and + writing of files with calls to fileutil commands. Now processing + input files in alphabetical order. Put common code for doctoc + and docidx generation into a small set of commands. toc and idx + are now sorted by description/keyword, output is column-aligned. + The doc* output is saved, to serve as examples. Document titles + are now cross-referencable via 'term', allowing direct links + between documents. Comments about internals added. Documentation + updated for the new functionality, and fixed all warnings due to + use of deprecated commands and list types. Added a section on + how to give feedback. + + * cvs.man: Fixed all warnings due to use of deprecated commands + * changelog.man: and list types, tweaked the titles, and added + sections about how to give feedback. + + * docidx.man: Significant rewrites for better language, better + * doctoc.man: referencing of introductory documents. Tweaked the + * doctools.man: titles, and added sections about how to give + feedback. + + * docidx_api.man: *** REMOVED *** old documentation about the + * docidx_fmt.man: languages and plugin APIs. + * doctoc_api.man: + * doctoc_fmt.man: + * doctools_api.man: + * doctools_fmt.man: + + * docidx_intro.man: *** ADDED *** new documentation about the + * docidx_lang_cmdref.man: languages and plugin APIs, with basic + * docidx_lang_faq.man: introductions, cross-referencing to + * docidx_lang_intro.man: related documents, further readings, + * docidx_lang_syntax.man: introduction by example, first + * docidx_plugin_apiref.man: beginning of faqs. + * doctoc_intro.man: + * doctoc_lang_cmdref.man: + * doctoc_lang_faq.man: + * doctoc_lang_intro.man: + * doctoc_lang_syntax.man: + * doctoc_plugin_apiref.man: + * doctools_intro.man: + * doctools_lang_cmdref.man: + * doctools_lang_faq.man: + * doctools_lang_intro.man: + * doctools_lang_syntax.man: + * doctools_plugin_apiref.man: + +2006-10-25 Andreas Kupries <andreask@activestate.com> + + * doctools.test: Added an explicit LANG=C setting to the tests. + * docidx.test: At least OS X needs the setting to behave correctly. + * doctoc.test: Thanks to Gustaf Neumann for the report. + +2006-10-08 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Rewritten to use new features for handling the + * docidx.test: environment. + * doctoc.test: + +2006-10-03 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.9 ======================== + * + +2006-10-02 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Made the testsuite robust against locale + * doctoc.test: settings in the environment. The tests + * docidx.test: assume the default locale (LANG=C). + +2006-09-19 Andreas Kupries <andreask@activestate.com> + + * doctools.man: Bumped version to 1.2.1 + * doctools.tcl: + * pkgIndex.tcl: + +2006-08-10 Andreas Kupries <andreask@activestate.com> + + * mpformats/_text.tcl: Replaced textutil with the exact packages + * mpformats/fmt.text: needed, and adjusted all callers to use the + long command names. + +2006-06-16 Andreas Kupries <andreask@activestate.com> + + * ../../apps/dtplite: Still found a xref link bug in the -merge + code path. The per-module toc had the wrong links. Added code to + generate and set a proper file mapping for these tocs. Removed + MapLink and switched to the new command "fileutil::relativeUrl". + +2006-03-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_nroff.tcl: Do not double-quote (sub)section titles if + they do not contain whitespaces. + +2006-01-28 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Fixed use of duplicate test names + +2006-01-22 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * docidx.test: More boilerplate simplified via use of test support. + * doctoc.test: + * doctools.test: + +2006-01-19 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * docidx.test: Hooked into the new common test support code. + * doctoc.test: + * doctools.test: + +2005-10-06 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.8 ======================== + * + +2005-10-03 Andreas Kupries <andreask@activestate.com> + + * checker.tcl: Added code checking for ambiguities in section + * mpformats/c.msg: and subsection titles. It causes warnings. + * mpformats/en.msg: Extended the message catalogs with strings for + * mpformats/de.msg: the new warning. + * mpformats/fr.msg: + +2005-06-17 Andreas Kupries <andreask@activestate.com> + + * mpformats/_common.tcl (c_sectionId): Converting quotes into + underscores. Fixes [SF Tcllib Bug 1220089]. + +2005-06-06 Andreas Kupries <andreask@activestate.com> + + * mpformats/fr.msg: Fixed [Tcllib SF Bug 1213636], reported by + <sarnold75@users.sourceforge.net>, by removing the incorrect + english strings preceding the french ones. + +2005-04-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Testsuite package requirements fixed to ensure + * docidx.test: use of local packages. + * doctoc.test: + + * doctools.tcl: Typo police. + * docidx.tcl: + * doctoc.tcl: + +2005-02-18 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_nroff.tcl: Fixed problem with comment + handling. Before the fix we could generate output where nroff + would misinterpret a string in apostrophes at the beginning of a + line as comment. Regular comments now have the special \1 + quoting for markup. + + * fmt.nroff: Fixed list processing. The commands stating list + items needed newlines to ensure proper separation if the input + has text immediately following the command, and not on the next + line. Superfluous newlines coming from text stating in the next + line is automatically excised during post-processing. + +2005-01-17 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_nroff.tcl: Extended the post processing to regularize + confusing *roff formatting at the beginning of lines. This fixes + Tcllib SF Bug 1094294, which was reported by Rolf Ade + <pointsman@users.sourceforge.net>. + +2005-01-11 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff: Fixed bad nroff formatting for examples + * mpformats/_nroff.tcl: with explicit start/end commands. + +2004-11-01 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.html (fmt_namespace): Added HTML backend code for + the namespace command. + +2004-10-05 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.7 ======================== + * + +2004-09-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_text.tcl: Fixed expr'essions without braces. + +2004-09-21 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.nroff: Removed superfluous nr_rst calls inserted + at the end of a command, by the commands 'call', and 'usage'. + +2004-07-30 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_common.tcl: Made section references + * mpformats/fmt.html: insensitive to case of + * mpformats/fmt.latex: the refering text. Also + * mpformats/fmt.nroff: now allowing an optional + * mpformats/fmt.text: label to the reference + * mpformats/fmt.tmml: a different text than + * mpformats/fmt.wiki: the section title. Updated + * doctools_fmt.man: the format and api specifi- + * doctools_api.man: cations. + * checker.tcl: + +2004-07-29 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/idx.html: Changed index table to use top alignment. + + * doctools.man: Full overhaul of the documentation + * doctools_api.man: pertaining to doctools, format, engine + * doctools_fmt.man: api, and framework package. + + * docidx_fmt.man: Typo fixes. + * doctoc_fmt.man: + + * doctools.test: Updated to changes in error processing made + * doctoc.test: on 2004-07-22 (See below). + * docidx.test: + +2004-07-24 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * docidx_fmt.man: More overhaul. + * docidx_api.man: + * doctoc_fmt.man: + * doctoc_api.man: + * doctoc.man: + * doctools_fmt.man: + * doctools_api.man: + * doctools.man: + * changelog.man: + * cvs.man: + +2004-07-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * docidx_api.man: Overhaul. + * docidx.man: + + * ../../apps/dtplite: Revamped the whole file mapping. Actually + ripped it out. Is not needed, the formatting engine does the + necessary parts for us, if we feed it the correct -file + options. This kills the outstanding bug with xref links. + + * ../../apps/dtplite: Bugfix. Added checks to prevent duplicate + entries in the keyword index. Without these checks going through + a set of packages twice for merging will create double links for + each actual entry. Changed the representation of the index saved + between merge invokations to keep the array for the voiding of + duplicates around. + + * docidx.man: Overhaul of documentation. + * cvs.man: + * changelog.man: + +2004-07-22 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * ../../apps/dtplite: Reduced error output, show only the message, + not the whole stack. + + * doctools.tcl: Changed processing of error messages so that + * doctoc.tcl: we don't loose the location information. + * docidx.tcl: + +2004-07-22 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools_api.man: Polished the manpages a bit, + * ../../apps/dtplite.man: for better cross-referencing. + + * mpformats/fmt.html: Fixed initialization bug regarding + cross-references. Added xref matching to the formatting commands + 'term' and 'package'. Extended matching to allow multiple + prefixes, and to search for the word in lowercase. + +2004-07-20 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * apps/dtplite.man: New application for doctools processing. + * apps/dtplite: Supercedes 'mpexpand'. Will be installed. + + * mpformats/idx.html: Added engine parameter 'kwid', allowing the + external definition of anchor names for keywords instead of + having them generated automatically. Required for persistence + when extending an existing index. + + * mpformats/fmt.html: Added eols to the table of contents for + better readability of the generated HTML. + + * mpformats/toc.nroff: Fixed bad markup in genration of + * mpformats/idx.nroff: tocs and indices. Internal markers + were not stripped out. + + * mpformats/toc.wiki: + * mpformats/toc.tmml: + * mpformats/toc.text: + * mpformats/toc.nroff: + * mpformats/toc.html: + * checker_toc.tcl: Extended 'division_start' formatting command + * doctoc_fmt.man: with an optional second argument, a symbolic + file reference. Create a link to this file from the division + label, if supported by the format. Where not the second argument + will be ignored. + +2004-07-10 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * docidx.man: Fixed [Tcllib SF Bug 985601]. A number + * doctoc.man: of options (-copyright) and methods (map, + * doctools.man: parameters, setparam) were not documented, + * docidx_api.man: nor the engine parameters supported by the + * doctoc_api.man: predefined html formatters (header, footer, + * doctools_api.man: meta, xref). This is no longer the case. + +2004-05-30 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand.man: Updated reference 'dtformat' to 'doctools_fmt'. + +2004-05-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Updated version number to distinguish from the + * doctools.man: 1.6.1 release. + * pkgIndex.tcl: + +2004-05-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.6.1 ======================== + * + +2004-05-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Rel. engineering. Updated version number + * doctools.man: of doctools to reflect its changes, to 1.0.2. + * pkgIndex.tcl: + +2004-05-14 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Fixed a bug in the namespace implementation + * checker.tcl: (RFE 943145, see below). Cannot use 'namespace' in + checker, it uses msgcat, uses in turn the builtin, overwriting + is bad. Have to handle this specially (New name, rewrite to new + name) before handing the macro over to the expander. + + * doctools.tcl: Implemented [SF Tcllib RFE 772490] for + * checker.tcl: doctools, the addition of 'subsections' + * mpformats/_common.tcl: to the language. Updated the main engine, + * mpformats/_nroff.tcl: the validator subsystem, and all formatting + * mpformats/_text.tcl: engines which are coming with the package. + * mpformats/fmt.html: For HTML output subsections are added to + * mpformats/fmt.latex: the TOC (See [SF Tcllib RFE 772491] below) + * mpformats/fmt.nroff: as well. + * mpformats/fmt.null: + * mpformats/fmt.text: + * mpformats/fmt.tmml: + * mpformats/fmt.wiki: + +2004-05-14 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_text.tcl (SECT): Fixed a small problem in the text + generator which was present for ages. Titles of more than one + word would have braces around them. Not fatal but also not so + nice looking. It was an argument versus argument list + thing. Adding a lindex in the proper place gets rid of the + additional level of quoting. + +2004-05-04 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.html: Implemented [SF Tcllib RFE 772491]. Added + the generation of a table of contents at the beginning of the + html output for quick jumps to the various parts of the + documentation. + + * checker.tcl: Accepted [SF Tcllib RFE 946856], an + * doctools_fmt.man: extension of the uri command to allow + * doctools.tcl: labels. Updated documentation, added + * mpformats/fmt.html: added to highlevel implementation, + * mpformats/fmt.latex: updated all predefined formatters. + * mpformats/fmt.nroff: + * mpformats/fmt.null: Accepted [SF Tcllib RFE 943145] as + * mpformats/fmt.text: well, adding a namespace markup. + * mpformats/fmt.tmml: + * mpformats/fmt.wiki: + + * mpformats/_nroff.tcl: Fixed [SF Tcllib Bug 943146]. Added markup + * mpformats/fmt.nroff: protection code like already in use for + HTML and XML to handle nroff's special + characters, i.e. the backslash properly. + Also fixed handling of leading dashes in + 'opt_def'. + +2004-04-22 Joe English <jenglish@users.sourceforge.net> + + * mpformats/fmt.xml: BUGFIX: "puts stderr" ==> "puts_stderr". + +2004-02-15 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.6 ======================== + * + +2004-02-09 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.test: Fixed problems with Tcl 8.5, the tests were + dependent on the order of keys in the result of [array get]. + +2003-10-21 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.wiki (fmt_manpage_end): Fixed usage of wrong + variable ('copyright' was used, should have been 'ct'). + [Bug 826206]. + +2003-06-06 Andreas Kupries <andreask@activestate.com> + + * mpformats/fr.msg: Added french message catalog. Supplied by + David Zolli <dzolli@users.sourceforge.net>, aka kroc. This is + tracker item [Bug 744149]. + +2003-05-23 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff (fmt_arg_def, fmt_cmd_def): Analogous errors + to fmt_opt_def, see below. Fixed. Reported by David Welton. + +2003-05-21 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff (fmt_opt_def): Fixed bug. Called [option], + should have been [fmt_option]. Prevented the nroff conversion of + the multiplexer documentation. Reported by David Welton. + +2003-05-05 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * + * Released and tagged Tcllib 1.4 ======================== + * + +2003-04-01 Andreas Kupries <andreask@activestate.com> + + * checker_toc.tcl: Bug fixes for handling of nested toc divisions. + + * ../../examples/doctools/doctools.idx: + * ../../examples/doctools/doctools.toc: Updated to reflect latest + changes in the format definitions. + + * doctoc.tcl: + * docidx.tcl: Added the package and file ops initially created in + doctools.tcl to these packages too, so that their text engines + can use 'textutil' too. + + * mpformats/_text.tcl: + * mpformats/fmt.text: + * mpformats/toc.text: + * mpformats/idx.text: Bug fixes. + +2003-03-31 Andreas Kupries <andreask@activestate.com> + + * mpformats/toc.text: + * mpformats/idx.text: New files, toc & index formatting in plain text. + + * mpformats/_text.tcl: + * mpformats/fmt.text: Moved processing of plain text into the generic part. + +2003-03-31 Andreas Kupries <andreask@activestate.com> + + * cvs.tcl (scanLog): Applied fix for Bug #712951 reported by Joe + English <jenglish@users.sourceforge.net>. + +2003-03-29 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl (SetupFormatter): Moved error output command to the + front, so that the code loading the engine can use it too, and + not only the engine procedures. Added alias for 'file', and a + special command which is a shortcut for 'package require' so + that engines can load packages. This was required for the plain + text engine which makes heavy use of the formatting commands in + 'textutil'. Added setup of 'ctopandclear'. + (SetupChecker): Added setup of 'ctopandclear'. + (Package, Locate): New commands supporting package + require. Instead of trying to enable every command in the safe + interpreter required for package management we use the standard + package commands to locate the index for thr requested package + and evaluate just that in the safe interpreter, after + temporarily enabling source and load commands. + + * checker.tcl: Added code for debugging, like already present in + the files checker_doc*.tcl. + + * mpformats/_text.tcl: Core for plain text engines. + * mpformats/fmt.text: New engine. Generates output in plain text. + +2003-03-28 Andreas Kupries <andreask@activestate.com> + + * pkgIndex.tcl: added 'doctools::cvs' and 'doctools::changelog' to + the package index. + + * changelog.man: + * changelog.tcl: New. Parsing of ChangeLogs into list structures, + merging of multiple logs, conversion into a doctools + document. The code for parsing came originally out + Makedist_SupportAku, a private package extending my Makedist + tool. Documented the code. + + * cvs.tcl (toChangeLog): Using the new textutil commands 'indent' + and 'undent' for proper alignment of the comments extracted from + the log. + +2003-03-27 Andreas Kupries <andreask@activestate.com> + + * cvs.man: + * cvs.tcl: Added code to handle parsing and reformatting of cvs + log files. Origin of the code the tcl'ers wiki, page + http://wiki.tcl.tk/log2changelog. The actual original author is + unknown (not listed on the wiki). + +2003-03-24 Andreas Kupries <andreask@activestate.com> + + * doctools_fmt.man: Fixed documentation bug #704187 reported by + Roy Terry <royterry@users.sourceforge.net>. + +2003-03-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * checker.tcl: Fixed incorrect signature of 'usage'. + * mpformats/fmt.null: Bugfix in naming of the procedures. + +2003-03-13 Andreas Kupries <andreask@activestate.com> + + * mpformats/_common.tcl: Fixed initialization error for + cross-references causing unwanted suppression (leakage of + definitions between multiple pages). + + * doctoc.tcl: Bug fixes in three return statemments. + * docidx.tcl: (return -code error string, not return -code string) + * doctools.tcl: + +2003-03-11 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Rewrite handling of [keywords] and + * mpformats/fmt.latex: [see_also] to behave like for the TMML + * mpformats/fmt.list: formatter: Collect all keywords and + * mpformats/fmt.nroff: x-references during the first pass, insert + * mpformats/fmt.wiki: the results during the second pass, in + [manpage_end]. Ensures that at most one + see_also / keyword section is present, + ensures uniform order and handling of + multiple keyword / see_also commands is + now uniform too. + + * examples/doctools.idx: Moved to the new examples/doctools + * examples/doctools.toc: directory. Thanks to Larry Virden + <lvirden@users.sourceforge.net> for + pointing out that the original location + in the doctools module violated the + principle of collecting examples in a + separate directory, instated by + myself. Stupid me. + +2003-03-04 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * A examples/doctools.idx: Fairly extensive revamping of the + * A examples/doctools.toc: codebase. Added a format for + * A mpformats/_idx_common.tcl: indices, formatting engines, a + * A mpformats/_toc_common.tcl: package for handling it. Extended + * A mpformats/idx.html: all packages to allow engine + * A mpformats/idx.nroff: parameters and mapping from + * A mpformats/idx.null: symbolic to actual filenames or + * A mpformats/idx.wiki: urls. Right now only the HTML + * A mpformats/toc.html: engines actually provide + * A mpformats/toc.nroff: parameters. Added testsuites for + * A mpformats/toc.null: doctoc and docidx. Revamped the + * A mpformats/toc.tmml: documentation to cross-reference + * A mpformats/toc.wiki: each other better, more uniform in + * A api_idx.tcl: structure (not complete), naming of + * A api_toc.tcl: the manpages for this module is now + * A checker_idx.tcl: uniform. Added examples for doctoc + * A checker_toc.tcl: and docidx formats, both in the + * A docidx.man: manpages, and as separate files. + * A docidx.tcl: + * A docidx.test: + * A docidx_api.man: + * A docidx_fmt.man: + * A doctoc.man: + * A doctoc.tcl: + * A doctoc.test: + * A doctoc_api.man: + * A doctoc_fmt.man: + * A doctools_api.man: + * A doctools_fmt.man: + * A tocexpand: + * M ChangeLog: + * M NOTES: + * M api.tcl: + * M checker.tcl: + * M doctools.man: + * M doctools.tcl: + * M doctools.test: + * M pkgIndex.tcl: + * M mpformats/_common.tcl: + * M mpformats/_nroff.tcl: + * M mpformats/c.msg: + * M mpformats/de.msg: + * M mpformats/en.msg: + * M mpformats/fmt.html: + * M mpformats/fmt.latex: + * M mpformats/fmt.list: + * R dtformat.man: + * R dtformatter.man: + +2003-02-16 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.list: Modified to extract all meta information out + of the page. Changed the output format. Argument to the + 'manpage' command in the output is now a key/value list + acceptable to 'array set' instead of a simple list with fixed + positions for the various data elements. + +2003-02-16 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctoc.tcl: Specified a new portable format for + * api_toc.tcl: writing a table of contents. Wrote a + * checker_toc.tcl: package to handle input that format + * dtocformat.man: and a number of formatting engines + * dtocengine.man: plugging into this package to + * mpformats/_toc_common.tcl: generate output in various formats. + * mpformats/toc.html: This required additional checker code + * mpformats/toc.nroff: and more messages in the message + * mpformats/toc.null: catalogs. + * mpformats/toc.tmml: + * mpformats/toc.wiki: + * pkgIndex.tcl: + * mpformats/c.msg: + * mpformats/en.msg: + * mpformats/de.msg: + * mpformats/_nroff.tcl: + + * doctools.tcl: Rephrased documentation of SetupChecker a bit. + +2003-02-12 Andreas Kupries <andreask@activestate.com> + + * dtformatter.man: Updated the documentation to include the + * dtformat.man: two new commands (vset, include). + + * doctools.tcl (Eval): Added handling of new [include] + * doctools.tcl (ExpandInclude): formatting command. + + * checker.tcl (vset): New command in the formatting language for + handling variables (setting and retrieving values). Differs from + the regular in that the set value is not retruned as the result + of the command. This is necessary to avoid unwanted insertion of + data into the output stream. The command is handled in the + checker layer (although no checking is required). The engines + never see this command. + + * mpformats/fmt.nroff: Changed both engines to not use the + * mpformats/fmt.wiki: expander context stack anymore. It + interferes with handling of include + files. It was used to catch all output and + then perform last-miunte processing. for + that we have [fmt_postprocess], moved the + code to that. + +2003-01-27 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Modified generation of section titles to + make the resulting HTML more conformant and less + troublesome. Thanks to Larry Virden + <lvirden@users.sourceforge.net> for the catch. Revised the + engine a bit. Entries in the synopsis now refer directly to the + location where they are defined ([call] command). + +2003-01-16 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Removed 'strong' formatting. The checker + * mpformats/fmt.latex: warns if used and warnings requested, it + * mpformats/fmt.nroff: now also redirects the command to 'emph'. + * mpformats/fmt.wiki: The option -visualwarn (doctools, and + * mpformats/fmt.null: mpexpand) renamed to -deprecated. Message + * mpformats/fmt.list: 'visualmarkup' removed from the catalogs, + * mpformats/c.msg: and 'depr_strong' added instead. + * mpformats/en.msg: + * mpformats/de.msg: + * checker.tcl: + * doctools.tcl: + * mpexpand: + + * doctools.man: Updated, converted [strong] to better + * dtformat.man: formatting commands. Ditto for all manpages + * dtformatter.man: in tcllib containing 'strong'. 'strong' is now + * mpexpand.man: not present anymore. + + * mpformats/_common.tcl: Applied a patch by Joe English adding the + * mpformats/fmt.tmml: copyright information to the appropriate + place in the TMML output. This also fixes + a bug in c_get_copyright where an empty + string resulted in a incomplete line + being given to the formatter. + + * mpformats/fmt.html: Removed the phrase 'All rights reserved' + * mpformats/fmt.latex: from the code, on recommendation by + * mpformats/fmt.nroff: Joe English. + * mpformats/fmt.wiki: + + (In the way to early morrow :) + * mpformats/fmt.html: Changed to display copyright information in + * mpformats/fmt.latex: the conversion result itself and not only + * mpformats/fmt.nroff: embedded in comments. + * mpformats/fmt.wiki: + +2003-01-14 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * doctools.tcl: Added a new formatting command, + * doctools.test: 'copyright', to declare/assign copyright + * doctools.man: for manpages. Updated both documentation + * dtformat.man: and testsuite. Extended the common code + * checker.tcl: base with convenience methods for storing + * api.tcl: and retrieving such information. The + * mpformats/fmt.html: retrieval operation also implements the + * mpformats/fmt.latex: logic giving the information in a manpage + * mpformats/fmt.list: precedence over information coming from the + * mpformats/fmt.nroff: processor. Updated all predefined engines + * mpformats/fmt.null: to handle the new command. TMML done only + * mpformats/fmt.tmml: partially, as I don't know where the copy- + * mpformats/fmt.wiki: right has to go. + * mpformats/_common.tcl: + * mpformats/_html.tcl: + * mpformats/_nroff.tcl: + * mpexpand: + +2003-01-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand: Moved format help into the package itself. + * doctools.tcl: Changed the checker. Input syntax errors are not + * checker.tcl: written to stderr anymore, but reported through + * doctools.man: an standard tcl error. Warnings are collected and + * doctools.test: can be queried after a formatting run. Made the + generic engine more robust against failures in a + formatting engine. Wrote documentation for the + package. Extended the configuration method to be + more standard. Wrote a testsuite. + +2003-01-11 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand: Nearly complete rewrite of the system. + * mpformats/fmt.html: The recognized input format was _not_ + * mpformats/fmt.latex: changed. The main functionality was + * mpformats/fmt.list: placed into a package, doctools. This + * mpformats/fmt.nroff: package allows the creation of multiple + * mpformats/fmt.null: formatter objects, to be used alone or + * mpformats/fmt.tmml: together. The application 'mpexpand' was + * mpformats/fmt.wiki: rewritten to use that package and is now + * mpformats/_common.tcl: much simpler. The communication between + * mpformats/_nroff.tcl: the various stages was made simpler, and + * mpformats/_xml.tcl: one slave interpreter was dropped because + * mpformats/_html.tcl: of this. It might be added back if its + * api.tcl: existence proves to be beneficial. The + * checker.tcl: API between main systen and formatter + * doctools.tcl: engine was changed, consequently all + * dtformatter.man: existing engines had to be updated. They + were also made simpler, especially in the + area of list handling, because of the + validation done by the checker subsystem. + The version number is now 1.0. + +2002-12-16 David N. Welton <davidw@dedasys.com> + + * mpexpand (format_find): Added 'argv0' as a global variable, in + order to avoid erroring out when providing a bad format. + +2002-12-05 Andreas Kupries <andreask@activestate.com> + + * mpformats/fmt.nroff: Changed so that comments coming before + manpage_begin are moved after the standard header generated by + manpage_begin. + +2002-09-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand: Corrected example formatting, have to run argument + through plain text handling. + * mpformats/fmt.wiki: Added Wiki formatting. + +2002-07-08 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Changed bug #578465 which caused + mis-generation of angle-brackets and quotes. + +2002-06-06 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: + * mpformats/_html.tcl: Added the missing handling of " (") to + the format. + +2002-05-27 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_xml.tcl: args -> arguments, as the argument is not + the last one. The code as is was not erroneous, but a possible + trouble spot should tcl ever be more strict with 'args'. + +2002-05-21 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.nroff: Accepted patch for bug #556509, both by Joe + English <jenglish@users.sourceforge.net>. + +2002-05-09 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * This completes the implementation of SF tcllib item #534334. + + * mpformats/fmt.html: See last entry, completed definitions for + the new lists. + + * format.man: Added the new commands (see last entry) to the + format specification and also added more explanations regarding + sections and paragraphs. + +2002-05-09 Joe English <jenglish@users.sourceforge.net> + + * mpexpand: + * mpformats/c.msg: + * mpformats/de.msg: + * mpformats/en.msg: + * mpformats/fmt.nroff: + * mpformats/fmt.latex: + * mpformats/fmt.list: + * mpformats/fmt.nroff: + * mpformats/fmt.null: Added new list types for arguments, options, + commands, and Tk (widget) options. + +2002-04-24 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: + * mpformats/_html.tcl: Changes analogous to TMML (see below) to + differentiate internal markup and external special characters. + +2002-04-24 Joe English <jenglish@users.sourceforge.net> + + * mpformats/_xml.tcl + * mpformats/fmt.tmml: Correctly handles XML markup characters + in macro arguments. Also correctly escapes apostrophes + in attribute values (previously-unnoticed bug). + * mpformats/fmt.tmml: TMML uses <url> instead of <uri>, and + does not have a <strong> element; changed output accordingly. + +2002-04-23 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * format.man: Added descriptions for all the commands performing + semantic markup. This closes bug #527025. + +2002-04-10 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand: Fixed error in checker of plain text. + + * mpformats/fmt.nroff: Added newlines in front of dot commands to + make sure that the formatting is correct. Superfluous newlines + are stripped in the post processor of this format, so + unconditionally adding them does not hurt. + +2002-04-02 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/en.msg: + * mpformats/c.msg: + * mpformats/de.msg: Added the messages required by the new code + below. + + * mpexpand: Added code to check that plain text is not used in + places where it is not allowed. + +2002-04-01 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * Committed changes to list generation (better generation of + whitespace for HTML, allowing hints). Only the HTML formatter + currently acknowledges hints. This fixes SF Bug #535382. + +2002-03-26 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand: Changed the generation of error messages by the format + checker to use explicit error codes instead of trying to + construct the whole message automatically. Error codes are + mapped to textual messages using the message catalog facility, + allowing for easy i18n and l10n of mpexpand. Catalogs for the + locales "c", "en", and "de" are provided. + + * mpformats/fmt.html: Changed uri formatting to be a link. + + * mpformats/fmt.tmml: + * mpformats/fmt.html: + * mpformats/fmt.nroff: + * mpformats/fmt.latex: + * mpformats/fmt.list: + * mpformats/fmt.null: + * mpformats/_api.tcl: Added formatting commands "term" and "const" + to allow the structural markup of non-specific terminology and + of constant values. + + * mpformats/fmt.nroff (bullet): Bulleting changed, use \(bu as + bullet instead of *. + (uri): Fixed error with underlining. + +2002-03-25 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpexpand: Extended with additional code checking that the + formatting commands are not used out of order and in the wrong + context. This check is independent of the format and thus + implemented outside of the format. Tcllib FR #530059. + + * mpexpand: Implemented Tcllib FR #527029 (help options). + +2002-03-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Removed 'center' alignment from + examples. Tcllib Bug #528390. + +2002-03-09 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * modules/doctools/format.man: Added documentation for [rb] and + [lb]. This partially fixes bug #527025. + + * modules/doctools/mpformats/_html.tcl: The patch for FR #527716 + also fixes a bug in the generation of HTML escapes. The table + swiped from htmlparse seems to contain some non-standard + escapes. Which are removed now. + + * modules/doctools/format.man: + * modules/doctools/mpexpand: + * modules/doctools/mpformats/fmt.html: + * modules/doctools/mpformats/fmt.latex: + * modules/doctools/mpformats/fmt.list: + * modules/doctools/mpformats/fmt.nroff: + * modules/doctools/mpformats/fmt.null: + * modules/doctools/mpformats/fmt.tmml: + * modules/doctools/mpformats/fmt.tmml: Accepted FR #527716 by + Bryan Oakley <boakley@users.sourceforge.net> which adds a + command [usage] to the format. It allows the specification of + usage information for the synopsis without the need to be + embedded into a definition list. + +2002-02-28 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.nroff: Corrected problems with trimming lines and + the stripping of empty lines. + + * mpformats/fmt.html: Changed the formatting of examples. Embedded + them into a table and additionally marked them with a black bar + to the left. + +2002-02-27 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.null: Null format, does not produce any output. + + * mpformats/fmt.tmml: + * mpformats/fmt.nroff: + * mpformats/fmt.latex: + * mpformats/fmt.html: + * mpformats/fmt.list: Implementations of the new command. + + * mpexpand: Added the commands to the processor application. Added + option "-visualwarn". When present the processor warn about + usage of visual markup. Tcllib FR #517599. + + * mpformats/_api.tcl: Added a number of semantic markup commands + to the api as part of Tcllib FR #517599. Also added comment + command, see Tcllib FR #520269. + +2002-02-14 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_common.tcl: Frink run. + +2002-02-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/fmt.html: Added detection of section cross-references + in [emph] and [strong] based on the code for TMML. + +2002-02-13 Joe English <jenglish@users.sourceforge.net> + + * mpformats/fmt.tmml: [example_begin] inside lists was + not handled correctly. + + * mpformats/fmt.tmml: Detect section cross-references + in [emph] and [strong]. + +2002-02-12 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * mpformats/_html.tcl: Added command to map HTML special + characters to their escape sequences. + + * mpformats/fmt.latex: Added code to disable special processing of + plain text while inside of an example. + + * mpformats/fmt.tmml: Added HandleText call to [example] to handle + special XML characters inside of the example. Not requitred for + [example_begin] / [example_end] as the text will go through + HandleText automatically for that case. + + * mpformats/fmt.nroff: Added split to lsearch statement in + manpage_end to make the code robust against strings which are + not valid lists. + +2002-02-12 Joe English <jenglish@users.sourceforge.net> + + * Added [example_begin] and [example_end] commands. + Also [example { code ... }] command. + +2001-12-13 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * Added formatter for LaTeX. + +2001-12-12 Andreas Kupries <andreas_kupries@users.sourceforge.net> + + * New module. Application module providing a simple tcl-based + manpage markup language and a processor for converting this + format to TMML, nroff and HTML. Extensible, i.e. additional + formats can be added without to much work (Manpages for format + and internal interfaces are provided). diff --git a/tcllib/modules/doctools/NOTES b/tcllib/modules/doctools/NOTES new file mode 100644 index 0000000..05fd102 --- /dev/null +++ b/tcllib/modules/doctools/NOTES @@ -0,0 +1,34 @@ +====== + TODO +====== + +* docidx / doctoc package documentation - sync with code +* doctools package documentation ditto + + + + +* Add a tk-based editor application which loads and generates + the format (and can invoke the processor to generate the other + formats). + +* Rewrite formatters to use generator packages for their + output format. Example: HTML => tcllib/html package + to generate the tags. Less quoting issues. Has escape + handlers. + +======= + +Note that running multiple formatters in parallel is possible, but +requires that the whole chain of expander, checker and engine are +replicated per format. The reason for this is that engine generates +some output, but always passes it up to its caller, i.e the expander, +for final composition. This is especially true for nested macro +invocations where the intermediate results generated by the engine are +passed through the expander to be sent down again into the engine. For +multiple engines we have to combine and then separate the results for +the various formats. The problem is to distinguish between data coming +from the engine and text coming from the outside, for the latter has +to be replicated instead of separated. This is possible, but I do not +believe that it is worth the additional complexity of the +implemementation. diff --git a/tcllib/modules/doctools/api.tcl b/tcllib/modules/doctools/api.tcl new file mode 100644 index 0000000..79d5572 --- /dev/null +++ b/tcllib/modules/doctools/api.tcl @@ -0,0 +1,31 @@ +# -*- tcl -*- +# api.tcl -- API placeholders +# +# Copyright (c) 2001 Andreas Kupries <andreas_kupries@sourceforge.net> +# Copyright (c) 2002 Andreas Kupries <andreas_kupries@sourceforge.net> +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +################################################################ +# This file defines all commands expected from a formatter by the +# doctools library. It is loaded into the formatter interpreter before +# the code for a particular format is loaded. All commands defined +# here return an error. This ensures the generation of errors if a +# format forgets to define commands in the API. + +################################################################ +# Here it comes + +foreach __cmd { + initialize shutdown setup numpasses listvariables varset + + manpage_begin moddesc titledesc manpage_end require description + section para list_begin list_end lst_item call bullet enum see_also + keywords example example_begin example_end nl arg cmd opt emph strong + comment sectref syscmd method option widget fun type package class var + file uri term const copyright category +} { + proc fmt_$__cmd {args} [list return "return -code error \"Unimplemented API command $__cmd\""] +} +unset __cmd + +################################################################ diff --git a/tcllib/modules/doctools/api_idx.tcl b/tcllib/modules/doctools/api_idx.tcl new file mode 100644 index 0000000..3ee553d --- /dev/null +++ b/tcllib/modules/doctools/api_idx.tcl @@ -0,0 +1,26 @@ +# -*- tcl -*- +# api_idx.tcl -- API placeholders +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +################################################################ +# This file defines all commands expected from a docidx formatter by the +# doctools library. It is loaded into the formatter interpreter before +# the code for a particular docidx format is loaded. All commands defined +# here return an error. This ensures the generation of errors if a +# format forgets to define commands in the API. + +################################################################ +# Here it comes + +foreach __cmd { + idx_initialize idx_shutdown idx_setup idx_numpasses + idx_listvariables idx_varset + fmt_index_begin fmt_index_end fmt_key fmt_manpage fmt_url + fmt_comment fmt_plain_text +} { + proc $__cmd {args} [list return "return -code error \"Unimplemented API command $__cmd\""] +} +unset __cmd + +################################################################ diff --git a/tcllib/modules/doctools/api_toc.tcl b/tcllib/modules/doctools/api_toc.tcl new file mode 100644 index 0000000..42398cf --- /dev/null +++ b/tcllib/modules/doctools/api_toc.tcl @@ -0,0 +1,26 @@ +# -*- tcl -*- +# api_toc.tcl -- API placeholders +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +################################################################ +# This file defines all commands expected from a doctoc formatter by the +# doctools library. It is loaded into the formatter interpreter before +# the code for a particular doctoc format is loaded. All commands defined +# here return an error. This ensures the generation of errors if a +# format forgets to define commands in the API. + +################################################################ +# Here it comes + +foreach __cmd { + toc_initialize toc_shutdown toc_setup toc_numpasses + toc_listvariables toc_varset + fmt_toc_begin fmt_toc_end fmt_division_start fmt_division_end + fmt_item fmt_comment fmt_plain_text +} { + proc $__cmd {args} [list return "return -code error \"Unimplemented API command $__cmd\""] +} +unset __cmd + +################################################################ diff --git a/tcllib/modules/doctools/changelog.man b/tcllib/modules/doctools/changelog.man new file mode 100644 index 0000000..ff0e903 --- /dev/null +++ b/tcllib/modules/doctools/changelog.man @@ -0,0 +1,87 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools::changelog n 1.1] +[keywords changelog] +[keywords doctools] +[keywords emacs] +[copyright {2003-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {Processing text in Emacs ChangeLog format}] +[category {Documentation tools}] +[require Tcl 8.2] +[require textutil] +[require doctools::changelog [opt 1.1]] +[description] + +This package provides Tcl commands for the processing and reformatting +of text in the [file ChangeLog] format generated by [syscmd emacs]. + +[section API] + +[list_begin definitions] + +[call [cmd ::doctools::changelog::scan] [arg text]] + +The command takes the [arg text] and parses it under the assumption +that it contains a ChangeLog as generated by [syscmd emacs]. It +returns a data structure describing the contents of this ChangeLog. + +[para] + +This data structure is a list where each element describes one entry +in the ChangeLog. Each element/entry is then a list of three elements +describing the date of the entry, its author, and the comments made, +in this order. The last item in each element/entry, the comments, is a +list of sections. Each section is described by a list containing two +elements, a list of file names, and a string containing the true +comment associated with the files of the section. + +[para] +[example { + { + { + date + author + { + { + {file ...} + commenttext + } + ... + } + } + {...} + } +}] + +[call [cmd ::doctools::changelog::flatten] [arg entries]] + +This command converts a list of entries as generated by +[cmd change::scan] above into a simpler list of plain +text blocks each containing all the information of a +single entry. + +[call [cmd ::doctools::changelog::toDoctools] [arg title] [arg module] [arg version] [arg entries]] + +This command converts the pre-parsed ChangeLog [arg entries] as +generated by the command [cmd ::doctools::changelog::scan] into a +document in [term doctools] format and returns it as the result of the +command. + +[para] + +The other three arguments supply the information for the header of +that document which is not available from the changelog itself. + +[call [cmd ::doctools::changelog::merge] [arg entries]...] + +Each argument of the command is assumed to be a pre-parsed Changelog +as generated by the command [cmd ::doctools::changelog::scan]. This +command merges all of them into a single structure, and collapses +multiple entries for the same date and author into a single entry. The +new structure is returned as the result of the command. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/changelog.tcl b/tcllib/modules/doctools/changelog.tcl new file mode 100644 index 0000000..d0b711b --- /dev/null +++ b/tcllib/modules/doctools/changelog.tcl @@ -0,0 +1,281 @@ +# changelog.tcl -- +# +# Handling of ChangeLog's. +# +# Copyright (c) 2003-2008 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# RCS: @(#) $Id: changelog.tcl,v 1.8 2008/07/08 23:03:58 andreas_kupries Exp $ + + +# FUTURE -- Expand pre-parsed log (nested lists) into flat structures +# FUTURE -- => date/author/file/cref + cref/text +# FUTURE -- I.e. relational/tabular structure, useable in table displays, +# FUTURE -- sort by date, author, file to see aggregated changes +# FUTURE -- => Connectivity to 'struct::matrix', Reports! + + +package require Tcl 8.2 +package require textutil + +namespace eval ::doctools {} +namespace eval ::doctools::changelog { + namespace export scan flatten merge toDoctools +} + +proc ::doctools::changelog::flatten {entries} { + # Reformat the entries into a simpler structure. + + set result {} + foreach entry $entries { + foreach {date user sections} $entry break + set f {} + set t {} + foreach sec $sections { + foreach {files text} $sec break + foreach file $files { lappend f $file } + append t \n $text + } + + set t [textutil::adjust::indent [textutil::adjust $t] " "] + lappend result \ + "$date $user\n [join $f ", "]:\n$t" + } + + return $result +} + +# ::doctools::changelog::scan -- +# +# Scan a ChangeLog generated by 'emacs' and extract the relevant information. +# +# Result +# List of entries. Each entry is a list of three elements. These +# are date, author, and commentary. The commentary is a list of +# sections. Each section is a list of two elements, a list of +# files, and the associated text. + +proc ::doctools::changelog::scan {text} { + set text [split $text \n] + set n [llength $text] + + set entries [list] + set clist [list] + set files [list] + set comment "" + set first 1 + + for {set i 0} {$i < $n} {incr i} { + set line [lindex $text $i] + + if {[regexp "^\[^ \t\]" $line]} { + # No whitespace at the front, start a new entry + + closeEntry + + # For the upcoming entry. Quick extraction first, string + # based in case of failure. + + if {[catch { + set date [string trim [lindex $line 0]] + set author [string trim [lrange $line 1 end]] + }]} { + set pos [string first " " $line] + set date [string trim [string range $line 0 $pos]] + set author [string trim [string range $line $pos end]] + } + continue + } + + # Inside of an entry. + + set line [string trim $line] + + if {[string length $line] == 0} { + # Next comment section + closeSection + continue + } + + # Line is not empty. Split into file and comment parts, + # remember the data. + + if {[string first "* " $line] == 0} { + if {[regexp {^\* (.*):[ ]} $line full fname]} { + set line [string range $line [string length $full] end] + } elseif {[regexp {^\* (.*):$} $line full fname]} { + set line "" + } else { + # There is no filename + set fname "" + set line [string range $line 2 end] ; # Get rid of "* ". + } + + set detail "" + while {[string first "(" $fname] >= 0} { + if {[regexp {\([^)]*\)} $fname detailx]} { + regsub {\([^)]*\)} $fname {} fnameNew + } elseif {[regexp {\([^)]*} $fname detailx]} { + regsub {\([^)]*} $fname {} fnameNew + } else { + break + } + append detail " " $detailx + set fname [string trim $fnameNew] + } + if {$detail != {}} {set line "$detail $line"} + if {$fname != {}} {lappend files $fname} + } + + append comment $line\n + } + + closeEntry + return $entries +} + + +proc ::doctools::changelog::closeSection {} { + upvar 1 clist clist comment comment files files + + if { + ([string length $comment] > 0) || + ([llength $files] > 0) + } { + lappend clist [list $files [string trim $comment]] + set files [list] + set comment "" + } + return +} + +proc ::doctools::changelog::closeEntry {} { + upvar 1 clist clist comment comment files files first first \ + date date author author entries entries + + if {!$first} { + closeSection + lappend entries [list $date $author $clist] + } + set first 0 + set clist [list] + set files [list] + set comment "" + return +} + +# ::doctools::changelog::merge -- +# +# Merge several preprocessed changelogs (see scan) into one structure. + + +proc ::doctools::changelog::merge {args} { + + if {[llength $args] == 0} {return {}} + if {[llength $args] == 1} {return [lindex $args 0]} + + set res [list] + array set tmp {} + + # Merge up ... + + foreach entries $args { + foreach e $entries { + foreach {date author comments} $e break + if {![info exists tmp($date,$author)]} { + lappend res [list $date $author] + set tmp($date,$author) $comments + } else { + foreach section $comments { + lappend tmp($date,$author) $section + } + } + } + } + + # ... And construct the final result + + set args $res + set res [list] + foreach key [lsort -decreasing $args] { + foreach {date author} $key break + lappend res [list $date $author $tmp($date,$author)] + } + return $res +} + + +# ::doctools::changelog::toDoctools -- +# +# Convert a preprocessed changelog log (see scan) into a doctools page. +# +# Arguments: +# evar, cvar, fvar: Name of the variables containing the preprocessed log. +# +# Results: +# A string containing a properly formatted ChangeLog. +# + +proc ::doctools::changelog::q {text} {return "\[$text\]"} + +proc ::doctools::changelog::toDoctools {title module version entries} { + + set linebuffer [list] + lappend linebuffer [q "manpage_begin [list ${title}-changelog n $version]"] + lappend linebuffer [q "titledesc [list "$title ChangeLog"]"] + lappend linebuffer [q "moddesc [list $module]"] + lappend linebuffer [q description] + lappend linebuffer [q "list_begin definitions compact"] + + foreach entry $entries { + foreach {date author commentary} $entry break + + lappend linebuffer [q "lst_item \"[q "emph [list $date]"] -- [string map {{"} {\"} {\"} {\\\"}} $author]\""] + + if {[llength $commentary] > 0} { + lappend linebuffer [q nl] + } + + foreach section $commentary { + foreach {files text} $section break + if {$text != {}} { + set text [string map {[ [lb] ] [rb]} [textutil::adjust $text]] + } + + if {[llength $files] > 0} { + lappend linebuffer [q "list_begin definitions"] + + foreach f $files { + lappend linebuffer [q "lst_item [q "file [list $f]"]"] + } + if {$text != {}} { + lappend linebuffer "" + lappend linebuffer $text + lappend linebuffer "" + } + + lappend linebuffer [q list_end] + } elseif {$text != {}} { + # No files + lappend linebuffer [q "list_begin bullet"] + lappend linebuffer [q bullet] + lappend linebuffer "" + lappend linebuffer $text + lappend linebuffer "" + lappend linebuffer [q list_end] + } + } + lappend linebuffer [q nl] + } + + lappend linebuffer [q list_end] + lappend linebuffer [q manpage_end] + return [join $linebuffer \n] +} + +#------------------------------------ +# Module initialization + +package provide doctools::changelog 1.1 diff --git a/tcllib/modules/doctools/checker.tcl b/tcllib/modules/doctools/checker.tcl new file mode 100644 index 0000000..d63942d --- /dev/null +++ b/tcllib/modules/doctools/checker.tcl @@ -0,0 +1,734 @@ +# -*- tcl -*- +# checker.tcl +# +# Code used inside of a checker interpreter to ensure correct usage of +# doctools formatting commands. +# +# Copyright (c) 2003-2014 Andreas Kupries <andreas_kupries@sourceforge.net> + +# L10N + +package require msgcat + +proc ::msgcat::mcunknown {locale code} { + return "unknown error code \"$code\" (for locale $locale)" +} + +if {0} { + puts stderr "Locale [::msgcat::mcpreferences]" + foreach path [dt_search] { + puts stderr "Catalogs: [::msgcat::mcload $path] - $path" + } +} else { + foreach path [dt_search] { + ::msgcat::mcload $path + } +} + +# State, and checker commands. +# ------------------------------------------------------------- +# +# Note that the code below assumes that a command XXX provided by the +# formatter engine is accessible under the name 'fmt_XXX'. +# +# ------------------------------------------------------------- + +global state lstctx lstitem + +# --------------+-----------------------+---------------------- +# state | allowed commands | new state (if any) +# --------------+-----------------------+---------------------- +# all except | arg cmd opt comment | +# for "done" | syscmd method option | +# | widget fun type class | +# | package var file uri | +# | strong emph namespace | +# --------------+-----------------------+---------------------- +# manpage_begin | manpage_begin | header +# --------------+-----------------------+---------------------- +# header | moddesc titledesc | header +# | copyright keywords | +# | require see_also category | +# +-----------------------+----------- +# | description | body +# --------------+-----------------------+---------------------- +# body | section para list_end | body +# | list_begin lst_item | +# | call bullet usage nl | +# | example see_also | +# | keywords sectref enum | +# | arg_def cmd_def | +# | opt_def tkoption_def | +# | subsection category | +# +-----------------------+----------- +# | example_begin | example +# +-----------------------+----------- +# | manpage_end | done +# --------------+-----------------------+---------------------- +# example | example_end | body +# --------------+-----------------------+---------------------- +# done | | +# --------------+-----------------------+---------------------- +# +# Additional checks +# --------------------------------------+---------------------- +# list_begin/list_end | Are allowed to nest. +# --------------------------------------+---------------------- +# section | Not allowed in list context +# +# arg_def | Only in 'argument list'. +# cmd_def | Only in 'command list'. +# nl para | Only in list item context. +# opt_def | Only in 'option list'. +# tkoption_def | Only in 'tkoption list'. +# def/call | Only in 'definition list'. +# enum | Only in 'enum list'. +# item/bullet | Only in 'bullet list'. +# --------------------------------------+---------------------- + +# ------------------------------------------------------------- +# Helpers +proc Error {code {text {}}} { + global state lstctx lstitem + + # Problematic command with all arguments (we strip the "ck_" prefix!) + # -*- future -*- count lines of input, maintain history buffer, use + # -*- future -*- that to provide some context here. + + set cmd [lindex [info level 1] 0] + set args [lrange [info level 1] 1 end] + if {$args != {}} {append cmd " [join $args]"} + + # Use a message catalog to map the error code into a legible message. + set msg [::msgcat::mc $code] + + if {$text != {}} { + set msg [string map [list @ $text] $msg] + } + dt_error "Manpage error ($code), \"$cmd\" : ${msg}." + return +} +proc Warn {code args} { + global pass + if {$pass > 1} return + # Warnings only in the first pass! + set msg [::msgcat::mc $code] + foreach {off line col} [dt_where] break + set msg [eval [linsert $args 0 format $msg]] + set msg "In macro at line $line, column $col of file [dt_file]:\n$msg" + set msg [split $msg \n] + set prefix "DocTools Warning ($code): " + dt_warning "$prefix[join $msg "\n$prefix"]" + return +} +proc WarnX {code args} { + # Warnings only in the first pass! + set msg [::msgcat::mc $code] + foreach {off line col} [dt_where] break + set msg [eval [linsert $args 0 format $msg]] + set msg "In macro at line $line, column $col of file [dt_file]:\n$msg" + set msg [split $msg \n] + set prefix "DocTools Warning ($code): " + dt_warning "$prefix[join $msg "\n$prefix"]" + return +} + +proc Is {s} {global state ; return [string equal $state $s]} +proc IsNot {s} {global state ; return [expr {![string equal $state $s]}]} +proc Go {s} {Log " >>\[$s\]" ; global state ; set state $s; return} +proc LPush {l} { + global lstctx lstitem + set lstctx [linsert $lstctx 0 $l $lstitem] + return +} +proc LPop {} { + global lstctx lstitem + set lstitem [lindex $lstctx 1] + set lstctx [lrange $lstctx 2 end] + return +} +proc LSItem {} {global lstitem ; set lstitem 1} +proc LIs {l} {global lstctx ; string equal $l [lindex $lstctx 0]} +proc LItem {} {global lstitem ; return $lstitem} +proc LNest {} { + global lstctx + expr {[llength $lstctx] / 2} +} +proc LOpen {} { + global lstctx + expr {$lstctx != {}} +} +global lmap ldmap +array set lmap { + bullet itemized item itemized + arg arguments args arguments + opt options opts options + cmd commands cmds commands + enum enumerated tkoption tkoptions +} +array set ldmap { + bullet . arg . cmd . tkoption . opt . +} +proc LMap {what} { + global lmap ldmap + if {![info exists lmap($what)]} { + return $what + } + if {[dt_deprecated] && [info exists ldmap($what)]} { + Warn depr_ltype $what $lmap($what) + } + return $lmap($what) +} +proc LValid {what} { + switch -exact -- $what { + arguments - + commands - + definitions - + enumerated - + itemized - + options - + tkoptions {return 1} + default {return 0} + } +} + +proc State {} {global state ; return $state} +proc Enter {cmd} {Log "\[[State]\] $cmd"} + +#proc Log* {text} {puts -nonewline $text} +#proc Log {text} {puts $text} +proc Log* {text} {} +proc Log {text} {} + + +# ------------------------------------------------------------- +# Framing +proc ck_initialize {p} { + global state ; set state manpage_begin + global lstctx ; set lstctx [list] + global lstitem ; set lstitem 0 + global sect + if {$p == 1} { + catch {unset sect} ; set sect() . ; unset sect() + catch {unset sectt} ; set sectt() . ; unset sectt() + } + global pass ; set pass $p + global countersection ; set countersection 0 + global countersubsection ; set countersubsection 0 + return +} +proc ck_complete {} { + if {[Is done]} { + if {![LOpen]} { + return + } else { + Error end/open/list + } + } elseif {[Is example]} { + Error end/open/example + } else { + Error end/open/mp + } + return +} +# ------------------------------------------------------------- +# Plain text +proc plain_text {text} { + # Only in body, not between list_begin and first item. + # Ignore everything which is only whitespace ... + + set redux [string map [list " " "" "\t" "" "\n" ""] $text] + if {$redux == {}} {return [fmt_plain_text $text]} + if {[IsNot body] && [IsNot example]} {Error body} + if {[LOpen] && ![LItem]} {Error nolisttxt} + return [fmt_plain_text $text] +} + +# ------------------------------------------------------------- +# Variable handling ... + +proc vset {var args} { + switch -exact -- [llength $args] { + 0 { + # Retrieve contents of variable VAR + upvar #0 __$var data + if {![info exists data]} { + return -code error "can't read doc variable \"$var\": not set" + } + return $data + } + 1 { + # Set contents of variable VAR + global __$var + set __$var [lindex $args 0] + return "" ; # Empty string ! Nothing for output. + } + default { + return -code error "wrong#args: set var ?value?" + } + } +} + +# ------------------------------------------------------------- +# Formatting commands +proc manpage_begin {title section version} { + Enter manpage_begin + if {[IsNot manpage_begin]} {Error mpbegin} + if {[string match {* *} $title]} {Error mptitle} + Go header + fmt_manpage_begin $title $section $version +} +proc moddesc {desc} { + Enter moddesc + if {[IsNot header]} {Error hdrcmd} + fmt_moddesc $desc +} +proc titledesc {desc} { + Enter titledesc + if {[IsNot header]} {Error hdrcmd} + fmt_titledesc $desc +} +proc copyright {text} { + Enter copyright + if {[IsNot header]} {Error hdrcmd} + fmt_copyright $text +} +proc manpage_end {} { + Enter manpage_end + if {[IsNot body]} {Error bodycmd} + Go done + fmt_manpage_end +} +proc require {pkg {version {}}} { + Enter require + if {[IsNot header]} {Error hdrcmd} + fmt_require $pkg $version +} +proc description {} { + Enter description + if {[IsNot header]} {Error hdrcmd} + Go body + fmt_description [Sectdef section Description description] +} + +# Storage for (sub)section ids to enable checking for ambigous +# identificaton. The ids on this level are logical names. The backends +# are given physical names (via counters). +global sect ; # Map of logical -> physical ids +global sectt ; # Map of logical -> section title +global sectci ; # Current section (id) +global sectct ; # Current section (title) +global countersection +global countersubsection + +proc section {title {id {}}} { + global sect + + Enter section + if {[IsNot body]} {Error bodycmd} + if {[LOpen]} {Error nolistcmd} + + fmt_section $title [Sectdef section $title $id] +} +proc subsection {title {id {}}} { + global sect + + Enter subsection + if {[IsNot body]} {Error bodycmd} + if {[LOpen]} {Error nolistcmd} + + fmt_subsection $title [Sectdef subsection $title $id] +} + +proc Sectdef {type title id} { + global sect sectt sectci sectct countersection countersubsection pass + + # Compute a (sub)section id from the name (= section label/title) + # if the user did not provide their own id. + if {![string length $id]} { + if {$type == "section"} { + set id [list $title] + } elseif {$type == "subsection"} { + set id [list $sectci $title] + } else { + error INTERNAL + } + } + # Check if the id is unambigous. Issue a warning if not. For + # sections we remember the now-current name and id for use by + # subsections. + if {$pass == 1} { + if {[info exists sect($id)]} { + set msg $title + if {$type == "subsection"} { + append msg " (in " $sectct ")" + } + Warn sectambig $msg + } + set sect($id) $type[incr counter$type] + } + set sectt($id) $title + if {$type == "section"} { + set sectci $id + set sectct $title + } + return $sect($id) +} + +proc para {} { + Enter para + if {[IsNot body]} {Error bodycmd} + if {[LOpen]} { + if {![LItem]} {Error nolisthdr} + fmt_nl + } else { + fmt_para + } +} +proc list_begin {what {hint {}}} { + Enter "list_begin $what $hint" + if {[IsNot body]} {Error bodycmd} + if {[LOpen] && ![LItem]} {Error nolisthdr} + set what [LMap $what] + if {![LValid $what]} {Error invalidlist $what} + set res [fmt_list_begin $what $hint] + LPush $what + return $res +} +proc list_end {} { + Enter list_end + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + LPop + fmt_list_end +} + +# Deprecated command, and its common misspellings. Canon is 'def'. +proc lst_item {{text {}}} { + if {[dt_deprecated]} {Warn depr_lstitem "\[lst_item\]"} + def $text +} +proc list_item {{text {}}} { + if {[dt_deprecated]} {Warn depr_lstitem "\[list_item\]"} + def $text +} +proc listitem {{text {}}} { + if {[dt_deprecated]} {Warn depr_lstitem "\[listitem\]"} + def $text +} +proc lstitem {{text {}}} { + if {[dt_deprecated]} {Warn depr_lstitem "\[lstitem\]"} + def $text +} +proc def {{text {}}} { + Enter def + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs definitions]} {Error deflist} + LSItem + fmt_lst_item $text +} +proc arg_def {type name {mode {}}} { + Enter arg_def + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs arguments]} {Error arg_list} + LSItem + fmt_arg_def $type $name $mode +} +proc cmd_def {command} { + Enter cmd_def + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs commands]} {Error cmd_list} + LSItem + fmt_cmd_def $command +} +proc opt_def {name {arg {}}} { + Enter opt_def + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs options]} {Error opt_list} + LSItem + fmt_opt_def $name $arg +} +proc tkoption_def {name dbname dbclass} { + Enter tkoption_def + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs tkoptions]} {Error tkoption_list} + LSItem + fmt_tkoption_def $name $dbname $dbclass +} +proc call {cmd args} { + Enter call + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs definitions]} {Error deflist} + LSItem + eval [linsert $args 0 fmt_call $cmd] +} +# Deprecated. Use 'item' +proc bullet {} { + if {[dt_deprecated]} {Warn depr_bullet "\[bullet\]"} + item +} +proc item {} { + Enter item + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs itemized]} {Error bulletlist} + LSItem + fmt_bullet +} +proc enum {} { + Enter enum + if {[IsNot body]} {Error bodycmd} + if {![LOpen]} {Error listcmd} + if {![LIs enumerated]} {Error enumlist} + LSItem + fmt_enum +} +proc example {code} { + Enter example + return [example_begin][plain_text ${code}][example_end] +} +proc example_begin {} { + Enter example_begin + if {[IsNot body]} {Error bodycmd} + if {[LOpen] && ![LItem]} {Error nolisthdr} + Go example + fmt_example_begin +} +proc example_end {} { + Enter example_end + if {[IsNot example]} {Error examplecmd} + Go body + fmt_example_end +} +proc see_also {args} { + Enter see_also + if {[Is done]} {Error nodonecmd} + # if {[IsNot body]} {Error bodycmd} + # if {[LOpen]} {Error nolistcmd} + eval [linsert $args 0 fmt_see_also] +} +proc keywords {args} { + Enter keywords + if {[Is done]} {Error nodonecmd} + # if {[IsNot body]} {Error bodycmd} + # if {[LOpen]} {Error nolistcmd} + eval [linsert $args 0 fmt_keywords] +} +proc category {text} { + Enter category + if {[Is done]} {Error nodonecmd} + # if {[IsNot body]} {Error bodycmd} + # if {[LOpen]} {Error nolistcmd} + fmt_category $text +} +# nl - Deprecated +proc nl {} { + if {[dt_deprecated]} {Warn depr_nl "\[nl\]"} + para +} +proc emph {text} { + if {[Is done]} {Error nodonecmd} + fmt_emph $text +} +# strong - Deprecated +proc strong {text} { + if {[dt_deprecated]} {Warn depr_strong "\[strong\]"} + emph $text +} +proc arg {text} { + if {[Is done]} {Error nodonecmd} + fmt_arg $text +} +proc cmd {text} { + if {[Is done]} {Error nodonecmd} + fmt_cmd $text +} +proc opt {text} { + if {[Is done]} {Error nodonecmd} + fmt_opt $text +} +proc comment {text} { + if {[Is done]} {Error nodonecmd} + return ; #fmt_comment $text +} +proc sectref-external {title} { + if {[IsNot body]} {Error bodycmd} + if {[LOpen] && ![LItem]} {Error nolisthdr} + + fmt_sectref $title {} +} +proc sectref {id {title {}}} { + if {[IsNot body]} {Error bodycmd} + if {[LOpen] && ![LItem]} {Error nolisthdr} + + # syntax: id ?title? + # Check existence of referenced (sub)section. + global sect sectt sectci pass + + # Two things are done. + # (1) Check that the id is known and determine the full id. + # (2) Determine physical id, and, if needed, the title. + + if {[info exists sect($id)]} { + # Logical id, likely user-supplied, exists. + set pid $sect($id) + set fid $id + } else { + # Doesn't exist directly. Assume that the id is derived from a + # (sub)section title, search various combinations. + + set fid [list $id] + if {[info exists sect($fid)]} { + # Id was wrapped section title. + set pid $sect($fid) + } else { + # See if the id is the tail end of a subsection id. + set ic [array names sect [list * $id]] + if {![llength $ic]} { + # No, it is not. Give up. + if {$pass > 1 } { WarnX missingsect $id } + set pid {} + } elseif {[llength $ic] == 1} { + # Yes, and it is unique. Take it. + set fid [lindex $ic 0] + set pid $sect($fid) + } else { + # Yes, however it is ambigous. Issue warning, then + # select one of the possibilities. Prefer to keep the + # reference within the currenc section, otherwise, + # i.e. if we cannot do that, choose randomly. + if {$pass == 2} { WarnX sectambig $id } + set fid [list $sectci $id] + if {![info exists sect($fid)]} { + # No candidate in current section, so chose + # randomly. + set fid [lindex $ic 0] + } + set pid $sect($fid) + } + } + } + + # If we have no text take the section title as text, if we + # can. Last fallback for thext is the id. + if {$title == {}} { + if {$pid != {}} { + set title $sectt($fid) + } else { + set title $id + } + } + + # Hand both chosen title and physical id to the backend for + # actual formatting. + fmt_sectref $title $pid +} +proc syscmd {text} { + if {[Is done]} {Error nodonecmd} + fmt_syscmd $text +} +proc method {text} { + if {[Is done]} {Error nodonecmd} + fmt_method $text +} +proc option {text} { + if {[Is done]} {Error nodonecmd} + fmt_option $text +} +proc widget {text} { + if {[Is done]} {Error nodonecmd} + fmt_widget $text +} +proc fun {text} { + if {[Is done]} {Error nodonecmd} + fmt_fun $text +} +proc type {text} { + if {[Is done]} {Error nodonecmd} + fmt_type $text +} +proc package {text} { + if {[Is done]} {Error nodonecmd} + fmt_package $text +} +proc class {text} { + if {[Is done]} {Error nodonecmd} + fmt_class $text +} +proc var {text} { + if {[Is done]} {Error nodonecmd} + fmt_var $text +} +proc file {text} { + if {[Is done]} {Error nodonecmd} + fmt_file $text +} + +# Special case: We must not overwrite the builtin namespace command, +# as it is required by the package "msgcat". +proc _namespace {text} { + if {[Is done]} {Error nodonecmd} + fmt_namespace $text +} +proc uri {text {label {}}} { + if {[Is done]} {Error nodonecmd} + # The label argument is left out when undefined so that we can + # control old formatters as well, if the input is not using uri + # labels. + + if {$label == {}} { + fmt_uri $text + } else { + fmt_uri $text $label + } +} +proc image {text {label {}}} { + if {[Is done]} {Error nodonecmd} + # The label argument is left out when undefined so that we can + # control old formatters as well, if the input is not using uri + # labels. + + if {$label == {}} { + fmt_image $text + } else { + fmt_image $text $label + } +} +proc manpage {text} { + if {[Is done]} {Error nodonecmd} + # The label argument is left out when undefined so that we can + # control old formatters as well, if the input is not using uri + # labels. + + fmt_term $text + #fmt_manpage $text +} +proc usage {args} { + if {[Is done]} {Error nodonecmd} + eval fmt_usage $args +} +proc const {text} { + if {[Is done]} {Error nodonecmd} + fmt_const $text +} +proc term {text} { + if {[Is done]} {Error nodonecmd} + fmt_term $text +} + +proc mdash {} { + if {[Is done]} {Error nodonecmd} + fmt_mdash $text +} +proc ndash {} { + if {[Is done]} {Error nodonecmd} + fmt_ndash $text +} + +# ------------------------------------------------------------- diff --git a/tcllib/modules/doctools/checker_idx.tcl b/tcllib/modules/doctools/checker_idx.tcl new file mode 100644 index 0000000..31b3104 --- /dev/null +++ b/tcllib/modules/doctools/checker_idx.tcl @@ -0,0 +1,207 @@ +# -*- tcl -*- +# checker_idx.tcl +# +# Code used inside of a checker interpreter to ensure correct usage of +# docidx formatting commands. +# +# Copyright (c) 2003-2009 Andreas Kupries <andreas_kupries@sourceforge.net> + +# L10N + +package require msgcat + +proc ::msgcat::mcunknown {locale code} { + return "unknown error code \"$code\" (for locale $locale)" +} + +if {0} { + puts stderr "Locale [::msgcat::mcpreferences]" + foreach path [dt_search] { + puts stderr "Catalogs: [::msgcat::mcload $path] - $path" + } +} else { + foreach path [dt_search] { + ::msgcat::mcload $path + } +} + +# State, and checker commands. +# ------------------------------------------------------------- +# +# Note that the code below assumes that a command XXX provided by the +# formatter engine is accessible under the name 'fmt_XXX'. +# +# ------------------------------------------------------------- + +global state + +# State machine ... State centered +# --------------+-----------------------+---------------------- +# state | allowed commands | new state (if any) +# --------------+-----------------------+---------------------- +# all except | include vset | +# ==============+=======================+====================== +# idx_begin | idx_begin | -> contents +# --------------+-----------------------+---------------------- +# contents | key | -> ref_series +# --------------+-----------------------+---------------------- +# ref_series | manpage | -> refkey_series +# | url | +# --------------+-----------------------+---------------------- +# refkey_series | manpage | -> refkey_series +# | url | +# +-----------------------+----------- +# | key | -> ref_series +# +-----------------------+----------- +# | idx_end | -> done +# --------------+-----------------------+---------------------- + +# State machine, as above ... Command centered +# --------------+-----------------------+---------------------- +# state | allowed commands | new state (if any) +# --------------+-----------------------+---------------------- +# all except | include vset | +# ==============+=======================+====================== +# idx_begin | idx_begin | -> contents +# --------------+-----------------------+---------------------- +# contents | key | -> ref_series +# refkey_series | | +# --------------+-----------------------+---------------------- +# ref_series | manpage | -> refkey_series +# refkey_series | | +# --------------+-----------------------+---------------------- +# ref_series | url | -> refkey_series +# refkey_series | | +# --------------+-----------------------+---------------------- +# refkey_series | idx_end | -> done +# --------------+-----------------------+---------------------- + +# ------------------------------------------------------------- +# Helpers +proc Error {code {text {}}} { + global state + + # Problematic command with all arguments (we strip the "ck_" prefix!) + # -*- future -*- count lines of input, maintain history buffer, use + # -*- future -*- that to provide some context here. + + set cmd [lindex [info level 1] 0] + set args [lrange [info level 1] 1 end] + if {$args != {}} {append cmd " [join $args]"} + + # Use a message catalog to map the error code into a legible message. + set msg [::msgcat::mc $code] + + if {$text != {}} { + set msg [string map [list @ $text] $msg] + } + + dt_error "IDX error ($code), \"$cmd\" : ${msg}." + return +} +proc Warn {code text} { + set msg [::msgcat::mc $code] + dt_warning "IDX warning ($code): [join [split [format $msg $text] \n] "\nIDX warning ($code): "]" + return +} + +proc Is {s} {global state ; return [string equal $state $s]} +proc IsNot {s} {global state ; return [expr {![string equal $state $s]}]} +proc Go {s} {Log " >>\[$s\]" ; global state ; set state $s; return} +proc Push {s} {Log " //\[$s\]" ; global state stack ; lappend stack $state ; set state $s; return} +proc Pop {} {Log* " pop" ; global state stack ; set state [lindex $stack end] ; set stack [lrange $stack 0 end-1] ; Log " \\\\\[$state\]" ; return} +proc State {} {global state ; return $state} + +proc Enter {cmd} {Log* "\[[State]\] $cmd"} + +#proc Log* {text} {puts -nonewline $text} +#proc Log {text} {puts $text} +proc Log* {text} {} +proc Log {text} {} + +# ------------------------------------------------------------- +# Framing +proc ck_initialize {} { + global state ; set state idx_begin + global stack ; set stack [list] +} +proc ck_complete {} { + if {[Is done]} { + return + } else { + Error end/open/idx + } + return +} +# ------------------------------------------------------------- +# Plain text +proc plain_text {text} { + # Ignore everything which is only whitespace ... + # Beyond that plain text is not allowed. + + set redux [string map [list " " "" "\t" "" "\n" ""] $text] + if {$redux == {}} {return [fmt_plain_text $text]} + Error idx/plaintext + return "" +} + +# ------------------------------------------------------------- +# Variable handling ... + +proc vset {var args} { + switch -exact -- [llength $args] { + 0 { + # Retrieve contents of variable VAR + upvar #0 __$var data + return $data + } + 1 { + # Set contents of variable VAR + global __$var + set __$var [lindex $args 0] + return "" ; # Empty string ! Nothing for output. + } + default { + return -code error "wrong#args: set var ?value?" + } + } +} + +# ------------------------------------------------------------- +# Formatting commands +proc index_begin {label title} { + Enter index_begin + if {[IsNot idx_begin]} {Error idx/begincmd} + Go contents + fmt_index_begin $label $title +} +proc index_end {} { + Enter index_end + if {[IsNot refkey_series] && [IsNot contents]} {Error idx/endcmd} + Go done + fmt_index_end +} +proc key {text} { + Enter key + if {[IsNot contents] && [IsNot refkey_series]} {Error idx/keycmd} + Go ref_series + fmt_key $text +} +proc manpage {file label} { + Enter manpage + if {[IsNot ref_series] && [IsNot refkey_series]} {Error idx/manpagecmd} + Go refkey_series + fmt_manpage $file $label +} +proc url {url label} { + Enter url + if {[IsNot ref_series] && [IsNot refkey_series]} {Error idx/urlcmd} + Go refkey_series + fmt_url $url $label +} +proc comment {text} { + if {[Is done]} {Error idx/nodonecmd} + return ; #fmt_comment $text +} + +# ------------------------------------------------------------- diff --git a/tcllib/modules/doctools/checker_toc.tcl b/tcllib/modules/doctools/checker_toc.tcl new file mode 100644 index 0000000..7f305e4 --- /dev/null +++ b/tcllib/modules/doctools/checker_toc.tcl @@ -0,0 +1,214 @@ +# -*- tcl -*- +# checker_toc.tcl +# +# Code used inside of a checker interpreter to ensure correct usage of +# doctoc formatting commands. +# +# Copyright (c) 2003-2009 Andreas Kupries <andreas_kupries@sourceforge.net> + +# L10N + +package require msgcat + +proc ::msgcat::mcunknown {locale code} { + return "unknown error code \"$code\" (for locale $locale)" +} + +if {0} { + puts stderr "Locale [::msgcat::mcpreferences]" + foreach path [dt_search] { + puts stderr "Catalogs: [::msgcat::mcload $path] - $path" + } +} else { + foreach path [dt_search] { + ::msgcat::mcload $path + } +} + +# State, and checker commands. +# ------------------------------------------------------------- +# +# Note that the code below assumes that a command XXX provided by the +# formatter engine is accessible under the name 'fmt_XXX'. +# +# ------------------------------------------------------------- + +global state + +# State machine ... State centered +# --------------+-----------------------+---------------------- +# state | allowed commands | new state (if any) +# --------------+-----------------------+---------------------- +# all except | include vset | +# ==============+=======================+====================== +# toc_begin | toc_begin | -> contents +# --------------+-----------------------+---------------------- +# contents | item | -> contents // +# +-----------------------+----------- +# | division_start | -> end, PUSH division +# +-----------------------+----------- +# | toc_end | -> done +# --------------+-----------------------+---------------------- +# division | item | -> division // +# +-----------------------+----------- +# | division_start | -> division, PUSH division +# +-----------------------+----------- +# | division_end | POP (-> division / -> end) +# --------------+-----------------------+---------------------- +# end | toc_end | -> done +# +-----------------------+----------- +# | division_start | PUSH division +# --------------+-----------------------+---------------------- + +# State machine, as above ... Command centered +# --------------+-----------------------+---------------------- +# state | allowed commands | new state (if any) +# --------------+-----------------------+---------------------- +# all except | include vset | +# ==============+=======================+====================== +# toc_begin | toc_begin | -> contents +# --------------+-----------------------+---------------------- +# contents | item | -> contents +# division | | -> division +# --------------+-----------------------+---------------------- +# contents | division_start | -> end, PUSH division +# division | | -> divison, PUSH division +# end | | PUSH division +# --------------+-----------------------+---------------------- +# division | division_end | POP (-> division / -> end) +# --------------+-----------------------+---------------------- +# contents | toc_end | -> done +# end | | -> done +# --------------+-----------------------+---------------------- + +# ------------------------------------------------------------- +# Helpers +proc Error {code {text {}}} { + global state + + # Problematic command with all arguments (we strip the "ck_" prefix!) + # -*- future -*- count lines of input, maintain history buffer, use + # -*- future -*- that to provide some context here. + + set cmd [lindex [info level 1] 0] + set args [lrange [info level 1] 1 end] + if {$args != {}} {append cmd " [join $args]"} + + # Use a message catalog to map the error code into a legible message. + set msg [::msgcat::mc $code] + + if {$text != {}} { + set msg [string map [list @ $text] $msg] + } + + dt_error "TOC error ($code), \"$cmd\" : ${msg}." + return +} +proc Warn {code text} { + set msg [::msgcat::mc $code] + dt_warning "TOC warning ($code): [join [split [format $msg $text] \n] "\nTOC warning ($code): "]" + return +} + +proc Is {s} {global state ; return [string equal $state $s]} +proc IsNot {s} {global state ; return [expr {![string equal $state $s]}]} +proc Go {s} {Log " >>\[$s\]" ; global state ; set state $s; return} +proc Push {s} {Log " //\[$s\]" ; global state stack ; lappend stack $state ; set state $s; return} +proc Pop {} {Log* " pop" ; global state stack ; set state [lindex $stack end] ; set stack [lrange $stack 0 end-1] ; Log " \\\\\[$state\]" ; return} +proc State {} {global state stack ; return "$stack || $state"} + +proc Enter {cmd} {Log* "\[[State]\] $cmd"} + +#proc Log* {text} {puts -nonewline $text} +#proc Log {text} {puts $text} +proc Log* {text} {} +proc Log {text} {} + +# ------------------------------------------------------------- +# Framing +proc ck_initialize {} { + global state ; set state toc_begin + global stack ; set stack [list] +} +proc ck_complete {} { + if {[Is done]} { + return + } else { + Error end/open/toc + } + return +} +# ------------------------------------------------------------- +# Plain text +proc plain_text {text} { + # Ignore everything which is only whitespace ... + # Beyond that plain text is not allowed. + + set redux [string map [list " " "" "\t" "" "\n" ""] $text] + if {$redux == {}} {return [fmt_plain_text $text]} + Error toc/plaintext + return "" +} + +# ------------------------------------------------------------- +# Variable handling ... + +proc vset {var args} { + switch -exact -- [llength $args] { + 0 { + # Retrieve contents of variable VAR + upvar #0 __$var data + return $data + } + 1 { + # Set contents of variable VAR + global __$var + set __$var [lindex $args 0] + return "" ; # Empty string ! Nothing for output. + } + default { + return -code error "wrong#args: set var ?value?" + } + } +} + +# ------------------------------------------------------------- +# Formatting commands +proc toc_begin {label title} { + Enter toc_begin + if {[IsNot toc_begin]} {Error toc/begincmd} + Go contents + fmt_toc_begin $label $title +} +proc toc_end {} { + Enter toc_end + if {[IsNot end] && [IsNot contents]} {Error toc/endcmd} + Go done + fmt_toc_end +} +proc division_start {title {symfile {}}} { + Enter division_start + if { + [IsNot contents] && [IsNot end] && [IsNot division] + } {Error toc/sectcmd} + if {[Is contents] || [Is end]} {Go end} else {Go division} + Push division + fmt_division_start $title $symfile +} +proc division_end {} { + Enter division_end + if {[IsNot division]} {Error toc/sectecmd [State]} + Pop + fmt_division_end +} +proc item {file label desc} { + Enter item + if {[IsNot contents] && [IsNot division]} { Error toc/itemcmd } + fmt_item $file $label $desc +} +proc comment {text} { + if {[Is done]} {Error toc/nodonecmd} + return ; #fmt_comment $text +} + +# ------------------------------------------------------------- diff --git a/tcllib/modules/doctools/cvs.man b/tcllib/modules/doctools/cvs.man new file mode 100644 index 0000000..33fc733 --- /dev/null +++ b/tcllib/modules/doctools/cvs.man @@ -0,0 +1,101 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools::cvs n 1] +[see_also {[uri}] +[see_also http://wiki.tcl.tk/log2changelog] +[keywords changelog] +[keywords cvs] +[keywords {cvs log}] +[keywords emacs] +[keywords log] +[copyright {2003-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {Processing text in 'cvs log' format}] +[category {Documentation tools}] +[require Tcl 8.2] +[require textutil] +[require doctools::cvs [opt 1]] +[description] + +This package provides Tcl commands for the processing and reformatting +text in the format generated by the [syscmd {cvs log}] command. + +[para] + +The commands [cmd ::doctools::cvs::scanLog] +and [cmd ::doctools::cvs::toChangeLog] are derived from code found on +the [uri http://wiki.tcl.tk {Tcl'ers Wiki}]. See the references at the +end of the page. + +[section API] + +[list_begin definitions] + +[call [cmd ::doctools::cvs::scanLog] [arg text] [arg evar] [arg cvar] [arg fvar]] + +The command takes the [arg text] and parses it under the assumption +that it contains a CVS log as generated by [syscmd {cvs log}]. The +resulting information is stored in the variables whose names were +specified via [arg evar], [arg cvar], and [arg fvar]. + +[para] + +Already existing information in the referenced variables is preserved, +allowing the caller to merge data from multiple logs into one +database. + +[list_begin arguments] +[arg_def varname evar in] + +Has to refer to a scalar variable. After the call this variable will +contain a list of all the entries found in the log file. An entry is +identified through the combination of date and author, and can be +split over multiple physical entries, one per touched file. + +[para] + +It should be noted that the entries are listed in the same order as +they were found in the [arg text]. This is not necessarily sorted by +date or author. + +[para] + +Each item in the list is a list containing two elements, the date of +the entry, and its author, in this order. The date is formatted as +[var year]/[var month]/[var day]. + +[arg_def varname cvar in] + +Has to refer to an array variable. Keys are strings containing the +date and author of log entries, in this order, separated by a comma. + +[para] + +The values are lists of comments made for the entry. + +[arg_def varname fvar in] + +Has to refer to an array variable. Keys are strings containing +date, author of a log entry, and a comment for that entry, in this +order, separated by commas. + +[para] + +The values are lists of the files the entry is touching. + +[list_end] +[para] + +[call [cmd ::doctools::cvs::toChangeLog] [arg evar] [arg cvar] [arg fvar]]] + +The three arguments for this command are the same as the last three +arguments of the command [cmd ::doctools::cvs::scanLog]. This command +however expects them to be filled with information about one or more +logs. It takes this information and converts it into a text in the +format of a ChangeLog as accepted and generated by [syscmd emacs]. The +constructed text is returned as the result of the command. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/cvs.tcl b/tcllib/modules/doctools/cvs.tcl new file mode 100644 index 0000000..567c20d --- /dev/null +++ b/tcllib/modules/doctools/cvs.tcl @@ -0,0 +1,136 @@ +# cvs.tcl -- +# +# Handling of various cvs output formats. +# +# Copyright (c) 2003-2008 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# RCS: @(#) $Id: cvs.tcl,v 1.10 2008/07/08 23:03:58 andreas_kupries Exp $ + +package require Tcl 8.2 +package require textutil + +namespace eval ::doctools {} +namespace eval ::doctools::cvs { + namespace export scanLog toChangeLog +} + +# ::doctools::cvs::scanLog -- +# +# Scan a log generated by 'cvs log' and extract the relevant information. +# +# Arguments: +# text The text to scan +# +# Results: +# None. +# +# Sideeffects: +# None. +# +# Notes: +# Original location of code: http://wiki.tcl.tk/3638 +# aka http://wiki.tcl.tk/log2changelog +# Original author unknown. +# Bugfix by TR / Torsten Reincke + +proc ::doctools::cvs::scanLog {text evar cvar fvar} { + + set text [split $text \n] + set n [llength $text] + + upvar 1 $evar entries ; #set entries [list] + upvar 1 $cvar comments ; #array set comments {} + upvar 1 $fvar files ; #array set files {} + + for {set i 0} {$i < $n} {incr i} { + set line [lindex $text $i] + switch -glob -- $line { + "*Working file:*" { + regexp {Working file: (.*)} $line -> filename + } + "date:*" { + scan $line "date: %s %s author: %s" date time author + set author [string trim $author ";"] + + # read the comment lines following date + set comment "" + incr i + set line [lindex $text $i] + # [TR]: use regexp here to see if log ends: + while {(![regexp "(-----*)|(=====*)" $line]) && ($i < $n)} { + append comment $line "\n" + incr i + set line [lindex $text $i] + } + + # Store this date/author/comment + lappend entries [list $date $author] + lappend comments($date,$author) $comment + lappend files($date,$author,$comment) $filename + } + } + } + + return +} + + +# ::doctools::cvs::toChangeLog -- + +# Convert a preprocessed cvs log (see scanLog) into a Changelog +# suitable for emacs. +# +# Arguments: +# evar, cvar, fvar: Name of the variables containing the preprocessed log. +# +# Results: +# A string containing a properly formatted ChangeLog. +# +# Sideeffects: +# None. +# +# Notes: +# Original location of code: http://wiki.tcl.tk/3638 +# aka http://wiki.tcl.tk/log2changelog +# Original author unknown. + +proc ::doctools::cvs::toChangeLog {evar cvar fvar} { + upvar 1 $evar entries $cvar comments $fvar files + + set linebuffer [list] + + foreach e [lsort -unique -decreasing $entries] { + + # print the date/author + foreach {date author} $e {break} + lappend linebuffer "$date $author" + lappend linebuffer "" + + # Find all the comments submitted this date/author + + set clist [lsort -unique $comments($date,$author)] + + foreach c $clist { + # Print all files for a given comment + foreach f [lsort -unique $files($date,$author,$c)] { + lappend linebuffer "\t* $f:" + } + + # Format and print the comment + + lappend linebuffer [textutil::indent [textutil::undent $c] "\t "] + lappend linebuffer "" + continue + } + } + + return [join $linebuffer \n] +} + +#------------------------------------ +# Module initialization + +package provide doctools::cvs 1 diff --git a/tcllib/modules/doctools/docidx.man b/tcllib/modules/doctools/docidx.man new file mode 100644 index 0000000..8cd5d0a --- /dev/null +++ b/tcllib/modules/doctools/docidx.man @@ -0,0 +1,405 @@ +[vset PACKAGE_VERSION 1.0.5] +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools::idx n [vset PACKAGE_VERSION]] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[see_also docidx_plugin_apiref] +[keywords conversion] +[keywords docidx] +[keywords documentation] +[keywords HTML] +[keywords index] +[keywords {keyword index}] +[keywords latex] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] +[keywords wiki] +[copyright {2003-2014 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx - Processing indices}] +[category {Documentation tools}] +[require Tcl 8.2] +[require doctools::idx [opt [vset PACKAGE_VERSION]]] +[description] + +This package provides a class for the creation of objects able to +process and convert text written in the [term docidx] markup language +into any output format X for which a [term {formatting engine}] is +available. + +[para] + +A reader interested in the markup language itself should start with +the [term {docidx language introduction}] and proceed from there to +the formal specifications, i.e. the [term {docidx language syntax}] +and the [term {docidx language command reference}]. + +[para] + +If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a [term {plugin writer}] then reading +and understanding the [term {docidx plugin API reference}] is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail. + +[section {PUBLIC API}] +[subsection {PACKAGE COMMANDS}] + +[list_begin definitions] + +[call [cmd ::doctools::idx::new] [arg objectName] [opt "[option -option] [arg value] ..."]] + +This command creates a new docidx object with an associated Tcl +command whose name is [arg objectName]. This [term object] command is +explained in full detail in the sections [sectref {OBJECT COMMAND}] +and [sectref {OBJECT METHODS}]. The object command will be created +under the current namespace if the [arg objectName] is not fully +qualified, and in the specified namespace otherwise. + +[para] + +The options and their values coming after the name of the object are +used to set the initial configuration of the object. + +[call [cmd ::doctools::idx::help]] + +This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text. + +[call [cmd ::doctools::idx::search] [arg path]] + +Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section [sectref {FORMAT MAPPING}] for more explanations. + +[para] + +This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. + +This command is the means to do so. When given a [arg path] to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the [arg path] added +last is later searched through first. + +[para] + +An error will be thrown if the [arg path] either does not exist, is +not a directory, or is not readable. + +[list_end] + +[subsection {OBJECT COMMAND}] + +All commands created by [cmd ::doctools::idx::new] have the following +general form and may be used to invoke various operations on their +docidx converter object. + +[list_begin definitions] + +[call [cmd objectName] [method method] [opt [arg "arg arg ..."]]] + +The method [method method] and its [arg arg]'uments determine the exact +behavior of the command. See section [sectref {OBJECT METHODS}] for +the detailed specifications. + +[list_end] + +[subsection {OBJECT METHODS}] + +[list_begin definitions] + +[call [arg objectName] [method configure]] + +The method returns a list of all known options and their current +values when called without any arguments. + +[call [arg objectName] [method configure] [arg option]] + +The method behaves like the method [method cget] when called with a +single argument and returns the value of the option specified by said +argument. + +[call [arg objectName] [method configure] [option -option] [arg value]...] + +The method reconfigures the specified [option option]s of the object, +setting them to the associated [arg value]s, when called with an even +number of arguments, at least two. + +[para] + +The legal options are described in the section +[sectref {OBJECT CONFIGURATION}]. + +[call [arg objectName] [method cget] [option -option]] + +This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for. + +[para] + +The legal configuration options are described in section +[sectref {OBJECT CONFIGURATION}]. + +[call [arg objectName] [method destroy]] + +This method destroys the object it is invoked for. + +[call [arg objectName] [method format] [arg text]] + +This method runs the [arg text] through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no [option -format] was configured for the object. + +[para] + +The method assumes that the [arg text] is in [term docidx] format as +specified in the companion document [term docidx_fmt]. Errors will be +thrown otherwise. + +[call [arg objectName] [method map] [arg symbolic] [arg actual]] + +This methods add one entry to the per-object mapping from +[arg symbolic] filenames to the [arg actual] uris. + +The object just stores this mapping and makes it available to the +configured formatting engine through the command [cmd dt_fmap]. + +This command is described in more detail in the +[term {docidx plugin API reference}] which specifies the interaction +between the objects created by this package and index formatting +engines. + +[call [arg objectName] [method parameters]] + +This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format. + +[call [arg objectName] [method search] [arg path]] + +This method extends the per-object list of paths searched for index +formatting engines. See also the command [cmd ::doctools::idx::search] +on how to extend the per-package list of paths. Note that the path +entered last will be searched first. + +For more details see section [sectref {FORMAT MAPPING}]. + +[call [arg objectName] [method setparam] [arg name] [arg value]] + +This method sets the [arg name]d engine parameter to the specified +[arg value]. + +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given [arg name]. + +The list of parameters provided by the configured formatting engine +can be retrieved through the method [method parameters]. + +[call [arg objectName] [method warnings]] + +This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method [method format]. + +[list_end] + +[subsection {OBJECT CONFIGURATION}] + +All docidx objects understand the following configuration options: + +[list_begin options] + +[opt_def -file [arg file]] + +The argument of this option is stored in the object and made available +to the configured formatting engine through the command [cmd dt_file]. + +This command is described in more detail in the companion document +[term docidx_api] which specifies the API between the object and +formatting engines. + +[para] + +The default value of this option is the empty string. + +[para] + +The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed. + +[opt_def -format [arg text]] + +The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method [method format]. Its default value is the empty string. The +method [method format] cannot be used if this option is not set to a +valid value at least once. + +[para] + +The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched. + +[para] + +The section [sectref {FORMAT MAPPING}] explains in detail how the +package and object will look for engine implementations. + +[list_end] + +[subsection {FORMAT MAPPING}] + +The package and object will perform the following algorithm when +trying to map a format name [term foo] to a file containing an +implementation of a formatting engine for [term foo]: + +[list_begin enumerated] +[enum] + +If [term foo] is the name of an existing file then this file is +directly taken as the implementation. + +[enum] + +If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file [file idx.[term foo]]. If yes, then that file is taken as the +implementation. + +[para] + +Note that this list of paths is initially empty and can be extended +through the object method [method search]. + +[enum] + +If not, the list of package paths is searched. + +For each directory in the list the package checks if that directory +contains a file [file idx.[term foo]]. If yes, then that file is taken +as the implementation. + +[para] + +This list of paths can be extended +through the command [cmd ::doctools::idx::search]. + +It contains initially one path, the subdirectory [file mpformats] of +the directory the package itself is located in. In other words, if the +package implementation [file docidx.tcl] is installed in the directory +[file /usr/local/lib/tcllib/doctools] then it will by default search +the directory [file /usr/local/lib/tcllib/doctools/mpformats] for +format implementations. + +[enum] + +The mapping fails. + +[list_end] + +[section {PREDEFINED ENGINES}] + +The package provides predefined formatting engines for the following +formats. Some of the formatting engines support engine +parameters. These will be explicitly highlighted. + +[list_begin definitions] +[def html] + +This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters: + +[list_begin definitions] +[def footer] + +The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the [const </body>] tag, closing the body of the generated +HTML. + +[para] + +This can be used to insert boilerplate footer markup into the +generated document. + +[def header] + +The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the [const <body>] tag, starting the body of the generated HTML. + +[para] + +This can be used to insert boilerplate header markup into the +generated document. + +[def meta] + +The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the [const <head>] tag, starting the header section of the +generated HTML. + +[para] + +This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc. + +[list_end] +[para] + +[def latex] + +This engine generates output suitable for the [syscmd latex] text +processor coming out of the TeX world. + +[def list] + +This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages. + +[def nroff] + +This engine generates nroff output, for processing by [syscmd nroff], +or [syscmd groff]. The result will be standard man pages as they are +known in the unix world. + +[def null] + +This engine generates no outout at all. This can be used if one just +wants to validate some input. + +[def tmml] + +This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML. + +[def wiki] + +This engine generates Wiki markup as understood by Jean Claude +Wippler's [syscmd wikit] application. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/docidx.tcl b/tcllib/modules/doctools/docidx.tcl new file mode 100644 index 0000000..b8748ff --- /dev/null +++ b/tcllib/modules/doctools/docidx.tcl @@ -0,0 +1,962 @@ +# docidx.tcl -- +# +# Implementation of docidx objects for Tcl. +# +# Copyright (c) 2003-2014 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# RCS: @(#) $Id: docidx.tcl,v 1.22 2010/06/08 19:13:53 andreas_kupries Exp $ + +package require Tcl 8.2 +package require textutil::expander + +# @mdgen OWNER: api_idx.tcl +# @mdgen OWNER: checker_idx.tcl +# @mdgen OWNER: mpformats/*.tcl +# @mdgen OWNER: mpformats/*.msg +# @mdgen OWNER: mpformats/idx.* +# @mdgen OWNER: mpformats/man.macros + +namespace eval ::doctools {} +namespace eval ::doctools::idx { + # Data storage in the doctools::idx module + # ------------------------------- + # + # One namespace per object, containing + # 1) A list of additional search paths for format definition files. + # This list extends the list of standard paths known to the module. + # The paths in the list are searched before the standard paths. + # 2) Configuration information + # a) string: The format to use when converting the input. + # 4) Name of the interpreter used to perform the syntax check of the + # input (= allowed order of formatting commands). + # 5) Name of the interpreter containing the code coming from the format + # definition file. + # 6) Name of the expander object used to interpret the input to convert. + + # commands is the list of subcommands recognized by the docidx objects + variable commands [list \ + "cget" \ + "configure" \ + "destroy" \ + "format" \ + "map" \ + "search" \ + "warnings" \ + "parameters" \ + "setparam" \ + ] + + # Only export the toplevel commands + namespace export new search help + + # Global data + + # 1) List of standard paths to look at when searching for a format + # definition. Extensible. + # 2) Location of this file in the filesystem + + variable paths [list] + variable here [file dirname [info script]] +} + +# ::doctools::idx::search -- +# +# Extend the list of paths used when searching for format definition files. +# +# Arguments: +# path Path to add to the list. The path has to exist, has to be a +# directory, and has to be readable. +# +# Results: +# None. +# +# Sideeffects: +# The specified path is added to the front of the list of search +# paths. This means that the new path is search before the +# standard paths set at module initialization time. + +proc ::doctools::idx::search {path} { + variable paths + + if {![file exists $path]} {return -code error "doctools::idx::search: path does not exist"} + if {![file isdirectory $path]} {return -code error "doctools::idx::search: path is not a directory"} + if {![file readable $path]} {return -code error "doctools::idx::search: path cannot be read"} + + set paths [linsert $paths 0 $path] + return +} + +# ::doctools::idx::help -- +# +# Return a string containing short help +# regarding the existing formatting commands. +# +# Arguments: +# None. +# +# Results: +# A string. + +proc ::doctools::idx::help {} { + return "formatting commands\n\ + * index_begin - begin of index\n\ + * index_end - end of index\n\ + * key - begin of references for key\n\ + * manpage - index reference to manpage\n\ + * url - index reference to url\n\ + * vset - set/get variable values\n\ + * include - insert external file\n\ + * lb, rb - left/right brackets\n\ + " +} + +# ::doctools::idx::new -- +# +# Create a new docidx object with a given name. May configure the object. +# +# Arguments: +# name Name of the docidx object. +# args Options configuring the new object. +# +# Results: +# name Name of the doctools created + +proc ::doctools::idx::new {name args} { + if { [llength [info commands ::$name]] } { + return -code error "command \"$name\" already exists, unable to create docidx object" + } + if {[llength $args] % 2 == 1} { + return -code error "wrong # args: doctools::new name ?opt val...??" + } + + # The arguments seem to be ok, setup the namespace for the object + + namespace eval ::doctools::idx::docidx$name { + variable paths [list] + variable file "" + variable format "" + variable formatfile "" + variable format_ip "" + variable chk_ip "" + variable expander "[namespace current]::ex" + variable ex_ok 0 + variable msg [list] + variable map ; array set map {} + variable param [list] + } + + # Create the command to manipulate the object + # $name -> ::doctools::idx::DocIdxProc $name + interp alias {} ::$name {} ::doctools::idx::DocIdxProc $name + + # If the name was followed by arguments use them to configure the + # object before returning its handle to the caller. + + if {[llength $args] > 1} { + # Use linsert trick to make the command a pure list. + eval [linsert $args 0 _configure $name] + } + return $name +} + +########################## +# Private functions follow + +# ::doctools::idx::DocIdxProc -- +# +# Command that processes all docidx object commands. +# Dispatches any object command to the appropriate internal +# command implementing its functionality. +# +# Arguments: +# name Name of the docidx object to manipulate. +# cmd Subcommand to invoke. +# args Arguments for subcommand. +# +# Results: +# Varies based on command to perform + +proc ::doctools::idx::DocIdxProc {name {cmd ""} args} { + # Do minimal args checks here + if { [llength [info level 0]] == 2 } { + error "wrong # args: should be \"$name option ?arg arg ...?\"" + } + + # Split the args into command and args components + + if { [llength [info commands ::doctools::idx::_$cmd]] == 0 } { + variable commands + set optlist [join $commands ", "] + set optlist [linsert $optlist "end-1" "or"] + return -code error "bad option \"$cmd\": must be $optlist" + } + return [eval [list ::doctools::idx::_$cmd $name] $args] +} + +########################## +# Method implementations follow (these are also private commands) + +# ::doctools::idx::_cget -- +# +# Retrieve the current value of a particular option +# +# Arguments: +# name Name of the docidx object to query +# option Name of the option whose value we are asking for. +# +# Results: +# The value of the option + +proc ::doctools::idx::_cget {name option} { + _configure $name $option +} + +# ::doctools::idx::_configure -- +# +# Configure a docidx object, or query its configuration. +# +# Arguments: +# name Name of the docidx object to configure +# args Options and their values. +# +# Results: +# None if configuring the object. +# A list of all options and their values if called without arguments. +# The value of one particular option if called with a single argument. + +proc ::doctools::idx::_configure {name args} { + if {[llength $args] == 0} { + # Retrieve the current configuration. + + upvar #0 ::doctools::idx::docidx${name}::file file + upvar #0 ::doctools::idx::docidx${name}::format format + + set res [list] + lappend res -file $file + lappend res -format $format + return $res + + } elseif {[llength $args] == 1} { + # Query the value of one particular option. + + switch -exact -- [lindex $args 0] { + -file { + upvar #0 ::doctools::idx::docidx${name}::file file + return $file + } + -format { + upvar #0 ::doctools::idx::docidx${name}::format format + return $format + } + default { + return -code error \ + "doctools::idx::_configure: Unknown option \"[lindex $args 0]\", expected\ + -file, or -format" + } + } + } else { + # Reconfigure the object. + + if {[llength $args] % 2 == 1} { + return -code error "wrong # args: doctools::idx::_configure name ?opt val...??" + } + + foreach {option value} $args { + switch -exact -- $option { + -file { + upvar #0 ::doctools::idx::docidx${name}::file file + set file $value + } + -format { + if {[catch { + set fmtfile [LookupFormat $name $value] + SetupFormatter $name $fmtfile + upvar #0 ::doctools::idx::docidx${name}::format format + set format $value + } msg]} { + return -code error \ + -errorinfo $::errorInfo \ + "doctools::idx::_configure: -format: $msg" + } + } + default { + return -code error \ + "doctools::idx::_configure: Unknown option \"$option\", expected\ + -file, or -format" + } + } + } + } + return "" +} + +# ::doctools::idx::_destroy -- +# +# Destroy a docidx object, including its associated command and data storage. +# +# Arguments: +# name Name of the docidx object to destroy. +# +# Results: +# None. + +proc ::doctools::idx::_destroy {name} { + # Check the object for sub objects which have to destroyed before + # the namespace is torn down. + namespace eval ::doctools::idx::docidx$name { + if {$format_ip != ""} {interp delete $format_ip} + if {$chk_ip != ""} {interp delete $chk_ip} + + # Expander objects have no delete/destroy method. This would + # be a leak if not for the fact that an expander object is a + # namespace, and we have arranged to make it a sub namespace of + # the docidx object. Therefore tearing down our object namespace + # also cleans up the expander object. + # if {$expander != ""} {$expander destroy} + + } + namespace delete ::doctools::idx::docidx$name + interp alias {} ::$name {} + return +} + +# ::doctools::idx::_map -- +# +# Add a mapping from symbolic to actual filename to the object. +# +# Arguments: +# name Name of the docidx object to use +# sfname Symbolic filename to map +# afname Actual filename +# +# Results: +# None. + +proc ::doctools::idx::_map {name sfname afname} { + upvar #0 ::doctools::idx::docidx${name}::map map + set map($sfname) $afname + return +} + +# ::doctools::idx::_format -- +# +# Convert some text in doctools format +# according to the configuration in the object. +# +# Arguments: +# name Name of the docidx object to use +# text Text to convert. +# +# Results: +# The conversion result. + +proc ::doctools::idx::_format {name text} { + upvar #0 ::doctools::idx::docidx${name}::format format + if {$format == ""} { + return -code error "$name: No format was specified" + } + + upvar #0 ::doctools::idx::docidx${name}::format_ip format_ip + upvar #0 ::doctools::idx::docidx${name}::chk_ip chk_ip + upvar #0 ::doctools::idx::docidx${name}::ex_ok ex_ok + upvar #0 ::doctools::idx::docidx${name}::expander expander + upvar #0 ::doctools::idx::docidx${name}::passes passes + upvar #0 ::doctools::idx::docidx${name}::msg warnings + + if {!$ex_ok} {SetupExpander $name} + if {$chk_ip == ""} {SetupChecker $name} + # assert (format_ip != "") + + set warnings [list] + if {[catch {$format_ip eval idx_initialize}]} { + return -code error "Could not initialize engine" + } + set result "" + + for { + set p $passes ; set n 1 + } { + $p > 0 + } { + incr p -1 ; incr n + } { + if {[catch {$format_ip eval [list idx_setup $n]}]} { + catch {$format_ip eval idx_shutdown} + return -code error "Could not initialize pass $n of engine" + } + $chk_ip eval ck_initialize + + if {[catch {set result [$expander expand $text]} msg]} { + catch {$format_ip eval idx_shutdown} + # Filter for checker errors and reduce them to the essential message. + + if {![regexp {^Error in} $msg]} {return -code error $msg} + #set msg [join [lrange [split $msg \n] 2 end]] + + if {![regexp {^--> \(FmtError\) } $msg]} {return -code error "Docidx $msg"} + set msg [lindex [split $msg \n] 0] + regsub {^--> \(FmtError\) } $msg {} msg + + return -code error $msg + } + + $chk_ip eval ck_complete + } + + if {[catch {set result [$format_ip eval [list idx_postprocess $result]]}]} { + return -code error "Unable to post process final result" + } + if {[catch {$format_ip eval idx_shutdown}]} { + return -code error "Could not shut engine down" + } + return $result + +} + +# ::doctools::idx::_search -- +# +# Add a search path to the object. +# +# Arguments: +# name Name of the docidx object to extend +# path Search path to add. +# +# Results: +# None. + +proc ::doctools::idx::_search {name path} { + if {![file exists $path]} {return -code error "$name search: path does not exist"} + if {![file isdirectory $path]} {return -code error "$name search: path is not a directory"} + if {![file readable $path]} {return -code error "$name search: path cannot be read"} + + upvar #0 ::doctools::idx::docidx${name}::paths paths + set paths [linsert $paths 0 $path] + return +} + +# ::doctools::idx::_warnings -- +# +# Return the warning accumulated during the last invocation of 'format'. +# +# Arguments: +# name Name of the docidx object to query +# +# Results: +# A list of warnings. + +proc ::doctools::idx::_warnings {name} { + upvar #0 ::doctools::idx::docidx${name}::msg msg + return $msg +} + +# ::doctools::_parameters -- +# +# Returns a list containing the parameters provided +# by the selected formatting engine. +# +# Arguments: +# name Name of the doctools object to query +# +# Results: +# A list of parameter names + +proc ::doctools::idx::_parameters {name} { + upvar #0 ::doctools::idx::docidx${name}::param param + return $param +} + +# ::doctools::_setparam -- +# +# Set a named engine parameter to a value. +# +# Arguments: +# name Name of the doctools object to query +# param Name of the parameter to set. +# value Value to set the parameter to. +# +# Results: +# None. + +proc ::doctools::idx::_setparam {name param value} { + upvar #0 ::doctools::idx::docidx${name}::format_ip format_ip + + if {$format_ip == {}} { + return -code error \ + "Unable to set parameters without a valid format" + } + + $format_ip eval [list idx_varset $param $value] + return +} + +########################## +# Support commands + +# ::doctools::idx::LookupFormat -- +# +# Search a format definition file based upon its name +# +# Arguments: +# name Name of the docidx object to use +# format Name of the format to look for. +# +# Results: +# The file containing the format definition + +proc ::doctools::idx::LookupFormat {name format} { + # Order of searching + # 1) Is the name of the format an existing file ? + # If yes, take this file. + # 2) Look for the file in the directories given to the object itself.. + # 3) Look for the file in the standard directories of this package. + + if {[file exists $format] && [file isfile $format]} { + return $format + } + + upvar #0 ::doctools::idx::docidx${name}::paths opaths + foreach path $opaths { + set f [file join $path idx.$format] + if {[file exists $f] && [file isfile $f]} { + return $f + } + } + + variable paths + foreach path $paths { + set f [file join $path idx.$format] + if {[file exists $f] && [file isfile $f]} { + return $f + } + } + + return -code error "Unknown format \"$format\"" +} + +# ::doctools::idx::SetupFormatter -- +# +# Create and initializes an interpreter containing a +# formatting engine +# +# Arguments: +# name Name of the docidx object to manipulate +# format Name of file containing the code of the engine +# +# Results: +# None. + +proc ::doctools::idx::SetupFormatter {name format} { + + # Create and initialize the interpreter first. + # Use a transient variable. Interrogate the + # engine and check its response. Bail out in + # case of errors. Only if we pass the checks + # we tear down the old engine and make the new + # one official. + + variable here + set mpip [interp create -safe] ; # interpreter for the formatting engine + #set mpip [interp create] ; # interpreter for the formatting engine + + $mpip invokehidden source [file join $here api_idx.tcl] + #$mpip eval [list source [file join $here api_idx.tcl]] + interp alias $mpip dt_source {} ::doctools::idx::Source $mpip [file dirname $format] + interp alias $mpip dt_read {} ::doctools::idx::Read $mpip [file dirname $format] + interp alias $mpip dt_package {} ::doctools::idx::Package $mpip + interp alias $mpip file {} ::doctools::idx::FileOp $mpip + interp alias $mpip puts_stderr {} ::puts stderr + $mpip invokehidden source $format + #$mpip eval [list source $format] + + # Check the engine for useability in doctools. + + foreach api { + idx_numpasses + idx_initialize + idx_setup + idx_postprocess + idx_shutdown + idx_listvariables + idx_varset + } { + if {[$mpip eval [list info commands $api]] == {}} { + interp delete $mpip + error "$format error: API incomplete, cannot use this engine" + } + } + if {[catch { + set passes [$mpip eval idx_numpasses] + }]} { + interp delete $mpip + error "$format error: Unable to query for number of passes" + } + if {![string is integer $passes] || ($passes < 1)} { + interp delete $mpip + error "$format error: illegal number of passes \"$passes\"" + } + if {[catch { + set parameters [$mpip eval idx_listvariables] + }]} { + interp delete $mpip + error "$format error: Unable to query for list of parameters" + } + + # Passed the tests. Tear down existing engine, + # and checker. The latter is destroyed because + # of its aliases into the formatter, which are + # now invalid. It will be recreated during the + # next call of 'format'. + + upvar #0 ::doctools::idx::docidx${name}::formatfile formatfile + upvar #0 ::doctools::idx::docidx${name}::format_ip format_ip + upvar #0 ::doctools::idx::docidx${name}::chk_ip chk_ip + upvar #0 ::doctools::idx::docidx${name}::expander expander + upvar #0 ::doctools::idx::docidx${name}::passes xpasses + upvar #0 ::doctools::idx::docidx${name}::param xparam + + if {$chk_ip != {}} {interp delete $chk_ip} + if {$format_ip != {}} {interp delete $format_ip} + + set chk_ip "" + set format_ip "" + + # Now link engine API into it. + + interp alias $mpip dt_format {} ::doctools::idx::GetFormat $name + interp alias $mpip dt_user {} ::doctools::idx::GetUser $name + interp alias $mpip dt_fmap {} ::doctools::idx::MapFile $name + + foreach cmd {cappend cget cis cname cpop cpush cset lb rb} { + interp alias $mpip ex_$cmd {} $expander $cmd + } + + set format_ip $mpip + set formatfile $format + set xpasses $passes + set xparam $parameters + return +} + +# ::doctools::idx::SetupChecker -- +# +# Create and initializes an interpreter for checking the usage of +# docidx formatting commands +# +# Arguments: +# name Name of the docidx object to manipulate +# +# Results: +# None. + +proc ::doctools::idx::SetupChecker {name} { + # Create an interpreter for checking the usage of docidx formatting commands + # and initialize it: Link it to the interpreter doing the formatting, the + # expander object and the configuration information. All of which + # is accessible through the token/handle (name of state/object array). + + variable here + + upvar #0 ::doctools::idx::docidx${name}::chk_ip chk_ip + if {$chk_ip != ""} {return} + + upvar #0 ::doctools::idx::docidx${name}::expander expander + upvar #0 ::doctools::idx::docidx${name}::format_ip format_ip + + set chk_ip [interp create] ; # interpreter hosting the formal format checker + + # Make configuration available through command, then load the code base. + + foreach {cmd ckcmd} { + dt_search SearchPaths + dt_error FmtError + dt_warning FmtWarning + } { + interp alias $chk_ip $cmd {} ::doctools::idx::$ckcmd $name + } + $chk_ip eval [list source [file join $here checker_idx.tcl]] + + # Simple expander commands are directly routed back into it, no + # checking required. + + foreach cmd {cappend cget cis cname cpop cpush cset lb rb} { + interp alias $chk_ip $cmd {} $expander $cmd + } + + # Link the formatter commands into the checker. We use the prefix + # 'fmt_' to distinguish them from the checking commands. + + foreach cmd { + index_begin index_end key manpage url comment plain_text + } { + interp alias $chk_ip fmt_$cmd $format_ip fmt_$cmd + } + return +} + +# ::doctools::idx::SetupExpander -- +# +# Create and initializes the expander for input +# +# Arguments: +# name Name of the docidx object to manipulate +# +# Results: +# None. + +proc ::doctools::idx::SetupExpander {name} { + upvar #0 ::doctools::idx::docidx${name}::ex_ok ex_ok + if {$ex_ok} {return} + + upvar #0 ::doctools::idx::docidx${name}::expander expander + ::textutil::expander $expander + $expander evalcmd [list ::doctools::idx::Eval $name] + $expander textcmd plain_text + set ex_ok 1 + return +} + +# ::doctools::idx::SearchPaths -- +# +# API for checker. Returns list of search paths for format +# definitions. Used to look for message catalogs as well. +# +# Arguments: +# name Name of the docidx object to query. +# +# Results: +# None. + +proc ::doctools::idx::SearchPaths {name} { + upvar #0 ::doctools::idx::docidx${name}::paths opaths + variable paths + + set p $opaths + foreach s $paths {lappend p $s} + return $p +} + +# ::doctools::idx::FmtError -- +# +# API for checker. Called when an error occurred. +# +# Arguments: +# name Name of the docidx object to query. +# text Error message +# +# Results: +# None. + +proc ::doctools::idx::FmtError {name text} { + return -code error "(FmtError) $text" +} + +# ::doctools::idx::FmtWarning -- +# +# API for checker. Called when a warning was generated +# +# Arguments: +# name Name of the docidx object +# text Warning message +# +# Results: +# None. + +proc ::doctools::idx::FmtWarning {name text} { + upvar #0 ::doctools::idx::docidx${name}::msg msg + lappend msg $text + return +} + +# ::doctools::idx::Eval -- +# +# API for expander. Routes the macro invocations +# into the checker interpreter +# +# Arguments: +# name Name of the docidx object to query. +# +# Results: +# None. + +proc ::doctools::idx::Eval {name macro} { + upvar #0 ::doctools::idx::docidx${name}::chk_ip chk_ip + + # Handle the [include] command directly + if {[string match include* $macro]} { + set macro [$chk_ip eval [list subst $macro]] + foreach {cmd filename} $macro break + return [ExpandInclude $name $filename] + } + + return [$chk_ip eval $macro] +} + +# ::doctools::idx::ExpandInclude -- +# +# Handle inclusion of files. +# +# Arguments: +# name Name of the docidx object to query. +# path Name of file to include and expand. +# +# Results: +# None. + +proc ::doctools::idx::ExpandInclude {name path} { + upvar #0 ::doctools::idx::docidx${name}::file file + + set ipath [file normalize [file join [file dirname $file] $path]] + if {![file exists $ipath]} { + set ipath $path + if {![file exists $ipath]} { + return -code error "Unable to fine include file \"$path\"" + } + } + + set chan [open $ipath r] + set text [read $chan] + close $chan + + upvar #0 ::doctools::idx::docidx${name}::expander expander + + set saved $file + set file $ipath + set res [$expander expand $text] + set file $saved + + return $res +} + +# ::doctools::idx::GetUser -- +# +# API for formatter. Returns name of current user +# +# Arguments: +# name Name of the docidx object to query. +# +# Results: +# String, name of current user. + +proc ::doctools::idx::GetUser {name} { + global tcl_platform + return $tcl_platform(user) +} + +# ::doctools::idx::GetFormat -- +# +# API for formatter. Returns format information +# +# Arguments: +# name Name of the docidx object to query. +# +# Results: +# Format information + +proc ::doctools::idx::GetFormat {name} { + upvar #0 ::doctools::idx::docidx${name}::format format + return $format +} + +# ::doctools::idx::MapFile -- +# +# API for formatter. Maps symbolic to actual filename in an +# index element. If no mapping is found it is assumed that +# the symbolic name is also the actual name. +# +# Arguments: +# name Name of the docidx object to query. +# fname Symbolic name of the file. +# +# Results: +# Actual name of the file. + +proc ::doctools::idx::MapFile {name fname} { + upvar #0 ::doctools::idx::docidx${name}::map map + if {[info exists map($fname)]} { + return $map($fname) + } + return $fname +} + +# ::doctools::idx::Source -- +# +# API for formatter. Used by engine to ask for +# additional script files support it. +# +# Arguments: +# name Name of the docidx object to change. +# +# Results: +# Boolean flag. + +proc ::doctools::idx::Source {ip path file} { + $ip invokehidden source [file join $path [file tail $file]] + #$ip eval [list source [file join $path [file tail $file]]] + return +} + +proc ::doctools::idx::Read {ip path file} { + #puts stderr "$ip (read $path $file)" + + return [read [set f [open [file join $path [file tail $file]]]]][close $f] +} + +proc ::doctools::idx::FileOp {ip args} { + #puts stderr "$ip (file $args)" + # -- FUTURE -- disallow unsafe operations -- + + return [eval [linsert $args 0 file]] +} + +proc ::doctools::idx::Package {ip pkg} { + #puts stderr "$ip package require $pkg" + + set indexScript [Locate $pkg] + + $ip expose source + $ip expose load + $ip eval $indexScript + $ip hide source + $ip hide load + #$ip eval [list source [file join $path [file tail $file]]] + return +} + +proc ::doctools::idx::Locate {p} { + # @mdgen NODEP: doctools::__undefined__ + catch {package require doctools::__undefined__} + + #puts stderr "auto_path = [join $::auto_path \n]" + + # Check if requested package is in the list of loadable packages. + # Then get the highest possible version, and then the index script + + if {[lsearch -exact [package names] $p] < 0} { + return -code error "Unknown package $p" + } + + set v [lindex [lsort -increasing [package versions $p]] end] + + #puts stderr "Package $p = $v" + + return [package ifneeded $p $v] +} + +#------------------------------------ +# Module initialization + +namespace eval ::doctools::idx { + # Reverse order of searching. First to search is specified last. + + # FOO/docidx.tcl + # => FOO/mpformats + + #catch {search [file join $here lib doctools mpformats]} + #catch {search [file join [file dirname $here] lib doctools mpformats]} + catch {search [file join $here mpformats]} +} + +package provide doctools::idx 1.0.5 diff --git a/tcllib/modules/doctools/docidx.test b/tcllib/modules/doctools/docidx.test new file mode 100644 index 0000000..5c5d0c2 --- /dev/null +++ b/tcllib/modules/doctools/docidx.test @@ -0,0 +1,316 @@ +# -*- tcl -*- +# docidx.test: tests for the doctools::idx package. +# +# This file contains a collection of tests for one or more of the Tcl +# built-in commands. Sourcing this file into Tcl runs the tests and +# generates output for errors. No output means no errors were found. +# +# Copyright (c) 2003-2009 by Andreas Kupries <andreas_kupries@users.sourceforge.net> +# All rights reserved. +# +# RCS: @(#) $Id: docidx.test,v 1.15 2009/02/12 05:42:47 andreas_kupries Exp $ + +# ------------------------------------------------------------------------- + +source [file join \ + [file dirname [file dirname [file join [pwd] [info script]]]] \ + devtools testutilities.tcl] + +testsNeedTcl 8.2 +testsNeedTcltest 1.0 + +support { + use textutil/expander.tcl textutil::expander +} +testing { + useLocal docidx.tcl doctools::idx +} + +# ------------------------------------------------------------------------- + +array_unset env LANG* +array_unset env LC_* +set env(LANG) C ; # Usually default if nothing is set, OS X requires this. + +# ------------------------------------------------------------------------- + +namespace import ::doctools::idx::new + +# search paths ............................................................. + +test docidx-1.0 {default search paths} { + llength $::doctools::idx::paths +} 1 + +test docidx-1.1 {extend package search paths} { + ::doctools::idx::search [file dirname [info script]] + set res [list] + lappend res [llength $::doctools::idx::paths] + lappend res [lindex $::doctools::idx::paths 0] + set res +} [list 2 [file dirname [info script]]] + +test docidx-1.2 {extend package search paths, error} { + catch {::doctools::idx::search foo} result + set result +} {doctools::idx::search: path does not exist} + +# format help ............................................................. + +test docidx-2.0 {format help} { + string length [doctools::idx::help] +} 368 + +# docidx ............................................................. + +test docidx-3.0 {docidx errors} { + catch {new} msg + set msg +} [tcltest::wrongNumArgs "new" "name args" 0] + +test docidx-3.1 {docidx errors} { + catch {new set} msg + set msg +} "command \"set\" already exists, unable to create docidx object" + +test docidx-3.2 {docidx errors} { + new mydocidx + catch {new mydocidx} msg + mydocidx destroy + set msg +} "command \"mydocidx\" already exists, unable to create docidx object" + +test docidx-3.3 {docidx errors} { + catch {new mydocidx -foo} msg + set msg +} {wrong # args: doctools::new name ?opt val...??} + +# docidx methods ...................................................... + +test docidx-4.0 {docidx method errors} { + new mydocidx + catch {mydocidx} msg + mydocidx destroy + set msg +} "wrong # args: should be \"mydocidx option ?arg arg ...?\"" + +test docidx-4.1 {docidx errors} { + new mydocidx + catch {mydocidx foo} msg + mydocidx destroy + set msg +} "bad option \"foo\": must be cget, configure, destroy, format, map, search, warnings, parameters, or setparam" + +# cget .................................................................. + +test docidx-5.0 {cget errors} { + new mydocidx + catch {mydocidx cget} result + mydocidx destroy + set result +} [tcltest::wrongNumArgs "::doctools::idx::_cget" "name option" 1] + +test docidx-5.1 {cget errors} { + new mydocidx + catch {mydocidx cget foo bar} result + mydocidx destroy + set result +} [tcltest::tooManyArgs "::doctools::idx::_cget" "name option"] + +test docidx-5.2 {cget errors} { + new mydocidx + catch {mydocidx cget -foo} result + mydocidx destroy + set result +} {doctools::idx::_configure: Unknown option "-foo", expected -file, or -format} + +foreach {na nb option default newvalue} { + 3 4 -file {} foo + 5 6 -format {} html +} { + test docidx-5.$na {cget query} { + new mydocidx + set res [mydocidx cget $option] + mydocidx destroy + set res + } $default ; # {} + + test docidx-5.$nb {cget set & query} { + new mydocidx + mydocidx configure $option $newvalue + set res [mydocidx cget $option] + mydocidx destroy + set res + } $newvalue ; # {} +} + +# configure .................................................................. + +test docidx-6.0 {configure errors} { + new mydocidx + catch {mydocidx configure -foo bar -glub} result + mydocidx destroy + set result +} {wrong # args: doctools::idx::_configure name ?opt val...??} +# [tcltest::wrongNumArgs "::doctools::idx::_configure" "name ?option?|?option value...?" 1] + +test docidx-6.1 {configure errors} { + new mydocidx + catch {mydocidx configure -foo} result + mydocidx destroy + set result +} {doctools::idx::_configure: Unknown option "-foo", expected -file, or -format} + +test docidx-6.2 {configure retrieval} { + new mydocidx + catch {mydocidx configure} result + mydocidx destroy + set result +} {-file {} -format {}} + +foreach {n option illegalvalue result} { + 3 -format barf {doctools::idx::_configure: -format: Unknown format "barf"} +} { + test docidx-6.$n {configure illegal value} { + new mydocidx + catch {mydocidx configure $option $illegalvalue} result + mydocidx destroy + set result + } $result +} + +foreach {na nb option default newvalue} { + 4 5 -file {} foo + 6 7 -format {} html +} { + test docidx-6.$na {configure query} { + new mydocidx + set res [mydocidx configure $option] + mydocidx destroy + set res + } $default ; # {} + + test docidx-6.$nb {configure set & query} { + new mydocidx + mydocidx configure $option $newvalue + set res [mydocidx configure $option] + mydocidx destroy + set res + } $newvalue ; # {} +} + +test docidx-6.8 {configure full retrieval} { + new mydocidx -file foo -format html + catch {mydocidx configure} result + mydocidx destroy + set result +} {-file foo -format html} + +# search .................................................................. + +test docidx-7.0 {search errors} { + new mydocidx + catch {mydocidx search} result + mydocidx destroy + set result +} [tcltest::wrongNumArgs "::doctools::idx::_search" "name path" 1] + +test docidx-7.1 {search errors} { + new mydocidx + catch {mydocidx search foo bar} result + mydocidx destroy + set result +} [tcltest::tooManyArgs "::doctools::idx::_search" "name path"] + +test docidx-7.2 {search errors} { + new mydocidx + catch {mydocidx search foo} result + mydocidx destroy + set result +} {mydocidx search: path does not exist} + +test docidx-7.3 {search, initial} { + new mydocidx + set res [llength $::doctools::idx::docidxmydocidx::paths] + mydocidx destroy + set res +} 0 + +test docidx-7.4 {extend object search paths} { + new mydocidx + mydocidx search [file dirname [info script]] + set res [list] + lappend res [llength $::doctools::idx::docidxmydocidx::paths] + lappend res [lindex $::doctools::idx::docidxmydocidx::paths 0] + mydocidx destroy + set res +} [list 1 [file dirname [info script]]] + +# format & warnings ....................................................... + +test docidx-8.0 {format errors} { + new mydocidx + catch {mydocidx format} result + mydocidx destroy + set result +} [tcltest::wrongNumArgs "::doctools::idx::_format" "name text" 1] + +test docidx-8.1 {format errors} { + new mydocidx + catch {mydocidx format foo bar} result + mydocidx destroy + set result +} [tcltest::tooManyArgs "::doctools::idx::_format" "name text"] + +test docidx-8.2 {format errors} { + new mydocidx + catch {mydocidx format foo} result + mydocidx destroy + set result +} {mydocidx: No format was specified} + + +test docidx-8.3 {format} { + new mydocidx -format wiki + set res [mydocidx format {[index_begin foo bar][key snafu][manpage at fubar][index_end]}] + lappend res [mydocidx warnings] + mydocidx destroy + set res +} {Index '''foo''' '''bar''' '''snafu''': at {}} + + +# docidx syntax ....................................................... + +test docidx-9.0 {docidx syntax} { + new mydocidx -format null + catch {mydocidx format foo} result + mydocidx destroy + set result +} {Docidx Error in plain text at line 1, column 0: +[plain_text foo] +--> (FmtError) IDX error (idx/plaintext), "plain_text foo" : Plain text beyond whitespace is not allowed..} + + +test docidx-9.1 {docidx syntax, empty index, ok} { + new mydocidx -format null + set result [mydocidx format {[index_begin KWIC Test][index_end]}] + mydocidx destroy + set result +} {} + +test docidx-9.2 {docidx syntax, key without references, error} { + new mydocidx -format null + catch {mydocidx format {[index_begin KWIC Test][key X][index_end]}} result + mydocidx destroy + set result +} {Docidx Error in macro at line 1, column 30: +[index_end] +--> (FmtError) IDX error (idx/endcmd), "index_end" : Command not allowed here..} + + +namespace forget ::doctools::idx::new + +# ------------------------------------------------------------------------- + +testsuiteCleanup +return diff --git a/tcllib/modules/doctools/docidx_intro.man b/tcllib/modules/doctools/docidx_intro.man new file mode 100644 index 0000000..be44517 --- /dev/null +++ b/tcllib/modules/doctools/docidx_intro.man @@ -0,0 +1,106 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin docidx_intro n 1.0] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[see_also docidx_plugin_apiref] +[see_also doctoc_intro] +[see_also doctools::idx] +[see_also doctools_intro] +[keywords index] +[keywords {keyword index}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx introduction}] +[category {Documentation tools}] +[description] +[para] + +[term docidx] (short for [emph {documentation tables of contents}]) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of keyword-based +indices for documentation. These are + +[list_begin enumerated] +[enum] + +A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands. + +[enum] + +A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins. + +[enum] + +An API describing the interface between the package above and a +plugin. + +[list_end] + +[para] + +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. + +[para] + +[list_begin enumerated] +[enum] +A [term writer] of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +[term {docidx language introduction}] first. Having digested this +the formal [term {docidx language syntax}] specification should +become understandable. A writer experienced with docidx may only +need the [term {docidx language command reference}] from time to +time to refresh her memory. + +[para] + +While a document is written the [syscmd dtp] application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler [syscmd dtplite] application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them. + +[enum] +A [term processor] of documentation written in the [term docidx] +markup language has to know which tools are available for use. + +[para] + +The main tool is the aforementioned [syscmd dtp] application provided +by Tcllib. The simpler [syscmd dtplite] does not expose docidx to the +user. + +At the bottom level, common to both applications, however sits the +package [package doctoools::idx], providing the basic facilities to +read and process files containing text in the docidx format. + +[enum] +At last, but not least, [term {plugin writers}] have to understand the +interaction between the [package doctools::idx] package and its +plugins, as described in the [term {docidx plugin API reference}]. + +[list_end] + +[section {RELATED FORMATS}] + +docidx does not stand alone, it has two companion formats. These are +called [term doctoc] and [term doctools], and they are for the markup +of [term {tables of contents}], and general documentation, +respectively. + +They are described in their own sets of documents, starting at the +[term {doctoc introduction}] and the [term {doctools introduction}], +respectively. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/docidx_lang_cmdref.man b/tcllib/modules/doctools/docidx_lang_cmdref.man new file mode 100644 index 0000000..53664de --- /dev/null +++ b/tcllib/modules/doctools/docidx_lang_cmdref.man @@ -0,0 +1,116 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin docidx_lang_cmdref n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx language command reference}] +[category {Documentation tools}] +[description] +[para] + +This document specifies both names and syntax of all the commands +which together are the docidx markup language, version 1. + +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. + +A beginner should read the much more informally written +[term {docidx language introduction}] first. + +[section Commands] +[list_begin definitions] + +[call [cmd comment] [arg plaintext]] + +Index markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text. + +[call [cmd include] [arg filename]] + +Templating. The contents of the named file are interpreted as text +written in the docidx markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries. + +[call [cmd index_begin] [arg text] [arg title]] + +Document structure. The command to start an index. The arguments are a +label for the whole group of documents the index refers to +([arg text]) and the overall title text for the index ([arg title]), +without markup. + +[para] + +The label often is the name of the package (or extension) the +documents belong to. + +[call [cmd index_end]] + +Document structure. Command to end an index. Anything in the document +coming after this command is in error. + +[call [cmd key] [arg text]] + +Index structure. This command adds the keyword [arg text] to the +index. + +[call [cmd lb]] + +Text. The command is replaced with a left bracket. Use in free-form +text. Required to avoid interpretation of a left bracket as the start +of a markup command. Its usage is restricted to the arguments of other +markup commands. + +[call [cmd manpage] [arg file] [arg text]] + +Index structure. This command adds an element to the index which +refers to a document. The document is specified through the symbolic +name [arg file]. The [arg text] argument is used to label the +reference. + +[para] + +Symbolic names are used to preserve the convertibility of this format +to any output format. The actual name of the file will be inserted by +the chosen formatting engine when converting the input. This will be +based on a mapping from symbolic to actual names given to the engine. + +[call [cmd rb]] + +Text. The command is replaced with a right bracket. Use in free-form +text. Required to avoid interpretation of a right bracket as the end +of a markup command. Its usage is restricted to the arguments of other +commands. + +[call [cmd url] [arg url] [arg label]] + +Index structure. This is the second command to add an element to the +index. To refer to a document it is not using a symbolic name however, +but a (possibly format-specific) url describing the exact location of +the document indexed here. + +[call [cmd vset] [arg varname] [arg value] ] + +Templating. In this form the command sets the named document variable +to the specified [arg value]. It does not generate output. I.e. the +command is replaced by the empty string. + +[call [cmd vset] [arg varname]] + +Templating. In this form the command is replaced by the value of the +named document variable + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/docidx_lang_faq.man b/tcllib/modules/doctools/docidx_lang_faq.man new file mode 100644 index 0000000..786f471 --- /dev/null +++ b/tcllib/modules/doctools/docidx_lang_faq.man @@ -0,0 +1,28 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin docidx_lang_faq n 1.0] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords {docidx syntax}] +[keywords examples] +[keywords faq] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx language faq}] +[category {Documentation tools}] +[description] +[vset theformat docidx] + +[section OVERVIEW] + +[include include/placeholder.inc] +[include include/examples.inc] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/docidx_lang_intro.man b/tcllib/modules/doctools/docidx_lang_intro.man new file mode 100644 index 0000000..33fe521 --- /dev/null +++ b/tcllib/modules/doctools/docidx_lang_intro.man @@ -0,0 +1,214 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin docidx_lang_intro n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_syntax] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords {docidx syntax}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx language introduction}] +[category {Documentation tools}] +[description] +[para] + +This document is an informal introduction to version 1 of the docidx +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the [term {docidx language syntax}] specification +and the [term {docidx language command reference}]. + +[subsection Fundamentals] + +While the [term {docidx markup language}] is quite similar to the +[term {doctools markup language}], in the broadest terms possible, +there is one key difference. An index consists essentially only of +markup commands, with no plain text interspersed between them, except +for whitespace. + +[para] + +Each markup command is a Tcl command surrounded by a matching pair of +[const [lb]] and [const [rb]]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e. + +[para] +[example { + ... [key {markup language}] ... +}] + +[example { + ... [manpage thefile \\ + {file description}] ... +}] + +[subsection {Basic structure}] + +The most simple document which can be written in docidx is + +[example { + [index_begin GROUPTITLE TITLE] + [index_end] +}] + +[para] + +Not very useful, but valid. This also shows us that all docidx +documents consist of only one part where we will list all keys and +their references. + +[para] + +A more useful index will contain at least keywords, or short 'keys', +i.e. the phrases which were indexed. So: + +[example_begin] +[lb]index_begin GROUPTITLE TITLE[rb] +[lb][cmd {key markup}][rb] +[lb][cmd {key {semantic markup}]}][rb] +[lb][cmd {key {docidx markup}}][rb] +[lb][cmd {key {docidx language}}][rb] +[lb][cmd {key {docidx commands}}][rb] +[lb]index_end[rb] +[example_end] + +[para] + +In the above example the command [cmd key] is used to declare the +keyword phrases we wish to be part of the index. + +[para] + +However a truly useful index does not only list the keyword phrases, +but will also contain references to documents associated with the +keywords. Here is a made-up index for all the manpages in the module +[term base64]: + +[example_begin] +[lb]index_begin tcllib/base64 {De- & Encoding}[rb] +[lb]key base64[rb] +[lb][cmd {manpage base64}][rb] +[lb]key encoding[rb] +[lb][cmd {manpage base64}][rb] +[lb][cmd {manpage uuencode}][rb] +[lb][cmd {manpage yencode}][rb] +[lb]key uuencode[rb] +[lb][cmd {manpage uuencode}][rb] +[lb]key yEnc[rb] +[lb][cmd {manpage yencode}][rb] +[lb]key ydecode[rb] +[lb][cmd {manpage yencode}][rb] +[lb]key yencode[rb] +[lb][cmd {manpage yencode}][rb] +[lb]index_end[rb] +[example_end] + +[para] + +In the above example the command [cmd manpage] is used to insert +references to documents, using symbolic file names, with each command +belonging to the last [cmd key] command coming before it. + +[para] + +The other command to insert references is [cmd url]. In contrast to +[cmd manpage] it uses explicit (possibly format-specific) urls to +describe the location of the referenced document. As such this command +is intended for the creation of references to external documents which +could not be handled in any other way. + +[subsection {Advanced structure}] + +In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the [cmd index_begin] command opening the +document. + +[para] + +Instead of only whitespace the two templating commands [cmd include] +and [cmd vset] are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the table of +contents. I.e. it is possible to write + +[example_begin] +[lb][cmd {include FILE}][rb] +[lb][cmd {vset VAR VALUE}][rb] +[lb]index_begin GROUPTITLE TITLE[rb] +... +[lb]index_end[rb] +[example_end] + +Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. + +[example_begin] +[lb]index_begin GROUPTITLE TITLE[rb] +[lb][cmd {include FILE}][rb] +[lb][cmd {vset VAR VALUE}][rb] +... +[lb]index_end[rb] +[example_end] + +The only restriction [cmd include] has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before [cmd index_begin] may contain only the templating +commands [cmd vset] and [cmd include], a file included after a key +may contain only manape or url references, and other keys, etc. + +[subsection Escapes] + +Beyond the 6 commands shown so far we have two more available. + +However their function is not the marking up of index structure, but +the insertion of characters, namely [const [lb]] and [const [rb]]. + +These commands, [cmd lb] and [cmd rb] respectively, are required +because our use of [lb] and [rb] to bracket markup commands makes it +impossible to directly use [lb] and [rb] within the text. + +[para] + +Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added. + +[example_begin] + ... + These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required + because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it + impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. + ... +[example_end] + +[section {FURTHER READING}] + +Now that this document has been digested the reader, assumed to be a +[term writer] of documentation should be fortified enough to be able +to understand the formal [term {docidx language syntax}] +specification as well. From here on out the +[term {docidx language command reference}] will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax. + +[para] + +To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +[syscmd dtp]. + +[para] + +On the other hand, docidx is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple [syscmd dtplite] goes, creating an index for a set of +documents behind the scenes, without the writer having to do so on +their own. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/docidx_lang_syntax.man b/tcllib/modules/doctools/docidx_lang_syntax.man new file mode 100644 index 0000000..cdf7b0c --- /dev/null +++ b/tcllib/modules/doctools/docidx_lang_syntax.man @@ -0,0 +1,120 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin docidx_lang_syntax n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[keywords {docidx commands}] +[keywords {docidx language}] +[keywords {docidx markup}] +[keywords {docidx syntax}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx language syntax}] +[category {Documentation tools}] +[description] +[para] + +This document contains the formal specification of the syntax of the +docidx markup language, version 1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +[term {docidx language command reference}]. + +A beginner should read the much more informally written +[term {docidx language introduction}] first before trying to +understand either this document or the command reference. + +[section Fundamentals] + +In the broadest terms possible the [term {docidx markup language}] is +like SGML and similar languages. A document written in this language +consists primarily of markup commands, with text embedded into it at +some places. + +[para] + +Each markup command is a just Tcl command surrounded by a matching +pair of [const [lb]] and [const [rb]]. Which commands are available, +and their arguments, i.e. syntax is specified in the +[term {docidx language command reference}]. + +[para] + +In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other. + +[section {Lexical definitions}] + +In the syntax rules listed in the next section + +[list_begin enumerated] +[enum] +<TEXT> stands for all text except markup commands. + +[enum] +Any XXX stands for the markup command [lb]xxx[rb] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [const [lb]] and [const [rb]]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc. + +[enum] +<WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the [cmd comment] markup command. +[list_end] + +[section Syntax] + +The rules listed here specify only the syntax of docidx documents. The +lexical level of the language was covered in the previous section. + +[para] + +Regarding the syntax of the (E)BNF itself + +[list_begin enumerated] +[enum] +The construct { X } stands for zero or more occurrences of X. +[enum] +The construct [lb] X [rb] stands for zero or one occurrence of X. +[list_end] + +The syntax: + +[example { +index = defs + INDEX_BEGIN + [ contents ] + INDEX_END + { <WHITE> } + +defs = { INCLUDE | VSET | <WHITE> } +contents = keyword { keyword } + +keyword = defs KEY ref { ref } +ref = MANPAGE | URL | defs +}] + +At last a rule we were unable to capture in the EBNF syntax, as it is +about the arguments of the markup commands, something which is not +modeled here. + +[list_begin enumerated] +[enum] + +The arguments of all markup commands have to be plain text, and/or text +markup commands, i.e. one of + +[list_begin enumerated] +[enum][cmd lb], +[enum][cmd rb], or +[enum][cmd vset] (1-argument form). +[list_end] + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/docidx_plugin_apiref.man b/tcllib/modules/doctools/docidx_plugin_apiref.man new file mode 100644 index 0000000..e375547 --- /dev/null +++ b/tcllib/modules/doctools/docidx_plugin_apiref.man @@ -0,0 +1,421 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin docidx_plugin_apiref n 1.0] +[see_also docidx_intro] +[see_also docidx_lang_cmdref] +[see_also docidx_lang_faq] +[see_also docidx_lang_intro] +[see_also docidx_lang_syntax] +[see_also doctools::idx] +[keywords {formatting engine}] +[keywords index] +[keywords {index formatter}] +[keywords keywords] +[keywords markup] +[keywords plugin] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {docidx plugin API reference}] +[category {Documentation tools}] +[description] +[para] + +This document is intended for [term {plugin writers}], i.e. developers +wishing to write an index [term {formatting engine}] for some output +format X. + +[para] + +It specifies the interaction between the [package doctools::idx] +package and its plugins, i.e. the interface any index formatting +engine has to comply with. + +[para] + +This document deals with version 1 of the interface. + +[para] + +A reader who is on the other hand more interested in the markup +language itself should start with the + +[term {docidx language introduction}] and proceed from there to the +formal specifications, i.e. the [term {docidx language syntax}] and +the [term {docidx language command reference}]. + +[section OVERVIEW] + +The API for an index formatting engine consists of two major sections. + +[para] + +On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +[sectref {FRONTEND COMMANDS}] for their detailed specification. + +[para] + +And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. + +Please see section [sectref {PLUGIN COMMANDS}] and its subsections for +their detailed specification. + +[section {FRONTEND COMMANDS}] + +This section specifies the set of commands through which a plugin, +also known as an index formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter. + +[para] + +I.e. an index formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section [sectref {PLUGIN COMMANDS}]) are executed. + +[para] + +Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. + +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop. + +[para] + +Coming back to the imported commands, all the commands with prefix +[emph dt_] provide limited access to specific parts of the frontend, +whereas the commands with prefix [emph ex_] provide access to the +state of the [package textutil::expander] object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances. + +[para] + +[list_begin definitions] + +[call [cmd dt_fmap] [arg symfname]] + +Query command. It returns the actual pathname to use in the output in +place of the symbolic filename [arg symfname]. It will return the +unchanged input if no mapping was established for [arg symfname]. + +[para] + +The required mappings are established with the method [method map] of +a frontend, as explained in section [sectref-external {OBJECT METHODS}] +of the documentation for the package [package doctools::idx]. + +[call [cmd dt_format]] + +Query command. It returns the name of the format associated with the +index formatting engine. + +[call [cmd dt_read] [arg file]] + +Controlled filesystem access. Returns contents of [arg file] for +whatever use desired by the plugin. + +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error. + +[call [cmd dt_source] [arg file]] + +Controlled filesystem access. This command allows the index formatting +engine to load additional Tcl code it may need. + +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error. + +[call [cmd ex_cappend] [arg text]] +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. + +[call [cmd ex_cget] [arg varname]] +Retrieves the value of variable [arg varname], defined in the current +context. + +[call [cmd ex_cis] [arg cname]] +Determines whether or not the name of the current context is +[arg cname]. + +[call [cmd ex_cname]] +Returns the name of the current context. + +[call [cmd ex_cpop] [arg cname]] +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named [arg cname], or an +error results. + +[call [cmd ex_cpush] [arg cname]] +Pushes a context named [arg cname] onto the context stack. The +context must be popped by [method cpop] before expansion ends or an +error results. + +[call [cmd ex_cset] [arg varname] [arg value]] +Sets variable [arg varname] to [arg value] in the current context. + +[call [cmd ex_lb] [opt [arg newbracket]]] +Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If [arg newbracket] is specified, it becomes the new +bracket, and is returned. + +[call [cmd ex_rb] [opt [arg newbracket]]] +Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If [arg newbracket] is specified, it becomes the +new bracket, and is returned. + +[list_end] + +[section {PLUGIN COMMANDS}] + +The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections. + +[subsection {Management commands}] + +The management commands a plugin has to provide are used by the +frontend to + +[list_begin enumerated] +[enum] initialize and shutdown the plugin +[enum] determine the number of passes it has + to make over the input +[enum] initialize and shutdown each pass +[enum] query and initialize engine parameters +[list_end] +[para] + +After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence: + +[example { + idx_numpasses -> n + idx_listvariables -> vars + + idx_varset var1 value1 + idx_varset var2 value2 + ... + idx_varset varK valueK + idx_initialize + idx_setup 1 + ... + idx_setup 2 + ... + ... + idx_setup n + ... + idx_postprocess + idx_shutdown + ... +}] + +I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional. + +[para] + +After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at [cmd idx_varset]. + +[para] + +In each of the passes, i.e. after the calls of [cmd idx_setup] the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the docidx markup language, +as specified in the [term {docidx language syntax}] specification. + +[para] + +A different way of looking at the sequence is: + +[list_begin itemized] +[item] First some basic parameters are determined. + +[item] Then everything starting at the first [cmd idx_varset] to +[cmd idx_shutdown] forms a [term run], the formatting of a +single input. Each run can be followed by more. + +[item] Embedded within each run we have one or more [term passes], +each starting with [cmd idx_setup] and going until either the next +[cmd idx_setup] or [cmd idx_postprocess] is reached. + +[para] + +If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored. + +[list_end] +[para] + +The commands, their names, signatures, and responsibilities are, in +detail: + +[list_begin definitions] + +[call [cmd idx_initialize]] +[emph Initialization/Shutdown]. + +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. + +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored. + +[call [cmd idx_listvariables]] +[emph Initialization/Shutdown] and [emph {Engine parameters}]. + +Second command is called after the plugin code has been loaded, +i.e. immediately after [cmd idx_numpasses]. + +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty. + +[call [cmd idx_numpasses]] +[emph Initialization/Shutdown] and [emph {Pass management}]. + +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. + +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one. + +[call [cmd idx_postprocess] [arg text]] +[emph Initialization/Shutdown]. + +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument. + +[para] + +Expected to return a value, the final result of formatting the input. + +[call [cmd idx_setup] [arg n]] +[emph Initialization/Shutdown] and [emph {Pass management}]. + +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from [const 1] upward. + +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored. + +[call [cmd idx_shutdown]] +[emph Initialization/Shutdown]. + +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. + +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. + +No return value is expected, and any returned value is ignored. + +[call [cmd idx_varset] [arg varname] [arg text]] +[emph {Engine parameters}]. + +This command is called by the frontend to set an engine parameter to a +particular value. + +The parameter to change is specified by [arg varname], the value to +set in [arg text]. + +[para] + +The command has to throw an error if an unknown [arg varname] is +used. Only the names returned by [cmd idx_listvariables] have to be +considered as known. + +[para] + +The values of all engine parameters have to persist between passes and +runs. + +[list_end] + +[subsection {Formatting commands}] + +The formatting commands have to implement the formatting for the +output format, for all the markup commands of the docidx markup +language, except [cmd lb], [cmd rb], [cmd vset], [cmd include], and +[cmd comment]. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all. + +[para] + +This means, that each of the five markup commands specified in the +[term {docidx language command reference}] and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix [emph fmt_] added to it. + +[para] + +All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output. + +[para] + +To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +[term {docidx language command reference}] for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command. + +[para] + +The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the docidx +markup language, as specified in the [term {docidx language syntax}] +specification. + +[para] + +[list_begin definitions] + +[call [cmd fmt_plain_text] [arg text]] +[emph {No associated markup command}]. + +[para] Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text. + +[para] The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc.man b/tcllib/modules/doctools/doctoc.man new file mode 100644 index 0000000..f11f513 --- /dev/null +++ b/tcllib/modules/doctools/doctoc.man @@ -0,0 +1,405 @@ +[vset PACKAGE_VERSION 1.1.4] +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools::toc n [vset PACKAGE_VERSION]] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[see_also doctoc_plugin_apiref] +[keywords conversion] +[keywords doctoc] +[keywords documentation] +[keywords HTML] +[keywords latex] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords {table of contents}] +[keywords TMML] +[keywords toc] +[keywords wiki] +[copyright {2003-2014 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc - Processing tables of contents}] +[category {Documentation tools}] +[require Tcl 8.2] +[require doctools::toc [opt [vset PACKAGE_VERSION]]] +[description] + +This package provides a class for the creation of objects able to +process and convert text written in the [term doctoc] markup language +into any output format X for which a [term {formatting engine}] is +available. + +[para] + +A reader interested in the markup language itself should start with +the [term {doctoc language introduction}] and proceed from there to +the formal specifications, i.e. the [term {doctoc language syntax}] +and the [term {doctoc language command reference}]. + +[para] + +If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a [term {plugin writer}] then reading +and understanding the [term {doctoc plugin API reference}] is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail. + +[section {PUBLIC API}] +[subsection {PACKAGE COMMANDS}] + +[list_begin definitions] + +[call [cmd ::doctools::toc::new] [arg objectName] [opt "[option -option] [arg value] ..."]] + +This command creates a new doctoc object with an associated Tcl +command whose name is [arg objectName]. This [term object] command is +explained in full detail in the sections [sectref {OBJECT COMMAND}] +and [sectref {OBJECT METHODS}]. The object command will be created +under the current namespace if the [arg objectName] is not fully +qualified, and in the specified namespace otherwise. + +[para] + +The options and their values coming after the name of the object are +used to set the initial configuration of the object. + +[call [cmd ::doctools::toc::help]] + +This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text. + +[call [cmd ::doctools::toc::search] [arg path]] + +Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section [sectref {FORMAT MAPPING}] for more explanations. + +[para] + +This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. + +This command is the means to do so. When given a [arg path] to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the [arg path] added +last is later searched through first. + +[para] + +An error will be thrown if the [arg path] either does not exist, is +not a directory, or is not readable. + +[list_end] + +[subsection {OBJECT COMMAND}] + +All commands created by [cmd ::doctools::toc::new] have the following +general form and may be used to invoke various operations on their +doctoc converter object. + +[list_begin definitions] + +[call [cmd objectName] [method method] [opt [arg "arg arg ..."]]] + +The method [method method] and its [arg arg]'uments determine the exact +behavior of the command. See section [sectref {OBJECT METHODS}] for +the detailed specifications. + +[list_end] + +[subsection {OBJECT METHODS}] + +[list_begin definitions] + +[call [arg objectName] [method configure]] + +The method returns a list of all known options and their current +values when called without any arguments. + +[call [arg objectName] [method configure] [arg option]] + +The method behaves like the method [method cget] when called with a +single argument and returns the value of the option specified by said +argument. + +[call [arg objectName] [method configure] [option -option] [arg value]...] + +The method reconfigures the specified [option option]s of the object, +setting them to the associated [arg value]s, when called with an even +number of arguments, at least two. + +[para] + +The legal options are described in the section +[sectref {OBJECT CONFIGURATION}]. + +[call [arg objectName] [method cget] [option -option]] + +This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for. + +[para] + +The legal configuration options are described in section +[sectref {OBJECT CONFIGURATION}]. + +[call [arg objectName] [method destroy]] + +This method destroys the object it is invoked for. + +[call [arg objectName] [method format] [arg text]] + +This method runs the [arg text] through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no [option -format] was configured for the object. + +[para] + +The method assumes that the [arg text] is in [term doctoc] format as +specified in the companion document [term doctoc_fmt]. Errors will be +thrown otherwise. + +[call [arg objectName] [method map] [arg symbolic] [arg actual]] + +This methods add one entry to the per-object mapping from +[arg symbolic] filenames to the [arg actual] uris. + +The object just stores this mapping and makes it available to the +configured formatting engine through the command [cmd dt_fmap]. + +This command is described in more detail in the +[term {doctoc plugin API reference}] which specifies the interaction +between the objects created by this package and toc formatting +engines. + +[call [arg objectName] [method parameters]] + +This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format. + +[call [arg objectName] [method search] [arg path]] + +This method extends the per-object list of paths searched for toc +formatting engines. See also the command [cmd ::doctools::toc::search] +on how to extend the per-package list of paths. Note that the path +entered last will be searched first. + +For more details see section [sectref {FORMAT MAPPING}]. + +[call [arg objectName] [method setparam] [arg name] [arg value]] + +This method sets the [arg name]d engine parameter to the specified +[arg value]. + +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given [arg name]. + +The list of parameters provided by the configured formatting engine +can be retrieved through the method [method parameters]. + +[call [arg objectName] [method warnings]] + +This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method [method format]. + +[list_end] + +[subsection {OBJECT CONFIGURATION}] + +All doctoc objects understand the following configuration options: + +[list_begin options] + +[opt_def -file [arg file]] + +The argument of this option is stored in the object and made available +to the configured formatting engine through the command [cmd dt_file]. + +This command is described in more detail in the companion document +[term doctoc_api] which specifies the API between the object and +formatting engines. + +[para] + +The default value of this option is the empty string. + +[para] + +The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed. + +[opt_def -format [arg text]] + +The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method [method format]. Its default value is the empty string. The +method [method format] cannot be used if this option is not set to a +valid value at least once. + +[para] + +The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched. + +[para] + +The section [sectref {FORMAT MAPPING}] explains in detail how the +package and object will look for engine implementations. + +[list_end] + +[subsection {FORMAT MAPPING}] + +The package and object will perform the following algorithm when +trying to map a format name [term foo] to a file containing an +implementation of a formatting engine for [term foo]: + +[list_begin enumerated] +[enum] + +If [term foo] is the name of an existing file then this file is +directly taken as the implementation. + +[enum] + +If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file [file toc.[term foo]]. If yes, then that file is taken as the +implementation. + +[para] + +Note that this list of paths is initially empty and can be extended +through the object method [method search]. + +[enum] + +If not, the list of package paths is searched. + +For each directory in the list the package checks if that directory +contains a file [file toc.[term foo]]. If yes, then that file is taken +as the implementation. + +[para] + +This list of paths can be extended +through the command [cmd ::doctools::toc::search]. + +It contains initially one path, the subdirectory [file mpformats] of +the directory the package itself is located in. In other words, if the +package implementation [file doctoc.tcl] is installed in the directory +[file /usr/local/lib/tcllib/doctools] then it will by default search +the directory [file /usr/local/lib/tcllib/doctools/mpformats] for +format implementations. + +[enum] + +The mapping fails. + +[list_end] + +[section {PREDEFINED ENGINES}] + +The package provides predefined formatting engines for the following +formats. Some of the formatting engines support engine +parameters. These will be explicitly highlighted. + +[list_begin definitions] +[def html] + +This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters: + +[list_begin definitions] +[def footer] + +The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the [const </body>] tag, closing the body of the generated +HTML. + +[para] + +This can be used to insert boilerplate footer markup into the +generated document. + +[def header] + +The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the [const <body>] tag, starting the body of the generated HTML. + +[para] + +This can be used to insert boilerplate header markup into the +generated document. + +[def meta] + +The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the [const <head>] tag, starting the header section of the +generated HTML. + +[para] + +This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc. + +[list_end] +[para] + +[def latex] + +This engine generates output suitable for the [syscmd latex] text +processor coming out of the TeX world. + +[def list] + +This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages. + +[def nroff] + +This engine generates nroff output, for processing by [syscmd nroff], +or [syscmd groff]. The result will be standard man pages as they are +known in the unix world. + +[def null] + +This engine generates no outout at all. This can be used if one just +wants to validate some input. + +[def tmml] + +This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML. + +[def wiki] + +This engine generates Wiki markup as understood by Jean Claude +Wippler's [syscmd wikit] application. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc.tcl b/tcllib/modules/doctools/doctoc.tcl new file mode 100644 index 0000000..49b21b6 --- /dev/null +++ b/tcllib/modules/doctools/doctoc.tcl @@ -0,0 +1,968 @@ +# doctoc.tcl -- +# +# Implementation of doctoc objects for Tcl. +# +# Copyright (c) 2003-2014 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# RCS: @(#) $Id: doctoc.tcl,v 1.22 2010/06/08 19:13:53 andreas_kupries Exp $ + +package require Tcl 8.2 +package require textutil::expander + +# @mdgen OWNER: api_toc.tcl +# @mdgen OWNER: checker_toc.tcl +# @mdgen OWNER: mpformats/*.tcl +# @mdgen OWNER: mpformats/*.msg +# @mdgen OWNER: mpformats/toc.* +# @mdgen OWNER: mpformats/man.macros + +namespace eval ::doctools {} +namespace eval ::doctools::toc { + # Data storage in the doctools::toc module + # ------------------------------- + # + # One namespace per object, containing + # 1) A list of additional search paths for format definition files. + # This list extends the list of standard paths known to the module. + # The paths in the list are searched before the standard paths. + # 2) Configuration information + # a) string: The format to use when converting the input. + # 4) Name of the interpreter used to perform the syntax check of the + # input (= allowed order of formatting commands). + # 5) Name of the interpreter containing the code coming from the format + # definition file. + # 6) Name of the expander object used to interpret the input to convert. + + # commands is the list of subcommands recognized by the doctoc objects + variable commands [list \ + "cget" \ + "configure" \ + "destroy" \ + "format" \ + "map" \ + "search" \ + "warnings" \ + "parameters" \ + "setparam" \ + ] + + # Only export the toplevel commands + namespace export new search help + + # Global data + + # 1) List of standard paths to look at when searching for a format + # definition. Extensible. + # 2) Location of this file in the filesystem + + variable paths [list] + variable here [file dirname [info script]] +} + +# ::doctools::toc::search -- +# +# Extend the list of paths used when searching for format definition files. +# +# Arguments: +# path Path to add to the list. The path has to exist, has to be a +# directory, and has to be readable. +# +# Results: +# None. +# +# Sideeffects: +# The specified path is added to the front of the list of search +# paths. This means that the new path is search before the +# standard paths set at module initialization time. + +proc ::doctools::toc::search {path} { + variable paths + + if {![file exists $path]} {return -code error "doctools::toc::search: path does not exist"} + if {![file isdirectory $path]} {return -code error "doctools::toc::search: path is not a directory"} + if {![file readable $path]} {return -code error "doctools::toc::search: path cannot be read"} + + set paths [linsert $paths 0 $path] + return +} + +# ::doctools::toc::help -- +# +# Return a string containing short help +# regarding the existing formatting commands. +# +# Arguments: +# None. +# +# Results: +# A string. + +proc ::doctools::toc::help {} { + return "formatting commands\n\ + * toc_begin - begin of table of contents\n\ + * toc_end - end of toc\n\ + * division_start - begin of toc division\n\ + * division_end - end of toc division\n\ + * item - toc element\n\ + * vset - set/get variable values\n\ + * include - insert external file\n\ + * lb, rb - left/right brackets\n\ + " +} + +# ::doctools::toc::new -- +# +# Create a new doctoc object with a given name. May configure the object. +# +# Arguments: +# name Name of the doctoc object. +# args Options configuring the new object. +# +# Results: +# name Name of the doctools created + +proc ::doctools::toc::new {name args} { + if { [llength [info commands ::$name]] } { + return -code error "command \"$name\" already exists, unable to create doctoc object" + } + if {[llength $args] % 2 == 1} { + return -code error "wrong # args: doctools::new name ?opt val...??" + } + + # The arguments seem to be ok, setup the namespace for the object + + namespace eval ::doctools::toc::doctoc$name { + variable paths [list] + variable file "" + variable format "" + variable formatfile "" + variable format_ip "" + variable chk_ip "" + variable expander "[namespace current]::ex" + variable ex_ok 0 + variable msg [list] + variable map ; array set map {} + variable param [list] + } + + # Create the command to manipulate the object + # $name -> ::doctools::toc::DocTocProc $name + interp alias {} ::$name {} ::doctools::toc::DocTocProc $name + + # If the name was followed by arguments use them to configure the + # object before returning its handle to the caller. + + if {[llength $args] > 1} { + # Use linsert trick to make the command a pure list. + eval [linsert $args 0 _configure $name] + } + return $name +} + +########################## +# Private functions follow + +# ::doctools::toc::DocTocProc -- +# +# Command that processes all doctoc object commands. +# Dispatches any object command to the appropriate internal +# command implementing its functionality. +# +# Arguments: +# name Name of the doctoc object to manipulate. +# cmd Subcommand to invoke. +# args Arguments for subcommand. +# +# Results: +# Varies based on command to perform + +proc ::doctools::toc::DocTocProc {name {cmd ""} args} { + # Do minimal args checks here + if { [llength [info level 0]] == 2 } { + error "wrong # args: should be \"$name option ?arg arg ...?\"" + } + + # Split the args into command and args components + + if { [llength [info commands ::doctools::toc::_$cmd]] == 0 } { + variable commands + set optlist [join $commands ", "] + set optlist [linsert $optlist "end-1" "or"] + return -code error "bad option \"$cmd\": must be $optlist" + } + return [eval [list ::doctools::toc::_$cmd $name] $args] +} + +########################## +# Method implementations follow (these are also private commands) + +# ::doctools::toc::_cget -- +# +# Retrieve the current value of a particular option +# +# Arguments: +# name Name of the doctoc object to query +# option Name of the option whose value we are asking for. +# +# Results: +# The value of the option + +proc ::doctools::toc::_cget {name option} { + _configure $name $option +} + +# ::doctools::toc::_configure -- +# +# Configure a doctoc object, or query its configuration. +# +# Arguments: +# name Name of the doctoc object to configure +# args Options and their values. +# +# Results: +# None if configuring the object. +# A list of all options and their values if called without arguments. +# The value of one particular option if called with a single argument. + +proc ::doctools::toc::_configure {name args} { + if {[llength $args] == 0} { + # Retrieve the current configuration. + + upvar #0 ::doctools::toc::doctoc${name}::file file + upvar #0 ::doctools::toc::doctoc${name}::format format + + set res [list] + lappend res -file $file + lappend res -format $format + return $res + + } elseif {[llength $args] == 1} { + # Query the value of one particular option. + + switch -exact -- [lindex $args 0] { + -file { + upvar #0 ::doctools::toc::doctoc${name}::file file + return $file + } + -format { + upvar #0 ::doctools::toc::doctoc${name}::format format + return $format + } + default { + return -code error \ + "doctools::toc::_configure: Unknown option \"[lindex $args 0]\", expected\ + -file, or -format" + } + } + } else { + # Reconfigure the object. + + if {[llength $args] % 2 == 1} { + return -code error "wrong # args: doctools::toc::_configure name ?opt val...??" + } + + foreach {option value} $args { + switch -exact -- $option { + -file { + upvar #0 ::doctools::toc::doctoc${name}::file file + set file $value + } + -format { + if {[catch { + set fmtfile [LookupFormat $name $value] + SetupFormatter $name $fmtfile + upvar #0 ::doctools::toc::doctoc${name}::format format + set format $value + } msg]} { + return -code error \ + -errorinfo $::errorInfo \ + "doctools::toc::_configure: -format: $msg" + } + } + default { + return -code error \ + "doctools::toc::_configure: Unknown option \"$option\", expected\ + -file, or -format" + } + } + } + } + return "" +} + +# ::doctools::toc::_destroy -- +# +# Destroy a doctoc object, including its associated command and data storage. +# +# Arguments: +# name Name of the doctoc object to destroy. +# +# Results: +# None. + +proc ::doctools::toc::_destroy {name} { + # Check the object for sub objects which have to destroyed before + # the namespace is torn down. + namespace eval ::doctools::toc::doctoc$name { + if {$format_ip != ""} {interp delete $format_ip} + if {$chk_ip != ""} {interp delete $chk_ip} + + # Expander objects have no delete/destroy method. This would + # be a leak if not for the fact that an expander object is a + # namespace, and we have arranged to make it a sub namespace of + # the doctoc object. Therefore tearing down our object namespace + # also cleans up the expander object. + # if {$expander != ""} {$expander destroy} + + } + namespace delete ::doctools::toc::doctoc$name + interp alias {} ::$name {} + return +} + +# ::doctools::toc::_map -- +# +# Add a mapping from symbolic to actual filename to the object. +# +# Arguments: +# name Name of the doctoc object to use +# sfname Symbolic filename to map +# afname Actual filename +# +# Results: +# None. + +proc ::doctools::toc::_map {name sfname afname} { + upvar #0 ::doctools::toc::doctoc${name}::map map + set map($sfname) $afname + return +} + +# ::doctools::toc::_format -- +# +# Convert some text in doctools format +# according to the configuration in the object. +# +# Arguments: +# name Name of the doctoc object to use +# text Text to convert. +# +# Results: +# The conversion result. + +proc ::doctools::toc::_format {name text} { + upvar #0 ::doctools::toc::doctoc${name}::format format + if {$format == ""} { + return -code error "$name: No format was specified" + } + + upvar #0 ::doctools::toc::doctoc${name}::format_ip format_ip + upvar #0 ::doctools::toc::doctoc${name}::chk_ip chk_ip + upvar #0 ::doctools::toc::doctoc${name}::ex_ok ex_ok + upvar #0 ::doctools::toc::doctoc${name}::expander expander + upvar #0 ::doctools::toc::doctoc${name}::passes passes + upvar #0 ::doctools::toc::doctoc${name}::msg warnings + + if {!$ex_ok} {SetupExpander $name} + if {$chk_ip == ""} {SetupChecker $name} + # assert (format_ip != "") + + set warnings [list] + if {[catch {$format_ip eval toc_initialize}]} { + return -code error "Could not initialize engine" + } + set result "" + + for { + set p $passes ; set n 1 + } { + $p > 0 + } { + incr p -1 ; incr n + } { + if {[catch {$format_ip eval [list toc_setup $n]}]} { + catch {$format_ip eval toc_shutdown} + return -code error "Could not initialize pass $n of engine" + } + $chk_ip eval ck_initialize + + if {[catch {set result [$expander expand $text]} msg]} { + catch {$format_ip eval toc_shutdown} + # Filter for checker errors and reduce them to the essential message. + + if {![regexp {^Error in} $msg]} {return -code error $msg} + #set msg [join [lrange [split $msg \n] 2 end]] + + if {![regexp {^--> \(FmtError\) } $msg]} {return -code error "Doctoc $msg"} + set msg [lindex [split $msg \n] 0] + regsub {^--> \(FmtError\) } $msg {} msg + + return -code error $msg + } + + $chk_ip eval ck_complete + } + + if {[catch {set result [$format_ip eval [list toc_postprocess $result]]}]} { + return -code error "Unable to post process final result" + } + if {[catch {$format_ip eval toc_shutdown}]} { + return -code error "Could not shut engine down" + } + return $result + +} + +# ::doctools::toc::_search -- +# +# Add a search path to the object. +# +# Arguments: +# name Name of the doctoc object to extend +# path Search path to add. +# +# Results: +# None. + +proc ::doctools::toc::_search {name path} { + if {![file exists $path]} {return -code error "$name search: path does not exist"} + if {![file isdirectory $path]} {return -code error "$name search: path is not a directory"} + if {![file readable $path]} {return -code error "$name search: path cannot be read"} + + upvar #0 ::doctools::toc::doctoc${name}::paths paths + set paths [linsert $paths 0 $path] + return +} + +# ::doctools::toc::_warnings -- +# +# Return the warning accumulated during the last invocation of 'format'. +# +# Arguments: +# name Name of the doctoc object to query +# +# Results: +# A list of warnings. + +proc ::doctools::toc::_warnings {name} { + upvar #0 ::doctools::toc::doctoc${name}::msg msg + return $msg +} + +# ::doctools::_parameters -- +# +# Returns a list containing the parameters provided +# by the selected formatting engine. +# +# Arguments: +# name Name of the doctools object to query +# +# Results: +# A list of parameter names + +proc ::doctools::toc::_parameters {name} { + upvar #0 ::doctools::toc::doctoc${name}::param param + return $param +} + +# ::doctools::_setparam -- +# +# Set a named engine parameter to a value. +# +# Arguments: +# name Name of the doctools object to query +# param Name of the parameter to set. +# value Value to set the parameter to. +# +# Results: +# None. + +proc ::doctools::toc::_setparam {name param value} { + upvar #0 ::doctools::toc::doctoc${name}::format_ip format_ip + + if {$format_ip == {}} { + return -code error \ + "Unable to set parameters without a valid format" + } + + $format_ip eval [list toc_varset $param $value] + return +} + +########################## +# Support commands + +# ::doctools::toc::LookupFormat -- +# +# Search a format definition file based upon its name +# +# Arguments: +# name Name of the doctoc object to use +# format Name of the format to look for. +# +# Results: +# The file containing the format definition + +proc ::doctools::toc::LookupFormat {name format} { + # Order of searching + # 1) Is the name of the format an existing file ? + # If yes, take this file. + # 2) Look for the file in the directories given to the object itself.. + # 3) Look for the file in the standard directories of this package. + + if {[file exists $format] && [file isfile $format]} { + return $format + } + + upvar #0 ::doctools::toc::doctoc${name}::paths opaths + foreach path $opaths { + set f [file join $path toc.$format] + if {[file exists $f] && [file isfile $f]} { + return $f + } + } + + variable paths + foreach path $paths { + set f [file join $path toc.$format] + if {[file exists $f] && [file isfile $f]} { + return $f + } + } + + return -code error "Unknown format \"$format\"" +} + +# ::doctools::toc::SetupFormatter -- +# +# Create and initializes an interpreter containing a +# formatting engine +# +# Arguments: +# name Name of the doctoc object to manipulate +# format Name of file containing the code of the engine +# +# Results: +# None. + +proc ::doctools::toc::SetupFormatter {name format} { + + # Create and initialize the interpreter first. + # Use a transient variable. Interrogate the + # engine and check its response. Bail out in + # case of errors. Only if we pass the checks + # we tear down the old engine and make the new + # one official. + + variable here + set mpip [interp create -safe] ; # interpreter for the formatting engine + #set mpip [interp create] ; # interpreter for the formatting engine + + $mpip invokehidden source [file join $here api_toc.tcl] + #$mpip eval [list source [file join $here api_toc.tcl]] + interp alias $mpip dt_source {} ::doctools::toc::Source $mpip [file dirname $format] + interp alias $mpip dt_read {} ::doctools::toc::Read $mpip [file dirname $format] + interp alias $mpip dt_package {} ::doctools::toc::Package $mpip + interp alias $mpip file {} ::doctools::toc::FileOp $mpip + interp alias $mpip puts_stderr {} ::puts stderr + $mpip invokehidden source $format + #$mpip eval [list source $format] + + # Check the engine for useability in doctools. + + foreach api { + toc_numpasses + toc_initialize + toc_setup + toc_postprocess + toc_shutdown + toc_listvariables + toc_varset + } { + if {[$mpip eval [list info commands $api]] == {}} { + interp delete $mpip + error "$format error: API incomplete, cannot use this engine" + } + } + if {[catch { + set passes [$mpip eval toc_numpasses] + }]} { + interp delete $mpip + error "$format error: Unable to query for number of passes" + } + if {![string is integer $passes] || ($passes < 1)} { + interp delete $mpip + error "$format error: illegal number of passes \"$passes\"" + } + if {[catch { + set parameters [$mpip eval toc_listvariables] + }]} { + interp delete $mpip + error "$format error: Unable to query for list of parameters" + } + + # Passed the tests. Tear down existing engine, + # and checker. The latter is destroyed because + # of its aliases into the formatter, which are + # now invalid. It will be recreated during the + # next call of 'format'. + + upvar #0 ::doctools::toc::doctoc${name}::formatfile formatfile + upvar #0 ::doctools::toc::doctoc${name}::format_ip format_ip + upvar #0 ::doctools::toc::doctoc${name}::chk_ip chk_ip + upvar #0 ::doctools::toc::doctoc${name}::expander expander + upvar #0 ::doctools::toc::doctoc${name}::passes xpasses + upvar #0 ::doctools::toc::doctoc${name}::param xparam + + if {$chk_ip != {}} {interp delete $chk_ip} + if {$format_ip != {}} {interp delete $format_ip} + + set chk_ip "" + set format_ip "" + + # Now link engine API into it. + + interp alias $mpip dt_format {} ::doctools::toc::GetFormat $name + interp alias $mpip dt_user {} ::doctools::toc::GetUser $name + interp alias $mpip dt_fmap {} ::doctools::toc::MapFile $name + + foreach cmd {cappend cget cis cname cpop cpush cset lb rb} { + interp alias $mpip ex_$cmd {} $expander $cmd + } + + set format_ip $mpip + set formatfile $format + set xpasses $passes + set xparam $parameters + return +} + +# ::doctools::toc::SetupChecker -- +# +# Create and initializes an interpreter for checking the usage of +# doctoc formatting commands +# +# Arguments: +# name Name of the doctoc object to manipulate +# +# Results: +# None. + +proc ::doctools::toc::SetupChecker {name} { + # Create an interpreter for checking the usage of doctoc formatting commands + # and initialize it: Link it to the interpreter doing the formatting, the + # expander object and the configuration information. All of which + # is accessible through the token/handle (name of state/object array). + + variable here + + upvar #0 ::doctools::toc::doctoc${name}::chk_ip chk_ip + if {$chk_ip != ""} {return} + + upvar #0 ::doctools::toc::doctoc${name}::expander expander + upvar #0 ::doctools::toc::doctoc${name}::format_ip format_ip + + set chk_ip [interp create] ; # interpreter hosting the formal format checker + + # Make configuration available through command, then load the code base. + + foreach {cmd ckcmd} { + dt_search SearchPaths + dt_error FmtError + dt_warning FmtWarning + } { + interp alias $chk_ip $cmd {} ::doctools::toc::$ckcmd $name + } + $chk_ip eval [list source [file join $here checker_toc.tcl]] + + # Simple expander commands are directly routed back into it, no + # checking required. + + foreach cmd {cappend cget cis cname cpop cpush cset lb rb} { + interp alias $chk_ip $cmd {} $expander $cmd + } + + # Link the formatter commands into the checker. We use the prefix + # 'fmt_' to distinguish them from the checking commands. + + foreach cmd { + toc_begin toc_end division_start division_end item + comment plain_text + } { + interp alias $chk_ip fmt_$cmd $format_ip fmt_$cmd + } + return +} + +# ::doctools::toc::SetupExpander -- +# +# Create and initializes the expander for input +# +# Arguments: +# name Name of the doctoc object to manipulate +# +# Results: +# None. + +proc ::doctools::toc::SetupExpander {name} { + upvar #0 ::doctools::toc::doctoc${name}::ex_ok ex_ok + if {$ex_ok} {return} + + upvar #0 ::doctools::toc::doctoc${name}::expander expander + ::textutil::expander $expander + $expander evalcmd [list ::doctools::toc::Eval $name] + $expander textcmd plain_text + set ex_ok 1 + return +} + +# ::doctools::toc::SearchPaths -- +# +# API for checker. Returns list of search paths for format +# definitions. Used to look for message catalogs as well. +# +# Arguments: +# name Name of the doctoc object to query. +# +# Results: +# None. + +proc ::doctools::toc::SearchPaths {name} { + upvar #0 ::doctools::toc::doctoc${name}::paths opaths + variable paths + + set p $opaths + foreach s $paths {lappend p $s} + return $p +} + +# ::doctools::toc::FmtError -- +# +# API for checker. Called when an error occurred. +# +# Arguments: +# name Name of the doctoc object to query. +# text Error message +# +# Results: +# None. + +proc ::doctools::toc::FmtError {name text} { + return -code error "(FmtError) $text" +} + +# ::doctools::toc::FmtWarning -- +# +# API for checker. Called when a warning was generated +# +# Arguments: +# name Name of the doctoc object +# text Warning message +# +# Results: +# None. + +proc ::doctools::toc::FmtWarning {name text} { + upvar #0 ::doctools::toc::doctoc${name}::msg msg + lappend msg $text + return +} + +# ::doctools::toc::Eval -- +# +# API for expander. Routes the macro invocations +# into the checker interpreter +# +# Arguments: +# name Name of the doctoc object to query. +# +# Results: +# None. + +proc ::doctools::toc::Eval {name macro} { + upvar #0 ::doctools::toc::doctoc${name}::chk_ip chk_ip + + # Handle the [include] command directly + if {[string match include* $macro]} { + set macro [$chk_ip eval [list subst $macro]] + foreach {cmd filename} $macro break + return [ExpandInclude $name $filename] + } + + return [$chk_ip eval $macro] +} + +# ::doctools::toc::ExpandInclude -- +# +# Handle inclusion of files. +# +# Arguments: +# name Name of the doctoc object to query. +# path Name of file to include and expand. +# +# Results: +# None. + +proc ::doctools::toc::ExpandInclude {name path} { + # Look for the file relative to the directory of the + # main file we are converting. If that fails try to + # use the current working directory. Throw an error + # if the file couldn't be found. + + upvar #0 ::doctools::toc::doctoc${name}::file file + + set ipath [file normalize [file join [file dirname $file] $path]] + if {![file exists $ipath]} { + set ipath $path + if {![file exists $ipath]} { + return -code error "Unable to fine include file \"$path\"" + } + } + + set chan [open $ipath r] + set text [read $chan] + close $chan + + upvar #0 ::doctools::toc::doctoc${name}::expander expander + + set saved $file + set file $ipath + set res [$expander expand $text] + set file $saved + + return $res +} + +# ::doctools::toc::GetUser -- +# +# API for formatter. Returns name of current user +# +# Arguments: +# name Name of the doctoc object to query. +# +# Results: +# String, name of current user. + +proc ::doctools::toc::GetUser {name} { + global tcl_platform + return $tcl_platform(user) +} + +# ::doctools::toc::GetFormat -- +# +# API for formatter. Returns format information +# +# Arguments: +# name Name of the doctoc object to query. +# +# Results: +# Format information + +proc ::doctools::toc::GetFormat {name} { + upvar #0 ::doctools::toc::doctoc${name}::format format + return $format +} + +# ::doctools::toc::MapFile -- +# +# API for formatter. Maps symbolic to actual filename in a toc +# item. If no mapping is found it is assumed that the symbolic +# name is also the actual name. +# +# Arguments: +# name Name of the doctoc object to query. +# fname Symbolic name of the file. +# +# Results: +# Actual name of the file. + +proc ::doctools::toc::MapFile {name fname} { + upvar #0 ::doctools::toc::doctoc${name}::map map + if {[info exists map($fname)]} { + return $map($fname) + } + return $fname +} + +# ::doctools::toc::Source -- +# +# API for formatter. Used by engine to ask for +# additional script files support it. +# +# Arguments: +# name Name of the doctoc object to change. +# +# Results: +# Boolean flag. + +proc ::doctools::toc::Source {ip path file} { + $ip invokehidden source [file join $path [file tail $file]] + #$ip eval [list source [file join $path [file tail $file]]] + return +} + +proc ::doctools::toc::Read {ip path file} { + #puts stderr "$ip (read $path $file)" + + return [read [set f [open [file join $path [file tail $file]]]]][close $f] +} + +proc ::doctools::toc::FileOp {ip args} { + #puts stderr "$ip (file $args)" + # -- FUTURE -- disallow unsafe operations -- + + return [eval [linsert $args 0 file]] +} + +proc ::doctools::toc::Package {ip pkg} { + #puts stderr "$ip package require $pkg" + + set indexScript [Locate $pkg] + + $ip expose source + $ip expose load + $ip eval $indexScript + $ip hide source + $ip hide load + #$ip eval [list source [file join $path [file tail $file]]] + return +} + +proc ::doctools::toc::Locate {p} { + # @mdgen NODEP: doctools::__undefined__ + catch {package require doctools::__undefined__} + + #puts stderr "auto_path = [join $::auto_path \n]" + + # Check if requested package is in the list of loadable packages. + # Then get the highest possible version, and then the index script + + if {[lsearch -exact [package names] $p] < 0} { + return -code error "Unknown package $p" + } + + set v [lindex [lsort -increasing [package versions $p]] end] + + #puts stderr "Package $p = $v" + + return [package ifneeded $p $v] +} + +#------------------------------------ +# Module initialization + +namespace eval ::doctools::toc { + # Reverse order of searching. First to search is specified last. + + # FOO/doctoc.tcl + # => FOO/mpformats + + #catch {search [file join $here lib doctools mpformats]} + #catch {search [file join [file dirname $here] lib doctools mpformats]} + catch {search [file join $here mpformats]} +} + +package provide doctools::toc 1.1.4 diff --git a/tcllib/modules/doctools/doctoc.test b/tcllib/modules/doctools/doctoc.test new file mode 100644 index 0000000..da6e752 --- /dev/null +++ b/tcllib/modules/doctools/doctoc.test @@ -0,0 +1,319 @@ +# -*- tcl -*- +# doctoc.test: tests for the doctools::toc package. +# +# This file contains a collection of tests for one or more of the Tcl +# built-in commands. Sourcing this file into Tcl runs the tests and +# generates output for errors. No output means no errors were found. +# +# Copyright (c) 2003-2009 by Andreas Kupries <andreas_kupries@users.sourceforge.net> +# All rights reserved. +# +# RCS: @(#) $Id: doctoc.test,v 1.14 2009/02/12 05:42:47 andreas_kupries Exp $ + +# ------------------------------------------------------------------------- + +source [file join \ + [file dirname [file dirname [file join [pwd] [info script]]]] \ + devtools testutilities.tcl] + +testsNeedTcl 8.2 +testsNeedTcltest 1.0 + +support { + use textutil/expander.tcl textutil::expander +} +testing { + useLocal doctoc.tcl doctools::toc +} + +# ------------------------------------------------------------------------- + +array_unset env LANG* +array_unset env LC_* +set env(LANG) C ; # Usually default if nothing is set, OS X requires this. + +# ------------------------------------------------------------------------- + +namespace import ::doctools::toc::new + +# search paths ............................................................. + +test doctoc-1.0 {default search paths} { + llength $::doctools::toc::paths +} 1 + +test doctoc-1.1 {extend package search paths} { + ::doctools::toc::search [file dirname [info script]] + set res [list] + lappend res [llength $::doctools::toc::paths] + lappend res [lindex $::doctools::toc::paths 0] + set res +} [list 2 [file dirname [info script]]] + +test doctoc-1.2 {extend package search paths, error} { + catch {::doctools::toc::search foo} result + set result +} {doctools::toc::search: path does not exist} + +# format help ............................................................. + +test doctoc-2.0 {format help} { + string length [doctools::toc::help] +} 338 + +# doctoc ............................................................. + +test doctoc-3.0 {doctoc errors} { + catch {new} msg + set msg +} [tcltest::wrongNumArgs "new" "name args" 0] + +test doctoc-3.1 {doctoc errors} { + catch {new set} msg + set msg +} "command \"set\" already exists, unable to create doctoc object" + +test doctoc-3.2 {doctoc errors} { + new mydoctoc + catch {new mydoctoc} msg + mydoctoc destroy + set msg +} "command \"mydoctoc\" already exists, unable to create doctoc object" + +test doctoc-3.3 {doctoc errors} { + catch {new mydoctoc -foo} msg + set msg +} {wrong # args: doctools::new name ?opt val...??} + +# doctoc methods ...................................................... + +test doctoc-4.0 {doctoc method errors} { + new mydoctoc + catch {mydoctoc} msg + mydoctoc destroy + set msg +} "wrong # args: should be \"mydoctoc option ?arg arg ...?\"" + +test doctoc-4.1 {doctoc errors} { + new mydoctoc + catch {mydoctoc foo} msg + mydoctoc destroy + set msg +} "bad option \"foo\": must be cget, configure, destroy, format, map, search, warnings, parameters, or setparam" + +# cget .................................................................. + +test doctoc-5.0 {cget errors} { + new mydoctoc + catch {mydoctoc cget} result + mydoctoc destroy + set result +} [tcltest::wrongNumArgs "::doctools::toc::_cget" "name option" 1] + +test doctoc-5.1 {cget errors} { + new mydoctoc + catch {mydoctoc cget foo bar} result + mydoctoc destroy + set result +} [tcltest::tooManyArgs "::doctools::toc::_cget" "name option"] + +test doctoc-5.2 {cget errors} { + new mydoctoc + catch {mydoctoc cget -foo} result + mydoctoc destroy + set result +} {doctools::toc::_configure: Unknown option "-foo", expected -file, or -format} + +foreach {na nb option default newvalue} { + 3 4 -file {} foo + 5 6 -format {} html +} { + test doctoc-5.$na {cget query} { + new mydoctoc + set res [mydoctoc cget $option] + mydoctoc destroy + set res + } $default ; # {} + + test doctoc-5.$nb {cget set & query} { + new mydoctoc + mydoctoc configure $option $newvalue + set res [mydoctoc cget $option] + mydoctoc destroy + set res + } $newvalue ; # {} +} + +# configure .................................................................. + +test doctoc-6.0 {configure errors} { + new mydoctoc + catch {mydoctoc configure -foo bar -glub} result + mydoctoc destroy + set result +} {wrong # args: doctools::toc::_configure name ?opt val...??} +# [tcltest::wrongNumArgs "::doctools::toc::_configure" "name ?option?|?option value...?" 1] + +test doctoc-6.1 {configure errors} { + new mydoctoc + catch {mydoctoc configure -foo} result + mydoctoc destroy + set result +} {doctools::toc::_configure: Unknown option "-foo", expected -file, or -format} + +test doctoc-6.2 {configure retrieval} { + new mydoctoc + catch {mydoctoc configure} result + mydoctoc destroy + set result +} {-file {} -format {}} + +foreach {n option illegalvalue result} { + 3 -format barf {doctools::toc::_configure: -format: Unknown format "barf"} +} { + test doctoc-6.$n {configure illegal value} { + new mydoctoc + catch {mydoctoc configure $option $illegalvalue} result + mydoctoc destroy + set result + } $result +} + +foreach {na nb option default newvalue} { + 4 5 -file {} foo + 6 7 -format {} html +} { + test doctoc-6.$na {configure query} { + new mydoctoc + set res [mydoctoc configure $option] + mydoctoc destroy + set res + } $default ; # {} + + test doctoc-6.$nb {configure set & query} { + new mydoctoc + mydoctoc configure $option $newvalue + set res [mydoctoc configure $option] + mydoctoc destroy + set res + } $newvalue ; # {} +} + +test doctoc-6.8 {configure full retrieval} { + new mydoctoc -file foo -format html + catch {mydoctoc configure} result + mydoctoc destroy + set result +} {-file foo -format html} + +# search .................................................................. + +test doctoc-7.0 {search errors} { + new mydoctoc + catch {mydoctoc search} result + mydoctoc destroy + set result +} [tcltest::wrongNumArgs "::doctools::toc::_search" "name path" 1] + +test doctoc-7.1 {search errors} { + new mydoctoc + catch {mydoctoc search foo bar} result + mydoctoc destroy + set result +} [tcltest::tooManyArgs "::doctools::toc::_search" "name path"] + +test doctoc-7.2 {search errors} { + new mydoctoc + catch {mydoctoc search foo} result + mydoctoc destroy + set result +} {mydoctoc search: path does not exist} + +test doctoc-7.3 {search, initial} { + new mydoctoc + set res [llength $::doctools::toc::doctocmydoctoc::paths] + mydoctoc destroy + set res +} 0 + +test doctoc-7.4 {extend object search paths} { + new mydoctoc + mydoctoc search [file dirname [info script]] + set res [list] + lappend res [llength $::doctools::toc::doctocmydoctoc::paths] + lappend res [lindex $::doctools::toc::doctocmydoctoc::paths 0] + mydoctoc destroy + set res +} [list 1 [file dirname [info script]]] + +# format & warnings ....................................................... + +test doctoc-8.0 {format errors} { + new mydoctoc + catch {mydoctoc format} result + mydoctoc destroy + set result +} [tcltest::wrongNumArgs "::doctools::toc::_format" "name text" 1] + +test doctoc-8.1 {format errors} { + new mydoctoc + catch {mydoctoc format foo bar} result + mydoctoc destroy + set result +} [tcltest::tooManyArgs "::doctools::toc::_format" "name text"] + +test doctoc-8.2 {format errors} { + new mydoctoc + catch {mydoctoc format foo} result + mydoctoc destroy + set result +} {mydoctoc: No format was specified} + + +test doctoc-8.3 {format} { + new mydoctoc -format wiki + set res [mydoctoc format {[toc_begin foo bar][item at snafu gnarf][toc_end]}] + lappend res [mydoctoc warnings] + mydoctoc destroy + set res +} {Table of Contents '''foo''' '''bar''' {[[snafu]]:} at -- gnarf {}} + + +# doctoc syntax ....................................................... + +test doctoc-9.0 {doctoc syntax} { + new mydoctoc -format null + catch {mydoctoc format foo} result + mydoctoc destroy + set result +} {Doctoc Error in plain text at line 1, column 0: +[plain_text foo] +--> (FmtError) TOC error (toc/plaintext), "plain_text foo" : Plain text beyond whitespace is not allowed..} + +test docidx-9.1 {doctoc syntax v1.1, empty toc, ok} { + new mydocidx -format null + set result [mydocidx format {[toc_begin TOC Test][toc_end]}] + mydocidx destroy + set result +} {} + +test docidx-9.2 {doctoc syntax v1.1, mixing items and divisions, ok} { + new mydocidx -format null + set result [mydocidx format {[toc_begin TOC Test][item I1f i1 i1d][division_start D Df][item I2f i2 i2d][division_end][toc_end]}] + mydocidx destroy + set result +} {} + +test docidx-9.3 {doctoc syntax v1.1, empty division, ok} { + new mydocidx -format null + set result [mydocidx format {[toc_begin TOC Test][division_start D Df][division_end][toc_end]}] + mydocidx destroy + set result +} {} + +namespace forget ::doctools::toc::new + +# ------------------------------------------------------------------------- + +testsuiteCleanup +return diff --git a/tcllib/modules/doctools/doctoc_intro.man b/tcllib/modules/doctools/doctoc_intro.man new file mode 100644 index 0000000..80a3f4d --- /dev/null +++ b/tcllib/modules/doctools/doctoc_intro.man @@ -0,0 +1,105 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctoc_intro n 1.0] +[see_also docidx_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[see_also doctoc_plugin_apiref] +[see_also doctools::toc] +[see_also doctools_intro] +[keywords markup] +[keywords {semantic markup}] +[keywords {table of contents}] +[keywords toc] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc introduction}] +[category {Documentation tools}] +[description] +[para] + +[term doctoc] (short for [emph {documentation tables of contents}]) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of tables of +contents for documentation. These are + +[list_begin enumerated] +[enum] + +A tcl based language for the semantic markup of a table of +contents. Markup is represented by Tcl commands. + +[enum] + +A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins. + +[enum] + +An API describing the interface between the package above and a +plugin. + +[list_end] + +[para] + +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. + +[para] + +[list_begin enumerated] +[enum] +A [term writer] of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +[term {doctoc language introduction}] first. Having digested this +the formal [term {doctoc language syntax}] specification should +become understandable. A writer experienced with doctoc may only +need the [term {doctoc language command reference}] from time to +time to refresh her memory. + +[para] + +While a document is written the [syscmd dtp] application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler [syscmd dtplite] application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them. + +[enum] +A [term processor] of documentation written in the [term doctoc] +markup language has to know which tools are available for use. + +[para] + +The main tool is the aforementioned [syscmd dtp] application provided +by Tcllib. The simpler [syscmd dtplite] does not expose doctoc to the +user. + +At the bottom level, common to both applications, however sits the +package [package doctoools::toc], providing the basic facilities to +read and process files containing text in the doctoc format. + +[enum] +At last, but not least, [term {plugin writers}] have to understand the +interaction between the [package doctools::toc] package and its +plugins, as described in the [term {doctoc plugin API reference}]. + +[list_end] + +[section {RELATED FORMATS}] + +doctoc does not stand alone, it has two companion formats. These are +called [term docidx] and [term doctools], and they are for the markup +of [term {keyword indices}], and general documentation, respectively. + +They are described in their own sets of documents, starting at the +[term {docidx introduction}] and the [term {doctools introduction}], +respectively. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc_lang_cmdref.man b/tcllib/modules/doctools/doctoc_lang_cmdref.man new file mode 100644 index 0000000..eef57cf --- /dev/null +++ b/tcllib/modules/doctools/doctoc_lang_cmdref.man @@ -0,0 +1,127 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctoc_lang_cmdref n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc language command reference}] +[category {Documentation tools}] +[description] +[para] + +This document specifies both names and syntax of all the commands +which together are the doctoc markup language, version 1. + +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. + +A beginner should read the much more informally written +[term {doctoc language introduction}] first. + +[section Commands] +[list_begin definitions] + +[call [cmd comment] [arg plaintext]] + +Toc markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text. + +[call [cmd division_end]] + +Toc structure. This command closes the division opened by the last +[cmd division_begin] command coming before it, and not yet closed. + +[call [cmd division_start] [arg text] [opt [arg symfile]]] + +Toc structure. This command opens a division in the table of +contents. Its counterpart is [cmd division_end]. Together they allow a +user to give a table of contents additional structure. + +[para] + +The title of the new division is provided by the argument [arg text]. + +[para] + +If the symbolic filename [arg symfile] is present then the section +title should link to the referenced document, if links are supported +by the output format. + +[call [cmd include] [arg filename]] + +Templating. The contents of the named file are interpreted as text +written in the doctoc markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries. + +[call [cmd item] [arg file] [arg text] [arg desc]] + +Toc structure. This command adds an individual element to the table of +contents. Each such element refers to a document. The document is +specified through the symbolic name [arg file]. The [arg text] +argument is used to label the reference, whereas the [arg desc] +provides a short descriptive text of that document. + +[para] + +The symbolic names are used to preserve the convertibility of this +format to any output format. The actual name of the file will be +inserted by the chosen formatting engine when converting the +input. This will be based on a mapping from symbolic to actual names +given to the engine. + +[call [cmd lb]] + +Text. The command is replaced with a left bracket. Use in free-form +text. Required to avoid interpretation of a left bracket as the start +of a markup command. Its usage is restricted to the arguments of other +markup commands. + +[call [cmd rb]] + +Text. The command is replaced with a right bracket. Use in free-form +text. Required to avoid interpretation of a right bracket as the end +of a markup command. Its usage is restricted to the arguments of other +commands. + +[call [cmd toc_begin] [arg text] [arg title]] + +Document structure. The command to start a table of contents. The +arguments are a label for the whole group of documents the index +refers to ([arg text]) and the overall title text for the index +([arg title]), without markup. + +[para] + +The label often is the name of the package (or extension) the +documents belong to. + +[call [cmd toc_end]] + +Document structure. Command to end a table of contents. Anything in +the document coming after this command is in error. + +[call [cmd vset] [arg varname] [arg value] ] + +Templating. In this form the command sets the named document variable +to the specified [arg value]. It does not generate output. I.e. the +command is replaced by the empty string. + +[call [cmd vset] [arg varname]] + +Templating. In this form the command is replaced by the value of the +named document variable + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc_lang_faq.man b/tcllib/modules/doctools/doctoc_lang_faq.man new file mode 100644 index 0000000..1f4df69 --- /dev/null +++ b/tcllib/modules/doctools/doctoc_lang_faq.man @@ -0,0 +1,28 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctoc_lang_faq n 1.0] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords {doctoc syntax}] +[keywords examples] +[keywords faq] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc language faq}] +[category {Documentation tools}] +[description] +[vset theformat doctoc] + +[section OVERVIEW] + +[include include/placeholder.inc] +[include include/examples.inc] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc_lang_intro.man b/tcllib/modules/doctools/doctoc_lang_intro.man new file mode 100644 index 0000000..ca7589d --- /dev/null +++ b/tcllib/modules/doctools/doctoc_lang_intro.man @@ -0,0 +1,297 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctoc_lang_intro n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_syntax] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords {doctoc syntax}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc language introduction}] +[category {Documentation tools}] +[description] +[para] + +This document is an informal introduction to version 1.1 of the doctoc +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the [term {doctoc language syntax}] specification +and the [term {doctoc language command reference}]. + +[subsection Fundamentals] + +While the [term {doctoc markup language}] is quite similar to the +[term {doctools markup language}], in the broadest terms possible, +there is one key difference. A table of contents consists essentially +only of markup commands, with no plain text interspersed between them, +except for whitespace. + +[para] + +Each markup command is a Tcl command surrounded by a matching pair of +[const [lb]] and [const [rb]]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e. + +[para] +[example { + ... [division_start {Appendix 1}] ... +}] + +[example { + ... [item thefile \\ + label {file description}] ... +}] + +[subsection {Basic structure}] + +The most simple document which can be written in doctoc is + +[example { + [toc_begin GROUPTITLE TITLE] + [toc_end] +}] + +This also shows us that all doctoc documents consist of only one +part where we will list [term items] and [term divisions]. + +[para] + +The user is free to mix these as she sees fit. This is a change from +version 1 of the language, which did not allow this mixing, but only +the use of either a series of items or a series of divisions. + +[para] + +We will discuss the commands for each of these two possibilities in +the next sections. + +[subsection Items] + +Use the command [cmd item] to put an [term item] into a table of +contents. This is essentially a reference to a section, subsection, +etc. in the document, or set of documents, the table of contents is +for. The command takes three arguments, a symbolic name for the file +the item is for and two text to label the item and describe the +referenced section. + +[para] + +Symbolic names are used to preserve the convertibility of this format +to any output format. The actual name of any file will be inserted by +the chosen formatting engine when converting the input, based on a +mapping from symbolic to actual names given to the engine. + +[para] + +Here a made up example for a table of contents of this document: + +[example_begin] +[lb]toc_begin Doctoc {Language Introduction}[rb] +[lb][cmd {item 1 DESCRIPTION}][rb] +[lb][cmd {item 1.1 {Basic structure}}][rb] +[lb][cmd {item 1.2 Items}][rb] +[lb][cmd {item 1.3 Divisions}][rb] +[lb][cmd {item 2 {FURTHER READING}}][rb] +[lb]toc_end[rb] +[example_end] + +[subsection Divisions] + +One thing of notice in the last example in the previous section is +that the referenced sections actually had a nested structure, +something which was expressed in the item labels, by using a common +prefix for all the sections nested under section 1. + +[para] + +This kind of structure can be made more explicit in the doctoc +language by using divisions. Instead of using a series of plain items +we use a series of divisions for the major references, and then place +the nested items inside of these. + +[para] + +Of course, instead of the nested items we can again use divisions and +thus nest arbitrarily deep. + +[para] + +A division is marked by two commands instead of one, one to start it, +the other to close the last opened division. They are: + +[list_begin commands] +[cmd_def division_start] + +This command opens a new division. It takes one or two arguments, the +title of the division, and the symbolic name of the file it refers +to. The latter is optional. + +If the symbolic filename is present then the section title should link +to the referenced document, if links are supported by the output +format. + +[cmd_def division_end] +This command closes the last opened and not yet closed division. + +[list_end] + +[para] + +Using this we can recast the last example like this + +[example_begin] +[lb]toc_begin Doctoc {Language Introduction}[rb] +[lb][cmd {division_start DESCRIPTION}][rb] +[lb]item 1 {Basic structure}[rb] +[lb]item 2 Items[rb] +[lb]item 3 Divisions[rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_start {FURTHER READING}}][rb] +[lb][cmd {division_end}][rb] +[lb]toc_end[rb] +[example_end] + +[para] + +Or, to demonstrate deeper nesting + +[example_begin] +[lb]toc_begin Doctoc {Language Introduction}[rb] +[lb][cmd {division_start DESCRIPTION}][rb] +[lb][cmd {division_start {Basic structure}}][rb] +[lb]item 1 Do[rb] +[lb]item 2 Re[rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_start Items}][rb] +[lb]item a Fi[rb] +[lb]item b Fo[rb] +[lb]item c Fa[rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_start Divisions}][rb] +[lb]item 1 Sub[rb] +[lb]item 1 Zero[rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_start {FURTHER READING}}][rb] +[lb][cmd {division_end}][rb] +[lb]toc_end[rb] +[example_end] + +And do not forget, it is possible to freely mix items and divisions, +and to have empty divisions. + +[example_begin] +[lb]toc_begin Doctoc {Language Introduction}[rb] +[lb]item 1 Do[rb] +[lb][cmd {division_start DESCRIPTION}][rb] +[lb][cmd {division_start {Basic structure}}][rb] +[lb]item 2 Re[rb] +[lb][cmd {division_end}][rb] +[lb]item a Fi[rb] +[lb][cmd {division_start Items}][rb] +[lb]item b Fo[rb] +[lb]item c Fa[rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_start Divisions}][rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_end}][rb] +[lb][cmd {division_start {FURTHER READING}}][rb] +[lb][cmd {division_end}][rb] +[lb]toc_end[rb] +[example_end] + +[subsection {Advanced structure}] + +In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the [cmd toc_begin] command opening the +document. + +[para] + +Instead of only whitespace the two templating commands [cmd include] +and [cmd vset] are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the table of +contents. I.e. it is possible to write + +[example_begin] +[lb][cmd {include FILE}][rb] +[lb][cmd {vset VAR VALUE}][rb] +[lb]toc_begin GROUPTITLE TITLE[rb] +... +[lb]toc_end[rb] +[example_end] + +Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. + +[example_begin] +[lb]toc_begin GROUPTITLE TITLE[rb] +[lb][cmd {include FILE}][rb] +[lb][cmd {vset VAR VALUE}][rb] +... +[lb]toc_end[rb] +[example_end] + +The only restriction [cmd include] has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before [cmd toc_begin] may contain only the templating +commands [cmd vset] and [cmd include], a file included in a division +may contain only items or divisions commands, etc. + +[subsection Escapes] + +Beyond the 6 commands shown so far we have two more available. + +However their function is not the marking up of toc structure, but the +insertion of characters, namely [const [lb]] and [const [rb]]. + +These commands, [cmd lb] and [cmd rb] respectively, are required +because our use of [lb] and [rb] to bracket markup commands makes it +impossible to directly use [lb] and [rb] within the text. + +[para] + +Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added. + +[example_begin] + ... + These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required + because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it + impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. + ... +[example_end] + +[section {FURTHER READING}] + +Now that this document has been digested the reader, assumed to be a +[term writer] of documentation should be fortified enough to be able +to understand the formal [term {doctoc language syntax}] +specification as well. From here on out the +[term {doctoc language command reference}] will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax. + +[para] + +To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +[syscmd dtp]. + +[para] + +On the other hand, doctoc is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple [syscmd dtplite] goes, creating a table of contents +for a set of documents behind the scenes, without the writer having to +do so on their own. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc_lang_syntax.man b/tcllib/modules/doctools/doctoc_lang_syntax.man new file mode 100644 index 0000000..d9f0a0c --- /dev/null +++ b/tcllib/modules/doctools/doctoc_lang_syntax.man @@ -0,0 +1,105 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctoc_lang_syntax n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[keywords {doctoc commands}] +[keywords {doctoc language}] +[keywords {doctoc markup}] +[keywords {doctoc syntax}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc language syntax}] +[category {Documentation tools}] +[description] +[para] + +This document contains the formal specification of the syntax of the +doctoc markup language, version 1.1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +[term {doctoc language command reference}]. + +A beginner should read the much more informally written +[term {doctoc language introduction}] first before trying to +understand either this document or the command reference. + +[section Fundamentals] + +In the broadest terms possible the [term {doctoc markup language}] is +like SGML and similar languages. A document written in this language +consists primarily of markup commands, with text embedded into it at +some places. + +[para] + +Each markup command is a just Tcl command surrounded by a matching +pair of [const [lb]] and [const [rb]]. Which commands are available, +and their arguments, i.e. syntax is specified in the +[term {doctoc language command reference}]. + +[para] + +In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other. + +[section {Lexical definitions}] + +In the syntax rules listed in the next section + +[list_begin enumerated] +[enum] +<TEXT> stands for all text except markup commands. + +[enum] +Any XXX stands for the markup command [lb]xxx[rb] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [const [lb]] and [const [rb]]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc. + +[enum] +<WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the [cmd comment] markup command. +[list_end] + +[section Syntax] + +The rules listed here specify only the syntax of doctoc documents. The +lexical level of the language was covered in the previous section. + +[para] + +Regarding the syntax of the (E)BNF itself + +[list_begin enumerated] +[enum] +The construct { X } stands for zero or more occurrences of X. +[enum] +The construct [lb] X [rb] stands for zero or one occurrence of X. +[list_end] + +The syntax: + +[example { +toc = defs + TOC_BEGIN + contents + TOC_END + { <WHITE> } + +defs = { INCLUDE | VSET | <WHITE> } +contents = { defs entry } [ defs ] + +entry = ITEM | division + +division = DIVISION_START + contents + DIVISION_END +}] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctoc_plugin_apiref.man b/tcllib/modules/doctools/doctoc_plugin_apiref.man new file mode 100644 index 0000000..5e034a5 --- /dev/null +++ b/tcllib/modules/doctools/doctoc_plugin_apiref.man @@ -0,0 +1,421 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctoc_plugin_apiref n 1.0] +[see_also doctoc_intro] +[see_also doctoc_lang_cmdref] +[see_also doctoc_lang_faq] +[see_also doctoc_lang_intro] +[see_also doctoc_lang_syntax] +[see_also doctools::toc] +[keywords {formatting engine}] +[keywords markup] +[keywords plugin] +[keywords {semantic markup}] +[keywords {table of contents}] +[keywords toc] +[keywords {toc formatter}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctoc plugin API reference}] +[category {Documentation tools}] +[description] +[para] + +This document is intended for [term {plugin writers}], i.e. developers +wishing to write a toc [term {formatting engine}] for some output +format X. + +[para] + +It specifies the interaction between the [package doctools::toc] +package and its plugins, i.e. the interface any toc formatting engine +has to comply with. + +[para] + +This document deals with version 1 of the interface. + +[para] + +A reader who is on the other hand more interested in the markup +language itself should start with the + +[term {doctoc language introduction}] and proceed from there to the +formal specifications, i.e. the [term {doctoc language syntax}] and +the [term {doctoc language command reference}]. + +[section OVERVIEW] + +The API for a toc formatting engine consists of two major sections. + +[para] + +On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +[sectref {FRONTEND COMMANDS}] for their detailed specification. + +[para] + +And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. + +Please see section [sectref {PLUGIN COMMANDS}] and its subsections for +their detailed specification. + +[section {FRONTEND COMMANDS}] + +This section specifies the set of commands through which a plugin, +also known as a toc formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter. + +[para] + +I.e. a toc formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section [sectref {PLUGIN COMMANDS}]) are executed. + +[para] + +Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. + +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop. + +[para] + +Coming back to the imported commands, all the commands with prefix +[emph dt_] provide limited access to specific parts of the frontend, +whereas the commands with prefix [emph ex_] provide access to the +state of the [package textutil::expander] object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances. + +[para] + +[list_begin definitions] + +[call [cmd dt_fmap] [arg symfname]] + +Query command. It returns the actual pathname to use in the output in +place of the symbolic filename [arg symfname]. It will return the +unchanged input if no mapping was established for [arg symfname]. + +[para] + +The required mappings are established with the method [method map] of +a frontend, as explained in section [sectref-external {OBJECT METHODS}] +of the documentation for the package [package doctools::toc]. + +[call [cmd dt_format]] + +Query command. It returns the name of the format associated with the +toc formatting engine. + +[call [cmd dt_read] [arg file]] + +Controlled filesystem access. Returns contents of [arg file] for +whatever use desired by the plugin. + +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error. + +[call [cmd dt_source] [arg file]] + +Controlled filesystem access. This command allows the toc formatting +engine to load additional Tcl code it may need. + +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error. + +[call [cmd ex_cappend] [arg text]] +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. + +[call [cmd ex_cget] [arg varname]] +Retrieves the value of variable [arg varname], defined in the current +context. + +[call [cmd ex_cis] [arg cname]] +Determines whether or not the name of the current context is +[arg cname]. + +[call [cmd ex_cname]] +Returns the name of the current context. + +[call [cmd ex_cpop] [arg cname]] +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named [arg cname], or an +error results. + +[call [cmd ex_cpush] [arg cname]] +Pushes a context named [arg cname] onto the context stack. The +context must be popped by [method cpop] before expansion ends or an +error results. + +[call [cmd ex_cset] [arg varname] [arg value]] +Sets variable [arg varname] to [arg value] in the current context. + +[call [cmd ex_lb] [opt [arg newbracket]]] +Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If [arg newbracket] is specified, it becomes the new +bracket, and is returned. + +[call [cmd ex_rb] [opt [arg newbracket]]] +Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If [arg newbracket] is specified, it becomes the +new bracket, and is returned. + +[list_end] + +[section {PLUGIN COMMANDS}] + +The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections. + +[subsection {Management commands}] + +The management commands a plugin has to provide are used by the +frontend to + +[list_begin enumerated] +[enum] initialize and shutdown the plugin +[enum] determine the number of passes it has + to make over the input +[enum] initialize and shutdown each pass +[enum] query and initialize engine parameters +[list_end] +[para] + +After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence: + +[example { + toc_numpasses -> n + toc_listvariables -> vars + + toc_varset var1 value1 + toc_varset var2 value2 + ... + toc_varset varK valueK + toc_initialize + toc_setup 1 + ... + toc_setup 2 + ... + ... + toc_setup n + ... + toc_postprocess + toc_shutdown + ... +}] + +I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional. + +[para] + +After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at [cmd toc_varset]. + +[para] + +In each of the passes, i.e. after the calls of [cmd toc_setup] the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the doctoc markup language, +as specified in the [term {doctoc language syntax}] specification. + +[para] + +A different way of looking at the sequence is: + +[list_begin itemized] +[item] First some basic parameters are determined. + +[item] Then everything starting at the first [cmd toc_varset] to +[cmd toc_shutdown] forms a [term run], the formatting of a +single input. Each run can be followed by more. + +[item] Embedded within each run we have one or more [term passes], +each starting with [cmd toc_setup] and going until either the next +[cmd toc_setup] or [cmd toc_postprocess] is reached. + +[para] + +If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored. + +[list_end] +[para] + +The commands, their names, signatures, and responsibilities are, in +detail: + +[list_begin definitions] + +[call [cmd toc_initialize]] +[emph Initialization/Shutdown]. + +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. + +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored. + +[call [cmd toc_listvariables]] +[emph Initialization/Shutdown] and [emph {Engine parameters}]. + +Second command is called after the plugin code has been loaded, +i.e. immediately after [cmd toc_numpasses]. + +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty. + +[call [cmd toc_numpasses]] +[emph Initialization/Shutdown] and [emph {Pass management}]. + +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. + +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one. + +[call [cmd toc_postprocess] [arg text]] +[emph Initialization/Shutdown]. + +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument. + +[para] + +Expected to return a value, the final result of formatting the input. + +[call [cmd toc_setup] [arg n]] +[emph Initialization/Shutdown] and [emph {Pass management}]. + +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from [const 1] upward. + +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored. + +[call [cmd toc_shutdown]] +[emph Initialization/Shutdown]. + +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. + +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. + +No return value is expected, and any returned value is ignored. + +[call [cmd toc_varset] [arg varname] [arg text]] +[emph {Engine parameters}]. + +This command is called by the frontend to set an engine parameter to a +particular value. + +The parameter to change is specified by [arg varname], the value to +set in [arg text]. + +[para] + +The command has to throw an error if an unknown [arg varname] is +used. Only the names returned by [cmd toc_listvariables] have to be +considered as known. + +[para] + +The values of all engine parameters have to persist between passes and +runs. + +[list_end] + +[subsection {Formatting commands}] + +The formatting commands have to implement the formatting for the +output format, for all the markup commands of the doctoc markup +language, except [cmd lb], [cmd rb], [cmd vset], [cmd include], and +[cmd comment]. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all. + +[para] + +This means, that each of the five markup commands specified in the +[term {doctoc language command reference}] and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix [emph fmt_] added to it. + +[para] + +All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output. + +[para] + +To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +[term {doctoc language command reference}] for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command. + +[para] + +The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the doctoc +markup language, as specified in the [term {doctoc language syntax}] +specification. + +[para] + +[list_begin definitions] + +[call [cmd fmt_plain_text] [arg text]] +[emph {No associated markup command}]. + +[para] Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text. + +[para] The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools.man b/tcllib/modules/doctools/doctools.man new file mode 100644 index 0000000..950f7b4 --- /dev/null +++ b/tcllib/modules/doctools/doctools.man @@ -0,0 +1,543 @@ +[comment {-*- tcl -*- doctools manpage}] +[vset PACKAGE_VERSION 1.4.19] +[manpage_begin doctools n [vset PACKAGE_VERSION]] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[see_also doctools_plugin_apiref] +[keywords conversion] +[keywords documentation] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] +[copyright {2003-2014 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools - Processing documents}] +[category {Documentation tools}] +[require Tcl 8.2] +[require doctools [opt [vset PACKAGE_VERSION]]] +[description] + +This package provides a class for the creation of objects able to +process and convert text written in the [term doctools] markup +language into any output format X for which a +[term {formatting engine}] is available. + +[para] + +A reader interested in the markup language itself should start with +the [term {doctools language introduction}] and proceed from there to +the formal specifications, i.e. the [term {doctools language syntax}] +and the [term {doctools language command reference}]. + +[para] + +If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a [term {plugin writer}] then reading +and understanding the [term {doctools plugin API reference}] is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail. + +[section {PUBLIC API}] +[subsection {PACKAGE COMMANDS}] + +[list_begin definitions] + +[call [cmd ::doctools::new] [arg objectName] [opt [arg "option value"]...]] + +This command creates a new doctools object with an associated Tcl +command whose name is [arg objectName]. This [term object] command is +explained in full detail in the sections [sectref {OBJECT COMMAND}] +and [sectref {OBJECT METHODS}]. The object command will be created +under the current namespace if the [arg objectName] is not fully +qualified, and in the specified namespace otherwise. + +[para] + +The options and their values coming after the name of the object are +used to set the initial configuration of the object. + +[call [cmd ::doctools::help]] + +This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text. + +[call [cmd ::doctools::search] [arg path]] + +Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section [sectref {FORMAT MAPPING}] for more explanations. + +[para] + +This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. + +This command is the means to do so. When given a [arg path] to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the [arg path] added +last is later searched through first. + +[para] + +An error will be thrown if the [arg path] either does not exist, is +not a directory, or is not readable. + +[list_end] + +[subsection {OBJECT COMMAND}] + +All commands created by [cmd ::doctools::new] have the following +general form and may be used to invoke various operations on their +doctools converter object. + +[list_begin definitions] + +[call [cmd objectName] [method method] [opt [arg "arg arg ..."]]] + +The method [method method] and its [arg arg]'uments determine the exact +behavior of the command. See section [sectref {OBJECT METHODS}] for +the detailed specifications. + +[list_end] + +[subsection {OBJECT METHODS}] + +[list_begin definitions] + +[call [arg objectName] [method configure]] + +The method returns a list of all known options and their current +values when called without any arguments. + +[call [arg objectName] [method configure] [arg option]] + +The method behaves like the method [method cget] when called with a +single argument and returns the value of the option specified by said +argument. + +[call [arg objectName] [method configure] [option -option] [arg value]...] + +The method reconfigures the specified [option option]s of the object, +setting them to the associated [arg value]s, when called with an even +number of arguments, at least two. + +[para] + +The legal options are described in the section +[sectref {OBJECT CONFIGURATION}]. + +[call [arg objectName] [method cget] [option -option]] + +This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for. + +[para] + +The legal configuration options are described in section +[sectref {OBJECT CONFIGURATION}]. + +[call [arg objectName] [method destroy]] + +This method destroys the object it is invoked for. + +[call [arg objectName] [method format] [arg text]] + +This method runs the [arg text] through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no [option -format] was configured for the object. + +[para] + +The method assumes that the [arg text] is in [term doctools] format as +specified in the companion document [term doctools_fmt]. Errors will +be thrown otherwise. + +[call [arg objectName] [method map] [arg symbolic] [arg actual]] + +This methods add one entry to the per-object mapping from +[arg symbolic] filenames to the [arg actual] uris. + +The object just stores this mapping and makes it available to the +configured formatting engine through the command [cmd dt_fmap]. + +This command is described in more detail in the +[term {doctools plugin API reference}] which specifies the interaction +between the objects created by this package and doctools formatting +engines. + +[call [arg objectName] [method parameters]] + +This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format. + +[call [arg objectName] [method search] [arg path]] + +This method extends the per-object list of paths searched for doctools +formatting engines. See also the command [cmd ::doctools::search] on +how to extend the per-package list of paths. Note that the path +entered last will be searched first. + +For more details see section [sectref {FORMAT MAPPING}]. + +[call [arg objectName] [method setparam] [arg name] [arg value]] + +This method sets the [arg name]d engine parameter to the specified +[arg value]. + +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given [arg name]. + +The list of parameters provided by the configured formatting engine +can be retrieved through the method [method parameters]. + +[call [arg objectName] [method warnings]] + +This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method [method format]. + +[list_end] + +[subsection {OBJECT CONFIGURATION}] + +All doctools objects understand the following configuration options: + +[list_begin options] + +[opt_def -file [arg file]] + +The argument of this option is stored in the object and made available +to the configured formatting engine through the commands [cmd dt_file] +and [cmd dt_mainfile]. + +These commands are described in more detail in the companion document +[term doctools_api] which specifies the API between the object and +formatting engines. + +[para] + +The default value of this option is the empty string. + +[para] + +The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed. + +[opt_def -ibase [arg file]] + +The argument of this option is stored in the object and used as the +base path for resolution of relative include paths. If this option is +not set (empty string) the value of [option -file] is used instead. + +[para] + +Note that [option -file] and [option -ibase], while similar looking, +are actually very different. The value of [option -file] is used by +some engines for the generation of proper relative references between +output documents (HTML). As such this is a [term destination] +path. The [option -ibase] on the other hand is used to resolve +relative include paths, and as such deals with [term source] paths. + +[para] + +The default value of this option is the empty string. + +[opt_def -module [arg text]] + +The argument of this option is stored in the object and made available +to the configured formatting engine through the command [cmd dt_module]. + +This command is described in more detail in the companion document +[term doctools_api] which specifies the API between the object and +formatting engines. + +[para] + +The default value of this option is the empty string. + +[para] + +The configured formatting engine should interpret the value as the +name of the module the file containing the document which is currently +processed belongs to. + +[opt_def -format [arg text]] + +The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method [method format]. Its default value is the empty string. The +method [method format] cannot be used if this option is not set to a +valid value at least once. + +[para] + +The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched. + +[para] + +The section [sectref {FORMAT MAPPING}] explains in detail how the +package and object will look for engine implementations. + +[opt_def -deprecated [arg boolean]] + +This option is a boolean flag. The object will generate warnings if +this flag is set and the text given to method [method format] contains +the deprecated markup command [cmd strong]. + +Its default value is [const FALSE]. In other words, no warnings will +be generated. + +[opt_def -copyright [arg text]] + +The argument of this option is stored in the object and made available +to the configured formatting engine through the command [cmd dt_copyright]. + +This command is described in more detail in the companion document +[term doctools_api] which specifies the API between the object and +formatting engines. + +[para] + +The default value of this option is the empty string. + +[para] + +The configured formatting engine should interpret the value as a +copyright assignment for the document which is currently processed, or +the package described by it. + +[para] + +This information must be used if and only if the engine is unable to +find any copyright assignments within the document itself. Such are +specified by the formatting command [cmd copyright]. This command is +described in more detail in the companion document [term doctools_fmt] +which specifies the [term doctools] format itself. + +[list_end] + +[subsection {FORMAT MAPPING}] + +The package and object will perform the following algorithm when +trying to map a format name [term foo] to a file containing an +implementation of a formatting engine for [term foo]: + +[list_begin enumerated] +[enum] + +If [term foo] is the name of an existing file then this file is +directly taken as the implementation. + +[enum] + +If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file [file fmt.[term foo]]. If yes, then that file is taken as the +implementation. + +[para] + +Note that this list of paths is initially empty and can be extended +through the object method [method search]. + +[enum] + +If not, the list of package paths is searched. + +For each directory in the list the package checks if that directory +contains a file [file fmt.[term foo]]. If yes, then that file is taken +as the implementation. + +[para] + +This list of paths can be extended +through the command [cmd ::doctools::search]. + +It contains initially one path, the subdirectory [file mpformats] of +the directory the package itself is located in. + +In other words, if the package implementation [file doctools.tcl] is +installed in the directory [file /usr/local/lib/tcllib/doctools] then +it will by default search the + +directory [file /usr/local/lib/tcllib/doctools/mpformats] for format +implementations. + +[enum] + +The mapping fails. + +[list_end] + +[section {PREDEFINED ENGINES}] + +The package provides predefined engines for the following +formats. Some of the engines support parameters. These will be +explained below as well. + +[list_begin definitions] +[def html] + +This engine generates HTML markup, for processing by web browsers and +the like. This engine supports four parameters: + +[list_begin definitions] +[def footer] + +The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the [const </body>] tag, closing the body of the generated +HTML. + +[para] + +This can be used to insert boilerplate footer markup into the +generated document. + +[def header] + +The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the [const <body>] tag, starting the body of the generated HTML. + +[para] + +This can be used to insert boilerplate header markup into the +generated document. + +[def meta] + +The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the [const <head>] tag, starting the header section of the +generated HTML. + +[para] + +This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc. + +[def xref] + +The value for this parameter has to be a list of triples specifying +cross-reference information. This information is used by the engine to +create more hyperlinks. Each triple is a list containing a pattern, +symbolic filename and fragment reference, in this order. If a pattern +is specified multiple times the last occurence of the pattern will be +used. + +[para] + +The engine will consult the xref database when encountering specific +commands and will create a link if the relevant text matches one of +the patterns. No link will be created if no match was found. The link +will go to the uri [const {file#fragment}] listed in the relevant +triple, after conversion of the symbolic file name to the actual uri +via [cmd dt_fmap] (see the [term {doctools plugin API reference}]). + +This file-to-uri mapping was build by calls to the method [method map] +of the doctools object (See section [sectref {OBJECT METHODS}]). + +[para] + +The following formatting commands will consult the xref database: + +[list_begin definitions] +[def "[cmd cmd] [arg word]"] + +The command will look for the patterns [const sa,][arg word], and +[arg word], in this order. If this fails if it will convert [arg word] +to all lowercase and try again. + +[def "[cmd syscmd] [arg word]"] + +The command will look for the patterns [const sa,][arg word], and +[arg word], in this order. If this fails if it will convert [arg word] +to all lowercase and try again. + +[def "[cmd term] [arg word]"] + +The command will look for the patterns [const kw,][arg word], +[const sa,][arg word], and [arg word], in this order. If this fails if +it will convert [arg word] to all lowercase and try again. + +[def "[cmd package] [arg word]"] + +The command will look for the patterns [const sa,][arg word], +[const kw,][arg word], and [arg word], in this order. If this fails if +it will convert [arg word] to all lowercase and try again. + +[def "[cmd see_also] [arg word]..."] + +The command will look for the patterns [const sa,][arg word], and +[arg word], in this order, for each [arg word] given to the +command. If this fails if it will convert [arg word] to all lowercase +and try again. + +[def "[cmd keywords] [arg word]..."] + +The command will look for the patterns [const kw,][arg word], and +[arg word], in this order, for each [arg word] given to the +command. If this fails if it will convert [arg word] to all lowercase +and try again. + +[list_end] +[list_end] +[para] + +[def latex] + +This engine generates output suitable for the [syscmd latex] text +processor coming out of the TeX world. + +[def list] + +This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages. + +[def nroff] + +This engine generates nroff output, for processing by [syscmd nroff], +or [syscmd groff]. The result will be standard man pages as they are +known in the unix world. + +[def null] + +This engine generates no outout at all. This can be used if one just +wants to validate some input. + +[def tmml] + +This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML. + +[def wiki] + +This engine generates Wiki markup as understood by Jean Claude +Wippler's [syscmd wikit] application. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools.tcl b/tcllib/modules/doctools/doctools.tcl new file mode 100644 index 0000000..8365633 --- /dev/null +++ b/tcllib/modules/doctools/doctools.tcl @@ -0,0 +1,1361 @@ +# doctools.tcl -- +# +# Implementation of doctools objects for Tcl. +# +# Copyright (c) 2003-2014 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. + +package require Tcl 8.2 +package require textutil::expander + +# @mdgen OWNER: api.tcl +# @mdgen OWNER: checker.tcl +# @mdgen OWNER: mpformats/*.tcl +# @mdgen OWNER: mpformats/*.msg +# @mdgen OWNER: mpformats/fmt.* +# @mdgen OWNER: mpformats/man.macros + +namespace eval ::doctools { + # Data storage in the doctools module + # ------------------------------- + # + # One namespace per object, containing + # 1) A list of additional search paths for format definition files. + # This list extends the list of standard paths known to the module. + # The paths in the list are searched before the standard paths. + # 2) Configuration information + # a) string: The format to use when converting the input. + # b) boolean: A flag telling us whether to warn when visual markup + # is used in the input, or not. + # c) File information associated with the input, if any. + # d) Module information associated with the input, if any. + # e) Copyright information, if any + # 4) Name of the interpreter used to perform the syntax check of the + # input (= allowed order of formatting commands). + # 5) Name of the interpreter containing the code coming from the format + # definition file. + # 6) Name of the expander object used to interpret the input to convert. + + # commands is the list of subcommands recognized by the doctools objects + variable commands [list \ + "cget" \ + "configure" \ + "destroy" \ + "format" \ + "map" \ + "search" \ + "warnings" \ + "parameters" \ + "setparam" \ + ] + + # Only export the toplevel commands + namespace export new search help + + # Global data + + # 1) List of standard paths to look at when searching for a format + # definition. Extensible. + # 2) Location of this file in the filesystem + + variable paths [list] + variable here [file dirname [info script]] +} + +# ::doctools::search -- +# +# Extend the list of paths used when searching for format definition files. +# +# Arguments: +# path Path to add to the list. The path has to exist, has to be a +# directory, and has to be readable. +# +# Results: +# None. +# +# Sideeffects: +# The specified path is added to the front of the list of search +# paths. This means that the new path is search before the +# standard paths set at module initialization time. + +proc ::doctools::search {path} { + variable paths + + if {![file exists $path]} {return -code error "doctools::search: path does not exist"} + if {![file isdirectory $path]} {return -code error "doctools::search: path is not a directory"} + if {![file readable $path]} {return -code error "doctools::search: path cannot be read"} + + set paths [linsert $paths 0 $path] + return +} + +# ::doctools::help -- +# +# Return a string containing short help +# regarding the existing formatting commands. +# +# Arguments: +# None. +# +# Results: +# A string. + +proc ::doctools::help {} { + return "formatting commands\n\ + * manpage_begin - begin of manpage\n\ + * moddesc - module description\n\ + * titledesc - manpage title\n\ + * copyright - copyright assignment\n\ + * manpage_end - end of manpage\n\ + * require - package requirement\n\ + * description - begin of manpage body\n\ + * section - begin new section of body\n\ + * subsection - begin new sub-section of body\n\ + * para - begin new paragraph\n\ + * list_begin - begin a list\n\ + * list_end - end of a list\n\ + * lst_item - begin item of definition list\n\ + * call - command definition, adds to synopsis\n\ + * usage - see above, without adding to synopsis\n\ + * bullet - begin item in bulleted list\n\ + * enum - begin item in enumerated list\n\ + * arg_def - begin item in argument list\n\ + * cmd_def - begin item in command list\n\ + * opt_def - begin item in option list\n\ + * tkoption_def - begin item in tkoption list\n\ + * example - example block\n\ + * example_begin - begin example\n\ + * example_end - end of example\n\ + * category - category declaration\n\ + * see_also - cross reference declaration\n\ + * keywords - keyword declaration\n\ + * nl - paragraph break in list items\n\ + * arg - semantic markup - argument\n\ + * cmd - semantic markup - command\n\ + * opt - semantic markup - optional data\n\ + * comment - semantic markup - comment\n\ + * sectref - semantic markup - section reference\n\ + * syscmd - semantic markup - system command\n\ + * method - semantic markup - object method\n\ + * namespace - semantic markup - namespace name\n\ + * option - semantic markup - option\n\ + * widget - semantic markup - widget\n\ + * fun - semantic markup - function\n\ + * type - semantic markup - data type\n\ + * package - semantic markup - package\n\ + * class - semantic markup - class\n\ + * var - semantic markup - variable\n\ + * file - semantic markup - file \n\ + * uri - semantic markup - uri (optional label)\n\ + * term - semantic markup - unspecific terminology\n\ + * const - semantic markup - constant value\n\ + * emph - emphasis\n\ + * strong - emphasis, deprecated, usage is discouraged\n\ + " +} + +# ::doctools::new -- +# +# Create a new doctools object with a given name. May configure the object. +# +# Arguments: +# name Name of the doctools object. +# args Options configuring the new object. +# +# Results: +# name Name of the doctools created + +proc ::doctools::new {name args} { + + if { [llength [info commands ::$name]] } { + return -code error "command \"$name\" already exists, unable to create doctools object" + } + if {[llength $args] % 2 == 1} { + return -code error "wrong # args: doctools::new name ?opt val...??" + } + + # The arguments seem to be ok, setup the namespace for the object + + namespace eval ::doctools::doctools$name { + variable paths [list] + variable format "" + variable formatfile "" + variable deprecated 0 + variable file "" + variable mainfile "" + variable ibase "" + variable module "" + variable copyright "" + variable format_ip "" + variable chk_ip "" + variable expander "[namespace current]::ex" + variable ex_ok 0 + variable msg [list] + variable param [list] + variable map ; array set map {} + } + + # Create the command to manipulate the object + # $name -> ::doctools::DoctoolsProc $name + interp alias {} ::$name {} ::doctools::DoctoolsProc $name + + # If the name was followed by arguments use them to configure the + # object before returning its handle to the caller. + + if {[llength $args] > 1} { + # Use linsert trick to make the command a pure list. + eval [linsert $args 0 _configure $name] + } + return $name +} + +########################## +# Private functions follow + +# ::doctools::DoctoolsProc -- +# +# Command that processes all doctools object commands. +# Dispatches any object command to the appropriate internal +# command implementing its functionality. +# +# Arguments: +# name Name of the doctools object to manipulate. +# cmd Subcommand to invoke. +# args Arguments for subcommand. +# +# Results: +# Varies based on command to perform + +proc ::doctools::DoctoolsProc {name {cmd ""} args} { + # Do minimal args checks here + if { [llength [info level 0]] == 2 } { + error "wrong # args: should be \"$name option ?arg arg ...?\"" + } + + # Split the args into command and args components + + if { [llength [info commands ::doctools::_$cmd]] == 0 } { + variable commands + set optlist [join $commands ", "] + set optlist [linsert $optlist "end-1" "or"] + return -code error "bad option \"$cmd\": must be $optlist" + } + return [eval [list ::doctools::_$cmd $name] $args] +} + +########################## +# Method implementations follow (these are also private commands) + +# ::doctools::_cget -- +# +# Retrieve the current value of a particular option +# +# Arguments: +# name Name of the doctools object to query +# option Name of the option whose value we are asking for. +# +# Results: +# The value of the option + +proc ::doctools::_cget {name option} { + _configure $name $option +} + +# ::doctools::_configure -- +# +# Configure a doctools object, or query its configuration. +# +# Arguments: +# name Name of the doctools object to configure +# args Options and their values. +# +# Results: +# None if configuring the object. +# A list of all options and their values if called without arguments. +# The value of one particular option if called with a single argument. + +proc ::doctools::_configure {name args} { + upvar #0 ::doctools::doctools${name}::format_ip format_ip + upvar #0 ::doctools::doctools${name}::chk_ip chk_ip + upvar #0 ::doctools::doctools${name}::expander expander + upvar #0 ::doctools::doctools${name}::passes passes + + if {[llength $args] == 0} { + # Retrieve the current configuration. + + upvar #0 ::doctools::doctools${name}::file file + upvar #0 ::doctools::doctools${name}::ibase ibase + upvar #0 ::doctools::doctools${name}::module module + upvar #0 ::doctools::doctools${name}::format format + upvar #0 ::doctools::doctools${name}::copyright copyright + upvar #0 ::doctools::doctools${name}::deprecated deprecated + + set res [list] + lappend res -file $file + lappend res -ibase $ibase + lappend res -module $module + lappend res -format $format + lappend res -copyright $copyright + lappend res -deprecated $deprecated + return $res + + } elseif {[llength $args] == 1} { + # Query the value of one particular option. + + switch -exact -- [lindex $args 0] { + -file { + upvar #0 ::doctools::doctools${name}::file file + return $file + } + -ibase { + upvar #0 ::doctools::doctools${name}::ibase ibase + return $ibase + } + -module { + upvar #0 ::doctools::doctools${name}::module module + return $module + } + -copyright { + upvar #0 ::doctools::doctools${name}::copyright copyright + return $copyright + } + -format { + upvar #0 ::doctools::doctools${name}::format format + return $format + } + -deprecated { + upvar #0 ::doctools::doctools${name}::deprecated deprecated + return $deprecated + } + default { + return -code error \ + "doctools::_configure: Unknown option \"[lindex $args 0]\", expected\ + -copyright, -file, -ibase, -module, -format, or -deprecated" + } + } + } else { + # Reconfigure the object. + + if {[llength $args] % 2 == 1} { + return -code error "wrong # args: doctools::_configure name ?opt val...??" + } + + foreach {option value} $args { + switch -exact -- $option { + -file { + upvar #0 ::doctools::doctools${name}::file file + upvar #0 ::doctools::doctools${name}::mainfile mfile + set file $value + set mfile $value + } + -ibase { + upvar #0 ::doctools::doctools${name}::ibase ibase + set ibase $value + } + -module { + upvar #0 ::doctools::doctools${name}::module module + set module $value + } + -copyright { + upvar #0 ::doctools::doctools${name}::copyright copyright + set copyright $value + } + -format { + if {[catch { + set fmtfile [LookupFormat $name $value] + SetupFormatter $name $fmtfile + upvar #0 ::doctools::doctools${name}::format format + set format $value + } msg]} { + return -code error \ + -errorinfo $::errorInfo \ + "doctools::_configure: -format: $msg" + } + } + -deprecated { + if {![string is boolean $value]} { + return -code error \ + "doctools::_configure: -deprecated expected a boolean, got \"$value\"" + } + upvar #0 ::doctools::doctools${name}::deprecated deprecated + set deprecated $value + } + default { + return -code error \ + "doctools::_configure: Unknown option \"$option\", expected\ + -copyright, -file, -ibase, -module, -format, or -deprecated" + } + } + } + } + return "" +} + +# ::doctools::_destroy -- +# +# Destroy a doctools object, including its associated command and data storage. +# +# Arguments: +# name Name of the doctools object to destroy. +# +# Results: +# None. + +proc ::doctools::_destroy {name} { + # Check the object for sub objects which have to destroyed before + # the namespace is torn down. + namespace eval ::doctools::doctools$name { + if {$format_ip != ""} {interp delete $format_ip} + if {$chk_ip != ""} {interp delete $chk_ip} + + # Expander objects have no delete/destroy method. This would + # be a leak if not for the fact that an expander object is a + # namespace, and we have arranged to make it a sub namespace of + # the doctools object. Therefore tearing down our object namespace + # also cleans up the expander object. + # if {$expander != ""} {$expander destroy} + + } + namespace delete ::doctools::doctools$name + interp alias {} ::$name {} + return +} + +# ::doctools::_map -- +# +# Add a mapping from symbolic to actual filename to the object. +# +# Arguments: +# name Name of the doctools object to use +# sfname Symbolic filename to map +# afname Actual filename +# +# Results: +# None. + +proc ::doctools::_map {name sfname afname} { + upvar #0 ::doctools::doctools${name}::map map + set map($sfname) $afname + return +} + +# ::doctools::_img -- +# + +# Add a mapping from symbolic to the actual image filenames to +# the object. Two actual paths! The path the image is found at +# in the input, and the path for where image is to be placed in +# the output. +# +# Arguments: +# name Name of the doctools object to use +# sfname Symbolic filename to map +# afnameo Actual filename, origin +# afnamed Actual filename, destination +# +# Results: +# None. + +proc ::doctools::_img {name sfname afnameo afnamed} { + upvar #0 ::doctools::doctools${name}::imap imap + set imap($sfname) [list $afnameo $afnamed] + return +} + +# ::doctools::_format -- +# +# Convert some text in doctools format +# according to the configuration in the object. +# +# Arguments: +# name Name of the doctools object to use +# text Text to convert. +# +# Results: +# The conversion result. + +proc ::doctools::_format {name text} { + upvar #0 ::doctools::doctools${name}::format format + if {$format == ""} { + return -code error "$name: No format was specified" + } + + upvar #0 ::doctools::doctools${name}::format_ip format_ip + upvar #0 ::doctools::doctools${name}::chk_ip chk_ip + upvar #0 ::doctools::doctools${name}::ex_ok ex_ok + upvar #0 ::doctools::doctools${name}::expander expander + upvar #0 ::doctools::doctools${name}::passes passes + upvar #0 ::doctools::doctools${name}::msg warnings + + if {!$ex_ok} {SetupExpander $name} + if {$chk_ip == ""} {SetupChecker $name} + # assert (format_ip != "") + + set warnings [list] + if {[catch {$format_ip eval fmt_initialize}]} { + return -code error -errorcode {DOCTOOLS ENGINE} \ + "Could not initialize engine" + } + set result "" + + for { + set p $passes ; set n 1 + } { + $p > 0 + } { + incr p -1 ; incr n + } { + if {[catch {$format_ip eval [list fmt_setup $n]}]} { + catch {$format_ip eval fmt_shutdown} + return -code error -errorcode {DOCTOOLS ENGINE} \ + "Could not initialize pass $n of engine" + } + $chk_ip eval ck_initialize $n + + if {[catch {set result [$expander expand $text]} msg]} { + catch {$format_ip eval fmt_shutdown} + # Filter for checker errors and reduce them to the essential message. + + if {![regexp {^Error in} $msg]} { + return -code error -errorcode {DOCTOOLS INPUT} $msg + } + #set msg [join [lrange [split $msg \n] 2 end]] + + if {![regexp {^--> \(FmtError\) } $msg]} { + return -code error -errorcode {DOCTOOLS INPUT} "Doctools $msg" + } + set msg [lindex [split $msg \n] 0] + regsub {^--> \(FmtError\) } $msg {} msg + + return -code error -errorcode {DOCTOOLS INPUT} $msg + } + + $chk_ip eval ck_complete + } + + if {[catch {set result [$format_ip eval [list fmt_postprocess $result]]}]} { + return -code error -errorcode {DOCTOOLS ENGINE} \ + "Unable to post process final result" + } + if {[catch {$format_ip eval fmt_shutdown}]} { + return -code error -errorcode {DOCTOOLS ENGINE} \ + "Could not shut engine down" + } + return $result + +} + +# ::doctools::_search -- +# +# Add a search path to the object. +# +# Arguments: +# name Name of the doctools object to extend +# path Search path to add. +# +# Results: +# None. + +proc ::doctools::_search {name path} { + if {![file exists $path]} {return -code error "$name search: path does not exist"} + if {![file isdirectory $path]} {return -code error "$name search: path is not a directory"} + if {![file readable $path]} {return -code error "$name search: path cannot be read"} + + upvar #0 ::doctools::doctools${name}::paths paths + set paths [linsert $paths 0 $path] + return +} + +# ::doctools::_warnings -- +# +# Return the warning accumulated during the last invocation of 'format'. +# +# Arguments: +# name Name of the doctools object to query +# +# Results: +# A list of warnings. + +proc ::doctools::_warnings {name} { + upvar #0 ::doctools::doctools${name}::msg msg + return $msg +} + +# ::doctools::_parameters -- +# +# Returns a list containing the parameters provided +# by the selected formatting engine. +# +# Arguments: +# name Name of the doctools object to query +# +# Results: +# A list of parameter names + +proc ::doctools::_parameters {name} { + upvar #0 ::doctools::doctools${name}::param param + return $param +} + +# ::doctools::_setparam -- +# +# Set a named engine parameter to a value. +# +# Arguments: +# name Name of the doctools object to query +# param Name of the parameter to set. +# value Value to set the parameter to. +# +# Results: +# None. + +proc ::doctools::_setparam {name param value} { + upvar #0 ::doctools::doctools${name}::format_ip format_ip + + if {$format_ip == {}} { + return -code error \ + "Unable to set parameters without a valid format" + } + + $format_ip eval [list fmt_varset $param $value] + return +} + +########################## +# Support commands + +# ::doctools::LookupFormat -- +# +# Search a format definition file based upon its name +# +# Arguments: +# name Name of the doctools object to use +# format Name of the format to look for. +# +# Results: +# The file containing the format definition + +proc ::doctools::LookupFormat {name format} { + # Order of searching + # 1) Is the name of the format an existing file ? + # If yes, take this file. + # 2) Look for the file in the directories given to the object itself.. + # 3) Look for the file in the standard directories of this package. + + if {[file exists $format] && [file isfile $format] } { + return $format + } + + upvar #0 ::doctools::doctools${name}::paths opaths + foreach path $opaths { + set f [file join $path fmt.$format] + if {[file exists $f] && [file isfile $f]} { + return $f + } + } + + variable paths + foreach path $paths { + set f [file join $path fmt.$format] + if {[file exists $f] && [file isfile $f]} { + return $f + } + } + + return -code error "Unknown format \"$format\"" +} + +# ::doctools::SetupFormatter -- +# +# Create and initializes an interpreter containing a +# formatting engine +# +# Arguments: +# name Name of the doctools object to manipulate +# format Name of file containing the code of the engine +# +# Results: +# None. + +proc ::doctools::SetupFormatter {name format} { + + # Create and initialize the interpreter first. + # Use a transient variable. Interrogate the + # engine and check its response. Bail out in + # case of errors. Only if we pass the checks + # we tear down the old engine and make the new + # one official. + + variable here + set mpip [interp create -safe] ; # interpreter for the formatting engine + $mpip eval [list set auto_path $::auto_path] + #set mpip [interp create] ; # interpreter for the formatting engine + + $mpip invokehidden source [file join $here api.tcl] + #$mpip eval [list source [file join $here api.tcl]] + interp alias $mpip dt_source {} ::doctools::Source $mpip [file dirname $format] + interp alias $mpip dt_read {} ::doctools::Read $mpip [file dirname $format] + interp alias $mpip dt_package {} ::doctools::Package $mpip + interp alias $mpip file {} ::doctools::FileOp $mpip + interp alias $mpip puts_stderr {} ::puts stderr + interp alias $mpip puts_stdout {} ::puts stdout + $mpip invokehidden source $format + #$mpip eval [list source $format] + + # Check the engine for useability in doctools. + + foreach api { + fmt_numpasses + fmt_initialize + fmt_setup + fmt_postprocess + fmt_shutdown + fmt_listvariables + fmt_varset + } { + if {[$mpip eval [list info commands $api]] == {}} { + interp delete $mpip + error "$format error: API incomplete, cannot use this engine" + } + } + if {[catch { + set passes [$mpip eval fmt_numpasses] + }]} { + interp delete $mpip + error "$format error: Unable to query for number of passes" + } + if {![string is integer $passes] || ($passes < 1)} { + interp delete $mpip + error "$format error: illegal number of passes \"$passes\"" + } + if {[catch { + set parameters [$mpip eval fmt_listvariables] + }]} { + interp delete $mpip + error "$format error: Unable to query for list of parameters" + } + + # Passed the tests. Tear down existing engine, + # and checker. The latter is destroyed because + # of its aliases into the formatter, which are + # now invalid. It will be recreated during the + # next call of 'format'. + + upvar #0 ::doctools::doctools${name}::formatfile formatfile + upvar #0 ::doctools::doctools${name}::format_ip format_ip + upvar #0 ::doctools::doctools${name}::chk_ip chk_ip + upvar #0 ::doctools::doctools${name}::expander expander + upvar #0 ::doctools::doctools${name}::passes xpasses + upvar #0 ::doctools::doctools${name}::param xparam + + if {$chk_ip != {}} {interp delete $chk_ip} + if {$format_ip != {}} {interp delete $format_ip} + + set chk_ip "" + set format_ip "" + + # Now link engine API into it. + + interp alias $mpip dt_file {} ::doctools::GetFile $name + interp alias $mpip dt_mainfile {} ::doctools::GetMainFile $name + interp alias $mpip dt_fileid {} ::doctools::GetFileId $name + interp alias $mpip dt_ibase {} ::doctools::GetIBase $name + interp alias $mpip dt_module {} ::doctools::GetModule $name + interp alias $mpip dt_copyright {} ::doctools::GetCopyright $name + interp alias $mpip dt_format {} ::doctools::GetFormat $name + interp alias $mpip dt_user {} ::doctools::GetUser $name + interp alias $mpip dt_lnesting {} ::doctools::ListLevel $name + interp alias $mpip dt_fmap {} ::doctools::MapFile $name + interp alias $mpip dt_imgsrc {} ::doctools::ImgSrc $name + interp alias $mpip dt_imgdst {} ::doctools::ImgDst $name + interp alias $mpip dt_imgdata {} ::doctools::ImgData $name + interp alias $mpip file {} ::doctools::FileCmd + + foreach cmd {cappend cget cis cname cpop cpush ctopandclear cset lb rb} { + interp alias $mpip ex_$cmd {} $expander $cmd + } + + set format_ip $mpip + set formatfile $format + set xpasses $passes + set xparam $parameters + return +} + +# ::doctools::SetupChecker -- +# +# Create and initializes an interpreter for checking the usage of +# doctools formatting commands +# +# Arguments: +# name Name of the doctools object to manipulate +# +# Results: +# None. + +proc ::doctools::SetupChecker {name} { + # Create an interpreter for checking the usage of doctools formatting commands + # and initialize it: Link it to the interpreter doing the formatting, the + # expander object and the configuration information. All of which + # is accessible through the token/handle (name of state/object array). + + variable here + + upvar #0 ::doctools::doctools${name}::chk_ip chk_ip + if {$chk_ip != ""} {return} + + upvar #0 ::doctools::doctools${name}::expander expander + upvar #0 ::doctools::doctools${name}::format_ip format_ip + + set chk_ip [interp create] ; # interpreter hosting the formal format checker + + # Make configuration available through command, then load the code base. + + foreach {cmd ckcmd} { + dt_search SearchPaths + dt_deprecated Deprecated + dt_error FmtError + dt_warning FmtWarning + dt_where Where + dt_file GetFile + } { + interp alias $chk_ip $cmd {} ::doctools::$ckcmd $name + } + $chk_ip eval [list source [file join $here checker.tcl]] + + # Simple expander commands are directly routed back into it, no + # checking required. + + foreach cmd {cappend cget cis cname cpop cpush ctopandclear cset lb rb} { + interp alias $chk_ip $cmd {} $expander $cmd + } + + # Link the formatter commands into the checker. We use the prefix + # 'fmt_' to distinguish them from the checking commands. + + foreach cmd { + manpage_begin moddesc titledesc copyright manpage_end require + description section para list_begin list_end lst_item call + bullet enum example example_begin example_end see_also + keywords nl arg cmd opt comment sectref syscmd method option + widget fun type package class var file uri usage term const + arg_def cmd_def opt_def tkoption_def emph strong plain_text + namespace subsection category image + } { + interp alias $chk_ip fmt_$cmd $format_ip fmt_$cmd + } + return +} + +# ::doctools::SetupExpander -- +# +# Create and initializes the expander for input +# +# Arguments: +# name Name of the doctools object to manipulate +# +# Results: +# None. + +proc ::doctools::SetupExpander {name} { + upvar #0 ::doctools::doctools${name}::ex_ok ex_ok + if {$ex_ok} {return} + + upvar #0 ::doctools::doctools${name}::expander expander + ::textutil::expander $expander + $expander evalcmd [list ::doctools::Eval $name] + $expander textcmd plain_text + set ex_ok 1 + return +} + +# ::doctools::SearchPaths -- +# +# API for checker. Returns list of search paths for format +# definitions. Used to look for message catalogs as well. +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# None. + +proc ::doctools::SearchPaths {name} { + upvar #0 ::doctools::doctools${name}::paths opaths + variable paths + + set p $opaths + foreach s $paths {lappend p $s} + return $p +} + +# ::doctools::Deprecated -- +# +# API for checker. Returns flag determining +# whether visual markup is warned against, or not. +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# None. + +proc ::doctools::Deprecated {name} { + upvar #0 ::doctools::doctools${name}::deprecated deprecated + return $deprecated +} + +# ::doctools::FmtError -- +# +# API for checker. Called when an error occurred. +# +# Arguments: +# name Name of the doctools object to query. +# text Error message +# +# Results: +# None. + +proc ::doctools::FmtError {name text} { + return -code error "(FmtError) $text" +} + +# ::doctools::FmtWarning -- +# +# API for checker. Called when a warning was generated +# +# Arguments: +# name Name of the doctools object +# text Warning message +# +# Results: +# None. + +proc ::doctools::FmtWarning {name text} { + upvar #0 ::doctools::doctools${name}::msg msg + lappend msg $text + return +} + +# ::doctools::Where -- +# +# API for checker. Called when the current location is needed +# +# Arguments: +# name Name of the doctools object +# +# Results: +# List containing offset, line, column + +proc ::doctools::Where {name} { + upvar #0 ::doctools::doctools${name}::expander expander + return [$expander where] +} + +# ::doctools::Eval -- +# +# API for expander. Routes the macro invocations +# into the checker interpreter +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# None. + +proc ::doctools::Eval {name macro} { + upvar #0 ::doctools::doctools${name}::chk_ip chk_ip + + #puts stderr "\t\t$name [lindex [split $macro] 0]" + + # Handle the [include] command directly + if {[string match include* $macro]} { + set macro [$chk_ip eval [list subst $macro]] + foreach {cmd filename} $macro break + return [ExpandInclude $name $filename] + } + + # Rewrite the [namespace] command before passing it on. + # "namespace" is a special command. The interpreter the validator + # resides in uses the package "msgcat", which in turn uses the + # builtin namespace. So the builtin cannot be simply + # overwritten. We use a different name. + + if {[string match namespace* $macro]} { + set macro _$macro + } + return [$chk_ip eval $macro] +} + +# ::doctools::ExpandInclude -- +# +# Handle inclusion of files. +# +# Arguments: +# name Name of the doctools object to query. +# path Name of file to include and expand. +# +# Results: +# None. + +proc ::doctools::ExpandInclude {name path} { + upvar #0 ::doctools::doctools${name}::file file + upvar #0 ::doctools::doctools${name}::ibase ibase + + set savedi $ibase + set savedf $file + + set base $ibase + if {$base eq {}} { set base $file } + + set ipath [file normalize [file join [file dirname $base] $path]] + if {![file exists $ipath]} { + set ipath $path + if {![file exists $ipath]} { + return -code error "Unable to find include file \"$path\"" + } + } + + set chan [open $ipath r] + set text [read $chan] + close $chan + + upvar #0 ::doctools::doctools${name}::expander expander + + set ibase $ipath + set res [$expander expand $text] + + set ibase $savedi + set file $savedf + + return $res +} + +# ::doctools::GetUser -- +# +# API for formatter. Returns name of current user +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# String, name of current user. + +proc ::doctools::GetUser {name} { + global tcl_platform + return $tcl_platform(user) +} + +# ::doctools::GetFile -- +# +# API for formatter. Returns file information +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# File information + +proc ::doctools::GetFile {name} { + + #puts stderr "GetFile $name" + + upvar #0 ::doctools::doctools${name}::file file + + #puts stderr "ok $file" + return $file +} + +proc ::doctools::GetMainFile {name} { + + #puts stderr "GetMainFile $name" + + upvar #0 ::doctools::doctools${name}::mainfile mfile + + #puts stderr "ok $mfile" + return $mfile +} + +# ::doctools::GetFileId -- +# +# API for formatter. Returns file information (truncated to stem of filename) +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# File information + +proc ::doctools::GetFileId {name} { + return [file rootname [file tail [GetFile $name]]] +} + +proc ::doctools::GetIBase {name} { + upvar #0 ::doctools::doctools${name}::file file + upvar #0 ::doctools::doctools${name}::ibase ibase + + set base $ibase + if {$base eq {}} { set base $file } + return $base +} + +# ::doctools::FileCmd -- +# +# API for formatter. Restricted implementation of file. +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# Module information + +proc ::doctools::FileCmd {cmd args} { + switch -exact -- $cmd { + split {return [eval file split $args]} + join {return [eval file join $args]} + tail {return [eval file tail $args]} + rootname {return [eval file rootname $args]} + } + return -code error "Illegal subcommand: $cmd $args" +} + +# ::doctools::GetModule -- +# +# API for formatter. Returns module information +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# Module information + +proc ::doctools::GetModule {name} { + upvar #0 ::doctools::doctools${name}::module module + return $module +} + +# ::doctools::GetCopyright -- +# +# API for formatter. Returns copyright information +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# Copyright information + +proc ::doctools::GetCopyright {name} { + upvar #0 ::doctools::doctools${name}::copyright copyright + return $copyright +} + +# ::doctools::GetFormat -- +# +# API for formatter. Returns format information +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# Format information + +proc ::doctools::GetFormat {name} { + upvar #0 ::doctools::doctools${name}::format format + return $format +} + +# ::doctools::ListLevel -- +# +# API for formatter. Returns number of open lists +# +# Arguments: +# name Name of the doctools object to query. +# +# Results: +# Boolean flag. + +proc ::doctools::ListLevel {name} { + upvar #0 ::doctools::doctools${name}::chk_ip chk_ip + return [$chk_ip eval LNest] +} + +# ::doctools::MapFile -- +# +# API for formatter. Maps symbolic to actual filename in a doctools +# item. If no mapping is found it is assumed that the symbolic name +# is also the actual name. +# +# Arguments: +# name Name of the doctools object to query. +# fname Symbolic name of the file. +# +# Results: +# Actual name of the file. + +proc ::doctools::MapFile {name fname} { + upvar #0 ::doctools::doctools${name}::map map + + #parray map + + if {[info exists map($fname)]} { + return $map($fname) + } + return $fname +} + +# ::doctools::Img{Src,Dst} -- +# +# API for formatter. Maps symbolic to actual image in a doctools +# item. Returns nothing if no mapping is found. +# +# Arguments: +# name Name of the doctools object to query. +# iname Symbolic name of the image file. +# extensions List of acceptable file extensions. +# +# Results: +# Actual name of the file. + +proc ::doctools::ImgData {name iname extensions} { + + # The system searches for the image relative to the current input + # file, and the current main file + + upvar #0 ::doctools::doctools${name}::imap imap + + #parray imap + + foreach e $extensions { + if {[info exists imap($iname.$e)]} { + foreach {origin dest} $imap($iname.$e) break + + set f [open $origin r] + set img [read $f] + close $f + + return $img + } + } + return {} +} + +proc ::doctools::ImgSrc {name iname extensions} { + + # The system searches for the image relative to the current input + # file, and the current main file + + upvar #0 ::doctools::doctools${name}::imap imap + + #parray imap + + foreach e $extensions { + if {[info exists imap($iname.$e)]} { + foreach {origin dest} $imap($iname.$e) break + return $origin + } + } + return {} +} + +proc ::doctools::ImgDst {name iname extensions} { + # The system searches for the image relative to the current input + # file, and the current main file + + upvar #0 ::doctools::doctools${name}::imap imap + + #parray imap + + foreach e $extensions { + if {[info exists imap($iname.$e)]} { + foreach {origin dest} $imap($iname.$e) break + file mkdir [file dirname $dest] + file copy -force $origin $dest + return $dest + } + } + return {} +} + +# ::doctools::Source -- +# +# API for formatter. Used by engine to ask for +# additional script files support it. +# +# Arguments: +# name Name of the doctools object to change. +# +# Results: +# Boolean flag. + +proc ::doctools::Source {ip path file} { + #puts stderr "$ip (source $path $file)" + + $ip invokehidden source [file join $path [file tail $file]] + #$ip eval [list source [file join $path [file tail $file]]] + return +} + +proc ::doctools::Read {ip path file} { + #puts stderr "$ip (read $path $file)" + + return [read [set f [open [file join $path [file tail $file]]]]][close $f] +} + +proc ::doctools::Locate {p} { + # @mdgen NODEP: doctools::__undefined__ + catch {package require doctools::__undefined__} + + #puts stderr "auto_path = [join $::auto_path \n]" + + # Check if requested package is in the list of loadable packages. + # Then get the highest possible version, and then the index script + + if {[lsearch -exact [package names] $p] < 0} { + return -code error "Unknown package $p" + } + + set v [lindex [lsort -increasing [package versions $p]] end] + + #puts stderr "Package $p = $v" + + return [package ifneeded $p $v] +} + +proc ::doctools::FileOp {ip args} { + #puts stderr "$ip (file $args)" + # -- FUTURE -- disallow unsafe operations -- + + return [eval [linsert $args 0 file]] +} + +proc ::doctools::Package {ip pkg} { + #puts stderr "$ip package require $pkg" + + set indexScript [Locate $pkg] + + $ip expose source + $ip expose load + $ip eval $indexScript + $ip hide source + $ip hide load + #$ip eval [list source [file join $path [file tail $file]]] + return +} + +#------------------------------------ +# Module initialization + +namespace eval ::doctools { + # Reverse order of searching. First to search is specified last. + + # FOO/doctools.tcl + # => FOO/mpformats + + #catch {search [file join $here lib doctools mpformats]} + #catch {search [file join [file dirname $here] lib doctools mpformats]} + catch {search [file join $here mpformats]} +} + +package provide doctools 1.4.19 diff --git a/tcllib/modules/doctools/doctools.test b/tcllib/modules/doctools/doctools.test new file mode 100644 index 0000000..9d7935c --- /dev/null +++ b/tcllib/modules/doctools/doctools.test @@ -0,0 +1,443 @@ +# -*- tcl -*- +# doctools.test: tests for the doctools package. +# +# This file contains a collection of tests for one or more of the Tcl +# built-in commands. Sourcing this file into Tcl runs the tests and +# generates output for errors. No output means no errors were found. +# +# Copyright (c) 2003-2010 by Andreas Kupries <andreas_kupries@users.sourceforge.net> +# All rights reserved. +# +# RCS: @(#) $Id: doctools.test,v 1.28 2011/01/13 02:41:44 andreas_kupries Exp $ + +# ------------------------------------------------------------------------- + +source [file join \ + [file dirname [file dirname [file join [pwd] [info script]]]] \ + devtools testutilities.tcl] + +testsNeedTcl 8.2 +testsNeedTcltest 1.0 + +support { + use textutil/expander.tcl textutil::expander + use fileutil/fileutil.tcl fileutil +} +testing { + useLocal doctools.tcl doctools +} + +# ------------------------------------------------------------------------- + +array_unset env LANG* +array_unset env LC_* +set env(LANG) C ; # Usually default if nothing is set, OS X requires this. + +# ------------------------------------------------------------------------- + +namespace import ::doctools::new + +# --------------------------------------------------- + +# search paths ............................................................. + +test doctools-1.0 {default search paths} { + llength $::doctools::paths +} 1 + +test doctools-1.1 {extend package search paths} { + ::doctools::search [file dirname [info script]] + set res [list] + lappend res [llength $::doctools::paths] + lappend res [lindex $::doctools::paths 0] + set res +} [list 2 [file dirname [info script]]] + +test doctools-1.2 {extend package search paths, error} { + catch {::doctools::search foo} result + set result +} {doctools::search: path does not exist} + +# format help ............................................................. + +test doctools-2.0 {format help} { + string length [doctools::help] +} 2213 + +# doctools ............................................................. + +test doctools-3.0 {doctools errors} { + catch {new} msg + set msg +} [tcltest::wrongNumArgs "new" "name args" 0] + +test doctools-3.1 {doctools errors} { + catch {new set} msg + set msg +} "command \"set\" already exists, unable to create doctools object" + +test doctools-3.2 {doctools errors} { + new mydoctools + catch {new mydoctools} msg + mydoctools destroy + set msg +} "command \"mydoctools\" already exists, unable to create doctools object" + +test doctools-3.3 {doctools errors} { + catch {new mydoctools -foo} msg + set msg +} {wrong # args: doctools::new name ?opt val...??} + +# doctools methods ...................................................... + +test doctools-4.0 {doctools method errors} { + new mydoctools + catch {mydoctools} msg + mydoctools destroy + set msg +} "wrong # args: should be \"mydoctools option ?arg arg ...?\"" + +test doctools-4.1 {doctools errors} { + new mydoctools + catch {mydoctools foo} msg + mydoctools destroy + set msg +} "bad option \"foo\": must be cget, configure, destroy, format, map, search, warnings, parameters, or setparam" + +# cget .................................................................. + +test doctools-5.0 {cget errors} { + new mydoctools + catch {mydoctools cget} result + mydoctools destroy + set result +} [tcltest::wrongNumArgs "::doctools::_cget" "name option" 1] + +test doctools-5.1 {cget errors} { + new mydoctools + catch {mydoctools cget foo bar} result + mydoctools destroy + set result +} [tcltest::tooManyArgs "::doctools::_cget" "name option"] + +test doctools-5.2 {cget errors} { + new mydoctools + catch {mydoctools cget -foo} result + mydoctools destroy + set result +} {doctools::_configure: Unknown option "-foo", expected -copyright, -file, -ibase, -module, -format, or -deprecated} + +foreach {na nb option default newvalue} { + 3 4 -deprecated 0 1 + 5 6 -file {} foo + 7 8 -module {} bar + 9 10 -format {} latex + 11 12 -copyright {} {Andreas Kupries} +} { + test doctools-5.$na {cget query} { + new mydoctools + set res [mydoctools cget $option] + mydoctools destroy + set res + } $default ; # {} + + test doctools-5.$nb {cget set & query} { + new mydoctools + mydoctools configure $option $newvalue + set res [mydoctools cget $option] + mydoctools destroy + set res + } $newvalue ; # {} +} + +# configure .................................................................. + +test doctools-6.0 {configure errors} { + new mydoctools + catch {mydoctools configure -foo bar -glub} result + mydoctools destroy + set result +} {wrong # args: doctools::_configure name ?opt val...??} +# [tcltest::wrongNumArgs "::doctools::_configure" "name ?option?|?option value...?" 1] + +test doctools-6.1 {configure errors} { + new mydoctools + catch {mydoctools configure -foo} result + mydoctools destroy + set result +} {doctools::_configure: Unknown option "-foo", expected -copyright, -file, -ibase, -module, -format, or -deprecated} + +test doctools-6.2 {configure retrieval} { + new mydoctools + catch {mydoctools configure} result + mydoctools destroy + set result +} {-file {} -ibase {} -module {} -format {} -copyright {} -deprecated 0} + +foreach {n option illegalvalue result} { + 3 -deprecated foo {doctools::_configure: -deprecated expected a boolean, got "foo"} + 4 -format barf {doctools::_configure: -format: Unknown format "barf"} +} { + test doctools-6.$n {configure illegal value} { + new mydoctools + catch {mydoctools configure $option $illegalvalue} result + mydoctools destroy + set result + } $result +} + +foreach {na nb option default newvalue} { + 5 6 -deprecated 0 1 + 7 8 -file {} foo + 9 10 -module {} bar + 11 12 -format {} latex + 13 14 -copyright {} {Andreas Kupries} +} { + test doctools-6.$na {configure query} { + new mydoctools + set res [mydoctools configure $option] + mydoctools destroy + set res + } $default ; # {} + + test doctools-6.$nb {configure set & query} { + new mydoctools + mydoctools configure $option $newvalue + set res [mydoctools configure $option] + mydoctools destroy + set res + } $newvalue ; # {} +} + +test doctools-6.15 {configure full retrieval} { + new mydoctools -file foo -module bar -format latex -deprecated 1 -copyright gnarf + catch {mydoctools configure} result + mydoctools destroy + set result +} {-file foo -ibase {} -module bar -format latex -copyright gnarf -deprecated 1} + +# search .................................................................. + +test doctools-7.0 {search errors} { + new mydoctools + catch {mydoctools search} result + mydoctools destroy + set result +} [tcltest::wrongNumArgs "::doctools::_search" "name path" 1] + +test doctools-7.1 {search errors} { + new mydoctools + catch {mydoctools search foo bar} result + mydoctools destroy + set result +} [tcltest::tooManyArgs "::doctools::_search" "name path"] + +test doctools-7.2 {search errors} { + new mydoctools + catch {mydoctools search foo} result + mydoctools destroy + set result +} {mydoctools search: path does not exist} + +test doctools-7.3 {search, initial} { + new mydoctools + set res [llength $::doctools::doctoolsmydoctools::paths] + mydoctools destroy + set res +} 0 + +test doctools-7.4 {extend object search paths} { + new mydoctools + mydoctools search [file dirname [info script]] + set res [list] + lappend res [llength $::doctools::doctoolsmydoctools::paths] + lappend res [lindex $::doctools::doctoolsmydoctools::paths 0] + mydoctools destroy + set res +} [list 1 [file dirname [info script]]] + +# format & warnings ....................................................... + +test doctools-8.0 {format errors} { + new mydoctools + catch {mydoctools format} result + mydoctools destroy + set result +} [tcltest::wrongNumArgs "::doctools::_format" "name text" 1] + +test doctools-8.1 {format errors} { + new mydoctools + catch {mydoctools format foo bar} result + mydoctools destroy + set result +} [tcltest::tooManyArgs "::doctools::_format" "name text"] + +test doctools-8.2 {format errors} { + new mydoctools + catch {mydoctools format foo} result + mydoctools destroy + set result +} {mydoctools: No format was specified} + + +test doctools-8.3 {format} { + new mydoctools -format list + set res [mydoctools format {[manpage_begin foo n 1.0][description][strong foo][manpage_end]}] + set res [list [lindex $res 0] [dictsort [lindex $res 1]]] + lappend res [mydoctools warnings] + mydoctools destroy + set res +} {manpage {category {} desc {} fid {} file {} keywords {} module {} section n seealso {} shortdesc {} title foo version 1.0} {}} + +test doctools-8.4 {format} { + new mydoctools -format list -deprecated on + set res [mydoctools format {[manpage_begin foo n 1.0][description][strong foo][manpage_end]}] + set res [list [lindex $res 0] [dictsort [lindex $res 1]]] + lappend res [mydoctools warnings] + mydoctools destroy + set res +} {manpage {category {} desc {} fid {} file {} keywords {} module {} section n seealso {} shortdesc {} title foo version 1.0} {{DocTools Warning (depr_strong): In macro at line 1, column 38 of file : +DocTools Warning (depr_strong): Deprecated command "[strong]". +DocTools Warning (depr_strong): Please consider appropriate semantic markup or [emph] instead.}}} + + + +# doctools manpage syntax ....................................................... + +test doctools-9.0 {manpage syntax} { + new mydoctools -format null + catch {mydoctools format foo} result + mydoctools destroy + set result +} {Doctools Error in plain text at line 1, column 0: +[plain_text foo] +--> (FmtError) Manpage error (body), "plain_text foo" : Plain text not allowed outside of the body of the manpage.} + +# ------------------------------------------------------------------------- +## Series of tests for all available backends, check their formatting. + +set k 11 +foreach format { + html tmml + nroff latex + text wiki + desc list null +} { + set n 0 + foreach src [TestFilesGlob tests/man/*] { + if {[file tail $src] == "CVS"} continue + + # Get the expected result + set dst [localPath [file join tests $format [file tail $src]]] + set map @ID@ ; lappend map \$Id\$ ; lappend map @USR@ $tcl_platform(user) + set rem \$Id\$ ; lappend rem @ID@ ; lappend $tcl_platform(user) @USR@ + if {$format eq "nroff"} { + lappend map ".so man.macros\n" [fileutil::cat [localPath mpformats/man.macros]] + } + if {[catch { + set expected [string map $map [fileutil::cat $dst]] + }]} { set expected **missing** } + + test doctools-${format}-${k}.$n "doctools backends, $format/[file tail $src]" { + new mydoctools + mydoctools configure \ + -format $format \ + -module .MODULE. \ + -file .FILE. \ + -copyright .COPYRIGHT. + if {[catch { + set res [mydoctools format [fileutil::cat $src]] + }]} { + set res $::errorInfo + } + mydoctools destroy + #fileutil::writeFile ${dst}.actual [string map $rem $res] + set res + } $expected + + #fileutil::writeFile ${dst}.expected $expected + incr n + } + incr k +} + + +# ------------------------------------------------------------------------- +## Test of special 'raw' mode available to the HTML backend. + +set n 0 +foreach src [TestFilesGlob tests/man/*] { + if {[file tail $src] == "CVS"} continue + + # Get the expected result + set dst [localPath [file join tests html [file tail $src]]] + set map @ID@ ; lappend map \$Id\$ ; lappend map @USR@ $tcl_platform(user) + set rem \$Id\$ ; lappend rem @ID@ ; lappend $tcl_platform(user) @USR@ + + if {[catch { + set expected [string map $map [fileutil::cat $dst]] + }]} { set expected **missing** } + + # Transform regular output to contents of body/, i.e. raw output. + regsub {</body>.*} $expected {} expected + regsub {.*<body>} $expected {} expected + append expected \n + if {$n == 5 || $n == 8} { set expected \n$expected } + + # Run the test ... + test doctools-html-raw-11.$n "doctools backends, html-raw/[file tail $src]" { + new mydoctools + mydoctools configure \ + -format html \ + -module .MODULE. \ + -file .FILE. \ + -copyright .COPYRIGHT. + mydoctools setparam raw 1 + if {[catch { + set res [mydoctools format [fileutil::cat $src]] + }]} { + set res $::errorInfo + } + mydoctools destroy + #fileutil::writeFile ${dst}.actual [string map $rem $res] + set res + } $expected + + #fileutil::writeFile ${dst}.expected $expected + incr n +} + +# ------------------------------------------------------------------------- +## Series of tests for the frontend, cover all possible syntax errors. + +set n 0 +foreach src [TestFilesGlob tests/syntax/e_*] { + set dst [file join [file dirname $src] r_[string range [file tail ${src}] 2 end]] + set expected [string trim [fileutil::cat $dst]] + + test doctools-syntax-error-10.$n "doctools frontend, syntax error, [file tail $src]" { + new mydoctools + mydoctools configure \ + -format null \ + -module .MODULE. \ + -file .FILE. \ + -copyright .COPYRIGHT. + + catch { + mydoctools format [fileutil::cat $src] + } res + mydoctools destroy + #fileutil::writeFile ${src}.actual $msg + set res + } $expected + + #fileutil::writeFile ${dst}.expected $expected + incr n +} + +# ------------------------------------------------------------------------- + +namespace forget ::doctools::new + +testsuiteCleanup +return diff --git a/tcllib/modules/doctools/doctools_intro.man b/tcllib/modules/doctools/doctools_intro.man new file mode 100644 index 0000000..9a2229a --- /dev/null +++ b/tcllib/modules/doctools/doctools_intro.man @@ -0,0 +1,103 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools_intro n 1.0] +[see_also docidx_intro] +[see_also doctoc_intro] +[see_also doctools] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[see_also doctools_plugin_apiref] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools introduction}] +[category {Documentation tools}] +[description] +[para] + +[term doctools] (short for [emph {documentation tools}]) stands for +a set of related, yet different, entities which are working together +for the easy creation and transformation of documentation. These are + +[list_begin enumerated] +[enum] + +A tcl based language for the semantic markup of text. Markup is +represented by Tcl commands interspersed with the actual text. + +[enum] + +A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins. + +[enum] + +An API describing the interface between the package above and a +plugin. + +[list_end] + +[para] + +Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process. + +[para] + +[list_begin enumerated] +[enum] +A [term writer] of documentation has to understand the markup language +itself. A beginner to doctools should read the more informally written +[term {doctools language introduction}] first. Having digested this +the formal [term {doctools language syntax}] specification should +become understandable. A writer experienced with doctools may only +need the [term {doctools language command reference}] from time to +time to refresh her memory. + +[para] + +While a document is written the [syscmd dtplite] application can be +used to validate it, and after completion it also performs the +conversion into the chosen system of visual markup, be it *roff, HTML, +plain text, wiki, etc. + +[enum] +A [term processor] of documentation written in the [term doctools] +markup language has to know which tools are available for use. + +[para] + +The main tool is the aforementioned [syscmd dtplite] application +provided by Tcllib. A more powerful one (in terms of options and +ability to configure it) is the [syscmd dtp] application, provided by +Tclapps. + +At the bottom level, common to both applications, however sits the +package [package doctools], providing the basic facilities to read and +process files containing text in the doctools format. + +[enum] + +At last, but not least, [term {plugin writers}] have to understand the +interaction between the [package doctools] package and its plugins, as +described in the [term {doctools plugin API reference}]. + +[list_end] + +[section {RELATED FORMATS}] + +doctools does not stand alone, it has two companion formats. These are +called [term docidx] and [term doctoc], and they are for the markup of +[term {keyword indices}], and [term {tables of contents}], +respectively. + +They are described in their own sets of documents, starting at the +[term {docidx introduction}] and the [term {doctoc introduction}], +respectively. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools_lang_cmdref.man b/tcllib/modules/doctools/doctools_lang_cmdref.man new file mode 100644 index 0000000..7552fdf --- /dev/null +++ b/tcllib/modules/doctools/doctools_lang_cmdref.man @@ -0,0 +1,470 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools_lang_cmdref n 1.0] +[see_also doctools_intro] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools language command reference}] +[category {Documentation tools}] +[description] +[para] + +This document specifies both names and syntax of all the commands +which together are the doctools markup language, version 1. + +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. + +A beginner should read the much more informally written +[term {doctools language introduction}] first. + +[section Commands] +[list_begin definitions] + +[call [cmd arg] [arg text]] + +Text markup. The argument text is marked up as the [term argument] of +a command. Main uses are the highlighting of command arguments in +free-form text, and for the argument parameters of the markup commands +[cmd call] and [cmd usage]. + +[call [cmd arg_def] [arg type] [arg name] [opt [arg mode]]] + +Text structure. List element. Argument list. Automatically closes the +previous list element. Specifies the data-[arg type] of the described +argument of a command, its [arg name] and its i/o-[arg mode]. The +latter is optional. + +[call [cmd bullet]] + +[emph Deprecated]. Text structure. List element. Itemized list. See +[cmd item] for the canonical command to open a list item in an +itemized list. + +[call [cmd call] [arg args]] + +Text structure. List element. Definition list. Automatically closes +the previous list element. Defines the term as a command and its +arguments. + +The first argument is the name of the command described by the +following free-form text, and all arguments coming after that are +descriptions of the command's arguments. + +It is expected that the arguments are marked up with [cmd arg], +[cmd method], [cmd option] etc., as is appropriate, and that the +command itself is marked up with [cmd cmd]. + +It is expected that the formatted term is not only printed in place, +but also in the table of contents of the document, or synopsis, +depending on the output format. + +[call [cmd category] [arg text]] + +Document information. Anywhere. This command registers its plain text +arguments as the category this document belongs to. If this command is +used multiple times the last value specified is used. + +[call [cmd class] [arg text]] + +Text markup. The argument is marked up as the name of a +[term class]. The text may have other markup already applied to +it. Main use is the highlighting of class names in free-form text. + +[call [cmd cmd] [arg text]] + +Text markup. The argument text is marked up as the name of a +[term {Tcl command}]. The text may have other markup already applied +to it. Main uses are the highlighting of commands in free-form text, +and for the command parameters of the markup commands [cmd call] and +[cmd usage]. + +[call [cmd cmd_def] [arg command]] + +Text structure. List element. Command list. Automatically closes the +previous list element. The argument specifies the name of the +[term {Tcl command}] to be described by the list element. Expected to +be marked up in the output as if it had been formatted with [cmd cmd]. + +[call [cmd comment] [arg plaintext]] + +Text markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text. + +[call [cmd const] [arg text]] + +Text markup. The argument is marked up as a [term constant] value. The +text may have other markup already applied to it. Main use is the +highlighting of constants in free-form text. + +[call [cmd copyright] [arg text]] + +Document information. Anywhere. The command registers the plain text +argument as a copyright assignment for the manpage. When invoked more +than once the assignments are accumulated. + +[call [cmd def] [arg text]] + +Text structure. List element. Definition list. Automatically closes +the previous list element. The argument text is the term defined by +the new list element. Text markup can be applied to it. + +[call [cmd description]] + +Document structure. This command separates the header from the +document body. Implicitly starts a section named "DESCRIPTION" (See +command [cmd section]). + +[call [cmd enum]] + +Text structure. List element. Enumerated list. Automatically closes +the previous list element. + +[call [cmd emph] [arg text]] + +Text markup. The argument text is marked up as emphasized. Main use is +for general highlighting of pieces of free-form text without attaching +special meaning to the pieces. + +[call [cmd example] [arg text]] + +Text structure, Text markup. This command marks its argument up as an +[term example]. Main use is the simple embedding of examples in +free-form text. It should be used if the example does [emph not] need +special markup of its own. Otherwise use a sequence of +[cmd example_begin] ... [cmd example_end]. + +[call [cmd example_begin]] + +Text structure. This commands starts an example. All text until the +next [cmd example_end] belongs to the example. Line breaks, spaces, +and tabs have to be preserved literally. Examples cannot be nested. + +[call [cmd example_end]] + +Text structure. This command closes the example started by the last +[cmd example_begin]. + +[call [cmd file] [arg text]] + +Text markup. The argument is marked up as a [term file] or +[term directory], i.e. in general a [term path]. The text may have +other markup already applied to it. Main use is the highlighting of +paths in free-form text. + +[call [cmd fun] [arg text]] + +Text markup. The argument is marked up as the name of a +[term function]. The text may have other markup already applied to +it. Main use is the highlighting of function names in free-form text. + +[call [cmd image] [arg name] [opt [arg label]]] + +Text markup. The argument is the symbolic name of an [term image] +and replaced with the image itself, if a suitable variant is found +by the backend. The second argument, should it be present, will be +interpreted the human-readable description of the image, and put +into the output in a suitable position, if such is supported by the +format. The HTML format, for example, can place it into the [term alt] +attribute of image references. + +[call [cmd include] [arg filename]] + +Templating. The contents of the named file are interpreted as text +written in the doctools markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries. + +[call [cmd item]] + +Text structure. List element. Itemized list. Automatically closes the +previous list element. + +[call [cmd keywords] [arg args]] + +Document information. Anywhere. This command registers all its plain text +arguments as keywords applying to this document. Each argument is a single +keyword. If this command is used multiple times all the arguments accumulate. + +[call [cmd lb]] + +Text. The command is replaced with a left bracket. Use in free-form text. +Required to avoid interpretation of a left bracket as the start of a markup +command. + +[call [cmd list_begin] [arg what]] + +Text structure. This command starts a list. The exact nature of the +list is determined by the argument [arg what] of the command. This +further determines which commands are have to be used to start the +list elements. Lists can be nested, i.e. it is allowed to start a new +list within a list element. + +[para] +The allowed types (and their associated item commands) are: + +[list_begin definitions] +[def [const arguments]] [cmd arg_def]. +[def [const commands]] [cmd cmd_def]. +[def [const definitions]] [cmd def] and [cmd call]. +[def [const enumerated]] [cmd enum] +[def [const itemized]] [cmd item] +[def [const options]] [cmd opt_def] +[def [const tkoptions]] [cmd tkoption_def] +[list_end] +[para] + +Additionally the following names are recognized as shortcuts for some +of the regular types: + +[list_begin definitions] +[def [const args]] Short for [const arguments]. +[def [const cmds]] Short for [const commands]. +[def [const enum]] Short for [const enumerated]. +[def [const item]] Short for [const itemized]. +[def [const opts]] Short for [const options]. +[list_end] +[para] + +At last the following names are still recognized for backward +compatibility, but are otherwise considered to be [emph deprecated]. + +[list_begin definitions] +[def [const arg]] [emph Deprecated]. See [const arguments]. +[def [const bullet]] [emph Deprecated]. See [const itemized]. +[def [const cmd]] [emph Deprecated]. See [const commands]. +[def [const opt]] [emph Deprecated]. See [const options]. +[def [const tkoption]] [emph Deprecated]. See [const tkoptions]. +[list_end] + +[para] + +[call [cmd list_end]] + +Text structure. This command closes the list opened by the last +[cmd list_begin] command coming before it. + +[call [cmd lst_item] [arg text]] + +[emph Deprecated]. Text structure. List element. Definition list. See +[cmd def] for the canonical command to open a general list item in a +definition list. + +[call [cmd manpage_begin] [arg command] [arg section] [arg version]] +[see_also doctools_intro] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords markup] +[keywords {semantic markup}] + +Document structure. The command to start a manpage. The arguments are +the name of the [arg command] described by the manpage, the +[arg section] of the manpages this manpage resides in, and the +[arg version] of the module containing the command. All arguments have +to be plain text, without markup. +[call [cmd manpage_end]] + +Document structure. Command to end a manpage/document. Anything in the document +coming after this command is in error. + +[call [cmd method] [arg text]] + +Text markup. The argument text is marked up as the name of an +[term object] [term method], i.e. subcommand of a Tcl command. The +text may have other markup already applied to it. Main uses are the +highlighting of method names in free-form text, and for the command +parameters of the markup commands [cmd call] and [cmd usage]. + +[call [cmd moddesc] [arg text]] + +Document information. Header. Registers the plain text argument as a short +description of the module the manpage resides in. + +[call [cmd namespace] [arg text]] + +Text markup. The argument text is marked up as a namespace name. The +text may have other markup already applied to it. Main use is the +highlighting of namespace names in free-form text. + +[call [cmd nl]] + +[emph Deprecated]. Text structure. See [cmd para] for the canonical +command to insert paragraph breaks into the text. + +[call [cmd opt] [arg text]] + +Text markup. The argument text is marked up as [term optional]. The text may +have other markup already applied to it. Main use is the highlighting of +optional arguments, see the command arg [cmd arg]. + +[call [cmd opt_def] [arg name] [opt [arg arg]]] + +Text structure. List element. Option list. Automatically closes the +previous list element. Specifies [arg name] and arguments of the +[term option] described by the list element. It is expected that the +name is marked up using [cmd option]. + +[call [cmd option] [arg text]] + +Text markup. The argument is marked up as [term option]. The text may +have other markup already applied to it. Main use is the highlighting +of options, also known as command-switches, in either free-form text, +or the arguments of the [cmd call] and [cmd usage] commands. + +[call [cmd package] [arg text]] + +Text markup. The argument is marked up as the name of a +[term package]. The text may have other markup already applied to +it. Main use is the highlighting of package names in free-form text. + +[call [cmd para]] + +Text structure. This command breaks free-form text into +paragraphs. Each command closes the paragraph coming before it and +starts a new paragraph for the text coming after it. Higher-level +forms of structure are sections and subsections. + +[call [cmd rb]] + +Text. The command is replaced with a right bracket. Use in free-form text. +Required to avoid interpretation of a right bracket as the end of a markup +command. + +[call [cmd require] [arg package] [opt [arg version]]] + +Document information. Header. This command registers its argument +[arg package] as the name of a package or application required by the +described package or application. A minimum version can be provided as +well. This argument can be marked up. The usual markup is [cmd opt]. + +[call [cmd section] [arg name]] + +Text structure. This command starts a new named document section. The +argument has to be plain text. Implicitly closes the last paragraph +coming before it and also implicitly opens the first paragraph of the +new section. + +[call [cmd sectref] [arg id] [opt [arg text]]] + +Text markup. Formats a reference to the section identified by [arg id]. +If no [arg text] is specified the title of the referenced section is +used in the output, otherwise [arg text] is used. + +[call [cmd sectref-external] [arg text]] + +Text markup. Like [cmd sectref], except that the section is assumed to +be in a different document and therefore doesn't need to be identified, +nor are any checks for existence made. Only the text to format is needed. + +[call [cmd see_also] [arg args]] + +Document information. Anywhere. The command defines direct cross-references +to other documents. Each argument is a plain text label identifying the +referenced document. If this command is used multiple times all the arguments +accumulate. + +[call [cmd strong] [arg text]] + +[emph Deprecated]. Text markup. See [cmd emph] for the canonical +command to emphasize text. + +[call [cmd subsection] [arg name]] + +Text structure. This command starts a new named subsection of a +section. The argument has to be plain text. Implicitly closes the last +paragraph coming before it and also implicitly opens the first +paragraph of the new subsection. + +[call [cmd syscmd] [arg text]] + +Text markup. The argument text is marked up as the name of an external +command. The text may have other markup already applied to it. Main +use is the highlighting of external commands in free-form text. + +[call [cmd term] [arg text]] + +Text markup. The argument is marked up as unspecific terminology. The +text may have other markup already applied to it. Main use is the +highlighting of important terms and concepts in free-form text. + +[call [cmd titledesc] [arg desc]] + +Document information. Header. Optional. Registers the plain text +argument as the title of the manpage. Defaults to the value registered +by [cmd moddesc]. + +[call [cmd tkoption_def] [arg name] [arg dbname] [arg dbclass]] + +Text structure. List element. Widget option list. Automatically closes +the previous list element. Specifies the [arg name] of the option as +used in scripts, the name used by the option database ([arg dbname]), +and its class ([arg dbclass]), i.e. its type. It is expected that the +name is marked up using [cmd option]. + +[call [cmd type] [arg text]] + +Text markup. The argument is marked up as the name of a +[term {data type}]. The text may have other markup already applied to +it. Main use is the highlighting of data types in free-form text. + +[call [cmd uri] [arg text] [opt [arg text]]] + +Text markup. The argument is marked up as an [term uri] (i.e. a +[term {uniform resource identifier}]. The text may have other markup +already applied to it. Main use is the highlighting of uris in +free-form text. The second argument, should it be present, will be +interpreted the human-readable description of the uri. In other words, +as its label. Without an explicit label the uri will be its own label. + +[call [cmd usage] [arg args]] + +Text markup. See [cmd call] for the full description, this command is +syntactically identical, as it is in its expectations for the markup +of its arguments. + +In contrast to [cmd call] it is however not allowed to generate output +where this command occurs in the text. The command is [term silent]. +The formatted text may only appear in a different section of the +output, for example a table of contents, or synopsis, depending on the +output format. + +[call [cmd var] [arg text]] + +Text markup. The argument is marked up as the name of a +[term variable]. The text may have other markup already applied to +it. Main use is the highlighting of variables in free-form text. + +[call [cmd vset] [arg varname] [arg value] ] + +Templating. In this form the command sets the named document variable +to the specified [arg value]. It does not generate output. I.e. the +command is replaced by the empty string. + +[call [cmd vset] [arg varname]] + +Templating. In this form the command is replaced by the value of the +named document variable + +[call [cmd widget] [arg text]] + +Text markup. The argument is marked up as the name of a +[term widget]. The text may have other markup already applied to +it. Main use is the highlighting of widget names in free-form text. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools_lang_faq.man b/tcllib/modules/doctools/doctools_lang_faq.man new file mode 100644 index 0000000..f30a9dd --- /dev/null +++ b/tcllib/modules/doctools/doctools_lang_faq.man @@ -0,0 +1,28 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools_lang_faq n 1.0] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords examples] +[keywords faq] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools language faq}] +[category {Documentation tools}] +[description] +[vset theformat doctools] + +[section OVERVIEW] + +[include include/placeholder.inc] +[include include/examples.inc] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools_lang_intro.man b/tcllib/modules/doctools/doctools_lang_intro.man new file mode 100644 index 0000000..9aced05 --- /dev/null +++ b/tcllib/modules/doctools/doctools_lang_intro.man @@ -0,0 +1,727 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools_lang_intro n 1.0] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools language introduction}] +[category {Documentation tools}] +[description] +[para] + +This document is an informal introduction to version 1 of the doctools +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the [term {doctools language syntax}] specification +and the [term {doctools language command reference}]. + +[subsection Fundamentals] + +In the broadest terms possible the [term {doctools markup language}] +is LaTeX-like, instead of like SGML and similar languages. A document +written in this language consists primarily of text, with markup +commands embedded into it. + +[para] + +Each markup command is a Tcl command surrounded by a matching pair of +[const [lb]] and [const [rb]]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e. + +[para] +[example { + ... [list_begin enumerated] ... +}] + +[example { + ... [call [cmd foo] \\ + [arg bar]] ... +}] + +[example { + ... [term {complex concept}] ... +}] + +[example { + ... [opt "[arg key] [arg value]"] ... +}] + +[subsection {Basic structure}] + +The most simple document which can be written in doctools is + +[example { + [manpage_begin NAME SECTION VERSION] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] + [description] + [vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] +}] + +This also shows us that all doctools documents are split into two +parts, the [term header] and the [term body]. Everything coming before +[lb][cmd description][rb] belongs to the header, and everything coming +after belongs to the body, with the whole document bracketed by the +two [cmd manpage_*] commands. Before and after these opening and +closing commands we have only [term whitespace]. + +[para] + +In the remainder of this section we will discuss only the contents of +the header, the structure of the body will be discussed in the section +[sectref {Text structure}]. + +[para] + +The header section can be empty, and otherwise may contain only an +arbitrary sequence of the four so-called [term header] commands, plus +[term whitespace]. These commands are + +[list_begin commands] +[cmd_def titledesc] +[cmd_def moddesc] +[cmd_def require] +[cmd_def copyright] +[list_end] + +They provide, through their arguments, additional information about +the document, like its title, the title of the larger group the +document belongs to (if applicable), the requirements of the +documented packages (if applicable), and copyright assignments. All of +them can occur multiple times, including none, and they can be used in +any order. + +However for [cmd titledesc] and [cmd moddesc] only the last occurrence +is taken. For the other two the specified information is accumulated, +in the given order. Regular text is not allowed within the header. + +[para] + +Given the above a less minimal example of a document is + +[example_begin] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb][cmd {copyright {YEAR AUTHOR}}][rb] +[lb][cmd {titledesc TITLE}][rb] +[lb][cmd {moddesc MODULE_TITLE}][rb] +[lb][cmd {require PACKAGE VERSION}][rb] +[lb][cmd {require PACKAGE}][rb] +[lb]description[rb] +[lb]manpage_end[rb] +[example_end] + +Remember that the whitespace is optional. The document + +[example { + [manpage_begin NAME SECTION VERSION] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] + [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] + [require PACKAGE VERSION][require PACKAGE][description] + [vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] +}] + +has the same meaning as the example before. + +[para] + +On the other hand, if [term whitespace] is present it consists not +only of any sequence of characters containing the space character, +horizontal and vertical tabs, carriage return, and newline, but it may +contain comment markup as well, in the form of the [cmd comment] +command. + +[example_begin] +[lb][cmd {comment { ... }}][rb] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb]copyright {YEAR AUTHOR}[rb] +[lb]titledesc TITLE[rb] +[lb]moddesc MODULE_TITLE[rb][lb][cmd {comment { ... }}][rb] +[lb]require PACKAGE VERSION[rb] +[lb]require PACKAGE[rb] +[lb]description[rb] +[lb]manpage_end[rb] +[lb][cmd {comment { ... }}][rb] +[example_end] + +[subsection {Advanced structure}] + +In the simple examples of the last section we fudged a bit regarding +the markup actually allowed to be used before the [cmd manpage_begin] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +command opening the document. + +[para] + +Instead of only whitespace the two templating commands [cmd include] +and [cmd vset] are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the document. I.e. it +is possible to write + +[example_begin] +[lb][cmd {include FILE}][rb] +[lb][cmd {vset VAR VALUE}][rb] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb]description[rb] +[lb]manpage_end[rb] +[example_end] + +Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. I.e. for example in the header as well. + +[example_begin] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb][cmd {include FILE}][rb] +[lb][cmd {vset VAR VALUE}][rb] +[lb]description[rb] +[lb]manpage_end[rb] +[example_end] + +The only restriction [cmd include] has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before [cmd manpage_begin] may contain only the +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +templating commands [cmd vset] and [cmd include], a file included in +the header may contain only header commands, etc. + +[subsection {Text structure}] + +The body of the document consists mainly of text, possibly split into +sections, subsections, and paragraphs, with parts marked up to +highlight various semantic categories of text, and additional +structure through the use of examples and (nested) lists. + +[para] + +This section explains the high-level structural commands, with +everything else deferred to the following sections. + +[para] + +The simplest way of structuring the body is through the introduction +of paragraphs. The command for doing so is [cmd para]. Each occurrence +of this command closes the previous paragraph and automatically opens +the next. The first paragraph is automatically opened at the beginning +of the body, by [cmd description]. In the same manner the last +paragraph automatically ends at [cmd manpage_end]. + +[example_begin] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb]description[rb] + ... +[lb][cmd para][rb] + ... +[lb][cmd para][rb] + ... +[lb]manpage_end[rb] +[example_end] + +Empty paragraphs are ignored. + +[para] + +A structure coarser than paragraphs are sections, which allow the +writer to split a document into larger, and labeled, pieces. The +command for doing so is [cmd section]. Each occurrence of this command +closes the previous section and automatically opens the next, +including its first paragraph. The first section is automatically +opened at the beginning of the body, by [cmd description] (This +section is labeled "DESCRIPTION"). In the same manner the last section +automatically ends at [cmd manpage_end]. + +[para] + +Empty sections are [emph not] ignored. We are free to (not) use +paragraphs within sections. + +[example_begin] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb]description[rb] + ... +[lb][cmd {section {Section A}}][rb] + ... +[lb]para[rb] + ... +[lb][cmd {section {Section B}}][rb] + ... +[lb]manpage_end[rb] +[example_end] + +Between sections and paragraphs we have subsections, to split sections. + +The command for doing so is [cmd subsection]. Each occurrence of this +command closes the previous subsection and automatically opens the +next, including its first paragraph. A subsection is automatically +opened at the beginning of the body, by [cmd description], and at the +beginning of each section. In the same manner the last subsection +automatically ends at [cmd manpage_end]. + +[para] + +Empty subsections are [emph not] ignored. We are free to (not) use +paragraphs within subsections. + +[example_begin] +[lb]manpage_begin NAME SECTION VERSION[rb] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[lb]description[rb] + ... +[lb]section {Section A}[rb] + ... +[lb][cmd {subsection {Sub 1}}][rb] + ... +[lb]para[rb] + ... +[lb][cmd {subsection {Sub 2}}][rb] + ... +[lb]section {Section B}[rb] + ... +[lb]manpage_end[rb] +[example_end] + +[subsection {Text markup}] + +Having handled the overall structure a writer can impose on the +document we now take a closer at the text in a paragraph. + +[para] + +While most often this is just the unadorned content of the document we +do have situations where we wish to highlight parts of it as some type +of thing or other, like command arguments, command names, concepts, +uris, etc. + +[para] + +For this we have a series of markup commands which take the text to +highlight as their single argument. It should be noted that while +their predominant use is the highlighting of parts of a paragraph they +can also be used to mark up the arguments of list item commands, and +of other markup commands. + +[para] + +The commands available to us are + +[list_begin commands] +[cmd_def arg] Its argument is a the name of a command argument. +[cmd_def class] Its argument is a class name. +[cmd_def cmd] Its argument is a command name (Tcl command). +[cmd_def const] Its argument is a constant. +[cmd_def emph] General, non-semantic emphasis. +[cmd_def file] Its argument is a filename / path. +[cmd_def fun] Its argument is a function name. +[cmd_def method] Its argument is a method name +[cmd_def namespace] Its argument is namespace name. +[cmd_def opt] Its argument is some optional syntax element. +[cmd_def option] Its argument is a command line switch / widget option. +[cmd_def package] Its argument is a package name. +[cmd_def sectref] Its argument is the title of a section or subsection, + i.e. a section reference. +[cmd_def syscmd] Its argument is a command name (external, system command). +[cmd_def term] Its argument is a concept, or general terminology. +[cmd_def type] Its argument is a type name. +[cmd_def uri] Its argument is a uniform resource identifier, i.e an + external reference. A second argument can be used + to specify an explicit label for the reference in + question. +[cmd_def usage] The arguments describe the syntax of a Tcl command. +[cmd_def var] Its argument is a variable. +[cmd_def widget] Its argument is a widget name. +[list_end] + +The example demonstrating the use of text markup is an excerpt from +the [term {doctools language command reference}], with some +highlighting added. + +It shows their use within a block of text, as the arguments of a list +item command ([cmd call]), and our ability to nest them. + +[example_begin] + ... + [lb]call [lb][cmd {cmd arg_def}][rb] [lb][cmd {arg type}][rb] [lb][cmd {arg name}][rb]] [lb][cmd opt] [lb][cmd {arg mode}][rb][rb][rb] + + Text structure. List element. Argument list. Automatically closes the + previous list element. Specifies the data-[lb][cmd {arg type}][rb] of the described + argument of a command, its [lb][cmd {arg name}][rb] and its i/o-[lb][cmd {arg mode}][rb]. The + latter is optional. + ... +[example_end] + +[subsection Escapes] + +Beyond the 20 commands for simple markup shown in the previous section +we have two more available which are technically simple markup. + +However their function is not the marking up of phrases as specific +types of things, but the insertion of characters, namely [const [lb]] +and [const [rb]]. + +These commands, [cmd lb] and [cmd rb] respectively, are required +because our use of [lb] and [rb] to bracket markup commands makes it +impossible to directly use [lb] and [rb] within the text. + +[para] + +Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added. + +[example_begin] + ... + These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required + because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it + impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. + ... +[example_end] + +[subsection Cross-references] + +The last two commands we have to discuss are for the declaration of +cross-references between documents, explicit and implicit. They are +[cmd keywords] and [cmd see_also]. Both take an arbitrary number of +arguments, all of which have to be plain unmarked text. I.e. it is not +allowed to use markup on them. Both commands can be used multiple +times in a document. If that is done all arguments of all occurrences +of one of them are put together into a single set. + +[list_begin definitions] +[def [cmd keywords]] + +The arguments of this command are interpreted as keywords describing +the document. A processor can use this information to create an index +indirectly linking the containing document to all documents with the +same keywords. + +[def [cmd see_also]] + +The arguments of this command are interpreted as references to other +documents. A processor can format them as direct links to these +documents. + +[list_end] + +[para] + +All the cross-reference commands can occur anywhere in the document +between [cmd manpage_begin] and [cmd manpage_end]. As such the writer +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +can choose whether she wants to have them at the beginning of the +body, or at its end, maybe near the place a keyword is actually +defined by the main content, or considers them as meta data which +should be in the header, etc. + +[para] + +Our example shows the sources for the cross-references of this +document, with some highlighting added. Incidentally they are found +at the end of the body. + +[example_begin] + ... + [lb][cmd {see_also doctools_intro}][rb] + [lb][cmd {see_also doctools_lang_syntax}][rb] + [lb][cmd {see_also doctools_lang_cmdref}][rb] + [lb][cmd {keywords markup {semantic markup}}][rb] + [lb][cmd {keywords {doctools markup} {doctools language}}][rb] + [lb][cmd {keywords {doctools syntax} {doctools commands}}][rb] + [lb]manpage_end[rb] +[example_end] + +[subsection Examples] + +Where ever we can write plain text we can write examples too. For +simple examples we have the command [cmd example] which takes a single +argument, the text of the argument. The example text must not contain +markup. If we wish to have markup within an example we have to use the +2-command combination [cmd example_begin] / [cmd example_end] instead. + +[para] + +The first opens an example block, the other closes it, and in between +we can write plain text and use all the regular text markup commands. +Note that text structure commands are not allowed. This also means +that it is not possible to embed examples and lists within an example. +On the other hand, we [emph can] use templating commands within +example blocks to read their contents from a file (Remember section +[sectref {Advanced structure}]). + +[para] + +The source for the very first example in this document (see section +[sectref Fundamentals]), with some highlighting added, is + +[example_begin] + [lb][cmd example] { + ... [lb]list_begin enumerated[rb] ... + }[rb] +[example_end] + +Using [cmd example_begin] / [cmd example_end] this would look like + +[example_begin] + [lb][cmd example_begin][rb] + ... [lb]list_begin enumerated[rb] ... + [lb][cmd example_end][rb] +[example_end] + +[subsection Lists] + +Where ever we can write plain text we can write lists too. The main +commands are [cmd list_begin] to start a list, and [cmd list_end] to +close one. The opening command takes an argument specifying the type +of list started it, and this in turn determines which of the eight +existing list item commands are allowed within the list to start list +items. + +[para] + +After the opening command only whitespace is allowed, until the first +list item command opens the first item of the list. Each item is a +regular series of paragraphs and is closed by either the next list +item command, or the end of the list. If closed by a list item command +this command automatically opens the next list item. A consequence of +a list item being a series of paragraphs is that all regular text +markup can be used within a list item, including examples and other +lists. + +[para] + +The list types recognized by [cmd list_begin] and their associated +list item commands are: + +[list_begin definitions] +[def [const arguments]] + +([cmd arg_def]) This opens an [term {argument (declaration) list}]. It +is a specialized form of a term definition list where the term is an +argument name, with its type and i/o-mode. + +[def [const commands]] + +([cmd cmd_def]) This opens a [term {command (declaration) list}]. It +is a specialized form of a term definition list where the term is a +command name. + +[def [const definitions]] + +([cmd def] and [cmd call]) This opens a general +[term {term definition list}]. The terms defined by the list items are +specified through the argument(s) of the list item commands, either +general terms, possibly with markup ([cmd def]), or Tcl commands with +their syntax ([cmd call]). + +[def [const enumerated]] + +([cmd enum]) This opens a general [term {enumerated list}]. + +[def [const itemized]] + +([cmd item]) +This opens a general [term {itemized list}]. + +[def [const options]] + +([cmd opt_def]) This opens an [term {option (declaration) list}]. It +is a specialized form of a term definition list where the term is an +option name, possibly with the option's arguments. + +[def [const tkoptions]] + +([cmd tkoption_def]) This opens a +[term {widget option (declaration) list}]. It is a specialized form of +a term definition list where the term is the name of a configuration +option for a widget, with its name and class in the option database. + +[list_end] + +Our example is the source of the definition list in the previous +paragraph, with most of the content in the middle removed. + +[example_begin] + ... + [lb][cmd list_begin] definitions[rb] + [lb][cmd def] [lb]const arg[rb][rb] + + ([lb]cmd arg_def[rb]) This opens an argument (declaration) list. It is a + specialized form of a definition list where the term is an argument + name, with its type and i/o-mode. + + [lb][cmd def] [lb]const itemized[rb][rb] + + ([lb]cmd item[rb]) + This opens a general itemized list. + + ... + [lb][cmd def] [lb]const tkoption[rb][rb] + + ([lb]cmd tkoption_def[rb]) This opens a widget option (declaration) list. It + is a specialized form of a definition list where the term is the name + of a configuration option for a widget, with its name and class in the + option database. + + [lb][cmd list_end][rb] + ... +[example_end] + +Note that a list cannot begin in one (sub)section and end in +another. Differently said, (sub)section breaks are not allowed within +lists and list items. An example of this [emph illegal] construct is + +[example_begin] + ... + [lb]list_begin itemized[rb] + [lb]item[rb] + ... + [lb][cmd {section {ILLEGAL WITHIN THE LIST}}][rb] + ... + [lb]list_end[rb] + ... +[example_end] + +[section {FURTHER READING}] + +Now that this document has been digested the reader, assumed to be a +[term writer] of documentation should be fortified enough to be able +to understand the formal [term {doctools language syntax}] +specification as well. From here on out the +[term {doctools language command reference}] will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax. + +[para] + +To be able to validate a document while writing it, it is also +recommended to familiarize oneself with one of the applications for +the processing and conversion of doctools documents, i.e. either +Tcllib's easy and simple [syscmd dtplite], or Tclapps' +ultra-configurable [syscmd dtp]. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools_lang_syntax.man b/tcllib/modules/doctools/doctools_lang_syntax.man new file mode 100644 index 0000000..7f69405 --- /dev/null +++ b/tcllib/modules/doctools/doctools_lang_syntax.man @@ -0,0 +1,142 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools_lang_syntax n 1.0] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools language syntax}] +[category {Documentation tools}] +[description] +[para] + +This document contains the formal specification of the syntax of the +doctools markup language, version 1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +[term {doctools language command reference}]. + +A beginner should read the much more informally written +[term {doctools language introduction}] first before trying to +understand either this document or the command reference. + +[section Fundamentals] + +In the broadest terms possible the [term {doctools markup language}] +is LaTeX-like, instead of like SGML and similar languages. A document +written in this language consists primarily of text, with markup +commands embedded into it. + +[para] + +Each markup command is a just Tcl command surrounded by a matching +pair of [const [lb]] and [const [rb]]. Which commands are available, +and their arguments, i.e. syntax is specified in the +[term {doctools language command reference}]. + +[para] + +In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other. + +[section {Lexical definitions}] + +In the syntax rules listed in the next section + +[list_begin enumerated] +[enum] +<TEXT> stands for all text except markup commands. + +[enum] +Any XXX stands for the markup command [lb]xxx[rb] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [const [lb]] and [const [rb]]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc. + +[enum] +<WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the [cmd comment] markup command. +[list_end] + +[section Syntax] + +The rules listed here specify only the syntax of doctools +documents. The lexical level of the language was covered in the +previous section. + +[para] + +Regarding the syntax of the (E)BNF itself + +[list_begin enumerated] +[enum] +The construct { X } stands for zero or more occurrences of X. +[enum] +The construct [lb] X [rb] stands for zero or one occurrence of X. +[enum] +The construct LIST_BEGIN<X> stands for the markup command +[cmd list_begin] with [const X] as its type argument. +[list_end] + +The syntax: + +[example { +manpage = defs + MANPAGE_BEGIN + header + DESCRIPTION + body + MANPAGE_END + { <WHITE> } + +defs = { INCLUDE | VSET | <WHITE> } + +header = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref } + +xref = KEYWORDS | SEE_ALSO | CATEGORY + +body = paras { SECTION sbody } +sbody = paras { SUBSECTION ssbody } +ssbody = paras + +paras = tblock { (PARA | NL) tblock } + +tblock = { <TEXT> | defs | markup | xref | an_example | a_list } + +markup = ARG | CLASS | CMD | CONST | EMPH | FILE + | FUN | LB | METHOD | NAMESPACE | OPT | OPTION + | PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM + | TYPE | URI | USAGE | VAR | WIDGET + +example = EXAMPLE + | EXAMPLE_BEGIN extext EXAMPLE_END + +extext = { <TEXT> | defs | markup } + +a_list = LIST_BEGIN<arguments> argd_list LIST_END + | LIST_BEGIN<commands> cmdd_list LIST_END + | LIST_BEGIN<definitions> def_list LIST_END + | LIST_BEGIN<enumerated> enum_list LIST_END + | LIST_BEGIN<itemized> item_list LIST_END + | LIST_BEGIN<options> optd_list LIST_END + | LIST_BEGIN<tkoptions> tkoptd_list LIST_END + +argd_list = [ <WHITE> ] { ARG_DEF paras } +cmdd_list = [ <WHITE> ] { CMD_DEF paras } +def_list = [ <WHITE> ] { (DEF|CALL) paras } +enum_list = [ <WHITE> ] { ENUM paras } +item_list = [ <WHITE> ] { ITEM paras } +optd_list = [ <WHITE> ] { OPT_DEF paras } +tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras } +}] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/doctools_plugin_apiref.man b/tcllib/modules/doctools/doctools_plugin_apiref.man new file mode 100644 index 0000000..c177bcd --- /dev/null +++ b/tcllib/modules/doctools/doctools_plugin_apiref.man @@ -0,0 +1,478 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin doctools_plugin_apiref n 1.1] +[see_also doctools] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_intro] +[see_also doctools_lang_syntax] +[keywords document] +[keywords formatter] +[keywords {formatting engine}] +[keywords manpage] +[keywords markup] +[keywords {semantic markup}] +[copyright {2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation tools}] +[titledesc {doctools plugin API reference}] +[category {Documentation tools}] +[description] +[para] + +This document is intended for [term {plugin writers}], i.e. developers +wishing to write a doctools [term {formatting engine}] for some output +format X. + +[para] + +It specifies the interaction between the [package doctools] package +and its plugins, i.e. the interface any doctools formatting engine has +to comply with. + +[para] + +This document deals with version 1 of the interface. + +[para] + +A reader who is on the other hand more interested in the markup +language itself should start with the + +[term {doctools language introduction}] and proceed from there to the +formal specifications, i.e. the [term {doctools language syntax}] and +the [term {doctools language command reference}]. + +[section OVERVIEW] + +The API for a doctools formatting engine consists of two major +sections. + +[para] + +On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +[sectref {FRONTEND COMMANDS}] for their detailed specification. + +[para] + +And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. + +Please see section [sectref {PLUGIN COMMANDS}] and its subsections for +their detailed specification. + +[section {FRONTEND COMMANDS}] + +This section specifies the set of commands through which a plugin, +also known as a doctools formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter. + +[para] + +I.e. a doctools formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section [sectref {PLUGIN COMMANDS}]) are executed. + +[para] + +Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. + +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop. + +[para] + +Coming back to the imported commands, all the commands with prefix +[emph dt_] provide limited access to specific parts of the frontend, +whereas the commands with prefix [emph ex_] provide access to the +state of the [package textutil::expander] object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances. + +[para] + +[list_begin definitions] + +[call [cmd dt_copyright]] + +Query command. It returns a string containing the copyright +information the doctools processor was configured with. The relevant +option is [option -copyright]). + +[call [cmd dt_file]] + +Query command. It returns the full path of the file containing the +input currently processed by the engine. This may be an included file. + +[call [cmd dt_mainfile]] + +Query command. It returns the full path of the toplevel file containing +the input currently processed by the engine. + +[call [cmd dt_fileid]] + +Query command. It returns the name of the file containing the input +currently processed by the engine, without path, nor extension. + +[call [cmd dt_fmap] [arg symfname]] + +Query command. It returns the actual pathname to use in the output in +place of the symbolic filename [arg symfname]. It will return the +unchanged input if no mapping was established for [arg symfname]. + +[para] + +The required mappings are established with the method [method map] of +a frontend, as explained in section [sectref-external {OBJECT METHODS}] +of the documentation for the package [package doctools]. + +[call [cmd dt_format]] + +Query command. It returns the name of the format associated with the +doctools formatting engine. + +[call [cmd dt_imgdata] [arg key] [arg extensions]] + +Query command. Access to the image map. Looks for an image recorded +under the [arg key] and having on the specified [arg extension]. If a +matching image is found its data is returned as the result of the +command. Otherwise an empty string is returned. + +[call [cmd dt_imgdst] [arg key] [arg extensions]] + +Query command. Access to the image map. Looks for an image recorded +under the [arg key] and having on the specified [arg extension]. If a +matching image is found its destination path in the output is returned +as the result of the command. Otherwise an empty string is returned. + +[call [cmd dt_imgsrc] [arg key] [arg extensions]] + +Query command. Access to the image map. Looks for an image recorded +under the [arg key] and having on the specified [arg extension]. If a +matching image is found its origin path is returned as the result of +the command. Otherwise an empty string is returned. + +[call [cmd dt_lnesting]] + +Query command. It returns the number of lists currently open. + +[call [cmd dt_module]] + +Query command. It returns the name of the module the input currently +processed belongs to. + +[call [cmd dt_read] [arg file]] + +Controlled filesystem access. Returns contents of [arg file] for +whatever use desired by the plugin. + +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error. + +[call [cmd dt_source] [arg file]] + +Controlled filesystem access. This command allows the doctools +formatting engine to load additional Tcl code it may need. + +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error. + +[call [cmd dt_user]] + +Query command. It returns the name of the current user as known to the +tcl interpreter the frontend controlling the formatting engine resides +in. + +[call [cmd ex_cappend] [arg text]] +Appends a string to the output in the current context. This command +should rarely be used by macros or application code. + +[call [cmd ex_cget] [arg varname]] +Retrieves the value of variable [arg varname], defined in the current +context. + +[call [cmd ex_cis] [arg cname]] +Determines whether or not the name of the current context is +[arg cname]. + +[call [cmd ex_cname]] +Returns the name of the current context. + +[call [cmd ex_cpop] [arg cname]] +Pops a context from the context stack, returning all accumulated +output in that context. The context must be named [arg cname], or an +error results. + +[call [cmd ex_cpush] [arg cname]] +Pushes a context named [arg cname] onto the context stack. The +context must be popped by [method cpop] before expansion ends or an +error results. + +[call [cmd ex_cset] [arg varname] [arg value]] +Sets variable [arg varname] to [arg value] in the current context. + +[call [cmd ex_lb] [opt [arg newbracket]]] +Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If [arg newbracket] is specified, it becomes the new +bracket, and is returned. + +[call [cmd ex_rb] [opt [arg newbracket]]] +Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If [arg newbracket] is specified, it becomes the +new bracket, and is returned. + +[list_end] + +[section {PLUGIN COMMANDS}] + +The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections. + +[subsection {Management commands}] + +The management commands a plugin has to provide are used by the +frontend to + +[list_begin enumerated] +[enum] initialize and shutdown the plugin +[enum] determine the number of passes it has + to make over the input +[enum] initialize and shutdown each pass +[enum] query and initialize engine parameters +[list_end] +[para] + +After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence: + +[example { + fmt_numpasses -> n + fmt_listvariables -> vars + + fmt_varset var1 value1 + fmt_varset var2 value2 + ... + fmt_varset varK valueK + fmt_initialize + fmt_setup 1 + ... + fmt_setup 2 + ... + ... + fmt_setup n + ... + fmt_postprocess + fmt_shutdown + ... +}] + +I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional. + +[para] + +After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at [cmd fmt_varset]. + +[para] + +In each of the passes, i.e. after the calls of [cmd fmt_setup] the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the doctools markup language, +as specified in the [term {doctools language syntax}] specification. + +[para] + +A different way of looking at the sequence is: + +[list_begin itemized] +[item] First some basic parameters are determined. + +[item] Then everything starting at the first [cmd fmt_varset] to +[cmd fmt_shutdown] forms a [term run], the formatting of a +single input. Each run can be followed by more. + +[item] Embedded within each run we have one or more [term passes], +each starting with [cmd fmt_setup] and going until either the next +[cmd fmt_setup] or [cmd fmt_postprocess] is reached. + +[para] + +If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored. + +[list_end] +[para] + +The commands, their names, signatures, and responsibilities are, in +detail: + +[list_begin definitions] + +[call [cmd fmt_initialize]] +[emph Initialization/Shutdown]. + +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. + +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored. + +[call [cmd fmt_listvariables]] +[emph Initialization/Shutdown] and [emph {Engine parameters}]. + +Second command is called after the plugin code has been loaded, +i.e. immediately after [cmd fmt_numpasses]. + +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty. + +[call [cmd fmt_numpasses]] +[emph Initialization/Shutdown] and [emph {Pass management}]. + +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. + +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one. + +[call [cmd fmt_postprocess] [arg text]] +[emph Initialization/Shutdown]. + +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument. + +[para] + +Expected to return a value, the final result of formatting the input. + +[call [cmd fmt_setup] [arg n]] +[emph Initialization/Shutdown] and [emph {Pass management}]. + +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from [const 1] upward. + +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored. + +[call [cmd fmt_shutdown]] +[emph Initialization/Shutdown]. + +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. + +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. + +No return value is expected, and any returned value is ignored. + +[call [cmd fmt_varset] [arg varname] [arg text]] +[emph {Engine parameters}]. + +This command is called by the frontend to set an engine parameter to a +particular value. + +The parameter to change is specified by [arg varname], the value to +set in [arg text]. + +[para] + +The command has to throw an error if an unknown [arg varname] is +used. Only the names returned by [cmd fmt_listvariables] have to be +considered as known. + +[para] + +The values of all engine parameters have to persist between passes and +runs. + +[list_end] + +[subsection {Formatting commands}] + +The formatting commands have to implement the formatting for the +output format, for all the markup commands of the doctools markup +language, except [cmd lb], [cmd rb], [cmd vset], [cmd include], and +[cmd comment]. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all. + +[para] + +This means, that each of the 49 markup commands specified in the +[term {doctools language command reference}] and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix [emph fmt_] added to it. + +[para] + +All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output. + +[para] + +To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +[term {doctools language command reference}] for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command. + +[para] + +The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the doctools +markup language, as specified in the [term {doctools language syntax}] +specification. + +[para] + +[list_begin definitions] + +[call [cmd fmt_plain_text] [arg text]] +[emph {No associated markup command}]. + +[para] Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text. + +[para] The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change. + +[list_end] + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/include/examples.inc b/tcllib/modules/doctools/include/examples.inc new file mode 100644 index 0000000..467e047 --- /dev/null +++ b/tcllib/modules/doctools/include/examples.inc @@ -0,0 +1,30 @@ + +[section EXAMPLES] + +[subsection "Where do I find [vset theformat] examples?"] + +We have no direct examples of documents written using [vset theformat] +markup. However the doctools processor [syscmd dtplite] does generate +a table of contents when processing a set of documents written in +doctools markup. The intermediate file for it uses [vset theformat] +markup and is not deleted when generation completes. Such files can +therefore serve as examples. + +[para] + +[syscmd dtplite] is distributed as part of Tcllib, so to get it you +need one of + +[list_begin enumerated] + +[enum] +A snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at + +[uri {/wiki?name=Development+Snapshots} {Development Snapshots}] + +[enum] +A Tcllib release archive. They are available at the [uri /home home] +page. + +[list_end] diff --git a/tcllib/modules/doctools/include/placeholder.inc b/tcllib/modules/doctools/include/placeholder.inc new file mode 100644 index 0000000..1d8a244 --- /dev/null +++ b/tcllib/modules/doctools/include/placeholder.inc @@ -0,0 +1,12 @@ + +[subsection {What is this document?}] + +This document is currently mainly a placeholder, to be filled with +commonly asked questions about the [vset theformat] markup language +and companions, and their answers. + +[para] + +Please report any questions (and, if possible, answers) we should +consider for this document as explained in the section +[sectref {Bugs, Ideas, Feedback}] below. diff --git a/tcllib/modules/doctools/mpexpand b/tcllib/modules/doctools/mpexpand new file mode 100755 index 0000000..faaa80e --- /dev/null +++ b/tcllib/modules/doctools/mpexpand @@ -0,0 +1,153 @@ +#! /bin/sh +# -*- tcl -*- \ +exec tclsh "$0" ${1+"$@"} + +lappend auto_path [file dirname [file dirname [info script]]] +package require doctools + +# --------------------------------------------------------------------- +# 1. Handle command line options, input and output +# 2. Initialize a doctools object. +# 3. Run the input through the object. +# 4. Write output. +# --------------------------------------------------------------------- + +proc usage {{exitstate 1}} { + global argv0 + puts "Usage: $argv0\ + ?-h|--help|-help|-??\ + ?-help-fmt|--help-fmt?\ + ?-module module?\ + ?-deprecated?\ + ?-copyright text?\ + format in|- ?out|-?" + exit $exitstate +} + +# --------------------------------------------------------------------- + +proc fmthelp {} { + # Tcllib FR #527029: short reference of formatting commands. + + global argv0 + puts "$argv0 [doctools::help]" + exit 0 +} + +# --------------------------------------------------------------------- +# 1. Handle command line options, input and output + +proc cmdline {} { + global argv0 argv format in out extmodule deprecated copyright + + set copyright "" + set extmodule "" + set deprecated 0 + + while {[string match -* [set opt [lindex $argv 0]]]} { + switch -exact -- $opt { + -module { + set extmodule [lindex $argv 1] + set argv [lrange $argv 2 end] + continue + } + -copyright { + set copyright [lindex $argv 1] + set argv [lrange $argv 2 end] + continue + } + -deprecated { + set deprecated 1 + set argv [lrange $argv 1 end] + } + -help - -h - --help - -? { + # Tcllib FR #527029 + usage 0 + } + -help-fmt - --help-fmt { + # Tcllib FR #527029 + fmthelp + } + default { + # Unknown option + usage + } + } + } + + if {[llength $argv] < 3} { + usage + } + foreach {format in out} $argv break + + if {$format == {} || $in == {}} { + usage + } + if {$out == {}} {set out -} + return $format +} + +# --------------------------------------------------------------------- +# 3. Read input. Also providing the namespace with file information. + +proc get_input {} { + global in + if {[string equal $in -]} { + return [read stdin] + } else { + set if [open $in r] + set text [read $if] + close $if + return $text + } +} + +# --------------------------------------------------------------------- +# 4. Write output. + +proc write_out {text} { + global out + if {[string equal $out -]} { + puts -nonewline stdout $text + } else { + set of [open $out w] + puts -nonewline $of $text + close $of + } +} + + +# --------------------------------------------------------------------- +# Get it all together + +proc main {} { + global format deprecated extmodule in copyright + + #if {[catch {} + cmdline + + ::doctools::new dt -format $format -deprecated $deprecated -file $in + if {$extmodule != {}} { + dt configure -module $extmodule + } + if {$copyright != {}} { + dt configure -copyright $copyright + } + + write_out [dt format [get_input]] + + set warnings [dt warnings] + if {[llength $warnings] > 0} { + puts stderr [join $warnings \n] + } + + #{} msg]} {} + #puts stderr "Execution error: $msg" + #{} + return +} + + +# --------------------------------------------------------------------- +main +exit diff --git a/tcllib/modules/doctools/mpexpand.all b/tcllib/modules/doctools/mpexpand.all new file mode 100755 index 0000000..3b1878c --- /dev/null +++ b/tcllib/modules/doctools/mpexpand.all @@ -0,0 +1,38 @@ +#! /bin/sh +# -*- tcl -*- \ +exec tclsh "$0" ${1+"$@"} + +set here [file dirname [file join [pwd] [info script]]] +set verbose 0 + +set o [lindex $argv 0] +if {[string equal $o "-verbose"]} { + set verbose 1 + set argv [lrange $argv 1 end] +} elseif {[string equal $o ""] && [llength $argv] > 1} { + puts stderr "Usage: $argv0 ?-verbose? ?module?" + exit 1 +} + +set module [lindex $argv 0] +array set fmts { + nroff n + html html + tmml tmml + latex tex +} + +foreach fname [glob -nocomplain *.man] { + foreach fmt [array names fmts] { + set out [file rootname $fname].$fmts($fmt) + if {1 || $verbose} { + puts " $fname -> $out" + } + if {$module != {}} { + exec [file join $here mpexpand] -module $module $fmt $fname $out + } else { + exec [file join $here mpexpand] $fmt $fname $out + } + } +} +exit diff --git a/tcllib/modules/doctools/mpexpand.man b/tcllib/modules/doctools/mpexpand.man new file mode 100644 index 0000000..954d3ae --- /dev/null +++ b/tcllib/modules/doctools/mpexpand.man @@ -0,0 +1,107 @@ +[comment {-*- tcl -*- doctools manpage}] +[manpage_begin mpexpand n 1.0] +[see_also expander(n)] +[see_also format(n)] +[see_also formatter(n)] +[keywords conversion] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] +[copyright {2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[copyright {2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] +[moddesc {Documentation toolbox}] +[titledesc {Markup processor}] +[category {Documentation tools}] +[description] +[para] + +This manpage describes a processor / converter for manpages in the +doctools format as specified in [cmd doctools_fmt]. The processor +is based upon the package [package doctools]. + +[list_begin definitions] +[call [cmd mpexpand] [opt "-module [arg module]"] [arg format] [arg infile]|- [arg outfile]|-] + +The processor takes three arguments, namely the code describing which +formatting to generate as the output, the file to read the markup +from, and the file to write the generated output into. If the +[arg infile] is "[const -]" the processor will read from +[const stdin]. If [arg outfile] is "[const -]" the processor will +write to [const stdout]. + +[para] + +If the option [arg -module] is present its value overrides the internal +definition of the module name. + +[para] + +The currently known output formats are + +[list_begin definitions] + +[def [const nroff]] + +The processor generates *roff output, the standard format for unix +manpages. + +[def [const html]] + +The processor generates HTML output, for usage in and display by web +browsers. + +[def [const tmml]] + +The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML. + +[def [const latex]] + +The processor generates LaTeX output. + +[def [const wiki]] + +The processor generates Wiki markup as understood by [syscmd wikit]. + +[def [const list]] + +The processor extracts the information provided by [cmd manpage_begin]. +[see_also expander(n)] +[see_also format(n)] +[see_also formatter(n)] +[keywords conversion] +[keywords HTML] +[keywords manpage] +[keywords markup] +[keywords nroff] +[keywords TMML] + +[def [const null]] + +The processor does not generate any output. + +[list_end] + +[call [cmd mpexpand.all] [opt [arg -verbose]] [opt [arg module]]] + +This command uses [syscmd mpexpand] to generate all possible output +formats for all manpages in the current directory. The manpages are +recognized through the extension [file .man]. If [arg -verbose] is +specified the command will list its actions before executing them. + +[para] + +The [arg module] information is passed to [cmd mpexpand]. + +[list_end] + +[section NOTES] +[para] + +Possible future formats are plain text, pdf and postscript. + +[vset CATEGORY doctools] +[include ../doctools2base/include/feedback.inc] +[manpage_end] diff --git a/tcllib/modules/doctools/mpformats/_common.tcl b/tcllib/modules/doctools/mpformats/_common.tcl new file mode 100644 index 0000000..9f2288a --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_common.tcl @@ -0,0 +1,303 @@ +# -*- tcl -*- +# +# _common.tcl +# +# (c) 2001 Andreas Kupries <andreas_kupries@sourceforge.net> +# (c) 2002 Andreas Kupries <andreas_kupries@sourceforge.net> + +################################################################ +# The code here contains general definitions for API functions and +# state information. They are used by several formatters to simplify +# their own code. + +global state +array set state {} + +proc fmt_initialize {} { + global state + unset state + + set state(pass) unknown ; # Not relevant before a pass + set state(begun) unknown ; # is active + set state(mdesc) {} ; # Text, module desciption + #set state(tdesc) {} ; # Text, title of manpage + set state(copyright) {} ; # Text, copyright assignment (list) + return +} + +proc fmt_shutdown {} {return} +proc fmt_numpasses {} {return 2} +proc fmt_postprocess {text} {return $text} +proc fmt_plain_text {text} {return $text} +proc fmt_listvariables {} {return {}} +proc fmt_varset {varname text} {return} + +proc fmt_setup {n} { + # Called to setup a pass through the input. + + global state + set state(pass) $n ; # We are in pass 'n' through the text. + set state(begun) 0 ; # No manpage_begin yet + + if {$n == 1} {c_xref_init} + + SetPassProcs $n + return +} + +################################################################ +# Functions made available to the formatter to access the common +# state managed here. + +proc c_inpass {} {global state ; return $state(pass)} + +proc c_begin {} {global state ; set state(begun) 1 ; return} +proc c_begun {} {global state ; return $state(begun)} + +proc c_get_module {} {global state ; return $state(mdesc)} +proc c_set_module {text} {global state ; set state(mdesc) $text ; return} + +proc c_set_title {text} {global state ; set state(tdesc) $text ; return} +proc c_get_title {} { + global state + if {![info exists state(tdesc)]} { + return $state(mdesc) + } + return $state(tdesc) +} + +proc c_copyrightsymbol {} {return "(c)"} +proc c_set_copyright {text} {global state ; lappend state(copyright) $text ; return} +proc c_get_copyright {} { + global state + + set cc $state(copyright) + if {$cc == {}} {set cc [dt_copyright]} + if {$cc == {}} {return {}} + + set stmts {} + set re {^Copyright +(?:\(c\)|\\\(co|©)? *(.+)$} + foreach stmt $cc { + if { [string equal -nocase "public domain" [string trim $stmt]] } { + lappend stmts "Public domain" + } elseif { [regexp -nocase -- $re $stmt -> stmt] } { + lappend stmts $stmt + } else { + lappend stmts "Copyright [c_copyrightsymbol] $stmt" + } + } + + return [join $stmts \n] +} + +proc c_provenance {} { + return "Generated from file '[file tail [dt_ibase]]' by tcllib/doctools with format '[dt_format]'" +} + +################################################################ +# Manage pass-dependent procedure definitions. + +global PassProcs + +# pass $passNo procName procArgs { body } -- +# Specifies procedure definition for pass $n. +# +proc c_pass {pass proc arguments body} { + global PassProcs + lappend PassProcs($pass) $proc $arguments $body +} +proc SetPassProcs {pass} { + global PassProcs + foreach {proc args body} $PassProcs($pass) { + proc $proc $args $body + } +} + + +################################################################ +# Manage a set of buffers to hold information between passes. +# Each buffer holds a list of lines. + +global Buffers + +# holdBuffers buffer ? buffer ...? -- +# Declare a list of hold buffers, +# to collect data in one pass and output it later. +# +proc c_holdBuffers {args} { + global Buffers + foreach arg $args { + set Buffers($arg) [list] + } +} + +proc c_holdRemove {args} { + global Buffers + foreach arg $args { + catch {unset Buffers($arg)} + } + return +} + +# hold buffer text -- +# Append text to named buffer +# +proc c_hold {buffer entry} { + global Buffers + lappend Buffers($buffer) $entry + + #puts "$buffer -- $entry" + return +} + +proc c_holding {buffer} { + global Buffers + set l 0 + catch {set l [llength $Buffers($buffer)]} + return $l +} + +# held buffer -- +# Returns current contents of named buffer and empty the buffer. +# +proc c_held {buffer} { + global Buffers + set content [join $Buffers($buffer) "\n"] + set Buffers($buffer) [list] + return $content +} + +###################################################################### +# Nested counter + +global counters cnt +set counters [list] +set cnt 0 + +proc c_cnext {} {global cnt ; incr cnt} +proc c_cinit {} { + global counters cnt + set counters [linsert $counters 0 $cnt] + set cnt 0 + return +} +proc c_creset {} { + global counters cnt + set cnt [lindex $counters 0] + set counters [lrange $counters 1 end] + return +} + + +###################################################################### +# Utilities. +# + +proc NOP {args} { } ;# do nothing +proc NYI {{message {}}} { + return -code error [append message " Not Yet Implemented"] +} + +###################################################################### +# Cross-reference tracking (for a single file). +# +global SectionNames ;# array mapping 'section name' to 'reference id' +global SectionList ;# List of sections, their ids, and levels, in +set SectionList {} ;# order of definition. + +# sectionId -- +# Format section name as an XML ID. +# +proc c_sectionId {name} { + # Identical to '__sid' in checker.tcl + regsub -all {[ ]+} [string tolower [string trim $name]] _ id + regsub -all {"} $id _ id ; # " + return $id +} + +# possibleReference text gi -- +# Check if $text is a potential cross-reference; +# if so, format as a reference; +# otherwise format as a $gi element. +# +proc c_possibleReference {text gi {label {}}} { + global SectionNames + if {![string length $label]} {set label $text} + set id [c_sectionId $text] + if {[info exists SectionNames($id)]} { + return "[startTag ref refid $id]$label[endTag ref]" + } else { + return [wrap $label $gi] + } +} + +proc c_newSection {name level location {id {}}} { + global SectionList SectionNames + if {$id == {}} { + set id [c_sectionId $name] + } + set SectionNames($id) . + set SectionList [linsert $SectionList $location $name $id $level] + return +} + +proc c_clrSections {} { + global SectionList SectionNames + set SectionList {} + catch {unset SectionNames} +} + +###################################################################### +# Conversion specification. +# +# Two-pass processing. The first pass collects text for the +# SYNOPSIS, SEE ALSO, and KEYWORDS sections, and the second pass +# produces output. +# + +c_holdBuffers synopsis see_also keywords precomments category + +################################################################ +# Management of see-also and keyword cross-references + +proc c_xref_init {} { + global seealso seealso__ ; set seealso [list] ; catch {unset seealso__} ; array set seealso__ {} + global keywords keywords__ ; set keywords [list] ; catch {unset keywords__} ; array set keywords__ {} + global category ; set category "" +} + +proc c_xref_seealso {} {global seealso ; return $seealso} +proc c_xref_keywords {} {global keywords ; return $keywords} +proc c_xref_category {} {global category ; return $category} + +c_pass 1 fmt_category {text} { + global category + set category $text + return +} + +c_pass 1 fmt_see_also {args} { + global seealso seealso__ + foreach ref $args { + if {[info exists seealso__($ref)]} continue + lappend seealso $ref + set seealso__($ref) . + } + return +} + +c_pass 1 fmt_keywords {args} { + global keywords keywords__ + foreach ref $args { + if {[info exists keywords__($ref)]} continue + lappend keywords $ref + set keywords__($ref) . + } + return +} + +c_pass 2 fmt_category {args} NOP +c_pass 2 fmt_see_also {args} NOP +c_pass 2 fmt_keywords {args} NOP + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/_html.tcl b/tcllib/modules/doctools/mpformats/_html.tcl new file mode 100644 index 0000000..ae3ec98 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_html.tcl @@ -0,0 +1,198 @@ +# -*- tcl -*- +# Copyright (c) 2001-2008 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# Helper rules for the creation of the memchan website from the .exp files. +# General formatting instructions ... + +# htmlEscape text -- +# Replaces HTML markup characters in $text with the +# appropriate entity references. +# + +global textMap; +set textMap { + & & < < > > + \xa0 \xb0 ° \xc0 À \xd0 Ð \xe0 à \xf0 ð + \xa1 ¡ \xb1 ± \xc1 Á \xd1 Ñ \xe1 á \xf1 ñ + \xa2 ¢ \xb2 ² \xc2 Â \xd2 Ò \xe2 â \xf2 ò + \xa3 £ \xb3 ³ \xc3 Ã \xd3 Ó \xe3 ã \xf3 ó + \xa4 ¤ \xb4 ´ \xc4 Ä \xd4 Ô \xe4 ä \xf4 ô + \xa5 ¥ \xb5 µ \xc5 Å \xd5 Õ \xe5 å \xf5 õ + \xa6 ¦ \xb6 ¶ \xc6 Æ \xd6 Ö \xe6 æ \xf6 ö + \xa7 § \xb7 · \xc7 Ç \xd7 × \xe7 ç \xf7 ÷ + \xa8 ¨ \xb8 ¸ \xc8 È \xd8 Ø \xe8 è \xf8 ø + \xa9 © \xb9 ¹ \xc9 É \xd9 Ù \xe9 é \xf9 ù + \xaa ª \xba º \xca Ê \xda Ú \xea ê \xfa ú + \xab « \xbb » \xcb Ë \xdb Û \xeb ë \xfb û + \xac ¬ \xbc ¼ \xcc Ì \xdc Ü \xec ì \xfc ü + \xad ­ \xbd ½ \xcd Í \xdd Ý \xed í \xfd ý + \xae ® \xbe ¾ \xce Î \xde Þ \xee î \xfe þ + \xaf &hibar; \xbf ¿ \xcf Ï \xdf ß \xef ï \xff ÿ + {"} " +} ; # " make the emacs highlighting code happy. + +# Handling of HTML delimiters in content: +# +# Plain text is initially passed through unescaped; +# internally-generated markup is protected by preceding it with \1. +# The final PostProcess step strips the escape character from +# real markup and replaces markup characters from content +# with entity references. +# + +global markupMap +set markupMap { {&} {\1&} {<} {\1<} {>} {\1>} {"} {\1"} } +global finalMap +set finalMap $textMap +lappend finalMap {\1&} {&} {\1<} {<} {\1>} {>} {\1"} {"} + + +proc htmlEscape {text} { + global textMap + return [string map $textMap $text] +} + +proc fmt_postprocess {text} { + global finalMap + + if 0 { + puts_stderr ____________________________________________________________ + puts_stderr $text + puts_stderr ____________________________________________________________ + } + + # Put protected characters into their final form. + set text [string map $finalMap $text] + # Remove leading/trailing whitespace from paragraphs. + regsub -all "<p>\[\t\n \]*" $text {<p>} text + regsub -all "\[\t\n \]*</p>" $text {</p>} text + # Remove trailing linebreaks from paragraphs. + while {[regsub -all "<br>\[\t\n \]*</p>" $text {</p>} text]} continue + # Remove empty paragraphs + regsub -all "<p>\[\t\n \]*</p>" $text {} text + # Separate paragraphs + regsub -all "</p><p>" $text "</p>\n<p>" text + # Separate bigger structures + foreach outer {div p dl ul ol} { + foreach inner {div p dl ul ol} { + regsub -all "</${outer}><${inner}" $text "</${outer}>\n<${inner}" text + regsub -all "</${outer}></${inner}" $text "</${outer}>\n</${inner}" text + } + } + regsub -all "<li><dl" $text "<li>\n<dl" text + regsub -all "<li><ol" $text "<li>\n<ol" text + regsub -all "<li><ul" $text "<li>\n<ul" text + regsub -all "</dl></li" $text "</dl>\n</li" text + regsub -all "</ol></li" $text "</ol>\n</li" text + regsub -all "</ul></li" $text "</ul>\n</li" text + # Remove empty lines. + regsub -all "\n\n\n*" $text \n text + + if 0 { + puts_stderr @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + puts_stderr $text + puts_stderr @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + } + + return $text +} + +# markup text -- +# Protect markup characters in $text with \1. +# These will be stripped out in PostProcess. +# +proc markup {text} { + global markupMap + return [string map $markupMap $text] +} + +proc use_bg {} { + set c [bgcolor] + #puts stderr "using $c" + if {$c == {}} {return ""} + return bgcolor=$c +} + + +proc nbsp {} {return [markup " "]} +proc p {} {return [markup <p>]} +proc ptop {} {return [markup "<p valign=top>"]} +proc td {} {return [markup "<td [use_bg]>"]} +proc trtop {} {return [markup "<tr valign=top [use_bg]>"]} +proc tr {} {return [markup "<tr [use_bg]>"]} +proc sect {s} {return [markup <b>]$s[markup </b><br><hr>]} +proc link {text url} {return [markup "<a href=\"$url\">"]$text[markup </a>]} +proc table {} {return [markup "<table [border] width=100% cellspacing=0 cellpadding=0>"]} +proc btable {} {return [markup "<table border=1 width=100% cellspacing=0 cellpadding=0>"]} +proc stable {} {return [markup "<table [border] cellspacing=0 cellpadding=0>"]} + +proc link {text url} {return [markup "<a href=\"$url\">"]$text[markup </a>]} + +proc tcl_cmd {cmd} {return "[markup <b>]\[$cmd][markup </b>]"} +proc wget {url} {exec /usr/bin/wget -q -O - $url 2>/dev/null} + +proc url {tag text url} { + set body { + switch -exact -- $what { + link {return {\1<a href="%url%"\1>%text%\1</a\1>}} ; ## TODO - markup + text {return {%text%}} + url {return {%url%}} + } + } + proc $tag {{what link}} [string map [list %text% $text %url% $url] $body] +} + +proc img {tag alt img} { + proc $tag {} [list return "\1<img alt=\"$alt\" src=\"$img\"\1>"] +} + +proc imagelink {alt img} { + return [markup "<img alt=\"$alt\" src=\"$img\">"] +} + +proc protect {text} {return [string map [list & "&" < "<" > ">"] $text]} + +proc strong {text} {tag_ strong $text} +proc em {text} {tag_ em $text} +proc bold {text class} {tag_ b $text class $class} +proc italic {text class} {tag_ i $text class $class} +proc span {text class} {tag_ span $text class $class} + +proc tag {t} {return [markup <$t>]} +proc taga {t av} { + # av = attribute value ... + set avt [list] + foreach {a v} $av {lappend avt "$a=\"$v\""} + return [markup "<$t [join $avt]>"] +} +proc tag/ {t} {return [markup </$t>]} +proc tag_ {t block args} { + # args = key value ... + if {$args == {}} {return "[tag $t]$block[tag/ $t]"} + return "[taga $t $args]$block[tag/ $t]" +} +proc tag* {t args} { + if {[llength $args]} { + taga $t $args + } else { + tag $t + } +} + +proc ht_comment {text} { + return "[markup <]! -- [join [split $text \n] " -- "]\n --[markup >]" +} + +# wrap content gi -- +# Returns $content wrapped inside <$gi> ... </$gi> tags. +# +proc wrap {content gi} { + return "[tag $gi]${content}[tag/ $gi]" +} +proc startTag {x args} {if {[llength $args]} {taga $x $args} else {tag $x}} +proc endTag {x} {tag/ $x} + + +proc anchor {name text} { + return [taga a [list name $name]]$text[tag/ a] +} diff --git a/tcllib/modules/doctools/mpformats/_idx_common.tcl b/tcllib/modules/doctools/mpformats/_idx_common.tcl new file mode 100644 index 0000000..ca0c4c0 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_idx_common.tcl @@ -0,0 +1,31 @@ +# -*- tcl -*- +# +# _idx_common.tcl +# +# (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +################################################################ +# The code here contains general definitions for API functions and +# state information. They are used by several formatters to simplify +# their own code. + +proc idx_initialize {} {return} +proc idx_shutdown {} {return} +proc idx_numpasses {} {return 1} +proc idx_postprocess {text} {return $text} +proc idx_setup {n} {return} +proc idx_listvariables {} {return {}} +proc idx_varset {varname text} {return} + + +proc fmt_plain_text {text} {return $text} + +################################################################ +# Functions made available to the formatter to access the common +# state managed here. + +proc c_provenance {} { + return "Generated by tcllib/doctools/idx with format '[dt_format]'" +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/_nroff.tcl b/tcllib/modules/doctools/mpformats/_nroff.tcl new file mode 100644 index 0000000..c630875 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_nroff.tcl @@ -0,0 +1,183 @@ +# -*- tcl -*- +# +# -- nroff commands +# +# Copyright (c) 2003-2005 Andreas Kupries <andreas_kupries@sourceforge.net> + + +################################################################ +# nroff specific commands +# +# All dot-commands (f.e. .PP) are returned with a leading \n\1, +# enforcing that they are on a new line and will be protected as markup. +# Any empty line created because of this is filtered out in the +# post-processing step. + + +proc nr_lp {} {return \n\1.LP} +proc nr_ta {{text {}}} {return "\1.ta$text"} +proc nr_bld {} {return \1\\fB} +proc nr_bldt {t} {return "\n\1.B $t\n"} +proc nr_ul {} {return \1\\fI} +proc nr_rst {} {return \1\\fR} +proc nr_p {} {return \n\1.PP\n} +proc nr_comment {text} {return "\1'\1\\\" [join [split $text \n] "\n\1'\1\\\" "]"} ; # " +proc nr_enum {num} {nr_item " \[$num\]"} +proc nr_item {{text {}}} {return "\n\1.IP$text"} +proc nr_vspace {} {return \n\1.sp\n} +proc nr_blt {text} {return "\n\1.TP\n$text"} +proc nr_bltn {n text} {return "\n\1.TP $n\n$text"} +proc nr_in {} {return \n\1.RS} +proc nr_out {} {return \n\1.RE} +proc nr_nofill {} {return \n\1.nf} +proc nr_fill {} {return \n\1.fi} +proc nr_title {text} {return "\n\1.TH $text"} +proc nr_include {file} {return "\n\1.so $file"} +proc nr_bolds {} {return \n\1.BS} +proc nr_bolde {} {return \n\1.BE} +proc nr_read {fn} {return [nroffMarkup [dt_read $fn]]} +proc nr_cs {} {return \n\1.CS\n} +proc nr_ce {} {return \n\1.CE\n} + +proc nr_section {name} { + if {![regexp {[ ]} $name]} { + return "\n\1.SH [string toupper $name]" + } + return "\n\1.SH \"[string toupper $name]\"" +} +proc nr_subsection {name} { + if {![regexp {[ ]} $name]} { + return "\n\1.SS [string toupper $name]" + } + return "\n\1.SS \"[string toupper $name]\"" +} + + +################################################################ + +# Handling of nroff special characters in content: +# +# Plain text is initially passed through unescaped; +# internally-generated markup is protected by preceding it with \1. +# The final PostProcess step strips the escape character from +# real markup and replaces unadorned special characters in content +# with proper escapes. +# + +global markupMap +set markupMap [list \ + "\\" "\1\\" \ + "'" "\1'" \ + "." "\1." \ + "\\\\" "\\"] +global finalMap +set finalMap [list \ + "\1\\" "\\" \ + "\1'" "'" \ + "\1." "." \ + "." "\\&." \ + "\\" "\\\\"] +global textMap +set textMap [list "\\" "\\\\"] + + +proc nroffEscape {text} { + global textMap + return [string map $textMap $text] +} + +# markup text -- +# Protect markup characters in $text. +# These will be stripped out in PostProcess. +# +proc nroffMarkup {text} { + global markupMap + return [string map $markupMap $text] +} + +proc nroff_postprocess {nroff} { + global finalMap + + # Postprocessing final nroff text. + # - Strip empty lines out of the text + # - Remove leading and trailing whitespace from lines. + # - Exceptions to the above: Keep empty lines and leading + # whitespace when in verbatim sections (no-fill-mode) + + set nfMode [list \1.nf \1.CS] ; # commands which start no-fill mode + set fiMode [list \1.fi \1.CE] ; # commands which terminate no-fill mode + set lines [list] ; # Result buffer + set verbatim 0 ; # Automaton mode/state + + foreach line [split $nroff "\n"] { + #puts_stderr |[expr {$verbatim ? "VERB" : " "}]|$line| + + if {!$verbatim} { + # Normal lines, not in no-fill mode. + + if {[lsearch -exact $nfMode [split $line]] >= 0} { + # no-fill mode starts after this line. + set verbatim 1 + } + + # Ensure that empty lines are not added. + # This also removes leading and trailing whitespace. + + if {![string length $line]} {continue} + set line [string trim $line] + if {![string length $line]} {continue} + + if {[regexp {^\x1\\f[BI]\.} $line]} { + # We found confusing formatting at the beginning of + # the current line. We lift this line up and attach it + # at the end of the last line to remove this + # irregularity. Note that the regexp has to look for + # the special 0x01 character as well to be sure that + # the sequence in question truly is formatting. + # [bug-3601370] Only lift & attach if last line is not + # a directive + + set last [lindex $lines end] + if { ! [string match "\1.*" $last] } { + #puts_stderr \tLIFT + set lines [lreplace $lines end end] + set line "$last $line" + } + } elseif {[string match {[']*} $line]} { + # Apostrophes at the beginning of a line have to be + # quoted to prevent misinterpretation as comments. + # The true comments and are quoted with \1 already and + # will therefore not detected by the code here. + # puts_stderr \tQUOTE + set line \1\\$line + } ; # We are not handling dots at the beginning of a line here. + # # We are handling them in the finalMap which will quote _all_ + # # dots in a text with a zero-width escape (\&). + } else { + # No-fill mode. We remove trailing whitespace, but keep + # leading whitespace and empty lines. + + if {[lsearch -exact $fiMode [split $line]] >= 0} { + # Normal mode resumes after this line. + set verbatim 0 + } + set line [string trimright $line] + } + lappend lines $line + } + + set lines [join $lines "\n"] + + # Now remove all superfluous .IP commands (empty paragraphs). The + # first identity mapping is present to avoid smashing a man macro + # definition. + + lappend map \n\1.IP\n\1.\1.\n \n\1.IP\n\1.\1.\n + lappend map \n\1.IP\n\1. \n\1. + + set lines [string map $map $lines] + + # Return the modified result buffer + return [string map $finalMap $lines] +} + diff --git a/tcllib/modules/doctools/mpformats/_text.tcl b/tcllib/modules/doctools/mpformats/_text.tcl new file mode 100644 index 0000000..6541e35 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_text.tcl @@ -0,0 +1,430 @@ +# -*- tcl -*- +# +# _text.tcl -- Core support for text engines. + + +################################################################ + +if {0} { + catch {rename proc proc__} msg ; puts_stderr >>$msg + proc__ proc {cmd argl body} { + puts_stderr "proc $cmd $argl ..." + uplevel [list proc__ $cmd $argl $body] + } +} + +dt_package textutil::string ; # for adjust +dt_package textutil::repeat +dt_package textutil::adjust + +if {0} { + puts_stderr ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + rename proc {} + rename proc__ proc + puts_stderr ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +} + + +################################################################ +# Formatting constants ... Might be engine variables in the future. + +global lmarginIncrement ; set lmarginIncrement 4 +global rmarginThreshold ; set rmarginThreshold 20 +global bulleting ; set bulleting {* - # @ ~ %} +global enumeration ; set enumeration {[%] (%) <%>} + +proc Bullet {ivar} { + global bulleting ; upvar $ivar i + set res [lindex $bulleting $i] + set i [expr {($i + 1) % [llength $bulleting]}] + return $res +} + +proc EnumBullet {ivar} { + global enumeration ; upvar $ivar i + set res [lindex $enumeration $i] + set i [expr {($i + 1) % [llength $enumeration]}] + return $res +} + +################################################################ + +# +# The engine maintains several data structures per document and pass. +# Most important is an internal representation of the text better +# suited to perform the final layouting, the display list. Elements of +# the display list are lists containing 2 elements, an operation, and +# its arguments, in this order. The arguments are a list again, its +# contents are specific to the operation. +# +# The operations are: +# +# - SECT Section. Title. +# - SUBSECT Subsection. Title. +# - PARA Paragraph. Environment reference and text. +# +# The PARA operation is the workhorse of the engine, dooing all the +# formatting, using the information in an "environment" as the guide +# for doing so. The environments themselves are generated during the +# second pass through the contents. They contain the information about +# nesting (i.e. indentation), bulleting and the like. +# + +global cmds ; set cmds [list] ; # Display list +global pEnv ; array set pEnv {} ; # Defined paragraph environments (bulleting, indentation, other). +global para ; set para "" ; # Text buffer for paragraphs. + +global nextId ; set nextId 0 ; # Counter for environment generation. +global currentId ; set currentId {} ; # Id of current environment in 'pEnv' +global currentEnv ; array set currentEnv {} ; # Current environment, expanded form. +global contexts ; set contexts [list] ; # Stack of saved environments. +global off ; set off 1 ; # Supression of plain text in some places. + +################################################################ +# Management of the current context. + +proc Text {text} {global para ; append para $text ; return} +proc Store {op args} {global cmds ; lappend cmds [list $op $args] ; return} +proc Off {} {global off ; set off 1 ; return} +proc On {} {global off para ; set off 0 ; set para "" ; return} +proc IsOff {} {global off ; return [expr {$off == 1}]} + +# Debugging ... +#proc Text {text} {puts_stderr "TXT \{$text\}"; global para; append para $text ; return} +#proc Store {op args} {puts_stderr "STO $op $args"; global cmds; lappend cmds [list $op $args]; return} +#proc Off {} {puts_stderr OFF ; global off ; set off 1 ; return} +#proc On {} {puts_stderr ON_ ; global off para ; set off 0 ; set para "" ; return} + + +proc NewEnv {name script} { + global currentId nextId currentEnv + + #puts_stderr "NewEnv ($name)" + + set parentId $currentId + set currentId $nextId + incr nextId + + append currentEnv(NAME) -$parentId-$name + set currentEnv(parent) $parentId + set currentEnv(id) $currentId + + # Always squash a verbatim environment inherited from the previous + # environment ... + catch {unset currentEnv(verbenv)} + + uplevel $script + SaveEnv + return $currentId +} + +################################################################ + +proc TextInitialize {} { + global off ; set off 1 + global cmds ; set cmds [list] ; # Display list + global pEnv ; array set pEnv {} ; # Defined paragraph environments (bulleting, indentation, other). + global para ; set para "" ; # Text buffer for paragraphs. + + global nextId ; set nextId 0 ; # Counter for environment generation. + global currentId ; set currentId {} ; # Id of current environment in 'pEnv' + global currentEnv ; array set currentEnv {} ; # Current environment, expanded form. + global contexts ; set contexts [list] ; # Stack of saved environments. + + # lmargin = location of left margin for text. + # prefix = prefix string to use for all lines. + # wspfx = whitespace prefix for all but the first line + # listtype = type of list, if any + # bullet = bullet to use for unordered, bullet template for ordered. + # verbatim = flag if verbatim formatting requested. + # next = if present the environment to use after closing the paragraph using this one. + + NewEnv Base { + array set currentEnv { + lmargin 0 + prefix {} + wspfx {} + listtype {} + bullet {} + verbatim 0 + bulleting 0 + enumeration 0 + } + } + return +} + +################################################################ + +proc Section {name} {Store SECT $name ; return} +proc Subsection {name} {Store SUBSECT $name ; return} + +proc CloseParagraph {{id {}}} { + global para currentId + if {$para != {}} { + if {$id == {}} {set id $currentId} + Store PARA $id $para + #puts_stderr "CloseParagraph $id" + } + set para "" + return +} + +proc SaveContext {} { + global contexts currentId + lappend contexts $currentId + + #global currentEnv ; puts_stderr "Save>> $currentId ($currentEnv(NAME))" + return +} + +proc RestoreContext {} { + global contexts + SetContext [lindex $contexts end] + set contexts [lrange $contexts 0 end-1] + + #global currentId currentEnv ; puts_stderr "<<Restored $currentId ($currentEnv(NAME))" + return +} + +proc SetContext {id} { + global currentId currentEnv pEnv + set currentId $id + + # Ensure that array is clean before setting hte new block of + # information. + unset currentEnv + array set currentEnv $pEnv($currentId) + + #puts_stderr "--Set $currentId ($currentEnv(NAME))" + return +} + +proc SaveEnv {} { + global pEnv currentId currentEnv + set pEnv($currentId) [array get currentEnv] + return +} + +################################################################ + +proc NewVerbatim {} { + global currentEnv + return [NewEnv Verbatim {set currentEnv(verbatim) 1}] +} + +proc Verbatim {} { + global currentEnv + if {![info exists currentEnv(verbenv)]} { + SaveContext + set verb [NewVerbatim] + RestoreContext + + # Remember verbatim mode in the base environment + set currentEnv(verbenv) $verb + SaveEnv + } + return $currentEnv(verbenv) +} + +################################################################ + +proc text_plain_text {text} { + #puts_stderr "<<text_plain_text>>" + + if {[IsOff]} {return} + + # Note: Whenever we get plain text it is possible that a macro for + # visual markup actually generated output before the expander got + # to the current text. This output was captured by the expander in + # its current context. Given the current organization of the + # engine we have to retrieve this formatted text from the expander + # or it will be lost. This is the purpose of the 'ctopandclear', + # which retrieves the data and also clears the capture buffer. The + # latter to prevent us from retrieving it again later, after the + # next macro added more data. + + set text [ex_ctopandclear]$text + + # ... TODO ... Handling of example => verbatim + + if {[string length [string trim $text]] == 0} return + + Text $text + return +} + +################################################################ + +proc text_postprocess {text} { + + #puts_stderr XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + #puts_stderr <<$text>> + #puts_stderr XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + + global cmds + # The argument is not relevant. Access the display list, perform + # the final layouting and return its result. + + set linebuffer [list] + array set state {lmargin 0 rmargin 0} + foreach cmd $cmds { + foreach {op arguments} $cmd break + $op $arguments + } + + #puts_stderr XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + + return [join $linebuffer \n] +} + + +proc SECT {text} { + upvar linebuffer linebuffer + + # text is actually the list of arguments, having one element, the text. + set text [lindex $text 0] + #puts_stderr "SECT $text" + #puts_stderr "" + + # Write section title, underline it + + lappend linebuffer "" + lappend linebuffer $text + lappend linebuffer [textutil::repeat::strRepeat = [string length $text]] + return +} + +proc SUBSECT {text} { + upvar linebuffer linebuffer + + # text is actually the list of arguments, having one element, the text. + set text [lindex $text 0] + #puts_stderr "SUBSECT $text" + #puts_stderr "" + + # Write subsection title, underline it (with less emphasis) + + lappend linebuffer "" + lappend linebuffer $text + lappend linebuffer [textutil::repeat::strRepeat - [string length $text]] + return +} + +proc PARA {arguments} { + global pEnv + upvar linebuffer linebuffer + + foreach {env text} $arguments break + array set para $pEnv($env) + + #puts_stderr "PARA $env" + #parray_stderr para + #puts_stderr " \{$text\}" + #puts_stderr "" + + # Use the information in the referenced environment to format the paragraph. + + if {$para(verbatim)} { + set text [textutil::adjust::undent $text] + } else { + # The size is determined through the set left and right margins + # right margin is fixed at 80, left margin is variable. Size + # is at least 20. I.e. when left margin > 60 right margin is + # shifted out to the right. + + set size [expr {80 - $para(lmargin)}] + if {$size < 20} {set size 20} + + set text [textutil::adjust::adjust $text -length $size] + } + + # Now apply prefixes, (ws prefixes bulleting), at last indentation. + + if {[string length $para(prefix)] > 0} { + set text [textutil::adjust::indent $text $para(prefix)] + } + + if {$para(listtype) != {}} { + switch -exact $para(listtype) { + bullet { + # Indent for bullet, but not the first line. This is + # prefixed by the bullet itself. + + set thebullet $para(bullet) + } + enum { + # Handling the enumeration counter. Special case: An + # example as first paragraph in an item has to use the + # counter in environment it is derived from to prevent + # miscounting. + + if {[info exists para(example)]} { + set parent $para(parent) + array set __ $pEnv($parent) + if {![info exists __(counter)]} { + set __(counter) 1 + } else { + incr __(counter) + } + set pEnv($parent) [array get __] ; # Save context change ... + set n $__(counter) + } else { + if {![info exists para(counter)]} { + set para(counter) 1 + } else { + incr para(counter) + } + set pEnv($env) [array get para] ; # Save context change ... + set n $para(counter) + } + + set thebullet [string map [list % $n] $para(bullet)] + } + } + + set blen [string length $thebullet] + if {$blen >= [string length $para(wspfx)]} { + set text "$thebullet\n[textutil::adjust::indent $text $para(wspfx)]" + } else { + set fprefix $thebullet[string range $para(wspfx) $blen end] + set text "${fprefix}[textutil::adjust::indent $text $para(wspfx) 1]" + } + } + + if {$para(lmargin) > 0} { + set text [textutil::adjust::indent $text \ + [textutil::repeat::strRepeat " " $para(lmargin)]] + } + + lappend linebuffer "" + lappend linebuffer $text + return +} + +################################################################ + +proc strong {text} {return *${text}*} +proc em {text} {return _${text}_} + +################################################################ + +proc parray_stderr {a {pattern *}} { + upvar 1 $a array + if {![array exists array]} { + error "\"$a\" isn't an array" + } + set maxl 0 + foreach name [lsort [array names array $pattern]] { + if {[string length $name] > $maxl} { + set maxl [string length $name] + } + } + set maxl [expr {$maxl + [string length $a] + 2}] + foreach name [lsort [array names array $pattern]] { + set nameString [format %s(%s) $a $name] + puts_stderr " [format "%-*s = {%s}" $maxl $nameString $array($name)]" + } +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/_toc_common.tcl b/tcllib/modules/doctools/mpformats/_toc_common.tcl new file mode 100644 index 0000000..a6ee81d --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_toc_common.tcl @@ -0,0 +1,31 @@ +# -*- tcl -*- +# +# _toc_common.tcl +# +# (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +################################################################ +# The code here contains general definitions for API functions and +# state information. They are used by several formatters to simplify +# their own code. + +proc toc_initialize {} {return} +proc toc_shutdown {} {return} +proc toc_numpasses {} {return 1} +proc toc_postprocess {text} {return $text} +proc toc_setup {n} {return} +proc toc_listvariables {} {return {}} +proc toc_varset {varname text} {return} + + +proc fmt_plain_text {text} {return $text} + +################################################################ +# Functions made available to the formatter to access the common +# state managed here. + +proc c_provenance {} { + return "Generated by tcllib/doctools/toc with format '[dt_format]'" +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/_xml.tcl b/tcllib/modules/doctools/mpformats/_xml.tcl new file mode 100644 index 0000000..346a2bd --- /dev/null +++ b/tcllib/modules/doctools/mpformats/_xml.tcl @@ -0,0 +1,236 @@ +# -*- tcl -*- +# +# $Id: _xml.tcl,v 1.9 2004/04/22 21:16:46 jenglish Exp $ +# +# [expand] utilities for generating XML. +# +# Copyright (C) 2001 Joe English <jenglish@sourceforge.net>. +# Freely redistributable. +# +###################################################################### + + +# Handling XML delimiters in content: +# +# Plain text is initially passed through unescaped; +# internally-generated markup is protected by preceding it with \1. +# The final PostProcess step strips the escape character from +# real markup and replaces markup characters from content +# with entity references. +# + +variable attvalMap { {&} & {<} < {>} > {"} " {'} ' } ; # " +variable markupMap { {&} {\1&} {<} {\1<} {>} {\1>} } +variable finalMap { {\1&} {&} {\1<} {<} {\1>} {>} + {&} & {<} < {>} > } + +proc fmt_postprocess {text} { + variable finalMap + return [string map $finalMap $text] +} + +# markup text -- +# Protect markup characters in $text with \1. +# These will be stripped out in PostProcess. +# +proc markup {text} { + variable markupMap + return [string map $markupMap $text] +} + +# attlist { n1 v1 n2 v2 ... } -- +# Return XML-formatted attribute list. +# Does *not* escape markup -- the result must be passed through +# [markup] before returning it to the expander. +# +proc attlist {nvpairs} { + variable attvalMap + if {[llength $nvpairs] == 1} { set nvpairs [lindex $nvpairs 0] } + set attlist "" + foreach {name value} $nvpairs { + append attlist " $name='[string map $attvalMap $value]'" + } + return $attlist +} + +# startTag gi ?attname attval ... ? -- +# Return start-tag for element $gi with specified attributes. +# +proc startTag {gi args} { + return [markup "<$gi[attlist $args]>"] +} + +# endTag gi -- +# Return end-tag for element $gi. +# +proc endTag {gi} { + return [markup "</$gi>"] +} + +# emptyElement gi ?attribute value ... ? +# Return empty-element tag. +# +proc emptyElement {gi args} { + return [markup "<$gi[attlist $args]/>"] +} + +# xmlComment text -- +# Return XML comment declaration containing $text. +# NB: if $text includes the sequence "--", it will be mangled. +# +proc xmlComment {text} { + return [markup "<!-- [string map {-- { - - }} $text] -->"] +} + +# wrap content gi -- +# Returns $content wrapped inside <$gi> ... </$gi> tags. +# +proc wrap {content gi} { + return "[startTag $gi]${content}[endTag $gi]" +} + +# wrap? content gi -- +# Same as [wrap], but returns an empty string if $content is empty. +# +proc wrap? {content gi} { + if {![string length [string trim $content]]} { return "" } + return "[startTag $gi]${content}[endTag $gi]" +} + +# wrapLines? content gi ? gi... ? +# Same as [wrap?], but separates entries with newlines +# and supports multiple nesting levels. +# +proc wrapLines? {content args} { + if {![string length $content]} { return "" } + foreach gi $args { + set content [join [list [startTag $gi] $content [endTag $gi]] "\n"] + } + return $content +} + +# sequence args -- +# Handy combinator. +# +proc sequence {args} { join $args "\n" } + +###################################################################### +# XML context management. +# + +variable elementStack [list] + +# start gi ?attribute value ... ? -- +# Return start-tag for element $gi +# As a side-effect, pushes $gi onto the element stack. +# +proc start {gi args} { + if {[llength $args] == 1} { set args [lindex $args 0] } + variable elementStack + lappend elementStack $gi + return [startTag $gi $args] +} + +# xmlContext {gi1 ... giN} ?default? -- +# Pops elements off the element stack until one of +# the specified element types is found. +# +# Returns: sequence of end-tags for each element popped. +# +# If none of the specified elements are found, returns +# a start-tag for $default. +# +proc xmlContext {gis {default {}}} { + variable elementStack + set origStack $elementStack + set endTags [list] + while {[llength $elementStack]} { + set current [lindex $elementStack end] + if {[lsearch $gis $current] >= 0} { + return [join $endTags \n] + } + lappend endTags [endTag $current] + set elementStack [lreplace $elementStack end end] + } + # Not found: + set elementStack $origStack + if {![string length $default]} { + set where "[join $elementStack /] - [info level 1]" + puts_stderr "Warning: Cannot start context $gis ($where)" + set default [lindex $gis 0] + } + lappend elementStack $default + return [startTag $default] +} + +# end ? gi ? -- +# Generate markup to close element $gi, including end-tags +# for any elements above it on the element stack. +# +# If element name is omitted, closes the current element. +# +proc end {{gi {}}} { + variable elementStack + if {![string length $gi]} { + set gi [lindex $elementStack end] + } + set prefix [xmlContext $gi] + set elementStack [lreplace $elementStack end end] + return [join [list $prefix [endTag $gi]] "\n"] +} + +###################################################################### +# Utilities for multi-pass processing. +# +# Not really XML-related, but I find them handy. +# + +variable PassProcs +variable Buffers + +# pass $passNo procName procArgs { body } -- +# Specifies procedure definition for pass $n. +# +proc pass {pass proc arguments body} { + variable PassProcs + lappend PassProcs($pass) $proc $arguments $body +} + +proc setPassProcs {pass} { + variable PassProcs + foreach {proc args body} $PassProcs($pass) { + proc $proc $args $body + } +} + +# holdBuffers buffer ? buffer ...? -- +# Declare a list of hold buffers, +# to collect data in one pass and output it later. +# +proc holdBuffers {args} { + variable Buffers + foreach arg $args { + set Buffers($arg) [list] + } +} + +# hold buffer text -- +# Append text to named buffer +# +proc hold {buffer entry} { + variable Buffers + lappend Buffers($buffer) $entry + return +} + +# held buffer -- +# Returns current contents of named buffer and empty the buffer. +# +proc held {buffer} { + variable Buffers + set content [join $Buffers($buffer) "\n"] + set Buffers($buffer) [list] + return $content +} + +#*EOF* diff --git a/tcllib/modules/doctools/mpformats/c.msg b/tcllib/modules/doctools/mpformats/c.msg new file mode 100644 index 0000000..99c72a7 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/c.msg @@ -0,0 +1,58 @@ +# -*- tcl -*- +package require msgcat +namespace import ::msgcat::* + +mcset c end/open/list "End of manpage reached, \[list_end\] missing" +mcset c end/open/example "End of manpage reached, \[example_end\] missing" +mcset c end/open/mp "End of manpage reached, \[manpage_end\] missing" +mcset c mpbegin "Command must be first of manpage" +mcset c mptitle "Spaces not allowed in manpage title" +mcset c hdrcmd "Command not allowed outside of the header section" +mcset c bodycmd "Command not allowed outside of the body of the manpage" +mcset c body "Plain text not allowed outside of the body of the manpage" +mcset c reqcmd "Command not allowed outside of header or requirement section" +mcset c invalidlist "Invalid list type \"@\"" +mcset c nolistcmd "Command not allowed inside of a list" +mcset c nolisthdr "Command not allowed between beginning of a list and its first item" +mcset c nolisttxt "Plain text not allowed between beginning of a list and its first item" +mcset c listcmd "Command not allowed outside of a list" +mcset c deflist "Command restricted to usage in definition lists" +mcset c bulletlist "Command restricted to usage in itemized lists" +mcset c enumlist "Command restricted to usage in enumerated lists" +mcset c examplecmd "Command allowed only to close example section" +mcset c listcmd "Command not allowed outside of a list" +mcset c nodonecmd "Command not allowed after \[manpage_end\]" +mcset c arg_list "Command restricted to usage in argument lists" +mcset c cmd_list "Command restricted to usage in command lists" +mcset c opt_list "Command restricted to usage in option lists" +mcset c tkoption_list "Command restricted to usage in tkoption lists" +mcset c depr_strong "Deprecated command \"%s\".\n\tPlease consider appropriate semantic markup or \[emph\] instead." +mcset c depr_lstitem "Deprecated command \"%s\".\n\tPlease use \[def\] instead." +mcset c depr_nl "Deprecated command \"%s\".\n\tPlease use \[para\] instead." +mcset c depr_bullet "Deprecated command \"%s\".\n\tPlease use \[item\] instead." +mcset c depr_ltype "Deprecated list type \"%s\".\n\tPlease use \"%s\" instead." +mcset c sectambig "(Sub)Section title \"%s\" causes ambiguous section references." +mcset c missingsect "Refered (Sub)Section \"%s\" is not known." + +# TOC messages + +mcset c end/open/toc "\[toc_end\] missing." +mcset c toc/plaintext "Plain text beyond whitespace is not allowed." +mcset c toc/begincmd "Command not allowed here." +mcset c toc/endcmd "Command not allowed here." +mcset c toc/titlecmd "Command not allowed here." +mcset c toc/sectcmd "Command not allowed here." +mcset c toc/sectecmd "Command not allowed here." +mcset c toc/itemcmd "Command not allowed here." +mcset c toc/nodonecmd "Command not allowed after \[toc_end\]" + +# IDX messages + +mcset c end/open/idx "\[index_end\] missing." +mcset c idx/plaintext "Plain text beyond whitespace is not allowed." +mcset c idx/begincmd "Command not allowed here." +mcset c idx/endcmd "Command not allowed here." +mcset c idx/keycmd "Command not allowed here." +mcset c idx/manpagecmd "Command not allowed here." +mcset c idx/urlcmd "Command not allowed here." +mcset c idx/nodonecmd "Command not allowed after \[index_end\]" diff --git a/tcllib/modules/doctools/mpformats/de.msg b/tcllib/modules/doctools/mpformats/de.msg new file mode 100644 index 0000000..8ba908c --- /dev/null +++ b/tcllib/modules/doctools/mpformats/de.msg @@ -0,0 +1,54 @@ +# -*- tcl -*- +package require msgcat +namespace import ::msgcat::* + +mcset de end/open/list "Dokument zu Ende, nicht alle Listen wurden geschlossen" +mcset de end/open/example "Dokument zu Ende, das letzte Beispiel wurde nicht abgeschlossen" +mcset de end/open/mp "Dokument zu Ende, es fehlt der Abschlussbefehl \[manpage_end\]" +mcset de mpbegin "Erwartete diesen Befehl als ersten in der Manpage" +mcset de mptitle "Der Manpage Titel darf keine Leerzeichen enthalten" +mcset de hdrcmd "Dieser Befehl ist ausserhalb des Headers nicht erlaubt" +mcset de bodycmd "Dieser Befehl darf nicht ausserhalb des Hauptteils der Manpage auftreten" +mcset de body "Text darf nicht ausserhalb des Hauptteils der Manpage auftreten" +mcset de reqcmd "Dieser Befehl ist ausserhalb von Header/Requirements nicht erlaubt" +mcset de invalidlist "Die Listenart \"@\" ist dem System nicht bekannt" +mcset de nolistcmd "Dieser Befehl ist innerhalb einer Liste nicht erlaubt" +mcset de nolisthdr "Dieser Befehl darf nicht zwischen dem Beginn einer Liste und ihrem ersten Unterpunkt benutzt werden" +mcset de nolisttxt "Text darf nicht zwischen dem Beginn einer Liste und ihrem ersten Unterpunkt benutzt werden" +mcset de listcmd "Dieser Befehl ist ausserhalb einer Liste nicht erlaubt" +mcset de deflist "Dieser Befehl darf nur in Definitions-Listen benutzt werden" +mcset de bulletlist "Dieser Befehl darf nur in ungeordneten Listen benutzt werden" +mcset de enumlist "Dieser Befehl darf nur in Aufz\xE4hlungs-Listen benutzt werden" +mcset de examplecmd "Dieser Befehl kann nur zum Schliessen eines Beispieles benutzt werden" +mcset de listcmd "Dieser Befehl ist ausserhalb einer Liste nicht erlaubt" +mcset de nodonecmd "Dieser Befehl ist nach Ausf\xFChrung von \[manpage_end\] nicht mehr erlaubt" +mcset de arg_list "Dieser Befehl darf nur in Argument-Listen benutzt werden" +mcset de cmd_list "Dieser Befehl darf nur in Befehls-Listen benutzt werden" +mcset de opt_list "Dieser Befehl darf nur in Options-Listen benutzt werden" +mcset de tkoption_list "Dieser Befehl darf nur in TkOptions-Listen benutzt werden" +mcset de depr_strong "Misbilligter Befehl \"%s\".\n\tBitte verwenden sie \[emph\] oder eine passende semantische Auszeichnung." +mcset de depr_lstitem "Misbilligter Befehl \"%s\".\n\tBitte verwenden sie \[def\]." +mcset de depr_nl "Misbilligter Befehl \"%s\".\n\tBitte verwenden sie \[para\]." +mcset de depr_bullet "Misbilligter Befehl \"%s\".\n\tBitte verwenden sie \[item\]." +mcset de depr_ltype "Misbilligte Listen-Art \"%s\".\n\tBitte verwenden sie \"%s\"." +mcset de sectambig "Die Kapitel\xFCberschrift \"%s\" ist nicht eindeutig, Referenzen k\xF6nnen falsch sein." +mcset de missingsect "Die Kapitel\xFCberschrift \"%s\" ist nicht bekannt." + +mcset de end/open/toc "\[toc_end\] fehlt." +mcset de toc/plaintext "Normaler Text ist (mit Ausnahme von reinem Leerraum) nicht erlaubt." +mcset de toc/begincmd "Dieser Befehl ist hier nicht erlaubt." +mcset de toc/endcmd "Dieser Befehl ist hier nicht erlaubt." +mcset de toc/titlecmd "Dieser Befehl ist hier nicht erlaubt." +mcset de toc/sectcmd "Dieser Befehl ist hier nicht erlaubt." +mcset de toc/sectecmd "Dieser Befehl ist hier nicht erlaubt." +mcset de toc/itemcmd "Dieser Befehl ist hier nicht erlaubt." +mcset de toc/nodonecmd "Dieser Befehl ist nach \[toc_end\] nicht erlaubt." + +mcset de end/open/idx "\[index_end\] fehlt." +mcset de idx/plaintext "Normaler Text ist (mit Ausnahme von reinem Leerraum) nicht erlaubt." +mcset de idx/begincmd "Dieser Befehl ist hier nicht erlaubt." +mcset de idx/endcmd "Dieser Befehl ist hier nicht erlaubt." +mcset de idx/keycmd "Dieser Befehl ist hier nicht erlaubt." +mcset de idx/manpagecmd "Dieser Befehl ist hier nicht erlaubt." +mcset de idx/urlcmd "Dieser Befehl ist hier nicht erlaubt." +mcset de idx/nodonecmd "Dieser Befehl ist nach \[index_end\] nicht erlaubt." diff --git a/tcllib/modules/doctools/mpformats/en.msg b/tcllib/modules/doctools/mpformats/en.msg new file mode 100644 index 0000000..d7dfffd --- /dev/null +++ b/tcllib/modules/doctools/mpformats/en.msg @@ -0,0 +1,54 @@ +# -*- tcl -*- +package require msgcat +namespace import ::msgcat::* + +mcset en end/open/list "End of manpage reached, \[list_end\] missing" +mcset en end/open/example "End of manpage reached, \[example_end\] missing" +mcset en end/open/mp "End of manpage reached, \[manpage_end\] missing" +mcset en mpbegin "Command must be first of manpage" +mcset en mptitle "Spaces not allowed in manpage title" +mcset en hdrcmd "Command not allowed outside of the header section" +mcset en bodycmd "Command not allowed outside of the body of the manpage" +mcset en body "Plain text not allowed outside of the body of the manpage" +mcset en reqcmd "Command not allowed outside of header or requirement section" +mcset en invalidlist "Invalid list type \"@\"" +mcset en nolistcmd "Command not allowed inside of a list" +mcset en nolisthdr "Command not allowed between beginning of a list and its first item" +mcset en nolisttxt "Plain text not allowed between beginning of a list and its first item" +mcset en listcmd "Command not allowed outside of a list" +mcset en deflist "Command restricted to usage in definition lists" +mcset en bulletlist "Command restricted to usage in itemized lists" +mcset en enumlist "Command restricted to usage in enumerated lists" +mcset en examplecmd "Command allowed only to close example section" +mcset en listcmd "Command not allowed outside of a list" +mcset en nodonecmd "Command not allowed after \[manpage_end\]" +mcset en arg_list "Command restricted to usage in argument lists" +mcset en cmd_list "Command restricted to usage in command lists" +mcset en opt_list "Command restricted to usage in option lists" +mcset en tkoption_list "Command restricted to usage in tkoption lists" +mcset en depr_strong "Deprecated command \"%s\".\n\tPlease consider appropriate semantic markup or \[emph\] instead." +mcset en depr_lstitem "Deprecated command \"%s\".\n\tPlease use \[def\] instead." +mcset en depr_nl "Deprecated command \"%s\".\n\tPlease use \[para\] instead." +mcset en depr_bullet "Deprecated command \"%s\".\n\tPlease use \[item\] instead." +mcset en depr_ltype "Deprecated list type \"%s\".\n\tPlease use \"%s\" instead." +mcset en sectambig "(Sub)Section title \"%s\" causes ambiguous section references." +mcset en missingsect "Refered (Sub)Section \"%s\" is not known." + +mcset en end/open/toc "\[toc_end\] missing." +mcset en toc/plaintext "Plain text beyond whitespace is not allowed." +mcset en toc/begincmd "Command not allowed here." +mcset en toc/endcmd "Command not allowed here." +mcset en toc/titlecmd "Command not allowed here." +mcset en toc/sectcmd "Command not allowed here." +mcset en toc/sectecmd "Command not allowed here." +mcset en toc/itemcmd "Command not allowed here." +mcset en toc/nodonecmd "Command not allowed after \[toc_end\]" + +mcset en end/open/idx "\[index_end\] missing." +mcset en idx/plaintext "Plain text beyond whitespace is not allowed." +mcset en idx/begincmd "Command not allowed here." +mcset en idx/endcmd "Command not allowed here." +mcset en idx/keycmd "Command not allowed here." +mcset en idx/manpagecmd "Command not allowed here." +mcset en idx/urlcmd "Command not allowed here." +mcset en idx/nodonecmd "Command not allowed after \[index_end\]" diff --git a/tcllib/modules/doctools/mpformats/fmt.desc b/tcllib/modules/doctools/mpformats/fmt.desc new file mode 100644 index 0000000..19afb44 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.desc @@ -0,0 +1,49 @@ +# -*- tcl -*- +# +# -- Extraction of meta information from a manpage (package +# description), and associating it with package names. +# +# Copyright (c) 2005 Andreas Kupries <andreas_kupries@sourceforge.net> +# +################################################################ + +# Take the null format as a base and extend it a bit. +dt_source fmt.null + +global data +array set data {} + +proc fmt_numpasses {} {return 1} +proc fmt_postprocess {text} { + global data + + # Title in required packages => This is the sole package. + # Otherwise dump everything required. + + if {[lsearch -exact $data(require) $data(title)] >= 0} { + return [list $data(title) $data(shortdesc) $data(desc)] + } else { + set res {} + foreach p $data(require) { + lappend res [list $p $data(shortdesc) $data(desc)] + } + return [join $res \n] + } +} +proc fmt_plain_text {text} {return ""} +proc fmt_setup {n} {return} + +proc fmt_manpage_begin {title section version} { + global data + set data(title) $title + set data(require) {} + set data(desc) "" + set data(shortdesc) "" + return +} + +proc fmt_moddesc {desc} {global data ; set data(shortdesc) $desc} +proc fmt_titledesc {desc} {global data ; set data(desc) $desc} +proc fmt_require {p {v {}}} {global data ; lappend data(require) $p ; return} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fmt.html b/tcllib/modules/doctools/mpformats/fmt.html new file mode 100644 index 0000000..153a52d --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.html @@ -0,0 +1,737 @@ +# -*- tcl -*- +# +# fmt.html +# +# Copyright (c) 2001-2008 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# Definitions to convert a tcl based manpage definition into +# a manpage based upon HTML markup. +# +################################################################ +################################################################ + +dt_source _common.tcl ; # Shared code +dt_source _html.tcl ; # HTML basic formatting + +proc c_copyrightsymbol {} {return "[markup "&"]copy;"} + +proc bgcolor {} {return ""} +proc border {} {return 0} +proc Year {} {clock format [clock seconds] -format %Y} + +c_holdBuffers require synopsis + +################################################################ +## Backend for HTML markup + +# -------------------------------------------------------------- +# Handling of lists. Simplified, the global check of nesting and +# legality of list commands allows us to throw away most of the +# existing checks. + +global liststack ; # stack of list tags to use in list_end +set liststack {} + +proc lpush {t class} { + global liststack + lappend liststack [list [tag/ $t] [litc_getandclear]] + return [taga $t [list class $class]] +} + +proc lpop {} { + global liststack + set t [lindex $liststack end] + set liststack [lreplace $liststack end end] + foreach {t l} $t break + litc_set $l + return $t +} + +proc fmt_plain_text {text} { + return $text +} + +################################################################ +# Formatting commands. + +c_pass 1 fmt_manpage_begin {title section version} {c_cinit ; c_clrSections ; return} +c_pass 2 fmt_manpage_begin {title section version} { + + global sec_is_open ; set sec_is_open 0 + global subsec_is_open ; set subsec_is_open 0 + global prev_litem_close ; set prev_litem_close {} + global para_is_open ; set para_is_open 0 + global liststack ; set liststack {} + global defaultstyle + + XrefInit + c_cinit + set module [dt_module] + set shortdesc [c_get_module] + set description [c_get_title] + set copyright [c_get_copyright] + + set pagetitle "$title - $shortdesc" + + set hdr "" + + if {![Get raw]} { + append hdr [tag html] [tag head] \n + append hdr [tag_ title $pagetitle] \n + + if {![Extend hdr ByParameter meta]} { + # Insert standard CSS definitions. + append hdr [tag_ style \ + "[markup <]!--${defaultstyle}--[markup >]" \ + type text/css] \n + } + + append hdr [tag/ head] \n + append hdr [ht_comment [c_provenance]]\n + if {$copyright != {}} { + append hdr [ht_comment $copyright]\n + } + append hdr [ht_comment "$title.$section"] + append hdr \n\n + append hdr [tag body] + } + + Extend hdr ByParameter header \ + @TITLE@ $pagetitle + + append hdr [tag* div class doctools] \n + + set thetitle "[string trimleft $title :]($section) $version $module \"$shortdesc\"" + append hdr [tag_ h1 $thetitle class doctools_title] \n + append hdr [fmt_section Name name] \n + append hdr "[para_open] $title - $description" + return $hdr +} + +c_pass 1 fmt_moddesc {desc} {c_set_module $desc} +c_pass 2 fmt_moddesc {desc} NOP + +c_pass 1 fmt_titledesc {desc} {c_set_title $desc} +c_pass 2 fmt_titledesc {desc} NOP + +c_pass 1 fmt_copyright {desc} {c_set_copyright $desc} +c_pass 2 fmt_copyright {desc} NOP + +c_pass 1 fmt_manpage_end {} {c_creset ; return} +c_pass 2 fmt_manpage_end {} { + c_creset + set res "" + + set sa [c_xref_seealso] + set kw [c_xref_keywords] + set ca [c_xref_category] + set ct [c_get_copyright] + + if {[llength $sa] > 0} { + append res [fmt_section {See Also} see-also] \n + append res [join [XrefList [lsort $sa] sa] ", "] \n + } + if {[llength $kw] > 0} { + append res [fmt_section Keywords keywords] \n + append res [join [XrefList [lsort $kw] kw] ", "] \n + } + if {$ca ne ""} { + append res [fmt_section Category category] \n + append res $ca \n + } + if {$ct != {}} { + append res [fmt_section Copyright copyright] \n + append res [join [split $ct \n] [tag br]\n] [tag br]\n + } + + # Close last paragraph, subsection, and section. + append res [para_close][subsec_close][sec_close] + + Extend res ByParameter footer + + append res [tag/ div] + if {![Get raw]} { + append res [tag/ body] [tag/ html] + } + return $res +} + +c_pass 1 fmt_section {name id} {c_newSection $name 1 end $id} +c_pass 2 fmt_section {name id} { + return "[sec_open $id][tag_ h2 [anchor $id $name]]\n[para_open]" +} + +c_pass 1 fmt_subsection {name id} {c_newSection $name 2 end $id} +c_pass 2 fmt_subsection {name id} { + return "[subsec_open $id][tag_ h3 [anchor $id $name]]\n[para_open]" +} + +# Para breaks inside and outside of lists are identical +proc fmt_nl {} {para_open} +proc fmt_para {} {para_open} + +c_pass 2 fmt_require {pkg {version {}}} NOP +c_pass 1 fmt_require {pkg {version {}}} { + if {$version != {}} { append pkg " " $version } + c_hold require [tag_ li "package require [bold $pkg pkgname]"] + return +} + +c_pass 2 fmt_usage {cmd args} NOP +c_pass 1 fmt_usage {cmd args} { + if {[llength $args]} { + set text "$cmd [join $args " "]" + } else { + set text $cmd + } + c_hold synopsis [tag_ li $text] + return +} + +c_pass 1 fmt_call {cmd args} { + if {[llength $args]} { + set text "$cmd [join $args " "]" + } else { + set text $cmd + } + c_hold synopsis [tag_ li [link $text "#[c_cnext]"]] + return +} +c_pass 2 fmt_call {cmd args} { + if {[llength $args]} { + set text "$cmd [join $args " "]" + } else { + set text $cmd + } + return [fmt_lst_item [anchor [c_cnext] $text]] +} + +c_pass 1 fmt_description {did} NOP +c_pass 2 fmt_description {did} { + set result "" + set syn [c_held synopsis] + set req [c_held require] + + # Create the TOC. + + # Pass 1: We have a number of special sections which were not + # listed explicitly in the document sources. Add them + # now. Note the inverse order for the sections added + # at the beginning. + + c_newSection Description 1 0 $did + if {$syn != {} || $req != {}} {c_newSection Synopsis 1 0 synopsis} + c_newSection {Table Of Contents} 1 0 toc + + if {[llength [c_xref_seealso]] > 0} {c_newSection {See Also} 1 end see-also} + if {[llength [c_xref_keywords]] > 0} {c_newSection Keywords 1 end keywords} + if {[c_xref_category] ne ""} {c_newSection Category 1 end category} + if {[c_get_copyright] != {}} {c_newSection Copyright 1 end copyright} + + set sections $::SectionList + + # Pass 2: Generate the markup for the TOC, indenting the + # links according to the level of each section. + + append result [fmt_section {Table Of Contents} toc] [para_close] \n + append result [taga ul {class doctools_toc}] \n + + set lastlevel 1 + set close 0 + foreach {name id level} $sections { + # level in {1,2}, 1 = sectio n, 2 = subsection + if {$level == $lastlevel} { + # Close previous item. + if {$close} { append result [tag/ li] \n } + } elseif {$level > $lastlevel} { + # Start list of subsections + append result \n [tag ul] \n + } else { # level < lastlevel + # End list of subsections, and of previous item (two + # actually, the subsection, and the section item). + append result [tag/ li] \n [tag/ ul] \n [tag/ li] \n + } + # Start entry + if {$level == 1} { + append result [taga li {class doctools_section}] + } else { + append result [taga li {class doctools_subsection}] + } + append result [link $name "#$id"] + set close 1 + + set lastlevel $level + } + if {$lastlevel > 1 } { append result [tag/ ul] \n } + if {$close} { append result [tag/ li] \n } + + append result [tag/ ul] \n + + # Implicit sections coming after the TOC (Synopsis, then the + # description which starts the actual document). The other + # implict sections are added at the end of the document and + # are generated by 'fmt_manpage_end' in the second pass. + + if {$syn != {} || $req != {}} { + append result [fmt_section Synopsis synopsis] [para_close] [taga div {class doctools_synopsis}] \n + if {$req != {}} { + append result [tag_ ul \n$req\n class doctools_requirements] \n + } + if {$syn != {}} { + append result [tag_ ul \n$syn\n class doctools_syntax] \n + } + append result [tag/ div] \n + } + append result [fmt_section Description $did] \n + return $result +} + +################################################################ + +proc fmt_list_begin {what {hint {}}} { + # NOTE: The hint is ignored. Use stylesheet definitions to modify + # item and general list spacing. + switch -exact -- $what { + enumerated {set tag ol} + itemized {set tag ul} + arguments - + commands - + options - + tkoptions - + definitions {set tag dl} + } + return [para_close][lpush $tag doctools_$what] +} + +proc fmt_list_end {} { + set res [para_close][litc_getandclear]\n[lpop][para_open] + return $res +} +proc fmt_lst_item {text} { + set res [para_close][litc_getandclear]\n[tag_ dt $text]\n[tag dd][para_open] + litc_set [tag/ dd] + return $res +} +proc fmt_bullet {} { + set res [para_close][litc_getandclear]\n[tag li][para_open] + litc_set [tag/ li] + return $res +} +proc fmt_enum {} { + set res [para_close][litc_getandclear]\n[tag li][para_open] + litc_set [tag/ li] + return $res +} + +proc fmt_cmd_def {command} { + fmt_lst_item [fmt_cmd $command] +} +proc fmt_arg_def {type name {mode {}}} { + set text "" + append text $type " " [fmt_arg $name] + if {$mode != {}} { + append text " (" $mode ")" + } + fmt_lst_item $text +} +proc fmt_opt_def {name {arg {}}} { + set text [fmt_option $name] + if {$arg != {}} {append text " " $arg} + fmt_lst_item $text +} +proc fmt_tkoption_def {name dbname dbclass} { + set text "" + append text "Command-Line Switch:\t[fmt_option $name][tag br]\n" + append text "Database Name:\t[bold $dbname optdbname][tag br]\n" + append text "Database Class:\t[bold $dbclass optdbclass][tag br]\n" + fmt_lst_item $text +} + +################################################################ + +proc fmt_example_begin {} { + return [para_close]\n[tag* pre class doctools_example] +} +proc fmt_example_end {} { + return [tag/ pre]\n[para_open] +} +proc fmt_example {code} { + return "[fmt_example_begin][fmt_plain_text $code][fmt_example_end]" +} + +################################################################ + +proc fmt_arg {text} { italic $text arg } +proc fmt_cmd {text} { bold [XrefMatch $text sa] cmd } +proc fmt_emph {text} { em $text } +proc fmt_opt {text} { span "?$text?" opt } + +proc fmt_comment {text} {ht_comment $text} +proc fmt_sectref {title {id {}}} { + global SectionNames + if {$id == {}} { + set id [c_sectionId $title] + } + if {[info exists SectionNames($id)]} { + return [span [link $title "#$id"] sectref] + } else { + return [bold $title sectref] + } +} + +proc fmt_syscmd {text} {bold [XrefMatch $text sa] syscmd} +proc fmt_method {text} {bold $text method} +proc fmt_option {text} {bold $text option} +proc fmt_widget {text} {bold $text widget} +proc fmt_fun {text} {bold $text function} +proc fmt_type {text} {bold $text type} +proc fmt_package {text} {bold [XrefMatch $text sa kw] package} +proc fmt_class {text} {bold $text class} +proc fmt_var {text} {bold $text variable} +proc fmt_file {text} {return "\"[bold $text file]\""} +proc fmt_namespace {text} {bold $text namespace} +proc fmt_uri {text {label {}}} { + if {$label == {}} {set label $text} + return [link $label $text] +} + +proc fmt_image {text {label {}}} { + # text = symbolic name of the image. + + set img [dt_imgdst $text {png gif jpg}] + + if {$label eq {}} { + set label $text + } + + if {$img ne {}} { + return [imagelink $label [LinkTo $img [LinkHere]]] + } + + if {[regexp -- {^http://} $text] || + [regexp -- {^ftp://} $text]} { + return [imagelink $label $text] + } + + #puts_stderr here:\t[LinkHere] + #puts_stderr dest:\t$img + #puts_stderr rela:\t[LinkTo $img [LinkHere]] + #puts_stderr + + return [strong "Image: $label"] +} + +proc fmt_term {text} {italic [XrefMatch $text kw sa] term} +proc fmt_const {text} {bold $text const} + +proc fmt_mdash {} { return "[markup &]mdash;" } +proc fmt_ndash {} { return "[markup &]ndash;" } + +################################################################ + +global sec_is_open +set sec_is_open 0 + +proc sec_open {id} { + global sec_is_open + set res [para_close][subsec_close][sec_close][tag* div id $id class doctools_section] + set sec_is_open 1 + return $res +} + +proc sec_close {} { + global sec_is_open + if {!$sec_is_open} {return ""} + set sec_is_open 0 + return [tag/ div]\n +} + +################################################################ + +global subsec_is_open +set subsec_is_open 0 + +proc subsec_open {id} { + global subsec_is_open + set res [para_close][subsec_close][tag* div id $id class doctools_subsection] + set subsec_is_open 1 + return $res +} + +proc subsec_close {} { + global subsec_is_open + if {!$subsec_is_open} {return ""} + set subsec_is_open 0 + return [tag/ div]\n +} + +################################################################ + +# Piece of html to close the previous list element, if any. +# Saved on the list stack + +global prev_litem_close +set prev_litem_close {} + +proc litc_getandclear {} { + global prev_litem_close + set res $prev_litem_close + set prev_litem_close {} + return $res +} + +proc litc_set {value} { + global prev_litem_close + set prev_litem_close $value + return +} + +################################################################ + +global para_is_open +set para_is_open 0 + +proc para_open {} { + global para_is_open + set res [para_close][tag p] + set para_is_open 1 + return $res +} + +proc para_close {} { + global para_is_open + if {!$para_is_open} {return ""} + set para_is_open 0 + return [tag/ p] +} + +################################################################ + +global xref ; array set xref {} + +global __var +array set __var { + meta {} + header {} + footer {} + xref {} + raw 0 +} +proc Get {varname} {global __var ; return $__var($varname)} +proc fmt_listvariables {} {global __var ; return [array names __var]} +proc fmt_varset {varname text} { + global __var + if {![info exists __var($varname)]} {return -code error "Unknown engine variable \"$varname\""} + set __var($varname) $text + return +} + +# Engine parameter handling +proc Extend {v _ by args} { + set html [Get $by] + if {$html == {}} { return 0 } + upvar 1 $v text + if {[llength $args]} { + set html [string map $args $html] + } + append text [markup $html] \n + return 1 +} + +global defaultstyle +set defaultstyle { + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +} + +################################################################ + +proc XrefInit {} { + global xref __var + foreach item $__var(xref) { + foreach {pattern fname fragment} $item break + set fname_ref [dt_fmap $fname] + if {$fragment != {}} {append fname_ref #$fragment} + set xref($pattern) $fname_ref + } + proc XrefInit {} {} + return +} + +proc XrefMatch {word args} { + global xref + + foreach ext $args { + if {$ext != {}} { + if {[info exists xref($ext,$word)]} { + return [XrefLink $xref($ext,$word) $word] + } + } + } + if {[info exists xref($word)]} { + return [XrefLink $xref($word) $word] + } + + # Convert the word to all-lower case and then try again. + + set lword [string tolower $word] + + foreach ext $args { + if {$ext != {}} { + if {[info exists xref($ext,$lword)]} { + return [XrefLink $xref($ext,$lword) $word] + } + } + } + if {[info exists xref($lword)]} { + return [XrefLink $xref($lword) $word] + } + + return $word +} + +proc XrefList {list {ext {}}} { + set res [list] + foreach w $list {lappend res [XrefMatch $w $ext]} + return $res +} + +proc LinkHere {} { + return [dt_fmap [dt_mainfile]] +} + +proc LinkTo {dest here} { + # Ensure that the link is properly done relative to this file! + + set save $dest + + #puts_stderr "XrefLink $dest $label" + + set here [file split $here] + set dest [file split $dest] + + #puts_stderr "XrefLink < $here" + #puts_stderr "XrefLink > $dest" + + while {[string equal [lindex $dest 0] [lindex $here 0]]} { + set dest [lrange $dest 1 end] + set here [lrange $here 1 end] + if {[llength $dest] == 0} {break} + } + set ul [llength $dest] + set hl [llength $here] + + if {$ul == 0} { + set dest [lindex [file split $save] end] + } else { + while {$hl > 1} { + set dest [linsert $dest 0 ..] + incr hl -1 + } + set dest [eval file join $dest] + } + + #puts_stderr "XrefLink --> $dest" + return $dest +} + +proc XrefLink {dest label} { + # Ensure that the link is properly done relative to this file! + + set here [LinkHere] + set dest [LinkTo $dest $here] + + if {[string equal $dest [lindex [file split $here] end]]} { + # Suppress self-referential links, i.e. links made from the + # current file to itself. Note that links to specific parts of + # the current file are not suppressed, only exact links. + return $label + } + return [link $label $dest] +} diff --git a/tcllib/modules/doctools/mpformats/fmt.latex b/tcllib/modules/doctools/mpformats/fmt.latex new file mode 100644 index 0000000..c0cbe68 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.latex @@ -0,0 +1,404 @@ +# -*- tcl -*- +# +# fmt.latex +# +# (c) 2001 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# [mpexpand] definitions to convert a tcl based manpage definition into +# a manpage based upon LaTeX markup. +# +################################################################ + +## +## This engine needs a rewrite for a better handling +## of characters special to TeX / LaTeX. +## + +dt_source _common.tcl ; # Shared code + +global _in_example +set _in_example 0 + +global _has_images +set _has_images 0 + +# Called to handle plain text from the input +proc fmt_plain_text {text} { + global _in_example + if {$_in_example} { + return $text + } + return [texEscape $text] +} + +proc Year {} {clock format [clock seconds] -format %Y} + +c_holdBuffers require + +proc fmt_postprocess {text} { + regsub -all -- "\n+" $text "\n" text + return [string map {\1\\ \\ \1$ $} $text] + #return $text +} + +################################################################ +## Backend for LaTeX markup + +c_pass 1 fmt_manpage_begin {title section version} NOP +c_pass 2 fmt_manpage_begin {title section version} { + global _has_images + + set module [dt_module] + set shortdesc [c_get_module] + set description [c_get_title] + set copyright [c_get_copyright] + + set hdr "" + append hdr [Comment [c_provenance]] \n + if {$copyright != {}} { + append hdr [Comment $copyright] \n + } + append hdr [Comment "CVS: \$Id\$ $title.$section"] \n + append hdr \n + append hdr "\1\\documentclass\{article\}" \n + + if {$_has_images} { + append hdr "\1\\usepackage{epsfig}" \n + append hdr "\1\\usepackage{epstopdf}" \n + } + + append hdr "\1\\begin\{document\}" \n + append hdr "\1\\author\{[dt_user]\}" \n + + set titletext "" + append titletext "$module / $title -- " + append titletext "$shortdesc : $description" + + append hdr "\1\\title\{[texEscape $titletext]\}" \n + append hdr "\1\\maketitle" \n + return $hdr +} + +c_pass 1 fmt_moddesc {desc} {c_set_module $desc} +c_pass 2 fmt_moddesc {desc} NOP + +c_pass 1 fmt_titledesc {desc} {c_set_title $desc} +c_pass 2 fmt_titledesc {desc} NOP + +c_pass 1 fmt_copyright {desc} {c_set_copyright [texEscape $desc]} +c_pass 2 fmt_copyright {desc} NOP + +c_pass 1 fmt_manpage_end {} NOP +c_pass 2 fmt_manpage_end {} { + set res "" + + set sa [c_xref_seealso] + set kw [c_xref_keywords] + set ca [c_xref_category] + set ct [c_get_copyright] + + if {[llength $sa] > 0} { + set tmp {} + foreach x $sa {lappend tmp [texEscape $x]} + set sa $tmp + + append res [fmt_section {See Also} see-also] \n + append res [join [lsort $sa] ", "] \n + } + if {[llength $kw] > 0} { + set tmp {} + foreach x $kw {lappend tmp [texEscape $x]} + set kw $tmp + + append res [fmt_section Keywords keywords] \n + append res [join [lsort $kw] ", "] \n + } + if {$ca ne ""} { + set ca [texEscape $ca] + + append res [fmt_section Category category] \n + append res $ca \n + } + if {$ct != {}} { + append res [fmt_section Copyright copyright] \n + append res \1\\begin\{flushleft\} \n + append res [join [split $ct \n] \1\\linebreak\n] \1\\linebreak\n + append res \1\\end\{flushleft\} \n + } + append res "\1\\end\{document\}" + return $res +} + +proc fmt_section {name id} {return "\1\\section\{[texEscape $name]\}\1\\label\{$id\}"} +proc fmt_subsection {name id} {return "\1\\subsection\{[texEscape $name]\}\1\\label\{$id\}"} +proc fmt_para {} {return \n\n} + +c_pass 2 fmt_require {pkg {version {}}} NOP +c_pass 1 fmt_require {pkg {version {}}} { + if {$version != {}} { + set res "package require [Bold "$pkg $version"]\n" + } else { + set res "package require [Bold $pkg]\n" + } + c_hold require $res + return +} + +c_pass 2 fmt_usage {cmd args} NOP +c_pass 1 fmt_usage {cmd args} {c_hold synopsis "\1\\item\[\] $cmd [join $args " "]"} + +c_pass 2 fmt_call {cmd args} {return "[fmt_lst_item "$cmd [join $args " "]"]"} +c_pass 1 fmt_call {cmd args} {c_hold synopsis "\1\\item\[\] $cmd [join $args " "]"} + +c_pass 1 fmt_description {id} NOP +c_pass 2 fmt_description {id} { + set res "" + set req [c_held require] + set syn [c_held synopsis] + if {$req != {} || $syn != {}} { + append res [fmt_section Synopsis synopsis]\n + if {$req != {}} { + append res \1\\begin\{flushleft\} \n + append res $req \n + append res \1\\end\{flushleft\} \n + } + if {$syn != {}} { + append res "\1\\begin\{itemize\}" \n + append res ${syn} \n\n + append res "\1\\end\{itemize\}" \n + } + } + append res [fmt_section Description $id] + return $res +} + +################################################################ + +global list_state +array set list_state {level -1} + +proc fmt_list_begin {what {hint {}}} { + # ignoring hints + global list_state + incr list_state(level) + set list_state(l,$list_state(level)) $what + set list_state(l,$list_state(level),item) 0 + + switch -exact -- $what { + enumerated { + return \1\\begin\{enumerate\} + } + itemized - + arguments - + options - + commands - + tkoptions - + definitions { + return \1\\begin\{itemize\} + } + default { + return -code error "Must not happen" + } + } +} + +proc fmt_list_end {} { + global list_state + + set what $list_state(l,$list_state(level)) + set item $list_state(l,$list_state(level),item) + + catch {unset list_state(l,$list_state(level))} + catch {unset list_state(l,$list_state(level),item)} + + incr list_state(level) -1 + + switch -exact -- $what { + enumerated { + return \1\\end\{enumerate\} + } + itemized - + arguments - + options - + commands - + tkoptions - + definitions { + return \1\\end\{itemize\} + } + default { + return -code error "Must not happen" + } + } +} + +proc fmt_bullet {} {return "\n%\n\1\\item\n%\n"} +proc fmt_enum {} {return "\n%\n\1\\item\n%\n"} + +proc fmt_lst_item {text} { + global list_state + + set item $list_state(l,$list_state(level),item) + set list_state(l,$list_state(level),item) 1 + + set text [texEscape $text] + return "\n%\n\1\\item\[\] $text\n%\n" +} + +proc fmt_arg_def {type name {mode {}}} { + global list_state + + set item $list_state(l,$list_state(level),item) + set list_state(l,$list_state(level),item) 1 + + set text "" + append text [fmt_arg $name] + append text " $type" + if {$mode != {}} {append text " ($mode)"} + return "\n%\n\1\\item\[\] $text\n%\n" +} + +proc fmt_cmd_def {command} { + global list_state + + set item $list_state(l,$list_state(level),item) + set list_state(l,$list_state(level),item) 1 + + set text [fmt_cmd $command] + return "\n%\n\1\\item\[\] $text\n%\n" +} + +proc fmt_opt_def {name {arg {}}} { + global list_state + + set item $list_state(l,$list_state(level),item) + set list_state(l,$list_state(level),item) 1 + + set text [fmt_option $name] + if {$arg != {}} {append text " $arg"} + return "\n%\n\1\\item\[\] $text\n%\n" +} + +proc fmt_tkoption_def {name dbname dbclass} { + global list_state + + set item $list_state(l,$list_state(level),item) + set list_state(l,$list_state(level),item) 1 + + set text "" + append text "Command-Line Switch: [Bold $name]\\\\\n" + append text "Database Name: [Bold $dbname]\\\\\n" + append text "Database Class: [Bold $dbclass]\\\\\n" + return "\n%\n\1\\item\[\] $text\n%\n" +} + +################################################################ + +proc fmt_example_begin {} { + global _in_example + set _in_example 1 + return {\begin{verbatim}} +} +proc fmt_example_end {} { + global _in_example + set _in_example 0 + return {\end{verbatim}} +} +# No mapping of special characters +proc fmt_example {code} { return "\1\\begin\{verbatim\}\n${code}\n\1\\end\{verbatim\}\n" } + +proc fmt_nl {} {return} +proc fmt_arg {text} {Underline $text} +proc fmt_cmd {text} {Bold $text} +proc fmt_emph {text} {Italic $text} +proc fmt_opt {text} {return ?$text?} + +proc fmt_comment {text} { + set res [list] + foreach l [split $text \n] { + lappend res [Comment $l] + } + return [join $res \n] +} +proc fmt_sectref {text {label {}}} { + if {![string length $label]} {set label $text} + Bold "$text (\1\\ref\{$label\})" +} +proc fmt_syscmd {text} {Bold $text} +proc fmt_method {text} {Bold $text} +proc fmt_option {text} {Bold $text} +proc fmt_widget {text} {Bold $text} +proc fmt_fun {text} {Bold $text} +proc fmt_type {text} {Bold $text} +proc fmt_package {text} {Bold $text} +proc fmt_class {text} {Bold $text} +proc fmt_var {text} {Bold $text} +proc fmt_file {text} {return "\"[Italic $text]\""} +proc fmt_namespace {text} {Bold $text]} +proc fmt_uri {text {label {}}} { + if {$label == {}} { + # Without label we use the link directly as part of the text. + return [Underline $text] + } else { + # Label is used in the text, refered link is delegated into a + # footnote. + return "[Underline $label] \1\\footnote\{[texEscape $text]\}" + } +} +proc fmt_image {text {label {}}} { + global _has_images + # text = symbolic name of the image. + + set img [dt_imgsrc $text {eps ps}] + if {$img eq {}} { + if {$label eq {}} { + return [Underline "IMAGE: $text"] + } else { + return [Underline "IMAGE: $text $label"] + } + } + + set _has_images 1 + + return "\1\\begin{figure}\[htp\]\1\\includegraphics\[width=0.9\1\\textwidth\]{$img}\1\\end{figure}" +} +proc fmt_term {text} {Italic $text} +proc fmt_const {text} {Bold $text} +proc fmt_mdash {} { return " --- " } +proc fmt_ndash {} { return " -- " } + +################################################################ +# latex specific commands + +proc Comment {text} {return "% [join [split $text \n] "\n% "]"} +proc Bold {text} {return "\{\1\\bf [texEscape $text]\}"} +proc Italic {text} {return "\{\1\\it [texEscape $text]\}"} +proc Underline {text} {return "\1\\underline\{[texEscape $text]\}"} + +################################################################ + +proc texEscape {text} { + set x 0 + if {[string match *%* $text]} { + #puts_stderr '$text' + set x 1 + } + + # Important: \1 protected sequences are left unchanged, they are already escaped. + set text [string map { + \1$\\backslash$ \1$\\backslash$ \1$<$ \1$<$ \1$>$ \1$>$ + \1\\_ \1\\_ + \1\\% \1\\% + \1\\^ \1\\^ + \1\\$ \1\\$ + \1\\# \1\\# + \1\\& \1\\& + \1\\ \1\\ + \\ \1$\\backslash$ _ \1\\_ % \1\\% ^ \1\\^ $ \1\\$ < \1$<$ > \1$>$ # \1\\# & \1\\& + } $text] + if {$x} { + #puts_stderr "==> '$text'" + } + return $text +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fmt.list b/tcllib/modules/doctools/mpformats/fmt.list new file mode 100644 index 0000000..15ed7f9 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.list @@ -0,0 +1,52 @@ +# -*- tcl -*- +# +# -- Extraction of basic meta information (title section version) from a manpage. +# +# Copyright (c) 2001-2002 Andreas Kupries <andreas_kupries@sourceforge.net> +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# +################################################################ + +# Take the null format as a base and extend it a bit. +dt_source fmt.null + +global data +array set data {} + +proc fmt_numpasses {} {return 1} +proc fmt_postprocess {text} { + global data + foreach key {seealso keywords} { + array set _ {} + foreach ref $data($key) {set _($ref) .} + set data($key) [array names _] + unset _ + } + return [list manpage [array get data]]\n +} +proc fmt_plain_text {text} {return ""} +proc fmt_setup {n} {return} + +proc fmt_manpage_begin {title section version} { + global data + set data(title) $title + set data(section) $section + set data(version) $version + set data(file) [dt_file] + set data(fid) [dt_fileid] + set data(module) [dt_module] + set data(desc) "" + set data(shortdesc) "" + set data(keywords) [list] + set data(seealso) [list] + set data(category) "" + return +} + +proc fmt_moddesc {desc} {global data ; set data(shortdesc) $desc} +proc fmt_titledesc {desc} {global data ; set data(desc) $desc} +proc fmt_keywords {args} {global data ; foreach ref $args {lappend data(keywords) $ref} ; return} +proc fmt_see_also {args} {global data ; foreach ref $args {lappend data(seealso) $ref} ; return} +proc fmt_category {text} {global data ; set data(category) $text ; return} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fmt.nroff b/tcllib/modules/doctools/mpformats/fmt.nroff new file mode 100644 index 0000000..0988255 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.nroff @@ -0,0 +1,290 @@ +# -*- tcl -*- +# +# -- doctools NROFF formatting engine. +# +# Copyright (c) 2001-2011 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# [expand] definitions to convert a tcl based manpage definition into +# a manpage based upon *roff markup. Additional definition files allow +# the conversion into HTML and TMML. + + +################################################################ +# Load shared code, load nroff support. + +dt_source _common.tcl +dt_source _nroff.tcl + +################################################################ +# Define the API commands. + +c_pass 1 fmt_manpage_begin {title section version} c_begin +c_pass 2 fmt_manpage_begin {title section version} { + c_begin + + set module [dt_module] + set shortdesc [c_get_module] + set description [c_get_title] + set copyright [c_get_copyright] + + # compact whitespace + foreach v {module shortdesc description copyright} { + upvar 0 $v text + regsub -all {[ \t]+} $text { } text + set text [string trim $text] + } + + c_holdBuffers hdr + + c_hold hdr [nr_comment {}] + c_hold hdr [nr_comment [c_provenance]] + if {$copyright != {}} { + c_hold hdr [nr_comment $copyright] + } + c_hold hdr [nr_comment {}] + + if {[set text [c_held precomments]] != {}} { + c_hold hdr $text + } + + c_hold hdr [nr_title "\"[string trimleft $title :]\" $section $version $module \"$shortdesc\""] + c_hold hdr [nr_read man.macros] + c_hold hdr [nr_bolds] + c_hold hdr [fmt_section NAME] + c_hold hdr "$title \1\\- $description" + + return [c_held hdr] +} + +c_pass 1 fmt_moddesc {desc} {c_set_module $desc} +c_pass 2 fmt_moddesc {desc} NOP + +c_pass 1 fmt_titledesc {desc} {c_set_title $desc} +c_pass 2 fmt_titledesc {desc} NOP + +c_pass 1 fmt_copyright {desc} {c_set_copyright $desc} +c_pass 2 fmt_copyright {desc} NOP + +c_pass 1 fmt_manpage_end {} NOP +c_pass 2 fmt_manpage_end {} { + + # Complete the generation with a copyright + # section, if such information is available. + + set nroff "" + + set sa [c_xref_seealso] + set kw [c_xref_keywords] + set ca [c_xref_category] + set ct [c_get_copyright] + + if {[llength $sa] > 0} { + append nroff [fmt_section {SEE ALSO}] \n + append nroff [join [lsort $sa] ", "] \n + } + if {[llength $kw] > 0} { + append nroff [fmt_section KEYWORDS] \n + set kwline [join [lsort $kw] ", "] + if { [string match ".*" $kwline] } { + set kwline "\\$kwline" + } + append nroff $kwline \n + } + if {$ca ne ""} { + append nroff [fmt_section CATEGORY] \n + append nroff $ca \n + } + if {$ct != {}} { + append nroff [fmt_section COPYRIGHT] \n + append nroff [nr_nofill] \n + append nroff $ct \n + append nroff [nr_fill] + } + return $nroff +} + +proc fmt_postprocess {nroff} {return [nroff_postprocess $nroff]} + +proc fmt_section {name {id {}}} {return [nr_section $name]} +proc fmt_subsection {name {id {}}} {return [nr_subsection $name]} +proc fmt_para {} { + if {[dt_lnesting]} { return [nr_item] } + nr_p +} + +c_pass 2 fmt_require {pkg {version {}}} NOP +c_pass 1 fmt_require {pkg {version {}}} { + if {$version != {}} {set version " $version"} + c_hold synopsis "package require [nr_bld]$pkg $version[nr_rst]\n[nr_vspace]" +} + +c_pass 1 fmt_usage {cmd args} {c_hold synopsis "$cmd [join $args " "]\n[nr_vspace]"} +c_pass 2 fmt_usage {cmd args} NOP + +c_pass 1 fmt_call {cmd args} {c_hold synopsis "$cmd [join $args " "]\n[nr_vspace]"} +c_pass 2 fmt_call {cmd args} {return "[fmt_lst_item "$cmd [join $args " "]"]"} + +c_pass 1 fmt_description {id} NOP +c_pass 2 fmt_description {id} { + set text "" + if {[set syn [c_held synopsis]] != {}} { + append text [fmt_section SYNOPSIS]\n + append text ${syn}\n + append text [nr_bolde]\n + } + append text [fmt_section DESCRIPTION] + return $text +} + +################################################################ + +global list_state +array set list_state {level -1} + +proc fmt_list_begin {what {hint {}}} { + c_cinit + if {[dt_lnesting]} { return [nr_in] } + return {} +} + +proc fmt_list_end {} { + c_creset + if {[dt_lnesting]} { + return [nr_out][nr_item] + } else { + return [nr_p] + } +} + +proc fmt_enum {} {return [nr_item " \[[c_cnext]\]\n"]} +proc fmt_bullet {} {return [nr_item " \1\\(bu\n"]} +proc fmt_lst_item {text} {return [nr_blt $text]\n} +proc fmt_cmd_def {command} {return [nr_blt [fmt_cmd $command]]\n} + +proc fmt_arg_def {type name {mode {}}} { + set text [nr_blt ""] + append text "$type [fmt_arg $name]" + if {$mode != {}} {append text " ($mode)"} + return $text\n +} +proc fmt_opt_def {name {arg {}}} { + #if {[string match -* $name]} {set name \1\\$name} + set name [fmt_option $name] + if {$arg != {}} {append name " $arg"} + return [nr_blt $name]\n +} +proc fmt_tkoption_def {name dbname dbclass} { + set text "" + append text "[nr_lp]\n" + append text "[nr_nofill]\n" + append text "[nr_ta " 6c"]\n" + append text "Command-Line Switch:\t[bold $name]\n" + append text "Database Name:\t[bold $dbname]\n" + append text "Database Class:\t[bold $dbclass]\n" + append text "[nr_fill]\n" + append text "[nr_item]\n" + return $text +} + +################################################################ + +proc fmt_example_begin {} { + return [nr_cs]\n +} +proc fmt_example_end {} { + if {[dt_lnesting]} { + return [nr_ce][nr_item] + } + nr_ce +} +proc fmt_example {code} { + set lines [list "" [nr_cs]] + foreach line [split $code "\n"] { + lappend lines [fmt_plain_text $line] + } + lappend lines [nr_ce] "" + return [join $lines "\n"] +} + +proc fmt_nl {} {nr_vspace} +proc fmt_arg {text} {underline $text} +proc fmt_cmd {text} {bold $text} +proc fmt_emph {text} {underline $text} +proc fmt_opt {text} {return ?$text?} + +proc bold {text} { + # .B don't work in .TP (nr_blt) + if {1||[string match *\n* $text]} { + return [nr_bld]$text[nr_rst] + } else { + return [nr_bldt $text] + } +} +proc underline {text} { + return [nr_ul]$text[nr_rst] +} + +proc fmt_comment {text} { + set res [list] + foreach l [split $text \n] { + lappend res [nr_comment $l] + } + if {[c_begun]} { + return [join $res \n] + } else { + if {[c_inpass] == 1} { + c_hold precomments [join $res \n] + } + return "" + } +} +proc fmt_sectref {text {label {}}} { + if {![string length $label]} {set label $text} + bold $text +} +proc fmt_syscmd {text} {bold $text} +proc fmt_method {text} {bold $text} +proc fmt_option {text} {bold $text} +proc fmt_widget {text} {bold $text} +proc fmt_fun {text} {bold $text} +proc fmt_type {text} {bold $text} +proc fmt_package {text} {bold $text} +proc fmt_class {text} {bold $text} +proc fmt_var {text} {bold $text} +proc fmt_file {text} {return "\"[underline $text]\""} +proc fmt_namespace {text} {bold $text} +proc fmt_uri {text {label {}}} { + if {$label == {}} { + # Without label we use the link directly as part of the text. + return [underline $text] + } else { + # with label and link we use the label directly, and the + # link comes in parentheses after that. + + return "[underline $label] \[$text\]" + } +} +proc fmt_image {text {label {}}} { + # text = symbolic name of the image. + + set img [dt_imgdata $text {pic}] + if {$img ne {}} { + return \n\1.PS\n$img\n\1.PE\n + } + set img [dt_imgdata $text {txt}] + if {$img ne {}} { + return \n\1.PS\n\1.nf\n$img\n\1.fi\n\1.PE\n + } + if {$label eq {}} { + return "IMAGE: $text" + } else { + return "IMAGE: $text $label" + } +} +proc fmt_term {text} {underline $text} +proc fmt_const {text} {bold $text} + +proc fmt_mdash {} { return " \1\\(em\n" } +proc fmt_ndash {} { return " \1\\(en\n" } + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fmt.null b/tcllib/modules/doctools/mpformats/fmt.null new file mode 100644 index 0000000..1b2eee0 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.null @@ -0,0 +1,30 @@ +# -*- tcl -*- +# +# -- Null format +# +# Copyright (c) 2001-2002 Andreas Kupries <andreas_kupries@sourceforge.net> +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +# This is a null format which does return no output at all. + +################################################################ + +proc fmt_initialize {} {return} +proc fmt_shutdown {} {return} +proc fmt_numpasses {} {return 1} +proc fmt_postprocess {text} {return ""} +proc fmt_plain_text {text} {return ""} +proc fmt_setup {n} {return} + +foreach p { + manpage_begin moddesc titledesc manpage_end require description + section para list_begin list_end lst_item call usage bullet enum + arg_def cmd_def opt_def tkoption_def see_also keywords example + example_begin example_end nl arg cmd opt emph comment image mdash + sectref syscmd method option widget fun type package class var + file uri term const copyright namespace subsection category ndash +} { + proc fmt_$p {args} {return ""} +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fmt.text b/tcllib/modules/doctools/mpformats/fmt.text new file mode 100644 index 0000000..27eec2e --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.text @@ -0,0 +1,473 @@ +# -*- tcl -*- +# +# fmt.text -- Engine to convert a doctools document into plain text. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# +################################################################ +################################################################ + +# Load shared code and modify it to our needs. + +dt_source _common.tcl +dt_source _text.tcl +proc c_copyrightsymbol {} {return "(c)"} + +rename fmt_initialize BaseInitialize +proc fmt_initialize {} {BaseInitialize ; TextInitialize ; return} + +################################################################ +# Special manpage environments + +proc NewExample {} { + global currentEnv + return [NewEnv Example { + set currentEnv(verbatim) 1 + append currentEnv(prefix) "| " + set currentEnv(example) . + }] ; # {} +} + +proc Example {} { + global currentEnv + if {![info exists currentEnv(exenv)]} { + SaveContext + set verb [NewExample] + RestoreContext + + # Remember verbatim mode in the base environment + set currentEnv(exenv) $verb + SaveEnv + } + return $currentEnv(exenv) +} + +proc NewList {what} { + # List environments + # Per list several environments are required. + + switch -exact -- $what { + enumerated {NewOrderedList} + itemized {NewUnorderedList} + arguments - + commands - + options - + tkoptions - + definitions {NewDefinitionList} + } +} + +proc NewUnorderedList {} { + global currentEnv lmarginIncrement + + # Itemized list - unordered list - bullet + # 1. Base environment provides indentation. + # 2. First paragraph in a list item. + # 3. All other paragraphs. + + set base [NewEnv Itemized { + incr currentEnv(lmargin) $lmarginIncrement + + set bullet [Bullet currentEnv(bulleting)] + }] ; # {} + set first [NewEnv First { + set currentEnv(wspfx) [::textutil::repeat::blank $lmarginIncrement] + set currentEnv(listtype) bullet + set currentEnv(bullet) $bullet + }] ; SetContext $base ; # {} + + set next [NewEnv Next { + incr currentEnv(lmargin) $lmarginIncrement + }] ; SetContext $base ; # {} + + set currentEnv(_first) $first + set currentEnv(_next) $next + set currentEnv(pcount) 0 + SaveEnv + return +} + +proc NewOrderedList {} { + global currentEnv lmarginIncrement + + # Ordered list - enumeration - enum + # 1. Base environment provides indentation. + # 2. First paragraph in a list item. + # 3. All other paragraphs. + + set base [NewEnv Enumerated { + incr currentEnv(lmargin) $lmarginIncrement + + set bullet [EnumBullet currentEnv(enumeration)] + }] ; # {} + set first [NewEnv First { + set currentEnv(wspfx) [::textutil::repeat::blank $lmarginIncrement] + set currentEnv(listtype) enum + set currentEnv(bullet) $bullet + }] ; SetContext $base ; # {} + + set next [NewEnv Next { + incr currentEnv(lmargin) $lmarginIncrement + }] ; SetContext $base ; # {} + + set currentEnv(_first) $first + set currentEnv(_next) $next + set currentEnv(pcount) 0 + SaveEnv + return +} + +proc NewDefinitionList {} { + global currentEnv lmarginIncrement + + # Definition list - terms & definitions + # 1. Base environment provides indentation. + # 2. Term environment + # 3. Definition environment + + set base [NewEnv DefL { + incr currentEnv(lmargin) $lmarginIncrement + }] ; # {} + set term [NewEnv Term { + set currentEnv(verbatim) 1 + }] ; SetContext $base ; # {} + + set def [NewEnv Def { + incr currentEnv(lmargin) $lmarginIncrement + }] ; SetContext $base ; # {} + + set currentEnv(_term) $term + set currentEnv(_definition) $def + SaveEnv + return +} + +################################################################ +# Final layouting. + +c_holdBuffers require + +proc fmt_postprocess {text} {text_postprocess $text} + + +################################################################ +# Implementations of the formatting commands. + +c_pass 1 fmt_plain_text {text} NOP +c_pass 2 fmt_plain_text {text} {text_plain_text $text} + +c_pass 1 fmt_manpage_begin {title section version} NOP +c_pass 2 fmt_manpage_begin {title section version} { + Off + set module [dt_module] + set shortdesc [c_get_module] + set description [c_get_title] + set copyright [c_get_copyright] + + set hdr [list] + lappend hdr "$title - $shortdesc" + lappend hdr [c_provenance] + lappend hdr "[string trimleft $title :]($section) $version $module \"$shortdesc\"" + set hdr [join $hdr \n] + + Text $hdr + CloseParagraph [Verbatim] + Section NAME + Text "$title - $description" + CloseParagraph + return +} + +c_pass 1 fmt_moddesc {desc} {c_set_module $desc} +c_pass 2 fmt_moddesc {desc} NOP + +c_pass 1 fmt_titledesc {desc} {c_set_title $desc} +c_pass 2 fmt_titledesc {desc} NOP + +c_pass 1 fmt_copyright {desc} {c_set_copyright $desc} +c_pass 2 fmt_copyright {desc} NOP + +c_pass 1 fmt_manpage_end {} NOP +c_pass 2 fmt_manpage_end {} { + set sa [c_xref_seealso] + set kw [c_xref_keywords] + set ca [c_xref_category] + set ct [c_get_copyright] + + CloseParagraph + if {[llength $sa] > 0} {Section {SEE ALSO} ; Text [join [lsort $sa] ", "] ; CloseParagraph} + if {[llength $kw] > 0} {Section KEYWORDS ; Text [join [lsort $kw] ", "] ; CloseParagraph} + if {$ca ne ""} {Section CATEGORY ; Text $ca ; CloseParagraph} + if {$ct != {}} {Section COPYRIGHT ; Text $ct ; CloseParagraph [Verbatim]} + return +} + +c_pass 1 fmt_section {name {id {}}} NOP +c_pass 2 fmt_section {name {id {}}} {CloseParagraph ; Section $name ; return} + +c_pass 1 fmt_subsection {name {id {}}} NOP +c_pass 2 fmt_subsection {name {id {}}} {CloseParagraph ; Subsection $name ; return} + +c_pass 1 fmt_para {} NOP +c_pass 2 fmt_para {} {CloseParagraph ; return} + +c_pass 2 fmt_require {pkg {version {}}} NOP +c_pass 1 fmt_require {pkg {version {}}} { + set result "package require $pkg" + if {$version != {}} {append result " $version"} + c_hold require $result + return +} + +c_pass 1 fmt_usage {cmd args} {c_hold synopsis "$cmd [join $args " "]"} +c_pass 2 fmt_usage {cmd args} NOP + +c_pass 1 fmt_call {cmd args} {c_hold synopsis "$cmd [join $args " "]"} +c_pass 2 fmt_call {cmd args} {fmt_lst_item "$cmd [join $args " "]"} + + +c_pass 1 fmt_description {id} NOP +c_pass 2 fmt_description {id} { + On + set syn [c_held synopsis] + set req [c_held require] + + if {$syn != {} || $req != {}} { + Section SYNOPSIS + if {($req != {}) && ($syn != {})} { + Text $req\n\n$syn + } else { + if {$req != {}} {Text $req} + if {$syn != {}} {Text $syn} + } + CloseParagraph [Verbatim] + } + + Section DESCRIPTION + return +} + +################################################################ + +c_pass 1 fmt_list_begin {what {hint {}}} NOP +c_pass 2 fmt_list_begin {what {hint {}}} { + #puts_stderr "<<fmt_list_begin $what>>" + + global currentEnv + if {[info exists currentEnv(_definition)]} { + CloseParagraph $currentEnv(_definition) + } elseif {[info exists currentEnv(pcount)]} { + if {$currentEnv(pcount) == 0} {CloseParagraph $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {CloseParagraph $currentEnv(_next)} + incr currentEnv(pcount) + } else { + CloseParagraph + } + SaveContext + NewList $what + Off + + #puts_stderr "<<fmt_list_begin _____>>" + return +} + +c_pass 1 fmt_list_end {} NOP +c_pass 2 fmt_list_end {} { + #puts_stderr "<<fmt_list_end>>" + + global currentEnv + if {[info exists currentEnv(_definition)]} { + CloseParagraph $currentEnv(_definition) + } else { + if {$currentEnv(pcount) == 0} {CloseParagraph $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {CloseParagraph $currentEnv(_next)} + } + RestoreContext + + #puts_stderr "<<fmt_list_end ____>>" + return +} + +c_pass 1 fmt_lst_item {text} NOP +c_pass 2 fmt_lst_item {text} { + global currentEnv + + #puts_stderr "<<fmt_lst_item \{$text\}>>" + + if {[IsOff]} { + On + } else { + CloseParagraph $currentEnv(_definition) + } + Text $text + CloseParagraph $currentEnv(_term) + + #puts_stderr "<<fmt_lst_item _____>>" + return +} + +c_pass 1 fmt_bullet {} NOP +c_pass 2 fmt_bullet {} { + global currentEnv + if {[IsOff]} {On ; return} + if {$currentEnv(pcount) == 0} {CloseParagraph $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {CloseParagraph $currentEnv(_next)} + set currentEnv(pcount) 0 + return +} + +c_pass 1 fmt_enum {} NOP +c_pass 2 fmt_enum {} { + global currentEnv + if {[IsOff]} {On ; return} + if {$currentEnv(pcount) == 0} {CloseParagraph $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {CloseParagraph $currentEnv(_next)} + set currentEnv(pcount) 0 + return +} + +c_pass 1 fmt_cmd_def {command} NOP +c_pass 2 fmt_cmd_def {command} {fmt_lst_item [fmt_cmd $command]} + +c_pass 1 fmt_arg_def {type name {mode {}}} NOP +c_pass 2 fmt_arg_def {type name {mode {}}} { + set text "$type [fmt_arg $name]" + if {$mode != {}} {append text " ($mode)"} + fmt_lst_item $text + return +} + +c_pass 1 fmt_opt_def {name {arg {}}} NOP +c_pass 2 fmt_opt_def {name {arg {}}} { + set text [fmt_option $name] + if {$arg != {}} {append text " $arg"} + fmt_lst_item $text + return +} + +c_pass 1 fmt_tkoption_def {name dbname dbclass} NOP +c_pass 2 fmt_tkoption_def {name dbname dbclass} { + set text "" + append text "Command-Line Switch:\t[fmt_option $name]\n" + append text "Database Name:\t[strong $dbname]\n" + append text "Database Class:\t[strong $dbclass]\n" + fmt_lst_item $text +} + +################################################################ + +c_pass 1 fmt_example_begin {} NOP +c_pass 2 fmt_example_begin {} { + global currentEnv para + if {[info exists currentEnv(_definition)]} { + CloseParagraph $currentEnv(_definition) + } elseif {[info exists currentEnv(pcount)]} { + if {$para != {}} { + if {$currentEnv(pcount) == 0} {CloseParagraph $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {CloseParagraph $currentEnv(_next)} + incr currentEnv(pcount) + } + } else { + CloseParagraph + } + return +} + +c_pass 1 fmt_example_end {} NOP +c_pass 2 fmt_example_end {} { + global currentEnv para + set penv {} + if {[info exists currentEnv(_definition)]} { + set penv $currentEnv(_definition) + } elseif {[info exists currentEnv(pcount)]} { + if {$currentEnv(pcount) == 0} {set penv $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {set penv $currentEnv(_next)} + incr currentEnv(pcount) + } + if {$penv != {}} { + # Save current list context, get chosen paragraph context and + # then create an example context form this. After closing the + # paragraph we get back our main list context. + + SaveContext + SetContext $penv + CloseParagraph [Example] + RestoreContext + } else { + CloseParagraph [Example] + } + return +} + +c_pass 1 fmt_example {code} NOP +c_pass 2 fmt_example {code} { + fmt_example_begin + fmt_plain_text $code + fmt_example_end + return +} + +c_pass 1 fmt_nl {} NOP +c_pass 2 fmt_nl {} { + global currentEnv + if {[info exists currentEnv(_definition)]} { + CloseParagraph $currentEnv(_definition) + } else { + if {$currentEnv(pcount) == 0} {CloseParagraph $currentEnv(_first)} + if {$currentEnv(pcount) > 0} {CloseParagraph $currentEnv(_next)} + incr currentEnv(pcount) + } + return +} + +################################################################ +# Visual markup of words and phrases. + +proc fmt_arg {text} {return $text} +proc fmt_cmd {text} {return $text} +proc fmt_emph {text} {em $text } +proc fmt_opt {text} {return "?$text?" } +proc fmt_comment {text} {return} +proc fmt_sectref {text {label {}}} { + if {![string length $label]} {set label $text} + return "-> $text" +} +proc fmt_syscmd {text} {strong $text} +proc fmt_method {text} {return $text} +proc fmt_option {text} {return $text} +proc fmt_widget {text} {strong $text} +proc fmt_fun {text} {strong $text} +proc fmt_type {text} {strong $text} +proc fmt_package {text} {strong $text} +proc fmt_class {text} {strong $text} +proc fmt_var {text} {strong $text} +proc fmt_file {text} {return "\"$text\""} +proc fmt_namespace {text} {strong $text} +proc fmt_uri {text {label {}}} { + if {$label == {}} { + # Without label we use the link directly as part of the text. + return "<URL:$text>" + } else { + return "[em $label] <URL:$text>" + } +} +proc fmt_image {text {label {}}} { + # text = symbolic name of the image. + + set img [dt_imgdata $text {txt}] + if {$img eq {}} { + if {$label eq {}} { + return "IMAGE: $text" + } else { + return "IMAGE: $text $label" + } + } + + return $img +} +proc fmt_term {text} {em $text} +proc fmt_const {text} {strong $text} +proc fmt_mdash {} { return " --- " } +proc fmt_ndash {} { return " -- " } + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fmt.tmml b/tcllib/modules/doctools/mpformats/fmt.tmml new file mode 100644 index 0000000..522f7c3 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.tmml @@ -0,0 +1,288 @@ +# -*- tcl -*- +# +# $Id: fmt.tmml,v 1.27 2010/07/06 18:49:15 andreas_kupries Exp $ +# +# [expand] definitions to convert a tcl based manpage definition +# into TMML. +# +# Copyright (C) 2001 Joe English <jenglish@sourceforge.net>. +# Freely redistributable. +# +# See also <URL: http://tmml.sourceforge.net> +# +# BUGS: +# + Text must be preceded by [para] or one of the +# list item macros, or else the output will be invalid. +# +###################################################################### + +dt_source _common.tcl +dt_source _xml.tcl + +###################################################################### +# Conversion specification. +# +# Two-pass processing. The first pass collects text for the +# SYNOPSIS, SEE ALSO, and KEYWORDS sections, and the second pass +# produces output. +# + +c_holdBuffers synopsis see_also keywords + +variable block {section dd li desc} ;# block context elements + +proc fmt_nl {} { emptyElement br } +proc fmt_arg {text} { wrap $text m } +proc fmt_cmd {text} { wrap $text cmd } +proc fmt_emph {text} { wrap $text emph } +proc fmt_opt {text} { wrap $text o } + +c_pass 1 fmt_example_begin {} NOP +c_pass 1 fmt_example_end {} NOP +c_pass 1 fmt_example {code} NOP +c_pass 2 fmt_example_begin {} { sequence [xmlContext $::block] [start example] } +c_pass 2 fmt_example_end {} { end example } +c_pass 2 fmt_example {code} { sequence [xmlContext $::block] [wrap $code example] } + +proc fmt_comment {text} {xmlComment $text} +proc fmt_sectref {text {id {}}} { + global SectionNames + if {$id == {}} { + set id [c_sectionId $text] + } + if {[info exists SectionNames($id)]} { + return "[startTag ref refid $id]$text[endTag ref]" + } else { + return [wrap $text emph] + } +} +proc fmt_syscmd {text} {wrap $text syscmd} +proc fmt_method {text} {wrap $text method} +proc fmt_option {text} {wrap $text option} +proc fmt_widget {text} {wrap $text widget} +proc fmt_fun {text} {wrap $text fun} +proc fmt_type {text} {wrap $text type} +proc fmt_package {text} {wrap $text package} +proc fmt_class {text} {wrap $text class} +proc fmt_var {text} {wrap $text variable} +proc fmt_file {text} {wrap $text file} +proc fmt_namespace {text} {wrap $text term} +proc fmt_uri {text {label {}}} { + # TMML ignores the label + wrap $text url +} +proc fmt_term {text} {wrap $text term} +proc fmt_const {text} {wrap $text l} + +proc fmt_mdash {} { return "[markup &]mdash;" } +proc fmt_ndash {} { return "[markup &]ndash;" } + + +c_pass 1 fmt_manpage_begin {args} NOP +c_pass 2 fmt_manpage_begin {title section version} { + set headInfo [list] + foreach copyrightLine [split [c_get_copyright] "\n"] { + lappend headInfo [emptyElement info key copyright value $copyrightLine] + } + # ... other metadata here if needed ... + + sequence \ + [xmlComment [c_provenance]] \ + [start manpage \ + id [dt_fileid] \ + cat cmd \ + title $title \ + version $version \ + package [dt_module]] \ + [wrapLines? [join $headInfo \n] head] \ + [start namesection] \ + [wrap $title name] \ + [wrap [c_get_title] desc] \ + [end namesection] \ + ; +} + +c_pass 1 fmt_moddesc {desc} {c_set_module $desc} +c_pass 1 fmt_titledesc {desc} {c_set_title $desc} +c_pass 1 fmt_copyright {desc} {c_set_copyright $desc} + +c_pass 2 fmt_moddesc {args} NOP +c_pass 2 fmt_titledesc {args} NOP +c_pass 2 fmt_copyright {desc} NOP + +c_pass 1 fmt_description {id} NOP +c_pass 2 fmt_description {id} { + sequence \ + [xmlContext manpage] \ + [wrapLines? [c_held synopsis] syntax synopsis] \ + [start section id $id] \ + [wrap "DESCRIPTION" title] \ + ; +} + +c_pass 1 fmt_section {name {id {}}} {c_newSection $name 1 end $id} +c_pass 2 fmt_section {name {id {}}} { + if {$id == {}} { set id [c_sectionId $name] } + sequence \ + [xmlContext manpage] \ + [start section id $id] \ + [wrap [string toupper $name] title] \ + ; +} + +c_pass 1 fmt_subsection {name {id {}}} {c_newSection $name 2 end $id} +c_pass 2 fmt_subsection {name {id {}}} { + if {$id == {}} { set id [c_sectionId $name] } + sequence \ + [xmlContext section] \ + [start subsection id $id] \ + [wrap [string toupper $name] title] \ + ; +} + +c_pass 1 fmt_para {} NOP +c_pass 2 fmt_para {} { sequence [xmlContext section] [start p] } + +foreach {type gi} { + itemized ul + enumerated ol + definitions dl + arguments arglist + commands commandlist + options optlist + tkoptions optionlist +} { + set listTypes($type) $gi + lappend listGIs $gi +} + +c_pass 1 fmt_list_begin {what {hint {}}} NOP +c_pass 1 fmt_list_end {} NOP +c_pass 2 fmt_list_begin {what {hint {}}} { + variable listTypes + sequence \ + [xmlContext $::block] \ + [start $listTypes($what)] \ + ; +} +c_pass 2 fmt_list_end {} { + variable listGIs + sequence \ + [xmlContext $listGIs] \ + [end] \ + ; +} + +c_pass 1 fmt_bullet {} NOP +c_pass 1 fmt_enum {} NOP +c_pass 2 fmt_bullet {} { sequence [xmlContext {ul ol}] [start li] } +c_pass 2 fmt_enum {} { sequence [xmlContext {ul ol}] [start li] } + +c_pass 1 fmt_lst_item {text} NOP +c_pass 2 fmt_lst_item {text} { + sequence \ + [xmlContext dl] \ + [start dle] \ + [wrap $text dt] \ + [start dd] \ + ; +} + +c_pass 1 fmt_arg_def {type name {mode {}}} NOP +c_pass 2 fmt_arg_def {type name {mode {}}} { + sequence \ + [xmlContext arglist] \ + [start argdef] \ + [wrap $type argtype] \ + [wrap $name name] \ + [wrap? $mode argmode] \ + [start desc] \ + ; +} + +c_pass 1 fmt_cmd_def {command} NOP +c_pass 2 fmt_cmd_def {command} { + sequence \ + [xmlContext commandlist] \ + [start commanddef] \ + [wrap $command command] \ + [start desc] \ + ; +} + +c_pass 1 fmt_opt_def {name {arg {}}} NOP +c_pass 2 fmt_opt_def {name {arg {}}} { + sequence \ + [xmlContext optlist] \ + [start optdef] \ + [wrap $name optname] \ + [wrap? $arg optarg] \ + [start desc] \ + ; +} + +c_pass 1 fmt_tkoption_def {name dbname dbclass} NOP +c_pass 2 fmt_tkoption_def {name dbname dbclass} { + sequence \ + [xmlContext optionlist] \ + [start optiondef] \ + [wrap $name name] \ + [wrap $dbname dbname] \ + [wrap $dbclass dbclass] \ + [start desc] \ + ; +} + +c_pass 1 fmt_usage {cmd args} { c_hold synopsis [formatCall $cmd $args] } +c_pass 2 fmt_usage {cmd args} NOP + +c_pass 1 fmt_call {cmd args} { c_hold synopsis [formatCall $cmd $args] } +c_pass 2 fmt_call {cmd args} { + sequence \ + [xmlContext dl] \ + [start dle] \ + [wrap [formatCall $cmd $args] dt] \ + [start dd] \ + ; +} +proc formatCall {cmd arglist} { + return "$cmd [join $arglist { }]" ;# OR: wrap "..." command +} + +c_pass 1 fmt_require {pkg {version {}}} { + c_hold synopsis [formatRequire $pkg $version] +} +c_pass 2 fmt_require {pkg {version {}}} NOP +proc formatRequire {pkg version} { + return "package require [wrap $pkg package] $version" +} + +# Note: TMML apparently has no support for category data inside of the document. + +c_pass 1 fmt_see_also {args} { holdWrapped see_also $args ref } +c_pass 1 fmt_keywords {args} { holdWrapped keywords $args keyword } +c_pass 1 fmt_category {args} NOP +c_pass 2 fmt_see_also {args} NOP +c_pass 2 fmt_keywords {args} NOP +c_pass 2 fmt_category {args} NOP + +# holdWrapped -- +# Common factor of [see_also] and [keywords]. +# +proc holdWrapped {buffer arglist gi} { + foreach arg $arglist { c_hold $buffer [wrap $arg $gi] } + return +} + +c_pass 1 fmt_manpage_end {} NOP +c_pass 2 fmt_manpage_end {} { + sequence \ + [xmlContext manpage] \ + [wrapLines? [c_held see_also] seealso] \ + [wrapLines? [c_held keywords] keywords] \ + [end manpage] \ + ; +} + +#*EOF* + diff --git a/tcllib/modules/doctools/mpformats/fmt.wiki b/tcllib/modules/doctools/mpformats/fmt.wiki new file mode 100644 index 0000000..ff663fa --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fmt.wiki @@ -0,0 +1,297 @@ +# -*- tcl -*- +# +# fmt.nroff +# +# (c) 2002 Andreas Kupries <andreas_kupries@sourceforge.net> +# +# [expand] definitions to convert a tcl based manpage definition into +# Wiki markup. +# +################################################################ + +dt_source _common.tcl ; # Shared code + +proc fmt_postprocess {wiki} { + # Strip empty lines out of the generated wiki source + # and trim leading blanks, except in code samples. + # + set lines [list] + set codeblock 0 + foreach line [split $wiki \n] { + if {![string compare $line "======"]} { + set codeblock [expr {!$codeblock}] + lappend lines $line + continue + } + if {$codeblock} { + lappend lines $line + } else { + if {[string match " |*" $line]} { + # Verbatim / example + lappend lines [string trimright $line] + } elseif {[string match ". *" $line]} { + # Verbatim / regular + lappend lines [string range [string trimright $line] 1 end] + } elseif {[regexp {^ \* .*} $line]} { + # Itemized lists. + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[string match " 1. *" $line]} { + # Enumerated lists + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[regexp "^ .*: " $line]} { + # Definition list + lappend lines [string map {[ [[ ] ]]} $line] + } elseif {[string match " *" $line]} { + # Unwanted indentation + lappend lines [string map {[ [[ ] ]]} [string trim $line]] + } else { + # Everything else + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } + } + } + set wiki [join $lines \n]\n + + regsub {^[ ]+} $wiki {} wiki + return $wiki +} + + +################################################################ +## Backend for *roff markup + +c_pass 1 fmt_manpage_begin {title section version} NOP +c_pass 2 fmt_manpage_begin {title section version} { + set module [dt_module] + set shortdesc [c_get_module] + set description [c_get_title] + + set hdr "" + append hdr "'''$title $version'''" + if {[string length $module]} { + append hdr " '''$module'''" + } + if {[string length $shortdesc]} { + append hdr " ''$shortdesc''" + } + append hdr \n + append hdr \n + append hdr "$description" + append hdr \n + return $hdr +} + +c_pass 1 fmt_moddesc {desc} {c_set_module $desc} +c_pass 2 fmt_moddesc {desc} NOP + +c_pass 1 fmt_titledesc {desc} {c_set_title $desc} +c_pass 2 fmt_titledesc {desc} NOP + +c_pass 1 fmt_copyright {desc} {c_set_copyright $desc} +c_pass 2 fmt_copyright {desc} NOP + +c_pass 1 fmt_manpage_end {} NOP +c_pass 2 fmt_manpage_end {} { + # Complete the generation with a copyright + # section, if such information is available. + + set wiki "" + + set sa [c_xref_seealso] + set kw [c_xref_keywords] + set ca [c_xref_category] + set ct [c_get_copyright] + + if {[llength $sa] > 0} { + append wiki [fmt_section {SEE ALSO}] \n + append wiki [join [lsort $sa] ", "] \n + } + if {[llength $kw] > 0} { + append wiki [fmt_section KEYWORDS] \n + append wiki [join [lsort $kw] ", "] \n + } + if {$ca ne ""} { + append wiki [fmt_section CATEGORY] \n + append wiki $ca \n + } + if {$ct != {}} { + append wiki [fmt_section COPYRIGHT] + append wiki ". " [join [split $ct \n] "\n. "] \n + } + return $wiki +} + +proc fmt_section {name {id {}}} {return "\n\n**$name**\n\n"} +proc fmt_subsection {name {id {}}} {return "\n\n***$name***\n\n"} + +proc fmt_para {} {return \n} + +c_pass 2 fmt_require {pkg {version {}}} NOP +c_pass 1 fmt_require {pkg {version {}}} { + if {$version != {}} {set version " $version"} + # @mdgen NODEP: ''' + c_hold synopsis "package require '''$pkg$version'''\n" +} + +c_pass 2 fmt_usage {cmd args} NOP +c_pass 1 fmt_usage {cmd args} {c_hold synopsis " * $cmd [join $args " "]\n"} + +c_pass 2 fmt_call {cmd args} {return "[fmt_lst_item "$cmd [join $args " "]"]"} +c_pass 1 fmt_call {cmd args} {c_hold synopsis " * $cmd [join $args " "]\n"} + +c_pass 1 fmt_description {id} NOP +c_pass 2 fmt_description {id} { + set result "" + if {[set syn [c_held synopsis]] != {}} { + append result [fmt_section SYNOPSIS] \n + append result $syn \n\n + } + append result [fmt_section DESCRIPTION] + return $result +} + +################################################################ +global arglist +set ::arglist 0 +proc fmt_list_begin {what {hint {}}} { + switch -exact -- $what { + "arguments" { + set ::arglist 1 + return "\n\n+++" + } + default { + return {} + } + } +} +proc fmt_list_end {} { + if {$::arglist} { + set ::arglist 0 + return "\n+++\n\n" + } + return {} +} + +proc fmt_bullet {} {return "\n\n * "} +proc fmt_enum {} {return "\n\n 1. "} +proc fmt_lst_item {text} {return "\n\n $text: "} +proc fmt_cmd_def {command} {return "\n\n [fmt_cmd $command]: "} + +proc fmt_arg_def {type name {mode {}}} { + set text "\n" + append text [fmt_arg $name] + append text " $type" + if {$mode != {}} {append text " ($mode)"} + return "${text} " +} +proc fmt_opt_def {name {arg {}}} { +# if {[string match -* $name]} {set name \\-$name} + set name [fmt_option $name] + if {$arg != {}} {append name " $arg"} + return "\n\n ${name}: " +} +proc fmt_tkoption_def {name dbname dbclass} { + set text "\n\n" + append text " Command-Line Switch:\t'''$name'''\n" + append text " Database Name:\t'''$dbname'''\n" + append text " Database Class:\t'''$dbclass'''\n" + append text " * " + return $text +} + +################################################################ + +global textmode +set textmode "" + +proc fmt_example_begin {} { + global mode_save textmode + lappend mode_save $textmode + set textmode example + return "\n======\n" +} +proc fmt_example_end {} { + global mode_save textmode + set textmode [lindex $mode_save end] + set mode_save [lrange $mode_save 0 end-1] + return "\n======\n" +} +proc fmt_example {code} { + return "$code" +} + +proc emph {text} {return ''$text''} +proc strong {text} {return '''$text'''} + +proc fmt_nl {} {return ""} +proc fmt_arg {text} {return ''$text''} +proc fmt_cmd {text} {return '''$text'''} +proc fmt_emph {text} {return ''$text''} +proc fmt_opt {text} {return ?$text?} +proc fmt_comment {text} {return {}} +proc fmt_sectref {text {label {}}} { + if {![string length $label]} {set label $text} + strong $text +} +proc fmt_syscmd {text} {strong $text} +proc fmt_method {text} {strong $text} +proc fmt_option {text} {strong $text} +proc fmt_widget {text} {strong $text} +proc fmt_fun {text} {strong $text} +proc fmt_type {text} {strong $text} +proc fmt_package {text} {strong $text} +proc fmt_class {text} {strong $text} +proc fmt_var {text} {strong $text} +proc fmt_file {text} {return "\"[emph $text]\""} +proc fmt_namespace {text} {strong $text} +proc fmt_uri {text {label {}}} { + if {$label == {}} { + # No label is an inlined emphasized link. + return $text + } else { + # Label in the text, link for it is hidden in an annotation. + return "$text%|%$label%|%" + } +} +proc fmt_image {text {label {}}} { + # text = symbolic name of the image. + + # Alt: png, jpg, gif, which are then used during HTML + # conversion. But unclear what the link is, to use for this. So, + # keeping as text for the moment. + + set img [dt_imgdata $text {txt}] + if {$img eq {}} { + if {$label eq {}} { + return "IMAGE: $text" + } else { + return "IMAGE: $text $label" + } + } + + return \n======\n$img\n======\n +} +proc fmt_term {text} {emph $text} +proc fmt_const {text} {strong $text} +proc fmt_mdash {} { return " --- " } +proc fmt_ndash {} { return " -- " } + +################################################################ +# wiki specific commands + +proc fmt_plain_text {text} { + # For the wiki we have to force certain text into a single line. + # We also have to make sure that the text is on the same line as + # the initiator (i.e. list bullet). + + global textmode + + if {"$textmode" == "example"} { + return "$text" + } + + regsub -all "\[ \t\n\]+" $text { } text + return $text +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/fr.msg b/tcllib/modules/doctools/mpformats/fr.msg new file mode 100755 index 0000000..e418e86 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/fr.msg @@ -0,0 +1,34 @@ +# -*- tcl -*- +package require msgcat +namespace import ::msgcat::* + +mcset fr end/open/list "Fin de la page de manuel atteinte, \[list_end\] manquant" +mcset fr end/open/example "Fin de la page de manuel atteinte, \[example_end\] manquant" +mcset fr end/open/mp "Fin de la page de manuel atteinte, \[manpage_end\] manquant" +mcset fr mpbegin "Cette commande doit \xEAtre la premi\xE8re de la page de manuel" +mcset fr mptitle "TODO: TRANSLATE: Spaces not allowed in manpage title" +mcset fr hdrcmd "Commande interdite \xE0 l'ext\xE9rieur de l'en-t\xEAte" +mcset fr bodycmd "Commande interdite \xE0 l'ext\xE9rieur du corps de la page de manuel" +mcset fr body "Le texte est interdit \xE0 l'ext\xE9rieur du corps de la page de manuel" +mcset fr reqcmd "Commande interdite \xE0 l'ext\xE9rieur de l'en-t\xEAte ou de la section de condition" +mcset fr invalidlist "Type de liste non valide \"@\"" +mcset fr nolistcmd "Commande interdite \xE0 l'int\xE9rieur d'une liste" +mcset fr nolisthdr "Commande interdite entre le d\xE9but d'une liste et son premier \xE9l\xE9ment" +mcset fr nolisttxt "Le texte est interdit entre le d\xE9but d'une liste et son premier \xE9l\xE9ment" +mcset fr listcmd "Commande interdite \xE0 l'ext\xE9rieur d'une liste" +mcset fr deflist "Commande restreinte \xE0 l'utilisation dans les listes de d\xE9finition" +mcset fr bulletlist "Commande restreinte \xE0 l'utilisation dans les listes d'\xE9l\xE9ments" +mcset fr enumlist "Commande restreinte \xE0 l'utilisation dans les listes num\xE9rot\xE9es" +mcset fr examplecmd "Commande autoris\xE9e uniquement pour fermer une section d'exemple" +mcset fr nodonecmd "Commande interdite apr\xE8s \[manpage_end\]" +mcset fr arg_list "Commande restreinte \xE0 l'utilisation dans les listes d'arguments" +mcset fr cmd_list "Commande restreinte \xE0 l'utilisation dans les listes de commandes" +mcset fr opt_list "Commande restreinte \xE0 l'utilisation dans les listes d'options" +mcset fr tkoption_list "Commande restreinte \xE0 l'utilisation dans les listes de tkoption" +mcset fr depr_strong "Commande obsol\xE8te \"%s\".\n\tConsultez l'aide s\xE9mantique correspondante ou \[emph\] \xE0 la place." +mcset fr depr_lstitem "Commande obsol\xE8te \"%s\".\n\tConsultez \[def\] \xE0 la place." +mcset fr depr_nl "Commande obsol\xE8te \"%s\".\n\tConsultez \[para\] \xE0 la place." +mcset fr depr_bullet "Commande obsol\xE8te \"%s\".\n\tConsultez \[item\] \xE0 la place." +mcset fr depr_ltype "<List type> obsol\xE8te \"%s\".\n\tConsultez \"%s\" \xE0 la place." +mcset fr sectambig "@@@ Translate @@@ (Sub)Section title \"%s\" causes ambiguous section references." +mcset fr missingsect "@@@ Translate @@@ Refered (Sub)Section \"%s\" is not known." diff --git a/tcllib/modules/doctools/mpformats/idx.html b/tcllib/modules/doctools/mpformats/idx.html new file mode 100644 index 0000000..1cd29e0 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/idx.html @@ -0,0 +1,314 @@ +## -*- tcl -*- +# ### ### ### ######### ######### ######### +## +# $Id: idx.html,v 1.8 2007/03/20 05:06:35 andreas_kupries Exp $ +# +# Index Formatting Engine : docidx --> HTML. +# Single-pass +# +# Copyright (c) 2003-2007 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. + +# ### ### ### ######### ######### ######### +## Requisites + +dt_source _idx_common.tcl +dt_source _html.tcl + +# ### ### ### ######### ######### ######### +## API implementation + +rename idx_postprocess {} +rename fmt_postprocess idx_postprocess + +proc fmt_plain_text {text} {return {}} + +proc fmt_index_begin {l t} { + global la ti + set la $l + set ti $t + return {} +} + +proc fmt_key {text} { + global key lk ch + set lk $text + set key($lk) {} + set ch([F $lk]) . + return {} +} + +proc fmt_manpage {f l} {Ref [dt_fmap $f] $l} +proc fmt_url {u l} {Ref $u $l} + +proc fmt_index_end {} { + LoadKwid + set lines {} + if {![Get raw]} { + BeginHeader ; Meta ; EndHeader + BeginBody + } + BodyHeader ; Title ; Navbar + BeginIndex ; Keys ; EndIndex + if {![Get raw]} { + EndBody + } + return [join $lines \n] +} + +# ### ### ### ######### ######### ######### +## Helper commands + +proc Ref {r l} { + global key lk + lappend key($lk) $r $l + return {} +} + +proc F {text} { + return [string toupper [string index $text 0]] +} + +proc LoadKwid {} { + global kwid + # Engine parameter - load predefined keyword anchors. + set ki [Get kwid] + if {![llength $ki]} return + array set kwid $ki + return +} + +proc BeginHeader {} { + global la ti + upvar 1 lines lines + lappend lines [markup <html>] + lappend lines [ht_comment [c_provenance]] + lappend lines [ht_comment "$la"] + lappend lines [markup <head>] + lappend lines "[markup <title>] $la [markup </title>]" + return +} + +proc Meta {} { + # Engine parameter - insert 'meta' + set meta [Get meta] + if {$meta == {}} return + upvar 1 lines lines + lappend lines [markup $meta] + return +} + +proc EndHeader {} { + upvar 1 lines lines + lappend lines [markup </head>] + return +} + +proc BeginBody {} { + upvar 1 lines lines + lappend lines [markup <body>] + return +} + +proc BodyHeader {} { + upvar 1 lines lines + # Engine parameter - insert 'header' + set header [Get header] + if {$header == {}} return + lappend map @TITLE@ [TheTitle] + set header [string map $map $header] + lappend lines [markup $header] + return +} + +proc TheTitle {} { + global la ti + set title ??? + if {($la != {}) && ($ti != {})} { + set title "$la -- $ti" + } elseif {$la != {}} { + set title $la + } elseif {$ti != {}} { + set title $ti + } + return $title +} + +proc Title {} { + upvar 1 lines lines + lappend lines "[markup <h3>] [TheTitle] [markup </h3>]" + return +} + +proc Navbar {} { + global ch cnt dot + upvar 1 lines lines + + set nav {} + foreach c [lsort -dict [array names ch]] { + set ref c[incr cnt] + set ch($c) $ref + lappend nav [ALink $ref $c] + } + + lappend lines [markup "<hr><div class=\"#doctools_idxnav\">"] + lappend lines [join $nav $dot] + lappend lines [markup </div>] + return +} + +proc BeginIndex {} { + upvar 1 lines lines + lappend lines [markup "<hr><table class=\"#doctools_idx\" width=\"100%\">"] + return +} + +proc Keys {} { + global key + upvar 1 lines lines + set lc {} + foreach k [lsort -dict [array names key]] { + set c [F $k] ; if {$lc != $c} { Section $c ; set lc $c } + BeginKey $k + References $k + EndKey + } + return +} + +proc Section {c} { + global ch + upvar 1 lines lines + lappend lines [markup {<tr class="#doctools_idxheader"><th colspan="2">}] + lappend lines [markup "<a name=\"$ch($c)\">Keywords: $c</a>"] + lappend lines [markup </th></tr>] + return +} + +proc BeginKey {k} { + upvar 1 lines lines + lappend lines [markup "<tr class=\"[Row]\" valign=top>"] + lappend lines [BeginColLeft][SetAnchor $k][markup </td>] + lappend lines [BeginColRight] + return +} + +proc EndKey {} { + upvar 1 lines lines + lappend lines [markup </td></tr>] + return +} + +proc References {k} { + global key dot + upvar 1 lines lines + set refs {} + foreach {ref label} $key($k) { + lappend refs [markup "<a href=\"$ref\"> $label </a>"] + } + lappend lines [join $refs $dot] + return +} + +proc EndIndex {} { + upvar 1 lines lines + lappend lines [markup </table>] + # Engine parameter - insert 'footer' + set footer [Get footer] + if {$footer == {}} return + lappend lines [markup "<hr>"] + lappend lines [markup $footer] + return +} + +proc EndBody {} { + upvar 1 lines lines + lappend lines [markup "</body></html>"] + return +} + +proc ALink {dst label} { + markup "<a href=\"#$dst\"> $label </a>" +} + +proc BeginColLeft {} { + return [markup {<td class="#doctools_idxleft" width="35%">}] +} + +proc BeginColRight {} { + return [markup {<td class="#doctools_idxright" width="65%">}] +} + +proc SetAnchor {text} { + return [markup "<a name=[Anchor $text]> $text </a>"] +} + +proc Anchor {text} { + global kwid cnt + if {[info exists kwid($text)]} { + return "\"$kwid($text)\"" + } + set anchor key$cnt + incr cnt + return "\"$anchor\"" +} + +proc Row {} { + global even + set res [expr {$even + ? "\#doctools_idxeven" + : "\#doctools_idxodd"}] + Flip + return $res +} + +proc Flip {} { + global even + set even [expr {1-$even}] + return +} + +# ### ### ### ######### ######### ######### +## Engine state + +# key : string -> dict(ref -> label) "key formatting" +# ch : string -> '.' "key starting characters" +# lk : string "last key" +# la : string "index label" +# ti : string "index title" +# cnt : int +# kwid : string -> ... +# even : bool + +global key ; array set key {} +global ch ; array set ch {} +global lk ; set lk {} +global la ; set la {} +global ti ; set ti {} +global cnt ; set cnt 0 +global kwid ; array set kwid {} +global even ; set even 1 +global dot ; set dot [markup { · }] + +# ### ### ### ######### ######### ######### +## Engine parameters + +global __var +array set __var { + meta {} + header {} + footer {} + kwid {} + raw 0 +} +proc Get {varname} {global __var ; return $__var($varname)} +proc idx_listvariables {} {global __var ; return [array names __var]} +proc idx_varset {varname text} { + global __var + if {![info exists __var($varname)]} {return -code error "Unknown engine variable \"$varname\""} + set __var($varname) $text + return +} + +## +# ### ### ### ######### ######### ######### diff --git a/tcllib/modules/doctools/mpformats/idx.nroff b/tcllib/modules/doctools/mpformats/idx.nroff new file mode 100644 index 0000000..5499310 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/idx.nroff @@ -0,0 +1,81 @@ +# -*- tcl -*- +# +# $Id: idx.nroff,v 1.7 2009/01/30 04:56:47 andreas_kupries Exp $ +# +# Engine to convert a docidx document into nroff. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _idx_common.tcl +dt_source _nroff.tcl + +###################################################################### +# Conversion specification. +# +# One-pass processing. + +proc idx_postprocess {nroff} { + # Postprocessing after generation ... + # Strip empty lines out of the generated nroff source + # and trim leading blanks, except in code samples. + + set lines [list] + foreach line [split $nroff "\n"] { + set line [string trim $line] + if {0 == [string length $line]} { + continue + } + lappend lines $line + } + return [nroff_postprocess [join $lines \n]] +} + +#proc fmt_plain_text {text} {if {$text != {}} {return \n} else {return {}}} +proc fmt_plain_text {text} {return {}} + +################################################################ +## Backend for NROFF markup + +global prec ok haskey +set prec "" +set ok 0 +set haskey 0 + +proc fmt_index_begin {label title} { + global prec ok + set ok 1 + set hdr [nr_comment {}]\n + if {$prec != {}} { + set hdr [nr_comment $prec]\n + } + append hdr [nr_comment [c_provenance]]\n + append hdr [nr_title "\"[string trimleft $label :]\" n"]\n + append hdr [nr_read man.macros]\n + append hdr [nr_bolds]\n + append hdr [nr_section INDEX]\n + append hdr $title[nr_in]\n + return $hdr +} +proc fmt_index_end {} {return [nr_out]} +proc fmt_key {text} { + global haskey + set res "" + if {$haskey} {append res [nr_out]\n} + append res $text[nr_in]\n + set haskey 1 + return $res +} +proc fmt_manpage {file label} {return [nr_blt [nr_bld]$file[nr_rst]]\n$label\n} +proc fmt_url {url label} {return [nr_blt [nr_bld]$url[nr_rst]]\n$label\n} + +proc fmt_comment {text} { + global prec ok + if {$ok} {return [nr_comment $text]} + append prec $text \n + return {} +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/idx.null b/tcllib/modules/doctools/mpformats/idx.null new file mode 100644 index 0000000..d0704a6 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/idx.null @@ -0,0 +1,23 @@ +# -*- tcl -*- +# +# -- Null format (docidx) +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +# This is a null format which does return no output at all. + +################################################################ + +proc idx_initialize {} {return} +proc idx_shutdown {} {return} +proc idx_numpasses {} {return 1} +proc idx_postprocess {text} {return ""} +proc idx_setup {n} {return} + +foreach p { + index_begin index_end key manpage url comment plain_text +} { + proc fmt_$p {args} {return ""} +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/idx.text b/tcllib/modules/doctools/mpformats/idx.text new file mode 100644 index 0000000..35540d8 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/idx.text @@ -0,0 +1,79 @@ +# -*- tcl -*- +# +# $Id: idx.text,v 1.4 2010/06/08 19:32:36 andreas_kupries Exp $ +# +# Engine to convert a docidx document into plain text. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _idx_common.tcl +dt_source _text.tcl +proc c_copyrightsymbol {} {return "(c)"} + +###################################################################### +# Conversion specification. +# One-pass processing. + +rename idx_postprocess {} +rename text_postprocess idx_postprocess +proc fmt_plain_text {text} {return {}} + +################################################################ +## Backend for plain text markup + +global map ; array set map {} +global key ; set key {} +global max ; set max 0 + +proc fmt_index_begin {label title} { + TextInitialize + + global map ; unset map ; array set map {} + global key ; set key {} + global max ; set max 0 + + set hdr "" + append hdr "Index [textutil::string::uncap [c_provenance]]\n\n" + + if {($label != {}) && ($title != {})} { + set title "$label -- $title" + } elseif {$label != {}} { + set title $label + } elseif {$title != {}} { + # title is set + } + append hdr $title \n + append hdr [textutil::repeat::strRepeat = [string length $title]] + Text $hdr + CloseParagraph [Verbatim] + return +} +proc fmt_index_end {} { + global map max + + set break 0 + set rmargin [expr {80 - $max}] + if {$rmargin < 20} {set rmargin 20} + incr max + set pfx [textutil::repeat::blank $max] + + foreach key [lsort [array names map]] { + set opfx $key[string range $pfx [string length $key] end] + Text $opfx[textutil::adjust::indent [textutil::adjust::adjust [join $map($key) ", "] -length $rmargin] $pfx 1] + CloseParagraph [Verbatim] + } + return +} +proc fmt_key {text} { + global key max ; set key $text + if {[string length $text] > $max} {set max [string length $text]} + return +} +proc fmt_manpage {file label} {global map key ; lappend map($key) $file ; return} +proc fmt_url {url label} {global map key ; lappend map($key) $url ; return} +proc fmt_comment {text} {return} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/idx.wiki b/tcllib/modules/doctools/mpformats/idx.wiki new file mode 100644 index 0000000..8eee534 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/idx.wiki @@ -0,0 +1,63 @@ +# -*- tcl -*- +# +# $Id: idx.wiki,v 1.2 2004/01/15 06:36:12 andreas_kupries Exp $ +# +# Engine to convert a docidx document into Wiki markup. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _idx_common.tcl ; # Shared code + +###################################################################### + +proc idx_postprocess {wiki} { + # Strip empty lines out of the generated wiki source + # and trim leading blanks, except in code samples. + # + set lines [list] + foreach line [split $wiki \n] { + if {[string match " |*" $line]} { + # Verbatim / example + lappend lines [string trimright $line] + } elseif {[string match ". *" $line]} { + # Verbatim / regular + lappend lines [string range [string trimright $line] 1 end] + } elseif {[string match " \* *" $line]} { + # Itemized lists. + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[string match " 1. *" $line]} { + # Enumerated lists + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[regexp "^ (\[^:\]): " $line]} { + # Definition list + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[string match " *" $line]} { + # Unwanted indentation + lappend lines [string map {[ [[ ] ]]} [string trim $line]] + } else { + # Everything else + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } + } + set wiki [join $lines \n]\n + + regsub {^[ ]+} $wiki {} wiki + return $wiki +} + +proc fmt_plain_text {text} {return {}} + +################################################################ +## Backend for wiki markup + +proc fmt_index_begin {label title} {return "Index '''$label'''\n'''[string trim $title]'''\n"} +proc fmt_index_end {} {return {}} +proc fmt_key {text} {return "\n '''[string trim $text]''': "} +proc fmt_manpage {file label} {return "$file "} +proc fmt_url {url label} {return "$url "} +proc fmt_comment {text} {return {}} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/man.macros b/tcllib/modules/doctools/mpformats/man.macros new file mode 100644 index 0000000..ddd073d --- /dev/null +++ b/tcllib/modules/doctools/mpformats/man.macros @@ -0,0 +1,267 @@ +.\" The -*- nroff -*- definitions below are for supplemental macros used +.\" in Tcl/Tk manual entries. +.\" +.\" .AP type name in/out ?indent? +.\" Start paragraph describing an argument to a library procedure. +.\" type is type of argument (int, etc.), in/out is either "in", "out", +.\" or "in/out" to describe whether procedure reads or modifies arg, +.\" and indent is equivalent to second arg of .IP (shouldn't ever be +.\" needed; use .AS below instead) +.\" +.\" .AS ?type? ?name? +.\" Give maximum sizes of arguments for setting tab stops. Type and +.\" name are examples of largest possible arguments that will be passed +.\" to .AP later. If args are omitted, default tab stops are used. +.\" +.\" .BS +.\" Start box enclosure. From here until next .BE, everything will be +.\" enclosed in one large box. +.\" +.\" .BE +.\" End of box enclosure. +.\" +.\" .CS +.\" Begin code excerpt. +.\" +.\" .CE +.\" End code excerpt. +.\" +.\" .VS ?version? ?br? +.\" Begin vertical sidebar, for use in marking newly-changed parts +.\" of man pages. The first argument is ignored and used for recording +.\" the version when the .VS was added, so that the sidebars can be +.\" found and removed when they reach a certain age. If another argument +.\" is present, then a line break is forced before starting the sidebar. +.\" +.\" .VE +.\" End of vertical sidebar. +.\" +.\" .DS +.\" Begin an indented unfilled display. +.\" +.\" .DE +.\" End of indented unfilled display. +.\" +.\" .SO ?manpage? +.\" Start of list of standard options for a Tk widget. The manpage +.\" argument defines where to look up the standard options; if +.\" omitted, defaults to "options". The options follow on successive +.\" lines, in three columns separated by tabs. +.\" +.\" .SE +.\" End of list of standard options for a Tk widget. +.\" +.\" .OP cmdName dbName dbClass +.\" Start of description of a specific option. cmdName gives the +.\" option's name as specified in the class command, dbName gives +.\" the option's name in the option database, and dbClass gives +.\" the option's class in the option database. +.\" +.\" .UL arg1 arg2 +.\" Print arg1 underlined, then print arg2 normally. +.\" +.\" .QW arg1 ?arg2? +.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). +.\" +.\" .PQ arg1 ?arg2? +.\" Print an open parenthesis, arg1 in quotes, then arg2 normally +.\" (for trailing punctuation) and then a closing parenthesis. +.\" +.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +.\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +.\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +.\" # BS - start boxed text +.\" # ^y = starting y location +.\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +.\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +.\" # VS - start vertical sidebar +.\" # ^Y = starting y location +.\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +.\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +.\" # Special macro to handle page bottom: finish off current +.\" # box/sidebar if in box/sidebar mode, then invoked standard +.\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +.\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +.\" # DE - end display +.de DE +.fi +.RE +.sp +.. +.\" # SO - start of list of standard options +.de SO +'ie '\\$1'' .ds So \\fBoptions\\fR +'el .ds So \\fB\\$1\\fR +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 5.5c 11c +.ft B +.. +.\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\*(So manual entry for details on the standard options. +.. +.\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +.\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +.\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.\" # UL - underline word +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.\" # QW - apply quotation marks to word +.de QW +.ie '\\*(lq'"' ``\\$1''\\$2 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\$2 +.. +.\" # PQ - apply parens and quotation marks to word +.de PQ +.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 +.\"" fix emacs highlighting +.el (\\*(lq\\$1\\*(rq\\$2)\\$3 +.. +.\" # QR - quoted range +.de QR +.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 +.\"" fix emacs highlighting +.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 +.. +.\" # MT - "empty" string +.de MT +.QW "" +.. diff --git a/tcllib/modules/doctools/mpformats/toc.html b/tcllib/modules/doctools/mpformats/toc.html new file mode 100644 index 0000000..a2f5dfc --- /dev/null +++ b/tcllib/modules/doctools/mpformats/toc.html @@ -0,0 +1,129 @@ +# -*- tcl -*- +# +# $Id: toc.html,v 1.6 2005/09/28 04:51:19 andreas_kupries Exp $ +# +# Engine to convert a doctoc document into HTML. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _toc_common.tcl +dt_source _html.tcl + +###################################################################### +# Conversion specification. +# +# One-pass processing. + +rename toc_postprocess {} +rename fmt_postprocess toc_postprocess + +proc fmt_plain_text {text} {return {}} + +################################################################ +## Backend for TMML markup + +global firstitem ; set firstitem 1 +global maintable ; set maintable 1 +global even ; set even 1 + +proc fmt_toc_begin {label title} { + set hdr "" + if {![Get raw]} { + append hdr "[markup <html><head>]\n" + append hdr "[markup <title>] $label [markup </title>]\n" + + # Engine parameter - insert 'meta' + if {[set meta [Get meta]] != {}} {append hdr [markup $meta]\n} + + append hdr "[markup </head>]\n" + append hdr [ht_comment [c_provenance]]\n + append hdr [ht_comment "$label"]\n + append hdr \n + append hdr [markup <body>]\n + } + + # Engine parameter - insert 'header' + if {[set header [Get header]] != {}} { + lappend map @TITLE@ $label + set header [string map $map $header] + append hdr [markup $header]\n + } + + append hdr "[markup <h3>] $label [markup </h3>]\n" + append hdr "[markup <hr><dl><dt><h2>] $title [markup </h2><dd>]\n" + return $hdr +} +proc fmt_toc_end {} { + global maintable + set text "\n" + if {$maintable} {append text [tag/ table]\n} + + # Engine parameter - insert 'footer' + set footer [Get footer] + if {$footer != {}} {set footer \n[markup ${footer}]\n} + + append text [tag /dl][tag hr]${footer} + + if {![Get raw]} { + append text [tag/ body][tag/ html]\n + } + return $text +} +proc fmt_division_start {title symfile} { + global maintable ; set maintable 0 + + if {$symfile == ""} { + return \n[markup <dl><dt>]$title[markup <dd>] + } else { + return \n[markup <dl><dt>][markup "<a href=\"[dt_fmap $symfile]\">"]$title[markup </a><dd>] + } +} +proc fmt_division_end {} { + global firstitem ; set firstitem 1 + global even ; set even 1 + return [markup </table></dl>] +} +proc fmt_item {file label desc} { + global firstitem even + set text "" + + if {$firstitem} { + set firstitem 0 + append text \n[markup "<table class=\"#doctools_toc\">"]\n + } + + if {$even} { + append text [markup "<tr class=\"#doctools_toceven\" >"]\n + } else { + append text [markup "<tr class=\"#doctools_tocodd\" >"]\n + } + set even [expr {1-$even}] + append text [markup "<td class=\"#doctools_tocleft\" >"][markup "<a href=\"[dt_fmap $file]\">"]$label[tag/ a][tag/ td]\n + append text [markup "<td class=\"#doctools_tocright\">"]${desc}[tag /td]\n + append text [tag/ tr]\n + return $text +} +proc fmt_comment {text} {ht_comment $text} + +################################################################ + +global __var +array set __var { + meta {} + header {} + footer {} + raw 0 +} +proc Get {varname} {global __var ; return $__var($varname)} +proc toc_listvariables {} {global __var ; return [array names __var]} +proc toc_varset {varname text} { + global __var + if {![info exists __var($varname)]} {return -code error "Unknown engine variable \"$varname\""} + set __var($varname) $text + return +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/toc.nroff b/tcllib/modules/doctools/mpformats/toc.nroff new file mode 100644 index 0000000..8706e08 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/toc.nroff @@ -0,0 +1,73 @@ +# -*- tcl -*- +# +# $Id: toc.nroff,v 1.7 2009/01/30 04:56:47 andreas_kupries Exp $ +# +# Engine to convert a doctoc document into nroff. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _toc_common.tcl +dt_source _nroff.tcl + +###################################################################### +# Conversion specification. +# +# One-pass processing. + +proc toc_postprocess {nroff} { + # Postprocessing after generation ... + # Strip empty lines out of the generated nroff source + # and trim leading blanks, except in code samples. + + set lines [list] + foreach line [split $nroff "\n"] { + set line [string trim $line] + if {0 == [string length $line]} { + continue + } + lappend lines $line + } + return [nroff_postprocess [join $lines \n]] +} + +#proc fmt_plain_text {text} {if {$text != {}} {return \n} else {return {}}} +proc fmt_plain_text {text} {return {}} + +################################################################ +## Backend for TMML markup + +global prec ok +set prec "" +set ok 0 + +proc fmt_toc_begin {label title} { + global prec ok + set ok 1 + set hdr [nr_comment {}]\n + if {$prec != {}} { + set hdr [nr_comment $prec]\n + } + append hdr [nr_comment [c_provenance]]\n + append hdr [nr_title "\"[string trimleft $label :]\" n"]\n + append hdr [nr_read man.macros]\n + append hdr [nr_bolds]\n + append hdr [nr_section CONTENTS]\n + append hdr $title[nr_in]\n + return $hdr +} +proc fmt_toc_end {} {} +proc fmt_division_start {title symfile} {return $title[nr_in]\n} +proc fmt_division_end {} {return [nr_out]\n} +proc fmt_item {file label desc} {return "[nr_blt [nr_bld]$label[nr_rst]]\n[nr_ul]$file[nr_rst]: $desc\n"} + +proc fmt_comment {text} { + global prec ok + if {$ok} {return [nr_comment $text]} + append prec $text \n + return {} +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/toc.null b/tcllib/modules/doctools/mpformats/toc.null new file mode 100644 index 0000000..d85ada3 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/toc.null @@ -0,0 +1,23 @@ +# -*- tcl -*- +# +# -- Null format (doctoc) +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> + +# This is a null format which does return no output at all. + +################################################################ + +proc toc_initialize {} {return} +proc toc_shutdown {} {return} +proc toc_numpasses {} {return 1} +proc toc_postprocess {text} {return ""} +proc toc_setup {n} {return} + +foreach p { + toc_begin toc_end item division_start division_end comment plain_text +} { + proc fmt_$p {args} {return ""} +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/toc.text b/tcllib/modules/doctools/mpformats/toc.text new file mode 100644 index 0000000..7215550 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/toc.text @@ -0,0 +1,88 @@ +# -*- tcl -*- +# +# $Id: toc.text,v 1.8 2010/06/08 19:13:53 andreas_kupries Exp $ +# +# Engine to convert a doctoc document into plain text. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _toc_common.tcl +dt_source _text.tcl + +###################################################################### +# Conversion specification. +# One-pass processing. + +rename toc_postprocess {} +rename text_postprocess toc_postprocess + +proc fmt_plain_text {text} {return {}} + +################################################################ +## Backend for TMML markup + +global seclist ; set seclist {} +global max ; set max 0 + +proc fmt_comment {text} {return} +proc fmt_toc_end {} {return} +proc fmt_toc_begin {label title} { + TextInitialize + + set title "$label -- $title" + set hdr "" + append hdr "Table of contents [textutil::string::uncap [c_provenance]]\n" + append hdr \n + append hdr $title \n + append hdr [textutil::repeat::strRepeat = [string length $title]] + Text $hdr + CloseParagraph [Verbatim] +} +proc fmt_division_start {title symfile} { + global lmarginIncrement currentEnv + global seclist ; set seclist {} + global max ; set max 0 + + Text $title\n + Text [textutil::repeat::strRepeat - [string length $title]] + CloseParagraph [Verbatim] + SaveContext + NewEnv Division { + incr currentEnv(lmargin) $lmarginIncrement + } + return +} +proc fmt_division_end {} { + global seclist max + + if {[llength $seclist] > 0} { + set break 0 + incr max 2 + set rmargin [expr {80 - $max}] + if {$rmargin < 20} {set rmargin 20} + set pfx [textutil::blank $max] + incr max -1 + set fpfx "[textutil::repeat::strRepeat . $max] " + + foreach {file desc} $seclist { + set opfx "$file [string range $fpfx [string length $file] end]" + Text $opfx[textutil::adjust::indent [textutil::adjust::adjust $desc -length $rmargin] $pfx 1] + CloseParagraph [Verbatim] + } + set seclist {} + } + + RestoreContext + return +} +proc fmt_item {file label desc} { + global seclist max + lappend seclist $file $desc + if {[string length $file] > $max} {set max [string length $file]} + return +} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/toc.tmml b/tcllib/modules/doctools/mpformats/toc.tmml new file mode 100644 index 0000000..d0ec261 --- /dev/null +++ b/tcllib/modules/doctools/mpformats/toc.tmml @@ -0,0 +1,37 @@ +# -*- tcl -*- +# +# $Id: toc.tmml,v 1.6 2005/09/28 04:51:19 andreas_kupries Exp $ +# +# Engine to convert a doctoc document into TMML. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +# See also <URL: http://tmml.sourceforge.net> +# +###################################################################### + +dt_source _toc_common.tcl +dt_source _xml.tcl + +###################################################################### +# Conversion specification. +# +# One-pass processing. + +rename toc_postprocess {} +rename fmt_postprocess toc_postprocess + +proc fmt_plain_text {text} {if {$text != {}} {return \n} else {return {}}} + +################################################################ +## Backend for TMML markup + +proc fmt_toc_begin {label title} {sequence [start manual package $label] [wrap $title title]} +proc fmt_toc_end {} {end manual} +proc fmt_division_start {title symfile} {sequence [start division] [wrap $text title]} +proc fmt_division_end {} {end division} +proc fmt_item {file label desc} {emptyElement subdoc href [dt_fmap $file]} +proc fmt_comment {text} {xmlComment $text} + +################################################################ diff --git a/tcllib/modules/doctools/mpformats/toc.wiki b/tcllib/modules/doctools/mpformats/toc.wiki new file mode 100644 index 0000000..271285e --- /dev/null +++ b/tcllib/modules/doctools/mpformats/toc.wiki @@ -0,0 +1,63 @@ +# -*- tcl -*- +# +# $Id: toc.wiki,v 1.6 2005/09/28 04:51:19 andreas_kupries Exp $ +# +# Engine to convert a doctoc document into Wiki markup. +# +# Copyright (c) 2003 Andreas Kupries <andreas_kupries@sourceforge.net> +# Freely redistributable. +# +###################################################################### + +dt_source _toc_common.tcl ; # Shared code + +###################################################################### + +proc toc_postprocess {wiki} { + # Strip empty lines out of the generated wiki source + # and trim leading blanks, except in code samples. + # + set lines [list] + foreach line [split $wiki \n] { + if {[string match " |*" $line]} { + # Verbatim / example + lappend lines [string trimright $line] + } elseif {[string match ". *" $line]} { + # Verbatim / regular + lappend lines [string range [string trimright $line] 1 end] + } elseif {[string match " \* *" $line]} { + # Itemized lists. + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[string match " 1. *" $line]} { + # Enumerated lists + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[regexp "^ (\[^:\]): " $line]} { + # Definition list + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } elseif {[string match " *" $line]} { + # Unwanted indentation + lappend lines [string map {[ [[ ] ]]} [string trim $line]] + } else { + # Everything else + lappend lines [string map {[ [[ ] ]]} [string trimright $line]] + } + } + set wiki [join $lines \n]\n + + regsub {^[ ]+} $wiki {} wiki + return $wiki +} + +proc fmt_plain_text {text} {if {$text != {}} {return \n} else {return {}}} + +################################################################ +## Backend for wiki markup + +proc fmt_toc_begin {label title} {return "Table of Contents '''$label'''\n'''[string trim $title]'''"} +proc fmt_toc_end {} {return {}} +proc fmt_division_start {title symfile} {return '''[string trim $title]'''} +proc fmt_division_end {} {return {}} +proc fmt_item {file label desc} {return " \[$label\]: $file -- $desc"} +proc fmt_comment {text} {return {}} + +################################################################ diff --git a/tcllib/modules/doctools/pkgIndex.tcl b/tcllib/modules/doctools/pkgIndex.tcl new file mode 100644 index 0000000..eabd037 --- /dev/null +++ b/tcllib/modules/doctools/pkgIndex.tcl @@ -0,0 +1,6 @@ +if {![package vsatisfies [package provide Tcl] 8.2]} {return} +package ifneeded doctools 1.4.19 [list source [file join $dir doctools.tcl]] +package ifneeded doctools::toc 1.1.4 [list source [file join $dir doctoc.tcl]] +package ifneeded doctools::idx 1.0.5 [list source [file join $dir docidx.tcl]] +package ifneeded doctools::cvs 1 [list source [file join $dir cvs.tcl]] +package ifneeded doctools::changelog 1.1 [list source [file join $dir changelog.tcl]] diff --git a/tcllib/modules/doctools/tests/desc/00 b/tcllib/modules/doctools/tests/desc/00 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/00 diff --git a/tcllib/modules/doctools/tests/desc/01 b/tcllib/modules/doctools/tests/desc/01 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/01 diff --git a/tcllib/modules/doctools/tests/desc/02 b/tcllib/modules/doctools/tests/desc/02 new file mode 100644 index 0000000..e694867 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/02 @@ -0,0 +1,2 @@ +AAA ..THE_MODULE.. ..THE_TITLE.. +BBB ..THE_MODULE.. ..THE_TITLE..
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/desc/03 b/tcllib/modules/doctools/tests/desc/03 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/03 diff --git a/tcllib/modules/doctools/tests/desc/04 b/tcllib/modules/doctools/tests/desc/04 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/04 diff --git a/tcllib/modules/doctools/tests/desc/05 b/tcllib/modules/doctools/tests/desc/05 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/05 diff --git a/tcllib/modules/doctools/tests/desc/06 b/tcllib/modules/doctools/tests/desc/06 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/06 diff --git a/tcllib/modules/doctools/tests/desc/07 b/tcllib/modules/doctools/tests/desc/07 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/07 diff --git a/tcllib/modules/doctools/tests/desc/08 b/tcllib/modules/doctools/tests/desc/08 new file mode 100644 index 0000000..9414a5b --- /dev/null +++ b/tcllib/modules/doctools/tests/desc/08 @@ -0,0 +1,3 @@ +AAA ..THE_MODULE.. ..THE_TITLE.. +BBB ..THE_MODULE.. ..THE_TITLE.. +CCC ..THE_MODULE.. ..THE_TITLE..
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/html/00 b/tcllib/modules/doctools/tests/html/00 new file mode 100644 index 0000000..b442cba --- /dev/null +++ b/tcllib/modules/doctools/tests/html/00 @@ -0,0 +1,117 @@ +<html><head> +<title>TEST - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/01 b/tcllib/modules/doctools/tests/html/01 new file mode 100644 index 0000000..cf1b91a --- /dev/null +++ b/tcllib/modules/doctools/tests/html/01 @@ -0,0 +1,136 @@ +<html><head> +<title>TEST - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © **Copyright** + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +<p>Argument ::<i class="arg">Argument</i>:: +Class ::<b class="class">Class</b>:: +Command ::<b class="cmd">Command</b>:: +Comment :::: +Const ::<b class="const">Constant</b>:: +Emphasis ::<em>Emphasis</em>:: +File ::"<b class="file">File/Path</b>":: +Function ::<b class="function">Function</b>:: +Method ::<b class="method">Method</b>:: +Namespace ::<b class="namespace">Namespace</b>:: +Option ::<b class="option">Option</b>:: +Optional ::<span class="opt">?Optional?</span>:: +Package ::<b class="package">Package</b>:: +Syscmd ::<b class="syscmd">SystemCommand</b>:: +Term ::<i class="term">Term</i>:: +Type ::<b class="type">Type</b>:: +Uri ::<a href="Uri">Uri</a>:: +Variable ::<b class="variable">Variable</b>:: +Widget ::<b class="widget">Widget</b>::</p> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © **Copyright**</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/02 b/tcllib/modules/doctools/tests/html/02 new file mode 100644 index 0000000..6418e3a --- /dev/null +++ b/tcllib/modules/doctools/tests/html/02 @@ -0,0 +1,134 @@ +<html><head> +<title>TEST - ..THE_MODULE..</title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. "..THE_MODULE.."</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST - ..THE_TITLE..</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#see-also">See Also</a></li> +<li class="doctools_section"><a href="#keywords">Keywords</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> +<div class="doctools_synopsis"> +<ul class="doctools_requirements"> +<li>package require <b class="pkgname">AAA</b></li> +<li>package require <b class="pkgname">BBB VVV</b></li> +</ul> +</div> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +</div> +<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2> +<p>ELSE, OTHER</p> +</div> +<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2> +<p>KEYA, KEYZ</p> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/03 b/tcllib/modules/doctools/tests/html/03 new file mode 100644 index 0000000..65a2b0f --- /dev/null +++ b/tcllib/modules/doctools/tests/html/03 @@ -0,0 +1,142 @@ +<html><head> +<title>TEST - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#section2">AaA</a></li> +<li class="doctools_section"><a href="#section3">BbB</a> +<ul> +<li class="doctools_subsection"><a href="#subsection1">BbB.cCc</a></li> +<li class="doctools_subsection"><a href="#subsection2">BbB.dDd</a></li> +</ul> +</li> +<li class="doctools_section"><a href="#section4">EeE</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +</div> +<div id="section2" class="doctools_section"><h2><a name="section2">AaA</a></h2> +<p>1</p> +</div> +<div id="section3" class="doctools_section"><h2><a name="section3">BbB</a></h2> +<p>22</p> +<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">BbB.cCc</a></h3> +<p>333</p> +</div> +<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">BbB.dDd</a></h3> +<p>4444</p> +</div> +</div> +<div id="section4" class="doctools_section"><h2><a name="section4">EeE</a></h2> +<p>5555</p> +<p>At <span class="sectref"><a href="#section2">AaA</a></span>.</p> +<p>At <b class="sectref">__undefined__</b>.</p> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/04 b/tcllib/modules/doctools/tests/html/04 new file mode 100644 index 0000000..82fdcfc --- /dev/null +++ b/tcllib/modules/doctools/tests/html/04 @@ -0,0 +1,126 @@ +<html><head> +<title>TEST - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +<p>BEGINNE HIER</p> +<pre class="doctools_example"> + Example Block More Lines +</pre> +<pre class="doctools_example"> +Inlined Example \ +Next Line +</pre> +<p>FERTIG</p> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/05 b/tcllib/modules/doctools/tests/html/05 new file mode 100644 index 0000000..b46ba50 --- /dev/null +++ b/tcllib/modules/doctools/tests/html/05 @@ -0,0 +1,176 @@ + +<html><head> +<title>BASIC - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- BASIC.a + --> +<body><div class="doctools"> +<h1 class="doctools_title">BASIC(a) 5 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>BASIC -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> +<div class="doctools_synopsis"> +<ul class="doctools_syntax"> +<li><a href="#1">a-command</a></li> +</ul> +</div> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +<p>OK</p> +<dl class="doctools_arguments"> +<dt>integer <i class="arg">argument-1</i></dt> +<dd><p>verification</p></dd> +<dt>string <i class="arg">argument-2</i> (out)</dt> +<dd><p>mogrification</p></dd> +</dl> +<dl class="doctools_commands"> +<dt><b class="cmd">command-a</b></dt> +<dd><p>explanation</p></dd> +<dt><b class="cmd">command-b</b></dt> +<dd><p>elucidation</p></dd> +</dl> +<dl class="doctools_definitions"> +<dt>term</dt> +<dd><p>definition</p></dd> +<dt><a name="1">a-command</a></dt> +<dd><p>semantic</p></dd> +</dl> +<ol class="doctools_enumerated"> +<li><p>A</p></li> +<li><p>B</p> +<p>C</p> +<p>D</p></li> +</ol> +<ul class="doctools_itemized"> +<li><p>1</p></li> +<li><p>2</p> +<p>2a</p> +<p>2b</p></li> +</ul> +<dl class="doctools_options"> +<dt><b class="option">option-1</b></dt> +<dd><p>meaning</p></dd> +<dt><b class="option">option-2</b> value</dt> +<dd><p>elaboration</p></dd> +</dl> +<dl class="doctools_tkoptions"> +<dt>Command-Line Switch: <b class="option">background</b><br> +Database Name: <b class="optdbname">Background</b><br> +Database Class: <b class="optdbclass">Color</b><br> +</dt> +<dd><p>candy</p></dd> +<dt>Command-Line Switch: <b class="option">foreground</b><br> +Database Name: <b class="optdbname">Foreground</b><br> +Database Class: <b class="optdbclass">Color</b><br> +</dt> +<dd><p>caramel</p></dd> +</dl> +<p>KO</p> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/06 b/tcllib/modules/doctools/tests/html/06 new file mode 100644 index 0000000..145e6ef --- /dev/null +++ b/tcllib/modules/doctools/tests/html/06 @@ -0,0 +1,145 @@ +<html><head> +<title>TEST - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +<ul class="doctools_itemized"> +<li><p>1</p> +<p>2</p> +<p>3</p></li> +<li> +<ol class="doctools_enumerated"> +<li><p>a</p> +<p>b</p> +<p>c</p></li> +<li> +<dl class="doctools_definitions"> +<dt>foo</dt> +<dd><p>snafu</p></dd> +<dt>bar</dt> +<dd><p>barf</p></dd> +<dt>roo</dt> +<dd><p>gork</p></dd> +</dl> +</li> +<li><p>a</p> +<p>b</p> +<p>c</p></li> +</ol> +</li> +<li><p>4</p> +<p>5</p> +<p>6</p></li> +</ul> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/07 b/tcllib/modules/doctools/tests/html/07 new file mode 100644 index 0000000..721257e --- /dev/null +++ b/tcllib/modules/doctools/tests/html/07 @@ -0,0 +1,137 @@ +<html><head> +<title>TEST - </title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © .COPYRIGHT. + --> +<! -- TEST.z + --> +<body><div class="doctools"> +<h1 class="doctools_title">TEST(z) 3.14.15.926 .MODULE. ""</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>TEST -</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +<ul class="doctools_itemized"> +<li><p>1</p></li> +<li><p>2</p> +<ol class="doctools_enumerated"> +<li><p>a</p></li> +<li><p>b</p> +<dl class="doctools_definitions"> +<dt>foo</dt> +<dd><p>snafu</p></dd> +<dt>bar</dt> +<dd><p>barf</p></dd> +<dt>roo</dt> +<dd><p>gork</p></dd> +</dl> +<p>bb</p></li> +<li><p>a</p></li> +</ol> +<p>22</p></li> +<li><p>3</p></li> +</ul> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © .COPYRIGHT.</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/html/08 b/tcllib/modules/doctools/tests/html/08 new file mode 100644 index 0000000..46cfd2a --- /dev/null +++ b/tcllib/modules/doctools/tests/html/08 @@ -0,0 +1,221 @@ + +<html><head> +<title>ALL - ..THE_MODULE..</title> +<style type="text/css"><!-- + HTML { + background: #FFFFFF; + color: black; + } + BODY { + background: #FFFFFF; + color: black; + } + DIV.doctools { + margin-left: 10%; + margin-right: 10%; + } + DIV.doctools H1,DIV.doctools H2 { + margin-left: -5%; + } + H1, H2, H3, H4 { + margin-top: 1em; + font-family: sans-serif; + font-size: large; + color: #005A9C; + background: transparent; + text-align: left; + } + H1.doctools_title { + text-align: center; + } + UL,OL { + margin-right: 0em; + margin-top: 3pt; + margin-bottom: 3pt; + } + UL LI { + list-style: disc; + } + OL LI { + list-style: decimal; + } + DT { + padding-top: 1ex; + } + UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { + font: normal 12pt/14pt sans-serif; + list-style: none; + } + LI.doctools_section, LI.doctools_subsection { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + PRE { + display: block; + font-family: monospace; + white-space: pre; + margin: 0%; + padding-top: 0.5ex; + padding-bottom: 0.5ex; + padding-left: 1ex; + padding-right: 1ex; + width: 100%; + } + PRE.doctools_example { + color: black; + background: #f5dcb3; + border: 1px solid black; + } + UL.doctools_requirements LI, UL.doctools_syntax LI { + list-style: none; + margin-left: 0em; + text-indent: 0em; + padding: 0em; + } + DIV.doctools_synopsis { + color: black; + background: #80ffff; + border: 1px solid black; + font-family: serif; + margin-top: 1em; + margin-bottom: 1em; + } + UL.doctools_syntax { + margin-top: 1em; + border-top: 1px solid black; + } + UL.doctools_requirements { + margin-bottom: 1em; + border-bottom: 1px solid black; + } +--></style> +</head> +<! -- Generated from file '.FILE.' by tcllib/doctools with format 'html' + --> +<! -- Copyright © **Copyright** + --> +<! -- ALL.a + --> +<body><div class="doctools"> +<h1 class="doctools_title">ALL(a) 5 .MODULE. "..THE_MODULE.."</h1> +<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> +<p>ALL - ..THE_TITLE..</p> +</div> +<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> +<ul class="doctools_toc"> +<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> +<li class="doctools_section"><a href="#synopsis">Synopsis</a></li> +<li class="doctools_section"><a href="#section1">Description</a></li> +<li class="doctools_section"><a href="#section2">API</a> +<ul> +<li class="doctools_subsection"><a href="#subsection1">NARGLE</a></li> +</ul> +</li> +<li class="doctools_section"><a href="#see-also">See Also</a></li> +<li class="doctools_section"><a href="#keywords">Keywords</a></li> +<li class="doctools_section"><a href="#copyright">Copyright</a></li> +</ul> +</div> +<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> +<div class="doctools_synopsis"> +<ul class="doctools_requirements"> +<li>package require <b class="pkgname">AAA</b></li> +<li>package require <b class="pkgname">BBB VVV</b></li> +<li>package require <b class="pkgname">CCC <span class="opt">?VVV?</span></b></li> +</ul> +<ul class="doctools_syntax"> +<li><a href="#1">CMDNAME ...</a></li> +<li><a href="#2">CMDNAME ...</a></li> +<li><a href="#3">CMDNAME ...</a></li> +</ul> +</div> +</div> +<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> +<dl class="doctools_commands"> +<dt><b class="cmd">NAME</b></dt> +<dd><p>DESCRIPTION ::<b class="cmd">Command</b>::</p></dd> +<dt><b class="cmd">NAME</b></dt> +<dd><p>DESCRIPTION ::::</p></dd> +<dt><b class="cmd">NAME</b></dt> +<dd><p>DESCRIPTION ::<b class="const">Constant</b>::</p></dd> +</dl> +</div> +<div id="section2" class="doctools_section"><h2><a name="section2">API</a></h2> +<dl class="doctools_definitions"> +<dt>TERM</dt> +<dd><p>DESCRIPTION ::<em>Emphasis</em>::</p></dd> +<dt>TERM</dt> +<dd><p>DESCRIPTION ::"<b class="file">File/Path</b>"::</p> +<dl class="doctools_tkoptions"> +<dt>Command-Line Switch: <b class="option">NAME</b><br> +Database Name: <b class="optdbname">DBNAME</b><br> +Database Class: <b class="optdbclass">CLASS</b><br> +</dt> +<dd><p>DESCRIPTION <span class="sectref"><a href="#subsection1">NARGLE</a></span></p></dd> +<dt>Command-Line Switch: <b class="option">NAME</b><br> +Database Name: <b class="optdbname">DBNAME</b><br> +Database Class: <b class="optdbclass">CLASS</b><br> +</dt> +<dd><p>DESCRIPTION ::<b class="function">Function</b>::</p></dd> +<dt>Command-Line Switch: <b class="option">NAME</b><br> +Database Name: <b class="optdbname">DBNAME</b><br> +Database Class: <b class="optdbclass">CLASS</b><br> +</dt> +<dd><p>DESCRIPTION ::<b class="method">Method</b>::</p></dd> +</dl></dd> +<dt>TERM</dt> +<dd><p>DESCRIPTION</p></dd> +<dt><a name="1">CMDNAME ...</a></dt> +<dd><p>DESCRIPTION ::<b class="namespace">Namespace</b>::</p> +<dl class="doctools_arguments"> +<dt>TYPE <i class="arg">NAME</i></dt> +<dd><p>DESCRIPTION ::<i class="arg">Argument</i>::</p></dd> +<dt>TYPE <i class="arg">NAME</i></dt> +<dd><p>DESCRIPTION ::<b class="option">Option</b>::</p></dd> +<dt>TYPE <i class="arg">NAME</i> (MODE)</dt> +<dd><p>DESCRIPTION ::<span class="opt">?Optional?</span>::</p> +<pre class="doctools_example"> + THE ARGUMENT IS USED IN THIS + AND/OR THAT MANNER +</pre> +</dd> +</dl></dd> +<dt><a name="2">CMDNAME ...</a></dt> +<dd><p>DESCRIPTION ::<b class="package">Package</b>::</p></dd> +<dt><a name="3">CMDNAME ...</a></dt> +<dd><p>DESCRIPTION ::<b class="syscmd">SystemCommand</b>::</p> +<dl class="doctools_options"> +<dt><b class="option">NAME</b></dt> +<dd><p>DESCRIPTION ::<i class="term">Term</i>::</p></dd> +<dt><b class="option">NAME</b></dt> +<dd><p>DESCRIPTION ::<b class="type">Type</b>::</p></dd> +<dt><b class="option">NAME</b> ARGUMENT</dt> +<dd><p>DESCRIPTION ::<a href="Uri">Uri</a>::</p></dd> +</dl></dd> +</dl> +<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">NARGLE</a></h3> +<ol class="doctools_enumerated"> +<li><p>PARAGRAPH ::<a href="Uri">UriLabel</a>::</p></li> +<li><p>PARAGRAPH ::<b class="variable">Variable</b>::</p></li> +<li><p>PARAGRAPH ::<b class="widget">Widget</b>::</p> +<ul class="doctools_itemized"> +<li><p>PARAGRAPH ::<b class="class">Class</b>::</p></li> +<li><p>PARAGRAPH</p></li> +<li><p>PARAGRAPH</p></li> +</ul> +</li> +</ol> +</div> +</div> +<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2> +<p>ELSE, OTHER</p> +</div> +<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2> +<p>KEYA, KEYZ</p> +</div> +<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> +<p>Copyright © **Copyright**</p> +</div> +</div></body></html> diff --git a/tcllib/modules/doctools/tests/latex/00 b/tcllib/modules/doctools/tests/latex/00 new file mode 100644 index 0000000..234076f --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/00 @@ -0,0 +1,14 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- : } +\maketitle +\section{Description}\label{section1} +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/01 b/tcllib/modules/doctools/tests/latex/01 new file mode 100644 index 0000000..08cf348 --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/01 @@ -0,0 +1,33 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) **Copyright** +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- : } +\maketitle +\section{Description}\label{section1} +Argument ::\underline{Argument}:: +Class ::{\bf Class}:: +Command ::{\bf Command}:: +Comment :::: +Const ::{\bf Constant}:: +Emphasis ::{\it Emphasis}:: +File ::"{\it File/Path}":: +Function ::{\bf Function}:: +Method ::{\bf Method}:: +Namespace ::{\bf Namespace]}:: +Option ::{\bf Option}:: +Optional ::?Optional?:: +Package ::{\bf Package}:: +Syscmd ::{\bf SystemCommand}:: +Term ::{\it Term}:: +Type ::{\bf Type}:: +Uri ::\underline{Uri}:: +Variable ::{\bf Variable}:: +Widget ::{\bf Widget}:: +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) **Copyright**\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/02 b/tcllib/modules/doctools/tests/latex/02 new file mode 100644 index 0000000..089dc1b --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/02 @@ -0,0 +1,23 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- ..THE\_MODULE.. : ..THE\_TITLE..} +\maketitle +\section{Synopsis}\label{synopsis} +\begin{flushleft} +package require {\bf AAA} +package require {\bf BBB VVV} +\end{flushleft} +\section{Description}\label{section1} +\section{See Also}\label{see-also} +ELSE, OTHER +\section{Keywords}\label{keywords} +KEYA, KEYZ +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/03 b/tcllib/modules/doctools/tests/latex/03 new file mode 100644 index 0000000..fe91842 --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/03 @@ -0,0 +1,26 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- : } +\maketitle +\section{Description}\label{section1} +\section{AaA}\label{section2} +1 +\section{BbB}\label{section3} +22 +\subsection{BbB.cCc}\label{subsection1} +333 +\subsection{BbB.dDd}\label{subsection2} +4444 +\section{EeE}\label{section4} +5555 +At {\bf AaA (\ref{section2})}. +At {\bf \_\_undefined\_\_ (\ref{\_\_undefined\_\_})}. +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/04 b/tcllib/modules/doctools/tests/latex/04 new file mode 100644 index 0000000..1d4ee66 --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/04 @@ -0,0 +1,23 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- : } +\maketitle +\section{Description}\label{section1} +BEGINNE HIER +\begin{verbatim} + Example Block More Lines +\end{verbatim} +\begin{verbatim} +Inlined Example \ +Next Line +\end{verbatim} +FERTIG +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/05 b/tcllib/modules/doctools/tests/latex/05 new file mode 100644 index 0000000..acd2f76 --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/05 @@ -0,0 +1,99 @@ + +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ BASIC.a +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / BASIC -- : } +\maketitle +\section{Synopsis}\label{synopsis} +\begin{itemize} +\item[] a-command +\end{itemize} +\section{Description}\label{section1} +OK +\begin{itemize} +% +\item[] \underline{argument-1} integer +% +verification +% +\item[] \underline{argument-2} string (out) +% + mogrification +\end{itemize} +\begin{itemize} +% +\item[] {\bf command-a} +% + explanation +% +\item[] {\bf command-b} +% +elucidation +\end{itemize} +\begin{itemize} +% +\item[] term +% + definition +% +\item[] a-command +% +semantic +\end{itemize} +\begin{enumerate} +% +\item +% +A +% +\item +% + B +C +D +\end{enumerate} +\begin{itemize} +% +\item +% +1 +% +\item +% + 2 +2a +2b +\end{itemize} +\begin{itemize} +% +\item[] {\bf option-1} +% + meaning +% +\item[] {\bf option-2} value +% +elaboration +\end{itemize} +\begin{itemize} +% +\item[] Command-Line Switch: {\bf background}\\ +Database Name: {\bf Background}\\ +Database Class: {\bf Color}\\ +% + candy +% +\item[] Command-Line Switch: {\bf foreground}\\ +Database Name: {\bf Foreground}\\ +Database Class: {\bf Color}\\ +% +caramel +\end{itemize} +KO +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/06 b/tcllib/modules/doctools/tests/latex/06 new file mode 100644 index 0000000..5347173 --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/06 @@ -0,0 +1,54 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- : } +\maketitle +\section{Description}\label{section1} +\begin{itemize} +% +\item +% + 1 2 3 +% +\item +% +\begin{enumerate} +% +\item +% + a b c +% +\item +% +\begin{itemize} +% +\item[] foo +% + snafu +% +\item[] bar +% + barf +% +\item[] roo +% + gork +\end{itemize} +% +\item +% + a b c +\end{enumerate} +% +\item +% + 4 5 6 +\end{itemize} +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/07 b/tcllib/modules/doctools/tests/latex/07 new file mode 100644 index 0000000..b9951c8 --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/07 @@ -0,0 +1,58 @@ +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) .COPYRIGHT. +% CVS: @ID@ TEST.z +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / TEST -- : } +\maketitle +\section{Description}\label{section1} +\begin{itemize} +% +\item +% + 1 +% +\item +% + 2 +\begin{enumerate} +% +\item +% + a +% +\item +% + b +\begin{itemize} +% +\item[] foo +% + snafu +% +\item[] bar +% + barf +% +\item[] roo +% + gork +\end{itemize} +bb +% +\item +% + a +\end{enumerate} +22 +% +\item +% + 3 +\end{itemize} +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) .COPYRIGHT.\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/latex/08 b/tcllib/modules/doctools/tests/latex/08 new file mode 100644 index 0000000..793a2cd --- /dev/null +++ b/tcllib/modules/doctools/tests/latex/08 @@ -0,0 +1,152 @@ + +% Generated from file '.FILE.' by tcllib/doctools with format 'latex' +% Copyright (c) **Copyright** +% CVS: @ID@ ALL.a +\documentclass{article} +\begin{document} +\author{@USR@} +\title{.MODULE. / ALL -- ..THE\_MODULE.. : ..THE\_TITLE..} +\maketitle +\section{Synopsis}\label{synopsis} +\begin{flushleft} +package require {\bf AAA} +package require {\bf BBB VVV} +package require {\bf CCC ?VVV?} +\end{flushleft} +\begin{itemize} +\item[] CMDNAME ... +\item[] CMDNAME ... +\item[] CMDNAME ... +\end{itemize} +\section{Description}\label{section1} +\begin{itemize} +% +\item[] {\bf NAME} +% + DESCRIPTION ::{\bf Command}:: +% +\item[] {\bf NAME} +% + DESCRIPTION :::: +% +\item[] {\bf NAME} +% + DESCRIPTION ::{\bf Constant}:: +\end{itemize} +\section{API}\label{section2} +\begin{itemize} +% +\item[] TERM +% + DESCRIPTION ::{\it Emphasis}:: +% +\item[] TERM +% + DESCRIPTION ::"{\it File/Path}":: +\begin{itemize} +% +\item[] Command-Line Switch: {\bf NAME}\\ +Database Name: {\bf DBNAME}\\ +Database Class: {\bf CLASS}\\ +% + DESCRIPTION {\bf NARGLE (\ref{subsection1})} +% +\item[] Command-Line Switch: {\bf NAME}\\ +Database Name: {\bf DBNAME}\\ +Database Class: {\bf CLASS}\\ +% + DESCRIPTION ::{\bf Function}:: +% +\item[] Command-Line Switch: {\bf NAME}\\ +Database Name: {\bf DBNAME}\\ +Database Class: {\bf CLASS}\\ +% + DESCRIPTION ::{\bf Method}:: +\end{itemize} +% +\item[] TERM +% + DESCRIPTION +% +\item[] CMDNAME ... +% + DESCRIPTION ::{\bf Namespace]}:: +\begin{itemize} +% +\item[] \underline{NAME} TYPE +% + DESCRIPTION ::\underline{Argument}:: +% +\item[] \underline{NAME} TYPE +% + DESCRIPTION ::{\bf Option}:: +% +\item[] \underline{NAME} TYPE (MODE) +% + DESCRIPTION ::?Optional?:: +\begin{verbatim} + THE ARGUMENT IS USED IN THIS + AND/OR THAT MANNER +\end{verbatim} +\end{itemize} +% +\item[] CMDNAME ... +% + DESCRIPTION ::{\bf Package}:: +% +\item[] CMDNAME ... +% + DESCRIPTION ::{\bf SystemCommand}:: +\begin{itemize} +% +\item[] {\bf NAME} +% + DESCRIPTION ::{\it Term}:: +% +\item[] {\bf NAME} +% + DESCRIPTION ::{\bf Type}:: +% +\item[] {\bf NAME} ARGUMENT +% + DESCRIPTION ::\underline{Uri}:: +\end{itemize} +\end{itemize} +\subsection{NARGLE}\label{subsection1} +\begin{enumerate} +% +\item +% + PARAGRAPH ::\underline{UriLabel} \footnote{Uri}:: +% +\item +% + PARAGRAPH ::{\bf Variable}:: +% +\item +% + PARAGRAPH ::{\bf Widget}:: +\begin{itemize} +% +\item +% + PARAGRAPH ::{\bf Class}:: +% +\item +% + PARAGRAPH +% +\item +% + PARAGRAPH +\end{itemize} +\end{enumerate} +\section{See Also}\label{see-also} +ELSE, OTHER +\section{Keywords}\label{keywords} +KEYA, KEYZ +\section{Copyright}\label{copyright} +\begin{flushleft} +Copyright (c) **Copyright**\linebreak +\end{flushleft} +\end{document} diff --git a/tcllib/modules/doctools/tests/list/00 b/tcllib/modules/doctools/tests/list/00 new file mode 100644 index 0000000..82f0dd4 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/00 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/01 b/tcllib/modules/doctools/tests/list/01 new file mode 100644 index 0000000..82f0dd4 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/01 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/02 b/tcllib/modules/doctools/tests/list/02 new file mode 100644 index 0000000..49e2bc7 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/02 @@ -0,0 +1 @@ +manpage {seealso {ELSE OTHER} keywords {KEYA KEYZ} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc ..THE_MODULE.. desc ..THE_TITLE.. fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/03 b/tcllib/modules/doctools/tests/list/03 new file mode 100644 index 0000000..82f0dd4 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/03 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/04 b/tcllib/modules/doctools/tests/list/04 new file mode 100644 index 0000000..82f0dd4 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/04 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/05 b/tcllib/modules/doctools/tests/list/05 new file mode 100644 index 0000000..5fdc7fb --- /dev/null +++ b/tcllib/modules/doctools/tests/list/05 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section a category {} module .MODULE. version 5 title BASIC shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/06 b/tcllib/modules/doctools/tests/list/06 new file mode 100644 index 0000000..82f0dd4 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/06 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/07 b/tcllib/modules/doctools/tests/list/07 new file mode 100644 index 0000000..82f0dd4 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/07 @@ -0,0 +1 @@ +manpage {seealso {} keywords {} file .FILE. section z category {} module .MODULE. version 3.14.15.926 title TEST shortdesc {} desc {} fid .FILE} diff --git a/tcllib/modules/doctools/tests/list/08 b/tcllib/modules/doctools/tests/list/08 new file mode 100644 index 0000000..e4a13e1 --- /dev/null +++ b/tcllib/modules/doctools/tests/list/08 @@ -0,0 +1 @@ +manpage {seealso {ELSE OTHER} keywords {KEYA KEYZ} file .FILE. section a category {} module .MODULE. version 5 title ALL shortdesc ..THE_MODULE.. desc ..THE_TITLE.. fid .FILE} diff --git a/tcllib/modules/doctools/tests/man/00 b/tcllib/modules/doctools/tests/man/00 new file mode 100644 index 0000000..cce77e7 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/00 @@ -0,0 +1,3 @@ +[manpage_begin TEST z 3.14.15.926] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/man/01 b/tcllib/modules/doctools/tests/man/01 new file mode 100644 index 0000000..0392196 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/01 @@ -0,0 +1,23 @@ +[manpage_begin TEST z 3.14.15.926] +[copyright **Copyright**] +[description] +Argument ::[arg Argument]:: +Class ::[class Class]:: +Command ::[cmd Command]:: +Comment ::[comment Comment]:: +Const ::[const Constant]:: +Emphasis ::[emph Emphasis]:: +File ::[file File/Path]:: +Function ::[fun Function]:: +Method ::[method Method]:: +Namespace ::[namespace Namespace]:: +Option ::[option Option]:: +Optional ::[opt Optional]:: +Package ::[package Package]:: +Syscmd ::[syscmd SystemCommand]:: +Term ::[term Term]:: +Type ::[type Type]:: +Uri ::[uri Uri]:: +Variable ::[var Variable]:: +Widget ::[widget Widget]:: +[manpage_end] diff --git a/tcllib/modules/doctools/tests/man/02 b/tcllib/modules/doctools/tests/man/02 new file mode 100644 index 0000000..11d01c0 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/02 @@ -0,0 +1,9 @@ +[manpage_begin TEST z 3.14.15.926] +[moddesc ..THE_MODULE..] +[titledesc ..THE_TITLE..] +[require AAA] +[require BBB VVV] +[keywords KEYA KEYZ] +[see_also OTHER ELSE] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/man/03 b/tcllib/modules/doctools/tests/man/03 new file mode 100644 index 0000000..f65d255 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/03 @@ -0,0 +1,19 @@ +[manpage_begin TEST z 3.14.15.926] +[description] +[section AaA] +1 +[section BbB] +22 +[subsection BbB.cCc] +333 +[subsection BbB.dDd] +4444 +[section EeE] +5555 + +[para] +At [sectref AaA]. +[para] +At [sectref __undefined__]. +[manpage_end] + diff --git a/tcllib/modules/doctools/tests/man/04 b/tcllib/modules/doctools/tests/man/04 new file mode 100644 index 0000000..82d4790 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/04 @@ -0,0 +1,16 @@ +[manpage_begin TEST z 3.14.15.926] +[description] +BEGINNE HIER +[example { + Example Block \ + More Lines +}] +[para] +[para] +[example_begin] +Inlined Example \ +Next Line +[example_end] +FERTIG +[manpage_end] + diff --git a/tcllib/modules/doctools/tests/man/05 b/tcllib/modules/doctools/tests/man/05 new file mode 100644 index 0000000..5ec6daa --- /dev/null +++ b/tcllib/modules/doctools/tests/man/05 @@ -0,0 +1,58 @@ +[comment {LISTS, BASIC}] +[manpage_begin BASIC a 5] +[description] +OK +[para] +[list_begin arguments] +[arg_def integer argument-1] +verification +[arg_def string argument-2 out] mogrification +[list_end] +[para] +[list_begin commands] +[cmd_def command-a] explanation +[cmd_def command-b] +elucidation +[list_end] +[para] +[list_begin definitions] +[def term] definition +[call a-command] +semantic +[list_end] +[para] +[list_begin enumerated] +[enum] +A +[enum] B +[para] +C +[para] +D +[list_end] +[para] +[list_begin itemized] +[item] +1 +[item] 2 +[para] +2a +[para] +2b +[list_end] +[para] +[list_begin options] +[opt_def option-1] meaning +[opt_def option-2 value] +elaboration +[list_end] +[para] +[list_begin tkoptions] +[tkoption_def background Background Color] candy +[tkoption_def foreground Foreground Color] +caramel +[list_end] +[para] +KO +[comment DONE] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/man/06 b/tcllib/modules/doctools/tests/man/06 new file mode 100644 index 0000000..c00a4c4 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/06 @@ -0,0 +1,27 @@ +[manpage_begin TEST z 3.14.15.926] +[description] +[comment { + nested lists, same and different types, examples have examples at + least three levels deep, for a proper inner level, i.e. not only + first/last level, but something truly in the middle. Also three + list items of the relevant on each level, see the proper handling + of indentations. For that we also need paragraphs in the items. + + start: itemized/enumerated/definition +}] +[list_begin itemized] +[item] 1 [para] 2 [para] 3 +[item] +[list_begin enumerated] +[enum] a [para] b [para] c +[enum] +[list_begin definitions] +[def foo] snafu +[def bar] barf +[def roo] gork +[list_end] +[enum] a [para] b [para] c +[list_end] +[item] 4 [para] 5 [para] 6 +[list_end] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/man/07 b/tcllib/modules/doctools/tests/man/07 new file mode 100644 index 0000000..09414c5 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/07 @@ -0,0 +1,23 @@ +[manpage_begin TEST z 3.14.15.926] +[description] +[comment { + nested list 2, put text before and after the embedded list. +}] +[list_begin itemized] +[item] 1 +[item] 2 +[list_begin enumerated] +[enum] a +[enum] b +[list_begin definitions] +[def foo] snafu +[def bar] barf +[def roo] gork +[list_end] +bb +[enum] a +[list_end] +22 +[item] 3 +[list_end] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/man/08 b/tcllib/modules/doctools/tests/man/08 new file mode 100644 index 0000000..0526e39 --- /dev/null +++ b/tcllib/modules/doctools/tests/man/08 @@ -0,0 +1,56 @@ +[comment {LISTS, ALL TYPES}] +[manpage_begin ALL a 5] +[copyright **Copyright**] +[moddesc ..THE_MODULE..] +[titledesc ..THE_TITLE..] +[require AAA] +[require BBB VVV] +[require CCC [opt VVV]] +[description] +[list_begin commands] +[cmd_def NAME] DESCRIPTION ::[cmd Command]:: +[cmd_def NAME] DESCRIPTION ::[comment Comment]:: +[cmd_def NAME] DESCRIPTION ::[const Constant]:: +[list_end] +[section API] +[list_begin definitions] +[def TERM] DESCRIPTION ::[emph Emphasis]:: +[def TERM] DESCRIPTION ::[file File/Path]:: +[list_begin tkoptions] +[tkoption_def NAME DBNAME CLASS] DESCRIPTION [sectref NARGLE] +[tkoption_def NAME DBNAME CLASS] DESCRIPTION ::[fun Function]:: +[tkoption_def NAME DBNAME CLASS] DESCRIPTION ::[method Method]:: +[list_end] +[def TERM] DESCRIPTION +[call CMDNAME ...] DESCRIPTION ::[namespace Namespace]:: +[list_begin arguments] +[arg_def TYPE NAME] DESCRIPTION ::[arg Argument]:: +[arg_def TYPE NAME] DESCRIPTION ::[option Option]:: +[arg_def TYPE NAME MODE] DESCRIPTION ::[opt Optional]:: +[example { + THE ARGUMENT IS USED IN THIS + AND/OR THAT MANNER +}] +[list_end] +[call CMDNAME ...] DESCRIPTION ::[package Package]:: +[call CMDNAME ...] DESCRIPTION ::[syscmd SystemCommand]:: +[list_begin options] +[opt_def NAME] DESCRIPTION ::[term Term]:: +[opt_def NAME] DESCRIPTION ::[type Type]:: +[opt_def NAME ARGUMENT] DESCRIPTION ::[uri Uri]:: +[list_end] +[list_end] +[subsection NARGLE] +[list_begin enumerated] +[enum] PARAGRAPH ::[uri Uri UriLabel]:: +[enum] PARAGRAPH ::[var Variable]:: +[enum] PARAGRAPH ::[widget Widget]:: +[list_begin itemized] +[item] PARAGRAPH ::[class Class]:: +[item] PARAGRAPH +[item] PARAGRAPH +[list_end] +[list_end] +[keywords KEYA KEYZ] +[see_also OTHER ELSE] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/nroff/00 b/tcllib/modules/doctools/tests/nroff/00 new file mode 100644 index 0000000..2cea3ca --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/00 @@ -0,0 +1,15 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +TEST \- +.SH DESCRIPTION +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/01 b/tcllib/modules/doctools/tests/nroff/01 new file mode 100644 index 0000000..bf0f3db --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/01 @@ -0,0 +1,34 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) **Copyright** +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +TEST \- +.SH DESCRIPTION +Argument ::\fIArgument\fR:: +Class ::\fBClass\fR:: +Command ::\fBCommand\fR:: +Comment :::: +Const ::\fBConstant\fR:: +Emphasis ::\fIEmphasis\fR:: +File ::"\fIFile/Path\fR":: +Function ::\fBFunction\fR:: +Method ::\fBMethod\fR:: +Namespace ::\fBNamespace\fR:: +Option ::\fBOption\fR:: +Optional ::?Optional?:: +Package ::\fBPackage\fR:: +Syscmd ::\fBSystemCommand\fR:: +Term ::\fITerm\fR:: +Type ::\fBType\fR:: +Uri ::\fIUri\fR:: +Variable ::\fBVariable\fR:: +Widget ::\fBWidget\fR:: +.SH COPYRIGHT +.nf +Copyright (c) **Copyright** + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/02 b/tcllib/modules/doctools/tests/nroff/02 new file mode 100644 index 0000000..1205e3c --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/02 @@ -0,0 +1,25 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "\&.\&.THE_MODULE\&.\&." +.so man.macros +.BS +.SH NAME +TEST \- \&.\&.THE_TITLE\&.\&. +.SH SYNOPSIS +package require \fBAAA \fR +.sp +package require \fBBBB VVV\fR +.sp +.BE +.SH DESCRIPTION +.SH "SEE ALSO" +ELSE, OTHER +.SH KEYWORDS +KEYA, KEYZ +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/03 b/tcllib/modules/doctools/tests/nroff/03 new file mode 100644 index 0000000..8e7482d --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/03 @@ -0,0 +1,29 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +TEST \- +.SH DESCRIPTION +.SH AAA +1 +.SH BBB +22 +.SS BBB\&.CCC +333 +.SS BBB\&.DDD +4444 +.SH EEE +5555 +.PP +At \fBAaA\fR\&. +.PP +At \fB__undefined__\fR\&. +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/04 b/tcllib/modules/doctools/tests/nroff/04 new file mode 100644 index 0000000..e132fe2 --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/04 @@ -0,0 +1,32 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +TEST \- +.SH DESCRIPTION +BEGINNE HIER +.CS + + + Example Block More Lines + +.CE +.PP +.PP +.CS + + +Inlined Example \\ +Next Line + +.CE +FERTIG +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/05 b/tcllib/modules/doctools/tests/nroff/05 new file mode 100644 index 0000000..fc4e5f5 --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/05 @@ -0,0 +1,96 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "BASIC" a 5 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +BASIC \- +.SH SYNOPSIS +a-command +.sp +.BE +.SH DESCRIPTION +OK +.PP +.TP +integer \fIargument-1\fR +verification +.TP +string \fIargument-2\fR (out) +mogrification +.PP +.PP +.TP +\fBcommand-a\fR +explanation +.TP +\fBcommand-b\fR +elucidation +.PP +.PP +.TP +term +definition +.TP +a-command +semantic +.PP +.PP +.IP [1] +A +.IP [2] +B +.sp +C +.sp +D +.PP +.PP +.IP \(bu +1 +.IP \(bu +2 +.sp +2a +.sp +2b +.PP +.PP +.TP +\fBoption-1\fR +meaning +.TP +\fBoption-2\fR value +elaboration +.PP +.PP +.LP +.nf +.ta 6c +Command-Line Switch: \fBbackground\fR +Database Name: \fBBackground\fR +Database Class: \fBColor\fR + +.fi +.IP +candy +.LP +.nf +.ta 6c +Command-Line Switch: \fBforeground\fR +Database Name: \fBForeground\fR +Database Class: \fBColor\fR + +.fi +.IP +caramel +.PP +.PP +KO +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/06 b/tcllib/modules/doctools/tests/nroff/06 new file mode 100644 index 0000000..63de9d8 --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/06 @@ -0,0 +1,55 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +TEST \- +.SH DESCRIPTION +.IP \(bu +1 +.sp +2 +.sp +3 +.IP \(bu +.RS +.IP [1] +a +.sp +b +.sp +c +.IP [2] +.RS +.TP +foo +snafu +.TP +bar +barf +.TP +roo +gork +.RE +.IP [3] +a +.sp +b +.sp +c +.RE +.IP \(bu +4 +.sp +5 +.sp +6 +.PP +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/07 b/tcllib/modules/doctools/tests/nroff/07 new file mode 100644 index 0000000..b4b3647 --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/07 @@ -0,0 +1,45 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) \&.COPYRIGHT\&. +'\" +.TH "TEST" z 3\&.14\&.15\&.926 \&.MODULE\&. "" +.so man.macros +.BS +.SH NAME +TEST \- +.SH DESCRIPTION +.IP \(bu +1 +.IP \(bu +2 +.RS +.IP [1] +a +.IP [2] +b +.RS +.TP +foo +snafu +.TP +bar +barf +.TP +roo +gork +.RE +.IP +bb +.IP [3] +a +.RE +.IP +22 +.IP \(bu +3 +.PP +.SH COPYRIGHT +.nf +Copyright (c) \&.COPYRIGHT\&. + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/nroff/08 b/tcllib/modules/doctools/tests/nroff/08 new file mode 100644 index 0000000..da008d4 --- /dev/null +++ b/tcllib/modules/doctools/tests/nroff/08 @@ -0,0 +1,140 @@ +'\" +'\" Generated from file '\&.FILE\&.' by tcllib/doctools with format 'nroff' +'\" Copyright (c) **Copyright** +'\" +.TH "ALL" a 5 \&.MODULE\&. "\&.\&.THE_MODULE\&.\&." +.so man.macros +.BS +.SH NAME +ALL \- \&.\&.THE_TITLE\&.\&. +.SH SYNOPSIS +package require \fBAAA \fR +.sp +package require \fBBBB VVV\fR +.sp +package require \fBCCC ?VVV?\fR +.sp +CMDNAME \&.\&.\&. +.sp +CMDNAME \&.\&.\&. +.sp +CMDNAME \&.\&.\&. +.sp +.BE +.SH DESCRIPTION +.TP +\fBNAME\fR +DESCRIPTION ::\fBCommand\fR:: +.TP +\fBNAME\fR +DESCRIPTION :::: +.TP +\fBNAME\fR +DESCRIPTION ::\fBConstant\fR:: +.PP +.SH API +.TP +TERM +DESCRIPTION ::\fIEmphasis\fR:: +.TP +TERM +DESCRIPTION ::"\fIFile/Path\fR":: +.RS +.LP +.nf +.ta 6c +Command-Line Switch: \fBNAME\fR +Database Name: \fBDBNAME\fR +Database Class: \fBCLASS\fR + +.fi +.IP +DESCRIPTION \fBNARGLE\fR +.LP +.nf +.ta 6c +Command-Line Switch: \fBNAME\fR +Database Name: \fBDBNAME\fR +Database Class: \fBCLASS\fR + +.fi +.IP +DESCRIPTION ::\fBFunction\fR:: +.LP +.nf +.ta 6c +Command-Line Switch: \fBNAME\fR +Database Name: \fBDBNAME\fR +Database Class: \fBCLASS\fR + +.fi +.IP +DESCRIPTION ::\fBMethod\fR:: +.RE +.TP +TERM +DESCRIPTION +.TP +CMDNAME \&.\&.\&. +DESCRIPTION ::\fBNamespace\fR:: +.RS +.TP +TYPE \fINAME\fR +DESCRIPTION ::\fIArgument\fR:: +.TP +TYPE \fINAME\fR +DESCRIPTION ::\fBOption\fR:: +.TP +TYPE \fINAME\fR (MODE) +DESCRIPTION ::?Optional?:: +.CS + + + THE ARGUMENT IS USED IN THIS + AND/OR THAT MANNER + +.CE +.RE +.TP +CMDNAME \&.\&.\&. +DESCRIPTION ::\fBPackage\fR:: +.TP +CMDNAME \&.\&.\&. +DESCRIPTION ::\fBSystemCommand\fR:: +.RS +.TP +\fBNAME\fR +DESCRIPTION ::\fITerm\fR:: +.TP +\fBNAME\fR +DESCRIPTION ::\fBType\fR:: +.TP +\fBNAME\fR ARGUMENT +DESCRIPTION ::\fIUri\fR:: +.RE +.PP +.SS NARGLE +.IP [1] +PARAGRAPH ::\fIUriLabel\fR [Uri]:: +.IP [2] +PARAGRAPH ::\fBVariable\fR:: +.IP [3] +PARAGRAPH ::\fBWidget\fR:: +.RS +.IP \(bu +PARAGRAPH ::\fBClass\fR:: +.IP \(bu +PARAGRAPH +.IP \(bu +PARAGRAPH +.RE +.PP +.SH "SEE ALSO" +ELSE, OTHER +.SH KEYWORDS +KEYA, KEYZ +.SH COPYRIGHT +.nf +Copyright (c) **Copyright** + +.fi
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/null/00 b/tcllib/modules/doctools/tests/null/00 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/00 diff --git a/tcllib/modules/doctools/tests/null/01 b/tcllib/modules/doctools/tests/null/01 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/01 diff --git a/tcllib/modules/doctools/tests/null/02 b/tcllib/modules/doctools/tests/null/02 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/02 diff --git a/tcllib/modules/doctools/tests/null/03 b/tcllib/modules/doctools/tests/null/03 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/03 diff --git a/tcllib/modules/doctools/tests/null/04 b/tcllib/modules/doctools/tests/null/04 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/04 diff --git a/tcllib/modules/doctools/tests/null/05 b/tcllib/modules/doctools/tests/null/05 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/05 diff --git a/tcllib/modules/doctools/tests/null/06 b/tcllib/modules/doctools/tests/null/06 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/06 diff --git a/tcllib/modules/doctools/tests/null/07 b/tcllib/modules/doctools/tests/null/07 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/07 diff --git a/tcllib/modules/doctools/tests/null/08 b/tcllib/modules/doctools/tests/null/08 new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tcllib/modules/doctools/tests/null/08 diff --git a/tcllib/modules/doctools/tests/syntax/e_arg_list b/tcllib/modules/doctools/tests/syntax/e_arg_list new file mode 100644 index 0000000..2cb55a5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_arg_list @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[arg_def arg-type arg-name] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_body b/tcllib/modules/doctools/tests/syntax/e_body new file mode 100644 index 0000000..fa86a64 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_body @@ -0,0 +1,4 @@ +Text before manpage_begin is not allowed +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def1 new file mode 100644 index 0000000..9469e13 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def1 @@ -0,0 +1,4 @@ +[arg_def arg-type arg-name] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def2 new file mode 100644 index 0000000..0bcb6b5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[arg_def arg-type arg-name] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def3 new file mode 100644 index 0000000..f729561 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_arg_def3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[arg_def arg-type arg-name] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_call1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_call1 new file mode 100644 index 0000000..3c7fff3 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_call1 @@ -0,0 +1,4 @@ +[call .command.] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_call2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_call2 new file mode 100644 index 0000000..f1a2082 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_call2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[call .command.] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_call3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_call3 new file mode 100644 index 0000000..9ab775e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_call3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[call .command.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def1 new file mode 100644 index 0000000..db6f015 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def1 @@ -0,0 +1,4 @@ +[cmd_def .command.] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def2 new file mode 100644 index 0000000..564d3c6 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[cmd_def .command.] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def3 new file mode 100644 index 0000000..4557ab1 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_cmd_def3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[cmd_def .command.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_def1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_def1 new file mode 100644 index 0000000..b1f4b25 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_def1 @@ -0,0 +1,4 @@ +[def] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_def2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_def2 new file mode 100644 index 0000000..e1a0db4 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_def2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[def] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_def3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_def3 new file mode 100644 index 0000000..089b4bb --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_def3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[def] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum1 new file mode 100644 index 0000000..801f2aa --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum1 @@ -0,0 +1,4 @@ +[enum] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum2 new file mode 100644 index 0000000..5b59ec4 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[enum] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum3 new file mode 100644 index 0000000..18f408e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_enum3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[enum] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_example1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example1 new file mode 100644 index 0000000..d392d3c --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example1 @@ -0,0 +1,4 @@ +[example {}] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_example2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example2 new file mode 100644 index 0000000..5d53198 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[example {}] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_example3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example3 new file mode 100644 index 0000000..cb54076 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[example {}] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin1 new file mode 100644 index 0000000..fe4172e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin1 @@ -0,0 +1,4 @@ +[example_begin] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin2 new file mode 100644 index 0000000..14f75b5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[example_begin] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin3 new file mode 100644 index 0000000..6be2c4b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_example_begin3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[example_begin] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_item1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_item1 new file mode 100644 index 0000000..dacec14 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_item1 @@ -0,0 +1,4 @@ +[item] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_item2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_item2 new file mode 100644 index 0000000..ffe4125 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_item2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[item] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_item3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_item3 new file mode 100644 index 0000000..43bc9a7 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_item3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[item] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin1 new file mode 100644 index 0000000..37e71ac --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin1 @@ -0,0 +1,4 @@ +[list_begin definitions] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin2 new file mode 100644 index 0000000..6604243 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[list_begin definitions] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin3 new file mode 100644 index 0000000..cd0ee95 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_begin3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[list_begin definitions] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end1 new file mode 100644 index 0000000..a8e221f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end1 @@ -0,0 +1,4 @@ +[list_end] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end2 new file mode 100644 index 0000000..a0b5e5f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[list_end] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end3 new file mode 100644 index 0000000..5bff582 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_list_end3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[list_end] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_manpage_end b/tcllib/modules/doctools/tests/syntax/e_bodycmd_manpage_end new file mode 100644 index 0000000..3ca4d96 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_manpage_end @@ -0,0 +1,5 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {example not closed}] +[example_begin] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def1 new file mode 100644 index 0000000..c107610 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def1 @@ -0,0 +1,4 @@ +[opt_def .option.] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def2 new file mode 100644 index 0000000..e5c3687 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[opt_def .option.] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def3 new file mode 100644 index 0000000..d3758dc --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_opt_def3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[opt_def .option.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_para1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_para1 new file mode 100644 index 0000000..15df4d3 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_para1 @@ -0,0 +1,4 @@ +[para] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_para2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_para2 new file mode 100644 index 0000000..b5aceba --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_para2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[para] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_para3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_para3 new file mode 100644 index 0000000..60f8d5b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_para3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[para] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_section1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_section1 new file mode 100644 index 0000000..d021414 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_section1 @@ -0,0 +1,4 @@ +[section foo] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_section2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_section2 new file mode 100644 index 0000000..5a76f33 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_section2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[section foo] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_section3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_section3 new file mode 100644 index 0000000..fa7cf65 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_section3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[section foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref1 new file mode 100644 index 0000000..792a4e3 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref1 @@ -0,0 +1,4 @@ +[sectref S] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref2 new file mode 100644 index 0000000..79fa807 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[sectref S] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref3 new file mode 100644 index 0000000..a4be9dc --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_sectref3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[sectref S] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection1 new file mode 100644 index 0000000..1b78303 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection1 @@ -0,0 +1,4 @@ +[subsection foo] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection2 new file mode 100644 index 0000000..55578bd --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[subsection foo] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection3 new file mode 100644 index 0000000..c65910e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_subsection3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad subsection}] +[example_begin] +[subsection foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def1 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def1 new file mode 100644 index 0000000..650dca5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def1 @@ -0,0 +1,4 @@ +[tkoption_def .option. .dbname. .dbclass.] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def2 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def2 new file mode 100644 index 0000000..270948c --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[tkoption_def .option. .dbname. .dbclass.] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def3 b/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def3 new file mode 100644 index 0000000..776b184 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bodycmd_tkoption_def3 @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_begin] +[tkoption_def .option. .dbname. .dbclass.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_bulletlist b/tcllib/modules/doctools/tests/syntax/e_bulletlist new file mode 100644 index 0000000..fda8e8e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_bulletlist @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[item] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_cmd_list b/tcllib/modules/doctools/tests/syntax/e_cmd_list new file mode 100644 index 0000000..3abf20f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_cmd_list @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[cmd_def .command.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_deflist_call b/tcllib/modules/doctools/tests/syntax/e_deflist_call new file mode 100644 index 0000000..2fc184f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_deflist_call @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin arguments] +[call .command.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_deflist_def b/tcllib/modules/doctools/tests/syntax/e_deflist_def new file mode 100644 index 0000000..33541ce --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_deflist_def @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin options] +[def] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_end_open_example b/tcllib/modules/doctools/tests/syntax/e_end_open_example new file mode 100644 index 0000000..cc77b82 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_end_open_example @@ -0,0 +1,5 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {example not closed}] +[example_begin] + diff --git a/tcllib/modules/doctools/tests/syntax/e_end_open_list b/tcllib/modules/doctools/tests/syntax/e_end_open_list new file mode 100644 index 0000000..2f8db2f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_end_open_list @@ -0,0 +1,5 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[list_begin commands] +[comment {list not closed}] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_end_open_mp b/tcllib/modules/doctools/tests/syntax/e_end_open_mp new file mode 100644 index 0000000..4b2a040 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_end_open_mp @@ -0,0 +1,2 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[comment {manpage not closed}] diff --git a/tcllib/modules/doctools/tests/syntax/e_enumlist b/tcllib/modules/doctools/tests/syntax/e_enumlist new file mode 100644 index 0000000..36713aa --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_enumlist @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[enum] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_examplecmd1 b/tcllib/modules/doctools/tests/syntax/e_examplecmd1 new file mode 100644 index 0000000..c5c919e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_examplecmd1 @@ -0,0 +1,4 @@ +[example_end] +[manpage_end ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_examplecmd2 b/tcllib/modules/doctools/tests/syntax/e_examplecmd2 new file mode 100644 index 0000000..7b08898 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_examplecmd2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[example_end] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_examplecmd3 b/tcllib/modules/doctools/tests/syntax/e_examplecmd3 new file mode 100644 index 0000000..e20804a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_examplecmd3 @@ -0,0 +1,5 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[example_end] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_copyright1 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_copyright1 new file mode 100644 index 0000000..011d640 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_copyright1 @@ -0,0 +1,4 @@ +[copyright foo] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_copyright2 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_copyright2 new file mode 100644 index 0000000..75aa471 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_copyright2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[copyright foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_description1 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_description1 new file mode 100644 index 0000000..60da8e9 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_description1 @@ -0,0 +1,4 @@ +[description] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_description2 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_description2 new file mode 100644 index 0000000..9cd8477 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_description2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_moddesc1 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_moddesc1 new file mode 100644 index 0000000..8cb7389 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_moddesc1 @@ -0,0 +1,4 @@ +[moddesc foo] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_moddesc2 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_moddesc2 new file mode 100644 index 0000000..c54a326 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_moddesc2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[moddesc foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_require1 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_require1 new file mode 100644 index 0000000..fb21304 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_require1 @@ -0,0 +1,4 @@ +[require foo] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_require2 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_require2 new file mode 100644 index 0000000..eb7c979 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_require2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[require foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_titledesc1 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_titledesc1 new file mode 100644 index 0000000..bdce8a8 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_titledesc1 @@ -0,0 +1,4 @@ +[titledesc foo] +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_hdrcmd_titledesc2 b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_titledesc2 new file mode 100644 index 0000000..784efae --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_hdrcmd_titledesc2 @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[titledesc foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_invalidlist_list_begin b/tcllib/modules/doctools/tests/syntax/e_invalidlist_list_begin new file mode 100644 index 0000000..b701442 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_invalidlist_list_begin @@ -0,0 +1,5 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[list_begin bogus] +[list_end] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_arg_def b/tcllib/modules/doctools/tests/syntax/e_listcmd_arg_def new file mode 100644 index 0000000..753b082 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_arg_def @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[arg_def arg-type arg-name] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_call b/tcllib/modules/doctools/tests/syntax/e_listcmd_call new file mode 100644 index 0000000..8960db8 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_call @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[call .command.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_cmd_def b/tcllib/modules/doctools/tests/syntax/e_listcmd_cmd_def new file mode 100644 index 0000000..989d5e7 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_cmd_def @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[cmd_def .command.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_def b/tcllib/modules/doctools/tests/syntax/e_listcmd_def new file mode 100644 index 0000000..88101d3 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_def @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[def] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_enum b/tcllib/modules/doctools/tests/syntax/e_listcmd_enum new file mode 100644 index 0000000..a177d56 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_enum @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[enum] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_item b/tcllib/modules/doctools/tests/syntax/e_listcmd_item new file mode 100644 index 0000000..854659e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_item @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[item] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_opt_def b/tcllib/modules/doctools/tests/syntax/e_listcmd_opt_def new file mode 100644 index 0000000..820ea58 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_opt_def @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[opt_def .option.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_listcmd_tkoption_def b/tcllib/modules/doctools/tests/syntax/e_listcmd_tkoption_def new file mode 100644 index 0000000..2e05f78 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_listcmd_tkoption_def @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] + +[tkoption_def .option. .dbname. .dbclass.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_mpbegin b/tcllib/modules/doctools/tests/syntax/e_mpbegin new file mode 100644 index 0000000..cc86833 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_mpbegin @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[manpage_begin BOGUS e 2.71828182845904523536] +[description] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_arg b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_arg new file mode 100644 index 0000000..4ec427d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_arg @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[arg .a.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_class b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_class new file mode 100644 index 0000000..9d9b289 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_class @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[class .c.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_cmd b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_cmd new file mode 100644 index 0000000..ebc5027 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_cmd @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[cmd .c.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_comment b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_comment new file mode 100644 index 0000000..fd3799b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_comment @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[comment .c] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_const b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_const new file mode 100644 index 0000000..25e217a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_const @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[const .c.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_emph b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_emph new file mode 100644 index 0000000..2c2116d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_emph @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[emph .t.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_file b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_file new file mode 100644 index 0000000..9ef7be8 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_file @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[file .f.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_fun b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_fun new file mode 100644 index 0000000..668ebf0 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_fun @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[fun .f.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_keywords b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_keywords new file mode 100644 index 0000000..72707eb --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_keywords @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[keywords .kw.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_method b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_method new file mode 100644 index 0000000..c3e33eb --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_method @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[method .m.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_namespace b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_namespace new file mode 100644 index 0000000..22787a9 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_namespace @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[namespace .n.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_opt b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_opt new file mode 100644 index 0000000..3ce4eb9 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_opt @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[opt .o] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_option b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_option new file mode 100644 index 0000000..a605936 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_option @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[option .o.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_package b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_package new file mode 100644 index 0000000..1bdab2c --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_package @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[package .p.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_see_also b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_see_also new file mode 100644 index 0000000..c460dcc --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_see_also @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[see_also .sa.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_syscmd b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_syscmd new file mode 100644 index 0000000..92c94ad --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_syscmd @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[syscmd .t] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_term b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_term new file mode 100644 index 0000000..e2fca6a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_term @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[term .t.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_type b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_type new file mode 100644 index 0000000..86c43b7 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_type @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[type .t.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_uri b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_uri new file mode 100644 index 0000000..b5a048e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_uri @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[uri .u.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_usage b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_usage new file mode 100644 index 0000000..e7ca07e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_usage @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[usage .c.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_var b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_var new file mode 100644 index 0000000..55061fc --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_var @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[var .v] diff --git a/tcllib/modules/doctools/tests/syntax/e_nodonecmd_widget b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_widget new file mode 100644 index 0000000..03ca668 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nodonecmd_widget @@ -0,0 +1,4 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[manpage_end] +[widget .w.] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolistcmd_section b/tcllib/modules/doctools/tests/syntax/e_nolistcmd_section new file mode 100644 index 0000000..d7d052c --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolistcmd_section @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[section foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolistcmd_subsection b/tcllib/modules/doctools/tests/syntax/e_nolistcmd_subsection new file mode 100644 index 0000000..54083f3 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolistcmd_subsection @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad subsection}] +[list_begin definitions] +[subsection foo] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolisthdr_example b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_example new file mode 100644 index 0000000..ba31d74 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_example @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad example before list item}] +[list_begin definitions] +[example {}] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolisthdr_example_begin b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_example_begin new file mode 100644 index 0000000..8bf39d9 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_example_begin @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad example_begin before list item}] +[list_begin definitions] +[example_begin] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolisthdr_list_begin b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_list_begin new file mode 100644 index 0000000..640dbd2 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_list_begin @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad list_begin before list item}] +[list_begin definitions] +[list_begin definitions] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolisthdr_para b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_para new file mode 100644 index 0000000..eaf06ca --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_para @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad para before list item}] +[list_begin definitions] +[para] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolisthdr_sectref b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_sectref new file mode 100644 index 0000000..dcd12cc --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolisthdr_sectref @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad sectref S before list item}] +[list_begin definitions] +[sectref S] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_nolisttxt b/tcllib/modules/doctools/tests/syntax/e_nolisttxt new file mode 100644 index 0000000..25d55d8 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_nolisttxt @@ -0,0 +1,7 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[list_begin definitions] +Text between list_begin and first item is not allowed +[def foo] +[list_end] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_opt_list b/tcllib/modules/doctools/tests/syntax/e_opt_list new file mode 100644 index 0000000..2b19792 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_opt_list @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[opt_def .option.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/e_tkoption_list b/tcllib/modules/doctools/tests/syntax/e_tkoption_list new file mode 100644 index 0000000..cc8daa8 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/e_tkoption_list @@ -0,0 +1,6 @@ +[manpage_begin ERROR e 2.71828182845904523536] +[description] +[comment {bad section}] +[list_begin definitions] +[tkoption_def .option. .dbname. .dbclass.] +[manpage_end] diff --git a/tcllib/modules/doctools/tests/syntax/r_arg_list b/tcllib/modules/doctools/tests/syntax/r_arg_list new file mode 100644 index 0000000..606ce63 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_arg_list @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[arg_def arg-type arg-name] +--> (FmtError) Manpage error (arg_list), "arg_def arg-type arg-name" : Command restricted to usage in argument lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_body b/tcllib/modules/doctools/tests/syntax/r_body new file mode 100644 index 0000000..fe30a1d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_body @@ -0,0 +1,4 @@ +Doctools Error in plain text at line 1, column 0: +[plain_text {Text before manpag...] +--> (FmtError) Manpage error (body), "plain_text Text before manpage_begin is not allowed +" : Plain text not allowed outside of the body of the manpage.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def1 new file mode 100644 index 0000000..e4c56aa --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[arg_def arg-type arg-name] +--> (FmtError) Manpage error (bodycmd), "arg_def arg-type arg-name" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def2 new file mode 100644 index 0000000..39fc9e5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[arg_def arg-type arg-name] +--> (FmtError) Manpage error (bodycmd), "arg_def arg-type arg-name" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def3 new file mode 100644 index 0000000..8fad811 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_arg_def3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[arg_def arg-type arg-name] +--> (FmtError) Manpage error (bodycmd), "arg_def arg-type arg-name" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_call1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_call1 new file mode 100644 index 0000000..7db2378 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_call1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[call .command.] +--> (FmtError) Manpage error (bodycmd), "call .command." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_call2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_call2 new file mode 100644 index 0000000..ab2b451 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_call2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[call .command.] +--> (FmtError) Manpage error (bodycmd), "call .command." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_call3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_call3 new file mode 100644 index 0000000..812f343 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_call3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[call .command.] +--> (FmtError) Manpage error (bodycmd), "call .command." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def1 new file mode 100644 index 0000000..cc165d1 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[cmd_def .command.] +--> (FmtError) Manpage error (bodycmd), "cmd_def .command." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def2 new file mode 100644 index 0000000..ef2562d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[cmd_def .command.] +--> (FmtError) Manpage error (bodycmd), "cmd_def .command." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def3 new file mode 100644 index 0000000..c9839a7 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_cmd_def3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[cmd_def .command.] +--> (FmtError) Manpage error (bodycmd), "cmd_def .command." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_def1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_def1 new file mode 100644 index 0000000..d1a6f48 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_def1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[def] +--> (FmtError) Manpage error (bodycmd), "def" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_def2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_def2 new file mode 100644 index 0000000..2fbf5fa --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_def2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[def] +--> (FmtError) Manpage error (bodycmd), "def" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_def3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_def3 new file mode 100644 index 0000000..70be81e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_def3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[def] +--> (FmtError) Manpage error (bodycmd), "def" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum1 new file mode 100644 index 0000000..5a7f4e3 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[enum] +--> (FmtError) Manpage error (bodycmd), "enum" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum2 new file mode 100644 index 0000000..241255f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[enum] +--> (FmtError) Manpage error (bodycmd), "enum" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum3 new file mode 100644 index 0000000..a772fce --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_enum3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[enum] +--> (FmtError) Manpage error (bodycmd), "enum" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_example1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example1 new file mode 100644 index 0000000..9aa7d2e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[example {}] +--> (FmtError) Manpage error (bodycmd), "example " : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_example2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example2 new file mode 100644 index 0000000..b6b622d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[example {}] +--> (FmtError) Manpage error (bodycmd), "example " : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_example3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example3 new file mode 100644 index 0000000..6fe07d4 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[example {}] +--> (FmtError) Manpage error (bodycmd), "example " : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin1 new file mode 100644 index 0000000..15e9da6 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[example_begin] +--> (FmtError) Manpage error (bodycmd), "example_begin" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin2 new file mode 100644 index 0000000..78b0f04 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[example_begin] +--> (FmtError) Manpage error (bodycmd), "example_begin" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin3 new file mode 100644 index 0000000..ccbc316 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_example_begin3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[example_begin] +--> (FmtError) Manpage error (bodycmd), "example_begin" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_item1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_item1 new file mode 100644 index 0000000..d4b8d2f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_item1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[item] +--> (FmtError) Manpage error (bodycmd), "item" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_item2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_item2 new file mode 100644 index 0000000..0e10f63 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_item2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[item] +--> (FmtError) Manpage error (bodycmd), "item" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_item3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_item3 new file mode 100644 index 0000000..264c774 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_item3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[item] +--> (FmtError) Manpage error (bodycmd), "item" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin1 new file mode 100644 index 0000000..662206d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[list_begin definitions] +--> (FmtError) Manpage error (bodycmd), "list_begin definitions" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin2 new file mode 100644 index 0000000..d14f992 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[list_begin definitions] +--> (FmtError) Manpage error (bodycmd), "list_begin definitions" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin3 new file mode 100644 index 0000000..5d8eb05 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_begin3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[list_begin definitions] +--> (FmtError) Manpage error (bodycmd), "list_begin definitions" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end1 new file mode 100644 index 0000000..8ba3285 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[list_end] +--> (FmtError) Manpage error (bodycmd), "list_end" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end2 new file mode 100644 index 0000000..7ccc09a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[list_end] +--> (FmtError) Manpage error (bodycmd), "list_end" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end3 new file mode 100644 index 0000000..e730c2b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_list_end3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[list_end] +--> (FmtError) Manpage error (bodycmd), "list_end" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_manpage_end b/tcllib/modules/doctools/tests/syntax/r_bodycmd_manpage_end new file mode 100644 index 0000000..5ec9b9b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_manpage_end @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[manpage_end] +--> (FmtError) Manpage error (bodycmd), "manpage_end" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def1 new file mode 100644 index 0000000..6f942b4 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[opt_def .option.] +--> (FmtError) Manpage error (bodycmd), "opt_def .option." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def2 new file mode 100644 index 0000000..1cffe35 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[opt_def .option.] +--> (FmtError) Manpage error (bodycmd), "opt_def .option." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def3 new file mode 100644 index 0000000..9a4fa68 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_opt_def3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[opt_def .option.] +--> (FmtError) Manpage error (bodycmd), "opt_def .option." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_para1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_para1 new file mode 100644 index 0000000..1f9f86f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_para1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[para] +--> (FmtError) Manpage error (bodycmd), "para" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_para2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_para2 new file mode 100644 index 0000000..7d01ae5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_para2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[para] +--> (FmtError) Manpage error (bodycmd), "para" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_para3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_para3 new file mode 100644 index 0000000..e726810 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_para3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[para] +--> (FmtError) Manpage error (bodycmd), "para" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_section1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_section1 new file mode 100644 index 0000000..82a7d7d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_section1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[section foo] +--> (FmtError) Manpage error (bodycmd), "section foo" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_section2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_section2 new file mode 100644 index 0000000..e210e8a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_section2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[section foo] +--> (FmtError) Manpage error (bodycmd), "section foo" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_section3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_section3 new file mode 100644 index 0000000..5c7d0d1 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_section3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[section foo] +--> (FmtError) Manpage error (bodycmd), "section foo" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref1 new file mode 100644 index 0000000..dd0adf6 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[sectref S] +--> (FmtError) Manpage error (bodycmd), "sectref S" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref2 new file mode 100644 index 0000000..042c226 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[sectref S] +--> (FmtError) Manpage error (bodycmd), "sectref S" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref3 new file mode 100644 index 0000000..7ea9783 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_sectref3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[sectref S] +--> (FmtError) Manpage error (bodycmd), "sectref S" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection1 new file mode 100644 index 0000000..6816e38 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[subsection foo] +--> (FmtError) Manpage error (bodycmd), "subsection foo" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection2 new file mode 100644 index 0000000..92738e0 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[subsection foo] +--> (FmtError) Manpage error (bodycmd), "subsection foo" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection3 new file mode 100644 index 0000000..659ac48 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_subsection3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[subsection foo] +--> (FmtError) Manpage error (bodycmd), "subsection foo" : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def1 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def1 new file mode 100644 index 0000000..76876b6 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[tkoption_def .option. .dbname....] +--> (FmtError) Manpage error (bodycmd), "tkoption_def .option. .dbname. .dbclass." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def2 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def2 new file mode 100644 index 0000000..a2547e8 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[tkoption_def .option. .dbname....] +--> (FmtError) Manpage error (bodycmd), "tkoption_def .option. .dbname. .dbclass." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def3 b/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def3 new file mode 100644 index 0000000..5599f07 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bodycmd_tkoption_def3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[tkoption_def .option. .dbname....] +--> (FmtError) Manpage error (bodycmd), "tkoption_def .option. .dbname. .dbclass." : Command not allowed outside of the body of the manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_bulletlist b/tcllib/modules/doctools/tests/syntax/r_bulletlist new file mode 100644 index 0000000..6a0ff5a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_bulletlist @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[item] +--> (FmtError) Manpage error (bulletlist), "item" : Command restricted to usage in itemized lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_cmd_list b/tcllib/modules/doctools/tests/syntax/r_cmd_list new file mode 100644 index 0000000..4d88a92 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_cmd_list @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[cmd_def .command.] +--> (FmtError) Manpage error (cmd_list), "cmd_def .command." : Command restricted to usage in command lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_deflist_call b/tcllib/modules/doctools/tests/syntax/r_deflist_call new file mode 100644 index 0000000..dbc836b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_deflist_call @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[call .command.] +--> (FmtError) Manpage error (deflist), "call .command." : Command restricted to usage in definition lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_deflist_def b/tcllib/modules/doctools/tests/syntax/r_deflist_def new file mode 100644 index 0000000..78ea873 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_deflist_def @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[def] +--> (FmtError) Manpage error (deflist), "def" : Command restricted to usage in definition lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_end_open_example b/tcllib/modules/doctools/tests/syntax/r_end_open_example new file mode 100644 index 0000000..c94311b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_end_open_example @@ -0,0 +1 @@ +(FmtError) Manpage error (end/open/example), "ck_complete" : End of manpage reached, [example_end] missing. diff --git a/tcllib/modules/doctools/tests/syntax/r_end_open_list b/tcllib/modules/doctools/tests/syntax/r_end_open_list new file mode 100644 index 0000000..175ed88 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_end_open_list @@ -0,0 +1 @@ +(FmtError) Manpage error (end/open/list), "ck_complete" : End of manpage reached, [list_end] missing. diff --git a/tcllib/modules/doctools/tests/syntax/r_end_open_mp b/tcllib/modules/doctools/tests/syntax/r_end_open_mp new file mode 100644 index 0000000..0098167 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_end_open_mp @@ -0,0 +1 @@ +(FmtError) Manpage error (end/open/mp), "ck_complete" : End of manpage reached, [manpage_end] missing. diff --git a/tcllib/modules/doctools/tests/syntax/r_enumlist b/tcllib/modules/doctools/tests/syntax/r_enumlist new file mode 100644 index 0000000..02dbc99 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_enumlist @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[enum] +--> (FmtError) Manpage error (enumlist), "enum" : Command restricted to usage in enumerated lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_examplecmd1 b/tcllib/modules/doctools/tests/syntax/r_examplecmd1 new file mode 100644 index 0000000..73e8afa --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_examplecmd1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[example_end] +--> (FmtError) Manpage error (examplecmd), "example_end" : Command allowed only to close example section. diff --git a/tcllib/modules/doctools/tests/syntax/r_examplecmd2 b/tcllib/modules/doctools/tests/syntax/r_examplecmd2 new file mode 100644 index 0000000..cdeb0f9 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_examplecmd2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[example_end] +--> (FmtError) Manpage error (examplecmd), "example_end" : Command allowed only to close example section. diff --git a/tcllib/modules/doctools/tests/syntax/r_examplecmd3 b/tcllib/modules/doctools/tests/syntax/r_examplecmd3 new file mode 100644 index 0000000..fef7b3e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_examplecmd3 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[example_end] +--> (FmtError) Manpage error (examplecmd), "example_end" : Command allowed only to close example section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_copyright1 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_copyright1 new file mode 100644 index 0000000..d553b7a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_copyright1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[copyright foo] +--> (FmtError) Manpage error (hdrcmd), "copyright foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_copyright2 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_copyright2 new file mode 100644 index 0000000..c52e120 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_copyright2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 3, column 0: +[copyright foo] +--> (FmtError) Manpage error (hdrcmd), "copyright foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_description1 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_description1 new file mode 100644 index 0000000..efc4e0d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_description1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[description] +--> (FmtError) Manpage error (hdrcmd), "description" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_description2 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_description2 new file mode 100644 index 0000000..4513c72 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_description2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 3, column 0: +[description] +--> (FmtError) Manpage error (hdrcmd), "description" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_moddesc1 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_moddesc1 new file mode 100644 index 0000000..540b3eb --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_moddesc1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[moddesc foo] +--> (FmtError) Manpage error (hdrcmd), "moddesc foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_moddesc2 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_moddesc2 new file mode 100644 index 0000000..6dea202 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_moddesc2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 3, column 0: +[moddesc foo] +--> (FmtError) Manpage error (hdrcmd), "moddesc foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_require1 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_require1 new file mode 100644 index 0000000..2967dda --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_require1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[require foo] +--> (FmtError) Manpage error (hdrcmd), "require foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_require2 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_require2 new file mode 100644 index 0000000..cc2a0d7 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_require2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 3, column 0: +[require foo] +--> (FmtError) Manpage error (hdrcmd), "require foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_titledesc1 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_titledesc1 new file mode 100644 index 0000000..bfaea22 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_titledesc1 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 1, column 0: +[titledesc foo] +--> (FmtError) Manpage error (hdrcmd), "titledesc foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_hdrcmd_titledesc2 b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_titledesc2 new file mode 100644 index 0000000..feb3d12 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_hdrcmd_titledesc2 @@ -0,0 +1,3 @@ +Doctools Error in macro at line 3, column 0: +[titledesc foo] +--> (FmtError) Manpage error (hdrcmd), "titledesc foo" : Command not allowed outside of the header section. diff --git a/tcllib/modules/doctools/tests/syntax/r_invalidlist_list_begin b/tcllib/modules/doctools/tests/syntax/r_invalidlist_list_begin new file mode 100644 index 0000000..08bb149 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_invalidlist_list_begin @@ -0,0 +1,3 @@ +Doctools Error in macro at line 3, column 0: +[list_begin bogus] +--> (FmtError) Manpage error (invalidlist), "list_begin bogus" : Invalid list type "bogus". diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_arg_def b/tcllib/modules/doctools/tests/syntax/r_listcmd_arg_def new file mode 100644 index 0000000..5b7dead --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_arg_def @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[arg_def arg-type arg-name] +--> (FmtError) Manpage error (listcmd), "arg_def arg-type arg-name" : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_call b/tcllib/modules/doctools/tests/syntax/r_listcmd_call new file mode 100644 index 0000000..654d685 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_call @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[call .command.] +--> (FmtError) Manpage error (listcmd), "call .command." : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_cmd_def b/tcllib/modules/doctools/tests/syntax/r_listcmd_cmd_def new file mode 100644 index 0000000..08f6e63 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_cmd_def @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[cmd_def .command.] +--> (FmtError) Manpage error (listcmd), "cmd_def .command." : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_def b/tcllib/modules/doctools/tests/syntax/r_listcmd_def new file mode 100644 index 0000000..d37f8b6 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_def @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[def] +--> (FmtError) Manpage error (listcmd), "def" : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_enum b/tcllib/modules/doctools/tests/syntax/r_listcmd_enum new file mode 100644 index 0000000..3511aa0 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_enum @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[enum] +--> (FmtError) Manpage error (listcmd), "enum" : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_item b/tcllib/modules/doctools/tests/syntax/r_listcmd_item new file mode 100644 index 0000000..6a0ce9a --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_item @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[item] +--> (FmtError) Manpage error (listcmd), "item" : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_opt_def b/tcllib/modules/doctools/tests/syntax/r_listcmd_opt_def new file mode 100644 index 0000000..fe99798 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_opt_def @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[opt_def .option.] +--> (FmtError) Manpage error (listcmd), "opt_def .option." : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_listcmd_tkoption_def b/tcllib/modules/doctools/tests/syntax/r_listcmd_tkoption_def new file mode 100644 index 0000000..868a7d2 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_listcmd_tkoption_def @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[tkoption_def .option. .dbname....] +--> (FmtError) Manpage error (listcmd), "tkoption_def .option. .dbname. .dbclass." : Command not allowed outside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_mpbegin b/tcllib/modules/doctools/tests/syntax/r_mpbegin new file mode 100644 index 0000000..c0a4637 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_mpbegin @@ -0,0 +1,3 @@ +Doctools Error in macro at line 2, column 0: +[manpage_begin BOGUS e 2.718281...] +--> (FmtError) Manpage error (mpbegin), "manpage_begin BOGUS e 2.71828182845904523536" : Command must be first of manpage. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_arg b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_arg new file mode 100644 index 0000000..e4215d2 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_arg @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[arg .a.] +--> (FmtError) Manpage error (nodonecmd), "arg .a." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_class b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_class new file mode 100644 index 0000000..82e1c96 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_class @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[class .c.] +--> (FmtError) Manpage error (nodonecmd), "class .c." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_cmd b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_cmd new file mode 100644 index 0000000..7932343 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_cmd @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[cmd .c.] +--> (FmtError) Manpage error (nodonecmd), "cmd .c." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_comment b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_comment new file mode 100644 index 0000000..00cc8d5 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_comment @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[comment .c] +--> (FmtError) Manpage error (nodonecmd), "comment .c" : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_const b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_const new file mode 100644 index 0000000..ae86794 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_const @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[const .c.] +--> (FmtError) Manpage error (nodonecmd), "const .c." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_emph b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_emph new file mode 100644 index 0000000..ca55b52 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_emph @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[emph .t.] +--> (FmtError) Manpage error (nodonecmd), "emph .t." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_file b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_file new file mode 100644 index 0000000..fc19a8f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_file @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[file .f.] +--> (FmtError) Manpage error (nodonecmd), "file .f." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_fun b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_fun new file mode 100644 index 0000000..c446c03 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_fun @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[fun .f.] +--> (FmtError) Manpage error (nodonecmd), "fun .f." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_keywords b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_keywords new file mode 100644 index 0000000..71a11dd --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_keywords @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[keywords .kw.] +--> (FmtError) Manpage error (nodonecmd), "keywords .kw." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_method b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_method new file mode 100644 index 0000000..89763df --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_method @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[method .m.] +--> (FmtError) Manpage error (nodonecmd), "method .m." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_namespace b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_namespace new file mode 100644 index 0000000..98f5f6c --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_namespace @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[namespace .n.] +--> (FmtError) Manpage error (nodonecmd), "_namespace .n." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_opt b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_opt new file mode 100644 index 0000000..55cf23e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_opt @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[opt .o] +--> (FmtError) Manpage error (nodonecmd), "opt .o" : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_option b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_option new file mode 100644 index 0000000..8566066 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_option @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[option .o.] +--> (FmtError) Manpage error (nodonecmd), "option .o." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_package b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_package new file mode 100644 index 0000000..f4786b4 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_package @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[package .p.] +--> (FmtError) Manpage error (nodonecmd), "package .p." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_see_also b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_see_also new file mode 100644 index 0000000..8f86a85 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_see_also @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[see_also .sa.] +--> (FmtError) Manpage error (nodonecmd), "see_also .sa." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_syscmd b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_syscmd new file mode 100644 index 0000000..fea66ba --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_syscmd @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[syscmd .t] +--> (FmtError) Manpage error (nodonecmd), "syscmd .t" : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_term b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_term new file mode 100644 index 0000000..87b0508 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_term @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[term .t.] +--> (FmtError) Manpage error (nodonecmd), "term .t." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_type b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_type new file mode 100644 index 0000000..6215855 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_type @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[type .t.] +--> (FmtError) Manpage error (nodonecmd), "type .t." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_uri b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_uri new file mode 100644 index 0000000..ff69b3e --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_uri @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[uri .u.] +--> (FmtError) Manpage error (nodonecmd), "uri .u." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_usage b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_usage new file mode 100644 index 0000000..e8591be --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_usage @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[usage .c.] +--> (FmtError) Manpage error (nodonecmd), "usage .c." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_var b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_var new file mode 100644 index 0000000..f5452aa --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_var @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[var .v] +--> (FmtError) Manpage error (nodonecmd), "var .v" : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nodonecmd_widget b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_widget new file mode 100644 index 0000000..534cec2 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nodonecmd_widget @@ -0,0 +1,3 @@ +Doctools Error in macro at line 4, column 0: +[widget .w.] +--> (FmtError) Manpage error (nodonecmd), "widget .w." : Command not allowed after [manpage_end]. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolistcmd_section b/tcllib/modules/doctools/tests/syntax/r_nolistcmd_section new file mode 100644 index 0000000..105d626 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolistcmd_section @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[section foo] +--> (FmtError) Manpage error (nolistcmd), "section foo" : Command not allowed inside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolistcmd_subsection b/tcllib/modules/doctools/tests/syntax/r_nolistcmd_subsection new file mode 100644 index 0000000..6f6480d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolistcmd_subsection @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[subsection foo] +--> (FmtError) Manpage error (nolistcmd), "subsection foo" : Command not allowed inside of a list. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolisthdr_example b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_example new file mode 100644 index 0000000..2c6c41f --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_example @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[example {}] +--> (FmtError) Manpage error (nolisthdr), "example " : Command not allowed between beginning of a list and its first item. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolisthdr_example_begin b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_example_begin new file mode 100644 index 0000000..27f659d --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_example_begin @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[example_begin] +--> (FmtError) Manpage error (nolisthdr), "example_begin" : Command not allowed between beginning of a list and its first item. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolisthdr_list_begin b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_list_begin new file mode 100644 index 0000000..a96686b --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_list_begin @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[list_begin definitions] +--> (FmtError) Manpage error (nolisthdr), "list_begin definitions" : Command not allowed between beginning of a list and its first item. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolisthdr_para b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_para new file mode 100644 index 0000000..93ab335 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_para @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[para] +--> (FmtError) Manpage error (nolisthdr), "para" : Command not allowed between beginning of a list and its first item. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolisthdr_sectref b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_sectref new file mode 100644 index 0000000..3f30687 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolisthdr_sectref @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[sectref S] +--> (FmtError) Manpage error (nolisthdr), "sectref S" : Command not allowed between beginning of a list and its first item. diff --git a/tcllib/modules/doctools/tests/syntax/r_nolisttxt b/tcllib/modules/doctools/tests/syntax/r_nolisttxt new file mode 100644 index 0000000..42f2160 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_nolisttxt @@ -0,0 +1,6 @@ +Doctools Error in plain text at line 3, column 24: +[plain_text { +Text between list...] +--> (FmtError) Manpage error (nolisttxt), "plain_text +Text between list_begin and first item is not allowed +" : Plain text not allowed between beginning of a list and its first item. diff --git a/tcllib/modules/doctools/tests/syntax/r_opt_list b/tcllib/modules/doctools/tests/syntax/r_opt_list new file mode 100644 index 0000000..3b7d384 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_opt_list @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[opt_def .option.] +--> (FmtError) Manpage error (opt_list), "opt_def .option." : Command restricted to usage in option lists. diff --git a/tcllib/modules/doctools/tests/syntax/r_tkoption_list b/tcllib/modules/doctools/tests/syntax/r_tkoption_list new file mode 100644 index 0000000..a9de502 --- /dev/null +++ b/tcllib/modules/doctools/tests/syntax/r_tkoption_list @@ -0,0 +1,3 @@ +Doctools Error in macro at line 5, column 0: +[tkoption_def .option. .dbname....] +--> (FmtError) Manpage error (tkoption_list), "tkoption_def .option. .dbname. .dbclass." : Command restricted to usage in tkoption lists. diff --git a/tcllib/modules/doctools/tests/text/00 b/tcllib/modules/doctools/tests/text/00 new file mode 100644 index 0000000..c4adc22 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/00 @@ -0,0 +1,17 @@ + +TEST - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "" + +NAME +==== + +TEST - + +DESCRIPTION +=========== + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/01 b/tcllib/modules/doctools/tests/text/01 new file mode 100644 index 0000000..742f125 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/01 @@ -0,0 +1,24 @@ + +TEST - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "" + +NAME +==== + +TEST - + +DESCRIPTION +=========== + +Argument ::Argument:: Class ::*Class*:: Command ::Command:: Comment :::: Const +::*Constant*:: Emphasis ::_Emphasis_:: File ::"File/Path":: Function +::*Function*:: Method ::Method:: Namespace ::*Namespace*:: Option ::Option:: +Optional ::?Optional?:: Package ::*Package*:: Syscmd ::*SystemCommand*:: Term +::_Term_:: Type ::*Type*:: Uri ::<URL:Uri>:: Variable ::*Variable*:: Widget +::*Widget*:: + +COPYRIGHT +========= + +Copyright (c) **Copyright**
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/02 b/tcllib/modules/doctools/tests/text/02 new file mode 100644 index 0000000..8d72762 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/02 @@ -0,0 +1,33 @@ + +TEST - ..THE_MODULE.. +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "..THE_MODULE.." + +NAME +==== + +TEST - ..THE_TITLE.. + +SYNOPSIS +======== + +package require AAA +package require BBB VVV + +DESCRIPTION +=========== + +SEE ALSO +======== + +ELSE, OTHER + +KEYWORDS +======== + +KEYA, KEYZ + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/03 b/tcllib/modules/doctools/tests/text/03 new file mode 100644 index 0000000..5880409 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/03 @@ -0,0 +1,46 @@ + +TEST - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "" + +NAME +==== + +TEST - + +DESCRIPTION +=========== + +AaA +=== + +1 + +BbB +=== + +22 + +BbB.cCc +------- + +333 + +BbB.dDd +------- + +4444 + +EeE +=== + +5555 + +At -> AaA. + +At -> __undefined__. + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/04 b/tcllib/modules/doctools/tests/text/04 new file mode 100644 index 0000000..25d3f98 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/04 @@ -0,0 +1,28 @@ + +TEST - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "" + +NAME +==== + +TEST - + +DESCRIPTION +=========== + +BEGINNE HIER + + +| Example Block More Lines + + +| Inlined Example \ +| Next Line + +FERTIG + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/05 b/tcllib/modules/doctools/tests/text/05 new file mode 100644 index 0000000..7ac98f2 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/05 @@ -0,0 +1,86 @@ + +BASIC - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +BASIC(a) 5 .MODULE. "" + +NAME +==== + +BASIC - + +SYNOPSIS +======== + +a-command + +DESCRIPTION +=========== + +OK + + integer argument-1 + + verification + + string argument-2 (out) + + mogrification + + command-a + + explanation + + command-b + + elucidation + + term + + definition + + a-command + + semantic + + [1] A + + [2] B + + C + + D + + * 1 + + * 2 + + 2a + + 2b + + option-1 + + meaning + + option-2 value + + elaboration + + Command-Line Switch: background + Database Name: *Background* + Database Class: *Color* + + candy + + Command-Line Switch: foreground + Database Name: *Foreground* + Database Class: *Color* + + caramel + +KO + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/06 b/tcllib/modules/doctools/tests/text/06 new file mode 100644 index 0000000..dac1bdf --- /dev/null +++ b/tcllib/modules/doctools/tests/text/06 @@ -0,0 +1,53 @@ + +TEST - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "" + +NAME +==== + +TEST - + +DESCRIPTION +=========== + + * 1 + + 2 + + 3 + + [1] a + + b + + c + + foo + + snafu + + bar + + barf + + roo + + gork + + [2] a + + b + + c + + * 4 + + 5 + + 6 + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/07 b/tcllib/modules/doctools/tests/text/07 new file mode 100644 index 0000000..3d9f378 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/07 @@ -0,0 +1,45 @@ + +TEST - +Generated from file '.FILE.' by tcllib/doctools with format 'text' +TEST(z) 3.14.15.926 .MODULE. "" + +NAME +==== + +TEST - + +DESCRIPTION +=========== + + * 1 + + * 2 + + [1] a + + [2] b + + foo + + snafu + + bar + + barf + + roo + + gork + + [3] bb + + [4] a + + * 22 + + * 3 + +COPYRIGHT +========= + +Copyright (c) .COPYRIGHT.
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/text/08 b/tcllib/modules/doctools/tests/text/08 new file mode 100644 index 0000000..4e85271 --- /dev/null +++ b/tcllib/modules/doctools/tests/text/08 @@ -0,0 +1,138 @@ + +ALL - ..THE_MODULE.. +Generated from file '.FILE.' by tcllib/doctools with format 'text' +ALL(a) 5 .MODULE. "..THE_MODULE.." + +NAME +==== + +ALL - ..THE_TITLE.. + +SYNOPSIS +======== + +package require AAA +package require BBB VVV +package require CCC ?VVV? + +CMDNAME ... +CMDNAME ... +CMDNAME ... + +DESCRIPTION +=========== + + NAME + + DESCRIPTION ::Command:: + + NAME + + DESCRIPTION :::: + + NAME + + DESCRIPTION ::*Constant*:: + +API +=== + + TERM + + DESCRIPTION ::_Emphasis_:: + + TERM + + DESCRIPTION ::"File/Path":: + + Command-Line Switch: NAME + Database Name: *DBNAME* + Database Class: *CLASS* + + DESCRIPTION -> NARGLE + + Command-Line Switch: NAME + Database Name: *DBNAME* + Database Class: *CLASS* + + DESCRIPTION ::*Function*:: + + Command-Line Switch: NAME + Database Name: *DBNAME* + Database Class: *CLASS* + + DESCRIPTION ::Method:: + + TERM + + DESCRIPTION + + CMDNAME ... + + DESCRIPTION ::*Namespace*:: + + TYPE NAME + + DESCRIPTION ::Argument:: + + TYPE NAME + + DESCRIPTION ::Option:: + + TYPE NAME (MODE) + + DESCRIPTION ::?Optional?:: + + + | THE ARGUMENT IS USED IN THIS + | AND/OR THAT MANNER + + CMDNAME ... + + DESCRIPTION ::*Package*:: + + CMDNAME ... + + DESCRIPTION ::*SystemCommand*:: + + NAME + + DESCRIPTION ::_Term_:: + + NAME + + DESCRIPTION ::*Type*:: + + NAME ARGUMENT + + DESCRIPTION ::<URL:Uri>:: + +NARGLE +------ + + [1] PARAGRAPH ::_UriLabel_ <URL:Uri>:: + + [2] PARAGRAPH ::*Variable*:: + + [3] PARAGRAPH ::*Widget*:: + + * PARAGRAPH ::*Class*:: + + * PARAGRAPH + + * PARAGRAPH + +SEE ALSO +======== + +ELSE, OTHER + +KEYWORDS +======== + +KEYA, KEYZ + +COPYRIGHT +========= + +Copyright (c) **Copyright**
\ No newline at end of file diff --git a/tcllib/modules/doctools/tests/tmml/00 b/tcllib/modules/doctools/tests/tmml/00 new file mode 100644 index 0000000..ad98243 --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/00 @@ -0,0 +1,19 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>TEST</name> +<desc></desc> + +</namesection> + + +<section id='section1'> +<title>DESCRIPTION</title> +</section> + + + +</manpage> diff --git a/tcllib/modules/doctools/tests/tmml/01 b/tcllib/modules/doctools/tests/tmml/01 new file mode 100644 index 0000000..795300f --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/01 @@ -0,0 +1,39 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) **Copyright**'/> +</head> +<namesection> +<name>TEST</name> +<desc></desc> + +</namesection> + + + +<section id='section1'> +<title>DESCRIPTION</title> +Argument ::<m>Argument</m>:: +Class ::<class>Class</class>:: +Command ::<cmd>Command</cmd>:: +Comment :::: +Const ::<l>Constant</l>:: +Emphasis ::<emph>Emphasis</emph>:: +File ::<file>File/Path</file>:: +Function ::<fun>Function</fun>:: +Method ::<method>Method</method>:: +Namespace ::<term>Namespace</term>:: +Option ::<option>Option</option>:: +Optional ::<o>Optional</o>:: +Package ::<package>Package</package>:: +Syscmd ::<syscmd>SystemCommand</syscmd>:: +Term ::<term>Term</term>:: +Type ::<type>Type</type>:: +Uri ::<url>Uri</url>:: +Variable ::<variable>Variable</variable>:: +Widget ::<widget>Widget</widget>:: +</section> + + + +</manpage> diff --git a/tcllib/modules/doctools/tests/tmml/02 b/tcllib/modules/doctools/tests/tmml/02 new file mode 100644 index 0000000..4a33616 --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/02 @@ -0,0 +1,36 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>TEST</name> +<desc>..THE_TITLE..</desc> + +</namesection> + + + + + + + +<synopsis> +<syntax> +package require <package>AAA</package> +package require <package>BBB</package> VVV +</syntax> +</synopsis> +<section id='section1'> +<title>DESCRIPTION</title> +</section> +<seealso> +<ref>OTHER</ref> +<ref>ELSE</ref> +</seealso> +<keywords> +<keyword>KEYA</keyword> +<keyword>KEYZ</keyword> +</keywords> + +</manpage> diff --git a/tcllib/modules/doctools/tests/tmml/03 b/tcllib/modules/doctools/tests/tmml/03 new file mode 100644 index 0000000..6b96884 --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/03 @@ -0,0 +1,49 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>TEST</name> +<desc></desc> + +</namesection> + + +<section id='section1'> +<title>DESCRIPTION</title> +</section> +<section id='section2'> +<title>AAA</title> +1 +</section> +<section id='section3'> +<title>BBB</title> +22 + +<subsection id='subsection1'> +<title>BBB.CCC</title> +333 +</subsection> +<subsection id='subsection2'> +<title>BBB.DDD</title> +4444 +</subsection> +</section> +<section id='section4'> +<title>EEE</title> +5555 + + +<p> +At <ref refid='section2'>AaA</ref>. +</p> +<p> +At <emph>__undefined__</emph>. +</p> +</section> + + + +</manpage> + diff --git a/tcllib/modules/doctools/tests/tmml/04 b/tcllib/modules/doctools/tests/tmml/04 new file mode 100644 index 0000000..c6cf13b --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/04 @@ -0,0 +1,37 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>TEST</name> +<desc></desc> + +</namesection> + + +<section id='section1'> +<title>DESCRIPTION</title> +BEGINNE HIER + +<example> + Example Block More Lines + +</example> + +<p> +</p> +<p> +</p> +<example> +Inlined Example \ +Next Line + +</example> +FERTIG +</section> + + + +</manpage> + diff --git a/tcllib/modules/doctools/tests/tmml/05 b/tcllib/modules/doctools/tests/tmml/05 new file mode 100644 index 0000000..250838e --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/05 @@ -0,0 +1,162 @@ + +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='BASIC' version='5' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>BASIC</name> +<desc></desc> + +</namesection> + +<synopsis> +<syntax> +a-command +</syntax> +</synopsis> +<section id='section1'> +<title>DESCRIPTION</title> +OK + +<p> +</p> +<arglist> + +<argdef> +<argtype>integer</argtype> +<name>argument-1</name> + +<desc> +verification +</desc> +</argdef> +<argdef> +<argtype>string</argtype> +<name>argument-2</name> +<argmode>out</argmode> +<desc> mogrification +</desc> +</argdef> + +</arglist> + +<p> +</p> +<commandlist> + +<commanddef> +<command>command-a</command> +<desc> explanation +</desc> +</commanddef> +<commanddef> +<command>command-b</command> +<desc> +elucidation +</desc> +</commanddef> + +</commandlist> + +<p> +</p> +<dl> + +<dle> +<dt>term</dt> +<dd> definition +</dd> +</dle> +<dle> +<dt>a-command </dt> +<dd> +semantic +</dd> +</dle> + +</dl> + +<p> +</p> +<ol> + +<li> +A +</li> +<li> B +<br/> +C +<br/> +D +</li> + +</ol> + +<p> +</p> +<ul> + +<li> +1 +</li> +<li> 2 +<br/> +2a +<br/> +2b +</li> + +</ul> + +<p> +</p> +<optlist> + +<optdef> +<optname>option-1</optname> + +<desc> meaning +</desc> +</optdef> +<optdef> +<optname>option-2</optname> +<optarg>value</optarg> +<desc> +elaboration +</desc> +</optdef> + +</optlist> + +<p> +</p> +<optionlist> + +<optiondef> +<name>background</name> +<dbname>Background</dbname> +<dbclass>Color</dbclass> +<desc> candy +</desc> +</optiondef> +<optiondef> +<name>foreground</name> +<dbname>Foreground</dbname> +<dbclass>Color</dbclass> +<desc> +caramel +</desc> +</optiondef> + +</optionlist> + +<p> +KO + +</p> +</section> + + + +</manpage> diff --git a/tcllib/modules/doctools/tests/tmml/06 b/tcllib/modules/doctools/tests/tmml/06 new file mode 100644 index 0000000..ccad907 --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/06 @@ -0,0 +1,62 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>TEST</name> +<desc></desc> + +</namesection> + + +<section id='section1'> +<title>DESCRIPTION</title> + + +<ul> + +<li> 1 <br/> 2 <br/> 3 +</li> +<li> + +<ol> + +<li> a <br/> b <br/> c +</li> +<li> + +<dl> + +<dle> +<dt>foo</dt> +<dd> snafu +</dd> +</dle> +<dle> +<dt>bar</dt> +<dd> barf +</dd> +</dle> +<dle> +<dt>roo</dt> +<dd> gork +</dd> +</dle> + +</dl> +</li> +<li> a <br/> b <br/> c +</li> + +</ol> +</li> +<li> 4 <br/> 5 <br/> 6 +</li> + +</ul> +</section> + + + +</manpage> diff --git a/tcllib/modules/doctools/tests/tmml/07 b/tcllib/modules/doctools/tests/tmml/07 new file mode 100644 index 0000000..1b1f693 --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/07 @@ -0,0 +1,64 @@ +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='TEST' version='3.14.15.926' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) .COPYRIGHT.'/> +</head> +<namesection> +<name>TEST</name> +<desc></desc> + +</namesection> + + +<section id='section1'> +<title>DESCRIPTION</title> + + +<ul> + +<li> 1 +</li> +<li> 2 + +<ol> + +<li> a +</li> +<li> b + +<dl> + +<dle> +<dt>foo</dt> +<dd> snafu +</dd> +</dle> +<dle> +<dt>bar</dt> +<dd> barf +</dd> +</dle> +<dle> +<dt>roo</dt> +<dd> gork +</dd> +</dle> + +</dl> +bb +</li> +<li> a +</li> + +</ol> +22 +</li> +<li> 3 +</li> + +</ul> +</section> + + + +</manpage> diff --git a/tcllib/modules/doctools/tests/tmml/08 b/tcllib/modules/doctools/tests/tmml/08 new file mode 100644 index 0000000..f2ade2d --- /dev/null +++ b/tcllib/modules/doctools/tests/tmml/08 @@ -0,0 +1,207 @@ + +<!-- Generated from file '.FILE.' by tcllib/doctools with format 'tmml' --> +<manpage id='.FILE' cat='cmd' title='ALL' version='5' package='.MODULE.'> +<head> +<info key='copyright' value='Copyright (c) **Copyright**'/> +</head> +<namesection> +<name>ALL</name> +<desc>..THE_TITLE..</desc> + +</namesection> + + + + + + + +<synopsis> +<syntax> +package require <package>AAA</package> +package require <package>BBB</package> VVV +package require <package>CCC</package> <o>VVV</o> +CMDNAME ... +CMDNAME ... +CMDNAME ... +</syntax> +</synopsis> +<section id='section1'> +<title>DESCRIPTION</title> + +<commandlist> + +<commanddef> +<command>NAME</command> +<desc> DESCRIPTION ::<cmd>Command</cmd>:: +</desc> +</commanddef> +<commanddef> +<command>NAME</command> +<desc> DESCRIPTION :::: +</desc> +</commanddef> +<commanddef> +<command>NAME</command> +<desc> DESCRIPTION ::<l>Constant</l>:: +</desc> +</commanddef> + +</commandlist> +</section> +<section id='section2'> +<title>API</title> + +<dl> + +<dle> +<dt>TERM</dt> +<dd> DESCRIPTION ::<emph>Emphasis</emph>:: +</dd> +</dle> +<dle> +<dt>TERM</dt> +<dd> DESCRIPTION ::<file>File/Path</file>:: + +<optionlist> + +<optiondef> +<name>NAME</name> +<dbname>DBNAME</dbname> +<dbclass>CLASS</dbclass> +<desc> DESCRIPTION <ref refid='subsection1'>NARGLE</ref> +</desc> +</optiondef> +<optiondef> +<name>NAME</name> +<dbname>DBNAME</dbname> +<dbclass>CLASS</dbclass> +<desc> DESCRIPTION ::<fun>Function</fun>:: +</desc> +</optiondef> +<optiondef> +<name>NAME</name> +<dbname>DBNAME</dbname> +<dbclass>CLASS</dbclass> +<desc> DESCRIPTION ::<method>Method</method>:: +</desc> +</optiondef> + +</optionlist> +</dd> +</dle> +<dle> +<dt>TERM</dt> +<dd> DESCRIPTION +</dd> +</dle> +<dle> +<dt>CMDNAME ...</dt> +<dd> DESCRIPTION ::<term>Namespace</term>:: + +<arglist> + +<argdef> +<argtype>TYPE</argtype> +<name>NAME</name> + +<desc> DESCRIPTION ::<m>Argument</m>:: +</desc> +</argdef> +<argdef> +<argtype>TYPE</argtype> +<name>NAME</name> + +<desc> DESCRIPTION ::<option>Option</option>:: +</desc> +</argdef> +<argdef> +<argtype>TYPE</argtype> +<name>NAME</name> +<argmode>MODE</argmode> +<desc> DESCRIPTION ::<o>Optional</o>:: + +<example> + THE ARGUMENT IS USED IN THIS + AND/OR THAT MANNER + +</example> +</desc> +</argdef> + +</arglist> +</dd> +</dle> +<dle> +<dt>CMDNAME ...</dt> +<dd> DESCRIPTION ::<package>Package</package>:: +</dd> +</dle> +<dle> +<dt>CMDNAME ...</dt> +<dd> DESCRIPTION ::<syscmd>SystemCommand</syscmd>:: + +<optlist> + +<optdef> +<optname>NAME</optname> + +<desc> DESCRIPTION ::<term>Term</term>:: +</desc> +</optdef> +<optdef> +<optname>NAME</optname> + +<desc> DESCRIPTION ::<type>Type</type>:: +</desc> +</optdef> +<optdef> +<optname>NAME</optname> +<optarg>ARGUMENT</optarg> +<desc> DESCRIPTION ::<url>Uri</url>:: +</desc> +</optdef> + +</optlist> +</dd> +</dle> + +</dl> + +<subsection id='subsection1'> +<title>NARGLE</title> +</subsection> +<ol> + +<li> PARAGRAPH ::<url>Uri</url>:: +</li> +<li> PARAGRAPH ::<variable>Variable</variable>:: +</li> +<li> PARAGRAPH ::<widget>Widget</widget>:: + +<ul> + +<li> PARAGRAPH ::<class>Class</class>:: +</li> +<li> PARAGRAPH +</li> +<li> PARAGRAPH +</li> + +</ul> +</li> + +</ol> + + +</section> +<seealso> +<ref>OTHER</ref> +<ref>ELSE</ref> +</seealso> +<keywords> +<keyword>KEYA</keyword> +<keyword>KEYZ</keyword> +</keywords> + +</manpage> diff --git a/tcllib/modules/doctools/tests/wiki/00 b/tcllib/modules/doctools/tests/wiki/00 new file mode 100644 index 0000000..de2d99b --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/00 @@ -0,0 +1,13 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' + + + + +**DESCRIPTION** + + + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/01 b/tcllib/modules/doctools/tests/wiki/01 new file mode 100644 index 0000000..f26ca64 --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/01 @@ -0,0 +1,13 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' + + + + +**DESCRIPTION** + +Argument ::''Argument'':: Class ::'''Class''':: Command ::'''Command''':: Comment :::: Const ::'''Constant''':: Emphasis ::''Emphasis'':: File ::"''File/Path''":: Function ::'''Function''':: Method ::'''Method''':: Namespace ::'''Namespace''':: Option ::'''Option''':: Optional ::?Optional?:: Package ::'''Package''':: Syscmd ::'''SystemCommand''':: Term ::''Term'':: Type ::'''Type''':: Uri ::Uri:: Variable ::'''Variable''':: Widget ::'''Widget''':: + +**COPYRIGHT** + + Copyright (c) **Copyright** + diff --git a/tcllib/modules/doctools/tests/wiki/02 b/tcllib/modules/doctools/tests/wiki/02 new file mode 100644 index 0000000..8ef71cf --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/02 @@ -0,0 +1,35 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' ''..THE_MODULE..'' + +..THE_TITLE.. + + +**SYNOPSIS** + + +package require '''AAA''' + +package require '''BBB VVV''' + + + + +**DESCRIPTION** + + + +**SEE ALSO** + + +ELSE, OTHER + + +**KEYWORDS** + + +KEYA, KEYZ + + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/03 b/tcllib/modules/doctools/tests/wiki/03 new file mode 100644 index 0000000..5032e2a --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/03 @@ -0,0 +1,35 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' + + + + +**DESCRIPTION** + + + +**AaA** + +1 + +**BbB** + +22 + +***BbB.cCc*** + +333 + +***BbB.dDd*** + +4444 + +**EeE** + +5555 +At '''AaA'''. +At '''__undefined__'''. + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/04 b/tcllib/modules/doctools/tests/wiki/04 new file mode 100644 index 0000000..6d2258a --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/04 @@ -0,0 +1,28 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' + + + + +**DESCRIPTION** + +BEGINNE HIER +====== + + Example Block More Lines + +====== + + + +====== + +Inlined Example \ +Next Line + +====== +FERTIG + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/05 b/tcllib/modules/doctools/tests/wiki/05 new file mode 100644 index 0000000..f4a628c --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/05 @@ -0,0 +1,66 @@ +'''BASIC 5''' '''.MODULE.''' + + + + +**SYNOPSIS** + + + * a-command + + + + +**DESCRIPTION** + +OK + + ++++ +''argument-1'' integer verification +''argument-2'' string (out) mogrification ++++ + + + + + '''command-a''': explanation + + '''command-b''': elucidation + + + term: definition + + a-command : semantic + + + 1. A + + 1. B C D + + + * 1 + + * 2 2a 2b + + + '''option-1''': meaning + + '''option-2''' value: elaboration + + +Command-Line Switch: '''background''' +Database Name: '''Background''' +Database Class: '''Color''' + * candy + +Command-Line Switch: '''foreground''' +Database Name: '''Foreground''' +Database Class: '''Color''' + * caramel +KO + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/06 b/tcllib/modules/doctools/tests/wiki/06 new file mode 100644 index 0000000..7526701 --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/06 @@ -0,0 +1,31 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' + + + + +**DESCRIPTION** + + + + * 1 2 3 + + * + + 1. a b c + + 1. + + foo: snafu + + bar: barf + + roo: gork + + 1. a b c + + * 4 5 6 + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/07 b/tcllib/modules/doctools/tests/wiki/07 new file mode 100644 index 0000000..e4541bb --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/07 @@ -0,0 +1,31 @@ +'''TEST 3.14.15.926''' '''.MODULE.''' + + + + +**DESCRIPTION** + + + + * 1 + + * 2 + + 1. a + + 1. b + + foo: snafu + + bar: barf + + roo: gork bb + + 1. a 22 + + * 3 + +**COPYRIGHT** + + Copyright (c) .COPYRIGHT. + diff --git a/tcllib/modules/doctools/tests/wiki/08 b/tcllib/modules/doctools/tests/wiki/08 new file mode 100644 index 0000000..0f21169 --- /dev/null +++ b/tcllib/modules/doctools/tests/wiki/08 @@ -0,0 +1,117 @@ +'''ALL 5''' '''.MODULE.''' ''..THE_MODULE..'' + +..THE_TITLE.. + + +**SYNOPSIS** + + +package require '''AAA''' + +package require '''BBB VVV''' + +package require '''CCC ?VVV?''' + + * CMDNAME ... + + * CMDNAME ... + + * CMDNAME ... + + + + +**DESCRIPTION** + + + + '''NAME''': DESCRIPTION ::'''Command''':: + + '''NAME''': DESCRIPTION :::: + + '''NAME''': DESCRIPTION ::'''Constant''':: + +**API** + + + + TERM: DESCRIPTION ::''Emphasis'':: + + TERM: DESCRIPTION ::"''File/Path''":: + +Command-Line Switch: '''NAME''' +Database Name: '''DBNAME''' +Database Class: '''CLASS''' + * DESCRIPTION '''NARGLE''' + +Command-Line Switch: '''NAME''' +Database Name: '''DBNAME''' +Database Class: '''CLASS''' + * DESCRIPTION ::'''Function''':: + +Command-Line Switch: '''NAME''' +Database Name: '''DBNAME''' +Database Class: '''CLASS''' + * DESCRIPTION ::'''Method''':: + + TERM: DESCRIPTION + + CMDNAME ...: DESCRIPTION ::'''Namespace''':: + ++++ +''NAME'' TYPE DESCRIPTION ::''Argument'':: +''NAME'' TYPE DESCRIPTION ::'''Option''':: +''NAME'' TYPE (MODE) DESCRIPTION ::?Optional?:: +====== + + THE ARGUMENT IS USED IN THIS + AND/OR THAT MANNER + +====== + ++++ + + + + CMDNAME ...: DESCRIPTION ::'''Package''':: + + CMDNAME ...: DESCRIPTION ::'''SystemCommand''':: + + '''NAME''': DESCRIPTION ::''Term'':: + + '''NAME''': DESCRIPTION ::'''Type''':: + + '''NAME''' ARGUMENT: DESCRIPTION ::Uri:: + +***NARGLE*** + + + + 1. PARAGRAPH ::Uri%|%UriLabel%|%:: + + 1. PARAGRAPH ::'''Variable''':: + + 1. PARAGRAPH ::'''Widget''':: + + * PARAGRAPH ::'''Class''':: + + * PARAGRAPH + + * PARAGRAPH + +**SEE ALSO** + + +ELSE, OTHER + + +**KEYWORDS** + + +KEYA, KEYZ + + +**COPYRIGHT** + + Copyright (c) **Copyright** + diff --git a/tcllib/modules/doctools/tocexpand b/tcllib/modules/doctools/tocexpand new file mode 100755 index 0000000..e01fc4b --- /dev/null +++ b/tcllib/modules/doctools/tocexpand @@ -0,0 +1,136 @@ +#! /bin/sh +# -*- tcl -*- \ +exec tclsh "$0" ${1+"$@"} + +rename source __source +proc source {path} { + set f [file join [pwd] $path] + uplevel 1 __source $path +} + + +lappend auto_path [file dirname [file dirname [info script]]] +package require doctools::toc + +# --------------------------------------------------------------------- +# 1. Handle command line options, input and output +# 2. Initialize a doctools object. +# 3. Run the input through the object. +# 4. Write output. +# --------------------------------------------------------------------- + +proc usage {{exitstate 1}} { + global argv0 + puts "Usage: $argv0\ + ?-h|--help|-help|-??\ + ?-help-fmt|--help-fmt?\ + format in|- ?out|-?" + exit $exitstate +} + +# --------------------------------------------------------------------- + +proc fmthelp {} { + # Tcllib FR #527029: short reference of formatting commands. + + global argv0 + puts "$argv0 [doctools::toc::help]" + exit 0 +} + +# --------------------------------------------------------------------- +# 1. Handle command line options, input and output + +proc cmdline {} { + global argv0 argv format in out + + set copyright "" + set extmodule "" + set deprecated 0 + + while {[string match -* [set opt [lindex $argv 0]]]} { + switch -exact -- $opt { + -help - -h - --help - -? { + # Tcllib FR #527029 + usage 0 + } + -help-fmt - --help-fmt { + # Tcllib FR #527029 + fmthelp + } + default { + # Unknown option + usage + } + } + } + + if {[llength $argv] < 3} { + usage + } + foreach {format in out} $argv break + + if {$format == {} || $in == {}} { + usage + } + if {$out == {}} {set out -} + return $format +} + +# --------------------------------------------------------------------- +# 3. Read input. Also providing the namespace with file information. + +proc get_input {} { + global in + if {[string equal $in -]} { + return [read stdin] + } else { + set if [open $in r] + set text [read $if] + close $if + return $text + } +} + +# --------------------------------------------------------------------- +# 4. Write output. + +proc write_out {text} { + global out + if {[string equal $out -]} { + puts -nonewline stdout $text + } else { + set of [open $out w] + puts -nonewline $of $text + close $of + } +} + + +# --------------------------------------------------------------------- +# Get it all together + +proc main {} { + global format in + + #if {[catch {} + cmdline + + ::doctools::toc::new dt -format $format + write_out [dt format [get_input]] + + set warnings [dt warnings] + if {[llength $warnings] > 0} { + puts stderr [join $warnings \n] + } + + #{} msg]} {} + #puts stderr "Execution error: $msg" + #{} + return +} + + +# --------------------------------------------------------------------- +main +exit |