You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by Jacques Le Roux <ja...@les7arts.com> on 2018/11/14 07:41:38 UTC
AsciiDoc generated online documentation and releases
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
Re: AsciiDoc generated online documentation and releases
Posted by Jacques Le Roux <ja...@les7arts.com>.
Le 22/11/2018 à 16:43, jleroux@apache.org 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
Re: AsciiDoc generated online documentation and releases
Posted by "jleroux@apache.org" <jl...@apache.org>.
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 <ar...@hotwaxsystems.com>
> wrote:
>
>> +1 for backport
>>
>> On Fri, Nov 16, 2018, 2:53 PM Rishi Solanki <ri...@gmail.com>
>> wrote:
>>
>>> +1 for backport.
>>>
>>> --
>>> Rishi Solanki
>>> Sr Manager, Enterprise Software Development
>>> HotWax Systems Pvt. Ltd.
>>> Direct: +91-9893287847
>>> http://www.hotwaxsystems.com
>>> www.hotwax.co
>>>
>>>
>>> On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <pi...@apache.org>
>>> 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 <
>>>> jacques.le.roux@les7arts.com> 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
>>>>>>
>>>>>>
>>>>>
Re: AsciiDoc generated online documentation and releases
Posted by Aditya Sharma <ad...@hotwaxsystems.com>.
+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 <ar...@hotwaxsystems.com>
wrote:
> +1 for backport
>
> On Fri, Nov 16, 2018, 2:53 PM Rishi Solanki <ri...@gmail.com>
> wrote:
>
> > +1 for backport.
> >
> > --
> > Rishi Solanki
> > Sr Manager, Enterprise Software Development
> > HotWax Systems Pvt. Ltd.
> > Direct: +91-9893287847
> > http://www.hotwaxsystems.com
> > www.hotwax.co
> >
> >
> > On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <pi...@apache.org>
> > 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 <
> > > jacques.le.roux@les7arts.com> 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
> > > > >
> > > > >
> > > >
> > > >
> > >
> >
>
Re: AsciiDoc generated online documentation and releases
Posted by Arun Patidar <ar...@hotwaxsystems.com>.
+1 for backport
On Fri, Nov 16, 2018, 2:53 PM Rishi Solanki <ri...@gmail.com> wrote:
> +1 for backport.
>
> --
> Rishi Solanki
> Sr Manager, Enterprise Software Development
> HotWax Systems Pvt. Ltd.
> Direct: +91-9893287847
> http://www.hotwaxsystems.com
> www.hotwax.co
>
>
> On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <pi...@apache.org>
> 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 <
> > jacques.le.roux@les7arts.com> 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
> > > >
> > > >
> > >
> > >
> >
>
Re: AsciiDoc generated online documentation and releases
Posted by Rishi Solanki <ri...@gmail.com>.
+1 for backport.
--
Rishi Solanki
Sr Manager, Enterprise Software Development
HotWax Systems Pvt. Ltd.
Direct: +91-9893287847
http://www.hotwaxsystems.com
www.hotwax.co
On Thu, Nov 15, 2018 at 10:56 PM Pierre Smits <pi...@apache.org>
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 <
> jacques.le.roux@les7arts.com> 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
> > >
> > >
> >
> >
>
Re: AsciiDoc generated online documentation and releases
Posted by Pierre Smits <pi...@apache.org>.
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 <
jacques.le.roux@les7arts.com> 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
> >
> >
>
>
Re: AsciiDoc generated online documentation and releases
Posted by Jacques Le Roux <ja...@les7arts.com>.
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
>
>