Jira 11693 created with a patch proposed if this solution is accepted, (and all asciidoc integrated) next step is to work component by component For each: 1. add in the component decorator <set field="helpAnchor" to to component Title in user-documentation 2. using heldata.xml to update all screens which had a dedicated text for help, with the new helpAnchor value
It's not a too large task, which can be maybe add in the task list for the next community days, and so finish the migration from docbook to asciidoc ;-) any thoughts? ps: this week, I will do this job for accounting component Le 11/05/2020 à 15:38, Olivier Heintz a écrit : > Hi community, > > First step about Docbook migration to asciidoc is done, all existing files > have been converted > (waiting a review before PR merge) > > Next step is to have a new help system, > > I propose to do a very simple solution which would be a link to a > documentation site. > This solution would use > 1. at ofbiz level, a default proprety for documentation website uri > 2. at the screen level > * it would be possible to give a other uri (for user documentation) > * if the anchor in the user documentation for this screen is put, the new > help is used otherwise the older link is used > > If this solution is validated, next step will be to update all the screens > with the correct link value > > I propose to create the Jira (and the implmentation) with this very simple > solution (using the doc generated by Buildbot as documentation site) > when some other people with a good knowledge of gradle and/or ofbiz cms have > time to do a internal documentation website, it will be possible to > change the default uri ;-) > > what's your opinion about ? > > > Le 26/02/2020 à 17:10, Olivier Heintz a écrit : >> inline >> >> Le 26/02/2020 à 14:02, Taher Alkhateeb a écrit : >>> Hello Olivier, >>> >>> Without digging into much detail, I can say that it's a good idea to >>> switch the online help system to asciidoc. >>> >>> The current structure of asciidoc templates is designed to be a full >>> manual document. To link up different pages to different sections, you >>> need to break the documentation down to smaller files and then combine >>> them. This way you can have both the "big" manual and the "per screen" >>> help section. >> >> In my experience, as I'm working with >> - current ofbiz online help >> - ofbiz webhelp >> - some static doc website done with Grav (build with multiple small files) >> - some static doc website done with asciidoc (only one large file) >> - ... >> >> With multiple small files it's needed to have a very good search engine and >> a global index / TOC >> >> With the One page doc, the TOC is very large and not always very convenient, >> but exist and the browser-find works >> and it's easy to navigate between details and generality >> >> So, as a user, I prefer help base on One page documentation. >>> >>> Also, gradle might not be enough for online help. A more robust >>> solution could involve integrating asciidoc at the framework level to >>> dynamically generate help. So this is another idea to consider. >> >> When we have tried, in the past to dynamically generate html from standard >> docbook process it was too slow >> it's why it was decide to use a freemarker template to do the generation, >> even if only 5% of docbook syntax >> was managed. >> >> Documentation not change very often, static page seem enough for our need. >> >>> >>> On Wed, Feb 26, 2020 at 2:29 PM Olivier Heintz <[email protected]> wrote: >>>> >>>> Hi all, >>>> >>>> Currently OFBiz Online help work with docbook files with html generation >>>> done by a ftl template. >>>> Link between screen and file to show is done with some content associated >>>> with key-word >>>> >>>> Decision has been done to no more used docbook format but now use asciidoc >>>> format. >>>> >>>> User-manual.adoc should be the new reference for user help. How to use it >>>> for online help ? >>>> >>>> I think it's important that online help is link to a internal help (which >>>> can be modified) not to a Apache-OFBiz-website-Help >>>> but this point of view can be discuss. >>>> >>>> To be able to have OFBiz internal help, three points should be solved : >>>> 1) with asciidoc we have multiple documentations, it seem important to >>>> have a "website" to be able to access easily all the doc. >>>> how to "encapsulate" each html documentation generated in a "website" >>>> 2) generation doc process put html and pdf files in build directory, how >>>> it's possible to access them from ofbiz >>>> 3) For online help it's necessary to be able to create link between screen >>>> and html anchor. >>>> In documentation generate from asciidoc, all title can be used. >>>> How to to say this screen should go to this documentation at this title. >>>> >>>> I suppose content application, can help to solve this points. >>>> I need some help from OFBiz-Content experts. >>>> >>>> For point (1) I'm using jBake but maybe it's possible to do something >>>> similar with templating in Content >>>> Who has some idea ? >>>> >>>> For point (2) I suppose it's a "gradle configuration" and "content >>>> configuration" >>>> Who has some idea ? >>>> >>>> For point (3) the more simple solution is to add 1 (or 2) field in context >>>> which contain help_title,(help_documentation) and >>>> so it will be simple to build the correct help link >>>>
