feat(help): distinct help for advanced-mode SQL forms; split list by mode (#36)
The six advanced SQL DML/query forms (SELECT, WITH, SQL_INSERT, SQL_UPDATE, SQL_DELETE, EXPLAIN_SQL) carried help_id: None, so `help select`/`help with` resolved to nothing and `help insert` showed only the simple form. Give each its own distinct help_id (data.select, data.sql_insert, …) with a hand-curated help.data.* page. Distinct strings keep the dedup invariant intact, and note_help_topic needs no change — `help insert` now shows the simple block and the sql_insert block (like `help create` already did), and the advanced-only forms resolve. note_help now groups the list by CommandCategory: app-lifecycle commands first (unlabelled), then "Simple-mode commands:" and "Advanced-mode (SQL) commands:" sections — replacing the old single "DSL data commands (in simple mode):" header, which used the banned "DSL" term and mis-labelled the advanced SQL forms it already contained. Four new help_command tests (red→green). Recorded as ADR-0024 Amendment 1; CHANGELOG updated.
This commit is contained in:
@@ -706,6 +706,56 @@ documentation is still hand-curated for round 1.
|
||||
table-ident from new-name-ident visually is a future
|
||||
enhancement.
|
||||
|
||||
## Amendment 1 — advanced-mode SQL forms get their own `help` pages, and the list groups by mode (2026-06-22, issue #36)
|
||||
|
||||
`help_id` (§Node taxonomy) drives two surfaces: the `help` **list**
|
||||
(`note_help` emits one `help.<id>` block per `Some` id) and the
|
||||
`help <topic>` **lookup** (`note_help_topic` shows the block of every
|
||||
node whose entry word matches the topic). The dedup rule is that
|
||||
`help_id` *strings* are unique (one block ⇒ printed once).
|
||||
|
||||
Originally the six advanced-mode SQL **DML/query** forms — `SELECT`,
|
||||
`WITH`, `SQL_INSERT`, `SQL_UPDATE`, `SQL_DELETE`, `EXPLAIN_SQL` —
|
||||
carried `help_id: None`. That was a list-formatting shortcut (avoid a
|
||||
second `insert` entry), but it had a side effect: `help select` /
|
||||
`help with` resolved to **nothing** (the unknown-topic note), and
|
||||
`help insert` showed only the simple form — even though the SQL surface
|
||||
is genuinely different and advanced mode exists precisely for learners
|
||||
moving to raw SQL. (The advanced SQL **DDL** forms — `sql_create_table`
|
||||
etc. — already had their own `help.ddl.sql_*` pages, so the gap was
|
||||
inconsistent as well as a pedagogy hole.)
|
||||
|
||||
**Decision.** Give every advanced SQL form its **own** `help_id`
|
||||
(`data.select`, `data.with`, `data.sql_insert`, `data.sql_update`,
|
||||
`data.sql_delete`, `data.explain_sql`) with a hand-curated
|
||||
`help.data.*` page (the catalog body stays hand-written, per "What's
|
||||
out of scope" above — this amendment doesn't change that). Because the
|
||||
ids are **distinct strings**, the dedup invariant
|
||||
(`no_two_registered_commands_share_a_help_id`) is untouched, and:
|
||||
|
||||
- **`help <topic>` shows every form sharing the entry word** — so
|
||||
`help insert` shows the simple block *and* the `sql_insert` block
|
||||
(exactly as `help create` already showed the simple + SQL create
|
||||
forms). Advanced-only `help select` / `help with` now resolve.
|
||||
- **The list groups by mode.** `note_help` now splits the REGISTRY by
|
||||
[`CommandCategory`]: app-lifecycle commands (ids in the `app.*`
|
||||
namespace, usable in either mode) list first, unlabelled, under the
|
||||
intro; then a **`help.simple_section`** ("Simple-mode commands:")
|
||||
group and a **`help.advanced_section`** ("Advanced-mode (SQL)
|
||||
commands:") group. This replaces the single `help.dsl_section` header
|
||||
("DSL data commands (in simple mode):"), which both used the banned
|
||||
"DSL" term (ADR-0002 user-facing posture) and wrongly claimed simple
|
||||
mode for the advanced SQL forms the section already held.
|
||||
|
||||
This partially realises ADR-0030 §6's "Polish" item (a `help sql`
|
||||
page): rather than one combined page, each form has its own, reached
|
||||
through the normal `help <topic>` surface and discoverable in the
|
||||
advanced-mode list section. `note_help_topic` needed **no** change —
|
||||
the new `help_id`s make the forms resolve automatically. Covered by
|
||||
`help_command::{help_select_renders_the_sql_select_block,
|
||||
help_with_renders_the_cte_block, help_insert_shows_both_simple_and_sql_forms,
|
||||
help_list_splits_simple_and_advanced_sections}`.
|
||||
|
||||
## References
|
||||
|
||||
- ADR-0023 — Unified declarative grammar tree (Proposed direction). Superseded by this ADR for execution detail.
|
||||
|
||||
+1
-1
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user