dela
db5598fbf7
Standalone LaTeX/TikZ skill for non-tensor paper figures: node/edge macros, lint-on-warning build, golden examples, and negative fixtures.
49 lines
1.8 KiB
Markdown
49 lines
1.8 KiB
Markdown
# Visual grammar
|
|
|
|
Choose the smallest grammar that exposes the paper's mechanism. Adding a second grammar
|
|
must add information.
|
|
|
|
| Fact to expose | Grammar |
|
|
|---|---|
|
|
| one semantic object | `\sfnode` |
|
|
| linear sequence inside one band | `\sfstage` + `\sfrow` … `\sfrowend` |
|
|
| an edge between two objects | `\sfconn` for flow, `\sfarrow` for fixed topology |
|
|
| an edge label | `\sfconn{name}{label}` or `\sfarrowlabel` |
|
|
| a real composite (module, subsystem, shared owner) | `\sfgroup` |
|
|
| an operator inside a flow row | `\sfop` |
|
|
| a side note about a finished band | `\sfcallout` |
|
|
| the bottom explanation | `\sfmeaningbox` |
|
|
|
|
## Node semantics
|
|
|
|
One block is one semantic object. If you need two verbs in one block, split it.
|
|
|
|
- Label is the object's name or role, not a sentence.
|
|
- Fill color encodes a role, not importance.
|
|
- Width/height may differ to reflect a visual hierarchy, but do not use size to invent
|
|
quantitative meaning unless the figure says so.
|
|
|
|
## Edge semantics
|
|
|
|
Every arrow must be one of:
|
|
|
|
- **data flow** — the output of A becomes the input of B.
|
|
- **control flow** — A decides whether or when B runs.
|
|
- **dependency** — B needs A to exist or to have run.
|
|
- **causality** — A causes B.
|
|
|
|
A decorative arrow is an error. If an edge does not carry one of those meanings, remove it
|
|
or replace it with a grouping/caption.
|
|
|
|
## Group semantics
|
|
|
|
`\sfgroup` names a composite object. The members inside must actually belong to that
|
|
composite in the paper. Do not draw an outline around nearby nodes merely because it looks
|
|
balanced. The fit list is explicit: `{(node1)(node2)}`.
|
|
|
|
## Captions and meaning box
|
|
|
|
- `\sfcaption{name}{symbol}{detail}`: one short symbol line plus one muted detail line.
|
|
- `\sfmeaningbox`: at most three rows — idea, objects, mechanism. Prefer removing content
|
|
over shrinking type or adding columns.
|