Convert guide from DocBook to AsciiDoc syntax

[raimue (Rainer Müller)]

Aljaž (g5pw@) did a prototype conversion of the guide to AsciiDoc using ​docbookrx. The results looked promising. Getting rid of DocBook and XML would make it easier to edit the guide and lower the entry for contributors.

[raimue (Rainer Müller)]

See: ​https://lists.macports.org/pipermail/macports-dev/2018-April/038403.html

[zerok (Horst Gutmann)]

Hi :)

What's the status on this? Can I somehow help with the conversion?

[raimue (Rainer Müller)]

Hello and welcome! Yes, help would be appreciated. I had to drop it last year because of too many other things going on.

I think the first step would be to get the tools running for another conversion of the XML to *.adoc. I documented the steps to run the AsciiDoc conversion script using docbookrx here: ​https://lists.macports.org/pipermail/macports-dev/2018-April/038420.html

However, in order to get docbookrx to understand some of the syntax specific to the MacPorts Guide, I also had to patch docbookrx as described here and this is the version that needs to be used: ​https://lists.macports.org/pipermail/macports-dev/2018-April/038482.html

Then you can generate HTML output with asciidoctor based on the *.adoc files with these top-level Makefile targets. The first one generates guide/adoc/guide.xml in DocBook 5 syntax, the second one converts this XML to HTML.

make guide-adoc2xml
make guide-fromadoc
open guide/html/adoc/index.html

When this works, there is a list of things that are not converted correctly in the README file (at least as far as I could spot, there might be more!). These either need to be patched in docbookrx to get them recognized correctly, or they need to be fixed manually in the *.adoc files. Of course, the latter only makes sense if we are not going to do any more automatic conversions with docbookrx. It would be hard to merge the generated *.adoc files with manual edits.

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

Even just comparing the current state and documenting any other errors in the current conversion would be a great help!

[FranklinYu (Franklin Yu)]

Some of the known issue listed in the ReadMe are included in ​this feature request. Unfortunately, according to ​this comment the maintainer isn’t actively working on this project recently, so we would have to maintain our own fork for now.

[raimue (Rainer Müller)]

PR: ​https://github.com/macports/macports-guide/pull/65

It has been several years since the last work to improve the yet incomplete conversion to AsciiDoc. I originally wanted to have this in the upstream repository to generate interest and involve more contributors with the required manual fixes. However, I also lost the focus on the guide conversion and did not continue the work.

At this point, having the unfinished conversion attempt in the repository does more harm than it does good as it especially confuses new contributors. Let's accept this is not happening and remove the adoc/ directory.