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
3 changed files with 6 additions and 21 deletions
Showing only changes of commit 5f8981b14f - Show all commits
-1
View File
@@ -61,7 +61,6 @@ In [docs/decisions.md](docs/decisions.md):
- The repeat cap bounds renders, not bytes
- 64-bit targets only
- A constant zero divisor is a load error; in a string column a divisor that is not constant prints `Inf`
- In data, a constant spelled as a sample is a load error
- Samples say what they emit, transforms what they do
- A record is a template seen as columns; a Go struct is the one second schema
- A struct's records follow Go's field access, and compile on first use
+6 -15
View File
@@ -84,7 +84,7 @@ adding one: a rule a user states in one sentence, at the cost of `printf` or a
A JSON template is its JSON, so the whitespace around it is no part of the template, per
the decision "Whitespace around a JSON template is dropped, in `NewTemplate` and on
stdin". Stdin holding only whitespace is misuse, since an unset variable sends just a
newline, and so is stdin holding only `null`, which `jq` prints for a missing key.
newline.
A lone reference, `{/users}` or `"{/users}"`, names the record `users` under `--format`,
one newline after it allowed, with `users` the default `--table`; one to nothing there
@@ -119,12 +119,12 @@ until item 129: it reads a path, and only the data is absent.
Padding is where the two readings disagree: a format string renders it, JSON drops it. A
template that parses as JSON is its JSON, so its padding is dropped, as `encoding/json`
drops it. Goal 5.7: only an obvious mistake fails to load, and padding around JSON is
none.
drops it. Goal 5.7 loads it: it is well-formed and means one thing.
## A JSON string stays a template even where its bare text renders alike
2026-10-07, Lilleman auf Larv. Serves goal 5.7: only an obvious mistake fails to load.
2026-10-07, Lilleman auf Larv. Serves goal 5.7: whatever is well-formed and means one thing
loads.
`"x {/a}"` and `x {/a}` render alike on stdin, in `NewTemplate` and in a struct tag. The
quotes are no mistake: inside them `\t` and `\n` write a tab or a newline where the
@@ -298,15 +298,6 @@ is sometimes not a number loads, and prints `NaN` on each draw where it is not o
and `NaN` in a string column work against goals 6.1 and 4 until `todo.md` item 81
refuses them there too.
## In data, a constant spelled as a sample is a load error
2026-09-24, Lilleman auf Larv; narrowed 2026-10-07. Serves goal 5.7.
`int(5,5)` and `float(1,1,2)` draw nothing, which suggests a range typed wrong, so each is
rejected naming the constant. A default written out, `weight: 1`, `repeat: 1` or
`separator: ""`, loads wherever it is written, and a number spelled `+5` or `05` loads as
`5`, as the CLI's `--seed 007` and `--repeat +3` do.
## Samples say what they emit, transforms what they do
2026-09-02, Lilleman auf Larv.
@@ -375,7 +366,7 @@ to agree.
A null is one more outcome of a column's draw, so a choice's weights skew it like any
other; a null-rate option would be a second way to state odds. Outside a record column a
null never renders as null, so it is refused naming `""` (goal 5.7).
null renders `""`.
## A typed column holds one value, not composed text
@@ -863,7 +854,7 @@ Valid while names are read only inside the category binding them.
2026-10-04, Lilleman auf Larv. Serves goal 3 and applies KISS.
Shipped under the floor by the maintainer's decisions of 2026-10-07: the CLI reading its template from stdin, with the scoring run and its ratchet waived for that chunk; and narrowing goal 5.7 to the refusals that catch a mistake, dropping the rest, with the scoring run and its ratchet waived for that chunk too.
Shipped under the floor by the maintainer's decisions of 2026-10-07: the CLI reading its template from stdin, with the scoring run and its ratchet waived for that chunk; and goal 5.7 loading whatever is well-formed and means one thing, dropping every refusal that guessed at a mistake, with the scoring run and its ratchet waived for that chunk too.
Last scoring run, 2026-10-07, on commit ad59967: Navigation 7.00, Locality 5.88, Shape 6.50, Self-sufficiency 6.13, overall 6.38. The nine-seat panel at depth 1, run beside it: Navigation 7.17, Locality 6.06, Shape 6.67, Self-sufficiency 6.56, overall 6.56. Against the runs on ac6158e, the scoring run's overall rose from 6.25 and its Shape from 6.38, while its Self-sufficiency fell from 6.38; the panel's overall held, and its Locality and Self-sufficiency fell by 0.05 each. Locality is lowest again, as at every panel since 2026-09-22. All 13 seats named the named-pick read path hardest: `readField`, `readName`, `readUnder` and `keeps`, with the pick keys `levelKeys` and `addressedKeys` build at load; twelve kept `doc.go`'s vocabulary open beside it. What the two runs found is filed in `todo.md`, and `todo.md` item 153 runs both again. Valid while `AGENTS.md` gates goal 3 at 7.0.
-5
View File
@@ -119,7 +119,6 @@
| 22 | 0.2.0 | | **Give `url` and `email` a path that draws only domains nobody can register, keeping the wide set as the default.** | 3 | 4 | 7 | 8 | 16 | 14.0 |
| 46 | 0.2.0 | | **Report the same error every load for a table with two bad options, and for a folder with two unnamed rows files.** | 2 | 2 | 3 | 7 | 6, 10 | 14.0 |
| 158 | 0.2.0 | | **Drop a UTF-8 byte order mark that starts stdin, and say in the README how to stop PowerShell 5.1 sending `Göteborg` as `G?teborg`.** | 2 | 2 | 4 | 5 | 7.2, 5.1 | 13.5 |
| 160 | 0.2.0 | | **Refuse a sample whose range rounds or formats to one value, `float(1,1.004,2)` or a year-only `date` layout over days of one year, naming the constant.** | 2 | 2 | 3 | 6 | 5.7 | 13.1 |
| 79 | 0.2.0 | decision | **Beside a `--data-path`, load in `New` the user's categories, the shipped ones they override or read, and the shipped ones whose reads reach an overridden one; load the rest on first reach.** | 6 | 6 | 7 | 8 | 13 | 12.9 |
| 27 | 0.2.0 | | **Merge `en_US.ip` and `sv_SE.ip`, today byte-identical, into one `misc.ip`.** | 3 | 2 | 4 | 6 | 8 | 12.3 |
| 107 | 0.2.0 | decision | **Move the template engine into `internal/`, leaving the root the public API and its options.** | 6 | 9 | 3 | 8 | 3.2, 3.4 | 12.2 |
@@ -452,10 +451,6 @@ On stdin `42` is refused as "a number", which does not name the text the author
A file a Windows editor saves with a BOM prints an invisible U+FEFF first, and a JSON template with one is read as a format string. PowerShell 5.1 encodes what it pipes to a program by `$OutputEncoding`, ASCII by default. The maintainer chose 0.2.0 on 2026-10-07.
### 160. Refuse a sample whose range rounds or formats to one value, `float(1,1.004,2)` or a year-only `date` layout over days of one year, naming the constant.
Goal 5.7's own example, a range with nothing to draw. Today only `lo == hi` and `from == to` are refused. The goals audit of the narrowed goal 5.7 found it.
### 79. Beside a `--data-path`, load in `New` the user's categories, the shipped ones they override or read, and the shipped ones whose reads reach an overridden one; load the rest on first reach.
Needs item 77, which makes an override fail unless it says it replaces.