Make great documentation goal 1.2, and plan the README's reorganisation and the nested-template gaps #33
@@ -99,7 +99,6 @@ In [docs/decisions.md](docs/decisions.md):
|
||||
- `misc.territory` is the spine, and a `misc` table naming a territory links to it
|
||||
- A table whose register publishes no frequency draws evenly
|
||||
- `misc.timezone` weighs a zone by the people living in it
|
||||
- `misc.port` selects by number, and carries no `name`
|
||||
- `misc.car` is one flat table, not a make linked to its models
|
||||
- `misc.territory` names its sovereign in a column, and there is no `misc.country` table
|
||||
- `misc.loglevel` is a table keyed by POSIX's keyword, carrying the code
|
||||
|
||||
+10
-18
@@ -410,15 +410,14 @@ Decided 2026-09-27 by the maintainer, for goal 4's one spelling per result; vali
|
||||
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
|
||||
`misc.currency[EUR]`, and only where it holds none an id the import assigns and never
|
||||
moves to another row. There is no `name` option.
|
||||
`misc.currency[EUR]`. There is no `name` option, and a table a user has no row of to
|
||||
select, a name table, `street`, `car` or `useragent`, carries no key and is drawn only.
|
||||
|
||||
- `misc.loglevel` keys on the keyword, `[err]`, which a configuration writes.
|
||||
- `misc.tld` keys on the ASCII form, `[.xn--p1ai]`, the one DNS carries.
|
||||
- `geo.US.locality` keys on the Census GEOID, `[1714000]` for Chicago.
|
||||
- `geo.SE.locality` keys on an assigned id: a postort has no code of its own.
|
||||
- A name table, `first-name`, `last-name` and `title`, carries no key, so it is drawn
|
||||
from and never selected.
|
||||
- `geo.SE.locality` keys on an integer the import assigns, since a postort has no code of
|
||||
its own: the import reads the previous TSV and keeps each postort's id by kommun and
|
||||
name, a new postort takes the next unused integer, and a removed or renamed one retires
|
||||
its id for good.
|
||||
|
||||
## A parent row with no child row is a load error
|
||||
|
||||
@@ -443,8 +442,7 @@ option earns its place.
|
||||
## The key index is built at load, the rest on first draw
|
||||
|
||||
A link is proved against the parent's keys and a key's uniqueness is a data mistake, so
|
||||
both are load-time; the name index and the per-parent child lists serve only a draw or a
|
||||
selection, so they wait for the first one, keeping `New` linear in the bytes read.
|
||||
both are load-time; the per-parent child lists serve only a draw, so they wait for the first one, keeping `New` linear in the bytes read.
|
||||
|
||||
## Two categories may name one TSV
|
||||
|
||||
@@ -551,9 +549,9 @@ are a curated proportion rather than bearers anyone counted.
|
||||
|
||||
## A table owns the spelling of a selector on it
|
||||
|
||||
A reference reaches a table by a path that carries no selector — `sv_SE.person.first`
|
||||
reads `first-name` through `sex` — so the walk that resolved a name cannot say where a
|
||||
reader would type one. The table's own location can, which is why it keeps its path, and
|
||||
A reference reaches a table by a path that carries no selector — `sv_SE.address` reads
|
||||
`geo.SE.locality` through its template — so the walk that reached it cannot say where
|
||||
a reader would type a selector. The table's own location can, which is why it keeps its path, and
|
||||
why an error names `geo.SE.municipality[1281]` rather than `municipality[1281]`.
|
||||
|
||||
## No builtin reads the clock, so a date is bounded by days, never by an age
|
||||
@@ -603,12 +601,6 @@ floored at 15,000, which goal 14 asks for: over 300 seeded draws of
|
||||
even weight gave them 44, and `America/Indiana/Petersburg`, a town of 2,400, fell from 17
|
||||
to 0. Valid while a draw weighted this way lands where people live.
|
||||
|
||||
## `misc.port` selects by number, and carries no `name`
|
||||
|
||||
29 of its services sit on more than one port, `http-alt` on three, so
|
||||
`misc.port[http-alt]` could name no one row. The number is what a port field holds
|
||||
anyway, and `misc.port[443].service` reads the other way.
|
||||
|
||||
## `misc.car` is one flat table, not a make linked to its models
|
||||
|
||||
A row is a make and a model drawn together, so no render pairs a Volvo with a RAV4. Two
|
||||
|
||||
@@ -101,7 +101,7 @@ by a `data-import/` script, as README goal 12 asks.
|
||||
rewrite that returns a different value where the read it conflicts with sits inside
|
||||
another category, and report a struct column's draw conflict with the path spelling
|
||||
a tag takes.
|
||||
- Let `geo.SE.locality[Lund].address` descend from a selected row into the template
|
||||
- Let `geo.US.locality[1714000].address` descend from a selected row into the template
|
||||
beside the family: require the path step to reach a sibling category, and seed every
|
||||
draw group of the render from the outer selector's pins.
|
||||
- Read `email.local`'s and `username`'s handles from the shipped name tables, which
|
||||
@@ -185,29 +185,24 @@ by a `data-import/` script, as README goal 12 asks.
|
||||
matched without case, else say the table selects by its key:
|
||||
`misc.territory[Sweden]` and `misc.territory[se]` name `[SE]`, `misc.protocol[tcp]`
|
||||
its key, and `misc.loglevel[Error]` `[err]`.
|
||||
- Delete the `name` option, and the load checks it carries: a name spelling another
|
||||
row's key, and a name repeating inside its parent.
|
||||
- Key `misc.loglevel` on `keyword`, and `geo.SE.locality` on an id `data-import/geo-se.py`
|
||||
assigns and keeps across imports, linking `street` and `postal-code` by it.
|
||||
- Drop `key` from `last-name` and `sv_SE.title`.
|
||||
- Rewrite what selects by name: in README.md, "selected by key or name",
|
||||
`misc.currency[Euro]`, "selects by either spelling", `misc.tld[.рф]`,
|
||||
`misc.loglevel[3]`, `misc.loglevel[err]` and "the code and the keyword do", the `geo`
|
||||
table's "by code or name", "by USPS abbreviation or name", "by GEOID or name" and
|
||||
"by name", `geo.SE.locality[Lund]`, `geo.SE.region[Skåne län]`,
|
||||
`geo.US.region[IL].locality[Springfield]`, "selection by name",
|
||||
`first-name[Taylor]`, `first-name[Kim]`, `sv_SE.title[dr]`, the `name` option's
|
||||
paragraph and "`[key]` or `[name]`"; `locality[Lund]` in docs/decisions.md; in
|
||||
CHANGELOG.md, "a path selects a row by key or name", "a name spelling another row's
|
||||
key", "a name repeating inside one parent row", "A `name` without a `key`" and
|
||||
`misc.tld[.рф]`.
|
||||
- Delete the `name` option and the load checks it carries, a name spelling another
|
||||
row's key and a name repeating inside its parent, and have `New` refuse a table
|
||||
still carrying `name`, naming `key`.
|
||||
- Key `misc.loglevel` on `keyword`, and `geo.SE.locality` on the integer
|
||||
`data-import/geo-se.py` assigns as the decision states, linking `street` and
|
||||
`postal-code` by it.
|
||||
- Drop `key` from `last-name` and `sv_SE.title`, and re-pin `testdata/shipped_shape.txt`.
|
||||
- Leave no selection by name in README.md, CHANGELOG.md or docs/: no selector spelling
|
||||
a free-form name, `geo.SE.locality[Lund]`, `misc.currency[Euro]`, `first-name[Kim]`
|
||||
and the rest, no "key or name", "by name" or "either" wording about selectors, and no
|
||||
`name` option in an example.
|
||||
- Render selected rows as the decision "A selected row is fixed, not drawn, and an
|
||||
unnamed read beside it is refused" states: `New` refuses
|
||||
`{/misc.territory[SE].capital} / {/misc.territory[FI].capital}` today, and a choice
|
||||
whose items select different rows. Have the refusal of an unnamed read name the
|
||||
rewrite through each selection: beside `{/geo.SE.locality[Lund].name}`,
|
||||
`{/geo.SE.municipality.name}` names none today, where
|
||||
`{/geo.SE.locality[Lund].municipality.name}` holds once the step up above lands.
|
||||
rewrite through each selection: beside `{/geo.US.locality[1714000].name}`,
|
||||
`{/geo.US.municipality.name}` names none today, where
|
||||
`{/geo.US.locality[1714000].municipality.name}` holds once the step up above lands.
|
||||
Scope the README's "A reference path into a category is held" to a path that
|
||||
selects no row.
|
||||
- Report the same error every load for a table with two bad options, and for a
|
||||
|
||||
Reference in New Issue
Block a user