Opened 7 years ago
Last modified 13 months ago
#56046 new enhancement
Convert guide from DocBook to AsciiDoc syntax
Reported by: | raimue (Rainer Müller) | Owned by: | g5pw (Aljaž Srebrnič) |
---|---|---|---|
Priority: | Normal | Milestone: | |
Component: | guide | Version: | |
Keywords: | Cc: | FranklinYu (Franklin Yu) | |
Port: |
Description
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.
Change History (6)
comment:1 Changed 7 years ago by raimue (Rainer Müller)
comment:2 Changed 6 years ago by zerok (Horst Gutmann)
Hi :)
What's the status on this? Can I somehow help with the conversion?
comment:3 Changed 6 years ago by 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!
comment:4 Changed 5 years ago by FranklinYu (Franklin Yu)
Cc: | FranklinYu added |
---|
comment:5 Changed 5 years ago by 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.
comment:6 Changed 13 months ago by 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.
See: https://lists.macports.org/pipermail/macports-dev/2018-April/038403.html