figdown 0.4.1 → 0.5.1

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

@@ -184,3 +184,26 @@ ordinary text and needs no quotes, because `[ ]` is a verbatim region.
 Under `figdown 0.3` any of these lines may carry `note=`, a drawn aside in
 prose: `process parse "Parse body" note="…"`. It is never parsable and never
 where a structural fact lives.
+
+## Naming a connector — `id=` (`figdown 0.5`)
+
+A connector may carry an optional `id=`, and most do not. Writing one gives
+the line a **handle**: a name other constructs in the same section use to
+point at this connector, a key a diff pairs on, and the value the artifact's
+`data-edge` carries.
+
+**What you may conclude from an id, and it is very little.** An id is a
+handle and its SPELLING says nothing. Meeting `flowline a -> b id=f1` you may conclude that
+something in the document can refer to this connector; you may **not**
+conclude that it belongs to a group of any kind, that it is the first of
+several, or that it is related to a connector with a similar name. Whatever
+claim looks implied is made by a construct that states it, or it is not made.
+
+**And an unnamed connector is not a lesser one.** Anonymity is the default:
+most connectors in most figures carry no id, and the absence is not a gap, a
+draft state or a weaker assertion. Do not treat the named connectors in a
+figure as the important ones.
+
+An id is bare, matches `[A-Za-z_][A-Za-z0-9_-]*`, and is unique within its
+section — it shares one namespace with node, group and region ids, so a
+connector cannot take a name something else already has.

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

@@ -250,3 +250,31 @@ a missing colour.
   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.
+
+## Naming a connector — `id=` (`figdown 0.5`)
+
+A connector may carry an optional `id=`, and most do not. Writing one gives
+the line a **handle**: a name other constructs in the same section use to
+point at this connector, a key a diff pairs on, and the value the artifact's
+`data-edge` carries.
+
+**What you may conclude from an id, and it is very little.** An id is a
+handle and its SPELLING says nothing. Meeting `message a -> b "SYN" id=m1` you may conclude that
+something in the document can refer to this connector; you may **not**
+conclude that it belongs to a group of any kind, that it is the first of
+several, or that it is related to a connector with a similar name. Whatever
+claim looks implied is made by a construct that states it, or it is not made.
+
+**And an unnamed connector is not a lesser one.** Anonymity is the default:
+most connectors in most figures carry no id, and the absence is not a gap, a
+draft state or a weaker assertion. Do not treat the named connectors in a
+figure as the important ones.
+
+An id is bare, matches `[A-Za-z_][A-Za-z0-9_-]*`, and is unique within its
+section — it shares one namespace with node, group and region ids, so a
+connector cannot take a name something else already has.
+
+**An id on a message names it and orders nothing.** The figure's time axis is
+declaration order and nothing else; two messages are two occurrences however
+they are named, and an id never says that two of them are one, or that one
+comes before another. If you need the order, read the order.

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

@@ -138,3 +138,32 @@ 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.
+
+## Naming a connector — `id=` (`figdown 0.5`)
+
+A connector may carry an optional `id=`, and most do not. Writing one gives
+the line a **handle**: a name other constructs in the same section use to
+point at this connector, a key a diff pairs on, and the value the artifact's
+`data-edge` carries.
+
+**What you may conclude from an id, and it is very little.** An id is a
+handle and its SPELLING says nothing. Meeting `transition s1 -[start]-> s2 id=t1` you may conclude that
+something in the document can refer to this connector; you may **not**
+conclude that it belongs to a group of any kind, that it is the first of
+several, or that it is related to a connector with a similar name. Whatever
+claim looks implied is made by a construct that states it, or it is not made.
+
+**And an unnamed connector is not a lesser one.** Anonymity is the default:
+most connectors in most figures carry no id, and the absence is not a gap, a
+draft state or a weaker assertion. Do not treat the named connectors in a
+figure as the important ones.
+
+An id is bare, matches `[A-Za-z_][A-Za-z0-9_-]*`, and is unique within its
+section — it shares one namespace with node, group and region ids, so a
+connector cannot take a name something else already has.
+
+**Why the caution matters most here.** Two transitions between one pair of
+states are two different TRIGGERS, and the trigger is the whole content of
+the arc — it lives in the `[mid]` inscription. A transition named `timeout`
+states no trigger; a transition whose inscription reads `timeout` does. Read
+the arc, never the handle.

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

