Migrating the guide to AsciiDoc

[Rainer Müller]

On 2018-04-22 09:29, Mojca Miklavec wrote:
> As requested during yesterday's meeting, here's the result of
> automatic conversion of our guide from xml (docbook) to asciidoc:
> 
>     https://github.com/macports/macports-guide/tree/master/guide/adoc
> 
> This was initially explored by Aljaž and gives quite nice results
> out-of-the-box, but there are still some issues with conversion that
> will have to be addressed either by fixing docbookrx itself or
> manually.

I fixed some of the issues by slightly modifying the XML. None of these
should change the output produced by DocBook, but help docbookrx to
understand the XML.

I started to document the issues with the conversion in the README. This
is not exhaustive, please add more things to this list if you spot them.

https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md

On one hand, some issues can only be fixed manually once we are sure we
are not going to run docbookrx again. On the other hand, I noticed that
it would be easier to fix other issues in docbookrx instead of
post-processing the *.adoc files.

However, some of the issues require tweaks to docbookrx that are
specific to the MacPorts guide, as they depend on assumptions how
certain elements are used.

I pushed some commits with such changes that are specific to the
MacPorts guide to my fork of docbookrx on the macports-guide branch:

https://github.com/raimue/docbookrx/tree/macports-guide

Should I move this repository to the MacPorts organization on GitHub for
collaboration? This would only be temporary until we are finished with
the conversion.

Rainer