After a few time spent on this subject and a few posts on this, I think I have reached the conclusion moment. Shortly, my goals were:
- to find a documentation format easy for writting and enough configurable as regards the generated output
- to allow different output formats
- light/easy/few tools required
I have taken into account the following formats:
- html
- docbook
- xdoc
- wiki
Some thoughts on each of them (thoughts that finally pushed me to the current solution):
- html way too related to output presentation
- xdoc quite powerfull and not very very linked to presentation. It misses a few things: imbricated section levels, meta support.
- docbook very powerfull, but way too complex (from both points of view: writting and configuration of output)
- wiki interesting, but the output is too limitted and requires a heavy solution (servlet container, except you are using the Wiki Plugin for Eclipse)
Conclusion:
An enhanced xdoc format (overpassing the missing features presented above) and a couple of XSLs to transform it either to a final document or to put it in the format of one of the other above mentioned formats.
Somebody could argue that I have tried to reinvent the wheel, but this is not the truth. I have added to the xdoc format just a few more things:
- level attribute for section element
- indefinite section recursion
- meta child element of properties element … and that’s all
I have already written 2 XSLs that transform it to HTML and Wiki and both are under 100 lines (even if I am not an expert of XSL). I will write another one that will transform my custom xdoc to Forrest xdoc and/or Maven xdoc and so I can use this format to generate a full site. Having only XML and XSL files I can work with aproximatively whatever editor in the world (for the moment I prefer using JEdit) and I can trigger the transformation process with a 10 lines Ant build script.
In the next days I will start posting the custom xdoc DTD and an example, than the Wiki XSL (this is very intersting indeed) and the lite HTML transformer.
If you are interested or you have other suggestions for me just drop me a line.
mindstorms 
I’m definately interested in what you come up with. I use forrest quite a bit for my open source project and one of my partners has been experimenting with Docbook for some architectural documentation. We haven’t integrated the two yet but we plan to.
– Robert McIntosh
robert.mcintosh@zurichna.com
For simple xdocs you can even use OpenOffice and edit it completely visually. At the end, just put the .swx file from OO in the content path for generation. Quite neat.
See http://www.logemann.org/blojsom/blog/default/2005/03/25/Apache_Forrest_for_freaks_only.html
for my latest Forrest efforts 😉
Have you looked at DITA? It’s like DocBook but simpler. It can also be mapped to any arbitrary ML through the use of topic specialization and domain specialization.
DITA toolkit including DTD and XSL to output HTML and PDF. http://www-106.ibm.com/developerworks/xml/library/x-dita6/x-dita_downloads.html
DITA intro.
http://www-106.ibm.com/developerworks/xml/library/x-dita1/index.html
DITA spec.
http://www.oasis-open.org/committees/download.php/12091/cd2.zip
DITA coverpages. http://xml.coverpages.org/dita.html
DITA intro series. http://www.arbortext.com/resources/xpn_jun_04.htm
DITA marketing overview.
http://www.idiominc.com/products/worldserver-DITA.asp
Hi,
I just implemented a prototype of an documentation plattform based on Forrest (forrest.apache.org) and DITA. Since I don’t want to expose our documetation authors to the DITA format, we’ll be using the XMLMind XML Editor for the content creation part.
The prototype works very well.
best regards,
Roman