You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by Olivier Heintz <ho...@ofbizextra.org> on 2020/05/19 09:54:58 UTC
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
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 <ho...@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
>>>>>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Jacques Le Roux <ja...@les7arts.com>.
Thanks Olivier!
Le 24/05/2020 à 10:26, Olivier Heintz a écrit :
> Hi Jacques,
>
> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we need directories per release under ci.apache.org/projects/ofbiz/site/"
>
> Currently there is :
> projects/ofbiz/site/
> ├── javadocs
> ├── ofbizdoc
> └── pluginsdoc
>
> we want
> projects/ofbiz/site/
> ├── stable
> | ├── javadocs
> | ├── ofbizdoc
> | └── pluginsdoc
> ├── next
> | ├── javadocs
> | ├── ofbizdoc
> | └── pluginsdoc
> └── trunk
> ├── javadocs
> ├── ofbizdoc
> └── pluginsdoc
>
>
> I have prepared modification in buildbot/.../ofbiz.conf
> who can commit it when new directory will be created,
> me or you prefer I create a OFBiz Jira ?
>
> Olivier
>
> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
>> Hi Olivier:
>>
>> It's only in R17, see content of a https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
>>
>> If you want to know more look at 'f_ofb_branch17_framework_plugins' in
>> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/ (only committers)
>>
>> All builds mention: "The Documentation is only generated for the next stable version, at the moment R17"
>>
>> Jobs to do are:
>>
>> Adds the same in trunk and R18
>>
>> And especially before ask the same than in https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each case. Better call them stable, next
>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
>>
>> HTH
>>
>> Jacques
>>
>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
>>> Thanks Jacques for the clarification,
>>>
>>> But, I'm not sure to understand,
>>> currently, doc is generated only for R17 and are only included in buildbot job for trunkFrameworkPlugin ?
>>> Work to do is to add for job R17Framework and R18Framework ?
>>> Infra help is needed to publish for multi-release ?
>>>
>>> can I help about one of these points ?
>>>
>>> Olivier
>>>
>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>>>> 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 <ho...@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
>>>>>>>>>>>>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Eugen Stan <eu...@netdava.com>.
I tend to agree with Pierre here. However this depends on what OFBiz and
ASF can commit to offer to users. Every thing to maintain is a cost and
a burden on the people doing the maintaining.
It is easier to have stable / next similar names for developers. However
for people who maintain the software in production, they will have R17,
R18 and will need the documentation for the specific releases in order
to operate it.
That is what they will search for. If OFBiz commits to support only 2
major versions that is fine and IMO should be explicit on the website so
people know what to expect.
Also for documentation I believe old-stable, stable and next is enough.
If the release cycle is a few years it will give people ample time to
upgrade.
If it's not a big burden, documentation for more releases could be
stored online.
BTW. Are you using Antora https://antora.org/ for the website docs ? If
not please check it out.
Regards,
Eugen
La 24.05.2020 19:55, Pierre Smits a scris:
> Even when opting to keep it the simple way as you envision it, it would
> still be better to name the sub folder like the branch it is intended for
> (instead of stable).
>
>
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Sun, May 24, 2020 at 6:24 PM Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> Pierre,
>>
>> Because there should be almost no differences (if any) in the
>> documentation of 17.12.01 and 17.12.03
>>
>> So my idea is to keep it simple: each supported branches would have a
>> documentation and that's it.
>>
>> Else:
>>
>> 1. each release we would have to move things.
>> 2. The documentation is generated by BuibBot. So the script would have to
>> be modified.
>> 3. And we would have to ask Infra to create another tree.
>>
>> It's already some work to change things when we create a new release
>> branch...
>>
>> We could discuss that more but I feel a documentation by supported release
>> branch is enough.
>>
>> Jacques
>>
>> Le 24/05/2020 à 18:04, Pierre Smits a écrit :
>>> Jacques,
>>>
>>> You seem to be missing my point.
>>>
>>> it doesn't matter whether a release contains only bug-fixes,
>> improvements,
>>> new features or a combination of those to have a documentation start
>> point
>>> under projects/ofbiz/site/
>>>
>>> Stable is not something we release, but it is a link to a specific
>>> reference point in the main repo. In our case, the release. It is also
>> not
>>> the branch in our repo where the release was taken from.
>>>
>>> So again my question: ' Why don't we use the release id under
>>> projects/ofbiz/site/'?
>>>
>>>
>>>
>>> Met vriendelijke groet,
>>>
>>> Pierre Smits
>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>> since
>>> 2008 (without privileges)
>>>
>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>> Apache Incubator <https://incubator.apache.org>, committer
>>> Apache Steve <https://steve.apache.org>, committer
>>>
>>>
>>> On Sun, May 24, 2020 at 12:51 PM Jacques Le Roux <
>>> jacques.le.roux@les7arts.com> wrote:
>>>
>>>> Hi Pierre,
>>>>
>>>> Between (eg) 17.12.01 and 17.12.03 there are no new features only bug
>>>> fixes, hence not doc changes.
>>>>
>>>> Le 24/05/2020 à 12:25, Pierre Smits a écrit :
>>>>> Doesn't demo-stable relates to a particular release? Instead of a
>> branch?
>>>>> Then why don't we the release id not mentioned under
>> projects/ofbiz/site/
>>>>> becoming:
>>>>>
>>>>> - projects/ofbiz/site/17.12.01
>>>>> - projects/ofbiz/site/17.12.03
>>>>> - etc.
>>>>>
>>>>>
>>>>> Met vriendelijke groet,
>>>>>
>>>>> Pierre Smits
>>>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>>>> since
>>>>> 2008 (without privileges)
>>>>>
>>>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>>>> Apache Incubator <https://incubator.apache.org>, committer
>>>>> Apache Steve <https://steve.apache.org>, committer
>>>>>
>>>>>
>>>>> On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
>>>>> holivier.lists@ofbizextra.org> wrote:
>>>>>
>>>>>> Hi Jacques,
>>>>>>
>>>>>> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we
>>>> need
>>>>>> directories per release under ci.apache.org/projects/ofbiz/site/"
>>>>>>
>>>>>> Currently there is :
>>>>>> projects/ofbiz/site/
>>>>>> ├── javadocs
>>>>>> ├── ofbizdoc
>>>>>> └── pluginsdoc
>>>>>>
>>>>>> we want
>>>>>> projects/ofbiz/site/
>>>>>> ├── stable
>>>>>> | ├── javadocs
>>>>>> | ├── ofbizdoc
>>>>>> | └── pluginsdoc
>>>>>> ├── next
>>>>>> | ├── javadocs
>>>>>> | ├── ofbizdoc
>>>>>> | └── pluginsdoc
>>>>>> └── trunk
>>>>>> ├── javadocs
>>>>>> ├── ofbizdoc
>>>>>> └── pluginsdoc
>>>>>>
>>>>>>
>>>>>> I have prepared modification in buildbot/.../ofbiz.conf
>>>>>> who can commit it when new directory will be created,
>>>>>> me or you prefer I create a OFBiz Jira ?
>>>>>>
>>>>>> Olivier
>>>>>>
>>>>>> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
>>>>>>> Hi Olivier:
>>>>>>>
>>>>>>> It's only in R17, see content of a
>>>>>> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
>>>>>>> If you want to know more look at 'f_ofb_branch17_framework_plugins'
>> in
>> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
>>>>>> (only committers)
>>>>>>> All builds mention: "The Documentation is only generated for the next
>>>>>> stable version, at the moment R17"
>>>>>>> Jobs to do are:
>>>>>>>
>>>>>>> Adds the same in trunk and R18
>>>>>>>
>>>>>>> And especially before ask the same than in
>>>>>> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
>>>>>> case. Better call them stable, next
>>>>>>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
>>>>>>>
>>>>>>> HTH
>>>>>>>
>>>>>>> Jacques
>>>>>>>
>>>>>>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
>>>>>>>> Thanks Jacques for the clarification,
>>>>>>>>
>>>>>>>> But, I'm not sure to understand,
>>>>>>>> currently, doc is generated only for R17 and are only included in
>>>>>> buildbot job for trunkFrameworkPlugin ?
>>>>>>>> Work to do is to add for job R17Framework and R18Framework ?
>>>>>>>> Infra help is needed to publish for multi-release ?
>>>>>>>>
>>>>>>>> can I help about one of these points ?
>>>>>>>>
>>>>>>>> Olivier
>>>>>>>>
>>>>>>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>>>>>>>>> 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
>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
>>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
>>>>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
>>>>>> holivier@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
>>>>>>>>>>>>>>>>>
--
Eugen Stan
+40720 898 747 / netdava.com
Re: New Online Help, base on ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Pierre Smits <pi...@apache.org>.
Wow....
You seem vexed.
We're not rotating branches every other week...
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Sun, May 24, 2020 at 7:18 PM Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> The idea is that the branches are rotating (R16 was stable 2 months ago)
> and it would be a pain to change that each time.
>
> Do you get that or should I explain more?
>
> Le 24/05/2020 à 18:55, Pierre Smits a écrit :
> > Even when opting to keep it the simple way as you envision it, it would
> > still be better to name the sub folder like the branch it is intended for
> > (instead of stable).
> >
> >
> >
> > Met vriendelijke groet,
> >
> > Pierre Smits
> > *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> since
> > 2008 (without privileges)
> >
> > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > *Apache Directory <https://directory.apache.org>, PMC Member*
> > Apache Incubator <https://incubator.apache.org>, committer
> > Apache Steve <https://steve.apache.org>, committer
> >
> >
> > On Sun, May 24, 2020 at 6:24 PM Jacques Le Roux <
> > jacques.le.roux@les7arts.com> wrote:
> >
> >> Pierre,
> >>
> >> Because there should be almost no differences (if any) in the
> >> documentation of 17.12.01 and 17.12.03
> >>
> >> So my idea is to keep it simple: each supported branches would have a
> >> documentation and that's it.
> >>
> >> Else:
> >>
> >> 1. each release we would have to move things.
> >> 2. The documentation is generated by BuibBot. So the script would
> have to
> >> be modified.
> >> 3. And we would have to ask Infra to create another tree.
> >>
> >> It's already some work to change things when we create a new release
> >> branch...
> >>
> >> We could discuss that more but I feel a documentation by supported
> release
> >> branch is enough.
> >>
> >> Jacques
> >>
> >> Le 24/05/2020 à 18:04, Pierre Smits a écrit :
> >>> Jacques,
> >>>
> >>> You seem to be missing my point.
> >>>
> >>> it doesn't matter whether a release contains only bug-fixes,
> >> improvements,
> >>> new features or a combination of those to have a documentation start
> >> point
> >>> under projects/ofbiz/site/
> >>>
> >>> Stable is not something we release, but it is a link to a specific
> >>> reference point in the main repo. In our case, the release. It is also
> >> not
> >>> the branch in our repo where the release was taken from.
> >>>
> >>> So again my question: ' Why don't we use the release id under
> >>> projects/ofbiz/site/'?
> >>>
> >>>
> >>>
> >>> Met vriendelijke groet,
> >>>
> >>> Pierre Smits
> >>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> >> since
> >>> 2008 (without privileges)
> >>>
> >>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> >>> *Apache Directory <https://directory.apache.org>, PMC Member*
> >>> Apache Incubator <https://incubator.apache.org>, committer
> >>> Apache Steve <https://steve.apache.org>, committer
> >>>
> >>>
> >>> On Sun, May 24, 2020 at 12:51 PM Jacques Le Roux <
> >>> jacques.le.roux@les7arts.com> wrote:
> >>>
> >>>> Hi Pierre,
> >>>>
> >>>> Between (eg) 17.12.01 and 17.12.03 there are no new features only bug
> >>>> fixes, hence not doc changes.
> >>>>
> >>>> Le 24/05/2020 à 12:25, Pierre Smits a écrit :
> >>>>> Doesn't demo-stable relates to a particular release? Instead of a
> >> branch?
> >>>>> Then why don't we the release id not mentioned under
> >> projects/ofbiz/site/
> >>>>> becoming:
> >>>>>
> >>>>> - projects/ofbiz/site/17.12.01
> >>>>> - projects/ofbiz/site/17.12.03
> >>>>> - etc.
> >>>>>
> >>>>>
> >>>>> Met vriendelijke groet,
> >>>>>
> >>>>> Pierre Smits
> >>>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> >>>> since
> >>>>> 2008 (without privileges)
> >>>>>
> >>>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> >>>>> *Apache Directory <https://directory.apache.org>, PMC Member*
> >>>>> Apache Incubator <https://incubator.apache.org>, committer
> >>>>> Apache Steve <https://steve.apache.org>, committer
> >>>>>
> >>>>>
> >>>>> On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
> >>>>> holivier.lists@ofbizextra.org> wrote:
> >>>>>
> >>>>>> Hi Jacques,
> >>>>>>
> >>>>>> I have created https://issues.apache.org/jira/browse/INFRA-20311
> "we
> >>>> need
> >>>>>> directories per release under ci.apache.org/projects/ofbiz/site/"
> >>>>>>
> >>>>>> Currently there is :
> >>>>>> projects/ofbiz/site/
> >>>>>> ├── javadocs
> >>>>>> ├── ofbizdoc
> >>>>>> └── pluginsdoc
> >>>>>>
> >>>>>> we want
> >>>>>> projects/ofbiz/site/
> >>>>>> ├── stable
> >>>>>> | ├── javadocs
> >>>>>> | ├── ofbizdoc
> >>>>>> | └── pluginsdoc
> >>>>>> ├── next
> >>>>>> | ├── javadocs
> >>>>>> | ├── ofbizdoc
> >>>>>> | └── pluginsdoc
> >>>>>> └── trunk
> >>>>>> ├── javadocs
> >>>>>> ├── ofbizdoc
> >>>>>> └── pluginsdoc
> >>>>>>
> >>>>>>
> >>>>>> I have prepared modification in buildbot/.../ofbiz.conf
> >>>>>> who can commit it when new directory will be created,
> >>>>>> me or you prefer I create a OFBiz Jira ?
> >>>>>>
> >>>>>> Olivier
> >>>>>>
> >>>>>> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
> >>>>>>> Hi Olivier:
> >>>>>>>
> >>>>>>> It's only in R17, see content of a
> >>>>>> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
> >>>>>>> If you want to know more look at 'f_ofb_branch17_framework_plugins'
> >> in
> >>
> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
> >>>>>> (only committers)
> >>>>>>> All builds mention: "The Documentation is only generated for the
> next
> >>>>>> stable version, at the moment R17"
> >>>>>>> Jobs to do are:
> >>>>>>>
> >>>>>>> Adds the same in trunk and R18
> >>>>>>>
> >>>>>>> And especially before ask the same than in
> >>>>>> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing
> each
> >>>>>> case. Better call them stable, next
> >>>>>>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
> >>>>>>>
> >>>>>>> HTH
> >>>>>>>
> >>>>>>> Jacques
> >>>>>>>
> >>>>>>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
> >>>>>>>> Thanks Jacques for the clarification,
> >>>>>>>>
> >>>>>>>> But, I'm not sure to understand,
> >>>>>>>> currently, doc is generated only for R17 and are only included in
> >>>>>> buildbot job for trunkFrameworkPlugin ?
> >>>>>>>> Work to do is to add for job R17Framework and R18Framework ?
> >>>>>>>> Infra help is needed to publish for multi-release ?
> >>>>>>>>
> >>>>>>>> can I help about one of these points ?
> >>>>>>>>
> >>>>>>>> Olivier
> >>>>>>>>
> >>>>>>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
> >>>>>>>>> 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
> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
> >> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
> >>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
> >>>>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
> >>>>>> holivier@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
> >>>>>>>>>>>>>>>>>
>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Jacques Le Roux <ja...@les7arts.com>.
The idea is that the branches are rotating (R16 was stable 2 months ago) and it would be a pain to change that each time.
Do you get that or should I explain more?
Le 24/05/2020 à 18:55, Pierre Smits a écrit :
> Even when opting to keep it the simple way as you envision it, it would
> still be better to name the sub folder like the branch it is intended for
> (instead of stable).
>
>
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Sun, May 24, 2020 at 6:24 PM Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> Pierre,
>>
>> Because there should be almost no differences (if any) in the
>> documentation of 17.12.01 and 17.12.03
>>
>> So my idea is to keep it simple: each supported branches would have a
>> documentation and that's it.
>>
>> Else:
>>
>> 1. each release we would have to move things.
>> 2. The documentation is generated by BuibBot. So the script would have to
>> be modified.
>> 3. And we would have to ask Infra to create another tree.
>>
>> It's already some work to change things when we create a new release
>> branch...
>>
>> We could discuss that more but I feel a documentation by supported release
>> branch is enough.
>>
>> Jacques
>>
>> Le 24/05/2020 à 18:04, Pierre Smits a écrit :
>>> Jacques,
>>>
>>> You seem to be missing my point.
>>>
>>> it doesn't matter whether a release contains only bug-fixes,
>> improvements,
>>> new features or a combination of those to have a documentation start
>> point
>>> under projects/ofbiz/site/
>>>
>>> Stable is not something we release, but it is a link to a specific
>>> reference point in the main repo. In our case, the release. It is also
>> not
>>> the branch in our repo where the release was taken from.
>>>
>>> So again my question: ' Why don't we use the release id under
>>> projects/ofbiz/site/'?
>>>
>>>
>>>
>>> Met vriendelijke groet,
>>>
>>> Pierre Smits
>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>> since
>>> 2008 (without privileges)
>>>
>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>> Apache Incubator <https://incubator.apache.org>, committer
>>> Apache Steve <https://steve.apache.org>, committer
>>>
>>>
>>> On Sun, May 24, 2020 at 12:51 PM Jacques Le Roux <
>>> jacques.le.roux@les7arts.com> wrote:
>>>
>>>> Hi Pierre,
>>>>
>>>> Between (eg) 17.12.01 and 17.12.03 there are no new features only bug
>>>> fixes, hence not doc changes.
>>>>
>>>> Le 24/05/2020 à 12:25, Pierre Smits a écrit :
>>>>> Doesn't demo-stable relates to a particular release? Instead of a
>> branch?
>>>>> Then why don't we the release id not mentioned under
>> projects/ofbiz/site/
>>>>> becoming:
>>>>>
>>>>> - projects/ofbiz/site/17.12.01
>>>>> - projects/ofbiz/site/17.12.03
>>>>> - etc.
>>>>>
>>>>>
>>>>> Met vriendelijke groet,
>>>>>
>>>>> Pierre Smits
>>>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>>>> since
>>>>> 2008 (without privileges)
>>>>>
>>>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>>>> Apache Incubator <https://incubator.apache.org>, committer
>>>>> Apache Steve <https://steve.apache.org>, committer
>>>>>
>>>>>
>>>>> On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
>>>>> holivier.lists@ofbizextra.org> wrote:
>>>>>
>>>>>> Hi Jacques,
>>>>>>
>>>>>> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we
>>>> need
>>>>>> directories per release under ci.apache.org/projects/ofbiz/site/"
>>>>>>
>>>>>> Currently there is :
>>>>>> projects/ofbiz/site/
>>>>>> ├── javadocs
>>>>>> ├── ofbizdoc
>>>>>> └── pluginsdoc
>>>>>>
>>>>>> we want
>>>>>> projects/ofbiz/site/
>>>>>> ├── stable
>>>>>> | ├── javadocs
>>>>>> | ├── ofbizdoc
>>>>>> | └── pluginsdoc
>>>>>> ├── next
>>>>>> | ├── javadocs
>>>>>> | ├── ofbizdoc
>>>>>> | └── pluginsdoc
>>>>>> └── trunk
>>>>>> ├── javadocs
>>>>>> ├── ofbizdoc
>>>>>> └── pluginsdoc
>>>>>>
>>>>>>
>>>>>> I have prepared modification in buildbot/.../ofbiz.conf
>>>>>> who can commit it when new directory will be created,
>>>>>> me or you prefer I create a OFBiz Jira ?
>>>>>>
>>>>>> Olivier
>>>>>>
>>>>>> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
>>>>>>> Hi Olivier:
>>>>>>>
>>>>>>> It's only in R17, see content of a
>>>>>> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
>>>>>>> If you want to know more look at 'f_ofb_branch17_framework_plugins'
>> in
>> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
>>>>>> (only committers)
>>>>>>> All builds mention: "The Documentation is only generated for the next
>>>>>> stable version, at the moment R17"
>>>>>>> Jobs to do are:
>>>>>>>
>>>>>>> Adds the same in trunk and R18
>>>>>>>
>>>>>>> And especially before ask the same than in
>>>>>> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
>>>>>> case. Better call them stable, next
>>>>>>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
>>>>>>>
>>>>>>> HTH
>>>>>>>
>>>>>>> Jacques
>>>>>>>
>>>>>>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
>>>>>>>> Thanks Jacques for the clarification,
>>>>>>>>
>>>>>>>> But, I'm not sure to understand,
>>>>>>>> currently, doc is generated only for R17 and are only included in
>>>>>> buildbot job for trunkFrameworkPlugin ?
>>>>>>>> Work to do is to add for job R17Framework and R18Framework ?
>>>>>>>> Infra help is needed to publish for multi-release ?
>>>>>>>>
>>>>>>>> can I help about one of these points ?
>>>>>>>>
>>>>>>>> Olivier
>>>>>>>>
>>>>>>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>>>>>>>>> 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
>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
>>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
>>>>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
>>>>>> holivier@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
>>>>>>>>>>>>>>>>>
Re: New Online Help, base on ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Pierre Smits <pi...@apache.org>.
Even when opting to keep it the simple way as you envision it, it would
still be better to name the sub folder like the branch it is intended for
(instead of stable).
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Sun, May 24, 2020 at 6:24 PM Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> Pierre,
>
> Because there should be almost no differences (if any) in the
> documentation of 17.12.01 and 17.12.03
>
> So my idea is to keep it simple: each supported branches would have a
> documentation and that's it.
>
> Else:
>
> 1. each release we would have to move things.
> 2. The documentation is generated by BuibBot. So the script would have to
> be modified.
> 3. And we would have to ask Infra to create another tree.
>
> It's already some work to change things when we create a new release
> branch...
>
> We could discuss that more but I feel a documentation by supported release
> branch is enough.
>
> Jacques
>
> Le 24/05/2020 à 18:04, Pierre Smits a écrit :
> > Jacques,
> >
> > You seem to be missing my point.
> >
> > it doesn't matter whether a release contains only bug-fixes,
> improvements,
> > new features or a combination of those to have a documentation start
> point
> > under projects/ofbiz/site/
> >
> > Stable is not something we release, but it is a link to a specific
> > reference point in the main repo. In our case, the release. It is also
> not
> > the branch in our repo where the release was taken from.
> >
> > So again my question: ' Why don't we use the release id under
> > projects/ofbiz/site/'?
> >
> >
> >
> > Met vriendelijke groet,
> >
> > Pierre Smits
> > *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> since
> > 2008 (without privileges)
> >
> > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > *Apache Directory <https://directory.apache.org>, PMC Member*
> > Apache Incubator <https://incubator.apache.org>, committer
> > Apache Steve <https://steve.apache.org>, committer
> >
> >
> > On Sun, May 24, 2020 at 12:51 PM Jacques Le Roux <
> > jacques.le.roux@les7arts.com> wrote:
> >
> >> Hi Pierre,
> >>
> >> Between (eg) 17.12.01 and 17.12.03 there are no new features only bug
> >> fixes, hence not doc changes.
> >>
> >> Le 24/05/2020 à 12:25, Pierre Smits a écrit :
> >>> Doesn't demo-stable relates to a particular release? Instead of a
> branch?
> >>>
> >>> Then why don't we the release id not mentioned under
> projects/ofbiz/site/
> >>>
> >>> becoming:
> >>>
> >>> - projects/ofbiz/site/17.12.01
> >>> - projects/ofbiz/site/17.12.03
> >>> - etc.
> >>>
> >>>
> >>> Met vriendelijke groet,
> >>>
> >>> Pierre Smits
> >>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> >> since
> >>> 2008 (without privileges)
> >>>
> >>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> >>> *Apache Directory <https://directory.apache.org>, PMC Member*
> >>> Apache Incubator <https://incubator.apache.org>, committer
> >>> Apache Steve <https://steve.apache.org>, committer
> >>>
> >>>
> >>> On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
> >>> holivier.lists@ofbizextra.org> wrote:
> >>>
> >>>> Hi Jacques,
> >>>>
> >>>> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we
> >> need
> >>>> directories per release under ci.apache.org/projects/ofbiz/site/"
> >>>>
> >>>> Currently there is :
> >>>> projects/ofbiz/site/
> >>>> ├── javadocs
> >>>> ├── ofbizdoc
> >>>> └── pluginsdoc
> >>>>
> >>>> we want
> >>>> projects/ofbiz/site/
> >>>> ├── stable
> >>>> | ├── javadocs
> >>>> | ├── ofbizdoc
> >>>> | └── pluginsdoc
> >>>> ├── next
> >>>> | ├── javadocs
> >>>> | ├── ofbizdoc
> >>>> | └── pluginsdoc
> >>>> └── trunk
> >>>> ├── javadocs
> >>>> ├── ofbizdoc
> >>>> └── pluginsdoc
> >>>>
> >>>>
> >>>> I have prepared modification in buildbot/.../ofbiz.conf
> >>>> who can commit it when new directory will be created,
> >>>> me or you prefer I create a OFBiz Jira ?
> >>>>
> >>>> Olivier
> >>>>
> >>>> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
> >>>>> Hi Olivier:
> >>>>>
> >>>>> It's only in R17, see content of a
> >>>> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
> >>>>> If you want to know more look at 'f_ofb_branch17_framework_plugins'
> in
> >>>>>
> >>
> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
> >>>> (only committers)
> >>>>> All builds mention: "The Documentation is only generated for the next
> >>>> stable version, at the moment R17"
> >>>>> Jobs to do are:
> >>>>>
> >>>>> Adds the same in trunk and R18
> >>>>>
> >>>>> And especially before ask the same than in
> >>>> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
> >>>> case. Better call them stable, next
> >>>>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
> >>>>>
> >>>>> HTH
> >>>>>
> >>>>> Jacques
> >>>>>
> >>>>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
> >>>>>> Thanks Jacques for the clarification,
> >>>>>>
> >>>>>> But, I'm not sure to understand,
> >>>>>> currently, doc is generated only for R17 and are only included in
> >>>> buildbot job for trunkFrameworkPlugin ?
> >>>>>> Work to do is to add for job R17Framework and R18Framework ?
> >>>>>> Infra help is needed to publish for multi-release ?
> >>>>>>
> >>>>>> can I help about one of these points ?
> >>>>>>
> >>>>>> Olivier
> >>>>>>
> >>>>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
> >>>>>>> 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
> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
> >> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
> >>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
> >>>> holivier@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
> >>>>>>>>>>>>>>>
>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Jacques Le Roux <ja...@les7arts.com>.
Pierre,
Because there should be almost no differences (if any) in the documentation of 17.12.01 and 17.12.03
So my idea is to keep it simple: each supported branches would have a documentation and that's it.
Else:
1. each release we would have to move things.
2. The documentation is generated by BuibBot. So the script would have to be modified.
3. And we would have to ask Infra to create another tree.
It's already some work to change things when we create a new release branch...
We could discuss that more but I feel a documentation by supported release branch is enough.
Jacques
Le 24/05/2020 à 18:04, Pierre Smits a écrit :
> Jacques,
>
> You seem to be missing my point.
>
> it doesn't matter whether a release contains only bug-fixes, improvements,
> new features or a combination of those to have a documentation start point
> under projects/ofbiz/site/
>
> Stable is not something we release, but it is a link to a specific
> reference point in the main repo. In our case, the release. It is also not
> the branch in our repo where the release was taken from.
>
> So again my question: ' Why don't we use the release id under
> projects/ofbiz/site/'?
>
>
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Sun, May 24, 2020 at 12:51 PM Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> Hi Pierre,
>>
>> Between (eg) 17.12.01 and 17.12.03 there are no new features only bug
>> fixes, hence not doc changes.
>>
>> Le 24/05/2020 à 12:25, Pierre Smits a écrit :
>>> Doesn't demo-stable relates to a particular release? Instead of a branch?
>>>
>>> Then why don't we the release id not mentioned under projects/ofbiz/site/
>>>
>>> becoming:
>>>
>>> - projects/ofbiz/site/17.12.01
>>> - projects/ofbiz/site/17.12.03
>>> - etc.
>>>
>>>
>>> Met vriendelijke groet,
>>>
>>> Pierre Smits
>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>> since
>>> 2008 (without privileges)
>>>
>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>> Apache Incubator <https://incubator.apache.org>, committer
>>> Apache Steve <https://steve.apache.org>, committer
>>>
>>>
>>> On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
>>> holivier.lists@ofbizextra.org> wrote:
>>>
>>>> Hi Jacques,
>>>>
>>>> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we
>> need
>>>> directories per release under ci.apache.org/projects/ofbiz/site/"
>>>>
>>>> Currently there is :
>>>> projects/ofbiz/site/
>>>> ├── javadocs
>>>> ├── ofbizdoc
>>>> └── pluginsdoc
>>>>
>>>> we want
>>>> projects/ofbiz/site/
>>>> ├── stable
>>>> | ├── javadocs
>>>> | ├── ofbizdoc
>>>> | └── pluginsdoc
>>>> ├── next
>>>> | ├── javadocs
>>>> | ├── ofbizdoc
>>>> | └── pluginsdoc
>>>> └── trunk
>>>> ├── javadocs
>>>> ├── ofbizdoc
>>>> └── pluginsdoc
>>>>
>>>>
>>>> I have prepared modification in buildbot/.../ofbiz.conf
>>>> who can commit it when new directory will be created,
>>>> me or you prefer I create a OFBiz Jira ?
>>>>
>>>> Olivier
>>>>
>>>> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
>>>>> Hi Olivier:
>>>>>
>>>>> It's only in R17, see content of a
>>>> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
>>>>> If you want to know more look at 'f_ofb_branch17_framework_plugins' in
>>>>>
>> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
>>>> (only committers)
>>>>> All builds mention: "The Documentation is only generated for the next
>>>> stable version, at the moment R17"
>>>>> Jobs to do are:
>>>>>
>>>>> Adds the same in trunk and R18
>>>>>
>>>>> And especially before ask the same than in
>>>> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
>>>> case. Better call them stable, next
>>>>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
>>>>>
>>>>> HTH
>>>>>
>>>>> Jacques
>>>>>
>>>>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
>>>>>> Thanks Jacques for the clarification,
>>>>>>
>>>>>> But, I'm not sure to understand,
>>>>>> currently, doc is generated only for R17 and are only included in
>>>> buildbot job for trunkFrameworkPlugin ?
>>>>>> Work to do is to add for job R17Framework and R18Framework ?
>>>>>> Infra help is needed to publish for multi-release ?
>>>>>>
>>>>>> can I help about one of these points ?
>>>>>>
>>>>>> Olivier
>>>>>>
>>>>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>>>>>>> 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
>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
>>>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
>>>> holivier@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
>>>>>>>>>>>>>>>
Re: New Online Help, base on ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Pierre Smits <pi...@apache.org>.
Jacques,
You seem to be missing my point.
it doesn't matter whether a release contains only bug-fixes, improvements,
new features or a combination of those to have a documentation start point
under projects/ofbiz/site/
Stable is not something we release, but it is a link to a specific
reference point in the main repo. In our case, the release. It is also not
the branch in our repo where the release was taken from.
So again my question: ' Why don't we use the release id under
projects/ofbiz/site/'?
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Sun, May 24, 2020 at 12:51 PM Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> Hi Pierre,
>
> Between (eg) 17.12.01 and 17.12.03 there are no new features only bug
> fixes, hence not doc changes.
>
> Le 24/05/2020 à 12:25, Pierre Smits a écrit :
> > Doesn't demo-stable relates to a particular release? Instead of a branch?
> >
> > Then why don't we the release id not mentioned under projects/ofbiz/site/
> >
> > becoming:
> >
> > - projects/ofbiz/site/17.12.01
> > - projects/ofbiz/site/17.12.03
> > - etc.
> >
> >
> > Met vriendelijke groet,
> >
> > Pierre Smits
> > *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> since
> > 2008 (without privileges)
> >
> > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > *Apache Directory <https://directory.apache.org>, PMC Member*
> > Apache Incubator <https://incubator.apache.org>, committer
> > Apache Steve <https://steve.apache.org>, committer
> >
> >
> > On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
> > holivier.lists@ofbizextra.org> wrote:
> >
> >> Hi Jacques,
> >>
> >> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we
> need
> >> directories per release under ci.apache.org/projects/ofbiz/site/"
> >>
> >> Currently there is :
> >> projects/ofbiz/site/
> >> ├── javadocs
> >> ├── ofbizdoc
> >> └── pluginsdoc
> >>
> >> we want
> >> projects/ofbiz/site/
> >> ├── stable
> >> | ├── javadocs
> >> | ├── ofbizdoc
> >> | └── pluginsdoc
> >> ├── next
> >> | ├── javadocs
> >> | ├── ofbizdoc
> >> | └── pluginsdoc
> >> └── trunk
> >> ├── javadocs
> >> ├── ofbizdoc
> >> └── pluginsdoc
> >>
> >>
> >> I have prepared modification in buildbot/.../ofbiz.conf
> >> who can commit it when new directory will be created,
> >> me or you prefer I create a OFBiz Jira ?
> >>
> >> Olivier
> >>
> >> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
> >>> Hi Olivier:
> >>>
> >>> It's only in R17, see content of a
> >> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
> >>> If you want to know more look at 'f_ofb_branch17_framework_plugins' in
> >>>
> >>
> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
> >> (only committers)
> >>> All builds mention: "The Documentation is only generated for the next
> >> stable version, at the moment R17"
> >>> Jobs to do are:
> >>>
> >>> Adds the same in trunk and R18
> >>>
> >>> And especially before ask the same than in
> >> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
> >> case. Better call them stable, next
> >>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
> >>>
> >>> HTH
> >>>
> >>> Jacques
> >>>
> >>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
> >>>> Thanks Jacques for the clarification,
> >>>>
> >>>> But, I'm not sure to understand,
> >>>> currently, doc is generated only for R17 and are only included in
> >> buildbot job for trunkFrameworkPlugin ?
> >>>> Work to do is to add for job R17Framework and R18Framework ?
> >>>> Infra help is needed to publish for multi-release ?
> >>>>
> >>>> can I help about one of these points ?
> >>>>
> >>>> Olivier
> >>>>
> >>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
> >>>>> 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
> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/ofbizdoc>
> >> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
> >> holivier@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
> >>>>>>>>>>>>>
>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Jacques Le Roux <ja...@les7arts.com>.
Hi Pierre,
Between (eg) 17.12.01 and 17.12.03 there are no new features only bug fixes, hence not doc changes.
Le 24/05/2020 à 12:25, Pierre Smits a écrit :
> Doesn't demo-stable relates to a particular release? Instead of a branch?
>
> Then why don't we the release id not mentioned under projects/ofbiz/site/
>
> becoming:
>
> - projects/ofbiz/site/17.12.01
> - projects/ofbiz/site/17.12.03
> - etc.
>
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
> holivier.lists@ofbizextra.org> wrote:
>
>> Hi Jacques,
>>
>> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we need
>> directories per release under ci.apache.org/projects/ofbiz/site/"
>>
>> Currently there is :
>> projects/ofbiz/site/
>> ├── javadocs
>> ├── ofbizdoc
>> └── pluginsdoc
>>
>> we want
>> projects/ofbiz/site/
>> ├── stable
>> | ├── javadocs
>> | ├── ofbizdoc
>> | └── pluginsdoc
>> ├── next
>> | ├── javadocs
>> | ├── ofbizdoc
>> | └── pluginsdoc
>> └── trunk
>> ├── javadocs
>> ├── ofbizdoc
>> └── pluginsdoc
>>
>>
>> I have prepared modification in buildbot/.../ofbiz.conf
>> who can commit it when new directory will be created,
>> me or you prefer I create a OFBiz Jira ?
>>
>> Olivier
>>
>> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
>>> Hi Olivier:
>>>
>>> It's only in R17, see content of a
>> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
>>> If you want to know more look at 'f_ofb_branch17_framework_plugins' in
>>>
>> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
>> (only committers)
>>> All builds mention: "The Documentation is only generated for the next
>> stable version, at the moment R17"
>>> Jobs to do are:
>>>
>>> Adds the same in trunk and R18
>>>
>>> And especially before ask the same than in
>> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
>> case. Better call them stable, next
>>> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
>>>
>>> HTH
>>>
>>> Jacques
>>>
>>> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
>>>> Thanks Jacques for the clarification,
>>>>
>>>> But, I'm not sure to understand,
>>>> currently, doc is generated only for R17 and are only included in
>> buildbot job for trunkFrameworkPlugin ?
>>>> Work to do is to add for job R17Framework and R18Framework ?
>>>> Infra help is needed to publish for multi-release ?
>>>>
>>>> can I help about one of these points ?
>>>>
>>>> Olivier
>>>>
>>>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>>>>> 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
>> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
>> holivier@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
>>>>>>>>>>>>>
Re: New Online Help, base on ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Pierre Smits <pi...@apache.org>.
Doesn't demo-stable relates to a particular release? Instead of a branch?
Then why don't we the release id not mentioned under projects/ofbiz/site/
becoming:
- projects/ofbiz/site/17.12.01
- projects/ofbiz/site/17.12.03
- etc.
Met vriendelijke groet,
Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)
*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer
On Sun, May 24, 2020 at 10:26 AM Olivier Heintz <
holivier.lists@ofbizextra.org> wrote:
> Hi Jacques,
>
> I have created https://issues.apache.org/jira/browse/INFRA-20311 "we need
> directories per release under ci.apache.org/projects/ofbiz/site/"
>
> Currently there is :
> projects/ofbiz/site/
> ├── javadocs
> ├── ofbizdoc
> └── pluginsdoc
>
> we want
> projects/ofbiz/site/
> ├── stable
> | ├── javadocs
> | ├── ofbizdoc
> | └── pluginsdoc
> ├── next
> | ├── javadocs
> | ├── ofbizdoc
> | └── pluginsdoc
> └── trunk
> ├── javadocs
> ├── ofbizdoc
> └── pluginsdoc
>
>
> I have prepared modification in buildbot/.../ofbiz.conf
> who can commit it when new directory will be created,
> me or you prefer I create a OFBiz Jira ?
>
> Olivier
>
> Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
> > Hi Olivier:
> >
> > It's only in R17, see content of a
> https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
> >
> > If you want to know more look at 'f_ofb_branch17_framework_plugins' in
> >
> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/
> (only committers)
> >
> > All builds mention: "The Documentation is only generated for the next
> stable version, at the moment R17"
> >
> > Jobs to do are:
> >
> > Adds the same in trunk and R18
> >
> > And especially before ask the same than in
> https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each
> case. Better call them stable, next
> > and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
> >
> > HTH
> >
> > Jacques
> >
> > Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
> >> Thanks Jacques for the clarification,
> >>
> >> But, I'm not sure to understand,
> >> currently, doc is generated only for R17 and are only included in
> buildbot job for trunkFrameworkPlugin ?
> >> Work to do is to add for job R17Framework and R18Framework ?
> >> Infra help is needed to publish for multi-release ?
> >>
> >> can I help about one of these points ?
> >>
> >> Olivier
> >>
> >> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
> >>> 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
> <http://ci.apache.org/projects/ofbiz/site/$%7Brelease%7D/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 <
> holivier@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
> >>>>>>>>>>>
>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Olivier Heintz <ho...@ofbizextra.org>.
Hi Jacques,
I have created https://issues.apache.org/jira/browse/INFRA-20311 "we need directories per release under ci.apache.org/projects/ofbiz/site/"
Currently there is :
projects/ofbiz/site/
├── javadocs
├── ofbizdoc
└── pluginsdoc
we want
projects/ofbiz/site/
├── stable
| ├── javadocs
| ├── ofbizdoc
| └── pluginsdoc
├── next
| ├── javadocs
| ├── ofbizdoc
| └── pluginsdoc
└── trunk
├── javadocs
├── ofbizdoc
└── pluginsdoc
I have prepared modification in buildbot/.../ofbiz.conf
who can commit it when new directory will be created,
me or you prefer I create a OFBiz Jira ?
Olivier
Le 23/05/2020 à 11:51, Jacques Le Roux a écrit :
> Hi Olivier:
>
> It's only in R17, see content of a https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
>
> If you want to know more look at 'f_ofb_branch17_framework_plugins' in
> https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/ (only committers)
>
> All builds mention: "The Documentation is only generated for the next stable version, at the moment R17"
>
> Jobs to do are:
>
> Adds the same in trunk and R18
>
> And especially before ask the same than in https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each case. Better call them stable, next
> and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
>
> HTH
>
> Jacques
>
> Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
>> Thanks Jacques for the clarification,
>>
>> But, I'm not sure to understand,
>> currently, doc is generated only for R17 and are only included in buildbot job for trunkFrameworkPlugin ?
>> Work to do is to add for job R17Framework and R18Framework ?
>> Infra help is needed to publish for multi-release ?
>>
>> can I help about one of these points ?
>>
>> Olivier
>>
>> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>>> 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 <ho...@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
>>>>>>>>>>>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Jacques Le Roux <ja...@les7arts.com>.
Hi Olivier:
It's only in R17, see content of a https://ci.apache.org/builders/ofbizBranch17FrameworkPlugins build
If you want to know more look at 'f_ofb_branch17_framework_plugins' in
https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/ofbiz.conf/ (only committers)
All builds mention: "The Documentation is only generated for the next stable version, at the moment R17"
Jobs to do are:
Adds the same in trunk and R18
And especially before ask the same than in https://issues.apache.org/jira/browse/INFRA-17258 distinguishing each case. Better call them stable, next
and trunk than R17, R18 and trunk (OK trunk never "change" ;) )...
HTH
Jacques
Le 23/05/2020 à 11:27, Olivier Heintz a écrit :
> Thanks Jacques for the clarification,
>
> But, I'm not sure to understand,
> currently, doc is generated only for R17 and are only included in buildbot job for trunkFrameworkPlugin ?
> Work to do is to add for job R17Framework and R18Framework ?
> Infra help is needed to publish for multi-release ?
>
> can I help about one of these points ?
>
> Olivier
>
> Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
>> 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 <ho...@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
>>>>>>>>>>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Olivier Heintz <ho...@ofbizextra.org>.
Thanks Jacques for the clarification,
But, I'm not sure to understand,
currently, doc is generated only for R17 and are only included in buildbot job for trunkFrameworkPlugin ?
Work to do is to add for job R17Framework and R18Framework ?
Infra help is needed to publish for multi-release ?
can I help about one of these points ?
Olivier
Le 20/05/2020 à 17:15, Jacques Le Roux a écrit :
> 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 <ho...@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
>>>>>>>>>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Jacques Le Roux <ja...@les7arts.com>.
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 <ho...@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
>>>>>>>>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Olivier Heintz <ho...@ofbizextra.org>.
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 <ho...@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
>>>>>>>
>
Re: New Online Help, base on
ci.apache.org/projects/ofbiz/site/ofbizdoc
Posted by Michael Brohl <mi...@ecomify.de>.
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 <ho...@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
>>>>>>