jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1347 Commits
1 Branch
1 Tag
216 MiB
 
 
 
 
 
 
Tree: 29d606fb21
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '29d606fb21'
${ noResults }
punkshell/goals/G-149-punkargs-formhint-lab...

2.7 KiB
Raw Blame History

G-149 punk::args: configurable multi-form synopsis hint labels

Status: proposed Scope: src/modules/punk/args-999999.0a1.0.tm (usage/arg_error multi-form Synopsis hint column); src/tests/modules/punk/args/testsuites/args/ Goal: The per-form hint labels rendered beside a multi-form definition's Synopsis lines (hard-coded ' i -form N ...' today) are configurable - a definition or rendering caller can supply its own hint text (parameterized by form index/name) or suppress the column - so consumers whose users cannot type 'i' (script-level definitions like make.tcl's, whose (script) ids are unreachable from any repl) show an actionable hint, while unconfigured definitions keep the current repl-oriented default. Acceptance: a punk::args mechanism (definition directive and/or usage/arg_error caller option) replaces the ' i -form N ...' hint labels with caller-supplied text and can suppress the column entirely; unconfigured definitions render byte-identical to today (existing synopsis/usage/arg_error pins pass unchanged); the mechanism is pinned in the args testsuite. make.tcl adopting it (e.g a 'make.tcl help tool ' phrasing) is recorded as consumer follow-through after a bootsupport promotion, not part of this acceptance.

Context

Identified during G-143 (achieved 2026-08-01 - goals/archive/G-143-maketcl-multiform-help.md): multi-form usage tables render ' i -form N ...' beside each form's synopsis line, hard-coded in the renderer (bootsupport args-0.13.0.tm ~5475; same code in the dev module). The wording is repl-centric and doubly inapplicable in make.tcl output - 'i' is not a make.tcl surface, and (script)-scoped ids exist only inside a running make.tcl process, so no repl can address them. make.tcl meanwhile has its own per-form navigation the hint could name ('make.tcl help ' - G-143's dry-run help).

Notes

  • Related: G-050 (proposed) - synopsis argument-validity marking; same renderer surface, independent mechanism.
  • Related: G-056 (proposed) - display-time word wrapping for help content; sibling render-surface work.
  • Related: G-151 (proposed) - annotated success render; sibling punk::args render-surface goal drafted the same session.
  • Origin: G-144 (achieved 2026-08-01 - goals/archive/G-144-punkargs-synopsis-name-fallback.md) shipped the @cmd -name auto-synopsis lines these hints sit beside.
  • Overlap survey 2026-08-02: goals_xref paths src/modules/punk/args-999999.0a1.0.tm - the punkargs family (G-044 G-050 G-053 G-056 G-069 G-072 G-073 G-075 G-083 G-084 G-088); besides those named above the family entries are parser/spec mechanisms unrelated to the hint column. Consumer side: make.tcl's argdoc (src/AGENTS.md make.tcl bullet) after a bootsupport promotion.