figdown 0.3.2 → 0.4.0

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

@@ -166,10 +166,12 @@ flowline check -> accept class=yes
 flowline check -> reject class=no
 ```
 
-A class a flowline joins MUST declare `stroke=` or `style=`; a `fill=`-only
-class joined by one is an error naming `stroke=`. `fill=` and `stroke=` are
-legal on any drawn element, but a flowline has no interior, so `fill=` on one
-is an error.
+A class a flowline joins MUST NOT declare `fill=` with no `stroke=`: that is
+an error naming `stroke=`. A class that declares **no paint at all** is
+legal — it claims a meaning, draws it in the derived legend with no swatch,
+and leaves the flowline its default line. `fill=` and `stroke=` are legal on
+any drawn element, but a flowline has no interior, so `fill=` on one is an
+error.
 
 The connector's operators are `->`, `<-`, `--` and `<->`. In a procedure you
 almost always want `->`: a step follows another step in one direction, and an

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

@@ -0,0 +1,252 @@
+# Genre `sequence` — EXPERIMENTAL
+
+The genre is outside the conformance surface: it may change or be
+**withdrawn** in a later `0.x` without a migration. There is no portable
+rewrite of a sequence figure — a scene genre cannot carry time order — so a
+figure written here is written here.
+
+**It draws a ladder.** Participants are columns, left to right in `lifeline`
+declaration order; time runs down the page, one row per `message` or `state`
+in the order you wrote them. A `fragment` is a frame around the rows that
+name it, with its operator in a tab at the top-left corner; an `operand` is a
+compartment of that frame, as wide as the frame, divided from the one above
+by a dashed rule, with its guard drawn `[in brackets]` at the left; a `state`
+is a pill centred on its own column. A message to and from the same lifeline
+draws a small rectangular loop; a message between non-adjacent columns is one
+straight shaft over the lifelines it crosses, which are left intact; `<->`
+draws ONE shaft with two heads, because it is one message and not two.
+
+**You place nothing.** This genre has no key that moves a coordinate — not
+`flow`, not `rank`, not a position. `layout` and `pin` still parse, because
+they are the language's and no genre may redefine them, and a `pin` here
+changes nothing at all: the drawing is identical with and without it.
+Everything you can change about the figure, you change by changing what the
+source SAYS.
+
+**There are no activation bars.** UML draws a bar for the period a
+participant is executing; that is a different thing from a message, this
+genre has no word for it, and the renderer will not invent one out of which
+messages happen to be adjacent.
+
+**It needs `figdown 0.4` on line 1.** `figdown 0.3 sequence` is a line error,
+and a deliberately named one: `genre "sequence" requires figdown 0.4`.
+
+## The vocabulary, which is five words
+
+**This file is `sequence`'s whole vocabulary.** Load it and you can author in
+this genre; do not load another genre's file, because another genre's
+declaration of a word is not authority for this one.
+
+| Line | What it declares |
+|---|---|
+| `lifeline <id> ["label"]` | a participant column — this genre's word for a node |
+| `message <a> -> <b> ["label"]` | one message from `<a>` to `<b>` — this genre's word for a connector |
+| `state <lifeline-id> "<state name>"` | the named state a lifeline is in from here on |
+| `fragment <id> ["label"] type=<operator>` | a combined fragment — a framed region of the exchange |
+| `operand <id> ["guard"] in=<fragment-id>` | one compartment of a fragment |
+
+All five are taken from OMG UML 2.5.1 clause 17, which is this genre's source
+standard, and every one of them is published by ISO as well, in ISO/IEC
+19505-2 clause 14. Three more words are legal because they are not about
+exchanges at all: `class` (what a colour means), `title`, and `layout`/`pin`
+— though a `pin` has nothing to place here.
+
+**`flow` and `rank` are NOT this genre's keywords**, and that is a
+consequence rather than an omission: both axes are already ordered by the
+source. Columns are in `lifeline` declaration order; time runs down the page
+in the order the `message` and `state` lines are written. A key that
+reordered either would make the drawing disagree with the text.
+
+**A `bitfield`, `table` or `timing` region cannot be opened here either.** A
+scene genre can host one because it has a scene to host it in; a ladder has
+no scene, so those three openers are line errors under `sequence`. Put the
+companion table in its own section with its own header line.
+
+## Order is declaration order, and it is TOTAL
+
+The figure's time axis is the `message` and `state` lines **in the order you
+wrote them**. There is one order, it is total, and every reader gets the same
+one. UML and ITU-T Z.120 both define a *partial* order — total along each
+participant's own axis only, with cross-participant order coming from the
+messages themselves. FigDown asserts more than either, deliberately, so that
+one source never admits two equally legal drawings and a reader never has to
+compute an ordering. **Write the lines in the order the events happen.**
+
+The one way to say that two messages are NOT ordered is a `par` fragment
+around them. That makes `type=par` part of the order model rather than a
+convenience: without it, adjacent means earlier-than, always.
+
+## `message`: three operators, and `--` is an error
+
+```figdown
+figdown 0.4 sequence
+lifeline c "Client"
+lifeline s "Server"
+message c -> s "DHCPDISCOVER"
+message c <- s "DHCPOFFER"
+message c <-> s "keepalive"
+```
+
+`->` and `<-` give the direction; `<->` is a sustained two-way exchange whose
+individual messages are not enumerated — one message, drawn with one shaft
+and two heads. **`--` is a line error here** and legal in every other genre:
+a message has a sending event and a receiving event, so one with no direction
+is not a thing this domain has.
+
+The trailing quoted string is the message text, and it is where to write it.
+The shared connector grammar also accepts a label in the inline bracket
+position — `message c -[DHCPDISCOVER]-> s` — and both spellings reach the
+same one field, so **writing both on one line is a line error**. Prefer the
+trailing form; the bracket position reads as an annotation on the line rather
+than as the message itself. `[tail]` and `[head]` are a different thing and
+are unaffected: they label the two ends, not the message.
+
+Both endpoints must be declared `lifeline` ids.
+
+## `state`: slot 1 REFERENCES a lifeline
+
+```figdown
+figdown 0.4 sequence
+lifeline c "Client"
+state c "BOUND"
+```
+
+This is the one place a word means something different from what it means in
+another genre. Under `statechart`, `state locked "LOCKED"` **declares** the id
+`locked`. Under `sequence`, `state c "BOUND"` **references** the lifeline `c`
+and declares nothing: nothing here refers to a state occurrence, so it needs no
+id of its own. The quoted name is **mandatory** — a state occurrence with no
+name asserts nothing.
+
+Two consecutive `state` lines naming the same lifeline and the same name are a
+line error: a state that has not changed is never restated.
+
+## `fragment` and `operand`: `type=` is mandatory
+
+```figdown
+figdown 0.4 sequence
+lifeline c "Client"
+lifeline s "Server"
+fragment renew "renewal cycle" type=loop
+operand t1 "while the lease is live" in=renew
+message c -> s "DHCPREQUEST" in=t1
+```
+
+`type=` takes one of **twelve** values, bare, taken whole from UML's
+`InteractionOperatorKind`:
+
+`alt` `opt` `loop` `par` `strict` `seq` `critical` `neg` `assert` `ignore`
+`consider` `break`
+
+There is **no default**. UML gives the attribute one (`seq`) and FigDown does
+not, because a default draws a frame that looks like an assertion and is not
+one. An `operand` is a compartment **of** a fragment, so its `in=` is
+mandatory, and its quoted string is the guard. A fragment or an operand with
+no members is a line error: a container's extent is the span of the lines
+that name it, and a container with no extent asserts nothing.
+
+## `in=`: five acceptors, one meaning, one level
+
+`in=` means *the element this one lives inside*, and its value is always a
+`fragment` or an `operand` id. It is accepted on **`message`, `operand`,
+`lifeline`, `state` and `fragment`** — five acceptors, all the same meaning.
+An `operand`'s `in=` is narrower still: a compartment belongs to a FRAGMENT,
+never to another compartment.
+
+Three rules come with it:
+
+- **Members must be CONTIGUOUS** in declaration order. An operand denotes the
+  ordered run of the occurrences it contains, so an occurrence that is not in
+  it cannot happen between two that are. A line that splits a run is a line
+  error naming the run.
+- **Fragment nesting is capped at ONE level.** A fragment may sit in an
+  operand of one enclosing fragment and no deeper. Write a deeper interaction
+  as a sibling fragment, or state it in `description=`.
+- **Containment is a tree.** A container that ends up inside itself is a line
+  error, because a cycle denotes nothing.
+
+## Three things this genre refuses, and what to write instead
+
+Each is a line error with a named diagnostic — the engine tells you the ground
+and the replacement. They are listed here so you do not reach for them.
+
+- **`gap` — refused.** The vertical axis is not proportional: non-zero time has
+  already passed between every adjacent pair of events, so the line would say
+  nothing new, and *draw it further apart* is a rendering request. Put the
+  elapsed time into the following message's label or its `description=`.
+- **`group` — refused.** UML clause 17 has no lifeline-grouping construct, and
+  a band across a column span would silently enclose non-members. Declare a
+  `class` naming what the participants have in common and put `class=` on each
+  `lifeline`: it asserts membership without asserting adjacency, and it earns a
+  legend entry.
+- **`lost=` — refused, and no option key was added for it.** For a message that
+  was sent and not delivered, declare `class dropped "Sent, never delivered"`,
+  put `class=dropped` on the message, and put the per-message reason in
+  `description=`.
+
+## A whole document
+
+```figdown
+figdown 0.4 sequence
+title "Address lease and renewal"
+class dropped "Sent, never delivered" stroke=#b91c1c style=dashed
+lifeline c "DHCP client"
+lifeline s "DHCP server"
+message c -> s "DHCPDISCOVER"
+message c <- s "DHCPOFFER"
+state c "BOUND"
+fragment renew "renewal cycle" type=loop
+operand t1 "when the renewal timer fires" in=renew
+message c -> s "DHCPREQUEST" in=t1 class=dropped description="the issuing server does not answer"
+state c "RENEWING" in=t1
+```
+
+Presentation is the same everywhere: `fill=` the interior, `stroke=` the
+outline and the whole of a line, `class=` one or more declared class ids
+comma-separated, and `style=solid|dashed|dotted` for the dash pattern.
+`fill=` is an error on a `message`, on a `fragment` and on an `operand` — a
+line has no interior, and a frame drawn over messages must not hide them.
+`shape=` is accepted by nothing here: every shape in the ladder is the
+engine's. `note=` is a drawn aside in prose and `description=` is authored
+documentation that is never drawn; neither is where a structural fact lives.
+A `fill=`-only class joined by a `message`, a `fragment` or an `operand` is a
+**line error**: a line has no interior, so that class reaches nothing on it —
+write `stroke=`. (This was accepted, when the check ran over
+`edge`s only; it reaches every collection that takes `class=`.) A class that declares **no paint at all** is legal on any
+member and always was here: it draws its meaning in the derived legend with
+no swatch, which is what `class dropped "Sent, never delivered"` does in the
+reference figure. Read a paint-less class as a claim about MEANING, never as
+a missing colour.
+
+## What you may conclude from a `sequence` figure
+
+- **Every `message` is a message**, its direction is the direction it travels,
+  and its position in the source is its position in time.
+- **The order is total.** Two messages written one after the other happened in
+  that order.
+- **`<->` is ONE message**, an exchange in both directions whose individual
+  messages are not enumerated — never a count of two.
+- **The set of participants is closed.** A participant not declared is not
+  asserted to exist. Column position is declaration order and means nothing
+  else: not seniority, not layering, not a path.
+- **A `state` line is the condition its lifeline is in from that point on**,
+  as free text — quotable, attributable, never parsable.
+- **A `fragment` says what KIND of run its members are**, and its `type=` is
+  that claim; an `operand`'s quoted string is the guard on that compartment.
+
+**Still not conclusible:**
+
+- **No elapsed time, ever.** Vertical distance means only that non-zero time
+  passed. There is no duration, no timestamp and no rate in this genre.
+- **No concurrency unless a `par` fragment says so.** Two adjacent messages are
+  ordered, not simultaneous.
+- **No failure, no retransmission and no loss** unless a `class` says so in
+  words. There is no keyword for any of them, and a `class` meaning is prose:
+  attribute it to the prose, not to the model.
+- **No activation, no execution period, no "busy".** Nothing is drawn for it
+  and nothing may be inferred from message adjacency.
+- **No identity** between two messages with the same label, and none between a
+  state name here and a state in a statechart document. A shared `class` is a
+  shared category, never a shared identity.
+- **Nothing from the layout zone.** Here that rule is total rather than
+  conventional: a `pin` changes no coordinate, because there is none to change.

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

@@ -79,9 +79,11 @@ spaces. Values from a fixed list are bare (`shape=box`, `style=dashed`,
 `shape=` is pure geometry and changes only the drawing — `shape=box` (the
 default), `shape=rounded`, `shape=circle`, `shape=ellipse`, `shape=diamond`,
 `shape=cylinder`. `style=` takes `style=solid`, `style=dashed` or
-`style=dotted`. A class a transition joins MUST declare `stroke=` or
-`style=`; `fill=` on a transition is an error, because a line has no
-interior. Under `figdown 0.3` a line may carry `note=`, a drawn aside in
+`style=dotted`. A class a transition joins MUST NOT declare `fill=` with no
+`stroke=` — that is an error naming `stroke=`; a class that declares **no
+paint at all** is legal and claims only a meaning, which the derived legend
+draws with no swatch. `fill=` on a transition is an error, because a line has
+no interior. Under `figdown 0.3` a line may carry `note=`, a drawn aside in
 prose — never parsable, never where a structural fact lives.
 
 ## What the genre adds, which is a reading and not a syntax

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

@@ -73,10 +73,12 @@ with what it *is* — "the internet", "the transit provider" — written in the
 label. `style=` takes `style=solid`, `style=dashed` or `style=dotted`.
 
 `class` declares what a colour **means** and is the only way to make colour
-carry meaning; a class an edge joins MUST declare `stroke=` or `style=`, and
-a `fill=`-only class joined by an edge is an error naming `stroke=`. `fill=`
-and `stroke=` are legal on any element, but an `edge` has no interior, so
-`fill=` on one is an error.
+carry meaning; a class an edge joins MUST NOT declare `fill=` with no
+`stroke=` — that is an error naming `stroke=`. A class that declares **no
+paint at all** is legal: it claims a meaning, draws it in the derived legend
+with no swatch, and leaves the edge its default line. `fill=` and `stroke=`
+are legal on any element, but an `edge` has no interior, so `fill=` on one is
+an error.
 
 Endpoint labels nest (`edge a [xe-0/0/0:1] -- b`); quote them when they hold
 a line break or an unbalanced bracket (`edge a ["slot\n1/1"] -- b`). A `#`

