Charles Engelke's Blog

February 8, 2004

Producing Printed Output

Filed under: docbook — Charles Engelke @ 10:58 pm

The formats we’ve produced from DocBook so far are well-suited to
on-line documents. But sometimes we want to get printed output.
Sure, we could print the HTML version from our web browser, but
the quality of the result, and our control over things like
headers and footers, aren’t very good. We want to use DocBook
tools that will generate high-quality printed output.



DocBook to HTML Help

Filed under: docbook — Charles Engelke @ 10:58 pm

Microsoft’s HTML Help is a really nice format for on-line technical
documentation. The information is presented more or less in
HTML, but there are lots of nice additional navigation features
available. For example, not only do you get a table of contents,
as with multiple HTML pages, but you also get an index and a live
search function. And all of this is in a single
CHM file, instead of the
several different files you would have to copy if you were
deploying a multiple HTML page version of the document.


February 3, 2004

Creating Multiple HTML Pages

Filed under: docbook — Charles Engelke @ 5:51 pm

One problem using MSXSL as our XSLT
processor becomes apparent when we try to do something a bit
fancier: convert a single DocBook file to multiple HTML pages.
There’s a stylesheet to do that called chunk.xsl,
so we should be able to create the output with the command


December 19, 2003

DocBook to HTML

Filed under: docbook — Charles Engelke @ 1:10 pm

It turns out that DocBook conversions have been written, though not
exactly as separate traditional programs. Instead, DocBook
developers have set up a joint
open-source project
at SourceForge with lots of DocBook conversion tools. Instead of writing these
tools in traditional computer languages, they’ve built them on
top of general XML conversion engines (and older SGML conversion
platforms, but we’re sticking with XML). The conversion engines
being used are called XSLT processors.
An XSLT (eXtensible Style Language Transformations) processor
takes an XML file as input, along with an XSLT style
(which is another XML file in a particular
syntax for XSL), and produces as output whatever the style
sheet specifies.


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)?


December 7, 2003

Entering Some Content

Filed under: docbook — Charles Engelke @ 7:06 pm

Okay, we’ve created a legal DocBook file. Now let’s create a
potentially useful one, with content between <book>
and </book>. But we can’t just put
raw text there, or it won’t be a legal DocBook file, and we
won’t be able to process it.


December 5, 2003

Our First DocBook File

Filed under: docbook — Charles Engelke @ 3:21 pm

In this note we are going to figure out what a DocBook file is,
how to create it, and how to edit it. By the end of this note
we will have a legal DocBook file.


December 4, 2003

XML Basics

Filed under: docbook — Charles Engelke @ 7:33 pm

Before we get into the guts of what a DocBook book
is, let’s cover some XML fundamentals. It won’t take long.


December 3, 2003

Why Were These Notes Written?

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

I’ve been working with DocBook lately, and it’s turning out to
be a great technology for Appia’s documentation. I’m learning as
I go, and sometimes it seems that every step requires me to back
up and learn two prerequisite steps first. So it’s kind of slow
going. I’ve decided to make mastering the basics of DocBook a
project for the month. I’ll learn how to create and edit the
documents effectively, and how to publish those documents to a
variety of different formats. In the process, I’ll set up a
good workbench for DocBook development on my PC.


Hands-on DocBook

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

DocBook is an XML document type for books, articles, and
sets of books and articles. You can create a DocBook file
for your documentation, and then use DocBook tools to publish
it in a form suitable for reading.


Create a free website or blog at