Most modern UNIX and Linux distributions come with suitable DocBook/XML tools, yet by default the output looks old-fashioned and is hard to tune. This page is both a demonstration of what your DocBook output can look like with a few lines of tweaks and an explanation of how to make it so. The sources can be found here.

I work with xmlto, available on http://cyberelk.net/tim/xmlto/. On Debian the package is called 'xmlto'. Behind the scene, xmlto calls xsltproc to do the actual work. All examples in this site work with version 0.18. If you are an emacs user, nxml-mode comes highly recommended. It can be found on http://www.thaiopensource.com/nxml-mode/. To tune the appearance of your generated html, the 'Web Developer' extension of FireFox is grand. It is also a highly useful tool to snarf CSS segments from pretty sites.

The following sections show how to do the minimal things to not give your documentation a museum look.

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: Write a suitable Cascading Style Sheet Instruct xmlto to use it

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.

At this point, this document assumes you are using FireFox with the Web Developer extension, or, are in a position to easily change the CSS file of this document and reloading it in your browser to watch the results. In this section, we'll be doing some experiments on this file, not the small file we wrote above.

DocBook provides for, at least, the following ways to draw special attention to a message: This is a <note>. This is a <warning>! This is a <caution>! Note the cool little icons. On most DocBook installations you'll find some sample icons, as shown above, that you need to copy to a place where your browser can find them. Feel free to use different icons though, these are pretty boring. Time for some CSS, we may want to make these warnings somewhat more special. Open the CSS file that belongs to this page (in FireFox, right-click on this page, select Web Developer, select CSS, select Edit CSS). Now add the following: .caution, .warning { border: 1px solid #f00; } This adds a bright red border around <caution> and <warning> messages. You may have been wondering what Cascading means in Cascading Style Sheets, well, here goes. Below the stanza above, add: .caution { font-size: 1.2em; } Now we've specialised the appearance of the <caution> message from the general stanza above that also specified the <warning> layout. The result is that the Caution text is now bigger by 20%.

This is really a matter of taste. Many sites these days feel the need to make their links stand out a bit more, for example by giving them a dotted underline and making them invert on hover. Well, if you want this, you can do it. Paste the following into the CSS: a { text-decoration: none; border-bottom: 1px dotted #000; } a:hover { background-color: #777; color: #fff; } This first removes the traditional underline by setting text-decoration to none, followed by specifying a dotted black bottom-border. Additionally, the a-element is configured to have a different back- and foreground when the cursor hovers over it. To test, here is a fine url to hover over. To pimp up your page further, briefly consider text-decoration: blink.

It appears that the dust has settled on this. For a long time, it was common to see inverted question marks or weird dice-face looking things in place of proper double and single quotes. To elaborate a bit, the regular ASCII charcter set, or nationalised variants such as ISO-8859-1 don't actually define left and right quotes. In some contexts the ` character has been abused as a left-quote, and, indeed in the 1990s this actually looked good on many browsers. However, these days the position of ` and ' has been clarified, and the font people have listened. The ` is now GRAVE ACCENT in Unicode-speak, and ' is ACUTE ACCENT, and look accordingly. For stunning detail on this issue, see here. For our purposes it is enough to know to never use `. It is permissible, and easy, to use ' to quote strings. However, the royal way of quoting strings in DocBook is to use <quote>. For example, <quote>quoted</quote> ends up like this: quoted. For comparison: regular double quotes "quoted", abusing the GRAVE ACCENT `quoted', using regular single quotes (aka ACUTE ACCENT) 'quoted', the royal way: A quoted quote looks like this.

Ok, these rarely used and truly spice up your output so it won't look DocBookish anymore. To make things pretty, we need to edit our config.xsl a bit. Watch the numbers: <?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"> <!-- Use ids for filenames --> <xsl:param name="use.id.as.filename" select="'1'"/> <!-- Turn on admonition graphics. --> <xsl:param name="admon.graphics" select="'1'"/> <xsl:param name="admon.graphics.path"></xsl:param> <!-- Configure the stylesheet to use --> <xsl:param name="html.stylesheet" select="'docbook.css'"/> <xsl:param name="chunk.section.depth" select="0"></xsl:param> <xsl:param name="callout.graphics" select="'1'"></xsl:param> <xsl:param name="callout.graphics.path"></xsl:param> </xsl:stylesheet> This turns on graphical callout numbers This configures the callouts graphics to be in the same directory as the html Sure looks pretty! You need to copy the number graphics over from the same place where you found warn.jpg etc, the files are called 1.png and onwards. The syntax is not too hard, add <co id="something"/> (note the closing /!) to your <screen> or <programlisting> and add a <calloutlist> below, like this: <calloutlist> <callout arearefs="graphics"> <para> This turns on graphical callout numbers </para> </callout> </calloutlist> There is also a hidden syntax for if you don't want to insert things in the text you refer to, perhaps because it is auto-generated. I haven't been able to get this to work though.

DocBook knows several document types, like book and article. Each of these comes with certain preset defaults which specify if sections are numbered, if the Table of Contents is repeated for each section etc. You might want to change these settings individually, which is possible by adding the following to the XSL configuration: <xsl:param name="generate.section.toc.level" select="1"></xsl:param> <xsl:param name="section.autolabel" select="1"></xsl:param> <xsl:param name="section.autolabel.max.depth" select="1"></xsl:param> In order this enables the output of a section level ToC, turns on the enumeration (numbering) of sections, but limits that numbering to the first nesting level - ie, sections within sections don't get additional numbers.

How can I add a spiffy Questions & Answers section? By using a Qandaset! How does a Qandaset work? As you would expect it to - with the minor exception that it can only live outside of a <para> Can you show some code? <qandaset> <qandaentry><question><para>How can I add a spiffy <quote>Questions & Answers</quote> section?</para></question> <answer><para>By using a Qandaset!</para></answer> </qandaentry> </qandaset>

In the HTML headers section of DocBook XSL: The Complete Guide we read that we can use the following to do this: <xsl:template name="user.footer.content"> <P class="copyright">© 2002 Megacorp, Inc.</P> </xsl:template> However, things are not as easy as they appear. For some reason or other, part of the toolchain decides that it needs to mess with lower case tags you insert here. The easy solution is to upper case all these, as is done above. A lot of HTML also works in lower case but specifically javascript breaks. This for all you Google AdSense users out there :-)