Graphviz: The DOT Language and Rendering Pipeline

The DOT language grammar from graphviz.org/doc/info/lang.html:

graph     : [ 'strict' ] ('graph' | 'digraph') [ ID ] '{' stmt_list '}'
stmt_list : [ stmt [ ';' ] stmt_list ]
stmt      : node_stmt | edge_stmt | attr_stmt | ID '=' ID | subgraph
attr_stmt : ('graph' | 'node' | 'edge') attr_list
attr_list : '[' [ a_list ] ']' [ attr_list ]
a_list    : ID '=' ID [ (';' | ',') a_list ]
edge_stmt : (node_id | subgraph) edgeRHS [ attr_list ]
edgeRHS   : edgeop (node_id | subgraph) [ edgeRHS ]
node_stmt : node_id [ attr_list ]
node_id   : ID [ port ]
port      : ':' ID [ ':' compass_pt ] | ':' compass_pt
subgraph  : [ 'subgraph' [ ID ] ] '{' stmt_list '}'
compass_pt: 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw' | 'c' | '_'

Four forms of identifier:

Quoted strings support concatenation with + and backslash-continued newlines. HTML strings do not.

Case-insensitive: node, edge, graph, digraph, subgraph, strict.

Three forms, all standard C/C++:

The // line comment is the form org-babel uses for tangle breadcrumbs:

These comments survive parsing — dot -Tpng ignores them, dot -Tdot strips them from the canonical output. The breadcrumbs are invisible to the renderer but enable org-babel-detangle to map tangled code back to its source block.

Default attributes propagate forward in the file:

This is why the wal.sh style guide places node [...] and edge [...] defaults at the top of every graph — they establish the palette for all nodes that follow.

A subgraph whose name starts with cluster is laid out as a visual container by the dot engine. This is a convention, not a language rule — other layout engines may ignore it.

All 85 wal.sh diagrams use dot (hierarchical). The rankdir attribute controls the primary axis: TB (top-to-bottom) for layer stacks, LR (left-to-right) for pipelines and state machines.

Emacs ob-dot enables dot src blocks in org files:

#+begin_src dot :file diagram.png :exports results :cmdline -Tpng
digraph G { a -> b; }
#+end_src

:file is required — ob-dot writes to this path. :cmdline -Tpng passes flags to the dot command. :exports results shows only the image in HTML output, not the source.

The round-trip workflow for editing diagrams:

1. Tangle — gmake tangle exports #+begin_src dot :tangle file.dot blocks from .org to standalone .dot files. With :comments link, the tangled file includes // [[file:...]] breadcrumbs.
2. Edit — modify the .dot file directly (agents or manual).
3. Compile — dot -Tpng file.dot -o file.png to verify it renders.
4. Detangle — gmake detangle reads the breadcrumbs and pulls changes back into the org src blocks.
5. Verify — re-tangle to confirm the round-trip is stable.

For this to work, the graphviz-dot-mode must set comment-start to "// " so org-babel knows how to write the breadcrumb comments. This is configured in project-config.el:

(add-to-list 'org-babel-tangle-lang-exts '("dot" . "dot"))
(add-hook 'graphviz-dot-mode-hook
          (lambda () (setq-local comment-start "// ")
                     (setq-local comment-end "")))

dot -Tdot parses a source file and emits the canonical form with computed positions. Comments are stripped. This is useful for:

• Verifying a file parses without errors
• Comparing two files for structural equivalence (ignore formatting)
• Debugging layout issues (the pos attributes show exact coordinates)

Batch validation of all diagrams:

find site/research -name '*.dot' | while read f; do
  dot -Tdot "$f" > /dev/null 2>&1 || echo "FAIL: $f"
done

Built-in since Emacs 24. Evaluates #+begin_src dot blocks.

The execute function writes the body to a temp file, calls dot <tmpfile> <cmdline> -o <outfile>, and returns the file path. Variables ($name) are interpolated from :var headers.

No session support — each evaluation is a fresh process.

Tangle writes DOT src blocks to standalone .dot files. With :comments link, breadcrumb comments enable detangle (round-trip).

Requires comment-start set to "// " in the target buffer. Our project-config.el registers this via graphviz-dot-mode-hook and adds ("dot" . "dot") to org-babel-tangle-lang-exts.

Built-in since Emacs 23 (part of CEDET/Semantic). Accepts BNF grammars in .wy files, generates Emacs Lisp LALR(1) parsers.

The DOT grammar translates mechanically from the spec's EBNF:

Compile path: M-x semantic-grammar-batch-build-packages on a .wy file produces a *-wy.el parser table.

Built-in companion to wisent. Defines lexer rules as define-lex-regex-analyzer forms. The DOT lexer needs:

• // line comments (trivial)
• # preprocessor lines (trivial)
• /* */ block comments (via syntax table)
• Quoted strings with \" escape and backslash-NL continuation
• HTML strings with balanced <...> nesting
• Numeric IDs (-?(\.[0-9]+|[0-9]+(\.[0-9]*)?))
• Case-insensitive keywords (graph = Graph = GRAPH)

The first three are trivial; the last four are the real work.

Not built-in. Installed from MELPA via project-config.el. Provides:

• Syntax highlighting for .dot files
• comment-start / comment-end (needed for tangle breadcrumbs)
• Indentation
• compile integration (C-c C-c runs dot)