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 <holiv...@apache.org> 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 >>
