Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33

Open
lilleman wants to merge 966 commits from worktree-todo-relative-dates-exact-counts into main
4 changed files with 8 additions and 7 deletions
Showing only changes of commit 03577ebca2 - Show all commits
-1
View File
@@ -20,7 +20,6 @@
run are two ratchets, never compared with each other. A lower score blocks the merge
even where it may be panel noise: fix what the seats name until the score rises.
- Hard tabs. No comment by default; delete a restatement, a rationale, history, or a file preamble.
- A spelling that only restates another is rejected at `New`, and the error names the one to use.
- Prose naming a source states what that source states: read the register's own field
before paraphrasing it, and name the register you read before claiming none
publishes a spelling.
+3 -2
View File
@@ -958,8 +958,9 @@ Where the project is heading; the sections before Audience document what ships t
5. `[SE]` selects one row of a table, and means that row wherever you write it.
6. If two people could read a template differently, loading it fails, and the
error shows how to write each meaning.
7. Each result has one obvious way to write it. A spelling that only restates another
fails to load, and the error shows the obvious one.
7. Each result has one obvious way to write it. A spelling with a part that doesn't
change anything — a default written out, a repeated item, a wrapper around what
could stand alone — fails to load, and the error shows it without that part.
8. When a clearer name turns up, it replaces the old one, even if that needs a new
major version.
6. **Mistakes are caught when the data loads, and the error says plainly what is
+3 -2
View File
@@ -164,7 +164,7 @@ naming the locale, so a folder renames and copies without editing its references
Data files, the CLI and the Go API are the public API, and a consumer must be able to
take a minor without an edit — so an added column is a major, since it changes the CSV
header and the `INSERT` column list, as is a removed value, which changes what a fixture
holds, and a new option, which reserves a field name. One spelling per result grows by
holds, and a new option, which reserves a field name. Goal 5.7's refusals grow by
tightening, so every fence invalidates some file. Each such release names the rejected
spelling and its replacement in the changelog and in the load error, and that is the
whole migration: a fence rejects one spelling with one replacement, so the fix is local
@@ -532,7 +532,8 @@ Valid until item 4 makes every `{…}` draw afresh, which revises the shared ste
## A table selects by one key column, a code, never a free-form name
Decided 2026-09-27 by the maintainer, for goal 5's one spelling per result; valid while
Decided 2026-09-27 by the maintainer, for goal 5.5: `[SE]` means one row wherever it is
written. Valid while
the key is the code a user writes, as a database keys a table. `country[NO]` loads, and
`country[Norway]` is refused naming `[NO]`, found by the row whose cell spells the
selector. The key is the friendliest code the register holds, `misc.territory[SE]` and
+2 -2
View File
@@ -84,7 +84,7 @@
| 81 | 0.2.0 | decision | **Refuse at load every `calc` operand not proven numeric and every divisor not proven nonzero, in a string column too.** | 4 | 4 | 6 | 8 | 6.1, 4 | 20.6 |
| 36 | 0.2.0 | | **Report every mistake a load finds in one error, as the decision "A load reports every mistake at once" states.** | 5 | 6 | 7 | 8 | 6 | 19.5 |
| 88 | 0.2.0 | | **Add a 12-digit `YYYYMMDDNNNC` form of `sv_SE.personnummer` and `sv_SE.samordningsnummer`, the form Skatteverket's testpersonnummer series and many systems store.** | 2 | 3 | 6 | 6 | 4 | 19.4 |
| 41 | 0.2.0 | | **Key every table by one key column, as the decision "A table selects by one key column, a code, never a free-form name" states.** | 6 | 7 | 7 | 8 | 5.7 | 19.1 |
| 41 | 0.2.0 | | **Key every table by one key column, as the decision "A table selects by one key column, a code, never a free-form name" states.** | 6 | 7 | 7 | 8 | 5.5 | 19.1 |
| 52 | 0.2.0 | | **Name the file a link error comes from beside its category path, `sub.x (/d/a/sub/x.json): …`.** | 1 | 2 | 5 | 7 | 6 | 19.0 |
| 28 | 0.2.0 | decision | **Accept a middle name, and draw a `personnummer` whose sex matches a sex selected through a named pick.** | 4 | 4 | 6 | 7 | 4.1 | 18.9 |
| 24 | 0.2.0 | defect | **Stop `misc.territory[EH].tld` rendering `.eh`, the one shipped TLD `misc.tld` does not hold.** | 1 | 1 | 4 | 7 | 4 | 18.6 |
@@ -231,7 +231,7 @@ Shape: T = table, t = template, c = choice.
- Deletes the token-order rules (`drawsApart`, `readFold`, `branches`, the pairwise replay), the expansion hold fence, `drawGroup`, the own-family fence and the cell-reference fences, and revises the decisions that point here. The remaining draw checks are names, paths through names, cycles and the repeat cap.
- Fixes on the way: `{/sel}|{/sel}` panics out of `Fake` today where two draws land on rows whose cells select different rows of another table; it must render.
- Rewrites the README's Computation, References, Draw group, Correlated fields, Linked tables, Names and "One draw, one spelling" sections; the Linked tables section says which pick's weights govern a family, since the bound row decides.
- Keeps a name read once where no reference can stand, such as `{/score as s}{calc(s * 2)}`, loading. Widens the refusal of a name read once to every binding, a path into it or a reference path bound included, since `{n.x}` read once is then `{/ref.x}`, and deletes the names fence over draw groups and nested repeats (`checkUses`, `readsHeld`).
- Keeps a name read once where no reference can stand, such as `{/score as s}{calc(s * 2)}` over a numeric category `score`, loading. Widens the refusal of a name read once to every binding, a path into it or a reference path bound included, since `{n.x}` read once is then `{/ref.x}`, and deletes the names fence over draw groups and nested repeats (`checkUses`, `readsHeld`).
- Say how a record's columns and a struct's tags read one pick, so the `first` and `sex` columns of one `sv_SE.person` record, or one struct's tags reading them, still describe one person.
- Re-pin seeded output and `testdata/shipped_shape.txt` in their own commits; the CHANGELOG names the grammar change.