DocBook — documentation in hand

If you've ever created a document of any kind, or you're about to, 
 you'll probably run into one of the following problems along the way, if you haven't already.

The need for a readable, open format
 The document was created in an editor that produced a file in a proprietary format.
 Independence from the output medium, or at least easy conversion
 The document was created for one medium, such as electronic publication, but you need to distribute it another way, such as in print or as audio.
 An easy way to work on the document
 The document already exists and you need to edit, share or extend it.

These problems affect any kind of document you can imagine, 
 whether it's an article for a local newspaper, an academic publication, a book, 
 hardware or software documentation, or a user manual. 
 All of these problems have something in common. They arise when you mix what 
 a document expresses with how it's presented.

What we need, then, is a language that describes the meaning
 and structure of the information instead of its presentation. XML is well suited to structuring information. All that remains
 is to define the tags that describe that structure, and that's precisely what DocBook does.

At heart, DocBook is simply a DTD that defines the structure of an XML document. DocBook
 plays the same kind of role as XHTML. Both XHTML and DocBook specify only which elements you can use and where 
 you can use them. When we write a document in DocBook, we're producing XML data described in the
 DocBook language.

The advantages of XML and good semantics, meaning expressive power,
 make DocBook one of the most widely used applications of SGML and XML (second only to HTML, according to J. Kosek).
 From here on I'll talk about DocBook as a system. XML and the DTD form the core, around which
 tools for processing documents have grown and continue to grow.

DocBook offers a wonderful feature I'd call writing once and presenting in many ways. If we write an article in DocBook about 
 Matěj from a little backwater, we can easily transform it into HTML for the web
 and RTF for the local newspaper office running a pirated office suite. Likewise, we can write a book, give the printer a PostScript version 
 and put the electronic version on an FTP server as a PDF.

From its beginnings to the present

DocBook came into being in 1991, created by HaL Computers and the publisher O'Reilly. Over the years large companies such as Hewlett-Packard, SCO and Fujitsu used it extensively. In 1999 DocBook came under the stewardship of OASIS, and it's still evolving.

DocBook was originally used to write Unix documentation. By now it has also been used, for example,
 for documentation for Linux, PHP and FreeBSD, and by companies such as Sun and the publisher 
 O'Reilly mentioned above. Today's DocBook goes well beyond its original purpose. It's easy to write an article, book or other kind of document. DocBook can also generate indexes and provide other features customary for the type of document.

DocBook output formats

Output formats are among the most valuable things DocBook offers. Some of the best known are

• Web — HTML, XHTML
• Print — RTF, PDF, PostScript, LaTeX
• Help — HTMLHelp, JavaHelp

There are more output formats, and support is expanding. An XSL transformation helps produce this variety 
 by generating a format directly, as with HTML or XHTML, or by transforming the document into an XSL-FO object, which the appropriate FO processor converts into the output format. A third option is to use DSSSL stylesheets, which are a little older.

Most of the tools you'll need to generate the format you want are distributed under licenses 
 that let you use them freely, including for commercial purposes. How to set up these tools and 
 use them with DocBook is described in the freely available electronic book 
 DocBook: The Definitive Guide.

You can find more information on the official DocBook site and especially on the home page of Jiří Kosek,
 who is closely involved with DocBook. There you can also find his invaluable guide,
 rather modestly titled DocBook — A brief introduction to creating and processing documents, which goes into much more detail. 
 Jiří Kosek has even put together a DocBook installation package for Windows.

The drawback of DocBook comes when you write the XML. To start you'll have to learn basic XML rules 
 and a handful of structural tags. For someone who understands even a little of what 
 DocBook offers, that isn't a problem. But try explaining to a secretary that she won't be writing meeting minutes the way
 she's used to in a WYSIWYG editor like Word. She'll have to work in a world of angle brackets. 
 There are WYSIWYG editors that produce DocBook XML, of course, but they're expensive.

Updated 14 November 2003 at 12:30

Zdenek Bohdanecky Jr. pointed me to the AUTHENTIC 2004 editor from Altova, which should also support DocBook. I found an interesting statement on the editor's website, which I quote: “authentic™ 2004 is offered under a free software licensing model. (Yes, completely free).”

Updated 13 November 2003 at 7:20

It turns out there is a usable editor with built-in DocBook support and even a Czech interface, as Jiří Kosek wrote to me.

A more intrepid secretary could perhaps manage the following editor:

XMLmind (http://www.xmlmind.com/xmleditor/)

The editor installs with the DocBook DTD and XSL stylesheets, so 
 you just select New -> DocBook Document from the menu and start writing. The editor 
 interface is even available in Czech.