61. Generation of grammar diagrams

Level: advanced · Reading time: 9 min · Prerequisite: book/chapters/60-sustainable-technical-documentation.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

Prerequisites: book/chapters/60-sustainable-technical-documentation.html. See also: book/chapters/60-sustainable-technical-documentation.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Grammar pages become unusable when they explain snippets without naming the parser layer or ambiguity they belong to.

Red Thread (Single Project)

One complete program is read as top-level declarations, block statements, expressions, and branch forms.

For what

This chapter helps the reader classify parser problems by grammar layer.

What you are going to do

You will inspect one valid program, one invalid program, and the grammar layer each one exercises.

Coherent example

space demo/grammar

pick Resp {
  case Ok(value: int)
  case Err(code: int)
}

proc run(x: int) -> int {
  match x {
    case 0 { give 0 }
    otherwise { give x }
  }
}

entry main at core/app {
  return run(1)
}

Global explanation

Grammar should be read by layer: top-level declarations, block statements, expressions, patterns, and ambiguity points. The reader should leave able to say what sort of parser expectation has failed.

Invalid case

proc broken(x: int) -> int {
  match x
    case 0 { give 0 }
  }
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Commenting each token instead of naming the grammar layer.
• Confusing parse failure with type or business failure.
• Skipping ambiguity notes where the same surface can be read two ways.

Short exercise

Take the valid example and identify one top-level rule, one statement rule, and one expression rule it exercises.

Summary in 5 points

1. Grammar is a layered model.
2. A full valid program is the right teaching unit.
3. Invalid examples should isolate parse structure failures.
4. Ambiguity must be explained, not hidden.
5. The chapter should naturally connect to diagnostics and tests.