Doctools > Docbook, Namespaces & Mortality > Implementation

Implementation

The implementation outlined here describes the approach used for proof-of-concept of the design proposed. It does not constitute a full implementation specification (nor is one likely to be produced); rather it serves as a guide for a small number of specific issues of interest.

Various concepts from the previous Doctools design are expected to remain applicable (most notably the theme system), although possibly ported to a more appropriate language.

Hierarchy and code reuse

The directory hierarchy for module implementations is proposed as follows:

module/moduleversion/outputformat/formatversion

This hierarchy versions output formats for each module implementation. For the lists of proposed modules, this may seem overwhelming by the volume of versions involved. In practise, they are simply interfaces to shared code common to several versions.

For shared code, it is important to take care for inheritance between versions. There are two situations under which inheritance may occur; importing code from the same format of an earlier version (and then extending, or overriding that implementation), and importing code from an alternate format. Importing code from alternate formats forms “cross-links” in the tree: the ordering of these links is still subject to the versioning described previously. This would usually occur when versions of one format track the versions of another (as in the relationship between Docbook-simple and Docbook).

For example, docbook-simple/v1.1/xhtml-strict/1.0 would contain the implementation for generating XHTML 1.0 from Docbook-simple v1.1. Since Docbook-simple tracks Docbook, this might import a cross-link from Docbook v4.3 (the Docbook version associated with Docbook-simple v1.1). For future versions of Docbook-simple (say v1.2), they may import their implementations from Docbook-simple v1.1. Likewise for future versions of XHTML the output versions (say 1.1) may import from XHTML 1.0.

Inevitably there will be portions of formats which will never be implemented. These do not make a module incomplete; the usual reason for these would be that the feature is irrelevant to the given output format. For example, Docbook's @role feature would usually not be expressed in output media, but some diagnostic message would be helpful, if the document author intends for some effect to happen.

There should be no reason for a module to contain a partial implementation (that is, to be incomplete), as modules should be small enough to be completable.

Interface

Two interfaces are proposed: a command-line tool for orchestrating builds and querying for information, and a library interface for programmatic use. As a convenience, Makefiles may be provided to ease the inclusion of the system into existing projects.

The modules employed to process a document may be inferred automatically from the document itself, if the document provides that information. If not, the required modules must be passed explicitly. Since each module's input format has a particular version, this must also be passed or inferred. When versions are inferred, the highest version is taken (as ordered by the module repository).

Likewise for output formats, it is expected that the user would not usually be interested in what version is being generated. Unless they explicitly restrict output to a specific version, as for inputs, the system defaults to the highest available.

Roadmap

The following order of implementation is rough, and proposed so as to maximise getting each area in place as quickly as possible. Once this underlying structure is solid, details may be implemented at a later date on top of that, without fear of disturbing the design.

  1. XSLT for docbook-simple, and a few other obvious modules, to give a little meat to play with.

  2. CLI orchestration tools and Makefile interfaces.

  3. Porting of themes from monolithic Doctools.

  4. PDF output. This should shake out a lot of orchestration details, particularly if it requires two-passes (to convert to TeXML and then to ConTeXt)

  5. Puredocs' formats; these provide a little extra to play with.

  6. Lots of little modules (as discussed in the appendix).

  7. Processing for docbook-to-little-modules. This forms an experiment in multi-stage processing, using our set of modules as an intermediate format.

Notes

Notes may be passed between modules, similar in concept to the notes passed between Apache's modules. In our case, these are used to provide information which another module may use as part of its responsibility for processing, without requiring that module to know how to acquire the information.

An example illustrates this well; the “figures” module is not responsible for generating tables of contents for listable items. Likewise the “structural” module would not know what a figure is, or where to look for one. It is desirable for the structural module to be able to list such things, along with sections and chapters and suchlike.

So, the figures module leaves a note for the structural module to pick up (Exactly what might be listed is presumably user-configurable via some module-specific configuration option):

structural:listable = 'figure'

Here structural:listable means a note called “listable” stored in the structural namespace, which the structural module can pick up. Likewise the “tables” module also sets structural:listable. The ToC-rendering portion of the structural module looks for all these structural:listable notes, and generates a table of contents for each. The name “listable” is up to the structural module; consider it an analogue of a namespaced environment variable.

The options system may be implemented using this same mechanism.

Prev  Home  Next
Proposal   A. Proposed components