Here is a POC.
One reason to give this POC a look is because most other open source project documentation uses XSL transformations for presentation formatting (duh - no surprise). The OFBiz help documents, though written in DocBook, are limited in the number of supported DocBook tags. This limitation can be overcome by using DocBook XLS.
Here is patch for a POC in the form of a OFBiz component that loads into hot-deploy. Sadly there is no OFBiz dog food in the component. But maybe inventive minds will suggest the best way to deploy all these HTML files in an OFBiz way if Java Help is unacceptable.
To get started:
1. Apply the patch.
2. Get a copy of DocBook XLS from http://sourceforge.net/projects/docbook/files/docbook-xsl/1.77.1/docbook-xsl-1.77.1.zip
3. Unzip into the component (root of ofbizhelp).
4. Read readme.txt for a description on contents and usage.
Note: image files are not included in the patch. You may have an issue running ant task from the patch. I tested in Eclipse and for some reason they would not execute. I had to create a new component (using the ant task create-component), copy the build.xml into the new components build.xml then copy other files to get it to work. Ugly! You may have better luck. May the force be with you.
A few words on options when using docbook-xsl-1.77.1
If you follow the current OFBiz help document practice of creating many files in a single folder, each containing a DocBook section, the output from the ant task build-javahelp will be a useless flat compilation of files in a single folder (this is why there are separate task for building accounting and OFBizBook.xml).
If however, you put your content in a folder structure that matches the desired output structure, then the html docbook-xsl will recurse through the folders and create the output in a structure matching the folder structure. This can be used by the Help Master tool (see readme.txt) to easily create a Java Help TOC. The patch contains the accounting help in such a structure. See data > helpdata > docbook > accounting. The final output, that can be viewed as Java Help, after creating the Java Help with Help Master is in ofbizhelp > webapp > ofbizhelp > javahelpacct.
An alternative is to create your content in a single DocBook book file (see help > data > docbook > humanres > OFBizBook.xml). The advantage of writing in a single file is that structure is managed for you by the XLS java help transformation. Also links between tags are easier to create and maintain. DocBook books have chapters which support fine grained structure tags sect1 thru sect5. The OFBiz DocBook files are limited to the top level section tag.
When you generate Java Help from a book tag, the table of contents structure is created automatically. One click on the ant task does it all.
The patch has all the support jsp files needed to run java help from the OFBiz container, but for reasons known only to the java gods, it does not work. The helpBroker does not appear to get initialized. I'm sure sharper minds them mine can figure this out, I'm just putting this on the back burner for now.
As a work around, using Help Master, you can view the finished products located in:
- help > webapp > ofbizhelp > javahelpacct
- help > webapp > ofbizhelp > javahelpmaster
Final word - this is a rough cut. I will be surprised if it works OOB, but it does work and the bonus for getting it working is a easy to maintain, scalable and richer OFBiz Help system.
I will be happy to respond to any questions or calls for help.