Start your favorite editor and paste the following magical invocation:

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "docbook/dtd/xml/4.2/docbookx.dtd">

Nobody really knows what this does exactly, but it works. Now to start the actual article:

<article>
  <articleinfo>
    <title>
      Making your DocBook/XML HTML output not suck
    </title>
  </articleinfo>
  <section>
    <title>Introduction</title>
    <para>
      Most modern UNIX and Linux distributions come with suitable DocBook/XML tools, yet by default..
    </para>
  </section>
</article>

This article is getting slightly recursive!

Save your file as docbook.xml and do the following:

$ xmlto html docbook.xml
$
      

And out comes docbook.html, which you should take a brief look at. It is has a very 1990s feel to it.

To change this, we will use the modern technology called “Cascading Style Sheets”. These can do almost everything and can be very complicated. We're not going make them so however. We need to do two things:

This is a system for, um, well, as far as I know, reconfiguring xmlto. Here is another magic invocation:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version="1.0">
  <xsl:param name="use.id.as.filename" select="'1'"/>
  <xsl:param name="admon.graphics" select="'1'"/>
  <xsl:param name="admon.graphics.path"></xsl:param>
  <xsl:param name="chunk.section.depth" select="0"></xsl:param>
  <xsl:param name="html.stylesheet" select="'docbook.css'"/>
</xsl:stylesheet>

This is their convoluted way of saying 'use.id.as.filename = 1'. Oh well. What this means is that sections which get their own files get named according to the id assigned to them in XML. Also, we want pictures in “warning” boxes, and these will be found in the same path as our html. In addition, we don't want any “chunking”, in other words, we want one file to come out.

The last line is the important one: it tells xmlto to include code in the output that will load a cascading style sheet called docbook.css.

Incidentally, these settings are documented on http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html, and are more properly settings of DocBook than of xmlto.

Save the above XSL file as config.xsl, you'll need it later on.

This is “web technology” and has been around for a while. I know little of all this, except for the parts I need to make my DocBook output look good (or at least, better).

I use the following:

body {
         font-family: luxi sans,sans-serif;
}

.screen {
        font-family: monospace;
        font-size: 1em;
        display: block;
        padding: 10px;
        border: 1px solid #bbb;
        background-color: #eee;
        color: #000;   
        overflow: auto;
        border-radius: 2.5px;
        -moz-border-radius: 2.5px;
        margin: 0.5em 2em;
 
}

.programlisting {
        font-family: monospace;
        font-size: 1em;
        display: block;
        padding: 10px;
        border: 1px solid #bbb;
        background-color: #ddd;
        color: #000;   
        overflow: auto;
        border-radius: 2.5px;
        -moz-border-radius: 2.5px;
        margin: 0.5em 2em;
}

Ok, we've said a few things here. The first stanza is arbitrarily the most important one, it selects a spiffy font. You can put other stuff in the body stanza as well, like a background image, the default text colour etc.

The second two stanzas are interesting as they “hook” into DocBook tags. The first one specifies the appearance of <screen> content, the second one that of <programlisting>'s. All this was gleened from the Fedora HOWTO pages, by the way, I invented none of this.

Do note however that while you can go wild with CSS, you can also mess things up. Most, if not all, uses of <screen> and <programlisting> expect a monospace font, for example. If you change that, diagrams will look bad.

Save the CSS file above as docbook.css, we'll need it in the next section.

So far we've made an XSL file telling DocBook to include a reference to a Cascading Style Sheet, which we've made as well. All that's left is to tell xmlto to use the XSL file:

$ xmlto xhtml -m config.xsl docbook.xml
Writing index.html for article
$ 
      

The -m config.xsl part is new, and makes xmlto read config.xsl. If this finished without errors, you should now have a file called index.html that looks a lot like the page you are reading now.