Feature #4132
idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2x
0%
Description
Right now we are using a2x to convert from asciidoc to pdf. This means, that actually we are going through the following chain of conversions:
adoc -> docbook -> latex -> pdf
As described here: http://asciidoc.org/publishing-ebooks-with-asciidoc.html
If we used asciidoctor-pdf instead, we could directly convert to pdf:
adoc -> pdf
https://github.com/asciidoctor/asciidoctor-pdf
In theory, we should need a lot less dependencies then, have the conversion go faster and less sources for errors. We could hopefully remove this part, for example:
a2x $(A2X_OPTS) $(notdir $<) || (echo "ERROR: a2x failed! Running asciidoc to get verbose errors..."; \
asciidoc -v $(ASCIIDOC_OPTS) $(notdir $<); exit 1)
The downside is, that currently asciidoctor-pdf is only available from debian 10 (buster) onwards:
https://packages.debian.org/search?keywords=asciidoctor%2Dpdf
Maybe we can adopt this at some point in the future, when asciidoctor-pdf is included in the oldest debian release that we support.
History
#1 Updated by neels about 2 months ago
Related: instead of generating XML to produce the VTY reference documentation, the 'show online-help' command could output asciidoc, too.
I guess that could be easier on humans?
But there is some combinatory logic going on which we might need to revisit; but nothing a bit of sed couldn't solve, IIRC
