Re: [atomic-devel] Doc format?

[Nick Coghlan <ncoghlan gmail com>]

On 8 March 2016 at 07:39, Josh Berkus <jberkus redhat com> wrote:
> On 03/07/2016 09:00 AM, Matt Micene wrote:
>>
>> One option would be to pick one and then use pandoc to convert as
>> needed, it supports conversions between asciidoc, markdown, and
>> reStructuredText.
>>
>> http://pandoc.org/try/ is an online version, you can paste one of the
>> existing PA.io docs into it and see how the conversion looks.  We'd want
>> to add a local version to the workflow, not the online.
>
> Unfortunately, PanDoc can't convert between AsciiDoc Binder and ReadTheDocs
> RST without significant loss of structure.

If I recall correctly (from past experience with trying to do Sphinx
-> DocbookXML conversions), the problem is that pandoc supports
*reStructuredText*, but doesn't support *Sphinx*, which defines a
whole host of reStructuredText roles to actually turn it into a
semantic markup language.

So getting a decent conversion from AsciiDoc to Sphinx or vice-versa
would require someone taking the time to teach pandoc about Sphinx
roles.

Regards,
Nick.

-- 
Nick Coghlan   |   ncoghlan gmail com   |   Brisbane, Australia