jn
/
punkshell
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

punk 0.2.2: fold help argdoc texts, narrow 'i help' tables (doc-only) 

From interactive review of the help restructure: 'i help' / 'i help <topic>'
usage tables rendered ~160 columns wide. Only the argless 'help' overview is
strictly 80-column - but the rest should stay reasonable, and the usage tables
do not yet wrap to terminal width, so punk::args source line lengths directly
set table width.

- helptopic argdoc help texts manually folded at ~70 columns ('help tcl' was
  the worst offender at ~230 chars on one line)
- generated ::punk::help/::punk::help_chunks definitions: basehelp/topichelp/
  chunks-note folded; topic choice grid rendered with -choicecolumns 2 (the
  largest width contributor)
- dynamically built definitions don't get the file-sourced indentation
  normalization - topichelp's continuation over-indented, fixed with an
  explicit \n join
- results: i help 68 cols, per-topic 61-65; argless 'help' output byte-
  identical to the strict-80 baseline; punk/ns 26 and punk/args 93+1 suites
  pass
- future improvement noted in CHANGELOG: automated (potentially language-
  dependent) wrapping of help text to available width, e.g. via tcllib's
  text-adjust facilities
- project 0.4.9 (CHANGELOG entry)

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
master
Julian Noble 7 days ago
parent
0505397590
commit
4b591e4e36
4 changed files with 48 additions and 13 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 4
      CHANGELOG.md
  2. 2
      punkproject.toml
  3. 52
      src/modules/punk-999999.0a1.0.tm
  4. 3
      src/modules/punk-buildversion.txt

4
CHANGELOG.md
Unescape View File

@ -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.4.9] - 2026-07-08
- punk 0.2.2 (doc-only, from interactive review of the help restructure): `i help` / `i help <topic>` usage tables narrowed to reasonable widths (61-68 columns, previously ~160) by manually folding the helptopic argdoc help texts at ~70 columns and rendering the generated topic-choice grid with `-choicecolumns 2`. Only the argless `help` overview is strictly 80-column (unchanged, byte-identical); usage tables do not yet wrap to terminal width, so punk::args source line lengths directly set table width — automated (potentially language-dependent) wrapping, e.g. via tcllib's text-adjust facilities, is a possible future improvement.
## [0.4.8] - 2026-07-08
- G-037 completed (flipped to achieved): new `make.tcl vfslibs` step (also run inside `make.tcl project`) propagates declared vendored platform-library packages into kit vfs lib_tcl<N> trees — declarations in `src/runtime/vendorlib_vfs.toml` (tomlish-parsed, per-package per-kit with explicit `supersedes` removal so no silent mixed-version provision; punkcheck provenance at src/vfs/.punkcheck, outside kit payloads; malformed entries fail the build naming the entry). G-024's mapvfs toml conversion was not required; the file is recorded as a candidate for absorption into it. Authority is the declaration — undeclared drift (e.g. the vendorlib/kit twapi divergence) is deliberately untouched.

2
punkproject.toml
Unescape View File

@ -1,3 +1,3 @@
[project]
name = "punkshell"
version = "0.4.8"
version = "0.4.9"

52
src/modules/punk-999999.0a1.0.tm
Unescape View File

@ -8476,23 +8476,28 @@ namespace eval punk {
dict set choicelabels $name [dict get $tinfo summary]
}
}
#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
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.
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
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. (topics must match exactly - no prefix matching)}
set topichelp "Help topic, or command words for basic command info.\n(topics must match exactly - no prefix matching)"
set specs [list]
lappend specs ::punk::help help "Punk shell help system." ""
lappend specs ::punk::help_chunks punk::help_chunks "Punk shell help system - content as {channel text} chunks." "\n\nhelp_chunks returns the help content as a list of {channel text} chunks rather than emitting it."
lappend specs ::punk::help_chunks punk::help_chunks "Punk shell help system - content as {channel text} chunks." "\n\nhelp_chunks returns the help content as a list of\n{channel text} chunks rather than emitting it."
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 "@leaders -min 0 -max -1" \n
append def "topic -optional 1 -multiple 1 -type string -choiceprefix 0 -choicerestricted 0 -choices {$choices} -choiceinfo {$choiceinfo} -choicelabels {$choicelabels} -help \"$topichelp\"" \n
append def "topic -optional 1 -multiple 1 -type string -choiceprefix 0 -choicerestricted 0 -choicecolumns 2 -choices {$choices} -choiceinfo {$choiceinfo} -choicelabels {$choicelabels} -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
@ -8548,7 +8553,12 @@ namespace eval punk {
punk::args::define {
@id -id ::punk::helptopic::topics
@cmd -name "help topics" -summary "List help topics." -help "Show the table of topics known to the help system, including registered aliases for each topic."
@cmd -name "help topics"\
-summary\
"List help topics."\
-help\
"Show the table of topics known to the help system,
including registered aliases for each topic."
@values -min 0 -max 0
}
proc topics {context args} {
@ -8570,7 +8580,15 @@ namespace eval punk {
punk::args::define {
@id -id ::punk::helptopic::tcl
@cmd -name "help tcl" -summary "Tcl version warnings." -help "Show the running Tcl patchlevel and build-info, with warnings for known Tcl bugs affecting this interpreter and known bugs in bundled library packages (as detected by the punk::lib::check::has_tclbug_* and has_libbug_* checks)."
@cmd -name "help tcl"\
-summary\
"Tcl version warnings."\
-help\
"Show the running Tcl patchlevel and build-info, with
warnings for known Tcl bugs affecting this interpreter
and known bugs in bundled library packages
(as detected by the punk::lib::check::has_tclbug_*
and has_libbug_* checks)."
@values -min 0 -max 0
}
proc tcl {context args} {
@ -8629,7 +8647,12 @@ namespace eval punk {
punk::args::define {
@id -id ::punk::helptopic::env
@cmd -name "help env" -summary "punkshell environment vars." -help "Show punk-related and other relevant environment variables with their current values."
@cmd -name "help env"\
-summary\
"punkshell environment vars."\
-help\
"Show punk-related and other relevant environment
variables with their current values."
@values -min 0 -max 0
}
proc env {context args} {
@ -8730,7 +8753,14 @@ namespace eval punk {
punk::args::define {
@id -id ::punk::helptopic::console
@cmd -name "help console" -summary "Console behaviour tests and warnings." -help "Run some console/terminal behaviour tests (control string hiding, grapheme cluster support, cursor position query timing) and report warnings. Requires a responsive interactive console."
@cmd -name "help console"\
-summary\
"Console behaviour tests and warnings."\
-help\
"Run some console/terminal behaviour tests (control
string hiding, grapheme cluster support, cursor
position query timing) and report warnings.
Requires a responsive interactive console."
@values -min 0 -max 0
}
proc console {context args} {

3
src/modules/punk-buildversion.txt
Unescape View File

@ -1,5 +1,6 @@
0.2.1
0.2.2
#First line must be a semantic version number
#all other lines are ignored.
#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 <topic>' 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
#0.2.0 - help system restructured onto a topic registry (::punk::helptopic: register/resolve, per-topic handler procs each with a punk::args definition); ::punk::help and ::punk::help_chunks punk::args definitions (re)generated from the registry so 'i help' / 'i help <topic>' render documented usage; 'help topics' derived from the registry; command-fallthrough and no-arg overview output unchanged; 'help env' degrades cleanly when punk::config is not initialised; help table objects destroyed after printing (leak fix)

Write Preview
Loading…
Cancel
Save