After a few years I’m looking at Docbook again. The theory is excellent, particularly for creating Technical or Help guides; you create your ‘document’ once – in a neutral language/format – and then you can publish it in many ways. For example you can generate a:
- PDF file
- Rich text (like MS Word)
- Web Page, with CSS style sheet to pretty it up
- Help file, such as compiled HTML
The actual neutral format is XML. And therein lies my list of things to investigate. XML is fantastic for such purposes, but isn’t the most friendly thing to edit, if you just attack the raw data. It looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Very simple book</title>
<chapter xml:id="chapter_1">
<title>Chapter 1</title>
<para>Hello world!</para>
<para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
</chapter>
<chapter xml:id="chapter_2">
<title>Chapter 2</title>
<para>Hello again, world!</para>
</chapter>
</book>
So my questions are:
- Is there a good GUI editor that understands the Docbook XML format, but hides it? In other words, makes it look like MS Word or Open Office.
- Can it spell check, including Australian English and have the ability to add your own words?
- How easy is it to do the final publish (i.e. transform) into PDF, Web Page etc
- Is the whole thing a compromise? Wonderful in theory, but the final Web Pages etc are pretty plain or hard to navigate.
- Does Docbook support cross-referencing? Vital for technical documents. You create a screen capture, add it to your document, then refer to it in the text; “see Figure <cross-reference>”
So far I’m using the open source Eclipse platform to handle the editing and – via Ant – the ‘automatic’ conversion. I got it to work yesterday, and a PDF was created. Today I’m taking the same ‘source’ (i.e. the Docbook XML) and trying to get it to generate a Web Page, then standard Help file (compiled HTML).
It’s not for the feint hearted, but I’m getting there. I’ve got a feeling you do all the hard work in the original set-up and configuration stage, then after that things become quite straightforward. We’ll see.
There are editors such as Conglomerate that try to hide it, but in my investigations a year or so back I never found a convincing editor. Like you, I love the theory, but there’s no way one can really expect your average office user (ie used to Word and the like) to make sense of DocBook. It remains in the Ubertech, till a decent editor comes about. The general markup languages such as SiSu converting to DocBook can take some of the pain away.
To some degree, LaTeX (and editors like Lyx) try to do similar things. A plain text format, separation of style from content, and I still think the output from LaTeX is superior to OpenOffice, Word, and things like DocBook (though you can pass DocBook through TeX). The thing that holds LaTeX back (aside from the market share .DOC files have and that your average non-science/maths graduate would never have heard of it) is there is no easy way to create style or “templates” (to use Word parlance) without hard labour. If there were, a lot of the time offices waste on formatting their reports and getting the figures right and pagination etc would disappear.
Very true and not just the editor, the whole processing environment. I too can’t see any non-ubergeek tech writer trying to get XML parsers going and reading through Java errors when things go wrong. I was using Eclipse and that did hide some of the complexity, but only partially.
I think I read that OpenOffice 3.x is going to support DocBook a bit more. I would have thought that it – already being XML based – would have been a natural fit. But then again there’s bound to be reasons, both technical and political, why it may not.
From my first year at work (1983) I got used to the Mark-up concept, with IBMs wonderful GML/Script. My understanding is that these evolved into SGML, HTML and XML.