Making your DocBook/XML HTML output not suck


Table of Contents

1. Introduction
Tools
2. Making a minimal but good looking page
Getting down to business
The Extensible Stylesheet Language
Cascading Style Sheet
Putting things together
3. More fancy CSS things
Notes, warnings, cautions: stuff that deserves special attention
Making links stand out
4. More DocBook specific things
The dreaded “Smart Quotes
Callouts
Section numbering, main Table of Contents, section Table of Contents
Questions & Answers
Adding headers and footers to HTML output

1. Introduction

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.

Tools

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.