@@ -164,3 +164,45 @@ as one intermediate `node` that fans out.
 part of the claim — a site, a rack, a country — say it with a `group` and a
 label. Delete every `pin` and the figure must still be the same figure
 (`../layout.md`).
+
+## Naming a connector — `id=` (`figdown 0.5`)
+
+A connector may carry an optional `id=`, and most do not. Writing one gives
+the line a **handle**: a name other constructs in the same section use to
+point at this connector, a key a diff pairs on, and the value the artifact's
+`data-edge` carries.
+
+**What you may conclude from an id, and it is very little.** An id is a
+handle and its SPELLING says nothing. Meeting `edge l1 -- s1 id=lag1a` you may conclude that
+something in the document can refer to this connector; you may **not**
+conclude that it belongs to a group of any kind, that it is the first of
+several, or that it is related to a connector with a similar name. Whatever
+claim looks implied is made by a construct that states it, or it is not made.
+
+**And an unnamed connector is not a lesser one.** Anonymity is the default:
+most connectors in most figures carry no id, and the absence is not a gap, a
+draft state or a weaker assertion. Do not treat the named connectors in a
+figure as the important ones.
+
+An id is bare, matches `[A-Za-z_][A-Za-z0-9_-]*`, and is unique within its
+section — it shares one namespace with node, group and region ids, so a
+connector cannot take a name something else already has.
+
+**What an id is FOR here: naming one link of several.** A `bundle` collects
+links, and its members may be written either as endpoint pairs or as
+connector ids. The pair form works only where exactly one link runs between
+the two devices; where several do — which is the ordinary shape of an
+aggregation — the ids are the only way to say which links belong:
+
+```figdown
+figdown 0.5 topology
+node sw1 "Switch-1"
+node sw2 "Switch-2"
+edge sw1 -- sw2 id=m1
+edge sw1 -- sw2 id=m2
+bundle ae0 "ae0" m1,m2
+```
+
+Read `m1,m2` as **exactly two members, named**, and nothing more: the ids do
+not say the links are ordered, numbered, or interchangeable. If the source
+also carries interface names, they are in the end labels, not in the ids.

package/skill/figdown/reference/scene.md

@@ -168,6 +168,29 @@ a `node` styled to look like one.
   `experimental/block.md` (EXPERIMENTAL)
 - Bars drawn from a `table` region → `experimental/chart.md` (EXPERIMENTAL)
 
+## Naming a connector — `id=` (`figdown 0.5`)
+
+A connector may carry an optional `id=`, and most do not. Writing one gives
+the line a **handle**: a name other constructs in the same section use to
+point at this connector, a key a diff pairs on, and the value the artifact's
+`data-edge` carries.
+
+**What you may conclude from an id, and it is very little.** An id is a
+handle and its SPELLING says nothing. Meeting `edge a -> b id=e1` you may conclude that
+something in the document can refer to this connector; you may **not**
+conclude that it belongs to a group of any kind, that it is the first of
+several, or that it is related to a connector with a similar name. Whatever
+claim looks implied is made by a construct that states it, or it is not made.
+
+**And an unnamed connector is not a lesser one.** Anonymity is the default:
+most connectors in most figures carry no id, and the absence is not a gap, a
+draft state or a weaker assertion. Do not treat the named connectors in a
+figure as the important ones.
+
+An id is bare, matches `[A-Za-z_][A-Za-z0-9_-]*`, and is unique within its
+section — it shares one namespace with node, group and region ids, so a
+connector cannot take a name something else already has.
+
 ## The drawn annotation — `note=` (`figdown 0.3`)
 
 `note=` is an **attribute on the annotated element's own line**, and the

package/skill/figdown/reference/transcribe.md

@@ -13,7 +13,10 @@ tiers, and you state which one you used in the provenance comment:
 
 ## Reconstruct the meaning, do not trace the drawing
 
-Recover what the original *means*, then state that in FigDown.
+Recover what the original *means*, then state that in FigDown. Measured, so
+that the temptation has a number beside it: of 216 question-labelled nodes in
+the production corpus, **78% are diamonds, 14% ellipses and 8% carry no shape
+at all** — a source's diamond is not evidence of a decision, its question is.
 
 - **Verify every bitfield row's width sum against the original ruler.**
 - **Never fabricate.** Mark every uncertainty in a `#` comment for human