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=073ad744…
My most recent ladder chart:
https://cgit.osmocom.org/osmo-bsc/commit/?h=neels/codec&id=01f370c1b365…
--
- Neels Hofmeyr <nhofmeyr(a)sysmocom.de>
http://www.sysmocom.de/
=======================================================================
* sysmocom - systems for mobile communications GmbH
* Alt-Moabit 93
* 10559 Berlin, Germany
* Sitz / Registered office: Berlin, HRB 134158 B
* Geschäftsführer / Managing Directors: Harald Welte