Migrating the guide to AsciiDoc

[Mojca Miklavec]

On Mon, 17 Feb 2020 at 21:05, Clemens Lang <cal at macports.org> wrote:
>
> 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.

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.

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?

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).

Mojca