Migrating the guide to AsciiDoc

[Mojca Miklavec]

On 23 April 2018 at 09:42, Jan Stary <hans at stare.cz> wrote:
> On Apr 22 09:29:53, mojca at macports.org 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,
>
> Thank you. Any format is better than xml,
> and any tool is better than docbook.
>
>> but there are still some issues with conversion that
>> will have to be addressed either by fixing docbookrx itself or
>> manually.
>>
>> If anyone is willing to help in the process, your help will be appreciated.
>
> Is asciidoc what the user is upposed to read directly, as in e.g.
> https://github.com/macports/macports-guide/blob/master/guide/adoc/installing.adoc

No.

> or is that considered an "internal" format to be ultimately converted
> to html and put on a web page such as https://guide.macports.org/
> where the user will read it?

Yes. The guide should be converted to HTML (and ideally also PDF).

The fact that GitHub can interpret the format is just a bonus that
might also help developers when editing the page, but it's not meant
to be the final product.

> On Apr 22 11:39:23, raimue at macports.org wrote:
>> AsciiDoc is both the name of the format and also the name of the
>> original reference implementation in Python, but development on that
>> ceased a few years ago. AsciiDoctor is an alternative implementation in
>> Ruby and actively being developed.
>
> Which one produced the current adoc from of the xml guide?

Neither of them, the conversion was done with docbookrx, the link is also on
    https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md
so
    https://github.com/asciidoctor/docbookrx

> The Plan section says
>
>  First convert .adoc files back to docbook .xml format
>  and use the existing toolchain to generate the html pages
>  (to avoid further delays).
>
> That makes no sense to me: why convert back?
> Cannot html pages be generated from adoc directly?
> (And if so, why not use the original xml?)

Yes, one can directly generate html. But we need to figure out how to
do page splitting etc. This is why Rainer suggested to temporarily go
through docbook again. This is not absolutely set in stone though, if
someone polishes the process to sufficient details to allow
straightforwand conversion, we can use that one.

(I believe the main reason why going through docbook was considered
was because none of us took the time to figure out how to make a
multi-page html from asciidoc directly.)

Mojca