docs(CLI): the trunk's third verb joins the list of forms the page says the console takes #2053

Merged
jaylouisw merged 1 commit from docs/1118-2347 into main 2026-11-19 00:38:04 +00:00
Owner

Doc: docs/CLI.md, the paragraph under "help is an index, and a test reads it out of the parser".

What was untrue. That paragraph enumerates what the console takes beyond the index row switchport trunk allowed vlan <list|all>; it named only add <list> and remove <list> and closed with "Both are accepted by the console today". Since #2038 the console also takes except <list>, a verb that replaces the list instead of editing it, and the parser's own refusal names it: this console takes a list (10,20), a range (10-20), "all", "add <list>", "except <list>" or "remove <list>" (engine/cli.js:3199-3203). The same page documents except as "the third verb" in "A trunk's allowed list is edited in place", so the two paragraphs contradicted each other. #2038 updated docs/ARCHITECTURE.md and missed this one.

Evidence from the code. generic-switch, Fa0/1 in trunk mode:

sw1(config-if)#switchport trunk allowed vlan except 1,999
Trunk on Fa0/1 allows VLANs 2-998,1000-4094 (all but 1,999)

The _help() row is still switchport trunk allowed vlan <list|all>, so the gap between the index and the parser is real and is still the code's to close; the page now records all three verbs.

Guards (before == after; prose-only). scripts/syntax-check.js 430 files OK; check-control-bytes clean; docs-cli-transcript 4/0; docs-show-commands 7/0 (59 forms, 118 commands, 74 refusals); help-completeness 8/0 (102 advertised commands, 19 mechanisms, 16 shows); help-key-is-not-a-value 40/0; no-form-help-key 81/0; help-key-works-in-every-prompt 10 pass, 0 fail.

Docs-only; no code touched. Not done here: the help index still lacks except <list> and link state <linkId>, both accepted at the console — the index is the code's to complete.

**Doc:** `docs/CLI.md`, the paragraph under "`help` is an index, and a test reads it out of the parser". **What was untrue.** That paragraph enumerates what the console takes beyond the index row `switchport trunk allowed vlan <list|all>`; it named only `add <list>` and `remove <list>` and closed with "Both are accepted by the console today". Since #2038 the console also takes `except <list>`, a verb that replaces the list instead of editing it, and the parser's own refusal names it: `this console takes a list (10,20), a range (10-20), "all", "add <list>", "except <list>" or "remove <list>"` (`engine/cli.js:3199-3203`). The same page documents `except` as "the third verb" in "A trunk's allowed list is edited in place", so the two paragraphs contradicted each other. #2038 updated `docs/ARCHITECTURE.md` and missed this one. **Evidence from the code.** `generic-switch`, `Fa0/1` in trunk mode: ``` sw1(config-if)#switchport trunk allowed vlan except 1,999 Trunk on Fa0/1 allows VLANs 2-998,1000-4094 (all but 1,999) ``` The `_help()` row is still `switchport trunk allowed vlan <list|all>`, so the gap between the index and the parser is real and is still the code's to close; the page now records all three verbs. **Guards (before == after; prose-only).** `scripts/syntax-check.js` 430 files OK; `check-control-bytes` clean; `docs-cli-transcript` 4/0; `docs-show-commands` 7/0 (59 forms, 118 commands, 74 refusals); `help-completeness` 8/0 (102 advertised commands, 19 mechanisms, 16 shows); `help-key-is-not-a-value` 40/0; `no-form-help-key` 81/0; `help-key-works-in-every-prompt` 10 pass, 0 fail. Docs-only; no code touched. Not done here: the `help` index still lacks `except <list>` and `link state <linkId>`, both accepted at the console — the index is the code's to complete.
docs(CLI): the trunk's third verb is on the page's own list of accepted forms (#2038 follow-up)
All checks were successful
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
CI / Classify the change (pull_request) Successful in 6s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Successful in 55s
CI / Test (Node 22) (pull_request) Successful in 55s
CI / Test (Node 18) (pull_request) Successful in 1m0s
CI / Arm auto-merge (pull_request) Successful in 3s
d0dd6931ec
#2038 taught the console `switchport trunk allowed vlan except <list>` and updated
docs/ARCHITECTURE.md, but the paragraph in docs/CLI.md that enumerates what the
console takes beyond the `help` index row still named only `add <list>` and
`remove <list>` — and closed with "Both are accepted", a count that no longer
matches. The same page already documents `except` as "the third verb" a thousand
lines earlier, so the two paragraphs disagreed.

Verified at a switch (generic-switch, Fa0/1 in trunk mode):

  switchport trunk allowed vlan except 1,999
  Trunk on Fa0/1 allows VLANs 2-998,1000-4094 (all but 1,999)

and the parser's own refusal in engine/cli.js:3199-3203 names all three verbs
("all", "add <list>", "except <list>" or "remove <list>"). The index row in
_help() is still `switchport trunk allowed vlan <list|all>`, so the gap is real
and is still the code's to close — the page now records all three.
forgejo-actions scheduled this pull request to auto merge when all checks succeed 2026-11-19 00:00:20 +00:00
jaylouisw deleted branch docs/1118-2347 2026-11-19 00:38:05 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!2053
No description provided.