DocBook XML Resources at CERN

DocBook is primarily an XML vocabulary (defined by a DTD, Docoment Type Definition) which maintained by the DocBook Technical Committee of OASIS. It is particularly well suited to books and papers about computer hardware and software (though it is by no means limited to such application areas).

Using DocBook

I have combined various documents describing DocBook and adapted them to CERN. The document Writing Documentation Using DocBook - Using DocBook at CERN is available in HTML (chunked per chapter), HTML (in a single file), or in PDF.

Why using DocBook is an optimal solution for single-source publishing is explained by Dan York in his nice tutorial.

Michael Smith wrote an introductory article about why one should consider using DocBook. It contains a lot of pointers to other information sources. From the GNU people we have A Crash Course in DocBook (be careful, they still use the DSSSL stylesheets instead of XML and the XSL stylesheets, but the text is educational per se).

Jirka Kosek gave three presentations about DocBook Best Practices at the O'Reilly Open Source Convention (July 23-27, 2001, Sheraton San Diego Hotel, San Diego, CA):

One can also learn quite a bit on how to use DocBook for professional HTML applications by reading Dan York's Summary of the e-smith Documentation Process. Dan explains why they chose SGML (and later XML) as their documentation strategy.

We have also a tutorial about DocBook by Normal Walsh, the Chair of the OASIS DocBook Technical Committee. Norm is Staff Engineer in the XML Technology Center at Sun Microsystems Inc. and is an active participant in a number of standards efforts, including the XML Schema and XSL Working Groups of the W3C.

DocBook reference Documentation

Definitive information about DocBook can be found at the main DocBook Web site at the Oasis-open organization. That site contains an up-to-date electronic version of the complete text of DocBook: The Definitive Guide, by Norman Walsh and Leonard Muellner and published by O'Reilly & Associates (access to the original copy at docbook.org or the local copy at CERN).

The DocBook DTD

At CERN, the DocBook XML DTDs, stylesheets, etc., as well as XML executables are below the directory root XMLBIN (/afs/cern.ch/sw/XML/XMLBIN on AFS, and \\cern.ch\dfs\experiments\sw\xml on Nice 2000).

The Current version of the installed DocBook DTD is 4.2.
The public identifier is "-//OASIS//DTD DocBook XML V4.2//EN".
The AFS access path is "/afs/cern.ch/sw/XML/XMLBIN/share/www.oasis-open.org/docbook/xmldtd-4.2/docbookx.dtd".

The LiveDTD utility is useful for navigating DTDs and studying their content model.

The XML DTDs are available from the OASIS site, where you should look for a link to the latest version.

DocBook XSLT stylesheets

The latest version of the DocBook XSLT stylesheets is installed on AFS in the directory "{/afs/cern.ch/sw/XML/XMLBIN}/share/java/sourceforge.net/projects/docbook/[DBXSLVERS]", where the part between {...} corresponds to the XMLBIN directory path as mentioned above, and [DBXSLVERS] is the version information, that corresponds to the actual version of the stylesheets (click here to see the version number).

Norman Walsh's XSL stylesheets to transform a DocBook XML document into HTML or XSL Formatting Objects can be found at the SourgeForge DocBook Open Repository Project. At CERN, the XML DTDs are in the subdirectories html, fo, etc. of the directory share/java/sourceforge.net/projects/docbook/[DBXSLVERS]/ under the $XMLBIN root (defined as /afs/cern.ch/sw/XML/XMLBIN on AFS, and \\cern.ch\dfs\experiments\sw\xml on Nice 2000).

Documentation is available as a userguide and a reference guide.

A tutorial about his stylesheets and how to customize them was given by Norm at the Oxford XSLT Conference in April 2001. His presentation is available as a series of individual slides or with the same slides available using a frame view. We also have his paper The Design of the DocBook XSL Stylesheets.

Here is another tutorial on cBook XSL: The Complete Guide by Robert Stayton.

Examples of customization stylesheets (supposed to work at CERN on systems connected to AFS) are listed below. The DocBook XSL Stylesheet Reference Documentation describes the precise meaning of the various parameters used in these examples. If you want to use and further customize a given stylesheet you will have to refer for that document.

Dave Pawson's Docbook FAQ

A collation of some Frequently Asked questions regarding Docbook. The initial focus is on the XML version of the DTD, and the XSLT based stylesheets, with some comments on SGML and DSSSL thrown in.

The Web site is at http://www.dpawson.co.uk/docbook/index.html.

Kosek's DocBook tutorial (in Czech) is installed locally (HTML, PDF).


Last updated: 2 August 2002 (Michel Goossens).