Migrating the guide to AsciiDoc

[Rainer Müller]

On 25.04.18 04:35, Rainer Müller wrote:
> 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

I fixed another problem with literals as `startupitem.*` was not
interpreted as expected by AsciiDoctor and has to be written as
`+startupitem.*+`:
https://github.com/asciidoctor/asciidoctor/issues/1045

This style is now applied to all string literals by my patched
docbookrx. The alternative would be to use only backticks in the
conversion and fix broken occurrences by hand afterwards. I opted for
the safe variant, although the syntax is not as lean as it could be.


It has been almost two years... I would like to suggest we finally
decide on a flag day on which I will do a final conversion of the
DocBook to AsciiDoc and after that only the AsciiDoc version is kept in
the repository. All remaining issues can then be worked on in the
AsciiDoc files.

Please test out the conversion from AsciiDoc to HTML and compare the
result with the previous DocBook version:
make guide-fromadoc && open guide/html/adoc/index.html

The README.md file documents known issues and things that will need
manual work after the final conversion. Feel free to add anything else
you can spot:
https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md

If we are still not ready to make the switch, I would like to give up
this experiment and delete all *.adoc files from the repository as the
current state seems to be rather confusing for contributors.

Rainer