Charles Engelke's Blog

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.

(more…)

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.

(more…)

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

(more…)

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
sheet (which is another XML file in a particular
syntax for XSL), and produces as output whatever the style
sheet specifies.

(more…)

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

(more…)

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.

(more…)

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.

(more…)

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

(more…)

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.

(more…)

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.

(more…)