figdown 0.1.7 → 0.2.0

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

@@ -3,14 +3,25 @@
 The genre itself is outside the v0.1 conformance surface: it may change or be
 withdrawn in a later `0.x`. A portable figure uses `block` instead.
 
-Load `../scene.md` first — `flowchart` reuses the whole scene vocabulary
-(`node`, `group`, `external`, `edge`, `flow`, `rank`) with the same meanings,
-and adds the three role keywords below. `flow down` is the default here.
+Load `../scene.md` first — `flowchart` reuses the scene vocabulary
+(`node`, `group`, `external`, `flow`, `rank`) with the same meanings, and adds
+the three role keywords below. `flow down` is the default here.
 
-## Three role keywords
+**Under `figdown 0.2` the connector is `flowline`, not `edge`** — ISO 5807's
+own word for a flowchart's connecting line. Same operators, same labels, same
+option keys, same model; only the word changed.
+
+**The spelling is gated by the version you declare.** Under
+`figdown 0.1 flowchart`, `edge` is still the word and `flowline` is a line
+error naming the version; under `figdown 0.2 flowchart` it is the other way
+round. Each version accepts exactly one spelling — two in one version would be
+an alias. A document that writes `flowline` must declare `figdown 0.2`, and
+`edge` under 0.1 stays legal until v1.0.
+
+## Three role keywords, and when to write `node` instead
 
 ```figdown
-figdown 0.1 flowchart
+figdown 0.2 flowchart
 flow down
 terminator start "Request received"
 process parse "Parse body"
@@ -19,13 +30,13 @@ process apply "Apply change"
 process reject "Reject"
 terminator done "Response sent"
 node log "Audit store" shape=cylinder
-edge start -> parse
-edge parse -> valid
-edge valid -[yes]-> apply
-edge valid -[no]-> reject
-edge apply -> done
-edge reject -> log
-edge log -> parse
+flowline start -> parse
+flowline parse -> valid
+flowline valid -[yes]-> apply
+flowline valid -[no]-> reject
+flowline apply -> done
+flowline reject -> log
+flowline log -> parse
 decision kind "Change kind?" shape=ellipse
 ```
 
@@ -44,13 +55,43 @@ wrong roughly one time in five.
 model still records the role. That is the escape hatch for matching a source
 drawing without lying about what the step is.
 
-**A bare `node` under `flowchart` states no role, and that is often correct.**
-Do not "upgrade" one to `process` unless it really is a step — a datastore, a
-wait, or an annotation is none of the three, and claiming a role would be a
-lie the reader cannot detect.
+**Prefer a role. `node` is the fallback, not the default.** Reach for
+`process`, `decision` or `terminator` first, and write `node` only when **the
+source does not state which** the stage is.
+
+That is what a bare `node` says here, and it is all it says: *the source does
+not state the role.* ISO 5807 is a standard for **drawing** flowcharts, so it
+has no "unclassified" — the person with the pen must draw some symbol, and
+every drawn stage therefore has a classification. FigDown separates role from
+geometry, so it can record the absence instead of inventing a role. A
+transcriber who genuinely cannot tell a Process from a Predefined process
+writes `node`, and that is the honest line.
+
+**`node` is NOT the spelling for "an ISO symbol FigDown has not implemented."**
+Nine ISO stage symbols have no word in this genre — Data (input/output),
+Stored data, Predefined process, Preparation, Manual operation, Manual input,
+Document, Parallel mode, Loop limit. That is a **gap in FigDown**, not a fact
+about your figure, and writing a bare `node` for one of them files the gap as
+if it were your judgement. When your source states a role this genre cannot
+spell:
+
+- write `node` — `process` would be a false claim, and nothing in the figure
+  could catch it;
+- **name the ISO symbol in a comment** on the same line, so the classification
+  survives as text a reader can quote (a comment is never parsed, and never a
+  second semantic channel);
+- report the gap, so it can be counted and closed.
+
+```figdown
+node cfg "Read config file"   # ISO 5807 Data (input/output) — no FigDown role
+```
+
+So do not "upgrade" a `node` to `process` to make it look decided — and do not
+write `node` because deciding was work. Those are different acts with the same
+spelling, and only you know which one you did.
 
 **Label every exit from a `decision`.** Use the on-line label form
-(`edge d -[yes]-> x`) or an endpoint label; an unlabelled branch is a figure
-the reader has to guess at.
+(`flowline d -[yes]-> x`) or an endpoint label; an unlabelled branch is a
+figure the reader has to guess at.
 
 **There is no loop keyword.** A plain back-edge *is* the loop.

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

