[MacPorts] #56046: Convert guide from DocBook to AsciiDoc syntax

[MacPorts]

#56046: Convert guide from DocBook to AsciiDoc syntax
--------------------------+------------------
  Reporter:  raimue       |      Owner:  g5pw
      Type:  enhancement  |     Status:  new
  Priority:  Normal       |  Milestone:
 Component:  guide        |    Version:
Resolution:               |   Keywords:
      Port:               |
--------------------------+------------------

Comment (by raimue):

 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!

-- 
Ticket URL: <https://trac.macports.org/ticket/56046#comment:3>
MacPorts <https://www.macports.org/>
Ports system for macOS