Thanks Olivier,
I must add that it's the current location and it would need more work to change
it, notably Infra help
Jacques
Le 20/05/2020 à 16:24, Olivier Heintz a écrit :
Yes, of course
My explanation was not clear, I propose to have one documentation by release
and use it in the relative help
My question is more about using (or not)
ci.apache.org/projects/ofbiz/site/${release}/ofbizdoc
Le 20/05/2020 à 08:32, Michael Brohl a écrit :
Hi Olivier,
wouldn't it be better to have different documentation paths for the
different branches?
If we would show the trunk documentation/help for stable branches, it
will most likely be wrong in some cases.
Another thought: it would be great if we could have the docs available
at ofbiz.apache.org/docs/trunk/, ofbiz.apache.org/docs/r18.12/ etc.
Thanks,
Michael Brohl
ecomify GmbH - www.ecomify.de
Am 19.05.20 um 11:54 schrieb Olivier Heintz:
Hi Community,
I need some comment or thought about one of point of the solution proposed.
Is there some people against the fact of used
ci.apache.org/projects/ofbiz/site/ofbizdoc (generate for the trunk) for the
ofbiz help ?
As I explained in my previous email, ci.apache.org/projects/ofbiz/site/ofbizdoc
would be the default value for userDocUri, (but value in
general.properties can be change with the local place of doc generation).
If community think, it's a good step solution (on the road to the new help
system), I will create a JIRA for generating the doc on all supported
branches (currently, it's only done for r17)
I just finished to migrate AccountingHelpData.xml to added the <set
field="helpAnchor" to the correct screens, so now it's really possible to see if
it's usable. I will updated the JIRA 11693.
Olivier
Le 12/05/2020 à 16:42, Olivier Heintz a écrit :
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 <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
