Write once, publish anywhere?
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.