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 8 additions and 5 deletions
Showing only changes of commit ad28f6621c - Show all commits
+1
View File
@@ -114,3 +114,4 @@ In [docs/decisions.md](docs/decisions.md):
- comprehension floor: every dimension and the overall at 7.0 or above; item 5 scores the restructure, which ships unscored: every `{…}` drawing afresh, the moves into `internal/`, and items 101, 102 and 104 to 106 - comprehension floor: every dimension and the overall at 7.0 or above; item 5 scores the restructure, which ships unscored: every `{…}` drawing afresh, the moves into `internal/`, and items 101, 102 and 104 to 106
- The template engine stays the root package until item 107; what reads no engine type sits in `internal/`, and items 101 and 102 move a table's rows there - The template engine stays the root package until item 107; what reads no engine type sits in `internal/`, and items 101 and 102 move a table's rows there
- Goal 5.1's `{…}` covers `{{`, `}}` and a lone `}`, so the goal names no escape - Goal 5.1's `{…}` covers `{{`, `}}` and a lone `}`, so the goal names no escape
- Goal 7.2's "no escaping" means a template needs no special character beyond `{}`
+7
View File
@@ -849,3 +849,10 @@ written. Yet `{{` prints `{`, `}}` prints `}`, and a lone `}` is a load error na
the README's Format string section states. The maintainer ruled the escape implicit in the the README's Format string section states. The maintainer ruled the escape implicit in the
goal: doubled braces and a lone `}` belong to the `{…}` syntax, so the goal names no escape and goal: doubled braces and a lone `}` belong to the `{…}` syntax, so the goal names no escape and
a lone `}` stays an error. Valid while a template escapes a brace by doubling it. a lone `}` stays an error. Valid while a template escapes a brace by doubling it.
## Goal 7.2's "no escaping" means a template needs no special character beyond `{}`
2026-10-05, Lilleman auf Larv. Serves goal 7.2: your first template of your own needs no
escaping and no options. The maintainer reads it as a template being writable with no special
character other than the braces, so a literal brace written `{{` or `}}` keeps the goal. Valid
while a template's only special characters are its braces.
-5
View File
@@ -108,7 +108,6 @@
| 27 | 0.2.0 | | **Merge `en_US.ip` and `sv_SE.ip`, today byte-identical, into one `misc.ip`.** | 3 | 2 | 4 | 6 | 5.7 | 14.1 | | 27 | 0.2.0 | | **Merge `en_US.ip` and `sv_SE.ip`, today byte-identical, into one `misc.ip`.** | 3 | 2 | 4 | 6 | 5.7 | 14.1 |
| 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 | | 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 | | 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 |
| 114 | 0.2.0 | question | **Settle whether goal 7.2's "no escaping" holds for a first template with a literal brace, which must write `{{` or `}}`.** | 1 | 1 | 4 | 5 | 7.2 | 13.8 |
| 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 | | 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 |
| 112 | 0.2.0 | | **Check a calc's field operands where its template links, beside its name operands, once item 36 reports every mistake at once.** | 2 | 2 | 1 | 6 | 3.2 | 10.3 | | 112 | 0.2.0 | | **Check a calc's field operands where its template links, beside its name operands, once item 36 reports every mistake at once.** | 2 | 2 | 1 | 6 | 3.2 | 10.3 |
| 94 | 0.2.0 | | **Refuse a name whose every read passes one deeper level, naming the binding of that level: `{place as p}{p.geo.town.name} {p.geo.town.zip}` is `{place.geo.town as t}{t.name} {t.zip}`.** | 3 | 3 | 3 | 5 | 5.7 | 10.2 | | 94 | 0.2.0 | | **Refuse a name whose every read passes one deeper level, naming the binding of that level: `{place as p}{p.geo.town.name} {p.geo.town.zip}` is `{place.geo.town as t}{t.name} {t.zip}`.** | 3 | 3 | 3 | 5 | 5.7 | 10.2 |
@@ -383,10 +382,6 @@ Require the path step to reach a sibling category.
`readTableOptions` in `table.go` and `walkDir` in `internal/datafiles` return on the first in Go's map order. `readTableOptions` in `table.go` and `walkDir` in `internal/datafiles` return on the first in Go's map order.
### 114. Settle whether goal 7.2's "no escaping" holds for a first template with a literal brace, which must write `{{` or `}}`.
Under the decision "Goal 5.1's `{…}` covers `{{`, `}}` and a lone `}`, so the goal names no escape", a literal brace is written `{{` or `}}`, and a lone `}` is a load error. Goal 7.2 promises a first template needs no escaping. The maintainer decides whether the escaping it rules out is shell quoting only, or the doubled brace too.
### 107. Move the template engine into `internal/`, leaving the root the public API and its options. ### 107. Move the template engine into `internal/`, leaving the root the public API and its options.
Needs item 5. The engine returns column values and the root builds `Record`. Revises the decision "The template engine stays the root package until item 107; what reads no engine type sits in `internal/`, and items 101 and 102 move a table's rows there", and, if the vocabulary moves, "The vocabulary sits below `doc.go`'s package clause, not in the package doc". Needs item 5. The engine returns column values and the root builds `Record`. Revises the decision "The template engine stays the root package until item 107; what reads no engine type sits in `internal/`, and items 101 and 102 move a table's rows there", and, if the vocabulary moves, "The vocabulary sits below `doc.go`'s package clause, not in the package doc".