| Chapter 3. How do I write a DocBook document? | ||
|---|---|---|
 |  | |
| Chapter 3. How do I write a DocBook document? | ||
|---|---|---|
| | | |
Contents
This is easily the most difficult thing to get used to when composing in DocBook or DTD that tries to focus on semantics rather than presentation. There's not one short or even long answer to the question of what the best authoring environment is, but recently a couple of editors have made strides in solving the problem of how to represent semantics and reasonable presentation at the same time.
WYSIWYG is ultimately impossible any time you produce multiple outputs from a single source. This subject is discussed every few months on one of the XML or DocBook lists.
See a list of DocBook authoring tools at the DocBook Wiki.
In addition to providing help authoring instances of DocBook XML (or any DTD) by indicating what elements are valid at what points, these tools validate documents. When a tool validates a document, it compares the XML to its DTD to see if it conforms to the DTD. If the document does not conform to the DTD, the tools typically try to indicate what and where the problem is, though they can't always tell you exactly what is wrong.
XMLMind XML Editor - XXE (Lite, but functional version free for “internal use”; ~$220 for a fully enabled version) : XMLMind uses CSS2 plus some extensions to present the document in a way that approximates what its final presentation might be. That is, lists look like lists, tables like tables, and so on. The editor also provides visual cues to indicate what element is currently selected and what your context is. A node-path bar shows the exact context and allows the writer to select a specific node. XMLMind supports xinclude, but has limited support for entities. If you're starting out, you can probably avoid the things that XMLMind can't do with entities, but if your existing docs or publishing system already requires that you use them, XMLMind may not be for you.
Syntext Serna (~$254) : Serna uses xslt and xsl-fo to style the document while you type and also uses tooltip-like visual cues to indicate where you are in the markup. Serna has full support for entities and allows you to edit them in context in the document. Another nice feature is that xrefs are resolved in the editing view, so it's even closer to wysiwyg.
emacs + psgml mode and nsgmls(free): The one true editor. Great if you like to look at tags. psgml mode gives you quite a bit of help and it is very stable. You have to edit tables by hand, however.
Arbortext Epic (c. $700?/seat): I have only demoed this briefly, but it has got a reputation of being the Rolls Royce of XML editors.
XMetaL: BlastRadius, formerly Corel, and before that Softquad (c. $470?/seat): XMetaL has some nice features, but requires that you customize it to make it's WYSIWG interface usable. It's really unfortunate that they don't include a DocBook kit that works “out-of-the-box”. I'm happy to share my macros etc. if anybody asks though.
Adobe FrameMaker 7 ($870): Based on what I've read on mailing lists, FrameMaker is not up to the task of providing you with and editing environment for DocBook. It contains a DocBook kit, but it would need lots of configuration before it would be useful.
XML Spy/Authentic ($400 / $0): Really more suited to the needs of “dataheads” and forms. Authentic, which allows you to edit and validate documents, is now free. It contains a DocBook kit, but it would need lots of configuration before it would be useful.
There are a few other editors at various levels of maturity. I hear Oxygen and Morphon mentioned sometimes.
I'm not discussing DSSSL or fosi here.
Most of the tools that transform XML documents are command line. Example using xsltproc:
xsltproc -o output.xml path/to/html/docbook.xsl input.xml
To use XSL to go to HTML Help, you must also run hhc or use the HTML Help workshop to compile the chm.
XSL does not take you directly to pdf. You use XSL to convert the DocBook document to xsl-fo, then use a fo renderer to convert that document to a pdf or postscript file.
There are several convenience tools that hide the transformation process from you to one degree or another. You certainly need either one of these or something you write yourself (a batch file, shell script, perl script, make file, ant script)
| |  | |
| 2.3. What can DocBook be made to look like? |  | 3.2. What is fo and what is a fo renderer? |