Feature #4132
closedidea: 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.
Updated by neels over 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
Updated by osmith about 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.
Updated by laforge about 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...
Updated by osmith about 1 year 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 https://jenkins.osmocom.org/jenkins/job/master-osmo-bsc/a1=default,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.
Updated by osmith about 1 year ago
- Status changed from New to Rejected
- 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.
Closing.
Updated by laforge about 1 year ago
osmith wrote in #note-5:
So I agree, it's not worth it.
sorry to hear you ended up at the same conclusion...