Msc-generator
A tool to draw various charts from text description
(version 6.1.0, 3 November 2017)
Zoltan R. Turanyi
i
Table of Contents
1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 What’s new in Msc-generator 6.1 . . . . . . . . . . . . . 2
3 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1 Working with Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 The Ribbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 Zooming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.4 Tracking Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5 Auto Split . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.6 Collapsing and Expanding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.7 Embedding a Chart in a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.8 Command-line Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4 Signalling Chart Language Tutorial . . . . . . . . . . . 9
4.1 Defining Arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Defining Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Dividers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.4 Drawing Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.5 Drawing Things in Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.6 Annotating the Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.7 Other Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5 Graph Language Tutorial . . . . . . . . . . . . . . . . . . . . . 35
6 Block Diagram Language Tutorial . . . . . . . . . . . 38
6.1 Defining and Arranging Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.2 Arrows and Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7 Usage Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.1 Multiple Chart Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.2 Design Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.3 External Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.4 Smart Indent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.5 Color Syntax Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.6 Typing Hints and Autocompletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.7 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.8 Working with Multi-page Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.9 Scaling Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.10 Advanced OLE Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.10.1 Graphics of Embedded Charts . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
ii
7.10.2 Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.11 Autosave and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.12
International Text Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.13 Command-Line Referece . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.13.1 Label Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.13.2 Coloring Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.13.3 Text Editor Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.14 Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8 Reference for Common Language Elements
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
8.1 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
8.2 Text Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
8.3 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8.4 Numbering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.5 Specifying Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
8.6 Common Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
8.6.1 Line and Fill Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
8.6.2 Shadow Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
8.6.3 Text Formatting Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
8.6.4 Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
8.7 Scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
8.8 Defining Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
8.9 Chart Designs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
8.10 Defining Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
8.11 Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
8.12 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
8.13 File Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
9 Signalling Chart Language Reference . . . . . . . . 92
9.1 Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.2 Specifying Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.2.1 Entity Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.2.2 Group Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
9.2.3 Entity Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
9.2.4 Implicit Entity Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
9.2.5 Entity Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
9.2.6 Entity Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
9.3 Specifying Arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
9.3.1 Lost Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.3.2 Arrow Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.3.3 Arrow Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
9.3.4 Block Arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
9.4 Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.4.1 Box Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9.4.2 Box Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.5 Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
iii
9.6 Verticals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.7 Dividers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.8 Notes and Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.8.1 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.8.2 Comments and Endnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.9 Parallel Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.9.1 Parallel Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.9.2 Overlap Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.9.3 Joining Arrows and Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.10 Signalling Chart Attributes and Styles . . . . . . . . . . . . . . . . . . . . . . 124
9.10.1 Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.10.2 Word Wrappiog and Long Labels . . . . . . . . . . . . . . . . . . . . . . . 126
9.10.2.1 Word Wrapping for Signalling Charts . . . . . . . . . . . . . . 126
9.10.2.2 Word Wrapping for Block Diagrams . . . . . . . . . . . . . . . 127
9.10.3 Compression and Vertical Spacing . . . . . . . . . . . . . . . . . . . . . . 128
9.10.4 Default and Refinement Styles for Signalling Charts . . . . 128
9.11 Chart Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
9.12 Multiple Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
9.13 Free Drawing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
9.13.1 Spacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
9.13.2 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
9.13.3 Inline text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
9.14 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
9.15 Mscgen Backwards Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
10 Graph Language Reference . . . . . . . . . . . . . . . . 143
10.1 Graph Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
10.2 Default and Refinement Styles for Graphviz Graphs . . . . . . . . . 144
10.3 Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11 Block Diagram Language Reference . . . . . . . 146
11.1 Block Name Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.2 Block Types and Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.3 Block Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
11.4 Block Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.4.1 Default alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.4.2 Alignment modifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
11.4.3 Content placement inside another block . . . . . . . . . . . . . . . . 161
11.4.4 Block Layout Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
11.5 Arrows in Block Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
11.5.1 Defining Arrows and Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
11.5.2 Ports and Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.5.3 Fine-tuning Arrow Ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.5.4 Defining Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
11.5.5 Arrow Labels and Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
11.5.6 Arrow and Line Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
11.6 Replicating parts of the Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
11.6.1 Copying a Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
11.6.2 Block Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
11.6.3 Repeating a Block Many Times . . . . . . . . . . . . . . . . . . . . . . . . 171
11.7 Chart Options and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
iv
Chapter 1: Introduction
1
1 Introduction
This manual is for Msc-generator (version 6.1.0, 3 November 2017), a tool to draw various
charts from a textual description.
Please visit https://sourceforge.net/projects/msc-generator/ to download the
latest version.
Msc-generator is a program that parses textual chart descriptions and produces graphical
output in a variety of file formats, or as a Windows OLE object, which can be embedded
in documents, such as Word or PowerPoint. It currently supports three kinds of charts:
Message Sequence Charts (MSCs, this is where the name of the tool comes from); general
graphs in the DOT language of graphviz; and experimental Block Diagrams.
Message Sequence Charts are a way of representing entities and message interactions
between those entities over some time period. MSCs are often used in combination with
SDL. MSCs are popular in telecom and data networks and standards to specify how pro-
tocols operate. MSCs need not be complicated to create or use. Msc-generator aims to
provide a simple text language that is clear to create, edit and understand, and which can
be transformed into images. Msc-generator is a potential alternative to mouse-based editing
tools, such as Microsoft Visio.
The signalling chart part of msc-generator is heavily extended and completely rewrit-
ten version of the 0.08 version of Michael C McTernan’s mscgen. The original tool was
more geared towards describing interprocess communication, this version is more geared
towards networking. Msc-generator has a number of enhancements compared to mscgen.
The command-line syntax of Msc-generator is compatible to that of mscgen, so any tool
integrated with mscgen (such as Doxygen) can also be used with Msc-generator. Since
version 4.5 Msc-generator also contains an mscgen compatibility mode, which aims to inter-
pret mscgen chart descriptions in a fully backwards compatible manner. See Section 9.15
[Mscgen Backwards Compatibility], page 140.
The graph part of msc-generator uses the graphviz library to lay out graphs. It uses the
DOT language to describe charts, with a few extensions.
Block Diagrams use a language similar in logic to the above two. The language aims to
capture the relation among blocks to lay them out in relation to one another.
Msc-generator builds on lex, yacc, graphviz, glpk and cairo. A Linux and Windows port
is maintained. The Windows version is written using MFC.
Chapter 2: What’s new in Msc-generator 6.1
2
2 What’s new in Msc-generator 6.1
The improvements added since version 6.0 are listed below. If you are new to Msc-generator,
you should probably skip this section and start with Chapter 3 [Getting Started], page 4.
• block: Modified defaults. Default margin and internal margin is now 10 pixels (in-
stead of 2). (The internal margin of shapes and boxes containing just labels defaults
to zero.) content_margin is set to no by default, thus the margin of blocks inside a
container is not considered when calculating the size of the container, just to space
them to one another.
Default arrow routing is curvy not polygon. Lines will have the default routing of
straight (crossing any block in the way). Default arrow distance from blocks is now
5. When specifying a port and/or a direction, the arrow goes 10 pixels away from the
block in the direction specified.
The default label is now "\*" which will substitute to the name of the block (if any).
• block: Added horizontal and vertical arrow routing methods.
• block: Modified alignment attributes. The top, bottom, left, right attributes (and
attribute values) now refer to the visible side of the block and not the outer margin
as before. Consequently the vtop, vbottom, vleft, vright attributes and attribute
values (which so far referred to the visible sides) are removed and the mtop, mbottom,
mleft, mright are introduced, which refer to the outer margin. Also, so far if you
wanted to align to the upper fifth of the visible part of, say block A (ignoring outer
margin) you had to say center=A@v20%, now you need to say center=A@20%. If you
want to align to the upper fifth between the top and bottom margin, now just say
center=A@m20%. This change is, because I expect people to want to align the visible
parts of blocks, and not to something invisible (a margin) around them.
• block: Now the language allows changing the attributes of a block after definition.
Just type the name of the block followed by attributes (possibly a colon label). You
can also do this for several blocks in one go by listing them with commas: a, b
[line.color=red]; This is useful if you want to specify the same attribute to many
blocks and don’t want to repeat them (nor want to change the running style via use).
• block: You can also automatically create blocks that are mentioned in an arrow, line
or an attribute update construct as above. So you no longer have to say box a; box
b; a->b; You can simply say a->b;. This behavior can be disabled by setting the
auto_create chart option to no.
• block: Added ports to blocks. Ports are a specific location for the shape, which can
be the endpoint for lines and arrows. Each shape can define its own ports using the P
command in defshape. Referring to the port is via the @ symbol, like block1@port1-
>block2@port2; For boxes, the ports top, topleft, bottom, bottomright, etc. are
defined. For any block, you can also use a compass point n, ne, e, se, s, sw, w, nw or
indicate a number [-360..360], which is interpreted in degrees clockwise, with 0 pointing
to north (=top). The resulting port will be where the line from the center of the block
in the direction specified crosses the outer contour of the block. (Each port can also
specify the direction (see below), if you use a compass point or a number, that will also
be the direction the arrow leaves the block.) If you specify no port, just a block, the
arrow will start from the centerpoint of the block (plus modifiers see below).
Chapter 2: What’s new in Msc-generator 6.1
3
• block: Added directions to ports. After specifying the port, you can also specify what
direction the arrow or line shall leave or arrive to the block. The direction is in degrees
same as above. So, block@left@0 will start an arrow on the left of the block but
upwards. You can also use the built-in compass point names n, ne, e, se, s, sw, w, nw;
or perp which will make the arrow leave the block perpendicular to the contour of the
block. Thus box@80@perp will make the arrow leave left. Note that you can specify
distance for the blocks starting or ending an arrow - it will determine, how wide an arc
at the start or end of the arrow will be.
• block: You can influence where the arrow or line actually starts or ends, by appending
coordinates. Adding a +x or -x will shift the starting or endpoint
of the arrow to the right or left (resp) by the specified number of pixels. You can also
add +x% or -x%, which will use the width of the block to determine
how much to shift. Using y instead of x you can shift vertically. For example, saying
a+y5->b+y5; will make the arrow lower than the centerline of a and b (assuming a
row). You can add as many such modifiers as you want (together with the number
only one, see the next bullet).
• block: You can now append a signed number to the specification of an arrow end, like
a+5->b@port-10; This will make the arrow longer (positive value) or shorter (negative
value). This can be specified mixed with +x and +y modifiers (see above), but is applied
last. So first we determine the start and endpoints and directions using ports and +x +y
modifiers and direction specifiers, then route the arrow, finally truncate or enlengthen
it.
• block: You can completely omit block names from coordinates. Thus (10,10)-
>(20,20) is a valid arrow. These numbers are interpreted from the inner margin
of the block the arrow is defined within. They also make the block auto-scale to
be at least as big the coordinates specify. You can also refer to your parent, by
(10%,10%)->(20%,20%) or in combination, like (10%+5,10%)->(0,0). You can also
specify the m letter in front of these, in this case the coordinate is interpreted by
ignoring the inner margin. For blocks this is the inner side of the block line, for shapes
this is the box specified by the T command.
• block: added container_shape default style for shapes having content. Also added
--, ++, .., == refinement styles for solid, dashed, dotted and double-lined lines (so that
we can make them straight routed by default). These goven how a==b; will look like,
for example.
• block: the draw_before and draw_after attributes are now mutually exclusive. Set-
ting one will silently clear the other. They can also be part of styles and can be used
in use commands to make all subsequent arrows or blocks be drawn before or after
another block (or set of blocks).
• backend: Added the text.gap attribute setting all four text margins to the same value.
• GUI: Added the Technical Info checkbox to perferences. Setting it will make the
GUI show compilation statistics and diagnostic.
• commandline: The same Technical Info is available via the -TI switch.