This section describes which basic system prerequisites have to be fulfilled for the work with DocBook-XML.
It must be said here that there are many ways to produce an arbitrarily formatted document from the DocBook-XML-version of a document. Regarding the audience of this primer document only "simple" methods are mentioned that imply a fairly high level of automatism.
To assure the availability of the tools that are required for creating and processing DocBook-XML documents the following packages should be installed. Although not all of these packages have to be installed if only a specific task has to be accomplished (e.g. only DocBook version 3 or version 4) it won't hurt to have them all. The working environment is then prepared for most events.
To create a specific output format from a DocBook-XML document there are basically two ways.
Using XSL-stylesheets and an XSLT processor in conjunction with an FOP processor.
The XSLT processor usually produces HTML or FOP (Formatting Objects Processor) output. The FOP output is then fed into an FOP processor that is a print formatter driven by XSL formatting objects (output independent formatter). E.g. the apache-FOP is a Java application that reads a formatting object tree and then renders the resulting pages to a specified output. Output formats currently supported are PDF, PCL, PS, SVG, XML (area tree representation), Print, AWT, MIF and TXT. The primary output target is PDF (HTML is missing).
Note: All this is currently work in progress (V.0.20) and therefore has not yet settled. Furthermore the establishment of the infrastructure requires some knowledge of the matter and can't be done purely from the SuSE-Linux-Distribution (internet download required).
Using DSSSL-stylesheets and jade
This approach is more straight forward because the necessary tools can be found ready made on the SuSE-Linux-Distribution. The tools are fairly easy to use because there are comfortable frontends available. The major drawback of this method is the fact that jade uses TeX (not LaTeX) as interim format on its way to the destination format. This implies some loss of structural information which in turn restricts the layout capabilities. Therefore full size print documentation (e.g. printed books) can't be done this way. Nevertheless for the kind of internal documentation that has to be produced by the development department this is the method of choice. It's beautiful enough and it provides way for the key formats HTML, PS, DVI and PDF.
Note: It must be said here that there are many packages available for this way and that it is a matter of research to find out what all of them are doing and how they interact.
Assuming that the latter of both methods mentioned above (using jade) should be used for documentation work the following packages are of interest. Those that are absolutely necessary are marked accordingly.
jade_dsl (necessary)
jade allows for converting SGML documents to low level TeX which in turn can be converted further to other formats like RTF, PDF, DVI etc.
This package is about to be obsoleted by openjade, the successor of jade_dsl. However some of the frontends still use jade_dsl so it is (currently) recommended to install jade_dsl in any case.
openjade (currently optional)
openjade allows for converting SGML documents to low level TeX which in turn can be converted further to other formats like RTF, PDF, DVI etc.
This package provides the same functionality like jade_dsl (and more) and will some day obsolete it. However some of the frontends still use jade_dsl.
jadetex (necessary)
jadetex is a package containing Macros to convert the TeX-output of jade_dsl to DVI or PDF.
sp (necessary)
The tools in this package allow for processing of SGML and XML documents. The parser nsgmls is used by jade_dsl. There are also some further tools for format conversion like sgmlnorm that "normalizes" abbreviated SGML code and s2x that converts SGML to XML.
docbook_3 - docbook_4 (necessary)
The DocBook DTDs for version 3 and version 4 each in SGML und XML.
docbook-dsssl-stylesheets (necessary)
DSSSL stands for "Document Style Semantics and Specification Language". Necessary for converting DocBook documents to other formats using jade. The respective files have the suffix dsl.
docbook-toys (necessary)
A script frontend for jade that allows for converting DocBook documents to other formats like HTML, PDF etc. in a fairly easy manner. It avoids the very many commandline parameters of jade (e.g. db2pdf converts a DocBook document to PDF). Works with DocBook-XML and DocBook-SGML.
Currently this package is made for jade_dsl (not open_jade).
docbook-utils (optional - didn't work out of the box)
Another jade frontend originating from the RedHat world. It's similar to the docbook-toys (e.g. docbook2pdf converts to PDF) but it is restricted to DocBook-SGML. The package also contains a perl script capable of finding differences in two SGML files (sgmldiff).
docbook-xml-website (optional)
A sample website implemented in DocBook-XML. It may be useful if web-related stuff has to be made with DocBook-XML
docbook-xsl-stylesheets (optional)
The XSL-Stylesheets for the DocBook-XML and "Simplified" DocBook-XML DTDs. These are the official DocBook XSL-Stylsheets. To make use of them an XSLT-processor must be used.
docbook2x (optional)
Converting DocBook documents to Texinfo and man pages.
perl-SGMLS (optional)
A perl5 class library that comes with an application called sgmlspl which is a very simple tranlslation utility to translate SGML to any other format using very simple style sheets that use perl subroutines. Actually, you need to write perl code only if the conversion is complicated. It reads the ESIS output of parsers like nsgmls and converts it to to the desired format. If the parser understands XML it also works with XML.
psgml (necessary for emacs users)
An Emacs add on package that provides comfortable modes for editing SGML and XML documents. The underlying DTD is parsed and the the menu stucture is extended for context sesitive tagging with respect to this DTD. Furthermore some additional tools are provided. Specifically made for Emacs; Xemacs has its own version.
Very good and most important for emacs users!
sgmltool (optional)
These are some tools created as successor for LinuxDoc-SGML. It is mentioned here only for completeness reasons, because it is based on pure SGML and has its own DTD based on the QWERTZ-DTD by Tom Gordon.