From 921b6b725403e1ae301ebb56e81cb5f927547cea Mon Sep 17 00:00:00 2001
From: Hal Blackburn <hwtb2@cam.ac.uk>
Date: Wed, 9 Aug 2023 07:06:08 +0000
Subject: [PATCH] docs: tweak the minimal syntax diagram

It now uses a simpler layout for the optional empty paths, and the type
is explicitly optional.
---
 .../syntax-diagrams/jb_arg_syntax_diagrams.py |  8 ++---
 docs/syntax-diagrams/minimal-argument.svg     | 32 ++++++++++++-------
 2 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/docs/syntax-diagrams/jb_arg_syntax_diagrams.py b/docs/syntax-diagrams/jb_arg_syntax_diagrams.py
index cf4b6b6..7125765 100644
--- a/docs/syntax-diagrams/jb_arg_syntax_diagrams.py
+++ b/docs/syntax-diagrams/jb_arg_syntax_diagrams.py
@@ -160,10 +160,10 @@ def argument() -> DiagramItem:
 
 def minimal_arg() -> DiagramItem:
     """A high-level summary of the argument structure."""
-    return OptionalSequence(
-        NonTerminal("key"),
-        Sequence(":", NonTerminal("type")),
-        Sequence(Choice(0, "=", "@"), NonTerminal("value")),
+    return Sequence(
+        Optional(NonTerminal("key")),
+        Choice(0, Sequence(":", Optional(NonTerminal("type"))), Skip()),
+        Optional(Sequence(Choice(0, "=", "@"), NonTerminal("value"))),
     )
 
 
diff --git a/docs/syntax-diagrams/minimal-argument.svg b/docs/syntax-diagrams/minimal-argument.svg
index 320421e..0f358cb 100644
--- a/docs/syntax-diagrams/minimal-argument.svg
+++ b/docs/syntax-diagrams/minimal-argument.svg
@@ -1,17 +1,25 @@
-<svg class="railroad-diagram" height="109" viewBox="0 0 469.0 109" width="469.0" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<svg class="railroad-diagram" height="101" viewBox="0 0 539.0 101" width="539.0" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
 <g transform="translate(.5 .5)">
 <g>
-<path d="M20 30v20m0 -10h20" /></g><g>
-<path d="M40 40h0" /><path d="M429.0 40h0" /><path d="M40.0 40a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10h45.5a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10" /><path d="M40.0 40h20" /><g class="non-terminal ">
-<path d="M60.0 40h0.0" /><path d="M105.5 40h0.0" /><rect height="22" width="45.5" x="60" y="29"></rect><text x="82.75" y="44">key</text></g><path d="M105.5 20h142.5a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10" /><path d="M105.5 40h20" /><g>
-<path d="M125.5 40h0.0" /><path d="M228.0 40h0.0" /><g class="terminal ">
-<path d="M125.5 40h0.0" /><path d="M154.0 40h0.0" /><rect height="22" rx="10" ry="10" width="28.5" x="125.5" y="29"></rect><text x="139.75" y="44">:</text></g><path d="M154.0 40h10" /><path d="M164.0 40h10" /><g class="non-terminal ">
-<path d="M174.0 40h0.0" /><path d="M228.0 40h0.0" /><rect height="22" width="54" x="174" y="29"></rect><text x="201" y="44">type</text></g></g><path d="M228.0 40h20" /><path d="M105.5 40a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10h102.5a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10" /><path d="M248.0 40h20" /><g>
-<path d="M268.0 40h0.0" /><path d="M409.0 40h0.0" /><g>
-<path d="M268.0 40h0.0" /><path d="M336.5 40h0.0" /><path d="M268.0 40h20" /><g class="terminal ">
-<path d="M288.0 40h0.0" /><path d="M316.5 40h0.0" /><rect height="22" rx="10" ry="10" width="28.5" x="288" y="29"></rect><text x="302.25" y="44">=</text></g><path d="M316.5 40h20" /><path d="M268.0 40a10 10 0 0 1 10 10v10a10 10 0 0 0 10 10" /><g class="terminal ">
-<path d="M288.0 70h0.0" /><path d="M316.5 70h0.0" /><rect height="22" rx="10" ry="10" width="28.5" x="288" y="59"></rect><text x="302.25" y="74">@</text></g><path d="M316.5 70a10 10 0 0 0 10 -10v-10a10 10 0 0 1 10 -10" /></g><path d="M336.5 40h10" /><g class="non-terminal ">
-<path d="M346.5 40h0.0" /><path d="M409.0 40h0.0" /><rect height="22" width="62.5" x="346.5" y="29"></rect><text x="377.75" y="44">value</text></g></g><path d="M409.0 40h20" /><path d="M248.0 40a10 10 0 0 1 10 10v29a10 10 0 0 0 10 10h141.0a10 10 0 0 0 10 -10v-29a10 10 0 0 1 10 -10" /></g><path d="M 429.0 40 h 20 m 0 -10 v 20"></path></g><style>/* <![CDATA[ */
+<path d="M20 30v20m0 -10h20" /></g><path d="M40 40h10" /><g>
+<path d="M50 40h0.0" /><path d="M489.0 40h0.0" /><g>
+<path d="M50.0 40h0.0" /><path d="M135.5 40h0.0" /><path d="M50.0 40a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10" /><g>
+<path d="M70.0 20h45.5" /></g><path d="M115.5 20a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10" /><path d="M50.0 40h20" /><g class="non-terminal ">
+<path d="M70.0 40h0.0" /><path d="M115.5 40h0.0" /><rect height="22" width="45.5" x="70" y="29"></rect><text x="92.75" y="44">key</text></g><path d="M115.5 40h20" /></g><g>
+<path d="M135.5 40h0.0" /><path d="M308.0 40h0.0" /><path d="M135.5 40h20" /><g>
+<path d="M155.5 40h0.0" /><path d="M288.0 40h0.0" /><g class="terminal ">
+<path d="M155.5 40h0.0" /><path d="M184.0 40h0.0" /><rect height="22" rx="10" ry="10" width="28.5" x="155.5" y="29"></rect><text x="169.75" y="44">:</text></g><path d="M184.0 40h10" /><g>
+<path d="M194.0 40h0.0" /><path d="M288.0 40h0.0" /><path d="M194.0 40a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10" /><g>
+<path d="M214.0 20h54.0" /></g><path d="M268.0 20a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10" /><path d="M194.0 40h20" /><g class="non-terminal ">
+<path d="M214.0 40h0.0" /><path d="M268.0 40h0.0" /><rect height="22" width="54" x="214" y="29"></rect><text x="241" y="44">type</text></g><path d="M268.0 40h20" /></g></g><path d="M288.0 40h20" /><path d="M135.5 40a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10" /><g>
+<path d="M155.5 60h132.5" /></g><path d="M288.0 60a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10" /></g><g>
+<path d="M308.0 40h0.0" /><path d="M489.0 40h0.0" /><path d="M308.0 40a10 10 0 0 0 10 -10v0a10 10 0 0 1 10 -10" /><g>
+<path d="M328.0 20h141.0" /></g><path d="M469.0 20a10 10 0 0 1 10 10v0a10 10 0 0 0 10 10" /><path d="M308.0 40h20" /><g>
+<path d="M328.0 40h0.0" /><path d="M469.0 40h0.0" /><g>
+<path d="M328.0 40h0.0" /><path d="M396.5 40h0.0" /><path d="M328.0 40h20" /><g class="terminal ">
+<path d="M348.0 40h0.0" /><path d="M376.5 40h0.0" /><rect height="22" rx="10" ry="10" width="28.5" x="348" y="29"></rect><text x="362.25" y="44">=</text></g><path d="M376.5 40h20" /><path d="M328.0 40a10 10 0 0 1 10 10v10a10 10 0 0 0 10 10" /><g class="terminal ">
+<path d="M348.0 70h0.0" /><path d="M376.5 70h0.0" /><rect height="22" rx="10" ry="10" width="28.5" x="348" y="59"></rect><text x="362.25" y="74">@</text></g><path d="M376.5 70a10 10 0 0 0 10 -10v-10a10 10 0 0 1 10 -10" /></g><path d="M396.5 40h10" /><g class="non-terminal ">
+<path d="M406.5 40h0.0" /><path d="M469.0 40h0.0" /><rect height="22" width="62.5" x="406.5" y="29"></rect><text x="437.75" y="44">value</text></g></g><path d="M469.0 40h20" /></g></g><path d="M489.0 40h10" /><path d="M 499.0 40 h 20 m 0 -10 v 20"></path></g><style>/* <![CDATA[ */
 :root {
   --line-colour: rgb(48 48 48);
   --line-width: 2px;