package/skill/figdown/reference/reading.md

@@ -94,14 +94,19 @@ 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
-  geometry, it exists only to stabilise the SVG, and no keyword turns this on
-  or off. *(One exception, and it is a workaround for a missing construct:
-  if the layout looks load-bearing — dense pins forming a stack, a grid or a
-  map, where stack order, cross-layer alignment or spans are the point —
-  read it, and say in your summary that you did. Such a document has a
-  semantics gap.)* A document with no `layout` line may use an older
-  `# --- layout` comment as an informal boundary.
+- **Ignore the layout namespace.** Its one member today is `pin`. Ignore every
+  member **wherever it appears** — membership decides, never position. A `pin`
+  written *before* the `layout` line is ignored on exactly the same terms as
+  one written after it, and about half of them are written before it. The
+  members are geometry, they exist only to stabilise the SVG, and no keyword
+  turns this on or off. *(One exception, and it is a workaround for a missing
+  construct: if the layout looks load-bearing — dense pins forming a stack, a
+  grid or a map, where stack order, cross-layer alignment or spans are the
+  point — read it, and say in your summary that you did. Such a document has a
+  semantics gap.)* The `layout` line, and an older `# --- layout` comment in a
+  document that has no `layout` line, are a **reader's signpost** and not the
+  test: they say where the author collected the geometry, which is useful and
+  is not what decides.
 - **Arrangement is not precedence.** Declaration order records the author's
   statement order — a focus and reading-order signal. It is not a ranking, a
   priority or a sequence.
