Preparing Cogent Documentation :
	Chapter 6. Tools

Chapter 6. Tools

Table of Contents

6.1. Overview

6.1.1. SGML Tools

This diagram shows how our tools interact with the SGML source, the DocBook DTD, the DocBook stylesheets and image files to produce output. Each of the tools is explained briefly below.

jade is the miracle program at the heart of our document processing system. It reads in SGML files, validates them against the DocBook DTD, and uses the DocBook stylesheets (*.dsl) to create HTML, RTF, or TeX output. It also generates a document index.

collateindex.pl works with jade to help produce the document index. This is done as follows:

jade reads the index.sgml file and creates a file called inumber.html that it puts in with the HTML output.
As jade processes the document, it creates another file named HTML.index, which contains index information for the newly-processed document, in a special format.
collateindex.pl reads the HTML.index file, and creates a new index.sgml file, based on the newly processed document.

Here we run into a chicken-and-egg dilemma, because the index.sgml file is updated after the SGML has been processed into HTML, but correct HTML output depends on the index.sgml file being up to date. For this reason, HTML output must be generated twice, or even three times if major changes have been made, before the book's index will be correct. Of course, all other outputs, such as PDF and Postscript depend on a correct index.sgml file, so to be safe, they should be generated after the HTML file. Also, the first time a book is processed, jade will complain that there is no index.sgml file. You can ignore that because it will exist the next time the book is processed.

toc2toc converts an HTML table of contents to a QNX Helpviewer table of contents.

jadetex is a TeX macro that converts TeX output to DVI format.

pdfjadetex is a wrapper that calls jadetex to convert TeX output to PDF format, incorporating PDF graphics.

dvips converts DVI output to Postscript format, incorporating EPS graphics.

psnup converts Postscript output to Postscript2.

6.1.2. XML Tools

In the summer of 2003 we started migrating our document processing to XML to take advantage of the more sophisticated and easier-to-use DocBook XSL stylesheets. These stylesheets work with CSS stylesheets which facilitates formatting, and they allow us to generate HTML Help for Windows in addition to regular HTML. In the first stage of this migration process we continue to maintain our source documents in SGML and convert them to XML each time during processing, using James Clark's osx processor. We then use the XSL processor xsltproc developed by Daniel Veillard to convert the XML to HTML and HTML Help.

The index generation for XML is the same as for SGML. We left it out of the diagram to keep it simple. The same holds for the details related to the jade processor.


5.9. Windows HTML Help		6.2. Installing a new version of DocBook