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.
1476 Commits
1 Branch
1 Tag
230 MiB
 
 
 
 
 
 
Tree: b0f206f53b
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'b0f206f53b'
${ noResults }
punkshell/goals/G-169-app-owned-launch-docs.md

2.8 KiB
Raw Blame History

G-169 App-owned launch-subcommand documentation consumed by the launcher

Status: proposed Scope: src/lib/app-punkscript/punkscript.tcl (carries its subcommand's punk::args definition via inert registration); src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm (single-definer handover); src/vfs/_config/punkboot_core.tcl (built-in help resolution via app-owned ids, *_main.tcl declaration surface documented, + synced copies via established channels); src/tests/shell/testsuites/punkexe/launcherhelp.test Goal: A subcommand's punk::args definition can live in its handling app and the launcher consumes it - proven on app-punkscript owning (script)::punkexe::script (inert PUNKARGS registration, no load-time side effects, lazily resolved at help/error time) with the moduledoc entry handed over (one definer per id); the ownership rule is recorded (docs live with the owning code - app-owned for app-handled subcommands, moduledoc for core-owned surfaces like tclsh); and the existing *_main.tcl project-subcommand declaration surface (summary/package/argsid/parse) is documented as the official authoring mechanism it already is. Acceptance: app-punkscript carries the script definition and 'help script' renders it on a baked kit via lazy resolution (guarded package require + docpackages/argsid - no eager load at boot; help-path load cost measured and recorded); the punkexe moduledoc no longer defines the id (no duplicate-definition warnings; single definer verified); degraded/plain help path intact; the *_main.tcl declaration keys are documented where kit authors look (location decided in the work: core header contract + a durable doc) including the parse=1 gate; launcherhelp.test passes with a new app-owned-resolution pin.

Context

2026-08-05 discussion: the actual '-e' parsing lives in app-punkscript while its documentation lives in the punkexe moduledoc - co-location kills that drift class. Nothing structural prevents launcher consumption of app-owned docs: the argsid+package indirection and parse=1 gate already exist for project subcommands (punkboot_core.tcl:1779-1791, 2168-2192), and punk::args 0.12.7's docpackages association loads a documenting package lazily on first usage query. The moduledoc pattern remains right where implementation is external or core-owned (tclcore precedent: separation + parity pins).

Notes

  • Coordination with G-168: either order works; whichever lands second edits the definition at its then-current home (never two definers).
  • Related: G-075 (proposed) - sibling documentation-reachability surface.
  • Related: G-042/G-043 (proposed) - adjacent declaration-composition patterns; deliberate non-overlap (launch surface, not repl subshells).
  • Overlap survey 2026-08-05: app-punkscript intersects no live goals; the punkboot_core.tcl matches are the G-168 survey's set (G-089 nearest, others incidental).