Figures in specifications

There are several ways for handling figures in a Gitlab-based specification. Let's discuss those options and their pros/cons in this thread.

Assumption: Figures are meant to be shown inside text documents that are written in markdown.

There are two ways how to accomplish that:

Referenced from Markdown

The markdown file contains a link to a supported a separate file containing a figure of a supported type. Markdown supports images in e.g. PNG or SVG. In addition to that format one must of also store the raw data in a separate file (e.g. MSC code, Visio image, ...). When the raw data is updated also the PNG/SVG version must be re-generated. To do that one needs to run e.g. command-line version mscgen.exe with paths to the source and target file. We envision that the Gitlab server does this automatically (using its pipeline functionality) whenever a new version of the raw data file is committed.

When working locally on your PC, you would probably install MSC locally to edit the MSC raw data file and would hence see the rendered version therein, too. But unless you regenerate the corresponding SVG/PNG file locally, you would not see the updated version inside the local markdown preview (e.g. in VS-Code). However, we also work on scripts that monitor updates to local (MSC-) files and that regenerate the PNG/SVG version automatically.

Embedded in Markdown

Gitlab and VS-Code have in-built support for Mermaid (https://mermaid.js.org/)which is an open source tool for creating sequence charts, block diagrams and many more. The syntax is different from MSC but similar. One can store the raw data of a Mermaid graph in a separate file similarly as discussed above for MSC. But it is also possible to embed the Mermaid raw data directly into the markdown text. The markdown renderer will render also the embedded Mermaid graph and display both in the markdown preview.

By default the resulting graphs look quite different from MSC but it should be possible to adjust that by means of style sheets (to be produced once).

When doing more complex changes to a graph or when creating a new graph, one may copy and paste the raw data to/from an (online/local) Mermaid editor (e.g. https://mermaid.live/). That means, you don't need to install an editor locally if you don't want to.

This approach seems quite attractive. One limitation is that one could not embed a figure generated from the same raw data in multiple places. However, we don't do that in today's specs either. Hence, this is likely no problem in practice.

Summary

We think it is worth trying out both approaches. References to a separately stored file will be necessary for figure formats that cannot be embedded directly (e.g. Visio, ...). And it is of course possible to mix both approaches for different file types.

It would be great if someone had time and energy to try creating Mermaid sequence charts with a similar look as our well known MSC charts.