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, but most of what is written here apply to the SGML version as well.
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>
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
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
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
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
Since the manipulations needed to convert from DocBook to anything can be complicated, the use of make is recommended. An example of a Makefile is:
MAX_TEX_RECURSION=4 XML_DECL=/usr/lib/sgml/declaration/xml.dcl HTML_SS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl PRINT_SS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl all: myfile myfile: myfile.ps myfile.txt myfile.html myfile.tex: myfile.db jade -t tex -V tex-backend \ -d $(PRINT_SS) \ $(XML_DECL) $< myfile.dvi: myfile.tex # Trick from Adam Di Carlo <firstname.lastname@example.org> to recurse jadetex # "just enough". -cp -pf prior.aux pprior.aux -cp -pf $(shell basename $< .tex).aux prior.aux jadetex $< if ! cmp $(shell basename $< .tex).aux prior.aux && \ ! cmp $(shell basename $< .tex).aux pprior.aux && \ expr $(MAKELEVEL) '<' $(MAX_TEX_RECURSION); then \ rm -f $@ ;\ $(MAKE) $@ ;\ fi rm -f prior.aux pprior.aux myfile.ps: myfile.dvi dvips -f $< > $@ myfile.html: myfile.db html.dsl jade -t sgml \ -d $(HTML_SS) \ $(XML_DECL) $< myfile.txt: myfile.db jade -t sgml -V nochunks \ -d $(HTML_SS) \ $(XML_DECL) $< > dump.html lynx -force_html -dump dump.html > $@ -rm -f dump.html validate: nsgmls -s -wxml $(XML_DECL) myfile.db clean: rm -f *.html *.aux *.log *.dvi *.ps *.tex *.txt
Localization (often written l10n to save space) is the adaptation to a different language. Let's take French (whose ISO code is "fr") as an example: DocBook can be l10n'ed for other languages (see /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/common/dbl1* for a list).
With the XML version, you have two ways to tell the language:
Using the lang attribute.
<article lang="fr">And you will get labels ("Table of contents", "Next", "Previous", etc) in French.
In the custom stylesheet:
(define %default-language% "fr")
It is not a complete l10n: hyphenation in the TeX output will not be correct, for instance.
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
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
DocBook is intended to be customizable. There are many ways
to do that,
but be careful: customization may lead to problems
when exchanging documents with others. See
If you add new elements, you'll probably have to create a custom stylesheet as well.
And also because future versions of DocBook will be XML.
Just ignore the warning
/usr/lib/sgml/declaration/xml.decl:1:W: SGML declaration was not implied
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.