https://projects.osmocom.org/https://projects.osmocom.org/favicon.ico?16647414092019-12-02T13:28:41ZOpen Source Mobile CommunicationsCellular Network Infrastructure - Feature #4132: idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2xhttps://projects.osmocom.org/issues/4132?journal_id=166862019-12-02T13:28:41Zneelsnhofmeyr@sysmocom.de
<ul></ul><p>Related: instead of generating XML to produce the VTY reference documentation, the 'show online-help' command could output asciidoc, too.<br />I guess that could be easier on humans?<br />But there is some combinatory logic going on which we might need to revisit; but nothing a bit of sed couldn't solve, IIRC</p> Cellular Network Infrastructure - Feature #4132: idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2xhttps://projects.osmocom.org/issues/4132?journal_id=179442020-04-03T06:40:55Zosmith
<ul></ul><p>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.</p> Cellular Network Infrastructure - Feature #4132: idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2xhttps://projects.osmocom.org/issues/4132?journal_id=179452020-04-03T07:50:25Zlaforge
<ul></ul><p>On Fri, Apr 03, 2020 at 06:40:55AM +0000, osmith [REDMINE] wrote:</p>
<blockquote>
<p>This seems feasible, but it's nothing I should be spending time on now.</p>
</blockquote>
<p>Yes, let's please focus on not spending time on fixing things that are working...</p> Cellular Network Infrastructure - Feature #4132: idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2xhttps://projects.osmocom.org/issues/4132?journal_id=264582023-03-24T13:11:58Zosmith
<ul></ul><p>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.</p>
<p>On debian 11, e.g. in <a class="external" href="https://jenkins.osmocom.org/jenkins/job/master-osmo-bsc/a1=default,a2=default,a3=default,a4=default,label=osmocom-master/21279/consoleFull">https://jenkins.osmocom.org/jenkins/job/master-osmo-bsc/a1=default,a2=default,a3=default,a4=default,label=osmocom-master/21279/consoleFull</a>, 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.</p>
<pre>
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.
</pre> Cellular Network Infrastructure - Feature #4132: idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2xhttps://projects.osmocom.org/issues/4132?journal_id=268252023-05-03T16:58:23Zosmith
<ul><li><strong>Status</strong> changed from <i>New</i> to <i>Rejected</i></li></ul>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:
<ul>
<li>generate the manuals faster</li>
<li>require less dependencies to be installed (-> build related docker images faster)</li>
</ul>
<p>For asciidoctor: to get the diagrams working, we would need the <a href="https://docs.asciidoctor.org/diagram-extension/latest/" class="external">diagram-extension</a> which is not packaged in Debian.<br />And even with that it looks like it would be quite some effort to make the manuals look the same as they are now.</p>
<p>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.</p>
<p>Closing.</p> Cellular Network Infrastructure - Feature #4132: idea: osmo-gsm-manuals: use asciidoctor-pdf instead of a2xhttps://projects.osmocom.org/issues/4132?journal_id=268302023-05-04T05:49:59Zlaforge
<ul></ul><p>osmith wrote in <a href="#note-5">#note-5</a>:</p>
<blockquote>
<p>So I agree, it's not worth it.</p>
</blockquote>
<p>sorry to hear you ended up at the same conclusion...</p>