Feature #4132


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

Added by osmith over 4 years ago. Updated 10 months 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 4 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 4 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 4 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...

Actions #4

Updated by osmith 11 months ago

Maybe worth revisiting this idea at some point. This would also avoid using inkscape during build of the manuals, as I understand the docbook->latex code ends up calling it to convert svgs to pdfs.

On debian 11, e.g. in,a2=default,a3=default,a4=default,label=osmocom-master/21279/consoleFull, this causes the following outputof deprecated functions and dbus related warnings that make it hard to find actual errors in the asciidoc format that would be the reason for a failed build.

inkscape -z -D --export-pdf=fig0.pdf /build/doc/manuals/aoip-mgw-options__1.svg
Warning: Option --without-gui= is deprecated
Warning: Option --export-pdf= is deprecated
Unable to init server: Could not connect: Connection refused
Failed to get connection
** (inkscape:40184): CRITICAL **: 09:22:51.887: dbus_g_proxy_new_for_name: assertion 'connection != NULL' failed

** (inkscape:40184): CRITICAL **: 09:22:51.887: dbus_g_proxy_call: assertion 'DBUS_IS_G_PROXY (proxy)' failed

** (inkscape:40184): CRITICAL **: 09:22:51.887: dbus_g_connection_register_g_object: assertion 'connection != NULL' failed

** (inkscape:40184): WARNING **: 09:22:51.999: Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored.
Actions #5

Updated by osmith 10 months ago

  • Status changed from New to Rejected
As discussed with Harald, I've researched this a bit. What I was hoping to find is one program without many dependencies that just converts asciidoc to pdf and is packaged in debian already, with the following goals:
  • generate the manuals faster
  • require less dependencies to be installed (-> build related docker images faster)

For asciidoctor: to get the diagrams working, we would need the diagram-extension which is not packaged in Debian.
And even with that it looks like it would be quite some effort to make the manuals look the same as they are now.

So I agree, it's not worth it. It probably makes more sense to slowly optimize the existing asciidoc based manuals code, e.g. adjust filters so we don't need to install inkscape and check if we can install less latex related depends etc.


Actions #6

Updated by laforge 10 months ago

osmith wrote in #note-5:

So I agree, it's not worth it.

sorry to hear you ended up at the same conclusion...


Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)