figdown 0.1.8 → 0.3.0

package/skill/figdown/reference/reading.md

@@ -25,6 +25,18 @@ syntax detail in the other files beside it.
 - **Authored prose** in a `description=` is quotable and displayable, and
   **never parsable**. Quote it, attribute it to its field, and stop. It
   carries no structure, no relation and no condition.
+- **A `note=` is authored prose too, on the same terms** (`figdown 0.3`).
+  It is quotable and displayable and **never parsable**. It is an **aside**:
+  its content is not a fact about the figure's structure. You MAY attribute
+  it to the element that carries it — attachment is by syntactic position, so
+  there is never a question of which element is meant — and you MUST NOT
+  infer a participant, an edge or a category from it. A `note=` on `title`
+  (`doc.note`) belongs to the **figure**, not to any element.
+- **`description=` and `note=` are not the same channel and neither replaces
+  the other.** They divide by AUDIENCE: `description=` is written **for you**
+  and puts no ink on the page; `note=` is written for the **human** and always
+  draws. Both may appear in one document, and an element carrying both is
+  making two statements to two readers, not saying one thing twice.
 
 ## Genre-specific readings
 
@@ -71,6 +83,15 @@ Widths, colours and alignment never change it.
 **`timing`.** Cycle *t* is the *t*-th character of the lane. `.` continues
 the previous value, and cycles stay contiguous across a gap.
 
+**`statechart`** (EXPERIMENTAL, `figdown 0.2` and later). Nodes are **states** — modes
+the machine is *in* — and edges are **transitions** on an event. This is the
+one reading you may not derive from the drawing: a cyclic figure with a
+self-loop is just as likely to be a polling `flowchart`, and the word "state
+machine" in a `title` decides nothing. Only line 1 decides. What you may and
+may not conclude is in `experimental/statechart.md`; the short version is that
+there is no current state, no initial state and no final state in the
+language, so reading any of the three out of a figure is invention.
+
 ## What you MUST NOT infer
 
 - **Ignore the layout zone.** Everything from the `layout` keyword down is
@@ -96,7 +117,10 @@ the previous value, and cycles stay contiguous across a gap.
 - **A keyword's meaning is relative to its genre.** Line 1 names the
   namespace. Never carry a reading from one genre into another, and read a
   nested region under **its** genre, not its host's. Multi-section files give
-  each section its own genre. The permanent exceptions: `figdown`, `title`,
+  each section its own genre — **and its own language version**; the two
+  numbers on a section's header line are that section's whole contract, and
+  one file may legitimately carry sections at different versions. The
+  permanent exceptions: `figdown`, `title`,
   `layout` and `pin` mean the same thing everywhere — which is exactly what
   lets you skip the layout zone without first knowing the genre.
 - **A shared `class` is a shared category, not an identity.** The language

package/skill/figdown/reference/scene.md

@@ -1,12 +1,37 @@
-# Scene genres — `block`, and the vocabulary `topology` / `flowchart` share
+# Genre `block` — things and the connections between them
 
-Status: `block` is NORMATIVE and portable. The same seven keywords are
-the whole scene surface; `topology` and `flowchart` reuse them and add their
-own, in their own files.
+Status: NORMATIVE and portable.
 
-Load this for any figure made of **things and the connections between them**.
+Load this for any figure made of **things and the connections between
+them** whose line 1 says `block`. Everything below is `block`'s own
+vocabulary; nothing below is authority for any other genre.
 
