From 97fede02546db2a0ff7de87b203426d8b9d6c2d3 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Wed, 5 Aug 2026 15:54:26 +1000 Subject: [PATCH] punkexe moduledoc 0.6.1: interim formhint suppression on the multi-form launcher definitions (script)::punkexe::script and ::tclsh declare '@cmd -formhint ""' (user direction 2026-08-05), suppressing the usage table's per-form hint labels under punk::args 0.17.0+ (older snapshots ignore the key and keep the ' i -form N ...' default - harmless). Rationale: the repl-oriented default is not typeable at the CLI where these tables render, and the (script) ids live in the boot interp - invisible to the repl's 'i'. A make.tcl-style actionable replacement does not exist: launcher help is deliberately subject-only (trailing words ignored - the prepend-help idiom, G-032 single-mechanism revision), so there is no per-form destination a hint could name, and a ' help ' pointer would be circular on the help path and redundant on the dispatch-error path (that table already shows all forms). Auto-selection cannot substitute either: the oneliner form's '-e' is dispatch-detected, not declared, and the file form's optional string scriptfile legitimately accepts '-e' (a file so named stays reachable as ./-e) - clean double-match, and expressing "any string except -e" needs G-072-class negation. Interim: if launcher help gains form-name narrowing ('help script oneliner' via usage -form, the G-150 cmdhelp precedent - candidate goal on request), the suppression becomes a real ' help %formname%' template. In-definition comments + the buildversion changelog record the decision. Verified on dev modules: no hint labels, Synopsis section and all four @form -synopsis lines intact for both ids. launcherhelp.test pins are presence/exit-code only - unaffected pre- and post-rebake; no kit-tier suppression pin added for an interim measure. _vfscommon.vfs picks up punkexe-0.6.1.tm (mint + vfscommonupdate; not in bootsupport's include list). Reaches kits at the user's selective rebakes. Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- .../punk/args/moduledoc/punkexe-999999.0a1.0.tm | 7 +++++++ .../punk/args/moduledoc/punkexe-buildversion.txt | 3 ++- .../{punkexe-0.6.0.tm => punkexe-0.6.1.tm} | 13 ++++++++++--- 3 files changed, 19 insertions(+), 4 deletions(-) rename src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/{punkexe-0.6.0.tm => punkexe-0.6.1.tm} (97%) diff --git a/src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm b/src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm index 328d06a4..7f67aa5d 100644 --- a/src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm +++ b/src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm @@ -196,9 +196,13 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::tclsh + #-formhint suppressed (empty): the ' i -form N ...' default is not typeable + #at the CLI where this renders, and launcher help is subject-only (no + #per-form narrowing to hint at). Interim until such narrowing exists. @cmd -name "punkexe tclsh" -& -summary -& "Run the punk executable as a (near) stock tclsh - no punk modules." -& + -formhint "" -& -help -& "Run the executable as a plain tclsh: no punk modules are loaded and behaviour matches stock 'tclsh' as closely as the kit boot @@ -311,9 +315,12 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::script + #-formhint suppressed (empty): as for tclsh above - no CLI 'i', no + #per-form help narrowing. Interim until such narrowing exists. @cmd -name "punkexe script" -& -summary -& "Run a script non-interactively in the punk script environment." -& + -formhint "" -& -help -& "Run a Tcl script and exit with an honest exit code (app-punkscript): script errors exit nonzero and the launch diff --git a/src/modules/punk/args/moduledoc/punkexe-buildversion.txt b/src/modules/punk/args/moduledoc/punkexe-buildversion.txt index 4da09923..7429fc3d 100644 --- a/src/modules/punk/args/moduledoc/punkexe-buildversion.txt +++ b/src/modules/punk/args/moduledoc/punkexe-buildversion.txt @@ -1,6 +1,7 @@ -0.6.0 +0.6.1 #First line must be a semantic version number #all other lines are ignored. +#0.6.1 - G-149-adjacent interim (user direction 2026-08-05): the two multi-form definitions ((script)::punkexe::script, ::tclsh) declare @cmd -formhint "" - the usage table's per-form hint labels are suppressed (renders under punk::args 0.17.0+; older snapshots ignore the key and show the ' i -form N ...' default). Rationale: the repl-oriented default is not typeable at the CLI where these tables render (and the (script) ids live in the boot interp, invisible to the repl's 'i'), while a make.tcl-style actionable replacement does not exist - launcher help is deliberately subject-only (trailing words ignored, the prepend-help idiom; G-032 single-mechanism revision), so there is no per-form destination a hint could name, and a ' help ' pointer would be circular on the help path and redundant on the dispatch-error path (that table already shows all forms). Interim: if launcher help gains form-name narrowing (candidate direction discussed 2026-08-05 - 'help script oneliner' via usage -form, the G-150 cmdhelp precedent), replace the suppression with a real ' help %formname%' template. #0.6.0 - single-mechanism revision (2026-08-05, user direction): all -help flag documentation withdrawn - 'help ?subcommand? ?arg ...?' is the sole help entry (trailing words accepted/ignored - the prepend-help idiom); (script)::punkexe::help gains the arg row + max -1; tclsh parity stated exception-free; per-subcommand -help paragraphs replaced with 'help ' pointers; buildinfo refuses help flags like any argument #0.5.0 - G-077 -e one-liner forms documented: (script)::punkexe::script gains the oneliner @form + -help paragraph; top-level (script)::punkexe documents the '-e' first-argument reclassification and gains its oneliner @form; (script)::punkexe::tclsh boundary text now points at the live forms #0.4.0 - G-032 launcher help/parse wiring live: help subcommand documented ((script)::punkexe::help + choices entry); top-level unknown-first-arg refusal rule + help discovery documented; per-subcommand first-arg -help notes (tclsh sole-arg carve-out); buildinfo argument-refusal shape; passthrough-vs-parsed decision recorded diff --git a/src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/punkexe-0.6.0.tm b/src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/punkexe-0.6.1.tm similarity index 97% rename from src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/punkexe-0.6.0.tm rename to src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/punkexe-0.6.1.tm index a6bda30c..4486dd7f 100644 --- a/src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/punkexe-0.6.0.tm +++ b/src/vfs/_vfscommon.vfs/modules/punk/args/moduledoc/punkexe-0.6.1.tm @@ -8,7 +8,7 @@ # (C) 2026 # # @@ Meta Begin -# Application punk::args::moduledoc::punkexe 0.6.0 +# Application punk::args::moduledoc::punkexe 0.6.1 # Meta platform tcl # Meta license BSD # @@ Meta End @@ -18,7 +18,7 @@ # doctools header # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ #*** !doctools -#[manpage_begin punkshell_module_punk::args::moduledoc::punkexe 0 0.6.0] +#[manpage_begin punkshell_module_punk::args::moduledoc::punkexe 0 0.6.1] #[copyright "2026"] #[titledesc {punk executable launch documentation}] [comment {-- Name section and table of contents description --}] #[moddesc {-}] [comment {-- Description at end of page heading --}] @@ -196,9 +196,13 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::tclsh + #-formhint suppressed (empty): the ' i -form N ...' default is not typeable + #at the CLI where this renders, and launcher help is subject-only (no + #per-form narrowing to hint at). Interim until such narrowing exists. @cmd -name "punkexe tclsh" -& -summary -& "Run the punk executable as a (near) stock tclsh - no punk modules." -& + -formhint "" -& -help -& "Run the executable as a plain tclsh: no punk modules are loaded and behaviour matches stock 'tclsh' as closely as the kit boot @@ -311,9 +315,12 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::script + #-formhint suppressed (empty): as for tclsh above - no CLI 'i', no + #per-form help narrowing. Interim until such narrowing exists. @cmd -name "punkexe script" -& -summary -& "Run a script non-interactively in the punk script environment." -& + -formhint "" -& -help -& "Run a Tcl script and exit with an honest exit code (app-punkscript): script errors exit nonzero and the launch @@ -534,7 +541,7 @@ namespace eval ::punk::args::register { package provide punk::args::moduledoc::punkexe [tcl::namespace::eval punk::args::moduledoc::punkexe { variable pkg punk::args::moduledoc::punkexe variable version - set version 0.6.0 + set version 0.6.1 }] return