Glen Mazza's Weblog

« Changing the languag... | Main | Human Resources:... »

https://web-gmazza.rhcloud.com/blog/date/20110115 Saturday January 15, 2011

DocBook Resources

Updated August 2012.

Here are the most useful Docbook-related resources I've found:

  1. DocBook 5: The Definitive Guide - by Norman Walsh, online reference manual for Docbook elements. Includes an element index for easy reference.
  2. DocBook XSL: The Complete Guide - by Bob Stayton, provides information on customizing Docbook-to-HTML/PDF output.
  3. XSL Stylesheets Reference - Generated reference documentation on Docbook stylesheet customization options.
  4. Docbkx Tools - Offering Docbkx Maven Plugin, perhaps the best Maven plugin for working with Docbook, see list of companies using it.
  5. Docbook XSL Stylesheets - The standard stylesheets used for PDF (more precisely, XSL) and HTML output, as well as a few other output formats. Downloading the stylesheets is not necessary if you're using the Docbkx plugin above, however having them handy is important when doing stylesheet customizations. Docbkx 2.0.14 uses stylesheets 1.76.1; to determine the stylesheet version used by other Docbkx plugins enter mvn dependency:resolve-plugins with any POM containing this plugin, and look for the docbook-xsl-{#version}-ns-resources.zip dependency.
  6. DocBook Wiki
  7. DocBook Mailing Lists -- Note there are two lists, one for general Docbook XML tags and the other for the Docbook stylesheets and output generation.
  8. DocBook, FOP and Fonts - Shows how to add a new font for PDF generation.
  9. Maven jDocBook Plugin - Alternative Maven plugin done by the JBoss team
  10. DocBook V5.0 Transition Guide - Shows some of the latest benefits of Docbook 5.0 and how to upgrade from Docbook 4.4.

Other projects using Docbook include GlassFish Metro and Jersey, Spring Web Services, JBoss Web Services and Apache Qpid.

A sample POM that will generate both PDF and HTML is shown below. It is part of a skeleton Docbook project that can be obtained from GitHub by using either the download ZIP button or git clone -v git://github.com/gmazza/blog-samples.git command. All that is necessary is to place your Docbook book or article XML (called DocbookResources.xml in the POM below) in the src/ folder, update any includes configuration elements in the POM, and run mvn clean install. After a few moments you'll see the HTML and PDF output in the target/ folder. Note you'll need to declare the foCustomization and/or htmlCustomization elements shown below only if you're customizing the default stylesheets (explained next).

Customizing the stylesheet output: When you'd like to change the way the default stylesheets render a particular Docbook element, Bob Stayton's guide mentioned above is an excellent resource. Customizations normally fall into either placing XSLT param values or template overrides in the customization file. For template overrides, it is usually easiest to search the standard Docbook stylesheets for the HTML or FO template used in rendering a particular Docbook element and then copying that template (with whatever desired modifications) into the customization file. For example, for PDF output I wanted to turn off the default output of hyperlink URL strings (param change) and make the actual hyperlinks blue in color (template change). The following stylesheet customization accomplishes this:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xslthl="http://xslthl.sf.net" xmlns:d="http://docbook.org/ns/docbook"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    exclude-result-prefixes="xslthl" version="1.0">

    <xsl:import href="urn:docbkx:stylesheet" />

    <!-- Make hyperlinks blue and don't display the underlying URL -->
    <xsl:param name="ulink.show" select="0" />

    <xsl:attribute-set name="xref.properties">
        <xsl:attribute name="color">blue</xsl:attribute>
    </xsl:attribute-set>

    <!-- Add any other template overrides here -->

</xsl:stylesheet>

I would then link this customization file into the Maven pom via the Docbkx foCustomization configuration switch. The necessary xsl:import statement above brings in the default stylesheets upon which the customizations are applied as explained on the Docbkx website.

Recommendations when writing Docbook XML:

Be aware of the following Docbook tags to make sure you're using the appropriate element to identify what you're writing. Using the proper element helps in formatting as it allows any future stylesheet customizations to correctly go into effect for all true instances of that element in the document:

  • For writing procedures (enumerated how-to's), use the procedure and step elements instead of hardcoding the step numbers within para elements.
  • Use orderedlist for numbered lists and itemized list for bulleted ones, providing what you're listing is not more appropriately a procedure. The child element of either type of list is listitem.
  • For software code and XML configuration files, use programlisting.
  • For user input, use the userinput tag:

    <para>From the command line, enter <userinput>mvn clean install</userinput> and then...</para>

  • For computer output (as from a console), use the computeroutput tag.
  • For computeroutput and userinput (and potentially other tags), wrap the tag with literallayout if you have more than one line of text and wish to retain the line break(s) and other whitespace in the PDF. (To ensure background styling works properly, make sure to have the literallayout tag outside the computeroutput, etc. tag and not inside it.)
  • For the programlisting and literallayout tags, consider breaking the text into multiple elements if the tag's contents would otherwise span more than one page.
  • For either files or directories, use filename, operating system constants like JAVA_HOME use constant, and application for software programs/applications.
  • Important: If you're using programlisting, computeroutput, literallayout or similar whitespace-retaining tags, be careful not to let your IDE format (correct the indentation of) the Docbook XML as that will mess up the appearance of the text within those tags.
  • Unless you need to specially override the default styling for an element compared to other instances of that element, it's best to avoid the Docbook emphasis element, as it defeats the purpose of Docbook by placing styling within the XML. Instead, use the proper Docbook element (such as userinput or computeroutput) and override the stylesheet for that element if the default styling for that element is not as desired.

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed

Valid HTML! Valid CSS!

This is a personal weblog, I do not speak for my employer.