Discussion:
AsciiDoc generated online documentation and releases
Jacques Le Roux
2018-11-14 07:41:38 UTC
Permalink
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
2018-11-15 11:50:43 UTC
Permalink
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
Post by 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
Pierre Smits
2018-11-15 17:25:48 UTC
Permalink
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 <
Post by 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
Post by 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.
Post by Jacques Le Roux
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.
Post by Jacques Le Roux
Do we also want to use the AsciiDoc generated documentation as we did to
provide an online help from the applications?
Post by Jacques Le Roux
Do we want to provide something like
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
Post by Jacques Le Roux
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
Post by Jacques Le Roux
page. It's then easy to provide links from there (using anchors going to
automatically generated IDs sections)
Post by Jacques Le Roux
What are your opinions? (I know I should re-read this thread
https://markmail.org/message/35ak34fpzlyjiopt and I started...)
Post by Jacques Le Roux
Jacques
Rishi Solanki
2018-11-16 09:15:26 UTC
Permalink
+1 for backport.

--
Rishi Solanki
Sr Manager, Enterprise Software Development
HotWax Systems Pvt. Ltd.
Direct: +91-9893287847
http://www.hotwaxsystems.com
www.hotwax.co
Post by Pierre Smits
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 <
Post by Jacques Le Roux
At
https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
Post by Jacques Le Roux
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
Post by 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.
Post by Jacques Le Roux
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.
Post by Jacques Le Roux
Do we also want to use the AsciiDoc generated documentation as we did
to
Post by Jacques Le Roux
provide an online help from the applications?
Post by Jacques Le Roux
Do we want to provide something like
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
Post by Jacques Le Roux
For me the answers to these questions is NO! We should have a sole
entry
Post by Jacques Le Roux
point for the documentation and it should be from the site documentation
Post by Jacques Le Roux
page. It's then easy to provide links from there (using anchors going
to
Post by Jacques Le Roux
automatically generated IDs sections)
Post by Jacques Le Roux
What are your opinions? (I know I should re-read this thread
https://markmail.org/message/35ak34fpzlyjiopt and I started...)
Post by Jacques Le Roux
Jacques
Arun Patidar
2018-11-22 04:22:46 UTC
Permalink
+1 for backport
Post by Rishi Solanki
+1 for backport.
--
Rishi Solanki
Sr Manager, Enterprise Software Development
HotWax Systems Pvt. Ltd.
Direct: +91-9893287847
http://www.hotwaxsystems.com
www.hotwax.co
Post by Pierre Smits
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
Post by Pierre Smits
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)
Post by Pierre Smits
since 2008*
Apache Steve <https://steve.apache.org>, committer
On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
Post by Jacques Le Roux
At
https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
Post by Pierre Smits
Post by Jacques Le Roux
Sharan already suggested to "Backport to releases where possible"
I think we should do that and not way R18 to use the AsciiDoc
generation
Post by Pierre Smits
Post by Jacques Le Roux
even if it's not complete
Opinions before I get ahead?
Jacques
Post by Jacques Le Roux
Hi,
So start this discussion, currently our main documents in
docs\asciidoc
Post by Pierre Smits
Post by Jacques Le Roux
refer to the R17 release. But those document don't exist in R17 branch.
Post by Jacques Le Roux
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.
Post by Jacques Le Roux
Do we also want to use the AsciiDoc generated documentation as we did
to
Post by Jacques Le Roux
provide an online help from the applications?
Post by Jacques Le Roux
Do we want to provide something like
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
Post by Jacques Le Roux
For me the answers to these questions is NO! We should have a sole
entry
Post by Jacques Le Roux
point for the documentation and it should be from the site
documentation
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
page. It's then easy to provide links from there (using anchors going
to
Post by Jacques Le Roux
automatically generated IDs sections)
Post by Jacques Le Roux
What are your opinions? (I know I should re-read this thread
https://markmail.org/message/35ak34fpzlyjiopt and I started...)
Post by Jacques Le Roux
Jacques
Aditya Sharma
2018-11-22 04:29:12 UTC
Permalink
+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/>
Post by Rishi Solanki
+1 for backport
Post by Rishi Solanki
+1 for backport.
--
Rishi Solanki
Sr Manager, Enterprise Software Development
HotWax Systems Pvt. Ltd.
Direct: +91-9893287847
http://www.hotwaxsystems.com
www.hotwax.co
Post by Pierre Smits
Hi Jacques,
I support the suggestion made by Sharan. It should not be too
difficult,
Post by Rishi Solanki
Post by Pierre Smits
when a release has been made available (this should be part of the
release
Post by Pierre Smits
activities), to generate the 'release' related documents and hook it
into
Post by Rishi Solanki
Post by Pierre Smits
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)
Post by Pierre Smits
since 2008*
Apache Steve <https://steve.apache.org>, committer
On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
Post by Jacques Le Roux
At
https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
Sharan already suggested to "Backport to releases where possible"
I think we should do that and not way R18 to use the AsciiDoc
generation
Post by Pierre Smits
Post by Jacques Le Roux
even if it's not complete
Opinions before I get ahead?
Jacques
Post by Jacques Le Roux
Hi,
So start this discussion, currently our main documents in
docs\asciidoc
Post by Pierre Smits
Post by Jacques Le Roux
refer to the R17 release. But those document don't exist in R17
branch.
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
I think it's not too late to backport them, but do we want to do
so?
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
Also I suggested to have an easy access to the documentation from
the
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
site documentation page.
Post by Jacques Le Roux
Do we also want to use the AsciiDoc generated documentation as we
did
Post by Rishi Solanki
Post by Pierre Smits
to
Post by Jacques Le Roux
provide an online help from the applications?
Post by Jacques Le Roux
Do we want to provide something like
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
Post by Jacques Le Roux
For me the answers to these questions is NO! We should have a sole
entry
Post by Jacques Le Roux
point for the documentation and it should be from the site
documentation
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
page. It's then easy to provide links from there (using anchors
going
Post by Rishi Solanki
Post by Pierre Smits
to
Post by Jacques Le Roux
automatically generated IDs sections)
Post by Jacques Le Roux
What are your opinions? (I know I should re-read this thread
https://markmail.org/message/35ak34fpzlyjiopt and I started...)
Post by Jacques Le Roux
Jacques
j***@apache.org
2018-11-22 15:43:52 UTC
Permalink
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
Post by Rishi Solanki
+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/>
Post by Rishi Solanki
+1 for backport
Post by Rishi Solanki
+1 for backport.
--
Rishi Solanki
Sr Manager, Enterprise Software Development
HotWax Systems Pvt. Ltd.
Direct: +91-9893287847
http://www.hotwaxsystems.com
www.hotwax.co
Post by Pierre Smits
Hi Jacques,
I support the suggestion made by Sharan. It should not be too
difficult,
Post by Rishi Solanki
Post by Pierre Smits
when a release has been made available (this should be part of the
release
Post by Pierre Smits
activities), to generate the 'release' related documents and hook it
into
Post by Rishi Solanki
Post by Pierre Smits
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)
Post by Pierre Smits
since 2008*
Apache Steve <https://steve.apache.org>, committer
On Thu, Nov 15, 2018 at 12:59 PM Jacques Le Roux <
Post by Jacques Le Roux
At
https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmap
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
Sharan already suggested to "Backport to releases where possible"
I think we should do that and not way R18 to use the AsciiDoc
generation
Post by Pierre Smits
Post by Jacques Le Roux
even if it's not complete
Opinions before I get ahead?
Jacques
Post by Jacques Le Roux
Hi,
So start this discussion, currently our main documents in
docs\asciidoc
Post by Pierre Smits
Post by Jacques Le Roux
refer to the R17 release. But those document don't exist in R17
branch.
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
I think it's not too late to backport them, but do we want to do
so?
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
Also I suggested to have an easy access to the documentation from
the
Post by Rishi Solanki
Post by Pierre Smits
Post by Jacques Le Roux
site documentation page.
Post by Jacques Le Roux
Do we also want to use the AsciiDoc generated documentation as we
did
Post by Rishi Solanki
Post by Pierre Smits
to
Post by Jacques Le Roux
provide an online help from the applications?
Post by Jacques Le Roux
Do we want to provide something like
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML?
Post by Jacques Le Roux
For me the answers to these questions is NO! We should have a sole
entry
Post by Jacques Le Roux
point for the documentation and it should be from the site
documentation
Post by Pierre Smits
Post by Jacques Le Roux
Post by Jacques Le Roux
page. It's then easy to provide links from there (using anchors
going
Post by Rishi Solanki
Post by Pierre Smits
to
Post by Jacques Le Roux
automatically generated IDs sections)
Post by Jacques Le Roux
What are your opinions? (I know I should re-read this thread
https://markmail.org/message/35ak34fpzlyjiopt and I started...)
Post by Jacques Le Roux
Jacques
Loading...