Re: [Documentation] test conversion from docbook to asciidoc

[Olivier Heintz]

Hi Jacques,

I have tested docbookrx convertion with HELP_ACCOUNTING_agreements.xml and the files mentioned in it and generate html with ./gradlew publishDocumentation
All the generated files seem correct, adoc and html.

When it will be a place (choosen by Documentation Team) to put files to work on, I will put them.

In the generate file HELP_ACCOUNTING_agreements.html, there is no anchor defined and we will need it if we need contextual link,
so now, I will try to find the good asciidoc syntax for that.

Olivier

Le 10/02/2018 à 11:21, Jacques Le Roux a écrit :

> Hi Olivier,
>
> I read at https://github.com/asciidoctor/docbookrx that
> "This converter is far from perfect at the moment and some of the conversion is done hastily. The plan is to evolve it into a robust library for
> performing this conversion in a reliable way."
>
> The last version of Pandoc (2.1.1) supports conversion from docbook to asciido. I have tried it but it seems not all is supported for instance using
> HELP_ACCOUNTING_agreements.xml (picked by chance)
>      pandoc -f docbook -t asciidoc HELP_ACCOUNTING_agreements.xml -o test.txt
> in
>      applications\accounting\data\helpdata
>
> I get this:
> <<
> Agreements.
> -----------
>
> An agreement is a way of recording a business arrangements or contract
> that your business makes with other companies or individuals. Common
> examples include Payment Terms (where you allow a customer up to 30 days
> to pay you) or Prompt Payment Discounts (where you offer a reduction on
> the amount owing if your customer pays you before a certain date)
>
> It can be used for the following:
>
> * Defining Payment Terms for Customers or Suppliers
> * Defining Sales Commissions
> * Setting up Prompt Payment Discounts
> * Setting up Price Lists (NOTE TO DO: Need to investigate how this logic
> overlaps with PRICE RULES in Catalog Manager)
> * Defining Late Fee Penalties
> * Defining preferred freight carriers or specific codes to be used
>  >>
>
> At 1st glance the text is limited in width to something like 72 chars I guess/hope this can be changed.
> And the included/linked documents are not  present.
> And yes, asciidoc can link
> http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#links
> https://github.com/asciidoctor/asciidoctor/wiki/How-to-link-to-a-relative-AsciiDoc-document
>
> Could you please try the same with docbookrx to see if we get something better?

[Sharan Foga]

Hi Olivier

Thanks for already getting started!

You are right that there is a lot of information in the online help that could help us with the general documentation. So just to be clear, we are not looking to update the online help at this stage, but only use the content from it that will help us create OFBiz documentation that includes a complete User and Technical Guide.

We have quite a bit of documentation sitting in our one of our old workspaces:

https://cwiki.apache.org/confluence/display/OFBENDUSER/End+User+Documentation

so rather than mess up the wiki that Michael has organised into a very nice structured format we could use the OFBENDUSER workspace instead. All the documentation in the OFBENDUSER workspace needs to be reviewed anyway and part of it was linked to the online help system too. So this could be a way of centralising everything we are going to work on and review in one place.

There are a few things that the Documentation Team will need to discuss, things like  the organisation, planning, communication etc - but let's get the basic setup stuff done first, then we can start talking about how to approach it all :-)

Thanks
Sharan

On 2018/02/11 11:42:16, Olivier Heintz <[hidden email]> wrote:

> Hi Jacques,
>
> I have tested docbookrx convertion with HELP_ACCOUNTING_agreements.xml and the files mentioned in it and generate html with ./gradlew publishDocumentation
> All the generated files seem correct, adoc and html.
>
> When it will be a place (choosen by Documentation Team) to put files to work on, I will put them.
>
> In the generate file HELP_ACCOUNTING_agreements.html, there is no anchor defined and we will need it if we need contextual link,
> so now, I will try to find the good asciidoc syntax for that.
>
> Olivier
>
> Le 10/02/2018 à 11:21, Jacques Le Roux a écrit :
> > Hi Olivier,
> >
> > I read at https://github.com/asciidoctor/docbookrx that
> > "This converter is far from perfect at the moment and some of the conversion is done hastily. The plan is to evolve it into a robust library for
> > performing this conversion in a reliable way."
> >
> > The last version of Pandoc (2.1.1) supports conversion from docbook to asciido. I have tried it but it seems not all is supported for instance using
> > HELP_ACCOUNTING_agreements.xml (picked by chance)
> >  Â Â Â  pandoc -f docbook -t asciidoc HELP_ACCOUNTING_agreements.xml -o test.txt
> > in
> >  Â Â Â  applications\accounting\data\helpdata
> >
> > I get this:
> > <<
> > Agreements.
> > -----------
> >
> > An agreement is a way of recording a business arrangements or contract
> > that your business makes with other companies or individuals. Common
> > examples include Payment Terms (where you allow a customer up to 30 days
> > to pay you) or Prompt Payment Discounts (where you offer a reduction on
> > the amount owing if your customer pays you before a certain date)
> >
> > It can be used for the following:
> >
> > * Defining Payment Terms for Customers or Suppliers
> > * Defining Sales Commissions
> > * Setting up Prompt Payment Discounts
> > * Setting up Price Lists (NOTE TO DO: Need to investigate how this logic
> > overlaps with PRICE RULES in Catalog Manager)
> > * Defining Late Fee Penalties
> > * Defining preferred freight carriers or specific codes to be used
> >  >>
> >
> > At 1st glance the text is limited in width to something like 72 chars I guess/hope this can be changed.
> > And the included/linked documents are not  present.
> > And yes, asciidoc can link
> > http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#links
> > https://github.com/asciidoctor/asciidoctor/wiki/How-to-link-to-a-relative-AsciiDoc-document
> >
> > Could you please try the same with docbookrx to see if we get something better?
>