3. Tools

There are two different types of tool related to SGML -- the tools you use to create SGML documents, and the tools you use to process SGML documents. These tools are very different, because they do completely different things.

3.1. Authoring tools

As mentioned in the Introduction, you don't really need any special tools for creating or authoring DocBook documents. In fact, at the moment, your best bet is to use your favourite text editor. DocBook documents must be in plaintext ASCII, not in any special binary format. Thus, you can use vi, emacs, notepad, textpad, or any other text editor that allows you to produce plain ASCII output.

There are some tools being developed that will allow you to create DocBook and other types of SGML documents without having to manually type in all the markup tags. At the moment, however, those tools are not available, or if they are available, they're not all that reliable. For now, it's recommended that you just use a text editor, and add your own markup tags by hand. It's a bit of a bother, but it's not difficult. The end result is definitely worth the time invested.

3.2. Processing tools - DocBook Tools

SGML processing tools are sets of scripts and programs that are used to turn SGML documents into other output formats. It is during this processing that all formatting is added and the final versions of the documents are created.

The OSWG uses a package called "DocBook Tools" to process the DocBook instances that are part of its documentation set. This package includes a set of scripts that simplify the use of a number of different programs, making it very easy to create a variety of different output formats, including HTML, PDF, PS, RTF, DVI, and TEX.

3.2.1. Getting DocBook Tools

You can get all the packages necessary for DocBook Tools at http://sourcware.cygnus.com/docbook-tools/.

3.2.2. Installing DocBook Tools

Unfortunately, installing and configuring DocBook Tools is (currently) outside the scope of this document. Refer to the DocBook Tools website for help and documentation. If you have problems, there is a DocBook Tools mailing list called "docbook-tools-discuss" where you can get help from other DocBook Tools users. Subscription information is available on the site.

If you cannot get the help you need on the docbook-tools-discuss list, you can join the oswg-docbook mailing list, and ask there. To subscribe, send a message to the following address with "subscribe" in the subject line of the message:



3.2.3. Using DocBook Tools

Using DocBook Tools is exceedingly simple. When you install the packages, a series of scripts are added to /usr/bin. Each script turns your DocBook document into a different output format. The scripts are called:

  • db2html - DocBook to HTML

  • db2dvi - DocBook to DVI

  • db2pdf - DocBook to PDF

  • db2ps - DocBook to PS

  • db2rtf - DocBook to RTF

Using these scripts is very simple, just type the script name on the command line followed by the name of the DocBook file you want to process. For example:

$ db2html my-document.sgml

If you have any problems with this, you can ask for help on either of the mailing lists mentioned above.