docs(cli): the help index has no row for the voice VLAN, and the allowed-list row stops at <list|all> #1984

Merged
jaylouisw merged 1 commit from docs/1118-1316 into main 2026-11-18 13:25:50 +00:00
Owner

The drift

docs/CLI.md argues that "a verb the console accepts and the index does not mention is a verb only its author knows about" and points at test/help-completeness.test.js as the check that closed #1491. That check compares the first word of a line against the dispatcher's vocabulary, so a keyword deeper in the line is invisible to it.

Two such keywords are accepted today and named nowhere in help:

accepted code in help?
switchport trunk allowed vlan add <list> / remove <list> engine/cli.js interface-mode dispatch (add/remove verbs) no - the index row reads `switchport trunk allowed vlan <list
switchport voice vlan <id> engine/cli.js t[0] === 'voice' && t[1] === 'vlan' no row at all

Evidence

Fresh session on an Aruba 2540 (port ge1):

sw1(config-if)#switchport voice vlan 20
Voice VLAN 20 on ge1
sw1(config-if)#switchport trunk allowed vlan add 30
Trunk on ge1 already allows all VLANs: "add" changes nothing

and show running-config prints switchport voice vlan 20 inside the interface block, so it is configured, stored and restored - just never indexed.

The fix

Docs-only: the "help is an index" section now records the gap in the words the page already uses for the traceroute max <n> row (indexed and not implemented) - the mirror image, accepted and not indexed. The index itself is the code's to complete.

## The drift `docs/CLI.md` argues that "a verb the console accepts and the index does not mention is a verb only its author knows about" and points at `test/help-completeness.test.js` as the check that closed #1491. That check compares the **first word** of a line against the dispatcher's vocabulary, so a keyword deeper in the line is invisible to it. Two such keywords are accepted today and named nowhere in `help`: | accepted | code | in `help`? | |---|---|---| | `switchport trunk allowed vlan add <list>` / `remove <list>` | `engine/cli.js` interface-mode dispatch (`add`/`remove` verbs) | no - the index row reads `switchport trunk allowed vlan <list|all>` | | `switchport voice vlan <id>` | `engine/cli.js` `t[0] === 'voice' && t[1] === 'vlan'` | no row at all | ## Evidence Fresh session on an Aruba 2540 (port `ge1`): ``` sw1(config-if)#switchport voice vlan 20 Voice VLAN 20 on ge1 sw1(config-if)#switchport trunk allowed vlan add 30 Trunk on ge1 already allows all VLANs: "add" changes nothing ``` and `show running-config` prints `switchport voice vlan 20` inside the interface block, so it is configured, stored and restored - just never indexed. ## The fix Docs-only: the "`help` is an index" section now records the gap in the words the page already uses for the traceroute `max <n>` row (indexed and not implemented) - the mirror image, accepted and not indexed. The index itself is the code's to complete.
docs(cli): the help index has no row for the voice VLAN, and the allowed-list row stops at <list|all>
All checks were successful
CI / Classify the change (pull_request) Successful in 6s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
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 52s
CI / Test (Node 22) (pull_request) Successful in 55s
CI / Test (Node 18) (pull_request) Successful in 59s
CI / Arm auto-merge (pull_request) Successful in 10s
19ebcc8a1e
The page's "help is an index" section says a verb the console accepts and the
index does not mention is a verb only its author knows about, and quotes the
guard that closed #1491. That guard compares the first word of a line against
the dispatcher's vocabulary, so a keyword further along the line is invisible
to it: engine/cli.js accepts `switchport trunk allowed vlan add <list>` and
`remove <list>` (the index row reads `<list|all>`) and `switchport voice vlan
<id>`, which has no row at all. `help` names neither. Recorded rather than
promised; the index is the code's to complete.
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!1984
No description provided.