Creating documentation with DocBook

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
	    

Automatize it with make

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 <[email protected]> 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 (l10n) of the output

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:

1. Using the lang attribute.

   	    <article lang="fr">
   
   	  

   And you will get labels ("Table of contents", "Next", "Previous", etc) in French.

2. 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.

Misc

To convert DocBook to man pages or other formats, see docbook2man (Debian package) and docbook-to-man-ans (Debian package).

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.