Charles Engelke's Blog

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.


December 2, 2003

Too smart for their own good

Filed under: Web Development — Charles Engelke @ 9:47 pm

It’s not rare for a website to be hard to use. Website development
is pretty difficult, and making it work well is a pretty tough
assignment. But sometimes very smart website developers work very hard
using difficult technology to produce a site that’s just awful to use.
If the developers had just been a bit lazier, or a bit less sophisticated,
the site would be much better.


December 1, 2003

Cleaning up this site’s looks

Filed under: Personal — Charles Engelke @ 3:17 pm

I’ve done some redesign work on this blog, as you can probably see.
Appearance is now controlled via CSS, instead of the 14 column (or so)
table it had. I also spiffed up the links in the sidebar, and added
a separate print stylesheet that will look better on paper than the
standard web design.

Create a free website or blog at