Feature #4132


idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2x

Added by osmith over 3 years ago. Updated almost 3 years ago.

Target version:
Start date:
Due date:
% Done:


Spec Reference:


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:

If we used asciidoctor-pdf instead, we could directly convert to pdf:

adoc -> 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:

Maybe we can adopt this at some point in the future, when asciidoctor-pdf is included in the oldest debian release that we support.

Actions #1

Updated by neels about 3 years 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

Actions #2

Updated by osmith almost 3 years ago

I've briefly evaluated if I could use this for the IMSI pseudonymization draft spec. The tool converts to pdf remarkably fast, but I could not find integration for message sequence charts (msc). It seems that we would need to add a plugin, which detects the msc block and calls mscgen first, and then load it with the -r command line option. This seems feasible, but it's nothing I should be spending time on now.

Actions #3

Updated by laforge almost 3 years ago

On Fri, Apr 03, 2020 at 06:40:55AM +0000, osmith [REDMINE] wrote:

This seems feasible, but it's nothing I should be spending time on now.

Yes, let's please focus on not spending time on fixing things that are working...


Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)