Macrotone Blogs

This summaries a few of the lessons learned using DocBook XML for documentation.

Upcast: The conversion from Microsoft Word to DocBook XML introduced a few opportunities for changes:

1. Media objects (figures) are all converted to ‘inlinemediaobject’, and even when the image is on its own it always is surrounded by ‘para’ and results up positioned on the left hand side of the page. The best approach we found was to convert them to simple ‘mediaobject’ and change then to become ‘figures’ and in this way also enable the creation of a ‘List of Figures’. We also tended to change the specified exact image size to use scaling so that the width of 14cm was most appropriate. [This did impact the fact that all html screen images come out at a standard width.]

The next stage in our documentation changes was the creation of PDF documents from the DocBook XML formats.  [See previous posts for other blogs on our documentation changes.]

There is a need to use a XSLT transform to convert the XML document to a FO (formatted object) which can then be processed to create the PDF output.

The DocBook distribution have available a set of XSL transforms for converting the XML files into a variety of different formats, so the first step was to download these. This is not strictly necessary since it is possible to access the XSL transforms over the web, but having a local copy speeds up the transformation process.

We have previously mentioned using XML documents in DocBook format. We now turn our attention to the question of the format of the tables. A previous blog on DocBook table format mentioned the two types of  tables supported by DocBook, but not every document table necessarily has to be in the same format. We have an ‘in-house’ style used for some time and the desire was to retain a similar format with our web pages.

We are using a Joomla component named DocImport written by Nicholas K. Dionysopoulos and are very pleased with its behaviour even though it is still in an ‘alpha’ release form. A credit to the authors abilities. The component presents each web page with headers and footers which are using a ‘table style’ which does not display column separators. This is understandable since the standard format for tables is basic to put it bluntly. 

We have been studying  the DocBook DTD and in particular the table specifications.  There are two separate and distinct formats supported, the originals CALS format and the ‘newer’ HTML format since DocBook version 4.3. CALS is an SGML standard developed by the U.S. military, and their set of table tags was one of the first to be developed that included complex features for tables.

Some confusion was encountered since one source claimed that both table formats could not be used in the same document, whilst another source claimed that the two forms cannot be mixed within  the same definition, which makes more sense.

Later, because of widespread familiarity with HTML tables, DocBook added HTML table elements. Now you can use tr and td instead of row and entry in a table.  They cannot be mixed within one table. Also, the content of each table cell has to be valid DocBook, so you cannot usually just cut and paste an HTML table into your DocBook document. But the DTD does permit a document to contain both CALS tables and HTML tables. The tgroup element is the distinguishing characteristic between them. A CALS table requires a tgroup, and an HTML table does not permit one.

We have been using the evaluation edition of XMLMind XML editor commonly known as XXE for a little while and discovered a a document on the web from the O’Reilly stable.

The link is for an older version of the software (Standard Edition 2.10 I think) but in the main it is still applicable with the latest evaluation edition (5.4.1).  The authors hope that it is found useful or as a starting point for your own work.

Note:  Reloading a later evaluation version resets the usage counter back to 30 days.

Historically we used to create our documentation using ‘Word Perfect’ but changed to using Microsoft Word, soon after Adobe ‘took over’ Word Perfect.  This has served us well for many years, but unfortunately Word has not kept up with the changes in the Web and the need for short pages of documentation easily accessible by users.  Yes, Word can generate HTML documents but anyone who has every looked at the created output will be struck by the obvious bloated code and its use of strangely named variables making it almost unreadable in its raw form.  This necessitates a cleanup operation on the code before it can really be used.

So the search was on to see it there is anything ‘better’ out there.

The obvious candidate was something known as DocBook which is written in XML, which means that it can be created and edited by virtually any editor upon any platform.  However to ensure good structure that meets the requirements of the DTD, something more robust is required.  It also raises the question of how one retains the investment in existing documents and how one can convert them to the ‘new’ format.  One advantage of the XML format is that it is reasonably easy to use XSL transforms to convert it to PDF, HTML  or indeed many other formats.