AsciiDoc generated online documentation and releases

[Jacques Le Roux]

Hi,

So start this discussion, currently our main documents in docs\asciidoc refer to the R17 release. But those document don't exist in R17 branch.

I think it's not too late to backport them, but do we want to do so?

Also I suggested to have an easy access to the documentation from the site documentation page.

Do we also want to use the AsciiDoc generated documentation as we did to provide an online help from the applications?

Do we want to provide something like https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?

For me the answers to these questions is NO! We should have a sole entry point for the documentation and it should be from the site documentation
page. It's then easy to provide links from there (using anchors going to automatically generated IDs sections)

What are your opinions? (I know I should re-read this thread https://markmail.org/message/35ak34fpzlyjiopt and I started...)

Jacques

[Jacques Le Roux]

At https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap

Sharan already suggested to "Backport to releases where possible"

I think we should do that and not way R18 to use the AsciiDoc generation even if it's not complete

Opinions before I get ahead?

Jacques


Le 14/11/2018 à 08:41, Jacques Le Roux a écrit :

> Hi,
>
> So start this discussion, currently our main documents in docs\asciidoc refer to the R17 release. But those document don't exist in R17 branch.
>
> I think it's not too late to backport them, but do we want to do so?
>
> Also I suggested to have an easy access to the documentation from the site documentation page.
>
> Do we also want to use the AsciiDoc generated documentation as we did to provide an online help from the applications?
>
> Do we want to provide something like https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
>
> For me the answers to these questions is NO! We should have a sole entry point for the documentation and it should be from the site documentation
> page. It's then easy to provide links from there (using anchors going to automatically generated IDs sections)
>
> What are your opinions? (I know I should re-read this thread https://markmail.org/message/35ak34fpzlyjiopt and I started...)
>
> Jacques
>
>

[Pierre Smits-3]

Hi Jacques,

I support the suggestion made by Sharan. It should not be too difficult,
when a release has been made available (this should be part of the release
activities), to generate the 'release' related documents and hook it into
the website. Our (potential) adopters will benefit.


Best regards,

Pierre Smits

*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
*Apache OFBiz <https://ofbiz.apache.org>, contributor (without privileges)
since 2008*
Apache Steve <https://steve.apache.org>, committer


On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
[hidden email]> wrote:

> At
> https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
>
> Sharan already suggested to "Backport to releases where possible"
>
> I think we should do that and not way R18 to use the AsciiDoc generation
> even if it's not complete
>
> Opinions before I get ahead?
>
> Jacques
>
>
> Le 14/11/2018 à 08:41, Jacques Le Roux a écrit :
> > Hi,
> >
> > So start this discussion, currently our main documents in docs\asciidoc
> refer to the R17 release. But those document don't exist in R17 branch.
> >
> > I think it's not too late to backport them, but do we want to do so?
> >
> > Also I suggested to have an easy access to the documentation from the
> site documentation page.
> >
> > Do we also want to use the AsciiDoc generated documentation as we did to
> provide an online help from the applications?
> >
> > Do we want to provide something like
> https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
> >
> > For me the answers to these questions is NO! We should have a sole entry
> point for the documentation and it should be from the site documentation
> > page. It's then easy to provide links from there (using anchors going to
> automatically generated IDs sections)
> >
> > What are your opinions? (I know I should re-read this thread
> https://markmail.org/message/35ak34fpzlyjiopt and I started...)
> >
> > Jacques
> >
> >
>
>

[Rishi Solanki]

+1 for backport.

--
Rishi Solanki
Sr Manager, Enterprise Software Development
HotWax Systems Pvt. Ltd.
Direct: [phone]
http://www.hotwaxsystems.com
www.hotwax.co


On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <[hidden email]>
wrote:

> Hi Jacques,
>
> I support the suggestion made by Sharan. It should not be too difficult,
> when a release has been made available (this should be part of the release
> activities), to generate the 'release' related documents and hook it into
> the website. Our (potential) adopters will benefit.
>
>
> Best regards,
>
> Pierre Smits
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> *Apache OFBiz <https://ofbiz.apache.org>, contributor (without privileges)
> since 2008*
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
> [hidden email]> wrote:
>
> > At
> >
> https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
> >
> > Sharan already suggested to "Backport to releases where possible"
> >
> > I think we should do that and not way R18 to use the AsciiDoc generation
> > even if it's not complete
> >
> > Opinions before I get ahead?
> >
> > Jacques
> >
> >
> > Le 14/11/2018 à 08:41, Jacques Le Roux a écrit :
> > > Hi,
> > >
> > > So start this discussion, currently our main documents in docs\asciidoc
> > refer to the R17 release. But those document don't exist in R17 branch.
> > >
> > > I think it's not too late to backport them, but do we want to do so?
> > >
> > > Also I suggested to have an easy access to the documentation from the
> > site documentation page.
> > >
> > > Do we also want to use the AsciiDoc generated documentation as we did
> to
> > provide an online help from the applications?
> > >
> > > Do we want to provide something like
> > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
> > >
> > > For me the answers to these questions is NO! We should have a sole
> entry
> > point for the documentation and it should be from the site documentation
> > > page. It's then easy to provide links from there (using anchors going
> to
> > automatically generated IDs sections)
> > >
> > > What are your opinions? (I know I should re-read this thread
> > https://markmail.org/message/35ak34fpzlyjiopt and I started...)
> > >
> > > Jacques
> > >
> > >
> >
> >
>

[Arun Patidar-2]

+1 for backport

On Fri, Nov 16, 2018, 2:53 PM Rishi Solanki <[hidden email]> wrote:

> +1 for backport.
>
> --
> Rishi Solanki
> Sr Manager, Enterprise Software Development
> HotWax Systems Pvt. Ltd.
> Direct: [phone]
> http://www.hotwaxsystems.com
> www.hotwax.co
>
>
> On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <[hidden email]>
> wrote:
>
> > Hi Jacques,
> >
> > I support the suggestion made by Sharan. It should not be too difficult,
> > when a release has been made available (this should be part of the
> release
> > activities), to generate the 'release' related documents and hook it into
> > the website. Our (potential) adopters will benefit.
> >
> >
> > Best regards,
> >
> > Pierre Smits
> >
> > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > *Apache Directory <https://directory.apache.org>, PMC Member*
> > Apache Incubator <https://incubator.apache.org>, committer
> > *Apache OFBiz <https://ofbiz.apache.org>, contributor (without
> privileges)
> > since 2008*
> > Apache Steve <https://steve.apache.org>, committer
> >
> >
> > On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
> > [hidden email]> wrote:
> >
> > > At
> > >
> >
> https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
> > >
> > > Sharan already suggested to "Backport to releases where possible"
> > >
> > > I think we should do that and not way R18 to use the AsciiDoc
> generation
> > > even if it's not complete
> > >
> > > Opinions before I get ahead?
> > >
> > > Jacques
> > >
> > >
> > > Le 14/11/2018 à 08:41, Jacques Le Roux a écrit :
> > > > Hi,
> > > >
> > > > So start this discussion, currently our main documents in
> docs\asciidoc
> > > refer to the R17 release. But those document don't exist in R17 branch.
> > > >
> > > > I think it's not too late to backport them, but do we want to do so?
> > > >
> > > > Also I suggested to have an easy access to the documentation from the
> > > site documentation page.
> > > >
> > > > Do we also want to use the AsciiDoc generated documentation as we did
> > to
> > > provide an online help from the applications?
> > > >
> > > > Do we want to provide something like
> > > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
> > > >
> > > > For me the answers to these questions is NO! We should have a sole
> > entry
> > > point for the documentation and it should be from the site
> documentation
> > > > page. It's then easy to provide links from there (using anchors going
> > to
> > > automatically generated IDs sections)
> > > >
> > > > What are your opinions? (I know I should re-read this thread
> > > https://markmail.org/message/35ak34fpzlyjiopt and I started...)
> > > >
> > > > Jacques
> > > >
> > > >
> > >
> > >
> >
>

[Aditya Sharma]

+1 for backport

Thanks and Regards,

*Aditya Sharma* | Enterprise Software Engineer
HotWax Commerce <http://www.hotwax.co/> by HotWax Systems
<http://www.hotwaxsystems.com/>
[image: https://www.linkedin.com/in/aditya-p-sharma/]
<https://www.linkedin.com/in/aditya-p-sharma/>


On Thu, Nov 22, 2018 at 9:53 AM Arun Patidar <[hidden email]>
wrote:

> +1 for backport
>
> On Fri, Nov 16, 2018, 2:53 PM Rishi Solanki <[hidden email]>
> wrote:
>
> > +1 for backport.
> >
> > --
> > Rishi Solanki
> > Sr Manager, Enterprise Software Development
> > HotWax Systems Pvt. Ltd.
> > Direct: [phone]
> > http://www.hotwaxsystems.com
> > www.hotwax.co
> >
> >
> > On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <[hidden email]>
> > wrote:
> >
> > > Hi Jacques,
> > >
> > > I support the suggestion made by Sharan. It should not be too
> difficult,
> > > when a release has been made available (this should be part of the
> > release
> > > activities), to generate the 'release' related documents and hook it
> into
> > > the website. Our (potential) adopters will benefit.
> > >
> > >
> > > Best regards,
> > >
> > > Pierre Smits
> > >
> > > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > > *Apache Directory <https://directory.apache.org>, PMC Member*
> > > Apache Incubator <https://incubator.apache.org>, committer
> > > *Apache OFBiz <https://ofbiz.apache.org>, contributor (without
> > privileges)
> > > since 2008*
> > > Apache Steve <https://steve.apache.org>, committer
> > >
> > >
> > > On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
> > > [hidden email]> wrote:
> > >
> > > > At
> > > >
> > >
> >
> https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
> > > >
> > > > Sharan already suggested to "Backport to releases where possible"
> > > >
> > > > I think we should do that and not way R18 to use the AsciiDoc
> > generation
> > > > even if it's not complete
> > > >
> > > > Opinions before I get ahead?
> > > >
> > > > Jacques
> > > >
> > > >
> > > > Le 14/11/2018 à 08:41, Jacques Le Roux a écrit :
> > > > > Hi,
> > > > >
> > > > > So start this discussion, currently our main documents in
> > docs\asciidoc
> > > > refer to the R17 release. But those document don't exist in R17
> branch.
> > > > >
> > > > > I think it's not too late to backport them, but do we want to do
> so?
> > > > >
> > > > > Also I suggested to have an easy access to the documentation from
> the
> > > > site documentation page.
> > > > >
> > > > > Do we also want to use the AsciiDoc generated documentation as we
> did
> > > to
> > > > provide an online help from the applications?
> > > > >
> > > > > Do we want to provide something like
> > > > https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
> > > > >
> > > > > For me the answers to these questions is NO! We should have a sole
> > > entry
> > > > point for the documentation and it should be from the site
> > documentation
> > > > > page. It's then easy to provide links from there (using anchors
> going
> > > to
> > > > automatically generated IDs sections)
> > > > >
> > > > > What are your opinions? (I know I should re-read this thread
> > > > https://markmail.org/message/35ak34fpzlyjiopt and I started...)
> > > > >
> > > > > Jacques
> > > > >
> > > > >
> > > >
> > > >
> > >
> >
>

Thanks all,

It seems nobody is against backporting, so I'll continue with OFBIZ-10651 and OFBIZ-10652

I already generate the documentation from the trunk under https://ci.apache.org/projects/ofbiz/site/. I'll  swap to R17 after backporting necessary,
as the documentation should preferably be provided for users, developers can always generate it locally.

Note: After upgrading asciidoctor-gradle-plugin this message shows when generating the documentation

    Implicit attributes projectdir and rootdir are deprecated and will no longer be set in 2.0. Please migrate your documents to use gradle-projectdir
    and gradle-rootdir instead.

It's a known issue and will be fixed soon: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/270

Also, so far in Buildbot log only (not locally) I saw a message saying

    asciidoctor: WARNING: could not embed image:
    /home/buildslave/slave/ofbizTrunkFrameworkPlugins/build/plugins/birt/src/docs/asciidoc/images/Report-Master.png; PNG uses unsupported interlace
    method

Anyway, despite that the image is embedded even in https://ci.apache.org/projects/ofbiz/site/pluginsdoc/birt/html5/birt.html

Also at r1847177  I formatted too long lines in wa-cross-domains-SSO.adoc. I'll do the same later to the Birt Flexible Reports doc that I imported
from text files.

I noticed that AsciidocFX wraps line by default (only view, no formatting option[1]) but there is no option for that in Eclipse Asciidoc Editor
plugin. I don't know for IntelliJ.

[1] https://github.com/asciidocfx/AsciidocFX/issues/205

Jacques


Le 22/11/2018 à 05:29, Aditya Sharma a écrit :

> +1 for backport
>
> Thanks and Regards,
>
> *Aditya Sharma* | Enterprise Software Engineer
> HotWax Commerce <http://www.hotwax.co/> by HotWax Systems
> <http://www.hotwaxsystems.com/>
> [image: https://www.linkedin.com/in/aditya-p-sharma/]
> <https://www.linkedin.com/in/aditya-p-sharma/>
>
>
> On Thu, Nov 22, 2018 at 9:53 AM Arun Patidar <[hidden email]>
> wrote:
>
>> +1 for backport
>>
>> On Fri, Nov 16, 2018, 2:53 PM Rishi Solanki <[hidden email]>
>> wrote:
>>
>>> +1 for backport.
>>>
>>> --
>>> Rishi Solanki
>>> Sr Manager, Enterprise Software Development
>>> HotWax Systems Pvt. Ltd.
>>> Direct: [phone]
>>> http://www.hotwaxsystems.com
>>> www.hotwax.co
>>>
>>>
>>> On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <[hidden email]>
>>> wrote:
>>>
>>>> Hi Jacques,
>>>>
>>>> I support the suggestion made by Sharan. It should not be too
>> difficult,
>>>> when a release has been made available (this should be part of the
>>> release
>>>> activities), to generate the 'release' related documents and hook it
>> into
>>>> the website. Our (potential) adopters will benefit.
>>>>
>>>>
>>>> Best regards,
>>>>
>>>> Pierre Smits
>>>>
>>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>>> Apache Incubator <https://incubator.apache.org>, committer
>>>> *Apache OFBiz <https://ofbiz.apache.org>, contributor (without
>>> privileges)
>>>> since 2008*
>>>> Apache Steve <https://steve.apache.org>, committer
>>>>
>>>>
>>>> On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
>>>> [hidden email]> wrote:
>>>>
>>>>> At
>>>>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
>>>>> Sharan already suggested to "Backport to releases where possible"
>>>>>
>>>>> I think we should do that and not way R18 to use the AsciiDoc
>>> generation
>>>>> even if it's not complete
>>>>>
>>>>> Opinions before I get ahead?
>>>>>
>>>>> Jacques
>>>>>
>>>>>
>>>>> Le 14/11/2018 à 08:41, Jacques Le Roux a écrit :
>>>>>> Hi,
>>>>>>
>>>>>> So start this discussion, currently our main documents in
>>> docs\asciidoc
>>>>> refer to the R17 release. But those document don't exist in R17
>> branch.
>>>>>> I think it's not too late to backport them, but do we want to do
>> so?
>>>>>> Also I suggested to have an easy access to the documentation from
>> the
>>>>> site documentation page.
>>>>>> Do we also want to use the AsciiDoc generated documentation as we
>> did
>>>> to
>>>>> provide an online help from the applications?
>>>>>> Do we want to provide something like
>>>>> https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
>>>>>> For me the answers to these questions is NO! We should have a sole
>>>> entry
>>>>> point for the documentation and it should be from the site
>>> documentation
>>>>>> page. It's then easy to provide links from there (using anchors
>> going
>>>> to
>>>>> automatically generated IDs sections)
>>>>>> What are your opinions? (I know I should re-read this thread
>>>>> https://markmail.org/message/35ak34fpzlyjiopt and I started...)
>>>>>> Jacques
>>>>>>
>>>>>>
>>>>>

[Jacques Le Roux]

Le 22/11/2018 à 16:43, [hidden email] a écrit :
>
> Also, so far in Buildbot log only (not locally) I saw a message saying
>
>    asciidoctor: WARNING: could not embed image:
> /home/buildslave/slave/ofbizTrunkFrameworkPlugins/build/plugins/birt/src/docs/asciidoc/images/Report-Master.png; PNG uses unsupported interlace
>    method
>
> Anyway, despite that the image is embedded even in https://ci.apache.org/projects/ofbiz/site/pluginsdoc/birt/html5/birt.html

The problem is in PDF: https://ci.apache.org/projects/ofbiz/site/pluginsdoc/birt/pdf/birt.pdf

This is related: https://github.com/asciidoctor/asciidoctor-pdf/issues/867

https://github.com/packetmonkey/prawn-gmagick is the solution.

I have created  OFBIZ-10703 for that but did not install it since it's impossible on Windows

    <<The prawn-gmagick gem uses native extensions to compile against GraphicsMagick. This system prerequisite limits installation to Linux and OSX.
    Please refer to the README for prawn-gmagick <https://github.com/packetmonkey/prawn-gmagick> to learn how to install it.>

Jacques