| Firebird Docset → Firebird Docwriters' Docs → Firebird Docwriting Guide → DocBook XML authoring tools |
|
|
|
Because DocBook is a non-binary format, you can use any plaintext editor like emacs, pico, Windows Notepad or vi to write your documentation. And indeed, some docmakers prefer this approach to other more sophisticated tools because it gives them full control over their text, and the hand-typed tags are always visible. But the drawback is that text editors can not validate your DocBook document: you'll only notice your mistakes when a build goes wrong. And the structure of your document – especially a large document – is also difficult to see in text mode, although a consistent use of multi-level indentation can do a lot of good here.
If you choose this approach or want to try it out, it would be a good idea to at least take an editor that's capable of XML syntax highlighting. A good one, and free at that, is ConText, available at http://www.fixedsys.com/context/. Unfortunately, ConText can't save in UTF-8 format. This is no problem for US-ASCII documents (save as DOS or Unix and you're fine), but as soon as you use diacritical marks or anything else above ASCII 127, ConText becomes as good as useless. A good, free alternative is SciTE at http://scintilla.sourceforge.net/SciTEDownload.html. It's less intuitive, but very powerful.
Don't save documents containing non-US-ASCII characters as 8-bit, in ConText or any other editor! Anything other than US ASCII has to be saved in a Unicode encoding, such as UTF-8 (for most languages) or UTF-16 (for some languages, if the UTF-16 file length is smaller or at least not much bigger than UTF-8). Actually, these encoding issues are an additional good reason to use an XML editor: they will usually save in the right encoding automatically.
Dedicated XML editors often have graphical interfaces to make the tags stand out nicely (and sometimes irritatingly); many allow you to collapse and expand elements so you can view the structure of your document and at the same time zoom in on the element you're working on; they may also let you switch between different views. Most of them can validate your document against the DocBook DTD, and some even have a special DocBook authoring mode which allows you to write more or less like in a word processor.
The author of this guide has tried out a number of these tools (free ones, cheap ones, and evaluation versions) and found XMLMind XML Editor to be the most useful. This is a personal opinion of course; your experience may differ.
Some XML editors you may want to evaluate:
XMLMind XML Editor, or XXE for short. The Standard Edition is free.
http://www.xmlmind.com/xmleditor/
Runs on: Linux, Windows, Mac OS X. Requires Java, but you need Java anyway or you won't be able to build the docs from the sources – see the Firebird Docbuilding Howto.
Features: Tree view (all elements collapsible) and Styled view (chapters and sections collapsible). The latter is what I usually work in: it shows the document in a basic but clear word-processor-like layout, defined in a stylesheet that comes with the program. Both views can be active simultaneously. DocBook mode won't let you enter anything non-DocBook. Element chooser. Attribute editor. Edit and Search functions. Spell checker. Special character picker. Speedbuttons to create frequently used elements like sections, lists, tables, etc. What I miss is a plaintext XML source view.
Oxygen XML Editor. $ 48 for non-commercial use. Free 30-day trial.
Runs on: Windows, Mac OS X, Linux, Eclipse. Requires Java.
Features: XML source editor. Tree editor. Attribute editor. Outline pane. DocBook tag tooltips. XSLT debugger (a powerful tool, irrelevant to docwriting but great if you're also going to work on our transformation stylesheets). Validation, refactoring, spell-checking, etc., etc. A very good XML editor.
epcEdit. € 89 for non-comercial use. Free 60-day evaluation.
Runs on: Linux, Windows, Solaris. Requires Tcl/Tk 8.1 or above (included in package).
Features: Structure tree pane. Element chooser. Attribute editor. Document pane can switch between plaintext and graphic XML mode. No special DocBook mode, but can validate any XML document based upon its DTD.
Altova XMLSpy. The Home Edition is now free.
http://www.altova.com/products_ide.html
Runs on: Windows, Eclipse. (Also reported to run on Linux using Wine, and on Mac OS X using Virtual PC 6.)
Features: Text and Browser views. All elements collapsible in Browser view. Browser view is read-only. Element chooser. Attribute picker. Edit and Search functions. Special character picker.
There's a feature matrix comparing Home, Professional and Enterprise editions at http://www.altova.com/matrix_x.html.
This list is not meant to be exhaustive, but if you know a good XML editor (good from the perspective of a Firebird docwriter) that you think should be in here, please let us know via the mailing list.
|
| Firebird Docset → Firebird Docwriters' Docs → Firebird Docwriting Guide → DocBook XML authoring tools |