-## The seven keywords
+**Every scene genre declares its own words.** There are four, and each one's
+vocabulary is declared once, in its own file:
+
+| genre on line 1 | where its vocabulary is declared |
+|---|---|
+| `block` | this file |
+| `topology` | `experimental/topology.md` |
+| `flowchart` | `experimental/flowchart.md` |
+| `statechart` | `experimental/statechart.md` |
+
+A word two of them spell the same is **two declarations that happen to agree
+today**, never one inherited — each genre may withdraw, rename or constrain
+its own without touching the others, and each carries its own reading advice
+because the same word can be safe in one domain and misleading in another.
+So do not carry a word from this file into another genre and do not go
+looking here for a word another genre's file did not give you: a word the
+genre on line 1 does not declare is a **line error that states the ground**,
+not a spellcheck.
+
+Three words are spelled the same in all four and are not subject vocabulary
+at all — `class` says what a colour *means*, `flow` and `rank` state layout
+intent. None of them names a thing in the world, so no domain holds a rival
+meaning for one, and each genre's file repeats them rather than sending you
+here.
+
+## The vocabulary, in one figure
 
 ```figdown
 figdown 0.1 block
@@ -52,8 +77,8 @@ edge retry -> reject class=slow
 `flow` takes `flow right|down|left|up` — one of the four, once per document.
 
 Values from a fixed list are written **bare**, never quoted: `shape=box`,
-`style=dashed`, `flow down`, `plane=over`. So are ids. Labels are the
-opposite and always take quotes.
+`style=dashed`, `flow down`, `gap=0`. So are ids. Labels are the opposite
+and always take quotes.
 
 `shape=` is **pure geometry, no domain nouns** — `shape=box` (the default),
 `shape=rounded`, `shape=circle`, `shape=ellipse`, `shape=diamond`,
@@ -67,6 +92,26 @@ inside a bracket label is ordinary text and needs no quotes —
 `edge a -[hop #1]-> b` — because `[ ]` is a verbatim region, like a quoted
 string, a comment and a pipe row.
 
+## What `group` and `external` claim here, and what they do not
+
+`block` is the **general-purpose** genre: it has no single domain, and that
+is what general-purpose means. So its two container-and-boundary words carry
+no domain caveat, and you should not supply one.
+
+- **`group`** is a container and nothing more — a box drawn round its
+  members, one nesting level deep. It asserts no ownership, no lifecycle, no
+  address space and no failure domain. Whatever the grouping *means* goes in
+  the label.
+- **`external`** is an out-of-figure endpoint: something the figure talks to
+  but does not describe. It is **never drawn** — the edge simply ends open —
+  it takes **no option key at all**, and there is no source standard behind
+  the spelling. It is FigDown's own word for FigDown's own boundary.
+
+A genre with one domain cannot be this quiet. `topology`'s file has to warn
+its reader off a rival reading of both words before it can use either; this
+file has nothing to warn about, and that asymmetry is why the two
+declarations are separate.
+
 ## Field-tested pitfalls
 
 **Containment is not an edge.** An edge from a node to its own container
@@ -114,5 +159,28 @@ a `node` styled to look like one.
 ## Where to go next
 
 - The figure came out scrambled, or placement is the message → `layout.md`
-- Marker lines, zone bands, link bundles, overlay planes, charts →
-  `experimental/constructs.md` (EXPERIMENTAL)
+- Marker lines and zone bands over a `block` figure →
+  `experimental/block.md` (EXPERIMENTAL)
+- Bars drawn from a `table` region → `experimental/chart.md` (EXPERIMENTAL)
+
+## The drawn annotation — `note=` (`figdown 0.3`)
+
+`note=` is an **attribute on the annotated element's own line**, and the
+element it is about is the element it is written on: `node a "A" note="…"`,
+`group g "G" note="…"`, `edge a -> b note="…"`, `title "T" note="…"`.
+There is no id, no target key and no locator, so there is never a question
+of which of several identically-labelled elements is meant.
+
+**What you may conclude.** The text is authored prose — quotable,
+displayable, **never parsable**. It is an aside about the element, not a
+fact about the figure's structure. Attribute it to its carrier and stop;
+do not infer a participant, an edge or a category from it. A `note=` on
+`title` is about the **figure** and about no element.
+
+**What it is not.** It is not `description=`. The two divide by AUDIENCE:
+`description=` is machine-facing and draws nothing beyond an SVG `<title>`;
+`note=` is human-facing and always draws. And **where a typed slot exists,
+a note is never where the fact lives** — a category is a `class` meaning, a
+containment is `in=`, a direction is the operator. If a note's text looks
+like structure, it is still prose: read the structure off the construct that
+states it.

package/skill/figdown/reference/experimental/constructs.md

@@ -1,90 +0,0 @@
-# EXPERIMENTAL / EXPERIMENTAL constructs
-
-Everything in this file is **outside the v0.1 conformance surface and outside
-the compatibility promise**. The engine accepts it and your document keeps
-working, but it may change or be withdrawn in a later `0.x`. The parser emits
-no warning, so a line that parses tells you nothing.
-
-Use these when the figure genuinely needs them. If the figure must be
-portable, do not — and if you use one anyway, say so beside the figure.
-
-## Markers and zones — `threshold`, `band`
-
-```figdown
-figdown 0.1 block
-group pool "Storage pool"
-node used "In use" in=pool
-threshold "High watermark = stop writes" in=pool offset=80%
-threshold "Low watermark = resume writes" in=pool offset=45%
-band "Reserved" 15% in=pool fill=#fee2e2
-band "Shared quota" 20..70% in=pool extend=down
-```
-
-- `threshold` needs a quoted label **and** `offset=<0..100>%`, both mandatory
-  — the `%` included. There is no `value=` and no `ref=`.
-- `band` needs a quoted label **first**, then either one percentage (a size)
-  or an explicit `<a>..<b>%` range. `..` is the language's ONE range
-  separator; the hyphen form is a line error. `extend=up|down|left|right`, and `up`
-  is the default.
-- The label is the knowledge in both cases. `offset=` is a fraction of the
-  target's rendered extent, **not a value of any quantity** — the target
-  declares no scale, so there is no conversion. Put the number in the label
-  or it is not in the document.
-- Both attach to a node or a group via `in=`.
-- **Attach at the scope the fact belongs to.** A limit shared by everything in
-  a group is one group-level marker; a fact true of one element attaches to
-  that element. The renderer may draw the two the same way — the difference is
-  in the text, and the text is the knowledge.
-
-## Link bundles — `bundle`
-
-```figdown
-figdown 0.1 block
-node leaf "Leaf"
-node s1 "Spine 1"
-node s2 "Spine 2"
-edge leaf -- s1
-edge leaf -- s2
-bundle ecmp "ECMP uplink set (2 × 100G)" leaf--s1,leaf--s2
-```
-
-Names a set of already-declared edges as one logical link. The dashed ring is
-drawn for you, and the member list is one comma-delimited token. Each member
-must name an edge that already exists and is unambiguous — v0.1 has no way to
-address one of two parallel edges between the same pair, so a bundle over
-parallel links cannot be spelled.
-
-## Overlay planes — `plane`, `plane=`
-
-```figdown
-figdown 0.1 block
-plane overlay "VXLAN tunnels" z-index=2
-node l1 "Leaf 1"
-node l2 "Leaf 2"
-node s1 "Spine" plane=overlay
-edge l1 <-> l2 plane=overlay
-```
-
-The **label is the knowledge** — "VXLAN tunnels" is what a reader keeps, not
-the paint order. Every document has an implicit `base` plane at `z-index=0`,
-and every element reports it unless it names another. An omitted `z-index=`
-takes the plane's 1-based declaration index. `z-index=` reorders the
-annotation pass only — edges, bundle rings, thresholds and bands. `plane=` is
-legal on a node, group, external endpoint, edge, class, bundle, threshold and
-band.
-
-## Charts from a table — `chart`, `type=`
-
-```figdown
-figdown 0.1 table
-table t "Throughput"
-| Port | Gbps |
-|------|------|
-| 1    | 25   |
-| 2    | 40   |
-chart t type=bar3d
-```
-
-Draws bars from a table's numeric cells. `type=` is the only option key and
-`bar3d` is its only value. For anything a chart library would do better, keep
-the raster and put the numbers in a table (`../transcribe.md`).