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 7 additions and 9 deletions
Showing only changes of commit 89f0b0d240 - Show all commits
+2 -4
View File
@@ -908,10 +908,8 @@ 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. 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 6. If two people could read a template differently, loading it fails, and the
error shows how to write each meaning. error shows how to write each meaning.
7. Each result has one obvious way to write it. A spelling with a part that doesn't 7. A spelling that suggests you meant something else — such as a range with nothing
change anything — a default written out, an item listed twice in a choice, a to draw, `int(5,5)` — fails to load, and the error shows what to write.
wrapper around what could stand alone — fails to load, and the error shows the
spelling to write instead.
8. When a clearer name turns up, it replaces the old one, even if that needs a new 8. When a clearer name turns up, it replaces the old one, even if that needs a new
major version. major version.
9. Everything fejkdata renders is written as a template: on the command line, in a 9. Everything fejkdata renders is written as a template: on the command line, in a
+3 -3
View File
@@ -324,10 +324,10 @@ its names: one tag may bind `{/person as p}{p.first}` and another read `{p.sex}`
while a path tag draws afresh as `{/path}` does (goal 5.2). while a path tag draws afresh as `{/path}` does (goal 5.2).
A tag binding a name only an embedding type reads is refused on the embedded type alone, as A tag binding a name only an embedding type reads is refused on the embedded type alone, as
any name read once is, so the embedder binds it in a tag of its own. A tagged field that any name nothing reads is, so the embedder binds it in a tag of its own. A tagged field that
another field hides is refused, not dropped. A named another field hides is refused, not dropped. A named
struct field is another entity and a record of its own. `fake:"-"` leaves a struct struct field is another entity and a record of its own. `fake:"-"` leaves any struct
field, embedded or named, unfilled, so no name may be `-`; a pointer back to a struct field unfilled, so no name may be `-`; a pointer back to a struct
already being filled is left alone, since filling it would never end. `New` cannot see a already being filled is left alone, since filling it would never end. `New` cannot see a
caller's types, so the first `FakeStruct` for a type compiles its tags and the answer, caller's types, so the first `FakeStruct` for a type compiles its tags and the answer,
error included, is kept per type: a test's first call is its load, and no `NewStruct` error included, is kept per type: a test's first call is its load, and no `NewStruct`
+2 -2
View File
@@ -245,8 +245,8 @@ Shape: T = table, t = template, c = choice.
Goal 5.9. Today a path is a second spelling of the template that reads it; afterwards only the template remains. Goal 5.9. Today a path is a second spelling of the template that reads it; afterwards only the template remains.
- A lone reference, a template of one reference token and nothing else, is what it references, as a record column reading one reference already is: `FakeRecord("{/users}")` returns the columns of `users`. The CLI's `loneReference` then goes, and `--format sql` takes its default `--table` from the library's parse of the reference. - A lone reference, a template of one reference token and nothing else, is what it references, as a record column reading one reference already is: `FakeRecord("{/users}")` returns the columns of `users`. The CLI's `loneReference` and the `isPath` check it copies from the token grammar then go, and `--format sql` takes its default `--table` from the library's parse of the reference.
- `Fake` and `FakeRecord` take a template. `FakeTemplate` folds into `Fake`, `FakeRecordTemplate` into `FakeRecord`, and `IsTemplate` goes, with `grammar.IsTemplate` and the lone-reference refusal. - `Fake` and `FakeRecord` take a template. `FakeTemplate` folds into `Fake`, `FakeRecordTemplate` into `FakeRecord`, and `IsTemplate` goes, with `grammar.IsTemplate`.
- `Fake` of a lone reference costs what `Fake` of its path costs today, and the allocation gate holds a case for it. - `Fake` of a lone reference costs what `Fake` of its path costs today, and the allocation gate holds a case for it.
- `List` and `--list` give each entry as the template that renders it, `{/sv_SE.person}`. - `List` and `--list` give each entry as the template that renders it, `{/sv_SE.person}`.
- Text that is not a JSON value and holds no `{…}` prints as written (goal 5.1), in a string field's struct tag and `Fake` alike, as stdin's text does in the CLI: `Fake("sv_SE.person")` returns `sv_SE.person`. `CHANGELOG.md` says that a path with no `{…}` prints as its text. A struct tag's `-` still skips its field. - Text that is not a JSON value and holds no `{…}` prints as written (goal 5.1), in a string field's struct tag and `Fake` alike, as stdin's text does in the CLI: `Fake("sv_SE.person")` returns `sv_SE.person`. `CHANGELOG.md` says that a path with no `{…}` prints as its text. A struct tag's `-` still skips its field.