Wednesday, January 30, 2008

DocBook: Reading Help Documentation Made Difficult

Over the past few weeks I've been learning all about XML (much overdue, I know). I've created my own file format with it's own DTD, even. Then I found out that DTDs went the way of the dinosaurs a few years ago. Oops. Well, I'm not learning anything else.

This all seemed really convenient because yesterday I downloaded a new Java package that has documentation shipped in DocBook format, an XML Schema format that can (supposedly) be compiled into a PDF, HTML, or other sorts of files. You would think that there would be something like "docbook2pdf" to compile it, but looking over the DocBook Wikipedia pages, and Googling all about DocBook, such a thing doesn't seem to exist. That would be too easy (if you think LaTeX-like document creation is easy).

Instead, I followed the ironically named "really quick guide to DocBook for Windows", which required me to install various cryptically named packages like "fop" and "saxon" (+ 3 more). Then I downloaded the "easy DocBook scripts for Windows" and edited the files to point to the install locations of the aforementioned packages. What a pain in the ass. Java has Javadoc for a reason! Compiling help documentation should not be so difficult.

In the end, I thought I was all done. I even registered "compile DocBook" as a right-click item for xml files. Then, I click it and get about 4 pages of error messages (sounds like LaTeX).

DocBook was started in 1991 and development continues today. I wish they would develop a simple front end for idiots computer scientists like me.

Computers, you've got a LONG way to go. Makes me excited, but also dismayed, to work in HCI.

No comments: