A Message Sequence Charts extension for odoc
Add documentation for odoc extension plugins
Add index.mld files with usage examples for each extension:
- mermaid: Flowcharts, sequence diagrams, state diagrams, etc.
- msc: Message Sequence Charts for protocol documentation
- dot: Graphviz/DOT diagrams for graphs and trees
- admonition: Note, warning, tip, important callout blocks
- rfc: IETF RFC citations with automatic linking
Each extension now has its own documentation page demonstrating
the syntax and showing live rendered examples.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+137
+135
index.mld
+135
index.mld
···
1
+
{0 MSC Extension for odoc}
2
+
3
+
This extension adds support for {{:https://www.mcternan.me.uk/mscgen/}Message
4
+
Sequence Charts} (MSC) in odoc documentation. MSC is a graphical and textual
5
+
language for describing interactions between components.
6
+
7
+
{1 Installation}
8
+
9
+
{[
10
+
opam install odoc-msc-extension
11
+
]}
12
+
13
+
Once installed, the extension is automatically loaded by odoc.
14
+
15
+
{1 Usage}
16
+
17
+
Use the [{@msc[...]}] tag to embed Message Sequence Charts:
18
+
19
+
{v
20
+
{@msc[
21
+
msc {
22
+
a, b, c;
23
+
a -> b [label="request"];
24
+
b -> c [label="forward"];
25
+
c -> b [label="response"];
26
+
b -> a [label="reply"];
27
+
}
28
+
]}
29
+
v}
30
+
31
+
{1 Examples}
32
+
33
+
{2 Simple Request-Response}
34
+
35
+
{@msc[
36
+
msc {
37
+
client, server;
38
+
client -> server [label="GET /api/data"];
39
+
server -> client [label="200 OK"];
40
+
}
41
+
]}
42
+
43
+
{2 Three-Party Interaction}
44
+
45
+
{@msc[
46
+
msc {
47
+
user, frontend, backend, database;
48
+
49
+
user -> frontend [label="click button"];
50
+
frontend -> backend [label="POST /submit"];
51
+
backend -> database [label="INSERT"];
52
+
database -> backend [label="OK"];
53
+
backend -> frontend [label="201 Created"];
54
+
frontend -> user [label="show success"];
55
+
}
56
+
]}
57
+
58
+
{2 With Conditions and Boxes}
59
+
60
+
{@msc[
61
+
msc {
62
+
a, b, c;
63
+
64
+
a box a [label="prepare"];
65
+
a -> b [label="request"];
66
+
b -> c [label="check"];
67
+
c -> b [label="valid"];
68
+
b box b [label="process"];
69
+
b -> a [label="done"];
70
+
}
71
+
]}
72
+
73
+
{2 Parallel Messages}
74
+
75
+
{@msc[
76
+
msc {
77
+
client, cache, origin;
78
+
79
+
client -> cache [label="GET /resource"];
80
+
--- [label="cache miss"];
81
+
cache -> origin [label="fetch"];
82
+
origin -> cache [label="content"];
83
+
cache -> client [label="200 OK"];
84
+
}
85
+
]}
86
+
87
+
{2 Authentication Flow}
88
+
89
+
{@msc[
90
+
msc {
91
+
browser, app, auth, api;
92
+
93
+
browser -> app [label="access protected"];
94
+
app -> auth [label="redirect to login"];
95
+
auth -> browser [label="login form"];
96
+
browser -> auth [label="credentials"];
97
+
auth -> app [label="auth code"];
98
+
app -> auth [label="exchange code"];
99
+
auth -> app [label="access token"];
100
+
app -> api [label="request + token"];
101
+
api -> app [label="data"];
102
+
app -> browser [label="render page"];
103
+
}
104
+
]}
105
+
106
+
{1 Options}
107
+
108
+
The extension supports the following options:
109
+
110
+
- [named-style] - MscGen style: [basic], [lazy], [classic], etc.
111
+
- [width] - CSS width (e.g., [500px], [100%])
112
+
- [height] - CSS height
113
+
- [format] - Output format: omit for client-side JS, or [png]/[svg] for
114
+
server-side rendering (requires [mscgen] CLI tool)
115
+
116
+
{1 How It Works}
117
+
118
+
By default, diagrams are rendered client-side using the mscgen_js library
119
+
loaded from a CDN. The extension injects the necessary [<script>] tags
120
+
into the HTML output.
121
+
122
+
For server-side rendering, install the [mscgen] CLI tool and use
123
+
[format=png] or [format=svg].
124
+
125
+
{1 Syntax Reference}
126
+
127
+
MSC syntax basics:
128
+
- Declare entities: [a, b, c;]
129
+
- Messages: [a -> b \[label="text"\];]
130
+
- Return messages: [a <- b \[label="text"\];]
131
+
- Boxes: [a box a \[label="text"\];]
132
+
- Separators: [--- \[label="text"\];]
133
+
134
+
See the {{:https://www.mcternan.me.uk/mscgen/}MscGen documentation} for
135
+
the complete syntax reference.