Playing With DocBook 5.0

21 Jan '06 - 15:06 by benr

DocBook 5.0b2 has arrived, and its time to leave any hesitation of migration from DocBook 4.x behind. Personally, I've been off in LaTeX land for some time now (as you can see). At least for me, the LaTeX vs DocBook argument is a simple trade off: LaTeX is faster for producing documentation, but lacks the diverse transformation capabilities offered by DocBook XSL. Since I personally prefer PDF output, LaTeX works beautifully and generally looks much nicer when printed compared to DocBook. Frankly, while both LaTeX and DocBook XSL are customizable, both are a massive pita and generally short of simple minor modifications I stick to the defaults created by the gurus. I love the simplicity of LaTeX but DocBook really is a better and more flexable system, so long as you don't mind constantly refering back to the DocBook Element Reference and typing everything out in longhand. Even still, using a proper tag like >envar< is definately superior to just putting these things in it italics.

Getting started with DocBook 5.0 on OpenSolaris is a peice of cake. You'll only need to download two things: the DocBook XSL stylesheets, and FOP, the Apache Format Objects processor for tranforming FO into PDF. To start you DocBook 5.0 journey, just download those two files (I'm using docbook-xsl 1.69.1 and the binary release of FOP 0.91beta-bin-jdk1.4). The other tool you'll need is xsltproc, which you lucky Solaris users will be happy to realize is already sitting in your /usr/bin, ready to use.

Download the XSL and FOP and unpack them in the directory of your choosing. I put mine in ~/DocBook. Now go and create your document. Here is a small example:

<?xml version='1.0' encoding="UTF-8"?>

<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
   
<articleinfo>
        <title>Cuddletech Programming Series </title>
        <subtitle>Intermediate C Programming</subtitle>

        <author>

                <firstname>Ben</firstname>
                <surname>Rockwood</surname>
                <affiliation>
                        <shortaffil>CDLTK</shortaffil>

                        <orgname>Cuddletech</orgname>
                        <address> <email>benr@cuddletech.com</email> </address>
                </affiliation>

        </author>
</articleinfo> 
                  
<section>   
<title>Intro</title>

<para>
Learning C can be as easy or difficugt as you want it to be.  This chapter
is intended to be a quick refresher and guide thru the basics of C.  Hopefully
this will fill in any gaps new coders have and get them on their way to EFL bliss.
</para>

             
</section>
</article>

If you've used DocBook 4.x in the past you notice that there is no DOCTYPE following the initial XML declaration, instead there is an XMLNS (Extensable Markup Language Name Space) associated with the ARTICLE tag. The same is true for a BOOK. This greatly simplifies things and puts the old "local or network DTD" arguments to rest. No more DTD's in fact, we're using RELAX NG now. The diffrence really isn't that important to the author however, from a writters point of view you won't notice a diffrence beyond the DOCTYPE things, but should you ever peak under the hood you'll see that RELAX NG is way cleaner than the old 4.x DTDs.

Once you've created your document (typically given a .xml or .db file extention, although I prefer .docbook to make things more self evident) you can go about the business of transforming it into something a little prettier. This is where the XSL (Extensible Stylesheet Language) comes into play. Using the xsltproc tool, you can specify the XSL to use to transform your spiffy DocBook 5.0 XML file. Lets first convert the above document into HTML:

$ /usr/bin/xsltproc -o sample.html /home/benr/DocBook/docbook-xsl-1.69.1/html/docbook.xsl sample.xml
Stripping NS from DocBook 5/NG document.
Processing stripped document.
$

Thats pretty painless right? To convert to PDF we'll need to use a two step process. First we'll use xsltproc to produce a FO (XSL Format Objects) document, and then we'll use FOP to proccess it into a finished PDF.

