Migrating the guide to AsciiDoc

[Rainer Müller]

On 17.02.20 23:13, Mojca Miklavec wrote:
> I didn't yet check how the latest conversion looks like, so I cannot
> really make a good informed decision, but I would vote for proceeding
> with .adoc.

For comparison, I just put the AsciiDoc based guide online here:
https://guide-test.macports.org/

> 1.) Could we (at the time when the final migration is done) put the
> old fully functional generated manual somewhere for reference, so that
> we know what to strive for even after we change the underlying
> scripts?
> 
> 2.) Do we already have a process/job in place to generate the docs from .adoc?

@Ryan
Could you please install the asciidoctor port on the 'jobs-guide'
builder? I think this should be the only new dependency.

Other than that, we only need to add the 'make guide-fromadoc' target to
the build job (or rather, redefine 'make all' accordingly in the Makefile).

> I believe that we could crowd-source cleaning the docs at least to
> some extent provided that the basics are taken care of. If doing sane
> fixes to docbookrx is not feasible in the very near future, it would
> help if we could simply freeze the docbook sources (I don't care if
> that time is simply now), freeze the manual, generate a new manual
> from the .adoc sources in that branch and publish it at a different
> temporary URL, so that developers can see the results and maybe even
> contribute fixes / PRs without having to get the courage to run the
> conversion process themselves. Once the result is somewhat
> satisfactory or the decided deadline passes (whichever comes first),
> (clean and) merge the branch to master and publish the new manual at
> the old URL (and maybe the old one at a different one for comparison
> for a limited time period).

Some of changes I made to docbookrx are specific to the MacPorts Guide,
for example to deal with the XML include structure. I do not think it is
worth to try to find a generic solution for that.

The known steps that will need manual work are documented here. Please
feel free to add anything else you find in the current guide-test to
this list. Or just sent a reply with feedback.

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

Rainer