pf » DocBook vs Apache Forrest

March 14, 2005

DocBook vs Apache Forrest

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 seperate 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:

Anyone out there using either of these documentation frameworks? Experiences, or good tools I missed? Any other good documentation frameworks?

Permalink | Add Comment |

add to del.icio.us | Tags: documentation, docbook, forrest, xml

7 people found this page useful, what do you think?

Trackbacks

Trackback Address: 267/60C3F85B42CE63D96760DD5B41EB8E27

Comments

On 03/14/2005 at 4:06:38 PM MST rob wrote:

Check out XXE for docbook. The spell checking alone is pretty sweet. If you know xml you should have a big learning curve, but check out the documentation for it as there are lots of neat short cuts. http://www.xmlmind.com/xmleditor/ (standard version is free :-D)

On 03/14/2005 at 4:14:13 PM MST rob wrote:

That should read "If you know xml you shouldn't have..." and you might want to check out Vex too if you haven't already http://vex.sourceforge.net/

On 03/14/2005 at 4:14:55 PM MST rob wrote:

Ok I suck it says vex right there derrr

On 03/14/2005 at 7:32:10 PM MST kyle wrote:

Unless the Conglomerate developers have radically updated it, it's not a great tool for doing any real XML editing.

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.

On 03/14/2005 at 11:44:00 PM MST Phil Cruz wrote:

For what's it's worth I used DocBook for CFCDoc (http://philcruz.com/cfcdoc). I went down that route before I found out about Forrest (so it's not like I evaluated both and chose DocBook). There are quite a few resources for it though and that helped to get up to speed.

On 03/15/2005 at 12:07:12 PM MST Kola wrote:

I use Forrest and write (technical) documentation from within CFEclipse using the free XMLspy Eclipse plugin. You can associate the document with the Forrest doc dtd for content assist. Works well.

On 05/13/2005 at 12:33:07 PM MDT Ross Gardler wrote:

With Forrest it is not an either/or decision. We support docbook as an input format, so use our own format for those "80% of cases" it works well and use docbook for the remaining cases.

It's also worth noting that Forrest also supports many other formats, such as various wiki dialects, POD, OOo, MS Word etc

On 09/10/2005 at 4:56:58 AM MDT Alex Griessel wrote:

Tried DITA (http://dita-ot.sf.net)? Nice for topic oriented documentation with content reuse and customization principles at the base of its foundation (adopts a topic/object orientation model for documentation).

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.

On 02/16/2006 at 4:37:05 PM MST SK wrote:

I have been using Docbook for sometime and it seems pretty solid. More so with the use of Vex (Eclipse Plugin). I do agree that it was a bit hard to set it up the first time. But it has been a very good experience from then on, especially because I can visually edit the document and I (most times) do not have to directly deal with xml.

But then, I think I read that Vex is not being supported right now. So beware of that.

On 07/27/2007 at 7:34:05 AM MDT Newcomer wrote:

Hi, I'm trying to use DocBook with VEX, too... How do you convert it to pdf or .chm? I'm trying also to install html forms to vex as well as docbook vers. 5 but I'm not able to d anything...What lacks is a real documentation...