gregturn / docbook2asciidoctor Goto Github PK

This script uses the Spring Boot CLI to convert an existing set of docbook manuals to asciidoctor.

To run:

It will print out a lot of debug information, but the above command will eventually produce:

• file1.adoc

• file2.adoc

• file3.adoc

Or if you are trying to convert a whole directory…​

The target folder will be your current path.

• Spacing inside code listings is tricky. Stripping out all redundant space would wreck formatting. But a lot of blocks are indented so figuring what to remove/not remove ends up in a less-then-perfect outcome. Attemps have been made to minimize, but you’ll probably have to hand edit (like removing extra blank lines before/after start of code blocks)

• Tables title block and column specs located in an awkward location. Because this is a SAX parser, it is simply too hard to put the column details BEFORE the title block, the way it should in asciidoctor. To help, a comment is generated explaining WHAT you must do when it fails to render in asciidoctor.

• Table column specs are also quite tricky. The script grabs all <colspec> elements, extras their colswidth attributes, and then tries to remove any "*", but this doesn’t seem to ALWAYS work.

• <example> blocks don’t render the title and opening/closing in the right order.

• If you have an index page with things like author details, copyrights, bookinfo, etc., its simply easier to write the front page by hand. The script at first tried to gather up all this info, but to make the script more flexible, this <bookinfo>, <authorgroup> stuff is simply ignored.

• Got images? You must craft a separate step to migrate all the image files into a new target "images" folder. We used a maven ant plugin to do that, as well as dropping in our own CSS file. The script now does the maven asciidoctor plugin handle moving image data into a target folder.

• Callouts are too hard and complex to convert the way docbook does them. Basically, all the info is passed through in an embedded fashion, meaning you need to go in and redo those parts yourself. Learn about them

• Just spotted a bullet list not rendered properly. Only links appeared, but the stars for each line were rendered, so it wasn’t hard to spot that it was done wrong.

In short, whenever you convert, you MUST walk through the results and edit appropriately. Hopefully, this script has minimized this.