Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 23 10:09:06, mojca at macports.org wrote:
> 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).

Can the conversion to PDF happen without docbook?
(i.e. can asciidoc(tor|*) produce pdf itself?)

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

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

Apparently, it still cannot do multi-page output:
https://github.com/asciidoctor/asciidoctor/issues/626
https://github.com/openSUSE/asciidoctor/issues/9

Which means this does not get rid of docbook:
it adds to the top of it (or the bottom of it).

	Jan