@@ -0,0 +1,92 @@
+# Genre `statechart` — EXPERIMENTAL / EXPERIMENTAL
+
+The genre itself is outside the conformance surface: it may change or be
+**withdrawn** in a later `0.x` without a migration. A portable figure uses
+`block` instead — that is what these figures were spelled as before `figdown
+0.2`, and the rewrite back is one line.
+
+**It needs `figdown 0.2` on line 1.** `figdown 0.1 statechart` is a line
+error, and a deliberately named one: `genre "statechart" requires figdown 0.2`.
+An engine may not read a `0.1` document as though it were `0.2`.
+
+Load `../scene.md` first — `statechart` reuses the scene vocabulary
+(`group`, `external`, `class`, `flow`, `rank`) with the same meanings, and
+**renames the other two**: a node is a **`state`** and a connector is a
+**`transition`**, both taken from OMG UML 2.5.1 §14. Nothing else changes —
+same option keys, same id space, same operators, same model — and `node` or
+`edge` here is a **line error** naming the word to write instead.
+
+`flow right` is the default, as in `block`; `flowchart`'s `down` default does
+**not** apply here.
+
+**Why this genre loses `node` and `flowchart` keeps it:** a statechart has
+exactly one kind of node, so there is nothing to leave unstated and `state`
+gives up nothing. A flowchart stage can have a role **the source does not
+state**, and there `node` is the only way to say so without asserting a role
+the source never gave.
+
+```figdown
+figdown 0.2 statechart
+title "Turnstile"
+class mode "A mode of the mechanism" fill=#e0e7ff
+state locked "LOCKED" class=mode
+state unlocked "UNLOCKED" class=mode
+transition locked -[coin]-> unlocked
+transition unlocked -[push]-> locked
+transition locked -[push]-> locked      # self-transition: the event happens
+                                        # and the machine stays
+flow right
+```
+
+## What the genre adds, which is a reading and not a syntax
+
+Everything above parses identically under `block`. The genre earns its
+existence in what you are entitled to conclude from it.
+
+**Under `statechart`, and not under `flowchart` or `block`:**
+
+- **Every top-level `state` is a state** — a *mode the machine is in*, not a
+  step it performs. It has duration; the machine sits in it until something
+  happens.
+- **Every `transition` is a transition**, and its direction is the direction of the
+  change. An undirected `--` between two states asserts a relationship the
+  genre has no reading for; do not read it as a transition in both directions.
+- **A mid label is a transition inscription** — the trigger, and optionally a
+  guard and an effect — as free text. There is no structure in it. Quote it,
+  attribute it to its edge, and stop; you may not parse `event / action` into
+  fields, because nothing in the language promises that shape.
+- **A self-loop is "the event occurs and the machine stays"**, which is a
+  fact about the machine. Under `flowchart` the same drawing is a *poll* —
+  "check again" — and that is a different claim entirely.
+- **The set of states is closed.** The nodes are all the modes the figure
+  asserts; a state not drawn is not asserted to exist.
+
+**Still not conclusible, and the list is the same as everywhere else:**
+
+- **No current state.** Nothing in a figure says which state the machine is
+  in now. A fill colour does not, a `class` does not, position does not.
+- **No initial and no final state.** The language has no vocabulary for
+  either at `figdown 0.2` — deliberately, pending evidence, and **no `start`
+  keyword was added**: ISO's terminator symbol is *both* ends distinguished by
+  its label, so there is no word to borrow, and a reader who lacks one answers
+  "unstated" rather than answering wrongly. A state with no incoming
+  transition is *drawn* that way; it is not *declared* initial, and reading it
+  as initial is inventing a fact.
+- **No ordering among transitions.** Peer edges have no sequence, and an
+  ordinal in a label is naming, not order.
+- **No hierarchy, no regions, no history.** A `group` groups; it does not
+  make a superstate.
+- **Nothing from the layout zone.** `pin` is arrangement for humans; skip it.
+
+**Reclassifying costs more than one line now.** Changing `flowchart` to
+`statechart` on line 1 no longer suffices: every `flowline` becomes a
+`transition` and every `node` a `state`. Run `tools/migrate-figdown.js` — it
+rewrites both, scoped by the header genre.
+
+**Do not upgrade a `flowchart` to a `statechart` on structure.** It was
+measured: cycles do not separate the two (of the state machines and the
+flowcharts in this project's own corpus, both are usually cyclic), and
+self-loops appear in almost none. A retry loop drawn as a flowchart is exactly
+the figure that reads wrong as a statechart. **Only the declared genre says
+which it is** — and a title that contains the words "state machine" does not,
+because a polling flowchart is routinely titled that way.

package/skill/figdown/reference/reading.md

@@ -71,6 +71,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` only). 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 +105,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,11 +1,26 @@
-# Scene genres — `block`, and the vocabulary `topology` / `flowchart` share
+# Scene genres — `block`, and the vocabulary `topology` / `flowchart` / `statechart` share
 
 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.
+the whole scene surface; `topology`, `flowchart` and `statechart` reuse them
+and add — or **rename** — their own, in their own files.
 
 Load this for any figure made of **things and the connections between them**.
 
+**Two of the seven are spelled differently by genre.** Read
+this file for what they *mean*; write the word your genre uses:
+
+| genre | the thing | the line |
+|---|---|---|
+| `block`, `topology` | `node` | `edge` |
+| `flowchart` | `node` | **`flowline`** |
+| `statechart` | **`state`** | **`transition`** |
+
+Each genre takes the term its own domain actually uses — ISO 5807 calls a
+flowchart's connector a *flowline*; UML calls a state machine's arc a
+*transition*. The wrong one is a **line error naming the right one**, never a
+silent acceptance, so you cannot get this wrong without being told. Everything
+else about them — operators, labels, option keys, the model — is identical.
+
 ## The seven keywords
 
 ```figdown