$ /usr/bin/xsltproc  /home/benr/DocBook/docbook-xsl-1.69.1/fo/docbook.xsl sample.xml > sample.fo
Making portrait pages on USletter paper (8.5inx11in)
$ /home/benr/DocBook/fop-0.91beta/fop sample.fo -pdf sample.pdf
$

Once you have the PDF you can check it out with gpdf or Acroread and then trash the FO.

Is that simple or what? Now that you've got the tools figured out you can concentrate on learning the DocBook markup itself. I recommend that you flip through DocBook 5.0: The Definitive Guide and DocBook XSL: The Complete Guide. You'll spend most of your time, early on, flipping through and getting to know the Element Reference.

If your an experienced and comfortable DocBook 4.x author, please check out the The DocBook 5.0 Transition Guide for a quick update on the new changes.

To make life easier on me, I use a Makefile to generate my output. This way I can make an edit in vi and then make pdf to update the output. Here is an example of the Makefile template I use:

### cuddletech.com - DocBook XML Document Transformation Makefile

### Document filename without suffix (.xml):
FILE = chapter2 

XSLTPROC = /usr/bin/xsltproc
FOP = /home/benr/DocBook/fop-0.91beta/fop

XSL_PREFIX = /home/benr/DocBook/docbook-xsl-1.69.1

HTML_XSL = $(XSL_PREFIX)/html/docbook.xsl
FO_XSL = $(XSL_PREFIX)/fo/docbook.xsl   

all: pdf html

fo:
        $(XSLTPROC) $(FO_ARGS) $(FO_XSL) $(FILE).xml > $(FILE).fo

pdf: fo 
        $(FOP) $(FILE).fo -pdf $(FILE).pdf
        rm -f $(FILE).fo

txt:
        $(XSLTPROC) $(FO_XSL) $(FILE).xml > $(FILE).fo
                $(FOP) $(FILE).fo -txt $(FILE).txt
        rm -f $(FILE).fo

html:
        $(XSLTPROC) -o $(FILE).html $(HTML_XSL) $(FILE).xml


clean:
        echo "REMOVING EVERYTHING BUT MAKEFILE AND XML SOURCE!!!!!"
        rm -f $(FILE).html
        rm -f $(FILE).pdf $(FILE).fo
        rm -f $(FILE).txt

check:
        xmllint --valid --noout $(FILE).xml

You can modify the output created by xsltproc, such as changing the page size or creating 2 column output, by passing arguments to xsltproc. The following line added to the above Makefile (above the "all" line) will generate a 7" by 9" (standard tech book size) 2 column output:

FO_ARGS = --stringparam page.height 9in --stringparam page.width 7in --stringparam column.count.body 2 --stringparam column.count.back 2

For a look at all the --stringparam's you can pass, look in the param/ directory within the docbook-xsl package.

If you have something to add to the world, whether it be something your interested in or something that you think took you too long to learn please consider writting about it! Often it is the beginners that make the best authors because they understand the frustrations involved rather than being an old pro without empathy for the beginner. No one will mock you if you make a mistake or flame you for being a n00b, but hundreds of users just like you will benefit from your experience and knowladge. Don't be shy!

Want to write for the OpenSolaris Project? We'd love to have you. Feel free to stop by the OpenSolaris Documentation Community and find out how you can be involved!

- - C O M M E N T S - -

Hello, nice site looks this

tracey (Email) (URL) - 12 June '06 - 13:51

I like this site!

micheal (Email) (URL) - 13 June '06 - 02:17

Very interesting & professional site. You done great work.

ivory (Email) (URL) - 13 June '06 - 02:21

I like this site!

elton (Email) (URL) - 13 June '06 - 17:43

Hi you have a nice homepage

dollie (Email) (URL) - 13 June '06 - 21:41

Hey man…sorry I missed the party.

Peter (Email) (URL) - 14 June '06 - 03:37

Personal information





Remember your information?
Comment

Small print: All html tags except <b> and <i> will be removed from your comment. You can make links by just typing the url or mail-address.


^M