You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by Paul Foxworthy <pa...@cohsoft.com.au> on 2017/11/08 07:25:28 UTC
Re: [Discussion] documentation framework for OFBiz
On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de> wrote:
> I assume that we can use any Asciidoc editor and need not to use
> Asciidoctor?
>
Hi Michael,
Asciidoctor is not an editor, it's a text processor that can convert
AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
(https://pandoc.org/).
One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
for IntelliJ IDEA. Your tastes may vary.
Cheers
Paul Foxworthy
--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia
Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Posted by Taher Alkhateeb <sl...@gmail.com>.
Hi Sharan,
As I was explaining to Jacques, there is no tool selection issue. Pandoc
cannot handle asciidoc and therefore the best viable choice is asciidoctor.
What is stopping us right now is my delay in implementing the feature ( I
am about half way through in OFBIZ-9873 to tackle the PoC ).
On Nov 8, 2017 1:21 PM, "Sharan Foga" <sh...@gmail.com> wrote:
Hi All
At the Open Source Summit in Prague a couple of weeks ago I attended quite
a few documentation related talks and also interviewed one of the
presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk
about converting legacy docs into more user story based content, so bit
like what we need to do. Anyway his recommendation was Asciidoc and he also
had some links to resources that could help in our documentation journey.
If the tool selection is actually stopping us from moving onto the next
step then let's present the proposal options (e.g Asciidoc, Pandoc etc) and
ask the community to select their preference..
Thanks
Sharan
On 08/11/17 10:33, Taher Alkhateeb wrote:
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>
>>> Asciidoctor?
>>>
>>> Hi Michael,
>>>
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to
>> Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
>>
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>
>
Re: [Discussion] documentation framework for OFBiz
Posted by Sharan Foga <sh...@gmail.com>.
Hi All
At the Open Source Summit in Prague a couple of weeks ago I attended
quite a few documentation related talks and also interviewed one of the
presenters (Robert Kratky from Red Hat) for FeatherCast. He did a talk
about converting legacy docs into more user story based content, so bit
like what we need to do. Anyway his recommendation was Asciidoc and he
also had some links to resources that could help in our documentation
journey.
If the tool selection is actually stopping us from moving onto the next
step then let's present the proposal options (e.g Asciidoc, Pandoc etc)
and ask the community to select their preference..
Thanks
Sharan
On 08/11/17 10:33, Taher Alkhateeb wrote:
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
>> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>> Asciidoctor?
>>>
>>> Hi Michael,
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>
Re: [Discussion] documentation framework for OFBiz
Posted by Jacques Le Roux <ja...@les7arts.com>.
Ha thanks Taher, this answer to Michael's question: we indeed need Asciidoctor if we want to transform from Asciidoc to other formats. Then Pandoc can
possibly be used for more possibilities
Jacques
Le 08/11/2017 à 10:33, Taher Alkhateeb a écrit :
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
> On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
>
>> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
>> wrote:
>>
>>
>> I assume that we can use any Asciidoc editor and need not to use
>>> Asciidoctor?
>>>
>>> Hi Michael,
>> Asciidoctor is not an editor, it's a text processor that can convert
>> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
>> (https://pandoc.org/).
>>
>> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
>> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
>> for IntelliJ IDEA. Your tastes may vary.
>>
>> Cheers
>>
>> Paul Foxworthy
>>
>> Hi Paul,
> Do you know if there are there good reasons to favor Asciidoctor over
> Pandoc?
> I'm more in favour of the later because now I know it (thanks to you :))
> and especially because it offers so much possibilities, see graph here
> https://pandoc.org/
> You never know what you will need one day...
>
> Jacques
>
Re: [Discussion] documentation framework for OFBiz
Posted by Paul Foxworthy <pa...@cohsoft.com.au>.
On 9 November 2017 at 18:26, Taher Alkhateeb <sl...@gmail.com>
wrote:
> Anyway I don't see a reason so far to use pandoc to publish to pdf.
> Asciidoctor can publish to html, docbook, pdf and others.
Thanks Taher. That's fine by me.
Cheers
Paul Foxworthy
--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia
Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Posted by Taher Alkhateeb <sl...@gmail.com>.
Hi Paul,
First regarding your comment about pandoc, essentially pandoc is a set of
readers and writers. Each markup language needs a reader to convert from
and a writer to convert to. Asciidoc is missing a reader implementation. I
hope someone would implement it eventually.
Anyway I don't see a reason so far to use pandoc to publish to pdf.
Asciidoctor can publish to html, docbook, pdf and others. I like pandoc, it
is a swiss army knife kind of tool for conversion and written in haskell
(fantastic). However like a swiss army knife, it is not specialized like a
native tool designed for the job. So the time to use pandoc might be if
we're stuck or have some limitation with asciidoctor.
On Nov 9, 2017 2:28 AM, "Paul Foxworthy" <pa...@cohsoft.com.au> wrote:
On 8 November 2017 at 20:33, Taher Alkhateeb <sl...@gmail.com>
wrote:
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
Thanks Taher,
My impression was pandoc can read just about any structured input. It's
curious AsciiDoc isn't there.
So for HTML it's
AsciiDoc -- (asciidoctor) --> HTML
and for PDF it's
AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF
That sound right?
Cheers
Paul
--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia
Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Posted by Paul Foxworthy <pa...@cohsoft.com.au>.
On 8 November 2017 at 20:33, Taher Alkhateeb <sl...@gmail.com>
wrote:
> If you check the link you sent, you will notice that asciidoc is not an
> input format in pandoc, but rather an ouput format.
>
Thanks Taher,
My impression was pandoc can read just about any structured input. It's
curious AsciiDoc isn't there.
So for HTML it's
AsciiDoc -- (asciidoctor) --> HTML
and for PDF it's
AsciiDoc -- (asciidoctor) --> DocBook XML -- (pandoc) --> PDF
That sound right?
Cheers
Paul
--
Coherent Software Australia Pty Ltd
PO Box 2773
Cheltenham Vic 3192
Australia
Phone: +61 3 9585 6788
Web: http://www.coherentsoftware.com.au/
Email: info@coherentsoftware.com.au
Re: [Discussion] documentation framework for OFBiz
Posted by Taher Alkhateeb <sl...@gmail.com>.
If you check the link you sent, you will notice that asciidoc is not an
input format in pandoc, but rather an ouput format.
On Nov 8, 2017 12:29 PM, "Jacques Le Roux" <ja...@les7arts.com>
wrote:
Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de>
> wrote:
>
>
> I assume that we can use any Asciidoc editor and need not to use
>> Asciidoctor?
>>
>> Hi Michael,
>
> Asciidoctor is not an editor, it's a text processor that can convert
> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
> (https://pandoc.org/).
>
> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
> for IntelliJ IDEA. Your tastes may vary.
>
> Cheers
>
> Paul Foxworthy
>
> Hi Paul,
Do you know if there are there good reasons to favor Asciidoctor over
Pandoc?
I'm more in favour of the later because now I know it (thanks to you :))
and especially because it offers so much possibilities, see graph here
https://pandoc.org/
You never know what you will need one day...
Jacques
Re: [Discussion] documentation framework for OFBiz
Posted by Jacques Le Roux <ja...@les7arts.com>.
Le 08/11/2017 à 08:25, Paul Foxworthy a écrit :
> On 17 October 2017 at 20:25, Michael Brohl <mi...@ecomify.de> wrote:
>
>
>> I assume that we can use any Asciidoc editor and need not to use
>> Asciidoctor?
>>
> Hi Michael,
>
> Asciidoctor is not an editor, it's a text processor that can convert
> AsciiDoc to HTML or DocBook XML. So it's an alternative processor to Pandoc
> (https://pandoc.org/).
>
> One of the reasons to choose any wiki-like language (AsciiDoc, Markdown,
> etc) is you can use any text editor at all. I use a nice AsciiDoc plugin
> for IntelliJ IDEA. Your tastes may vary.
>
> Cheers
>
> Paul Foxworthy
>
Hi Paul,
Do you know if there are there good reasons to favor Asciidoctor over Pandoc?
I'm more in favour of the later because now I know it (thanks to you :)) and especially because it offers so much possibilities, see graph here
https://pandoc.org/
You never know what you will need one day...
Jacques