summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md217
1 files changed, 129 insertions, 88 deletions
diff --git a/design/README.md b/design/README.md
index 60e6cea..253be7a 100644
--- a/design/README.md
+++ b/design/README.md
@@ -93,8 +93,8 @@ this table.
| | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key |
| | [`minimap`](#the-map-and-the-minimap) | a pane's whole column of the map, small, in a strip at its right | its window, marks, `flash` |
| | [`clock`](#clock-and-caption) | where in the recording | |
-| | [`column`](#column-an-experiment) | an experiment: the panes a beat is about in one column, its narration in the other | the `shelf` of folded panes |
-| | [`bubble`](#column-an-experiment) | a piece of narration placed in the frame, level with what it speaks of | `beside`, `below`, `above`, `on`; newest, older; its `stem` |
+| | [`column`](#column) | the second form a scene is composed in: the panes a beat is about in one column, its narration in the other | the `shelf` of folded panes; text on the right, or on the left while the program column is empty |
+| | [`bubble`](#column) | a piece of narration placed in the frame, level with what it speaks of | `beside`, `below`, `above`, `on`; newest, older; its `stem` |
| | [`caption`](#clock-and-caption) | the narrator | |
| | [`veil`](#clock-and-caption) | page over what a beat does not touch, or a pace cannot show | |
| | [`card`](#clock-and-caption) | a title, the legend: no program running | |
@@ -1359,7 +1359,7 @@ give way: where a step draws a link and a projection it is an echo (the word's
mark with the row's, at the same frame), its two ends being side by side and
the name and the digits saying already that they are one. rsp never takes a
link: its pin is on the window's top row by construction.
-[`establish`](#6-verbs) draws no lines. In the [`column`](#column-an-experiment)
+[`establish`](#6-verbs) draws no lines. In the [`column`](#column)
a bubble's stem stands only in the rest before a step, never with its ties.
**Off the window.** A link whose target is outside its panel's window (a
@@ -1880,23 +1880,53 @@ caption's and the clock's.
band), x2 (896 by 420: sixteen rows), x4 (448 by 210: one chain). It is
for reading, and always comes back.
-### column (an experiment)
+### column
-A second way to compose a scene, beside the working frame, to be tried on one
-scene and judged against it (the trial: [`open` followed down in the
-column](motion.md#a-scene-in-the-column-open-followed-down); mocks 49 to 55).
-It is not the language's default. The working frame shows the whole context
-and a caption under it; the column shows, beat by beat, the panes the beat is
-about and says what they do beside them, where they do it. It is an author's
-instrument: the scene says for every beat which panes stand, where each bubble
-sits and what it is tied to; the defaults below only spare typing, and never
-decide against what the scene wrote.
+The second way to compose a scene, beside the working frame, which stays the
+default where a scene chooses nothing. The working frame shows the whole
+context with a caption under it; the column shows the panes a beat is about
+in one column and says what they do beside them, level with where they do it
+([a scene built this way](motion.md#a-scene-in-the-column-open-followed-down);
+mocks 49 to 55; the renders `column-1080` beside `syscalls-1080`, and
+`column_sort-1080`). It is an author's instrument: the scene says for every
+beat its form, which panes stand, where its text sits and what it is tied to;
+the defaults below only spare typing, and never decide against what the scene
+wrote.
+
+**When to reach for it.** When the story is a column of rows that goes down
+and comes back: a call followed down to the kernel and back up, a recursion,
+the stack growing and shrinking, a frame filling byte by byte, a loop told
+turn by turn beside its rows. There the text, level with its row, moves as
+the story does, and the panes the beat needs get the height (a descent of 24
+rows where the working frame gives 17). **When the working frame serves
+better**: when every step acts on the program and the state at once (sort's
+swaps with the array, the heap scene's nodes over their bytes, a `continue`
+whose registers all change), when two runs face each other (the
+[`pair`](#pair)), and for a scene's opening and close, where the whole
+context is the point. Most scenes mix the two.
+
+**Mixing them.** A scene in the working frame takes the column for a few
+beats and comes back; the change is made in a rest, between beats, in one
+order and never in one frame. Into the column: the caption leaves (12 f); the
+panes the column will not keep fold to their tags where they stand (rows out
+6 f, then the panel closes as its tag travels to the shelf, 18 f, `glide`),
+so that no panel ever crosses another, empty or not; then the panes that stay
+glide and resize to their boxes (24 f), their rows riding with them; the
+text column opens and the first bubble arrives (18 f). Back to the working
+frame: the bubbles leave together (12 f); the panes glide to their working
+frame's boxes (24 f); the folded panes unfold from the shelf in their places
+(18 f, rows in 6 f); the caption arrives. About 70 f each way. A drawing that
+changes size between the forms keeps its labels inside its box at every frame:
+it scales as one (24 f) and its tag's note crossfades if it no longer fits.
**The frame.** Two columns of 880, the working frame's own: the panes on the
left (x 64), where the program column is in the working frame, so that a scene
going between the two keeps its source and disassembly where they were; the
text on the right (x 976), as an assembler's comment and the row's annotation
-sit right of the code they speak of. The gutter between keeps its lanes.
+sit right of the code they speak of. While the program column has nothing in
+it yet (an introduction building the state first, each part in the place it
+will keep) the text may stand on the left instead, beside the panes on the
+right. The gutter between keeps its lanes.
| Part | Where | |
| --- | --- | --- |
@@ -1913,28 +1943,40 @@ current one, when the beat changes line) and the pane where its effect lands
(the registers for a register, the stack for a stack word or a call's push,
the drawing when the idea changes); the cause's pane gets the rows its window
needs (a descent all its windows, the disassembly 11), the effect's the rest.
-A beat about the idea shows its drawing as large as the column lets it, or
-across both columns with its text above, below or on it (placements, below).
+Change the panes only where the beat's subject moves to another pane: each
+change costs about 1.4 s (the built scene changed them seven times, 9.5 s of
+its 23% more), so a column scene of eight beats should change them three or
+four times, not at every beat.
**Panes between beats.** What persists slides; nothing appears or vanishes in
one frame. In the rest between two beats, in this order: the last bubble
-dims; the panes that leave fold (their rows fade, 12 f, then the panel
-closes to its tag as the tag travels to its place on the shelf, 24 f,
-`glide`); the panes that stay glide to their new boxes (24 f); the panes that
-come unfold (the tag travels from the shelf to its box as the panel opens,
-24 f, then the rows fade in, 12 f); then an older bubble in the way glides out
-of it (24 f) and the next arrives. Never a fold and an unfold in one place at
-once: what leaves has left. About 70 f for the panes, 96 f more than a
-caption's change in all, and only in a rest (motion.md has the frames).
+dims; the panes that leave fold (rows out 6 f, the panel closing as its tag
+travels to the shelf, 18 f, `glide`); the panes that stay glide to their new
+boxes (24 f); the panes that come unfold (the tag from the shelf as the panel
+opens, 18 f, rows in 6 f); then an older bubble in the way glides out of it
+(24 f) and the next arrives. Never a fold and an unfold in one place at once.
+**A pane that stays and changes height keeps its rows** the whole way: its
+frame glides and its window gains or gives up rows at the edge that moves (the
+rows it loses fade as the edge reaches them, those it gains fade in behind
+it); it is never drawn empty, not for a frame (the built scene emptied its
+descent for 40 f while it grew).
-**`bubble`.** A piece of narration: one to three lines of at most 40
-characters, Go 40 on 54 as the caption is, code in mono 35; 16 of padding,
-812 wide at most. The newest is on `raised` paper, primary: the one being
-said. An older one loses its paper and dims to `dim` (18 f, as the next
-arrives), and stays as the account the viewer can glance back at. Three stand
-at most; a fourth's arrival makes the oldest leave first (12 f, `exit`).
-All leave at a chapter's end.
+**`bubble`.** A piece of narration: Go 40 on 54 as the caption is, code in
+mono 35, lines of at most 40 characters, 16 of padding, 812 wide at most. The
+newest is on `raised` paper, primary: the one being said. An older one loses
+its paper and dims to `dim` (18 f, as the next arrives), and stays as the
+account the viewer can glance back at. Three stand at most; a fourth's
+arrival makes the oldest leave first (12 f, `exit`). All leave at a chapter's
+end.
+- **How long**: its reading time (90 f + 3.6 f a character) is covered by its
+ beat: the 60 f lead, the beat's steps and a hold of at most 84 f, so that it
+ is never still being read while nothing moves (the built scene's 104
+ characters over a single step left 4.9 s of stillness). For one walked step
+ that is about 64 characters, two lines; three lines only for a beat whose
+ steps last as long as they take to read (a run, a crossing, a store at a
+ time). A held rest the scene means (a poster's picture) is said so, and is
+ the one exception.
- **Where it sits**: its first line level with the thing it speaks of (the
row's centre on the line's), so that the eye crosses on one line. The
author may name another level; the default is the row of the beat's first
@@ -1956,63 +1998,58 @@ All leave at a chapter's end.
bubble no stem; its level is then the tie.
- **The caption's rules, restated**: it arrives (18 f, rising 8) in a rest,
60 f before the step it describes fires (120 f for a scene's first); it is
- the newest at least 90 f + 3.6 f a character and at most 720 f; nothing
- arrives, moves or dims under a moving thing; it names only what is on
- screen at the pace it plays.
+ the newest at most 720 f; nothing arrives, moves or dims under a moving
+ thing; it names only what is on screen at the pace it plays.
**Placements.** Where a beat's text is, chosen per beat (or per scene):
| Placement | Where | For |
| --- | --- | --- |
-| `beside` | the text column; the panes in one column | a subject made of rows, or tall: the disassembly, a descent, the stack, the source and its instructions. The experiment's main form |
-| `below` | the caption band under the working frame (the present frame, every pane as it is) | a beat that needs the program and the state side by side: the scene's opening, which establishes everything; a `continue`; a step whose effects land in both columns at once |
-| `above` | a band of 120 over a wide subject at the stage's top, the subject under it | a wide drawing whose story runs down it (a calls tree growing, a graph in `layers`): the text leads the eye in at the top |
-| `on` | in the subject's own free space | a wide drawing with room inside it (a ring's interior, the corners round the rings, the gaps of the map's columns); tied by a stem to the part it speaks of |
+| `beside` | the text column; the panes in one column | a subject made of rows, or tall: the disassembly, a descent, the stack, a frame as bytes, the source and its instructions, the address space |
+| `below` | the caption band under the working frame (every pane as it is) | a beat that needs the program and the state side by side: a scene's opening, which establishes everything; a `continue`; a step whose effects land in both columns at once; a `pair` |
+| `above` | a band of 120 over a wide subject at the stage's top, the subject under it | a wide drawing whose story runs down it (a calls tree growing, a graph in `layers`, the `aligned` source and code): the text leads the eye in at the top |
+| `on` | in the subject's own free space | a wide drawing with room inside it (a ring's interior, the corners round the rings, the map's key and the gaps of its columns); tied by a stem to the part it speaks of |
The choice follows the subject's shape (rows: `beside`; wide: `above`, `below`
or `on`), where its free space is, and the way the story moves (text leads:
above when it runs down, below when the result arrives at the foot). A bubble
`on` a drawing keeps 16 clear of every element, every edge's path and every
-path a mark will travel while it stands (the renderer knows the beat's
-steps); its stem crosses nothing, going round the drawing's outside where it
-must (mock 55); where no such place holds it, the beat is `above`. A bubble
-never travels between placements: the last leaves (12 f), the frame changes
-(a [`relayout`](#6-verbs), 48 f), the next arrives (18 f). A scene that
-otherwise uses the column may stand the working frame as it is, both columns
-of panes, with its text below or above, for the beats that need both; the
-change is that relayout, between beats.
+path a mark will travel while it stands; its stem crosses nothing, going round
+the drawing's outside where it must (mock 55); where no such place holds it,
+the beat is `above`. The renderer finds the place and checks it from the
+beat's steps; a scene does not place it by hand. A bubble never travels
+between placements: the last leaves (12 f), the frame changes, the next
+arrives (18 f).
**Ties and paces in the column.** The step's ties are the frame's: the
-thread, a link, a projection, a touch. A touch from the disassembly to the
-stack under it leaves the row's right rule, goes down the gutter's middle lane
-and ends on the stack's right rule, its head pointing left (mock 49). At a
-run the panes keep their places and only the newest bubble stands; at a
-sprint the scene surfaces to the map as ever, and a bubble set `on` the map
-is the sprint's caption.
+thread, a link, a projection, a touch, a carry. A touch from the disassembly
+to the stack under it leaves the row's right rule, goes down the gutter's
+middle lane and ends on the stack's right rule, its head pointing left (mock
+49). At a run the panes keep their places and only the newest bubble stands;
+at a sprint the scene surfaces to the map as ever, and a bubble set `on` the
+map is the sprint's caption.
-**Reaching the whole context.** "We don't want to hide info" holds by three
-means: the shelf (every pane's tag, and each change in it struck there); a
-beat the author spends on the whole (`below`, the working frame), which the
-scene's opening is by default; and the map and `unroll`, as in the working
-frame.
+**Reaching the whole context.** Nothing is hidden: the shelf (every pane's
+tag, and each change in it struck there); the beats spent on the whole
+(`below`, the working frame), a scene's opening and close by default; and the
+map and `unroll`, as in the working frame.
-**What it costs and gains**, measured on the trial (the working frame's
-`beside` against the column at the same instant, mock 54):
+**Measures, as built** (`open` followed down, the working frame against the
+column at the crossing, mock 54 and the render):
| | The working frame | The column |
| --- | --- | --- |
-| the descent at the crossing | 17 rows (main 3, the stub 1, open 8, the kernel 2, heads 3) | 24 (main 5, open 13), and up to 27 with its floor above 888 |
-| source | 8 lines | 3 (the line and its neighbours) |
-| registers, stack, the log, its bytes | on screen, 14 rows, 11 words, 152, 152 | on the shelf, a tag each; rax 3 struck on its tag |
-| narration | 2 lines of 64 under the stage, 1792 by 120 | up to three bubbles of three lines of 40 beside the rows, 880 by 840 |
-| height for panes | 840 (48 to 888), shared by both columns' seven panes | 948 (84 to 1032), shared by the beat's two or three; 144 of it the floor |
+| the descent at the crossing | 17 rows (main 3, the stub 1, open 8, the kernel 2, heads 3) | 24 (main 5, open 13), up to 27 with its floor above 888 |
+| source | 8 lines | 3 |
+| registers, stack, the log, its bytes | on screen: 14 rows, 11 words, 152, 152 | on the shelf, a tag each; rax 3 struck on its tag |
+| narration | 2 lines of 64 under the stage | up to three bubbles of lines of 40 beside the rows; the newest level with its row in most beats |
+| height for panes | 840, shared by seven panes | 948 (84 to 1032), shared by two or three; 144 of it the floor |
+| length | 84 s | about a quarter longer (the renderer counts 23%): seven pane changes, about 9.5 s of it |
-The caption band is not gained as narrated rows: it is under a paused
-player's controls in either form, and the column keeps narrated rows above
-888. What is gained is the right column (the state panes' 880 by 840) given
-to the narration and the left one given to fewer panes: a descent half again
-as tall, a stack of nineteen words beside a call, and text that says where it
-speaks.
+The caption band is not gained as narrated rows (it is under a paused
+player's controls in either form); what is gained is the state column given
+to the narration and the program column to fewer, taller panes, and text
+that says where it speaks.
## 6. Verbs
@@ -2163,7 +2200,7 @@ recording of `mock/heap.c`; `mock/intro.py` draws the introduction and
its blocks (29 to 37) from the same list recording and its mappings;
`mock/gen.py` draws 1 to 8; `mock/touch.py` draws the disassembly tied to the
stack (44 to 48) and the carry (56) from a fresh recording of `reverse` and its call; `mock/column.py`
-the column experiment (49 to 55) from a fresh recording of `hello`. Each working
+the column (49 to 55) from a fresh recording of `hello`. Each working
frame has a `-480.png` beside it; the map has its 1080p (`19-map-1080.png`).
```sh
@@ -2503,6 +2540,27 @@ is not checked here. The tokens are under [Token changes](#token-changes).
instruction's own annotation saying the move (`rsp -0x18 3 words`,
`rbp = rsp`, `rsp +8 ยท saved rbp`); at a run the pins over the veil.
+15. **The column** ([column](#column)), now a form every scene may use, per
+ scene or per beat, the working frame its default. Built (`column`,
+ `column_sort`): the two columns, the shelf, the bubbles level with their
+ rows, the placements, the scene API. To fix, as the renders show them:
+ **a pane that stays and resizes keeps its rows** (the descent was drawn
+ empty for about 40 f while it grew: its frame must glide with its rows
+ in it, rows lost at the moving edge fading as it reaches them, rows gained
+ fading in behind it); **no panel crosses another in a change of form**
+ (the working frame's panels slid over each other, empty, on the way into
+ the column, and the graph shrank with its tag's note over the shelf on the
+ way out of it in `column_sort`): the leaving panes fold to the shelf in
+ place first, then the stayers move, a drawing scaling as one inside its
+ box; **an `on` bubble is placed and checked by the renderer** (16 clear of
+ every element and every path the beat's marks take; else `above`), not by
+ the scene; **a bubble about a folded pane points at its tag**; and the
+ instruments' CAPTION check extended to bubbles: a bubble whose reading
+ time is longer than its lead, its beat's steps and an 84 f hold is
+ flagged (the 104-character one left AIR of 4.9 s at 28.9 s), unless the
+ scene marks the rest as held. Then the two scenes motion.md storyboards
+ for it: the ASan pair and the introduction.
+
16. **The carry** ([`carry`](#4-ties)), a scene's knob `carry` (`.off`,
the default; `.arrow`; `.value` for the introduction's one walked load):
2 units in primary, an open chevron, the gutter's right lane, from the
@@ -2511,23 +2569,6 @@ is not checked here. The tokens are under [Token changes](#token-changes).
no touch; nothing for a move between registers; a stub to a folded or
off-window end.
-15. **The column, an experiment** ([column](#column-an-experiment); the trial's
- storyboard in [motion.md](motion.md#a-scene-in-the-column-open-followed-down)),
- built for the trial scene beside its present form, not in place of it:
- the stage as two columns of 880 (panes at 64, text at 976); the `shelf`
- of folded tags at y 48 with each tag's note and its strikes; the beat's
- panes from 84, narrated rows and rip above 888; the clock under the text
- column; the `bubble` (Go 40 on 54, three lines of 40 at most, the newest
- on raised paper, older ones dim, three at most) placed level with what it
- speaks of, older ones gliding out of its way and riding with their rows;
- its stem in the rest only; the placements `beside`, `below`, `above` and
- `on`, a relayout between them; the fold and unfold of panes between beats
- in the order the section gives; the touch in the column down the gutter
- onto the stack's right rule. And a scene API in which the author says, per
- beat, the panes (with rows or `rest`), the bubble's text, its placement,
- its level and its stem, every one optional and defaulted as the section
- says (motion.md has a beat written that way).
-
**What the recordings must hold**, with the tracer's options:
- For the map, as before: `--stack 1024`, `--disasm 69`, `--around 256`;