[
https://issues.apache.org/jira/browse/OFBIZ-4941?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13393620#comment-13393620
]
Tom Burns commented on OFBIZ-4941:
----------------------------------
Jacques,
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.
Tom
> Proposal for a new help system
> ------------------------------
>
> Key: OFBIZ-4941
> URL: https://issues.apache.org/jira/browse/OFBIZ-4941
> Project: OFBiz
> Issue Type: Wish
> Components: ALL COMPONENTS
> Affects Versions: SVN trunk
> Reporter: Jacques Le Roux
> Priority: Minor
> Fix For: SVN trunk
>
> Attachments: HelpAccounting.jpg, HelpPerformanceReview1.jpg,
> HelpPerformanceReview2.jpg, HelpRoadmap.jpg
>
>
> Quoting Tom Burns at OFBIZ-4869
> {quote}
> This is a status update just to let anyone who is interested know that this
> item is being worked on.
> I started out using the OFBiz structure for help docs but after a while I
> needed/wanted something more expressive.
> Here is what I wound up using for development:
> Java Help System http://java.net/projects/javahelp/content
> DocBook 5: The Definitive Guide
> http://www.docbook.org/tdg5/en/html/docbook.html
> http://www.docbook.org/xml/5.0/
> DocBook XSL: The Complete Guide
> http://www.sagehill.net/docbookxsl/index.html
>
> http://sourceforge.net/projects/docbook/files/docbook-xsl/1.77.1/docbook-xsl-1.77.1.zip
> Help Master - FE for managing java help files. Best feature drag and drop
> TOC creates TOC matching file folder structure. Convenient launcher for
> viewing & testing. http://www.halogenware.com/software/helpmaster.html
> XML Mind XML Editor - Free Personal Edition is far better then editing in
> Eclipse. download from http://www.xmlmind.com/xmleditor/download.shtml
> Tutorial - DocBook editing with XML Mind XML Editor. Worth going through
> http://www.xmlmind.com/xmleditor/tutorial.html
> Read Me First style guide from Sun (cost from Amazon 1 cent + shipping)
> Attached are some screen shots of the results.
> Every screen is/will be documented in a similar structure. This is as much
> for defining requirements and testing as for help. More work but worth it.
> The screenshots show a Java Help format generated using DocBook XSL. This
> will likely not be the final presentation format.
> Note the Performance Review screen shots do not match the trunk. There is a
> bug in update screen and I did some clean up of labels and drop-down list.
> There are issues like this all through the application so I did not want to
> get bogged down with patches at this time.
> {quote}
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
