Colophon

This thesis was written in SGML using the DocBook markup language. Since this appears to be a fairly atypical approach, at least within Rhodes University, this colophon attempts to document the process.

DocBook

DocBook provides a system for writing structured documents, such as this thesis, using the standardised general markup language, SGML (or the extensible markup language, XML). It is particularly well suited to documents with a computer slant, but is not exclusively limited to them. The DocBook document type definition is maintained by the DocBook Technical Committee under the auspices of the Oasis consortium, and is freely available to all.

This document is written using the SGML version of DocBook 4.2.

One of the features of DocBook is that it separates presentation from content in any document. The DocBook DTD provides a way of marking up document content, and presentation is controlled by separate stylesheets. This allows DocBook documents to be published in many different formats, and for the presentation to be easily changed.

This document makes use of Norman Walsh's modular DSSSL stylesheets (version 1.73) to control presentation, which allow both screen and print versions of this document to be produced.

DocBook is well documented, both on the web and in print. DocBook: The Definitive Guide is written by Norman Walsh and Leonard Muellner and is published by O'Reilly & Associates. The SGML sources for this book, as well as HTML and PDF versions, are freely available via the world wide web. Extensive use was made of this book during the writing of this thesis.

Producing Different Document Formats

In order to produce documents of different formats, the DocBook SGML source has to be processed using a DSSSL (Document Style Semantics and Specification Language) engine. This engine renders the SGML content based on the presentation rules defined in the DSSSL stylesheet.

This document is processed using the OpenJade DSSSL engine.

The process of producing the different output formats is controlled using the FreeBSD documentation project's document build toolset. This is a set of Makefiles that automate the process of generating DocBook documents. The toolset is readily available from the FreeBSD web site.

The FreeBSD build toolset provides the ability to produce documents in the hypertext markup language (HTML), plain text format, PostScript (PS), Adobe's portable document format (PDF), TeX/LaTeX, and the device independent file format (DVI). The PostScript and PDF versions of the document make use of the JadeTeX macros. The HTML versions of the document make use of the World Wide Web consortium's HTML Tidy utility.

OpenJade, the DSSSL processing engine also allows for output in XML. This means that SGML DocBook documents can easily be converted to XML DocBook documents, allowing the use of XSL stylesheets as well as DSSSL ones. The FreeBSD documentation build toolset supports the use of XML documents with XSL stylesheets, but this approach was not used in the production of this document.

Some post-production of the TeX, PostScript and PDF version is done using the patch(1) utility. A patch to the TeX source was produced, and this was applied by the Makefile before the JadeTeX macros were used to produce other formats. Unfortunately, this patch was necessary in order to make the recto title page to conform to the University's formating regulations regarding the title pages of theses. A better way of achieving this would have been to correct the DSSSL stylesheet to produce the right output.

Fonts

The PostScript and Portable Document Format versions of this document use the Helvetica font for headings and the Times-Roman font for the body text. The base font size is 11 point. The HTML version makes use of the Verdana font if it is available.

Images

Including images in DocBook was perhaps the most complex part of creating this document. Fortunately, the FreeBSD documentation project has done a lot of work towards integrating images into their documentation build toolset Makefiles. In addition, Nik Clayton has written a fair amount of documentation on the process.

None of this documentation, however, covers the task of getting the original images into the right formats. There are two basic classes of images, vector-based and bitmap-based. Each of these types has its own intricacies involved in their conversion, and experimentation determined the best way to proceed with them.

For ease of reference, the images in this document were created in the following ways:

All PNG images were created at a resolution of about 300 dots per inch. These images are print-ready, and are suitable for use with PDF format output. PDFJadeTeX does not correctly support interlaced PNG images, so none of the images were interlaced.

In order to create PNG images more suitable for web pages, the ImageMagick convert(1) utility was used. The images are rescaled to a width of 600 pixels and were interlaced to give the appearance that they download faster.

The JadeTeX macros make use of Encapsulated PostScript images when generating PostScript output. The GNU version of GhostView was used to calculate the bounding box in each PostScript image, and to save these images as Encapsulated PostScript. These EPS images were tidied up using the eps2eps(1) utility.

Printing

In order to produce the final printed version of this document, the documentation build toolset was used to create a PostScript version of this document. This PostScript document was printed on a Hewlett-Packard HP4100TN laser printer. Those pages which contain colour images were printed on a Hewlett-Packard ink-jet printer.