RFC about mscgen

mscgen is our tool of choice to generate ladder diagrams from the "msc" text input format. We use it in user manuals and on our redmine wiki, and there are also various .msc files in doc/ subdirs, as assistance for development.

I've written a lot of ladder diagrams, for documentation as well as figuring out how to implement things. I've developed a love/hate relationship, and recently I found a bug in mscgen.

Things have come up that I'd like your opinion on:

* ladder_to_msc.py

Writing .msc files by hand quickly started to annoy me: - Having to write '[label="..."]' all the time. - Multiline labels (e.g. '(note)' block) require "foo\nbar\nbaz" - input symbols for arrows are weird / non-intuitive - cannot use 'msc' as entity, weirdly conflicts with the outer 'msc { ... }', which is annoying for GSM diagrams featuring an MSC.

So quite some while ago I wrote a python script that reads my personal favorite format in which i enjoy writing ladder diagrams, and outputs plain .msc file format. I put it in libosmocore/contrib/ on a branch, have been using it ever since, but i never submitted it for merging, because it seemed like a personal preference thing, not worth complicating the doc tool chain for. So far I was, if at all, committing only the resulting .msc to git. But that creates a situation where only I have the *original* source in .ladder format, so (hypothetically) collaborating on ladder diagrams becomes convoluted.

Here is an example of my favorite ".ladder" format:

------ {hscale=1} upf = User Plane function cpf = Control Plane function

upf <- cpf PFCP Association Setup Request CP function Node Id, features upf -> cpf PFCP Association Setup Response UP function Node Id, features upf <> cpf associated upf () cpf start Heartbeat checking ... ------

The equivalent .msc produced by ladder_to_msc.py:

------ msc { hscale="1"; upf[label="User Plane function"],cpf[label="Control Plane function"];

upf <= cpf [label="PFCP Association Setup Request\nCP function Node Id, features"]; upf => cpf [label="PFCP Association Setup Response\nUP function Node Id, features"]; upf abox cpf [label="associated"]; upf rbox cpf [label="start Heartbeat checking"]; ...; ------

I'd like to hear some opinions, if you have any, on whether anyone else likes my new ladder format, and how to deal with .ladder source files.

Would it make sense to merge ladder_to_msc.py to libosmocore, install it via 'make install', and add the original .ladder files as well as Makefile rules to convert .ladder to .msc to .png where ever i wrote .ladder diagrams?

* mscgen bitrot is likely

Recently I've found a segfault in mscgen. I found a fix and tried to submit it. That's when I discovered that:

- the original project on code.google.com is dead and gone - the mail addresses of the original author result in bounces - random people put mscgen's trunk on github, exported from google code, no activity is apparent

I did reach the Debian maintainer of mscgen by mail. He doesn't have any way to contact the original author, either. It seems there could be a patch in the Debian package, at best.

I wonder if it would make sense to officially create an mscgen "fork" on Osmocom, in an effort to save the tool from bitrot and extinction, and offer our mscgen as the new upstream for debian's mscgen packaging.

I do have a number of things i'd like mscgen to be able to do, like left-adjust text in "note" blocks or improve the resolution of produced PNG images; I might also implement support for my .ladder format directly in mscgen.

I am vague on what my opinion is between the advantages and disadvantages, and it's all only semi important. I just know that I always end up writing .ladder instead of .msc, and that we will always need ladder diagrams.

Do you have any opinions on these things?

Thanks!

pointers:

ladder_to_msc.py: libosmocore branch neels/ladder https://cgit.osmocom.org/libosmocore/commit/?h=neels/ladder&id=073ad7443...

My most recent ladder chart: https://cgit.osmocom.org/osmo-bsc/commit/?h=neels/codec&id=01f370c1b3653...