MSC Extension for odoc

This extension adds support for Message Sequence Charts (MSC) in odoc documentation. MSC is a graphical and textual language for describing interactions between components.

Installation

opam install odoc-msc-extension

Once installed, the extension is automatically loaded by odoc.

Usage

Use the {@msc[...]} tag to embed Message Sequence Charts:

{@msc[
msc {
  a, b, c;
  a -> b [label="request"];
  b -> c [label="forward"];
  c -> b [label="response"];
  b -> a [label="reply"];
}
]}

Examples

Simple Request-Response

Three-Party Interaction

msc { user, frontend, backend, database; user -> frontend [label="click button"]; frontend -> backend [label="POST /submit"]; backend -> database [label="INSERT"]; database -> backend [label="OK"]; backend -> frontend [label="201 Created"]; frontend -> user [label="show success"]; }

With Conditions and Boxes

msc { a, b, c; a box a [label="prepare"]; a -> b [label="request"]; b -> c [label="check"]; c -> b [label="valid"]; b box b [label="process"]; b -> a [label="done"]; }

Parallel Messages

msc { client, cache, origin; client -> cache [label="GET /resource"]; --- [label="cache miss"]; cache -> origin [label="fetch"]; origin -> cache [label="content"]; cache -> client [label="200 OK"]; }

Authentication Flow

msc { browser, app, auth, api; browser -> app [label="access protected"]; app -> auth [label="redirect to login"]; auth -> browser [label="login form"]; browser -> auth [label="credentials"]; auth -> app [label="auth code"]; app -> auth [label="exchange code"]; auth -> app [label="access token"]; app -> api [label="request + token"]; api -> app [label="data"]; app -> browser [label="render page"]; }

Options

The extension supports the following options:

named-style - MscGen style: basic, lazy, classic, etc.
width - CSS width (e.g., 500px, 100%)
height - CSS height
format - Output format: omit for client-side JS, or png/svg for server-side rendering (requires mscgen CLI tool)

How It Works

By default, diagrams are rendered client-side using the mscgen_js library loaded from a CDN. The extension injects the necessary <script> tags into the HTML output.

For server-side rendering, install the mscgen CLI tool and use format=png or format=svg.

Syntax Reference

MSC syntax basics:

Declare entities: a, b, c;
Messages: a -> b [label="text"];
Return messages: a <- b [label="text"];
Boxes: a box a [label="text"];
Separators: --- [label="text"];

See the MscGen documentation for the complete syntax reference.