Creating documentation with DocBook

Here, we will see how to write and process documentation, using the DocBook DTD. We will use the XML version, often named DocBk, because I prefer XML[1], but most of what is written here apply to the SGML version as well.

Writing DocBook

You can skip this section if you just received a DocBook file and want to process it, rather than edit it.

Like with any DTD, I recommend Emacs' SGML mode, psgml to write DocBook.

First, choose a root element, preferably the simplest, article. Start with:


<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1//EN"
     "dtd/docbook-xml/docbookx.dtd">
<article>
  <artheader>
    <title>My first XML document</title>
  </artheader>
  <section>
    <title>My first section</title>
    <para>My first paragraph.</para>
  </section>
</article>

	

This is a complete DocBook document. You can validate it[2].

Typical DocBook documents use book, chapter or article as the root element. Then, they include a header, where you find meta-information, such as the title of the document. After this header, a DocBook document is divided into sections, each with a title.

To know the complete list of elements, see the set of DocBook texts (the link will work only if you installed the package "docbook-doc"), more specially DocBook DTD Reference (the link will work only if you installed the package "docbook-doc").

Processing DocBook documents

Remember, DocBook is not a program but a format. Asking "Does DocBook have a PDF output?" is meaningless. Software which uses DocBook may produce PDF. DocBook itself does nothing.

There are several different solutions to produce printed paper, Web pages or manual pages from DocBook documents. You could program such a transformation yourself with tools like the Perl module XML::Parser or the Java module XP. Or you can use stylesheets, which you may or may not write yourself. If you decide not to write them, you can use the Modular DocBook Stylesheets with jade.

Since we are using the XML version of DocBook, here is how to call jade to translate myfile.db to TeX:


	jade -t tex -V tex-backend \ 
                -d /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl \
                /usr/lib/sgml/declaration/xml.dcl myfile.db
	

which will produce a TeX file using jadetex macros and needing the jadetex program to be processed:


	jadetex myfile.tex
      

And to HTML:


	jade -t sgml \ 
                -d /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl \
                /usr/lib/sgml/declaration/xml.dcl myfile.db
	

Unfortunately, there is no easy way to create text-only output from a DocBook file, for instance for posting it on Usenet. The best available solution is to use the following kluge with lynx:


	jade -t sgml -V nochunks \
                 -d /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl \
                 /usr/lib/sgml/declaration/xml.dcl myfile.db > dump.html
	lynx -force_html -dump dump.html > myfile.txt
	
      

Using SGMLtools

You can also use SGMLtools, version 2. This may be simpler, since SGMLtools, version 2 automates the tasks performed by jade, jadetex and lynx. But it does not work with the XML version of DocBook. To convert a file to HTML:


	  sgmltools --backend=html howto.db
	    

And to PostScript:


	  sgmltools --backend=ps howto.db
	    

And to pure text:


	  sgmltools --backend=txt howto.db
	    

Customizing the Modular DocBook Stylesheets

If you write a custom element or if you want to change the default rendering of an element or if you simply want to customize the output a bit (such as changing the default font), you'll have to define a custom stylesheet. This does not imply retyping everything. DSSSL allows one stylesheet to "use" another. The stylesheet inherits all of the properties of the stylesheet that it is using, but local definitions take precedence over imported ones. An example of a custom stylesheet is:



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

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

(define %body-font-family% 
  ;; The font family used in body text
  "Palatino")

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

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

</style-sheet>

	

Your style instructions (here the changing of the font to Palatino) have to be written in DSSSL, whose syntax and many semantics come from the programming language Scheme, which is itself a Lisp dialect. You do not need to learn Scheme, the documentation of the Modular Stylesheets (the link will work only if you installed the package "docbook-stylesheets-doc") contains examples for most purposes.

Since there are actually two stylesheets, one for printing and one for HTML, the above custom stylesheet works only for the first one. For the second, here is an exemple:


<!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 %generate-article-titlepage% #t)

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

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

</style-sheet>

	  

In both cases, you'll have to tell Jade to use your stylesheets, here myprint.dsl:


	jade -t tex -V tex-backend \ 
                -d myprint.dsl \
                /usr/lib/sgml/declaration/xml.dcl myfile.db
	

Customizing the DocBook DTD

DocBook is intended to be customizable. There are many ways to do that[3], but be careful: customization may lead to problems when exchanging documents with others. See Customizer's Guide for the DocBook DTD (the link will work only if you installed the package "docbook-doc").

If you add new elements, you'll probably have to create a custom stylesheet as well.

Notes

[1]

And also because future versions of DocBook will be XML.

[2]

Just ignore the warning

/usr/lib/sgml/declaration/xml.decl:1:W: SGML declaration was not implied

[3]

Including copying the DTD and editing it... But I was referring to `clean' ways of modifying the DTD, which will not create too many problems with future versions of DocBook.