Migrating the guide to AsciiDoc

[Clemens Lang]

Hi,

On Sat, Feb 15, 2020 at 01:52:44AM +0100, Rainer Müller wrote:
> 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.

I agree. We should switch and then just fix the issues that are still
open. I think we can live with suboptimal formatting for a while until
somebody has the chance to fix it, especially if it's much easier to fix
due to the more modern asciidoc syntax.

-- 
Clemens