A 10 second guide to creating a DocBook document

Fri 04 November 2005

The Definitive Guide is a good start, but probably won't help you actually make a document.
You have two choices, XML or SGML (see the guide). I've always used SGML, but make it like XML (see below). This is because doing things like inserting a text file or program listing from a foreign file with XML requires all sorts of playing with tools that seem mostly to be based on Java, which sucks on any platform !x86, which I use a lot. It seems much easier to just use jade to get everything done.
Use the XML declaration for SGML so you can have closed tags (e.g. <tag />). I think this turns it into something defined as WebSGML. Close all your tags (such as <imagedata>) and make sure all your tags are lower case. This means if you want to make it XML later, you can. I've also found xsltproc does a better job at finding problems than jade.

You'll want a CSS file to style your HTML output. Create a DSSSL script that looks like below.

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
]>
<style-sheet>

<style-specification id="html" use="docbook">
<style-specification-body>

(define %stylesheet% "stylesheetname.css")

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>

Put your figures in with something like below and you can create both PDF and HTML output

<figure>
     <title>Figure title</title>
     <mediaobject>
       <imageobject>
         <imagedata fileref="figures/figure.eps" format="EPS" />
       </imageobject>
       <imageobject>
         <imagedata fileref="figures/figure.png" format="PNG" />
       </imageobject>
       <textobject>
         <phrase>About the figure.</phrase>
       </textobject>
     </mediaobject>
   </figure>

Create your output with the jw wrapper around jade.

HTML
$ jw -o html -d stylesheet.dsl -f docbook -b html -l /usr/share/xml/declaration/xml.dcl docbook-file.sgml

PDF
$ jw -f docbook -b dvi -l /usr/share/xml/declaration/xml.dcl docbook-file.sgml
$ dvipdf docbook-file.dvi