Migrating the guide to AsciiDoc

Clemens Lang cal at macports.org
Mon Feb 17 20:05:34 UTC 2020


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.


More information about the macports-dev mailing list