Charles Engelke's Blog

December 15, 2003

Rendering DocBook Files

Filed under: docbook — Charles Engelke @ 2:15 pm

Okay, we’ve created a valid DocBook file. Later on, we’ll delve
deeper into all the different kinds of elements available, and when
they should be used. For now, we have a simple question: how do
we convert this (nicely structured but almost unreadable to
humans) file to a better format for delivery? How can I get my DocBook
file rendered as HTML, or PDF, or other, more exotic formats like
CHM (Microsoft HTML Help)?

One perfectly valid way to do this would be to write computer
programs to perform each different kind of translation. Perhaps
we would have programs named docbook2html, docbook2pdf, and
docbook2chm. Run the appropriate program with our DocBook file
as input, and it would give us the output. Of course, we don’t
want to write any computer programs right now, but we’d gladly
take some that someone else had written already and use them.

One such suite of programs is GemDoc.
You can download
it and try it for 14 days for free, or buy it for only $100. It’s
really easy to use; just select the source file and check all the
output formats you want. Just click a button and watch it create all
those polished files for you. It does have one quirk that annoys
me: your DocBook filename must end with
XML or
SGML, not
docbook. I use XML files
for all sorts of things, so that generic extension doesn’t help
me keep track of DocBook files.

Despite that mild complaint, I think
GemDoc
is great, and strongly recommend it. It’s much easier to set up
and learn to use than any other DocBook publishing tool I’ve
found so far, and let’s face it, if it’s too hard to set up the
tools you need, you’ll probably give up on DocBook before you’ve
really had a chance to try it.

Tip

Info Tech staff:
I’ve asked the IT staff for blanket permission to install
the software mentioned in this DocBook project blog on
Info Tech PCs.
The request was approved, so you can go ahead and download
and install GemDoc or any other tools mentioned here without
first notifying asking.

I want to understand the publishing process very well, and exercise
fine control over it, so instead of sticking with GemDoc I’m
going to work with lower-level tools, all of them open source.
GemDoc is actually built on top of many of those tools, so we should
be able to get similar results. The rest of this chapter is concerned
with installing, configuring, and using those tools. By the end of
the chapter, we should have a robust and productive DocBook
publishing environment on our PCs.

Advertisements

Blog at WordPress.com.

%d bloggers like this: