Future Work

The limitations discussed in chapter 5 are obvious places where more work can be done in the future to enhance the doctools system.

With regard to image support for example I currently see two possible alternatives on implementing it. One method is simpler to implement in doctools, leaving the main part of the burden in the users hand. This method is implemented in the rendering system for TIPs [17]: Links to images are given in symbolic form, and the actual mapping from symbol to image data is then given to the format engine through means outside of the format itself. In the case of TIPs this is actually semi-automatic, each renderer uses the symbol as base path and then looks for a file with the proper file extension.

The alternative would be to extend doctools beyond text formatting by incorporating commands for the creation of vector and raster graphics [25]. This is more difficult to do, simply because all relevant formatting engines have to be extended to understand the input. And for those that don't or can't do graphics we either have to extend them so that the graphics commands do nothing, are the generic layer has to be able to detect if an engine is able to do graphics and do the skipping of graphics on its own. A question to consider before the implementation is: How far can we actually go with this?

A preliminary answer is: Quite far. In the XML world we have Scalable Vector Graphics, this can be combined with TMML. And in the *roff world we have the 'pic' language [8] for the same purpose. Which means that it is possible to incorporate at least vector graphics into manpages. And that is actually the most we will most likely need. As for the TEX/L^ATEX world, graphics can be incorporated either through PostScript, or a special sub-language for the description of vector graphics. In other words the same as proposed here.

A last note on this topic: The two alternatives discussed above do not exclude each other. They are actually quite orthogonal, one geared towards stronger vector graphics , the other more usable for raster images.

A less visible change would be to rewrite the interface between generic framework and formatting engines in an object-based manner. Actually this would be, for the sake of backward compatibility, rather the addition of an object-based interface to the system instead of replacing the existing interface completely. The point here is that the object-based approach makes a number of customization task a lot easier, by creating new engines by either derived them from an existing one, or by wrapping the custom code around it, i.e. delegation [19]. Even if this change is not done for the core system itself it is something writers of formatting engines should consider for their code.

Again more obvious work, extend the number of predefined formatting engines. Useful formats are, for example, DocBook [3] for connectivity to Linux documentation, Python's ReST (structured plain text, [5]), and Tcl's TIP format [17]. And beyond that an engine converting doctools into a format usable by Tk's text widget would allow for the portable display of our documents without the requiring additional extensions, like TkHTML [21].

And now looking at things from a completely different angle, consider the writing parsers which read formats like TMML, DocBook, ReST and return doctools. This way we can import existing documentation into the unified format. The most beneficial parser right now would be one for TMML. This is because Joe English already has a suite of applications which read *roff manpages and convert them into TMML, using a number of heuristics to guess the semantic markup. A TMML to doctools then simply completes the chain allowing the import of preexisting Unix manpages.

A simpler application would be to read doctools, and then write it back, in other words a pretty-printer.

The general theme the above is falling under is the (automatic, or semi-automatic) generation of documentation, using doctools as the generic intermediate language. In the discussion above the source is simply other existing documentation. A seed for this is already present in the doctools module, two packages parsing the output of cvs log and of emacs ChangeLog files, thus extending the generation of user-visible documentation from texts written by developers.

The next obvious step here is the extraction of documentation directly from the Tcl code, in other words, support for various types of literate programming. Examples of tools doing this are AutoDoc [9] and zdoc [10]. Inside of AutoDoc for example we have derivations of class genericFormatter, enabling it to write its result not only in HTML but any other format a class exists for. These parts could be rewritten to simply generate doctools and thus leverage of the formatting engines and tools already present for it. For a different approach in the same area see the User Documentation Project on the Wiki [1], which is thinking about using either doctools formatting directly for the embedded documentation or at least something very close it. Stepping further we come to tools which perform complex analyses on the source code of packages and application and have to report the results in some manner. An example of these class of applications is Source Navigator [22].

The last line of thought I wish to discuss here is the possibility to make the formatting language itself extensible. Look for example to the beginning of this chapter, where we talked about the support for images. One of the approaches discussed was to extend the language to support vector graphics. Is it possible to generalize such work ? I.e. to create a framework where language extensions itself can be plugged into the system, loaded on demand when used in a document ? Is this actually useful, or is graphics support the only important thing missing, language-wise ? This is also related to the topic of better support for templating and parameterized macros as described in chapter 5. For what else are such macros and templates than extensions of the formatting language itself ?