Railroad Diagrams

Railroad diagrams, sometimes called syntax diagrams, are a visual way of explaining the syntax rules of a computer language. Reading one is like reading a public transport map.

Each diagram starts on the left and ends on the right. Simply follow any line from the startpoint to the endpoint. All the alternative lines are equally valid. A line will sometimes jump over an item that is optional, or loop back to indicate that an item can be repeated.

In the example above, a comma appears between each occurrence of the repeated item. The comma path runs from right to left, and can only be reached by first passing through repeated.

Characters in round boxes are literal, i.e. they denote themselves. A name in a rectangular box denotes a further railroad diagram.

The TW Filter Syntax documentation makes extensive use of railroad diagrams.

The railroad diagrams in TiddlyWiki's documentation are generated with the Railroad Plugin.

Plugin

This plugin provides a <$railroad> widget for generating railroad diagrams as SVG images.

Alternatively, the diagram notation can be stored in a dedicated tiddler with its type field set to text/vnd.tiddlywiki.railroad, and that tiddler can simply be transcluded to wherever it is needed.

The plugin is based on a library by Tab Atkins, and has been extended to make it more flexible, including allowing components of a diagram to function as links or be transcluded from other tiddlers.

Learn more about the Railroad Plguin Syntax Description