@@ -122,7 +127,7 @@ language, so reading any of the three out of a figure is invention.
   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.
+  lets you skip the layout namespace without first knowing the genre.
 - **A shared `class` is a shared category, not an identity.** The language
   has no equivalence or alias relation.
 - **Status is not visible in the syntax.** A line that parses tells you

package/skill/figdown/reference/scene.md

@@ -137,9 +137,14 @@ edge check -> accept class=yes
 edge check -> reject class=no
 ```
 
-A class an edge joins MUST declare `stroke=` or `style=`; a `fill=`-only
-class and a paint-less class are both errors naming `stroke=`. One class may
-carry both keys and serve nodes and edges at once — do not split it.
+A class an edge joins MUST NOT declare `fill=` with no `stroke=`: an edge has
+no interior, so that class reaches nothing on it — write `stroke=`, and a
+`style=` beside the `fill=` does not answer for it. A class that declares
+**no paint at all** is legal on every member: it draws its meaning in the
+derived legend with no swatch, and the edge keeps its default line. Read a
+paint-less class as a claim about MEANING, never as a missing colour. One
+class may carry both keys and serve nodes and edges at once — do not split
+it.
 
 **Never invent a label.** If the shape genuinely carries no text — a
 junction, a bare glyph — write an explicitly empty label: `node j ""`. It