TMML Stuff

What is it?

TMML is an XML DTD designed for the documentation of Tcl, Tk, and other Tcl extensions. Please see the SourceForge project site for the current TMML distribution.

Comments on the DTD, the XML output, the HTML rendition, and anything else are more than welcome. E-mail me with any feedback.

What's new

5 Jan 2001:
The Web site at SourceForge has been set up.

21 Dec 2000:
Well, the SourceForge admins still haven't created the FTP or Web directories, but everything else looks like it's in place. I expect to have a new release sometime in January.

14 Dec 2000:
TMML is moving to SourceForge. Due to the recent changes at SourceForge the project site isn't fully set up yet, but it should be ready shortly.

27 Aug 2000:
First cut at a Windows Help converter.

Release 0.6:

• Added TMML-to-NROFF conversion script.
• Reworked structural inference heuristics in tmml2man; the output is now much more accurate.
• Changed content model of dl element: now dt/dd pairs are contained in a ``wrapper'' dle element.
• Added optlist element for general option lists.

Remaining to be done

• (26 Aug 2000) Just discovered a problem with man2tmml: Concat.3 and concat.1 turn into Concat.xml and concat.xml, respectively; this causes certain problems on Windows...
• Integrate with TEA to make it easier for package authors to use TMML.
• Review the overall organization of the tables of contents;
• Finalize TMML DTD, and document it (in progress).
• Obtain a permanent URL for the DTD (possibly in the xml.org repository?)
• Correct markup errors in the TROFF source and get the changes back to the TCT (in progress).
• Generate a WINHELP version of the manuals, using RATFINK and either Cost or TclDOM (in progress)
• Write a Schematron schema to specify conventions that aren't accounted for in the DTD.
• Fix up-conversion script to preserve copyright information (done)
• Break the alphabetical index up into sections (Tcl commands, C commands, miscellaneous) (done, see "Category Index");
• Add hyperlinks to the HTML output wherever possible, especially in SEE ALSO (done) and KEYWORDS sections (done);
• Attach version information (from .VS and .VE requests) to the appropriate structural element. Think about version information in general.
• Write a converter from TMML back into TROFF. (done)
• Add a subsection element (only one man page currently uses .SS -- cursors.n -- but it would be useful in general.) (Done, 23 Jul 2000)
• Check HTML man pages under MSIE, fix stylesheet as needed. (Done; now looks more-or-less OK in MSIE 5, Opera 3.6, and Mozilla M16. Still have some strange artifacts on NS 4.6/4.7). Update: There have been serious problems reported on MSIE 5.5 and Netscape 4.7, most likely font- or encoding-related. I haven't been able to replicate these though so am not sure how to fix the problem...
• Possibly: try man2tmml on [incr Tcl], TclX, other extensions... (Started: man2tmml works mostly OK on itcl docs, somewhat less OK on tcllib manpages).
• Build global keyword index cross-referencing all the available manuals.
• Possibly: extract an RDF representation of all the commands and options, and see if anything useful can be done with it.
• XSL stylesheets: Completely rewrite cross-reference processing templates; there's a huge bag of ad-hoc special-cases which could be unified into a common approach. (in progress)
• Implement processing for the subdoc element in manuals.

Stuff that should be added to the DTD:

• url, email, and/or address elements;
• Add information section for manual elements (author, copyright, version, etc)
• File and directory names?
• Change logs?
• Callouts?
• "notation" attribute on example, syntax, and other code elements

MINI-FAQ

• Q: Is there a way to convert the XML into NROFF?
  A: Yes: see tmml-man.tcl in the tools subdirectory. The translator requires the TclXML package.
• Q: How about Windows Help?
  A: [25 Aug 2000] Yes!
  Well, sort of.
  I've got a more-or-less working TMML-WINHELP converter, but there are a lot of things still missing: cross-references don't work, the indentation is completely wrong, and the conversion script requires Cost 2.3, which I haven't released yet... Also, the fact that Windows can't tell Expr.xml from expr.xml is causing me some problems. But stay tuned.
• 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.

Related packages

The following additional software is used in the translation process:

• The TclDOM package from Steve Ball of Zveno. Also available in the Ajuba CVS repository). This is used by the NROFF-to-TMML up-converter.
• The TclXML package. This is used by the TMML-to-NROFF down-converter.
• Tcl, version 8.2 or later. Many of the translations scripts also use the cmdline package from tcllib.
• The excellent SAXON XSLT Processor from Michael Kay of ICL. This is used to convert TMML to HTML. (Any XSLT processor should work, but the keyword index and alphabetical index rely on SAXON extensions to work properly.)
• James Clark's NSGMLS parser Not strictly necessary, but I like to validate the results at each step of translation.