[
https://issues.apache.org/jira/browse/OFBIZ-6450?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14587646#comment-14587646
]
Sharan Foga commented on OFBIZ-6450:
------------------------------------
Thanks for looking into thing Taher. I've been talking to a few people about
what you have mentioned here think I have found a bit more about our Docbook
story.
My understanding is that that when Docbook was originally installed in OFBiz,
it rendered the online help dynamically with the XSLT template and this gave
some real performance issues so an alternative solution was investigated.
Instead of rendering the help using the full XSLT template a FTL template was
created (HelpTemplate.ftl) which contained a very small subset of Docbook tags
for translating and displaying the online help files. This was done to speed up
the display and rendering of the help.
The HelpTemplate.ftl was created as a template dataresource in Content Manager
which is used for all the online help pages. So I think this FTL file formats
all the Docbook files and then it is rendered by renderContextAsText in the
ContentWorker.java
Based on this I think we now know why not all the Docbook tags work and also
why the complete XSLT translation is not happening.
BTW the CMS also contains a link that consolidates all the current online help
docbook files here http://localhost:8080/cmssite/cms/APACHE_OFBIZ_HTML
It's a start but doesn't look that great or consistent so I'm going to work on
tidying up these Docbook files and move them into one book per application
The Webhelp solution works by doing a one time conversion all the Docbook files
to HTML and then it renders the HTML which is a lot faster than dynamically
rendering using the XSLT template. So an idea could be that when we build OFBiz
we could also 'build' the webhelp or the webhelp HTML file conversion could be
included as a separate ant target eg. ./ant create-webhelp.
I've put some outline tasks together for the webhelp as part of the Webhelp
Jira OFBIZ-6015
> Docbook and OFBIz Online Help
> -----------------------------
>
> Key: OFBIZ-6450
> URL: https://issues.apache.org/jira/browse/OFBIZ-6450
> Project: OFBiz
> Issue Type: Bug
> Reporter: Sharan Foga
> Assignee: Sharan Foga
> Attachments: 02-docbook_overview_diagram.pdf, humanres.xml
>
>
> Jira created based on the steps suggested by Taher as follows:
> - First, we attempt to fix whatever is wrong in DocBook at the moment. If you
> can share exactly what you spotted then this would save us a lot of time in
> trying to dig to the problem. So a repeat process to identify the bugs from
> you would be great.
> - Second, we decide on a category structure for the sections of the
> documentation if we do not like the existing one
> - We also introduce or enforce a workflow that mandates an update of the
> documentation on each JIRA that affects functionality that requires
> documentation. For example, if we add or modify a screen in the party
> component, then we must provide the documentation for that screen before
> closing the JIRA for example.
> - As a last step we decide on the appropriate technology to move forward.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
