Pete FreitagDocBook vs Apache Forrest
By Pete Freitag
I've spent the last few hours looking at DocBook, and Apache Forrest two XML documentation frameworks. Basically what these two frameworks let you accomplish is separate your documentation content from your documentation layout, and display format. So you write all your documentation using one XML schema, then apply stylesheets to generate XHTML, PDF, RTF documentation.
We are currently trying to decide which format to use for our Java 1.5 based email server project. So far we are leaning towards DocBook because it seams more mature, and there are more tools for it, but Forrest seams to have a smaller learning curve.
I think Forrest's XML dialect covers 80 percent of the cases, with a much smaller learning curve, but for a large project that also needs to produce print documentation, DocBook merits consideration.
- The Server Side
DocBook as I mentioned does have lots of tools, though I didn't find any that I tried to be terribly great:
- Conglomerate - this tool looks promising but only works on Unix
- DocBook Template for OpenOffice - Had some trouble using this one creating sections, doesn't support all DocBook features.
- Vex - Vex is an Eclipse plugin that looked promising but I found it kind of hard to use.
- Big list of docbook tools
So we will probably just end up coding the XML by hand which is not that big of a deal, but It would be nice to have a visual tool for this.
One other advantage to DocBook is that there are some books written on the subject:
- DocBook: The Definitive Guide, ISBN: 1565925807 (O'Reilly XML)">
- DocBook XSL: The Complete Guide, ISBN: 0974152110
- DocBook XML Publishing, ISBN: 0761533311
Are you using either of these documentation frameworks? Do you have any experiences, or know of any good tools that I may have missed? Are there any other good documentation frameworks?
DocBook vs Apache Forrest was first published on March 14, 2005.
Weekly Security Advisories Email
Advisory Week is a new weekly email containing security advisories published by major software vendors (Adobe, Apple, Microsoft, etc).
Comments
From what I remember, it would show the XML document tree as a set of nested boxes within with you could edit the attributes or elements.
I was hoping to use it to do a DocBook manual for the IBM project I was working on the time but ended up using a simple text editor with syntax highlighting because it proved to be much easier to edit the document.
Personally, I love DocBook. For the various IBM projects I've worked on I typically create a usermanual using DocBook and then generate HTML and PDF copies of it for distribution. The only issues I've had with the entire process are the occasional bugs with Apache Fop when producing the PDF version from a formatted object.
It's also worth noting that Forrest also supports many other formats, such as various wiki dialects, POD, OOo, MS Word etc
The framework allows for documentation conversion to DocBook if needed but can handle the output of various formats ranging from pdf, chm, javadoc... The design allows for custom topic and domain types.