From 8cc7d42634a779b2c7259f7aa33024d8e7ca8aea Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 4 Aug 2026 01:12:50 +1000 Subject: [PATCH] punkexe moduledoc layout fixes and -& record continuations --- .../args/moduledoc/punkexe-999999.0a1.0.tm | 118 +++++++++--------- 1 file changed, 59 insertions(+), 59 deletions(-) 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 407ec228..f86a15b2 100644 --- a/src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm +++ b/src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm @@ -84,10 +84,10 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe - @cmd -name punkexe\ - -summary\ - "punk executable launch: package modes and subcommand dispatch."\ - -help\ + @cmd -name punkexe -& + -summary -& + "punk executable launch: package modes and subcommand dispatch." -& + -help -& "Launch surface of the punk shell executables ('' below stands for any punk kit executable, e.g punk905, or a generated project's kit). @@ -129,7 +129,7 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { per-kit table is the authority for a given executable." @form -synopsis " ?packagemode? ?subcommand? ?arg ...?" @leaders -min 0 -max 2 - packagemode -type string -optional 1 -default internal -help\ + packagemode -type string -optional 1 -default internal -help -& "Package-source mode: an ordered dash-separated list of path blocks, optionally scoped with the 'proj:' prefix. Blocks (each adds a group of module/library paths): @@ -155,7 +155,7 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { ties (faithful to the project's snapshot vintage) The launch reports the detected project root and effective precedence." - subcommand -type string -optional 1 -choicerestricted 0 -choices {tclsh script shell punk shellspy buildinfo help} -choicelabels { + subcommand -type string -optional 1 -choicerestricted 0 -choicecolumns 1 -choices {tclsh script shell punk shellspy buildinfo help} -choicelabels { tclsh " Run as a (near) stock tclsh - no punk modules loaded." script @@ -170,11 +170,11 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { " Print the kit's build/identity stamp report and exit (G-025)." help " Show usage for the launch surface or one of its subcommands (G-032)." - } -help\ + } -help -& "Subcommand to run. Each subcommand's own contract is documented under its definition id (script)::punkexe::." @values -min 0 -max -1 - arg -type any -optional 1 -multiple 1 -help\ + arg -type any -optional 1 -multiple 1 -help -& "Arguments for the selected subcommand." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- @@ -188,10 +188,10 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::tclsh - @cmd -name "punkexe tclsh"\ - -summary\ - "Run the punk executable as a (near) stock tclsh - no punk modules."\ - -help\ + @cmd -name "punkexe tclsh" -& + -summary -& + "Run the punk executable as a (near) stock tclsh - no punk modules." -& + -help -& "Run the executable as a plain tclsh: no punk modules are loaded and behaviour matches stock 'tclsh' as closely as the kit boot allows. The subcommand is an EXTENSION of standard tclsh @@ -267,28 +267,28 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { @form -form {scriptfile} -synopsis " tclsh ?-encoding name? scriptfile ?arg ...?" @leaders -min 0 -max 0 @opts - -encoding -type string -optional 1 -typesynopsis name -help\ + -encoding -type string -optional 1 -typesynopsis name -help -& "Encoding used to read scriptfile (as for 'source -encoding'). - Recognised only immediately after 'tclsh' and only when the - following argument does not begin with '-'; an incomplete - -encoding form falls through to the no-script form (stock - behaviour)." + Recognised only immediately after 'tclsh' and only when the + following argument does not begin with '-'; an incomplete + -encoding form falls through to the no-script form (stock + behaviour)." @values -min 1 -max -1 - scriptfile -type string -optional 0 -help\ + scriptfile -type string -optional 0 -help -& "Script file to source and exit. ::argv0 and 'info script' are - the (normalized) script path; remaining args are ::argv. The - script may set ::tclsh(dorepl) 1 (piperepl runtimes) to enter - the interactive repl after it completes." - arg -type any -optional 1 -multiple 1 -help\ + the (normalized) script path; remaining args are ::argv. The + script may set ::tclsh(dorepl) 1 (piperepl runtimes) to enter + the interactive repl after it completes." + arg -type any -optional 1 -multiple 1 -help -& "Arguments passed to the script in ::argv." @form -form {stdin} -synopsis " tclsh ?arg ...?" @values -min 0 -max -1 - arg -type any -optional 1 -multiple 1 -help\ + arg -type any -optional 1 -multiple 1 -help -& "With no script file all arguments (including any leading '-' - arguments) stay in ::argv; ::argv0 is the executable path. - Input comes from stdin: the interactive repl on a console - (piperepl runtimes), evaluation of piped input otherwise." + arguments) stay in ::argv; ::argv0 is the executable path. + Input comes from stdin: the interactive repl on a console + (piperepl runtimes), evaluation of piped input otherwise." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- @@ -301,10 +301,10 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::script - @cmd -name "punkexe script"\ - -summary\ - "Run a script non-interactively in the punk script environment."\ - -help\ + @cmd -name "punkexe script" -& + -summary -& + "Run a script non-interactively in the punk script environment." -& + -help -& "Run a Tcl script and exit with an honest exit code (app-punkscript): script errors exit nonzero and the launch plumbing emits nothing of its own on stdout/stderr, so @@ -323,19 +323,19 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { ordinary script argument." @form -synopsis " script ?scriptfile|lib:name? ?arg ...?" @values -min 0 -max -1 - scriptfile -type string -optional 1 -help\ + scriptfile -type string -optional 1 -help -& "Script file path, or lib:name for scriptlib resolution. - Omitted: the script is read from piped stdin." - arg -type any -optional 1 -multiple 1 -help\ + Omitted: the script is read from piped stdin." + arg -type any -optional 1 -multiple 1 -help -& "Arguments passed to the script in ::argv." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::shell - @cmd -name "punkexe shell"\ - -summary\ - "Interactive punk shell (repl)."\ - -help\ + @cmd -name "punkexe shell" -& + -summary -& + "Interactive punk shell (repl)." -& + -help -& "Launch the interactive punk shell (app-punkshell). With arguments, a script can be run first with the interactive shell maintained afterwards. This is also the default when the @@ -344,16 +344,16 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { usage and exits 0 (G-032)." @form -synopsis " shell ?arg ...?" @values -min 0 -max -1 - arg -type any -optional 1 -multiple 1 -help\ + arg -type any -optional 1 -multiple 1 -help -& "Arguments passed through to the shell launch." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::punk - @cmd -name "punkexe punk"\ - -summary\ - "punk shell launch; piped-stdin friendly."\ - -help\ + @cmd -name "punkexe punk" -& + -summary -& + "punk shell launch; piped-stdin friendly." -& + -help -& "Launch the punk shell. With arguments the app-punkshell launch path is used (as for 'shell'); without arguments the interactive shell is launched directly. Commands piped into @@ -364,16 +364,16 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { usage and exits 0 (G-032)." @form -synopsis " punk ?arg ...?" @values -min 0 -max -1 - arg -type any -optional 1 -multiple 1 -help\ + arg -type any -optional 1 -multiple 1 -help -& "Arguments passed through to the shell launch." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::shellspy - @cmd -name "punkexe shellspy"\ - -summary\ - "Experimental shellspy command-line processor."\ - -help\ + @cmd -name "punkexe shellspy" -& + -summary -& + "Experimental shellspy command-line processor." -& + -help -& "Pass all arguments to the experimental shellspy command-line processor (app-shellspy). Note: 'shellspy' is only this launch subcommand - it is not the project name (the project is @@ -382,7 +382,7 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { usage and exits 0 (G-032)." @form -synopsis " shellspy ?arg ...?" @values -min 0 -max -1 - arg -type any -optional 1 -multiple 1 -help\ + arg -type any -optional 1 -multiple 1 -help -& "Arguments for the shellspy processor." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- @@ -395,10 +395,10 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::buildinfo - @cmd -name "punkexe buildinfo"\ - -summary\ - "Print the kit's build/identity report and exit (G-025)."\ - -help\ + @cmd -name "punkexe buildinfo" -& + -summary -& + "Print the kit's build/identity report and exit (G-025)." -& + -help -& "Print a machine-parseable build/identity report on stdout and exit 0 - no repl fallthrough, nothing else on stdout, so the output is usable by exec-style and piped callers. @@ -438,10 +438,10 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { # -- --- --- --- --- --- --- --- --- --- --- --- --- --- lappend PUNKARGS [list { @id -id (script)::punkexe::help - @cmd -name "punkexe help"\ - -summary\ - "Show usage for the launch surface or one of its subcommands (G-032)."\ - -help\ + @cmd -name "punkexe help" -& + -summary -& + "Show usage for the launch surface or one of its subcommands (G-032)." -& + -help -& "Render launch usage on stdout and exit 0 (G-032). With no argument: the top-level table - the package modes and @@ -473,10 +473,10 @@ tcl::namespace::eval punk::args::moduledoc::punkexe { actual subcommand set." @form -synopsis " help ?subcommand?" @values -min 0 -max 1 - subject -type string -optional 1 -choices {tclsh script shell punk shellspy buildinfo help} -help\ + subject -type string -optional 1 -choices {tclsh script shell punk shellspy buildinfo help} -help -& "Subcommand to show usage for. In a kit the valid choices are - the live launch surface: the built-ins plus any - project-registered subcommands." + the live launch surface: the built-ins plus any + project-registered subcommands." }] # -- --- --- --- --- --- --- --- --- --- --- --- --- --- }