Andy and I are about to start a new spurt of article and paper writing, so I’m looking around for some tools to make it easier. We publish to the web a lot, so being able to generate decent looking HTML is a plus. We also want to generate good-looking printed documents from the same source, along with PDFs. So I thought I’d look at DocBook. In the past I’ve always been put off by the hassle involved in generating nice looking output from DocBook, but perhaps this time necessity would overcome my natural laziness. So over to www.docbook.org I go.
Unfortunately, I’m still not convinced. This time is didn’t even get as far as the arcania of formatting objects. Instead, I was floored by an example in the DocBook FAQ. Here’s how the FAQ recommends you mark up the Emacs key sequence C-h C-f (control H, followed by control F, which normally displays help on a function).
<keycombo action="seq">
<keycombo action="simul">
<keycap>C</keycap>
<keycap>h</keycap>
</keycombo>
<keycombo action="simul">
<keycap>C</keycap>
<keycap>f</keycap>
</keycombo>
</keycombo>
Whoa! Some markup! And at first sight, pretty logical: a keyboard combination consisting of a sequence of two simultaneous key presses, the first a ‘C’ and an ‘h’, the second a ‘C’ and an ‘f’.
Except, this isn’t logical markup at all. It is some remarkably verbose hybrid. It totally fails to convey the most important fact about the keys you press, namely that you are pressing control and h, followed by control and f. Instead, it simply encapsulates the Emacs convention of showing an uppercase ‘C’ to mean control.
And why is this bad? Because I want true logical markup. In LaTeX, I’d define some macros to let me write
\KeySeq{\Control{h} \Control{f}}
This (to my mind) a lot easier to read and type. But more importantly, it gives me the flexibility I need. Perhaps in online documentation I want to use the ‘C-h’ convention. No problem, I just write the macro appropriately and every control sequence is documented accordingly. If a publication says that their standard for control keys is "^h ^f", then a single change to the macro updates the whole document. And if I want to use fancy pictures of keys, my macros can do that too.
It seems to me that DocBook is falling in to the same trap as the rest of the XML world, confusing tedious verbosity for semantic information.
Of course, I’ve never used it for anything bigger than a FAQ, so I could be wrong.
