TMML | Overview | FAQ

Q: How do I create changebars like in the Tcl man pages?

A:

Many elements take a version attribute, which should contain a standard major.minor version number indicating the version of the package in which the feature being described was added. For stretches of inline text, you can use <new version="...">...</new> to mark new text.

tmml-man.tcl -newsince M.N will insert changebar macros (.VS / .VE pairs) for any element marked with a version number greater than or equal to M.N (as determined by package vcompare). The other down-converters do not (yet) do anything with version attributes. (I've got a partial implementation in tmml-html.xsl, not finished yet (as of 18 Jul 2002; stay tuned.)

The nroff-to-TMML up-converter does its best to change .VS/.VE pairs into version attributes; if it gets confused it turns them into <?NEW?> / <?ENDNEW?> processing instructions; these need to be cleaned up by hand.

Q: What advantages do you see in using TMML over the more general-purpose DocBook?

A: The main one is that TMML is custom-designed for Tcl and Tk reference manuals. It "knows" about things like the "STANDARD OPTIONS" and "WIDGET-SPECIFIC OPTIONS" sections of widget manpages, has a richer set of Tcl-specific semantic elements, and enforces certain conventions for how manpages are organized.
This makes it easier to build richer indexing structures -- http://tmml.sourceforge.net/doc/tcl/category-index.html is a good example of this -- and helps to ensure consistency: the formatted documentation for extensions that use TMML will ``look like'' the core docs.
Another difference, which some may see as an advantage, is that TMML is easier to edit by hand than DocBook. The core structural vocabulary was taken from HTML, so for example instead of OrderedList, ListItem, and VariableList it uses ol, li, and dl.
Another advantage is that, since TMML is simpler than DocBook, it's less work to develop down-translators into other formats (for instance, WINHELP).

Q: How about extending DocBook?

A: Sure, why not?

Steve Ball has developed a DocBook customization layer for the TclDOM project; see http://cvs.sf.net/cgi-bin/viewcvs.cgi/tclxml/tcldom/docs/ for the current version.

I didn't go this route because TMML was initially designed as a target for converting the existing NROFF documentation into XML. The up-converter works in several stages, adding additional structure and inferring semantics at various stages. As soon as I got to a form that had a high enough "information potential" to faithfully downtranslate to useful presentation forms (i.e., the current HTML rendition), I stopped. Pushing it up one more level to DocBook is certainly doable, but I didn't see the need.

Q: Is there a way to convert the XML into NROFF?

A: Yes: see tmml-man.tcl in the tools subdirectory. The translator requires one of the TclXML or tDOM packages.

Q: How about Windows Help?

A: Yes!
Well, sort of.
A WINHELP version of the Tcl reference manual is now available. .
The WINHELP conversion scripts require the development version of Cost 2.3.

Q: Does TMML support tables?

A: There is no general-purpose, HTML-style table element, but the xl (extended list) element may be used for simple multi-column tables.

Q: How about hardcopy?

A: I've had pretty good luck with tmml2man and groff -man -Tps. If there is a demand for it (or if I get an itch to learn XSL-FO :-), an XSL based formatter is also a possibility.

Q: tmml-man.tcl isn't generating any output. What's wrong?

A: Make sure you have version 2.0 or later of TclXML installed (or tDOM). I've had several reports of this problem occurring with TclXML 1.7