A 10 second guide to creating a DocBook document

  • 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