From 12f9f16097f0e9168be71f4c545e2793ed727bcb Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sun, 12 Jul 2026 19:23:51 +1000 Subject: [PATCH] G-045 increment 2: punk 0.2.4 - i help renders aligned via -unindentedfields (project 0.12.5) ::punk::helptopic::define_docs now authors its help text at the left margin and declares -unindentedfields {-help} on the generated @cmd line (honoured as of punk::args 0.6.1, increment 1) and on the topic argument line (a gate that existed all along but was never applied here). Previously: the @cmd -help braced literal carried ~16 spaces of source indent into the constructed definition (constructed defs get no whole-block normalization, pinned P4 characterization), so the Description block rendered continuations +12 right of the first line; the \n-relative topic -help rendered its first line +4 (the injected display prefix). Both blocks now render flush. Help text content unchanged (manual ~70-col folding retained). Verified in punk902z src (arg_error render + i help end-to-end); punk::ns suite 53/53; make.tcl modules builds clean. Planning note recorded in the goal detail file: the constructed-def normalization increment picks its consumer proof (define_docs re-conversion vs ensemble_subcommands_definition) when it lands. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- CHANGELOG.md | 4 +++ goals/G-045-punkargs-authoring-ergonomics.md | 19 +++++++++++++- punkproject.toml | 2 +- src/modules/punk-999999.0a1.0.tm | 26 +++++++++++--------- src/modules/punk-buildversion.txt | 3 ++- 5 files changed, 40 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e99cc90..fe5527ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to Entries are newest-first; one bullet per notable change. See the root `AGENTS.md` "Project Versioning" section for the bump policy. +## [0.12.5] - 2026-07-12 + +- G-045 (increment): 'i help' usage table alignment fixed (punk 0.2.4) - the Description block's continuations no longer render indented +12 relative to the first line, and the topic argument's help first line no longer renders +4 relative to its continuations. ::punk::helptopic::define_docs authors help text at the left margin with -unindentedfields {-help} on the @cmd and topic lines. Help text content unchanged. + ## [0.12.4] - 2026-07-12 - G-045 (increment): punk::args 0.6.1 - the @cmd directive now honours -unindentedfields for -help, so command help authored at the left margin renders its first line flush with continuations in help/usage displays (previously the option was accepted on @cmd but ignored). No shipped definitions used it yet, so existing help rendering is unchanged; the define documentation states where -unindentedfields is valid. diff --git a/goals/G-045-punkargs-authoring-ergonomics.md b/goals/G-045-punkargs-authoring-ergonomics.md index 2461a3d3..056ea982 100644 --- a/goals/G-045-punkargs-authoring-ergonomics.md +++ b/goals/G-045-punkargs-authoring-ergonomics.md @@ -118,11 +118,28 @@ punk::imap4's {\Deleted}/{$MDNSent} choice values) have them stated, not just te 0 fail; punk::ns suite 53/53 (arg_error consumer); make.tcl modules builds clean. +### 2026-07-12 increment 2: 'i help' alignment via -unindentedfields (punk 0.2.4) + +- ::punk::helptopic::define_docs now authors its help text at the left margin + and declares -unindentedfields {-help} on the generated @cmd line (using + increment 1's gate) and on the topic argument line (a gate that existed all + along but was never applied here). Verified in punk902z src: the Description + block's +12 continuation leak and the topic Help first-line +4 are both gone; + 'i help' renders flush end-to-end. punk::ns suite 53/53; make.tcl modules + clean. +- Planning note: the constructed-def normalization increment's consumer proof + was to be define_docs "dropping manual pre-normalization". define_docs now + uses the documented -unindentedfields idiom (left-margin authoring), not a + hack - when normalization lands, either define_docs converts to + indented-plus-normalized authoring (likely nicer in a builder proc) or + ensemble_subcommands_definition serves as the proof; decide and record then. + Remaining for acceptance: - record-continuation mechanism (the -& candidate): collision rules, escape story, parses identically to backslash-continuation equivalent, documented - constructed-definition whole-block normalization opt-in, with rendering_constructed_def_indent_characterization expectations updated and - ::punk::helptopic::define_docs de-hacked as the consumer proof + a constructed-def consumer converted as proof (see increment 2 planning note + on define_docs vs ensemble_subcommands_definition) - defquoting.test container quoting rules promoted into the punk::args::define -help documentation diff --git a/punkproject.toml b/punkproject.toml index cf4764ba..397b5f24 100644 --- a/punkproject.toml +++ b/punkproject.toml @@ -1,4 +1,4 @@ [project] name = "punkshell" -version = "0.12.4" +version = "0.12.5" license = "BSD-2-Clause" diff --git a/src/modules/punk-999999.0a1.0.tm b/src/modules/punk-999999.0a1.0.tm index 3d6a77c1..ecd78450 100644 --- a/src/modules/punk-999999.0a1.0.tm +++ b/src/modules/punk-999999.0a1.0.tm @@ -8494,16 +8494,20 @@ namespace eval punk { } #keep help-text lines manually folded (~70 cols) - the usage tables don't yet #wrap to terminal width, so line lengths here directly set the table width + #help text is authored at the left margin and the @cmd/topic lines declare + #-unindentedfields {-help} (G-045): constructed definitions get no + #whole-block indent normalization, so source-indented authoring here would + #leak extra indent into the rendered help set basehelp {Help system for the punk shell. - With no arguments - an overview of some key shell - commands is displayed. - When the first argument is a recognised topic - help - for that topic is displayed. - ('help topics' lists the available topics) - Anything else is treated as a command name - basic - command info (type and synopsis) is shown for a - resolvable command, or the resolved path for an - external executable.} +With no arguments - an overview of some key shell +commands is displayed. +When the first argument is a recognised topic - help +for that topic is displayed. +('help topics' lists the available topics) +Anything else is treated as a command name - basic +command info (type and synopsis) is shown for a +resolvable command, or the resolved path for an +external executable.} set topichelp "Help topic, or command words for basic command info.\nTopics accept their aliases and unique prefixes\n(some short words deliberately fall through to command lookup)." set specs [list] lappend specs ::punk::help help "Punk shell help system." "" @@ -8511,9 +8515,9 @@ namespace eval punk { foreach {id name summary extra} $specs { set def "" append def "@id -id $id" \n - append def "@cmd -name $name -summary \"$summary\" -help \"$basehelp$extra\"" \n + append def "@cmd -name $name -summary \"$summary\" -unindentedfields {-help} -help \"$basehelp$extra\"" \n append def "@leaders -min 0 -max -1" \n - append def "topic -optional 1 -multiple 1 -type string -choiceprefix 1 -choicerestricted 0 -choicecolumns 2 -choices {$choices} -choicealiases {$choicealiases} -choiceprefixdenylist {$topic_prefixdenylist} -choiceprefixreservelist {$topic_prefixreservelist} -choiceinfo {$choiceinfo} -choicelabels {$choicelabels} -help \"$topichelp\"" \n + append def "topic -optional 1 -multiple 1 -type string -choiceprefix 1 -choicerestricted 0 -choicecolumns 2 -choices {$choices} -choicealiases {$choicealiases} -choiceprefixdenylist {$topic_prefixdenylist} -choiceprefixreservelist {$topic_prefixreservelist} -choiceinfo {$choiceinfo} -choicelabels {$choicelabels} -unindentedfields {-help} -help \"$topichelp\"" \n append def "@values -min 0 -max 0" if {[punk::args::id_exists $id]} { #quiet undefine - redefinition on registry change is expected, not noteworthy diff --git a/src/modules/punk-buildversion.txt b/src/modules/punk-buildversion.txt index f6928306..ac621bba 100644 --- a/src/modules/punk-buildversion.txt +++ b/src/modules/punk-buildversion.txt @@ -1,6 +1,7 @@ -0.2.3 +0.2.4 #First line must be a semantic version number #all other lines are ignored. +#0.2.4 - G-045: 'i help' usage table alignment - ::punk::helptopic::define_docs authors its help text at the left margin and declares -unindentedfields {-help} on both the generated @cmd line (honoured as of punk::args 0.6.1) and the topic argument line. Previously the @cmd -help braced literal carried ~16 spaces of source indent into the constructed definition (no whole-block normalization), rendering Description continuations +12 right of the first line, and the \n-relative topic -help rendered its first line +4 (the injected display prefix). Both blocks now render flush. Text content unchanged (manual ~70-col folding retained). #0.2.3 - punk::help topic definition adopts punk::args -choicealiases (G-040): choices are the four canonical topics with registry aliases folded ('i help' shows one entry per topic with an (alias:...) note), unique prefixes of topics and aliases accepted, minimum-prefix policy per user decision recorded in ::punk::helptopic (denylist {help}: h/he/hel stay command words; reservelist {c to tc}: fall through to command lookup); unrecognised words still fall through to basic command info; argless 'help' overview unchanged #0.2.2 - documentation-only: helptopic argdoc help texts manually folded (~70 cols) and the generated ::punk::help topic choices grid set to -choicecolumns 2 - 'i help'/'i help ' tables now render at reasonable widths (61-68 cols, was ~160); usage tables don't yet wrap to terminal width so source line lengths set table width; argless 'help' overview output unchanged (strict 80-col layout preserved) #0.2.1 - 'help tcl' warning scan extended to the has_libbug_* check family (bundled/vendored library bugs, e.g. the G-036 tcludp detection) alongside has_tclbug_*; buginfo 'url' key supported for reference links to non tcl-core trackers; fixed latent unset-indent error when a triggered check had a bugref/url but no description