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.
989 Commits
1 Branch
1 Tag
180 MiB
 
 
 
 
 
 
Tree: 9f4ff1db62
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '9f4ff1db62'
${ noResults }
punkshell/goals/G-088-textblock-table-foote...

3.5 KiB
Raw Blame History

G-088 textblock table footer block + bottom-edge subtitle (arg_error examples marker)

Status: proposed Scope: src/modules/textblock-999999.0a1.0.tm (class::table options and bottom border assembly), src/modules/punk/args-999999.0a1.0.tm (arg_error usage-table examples marker), src/tests/modules/punk/args/testsuites/args/examples.test + textblock table coverage Goal: The usage/error table can carry a short marker embedded in its bottom frame edge (a bottom-right examples indicator, the counterpart of the top 'Usage' title), backed by textblock::class::table gaining frame-parity -subtitle/-subtitlealign and footer row support with column spans independent of the body, as the header already has. Acceptance: textblock::class::table renders -subtitle with -subtitlealign left|centre|right in its bottom border whether or not footer rows are present; footer rows with independent colspans render via a configure_footer/footer_colspans API mirroring configure_header; arg_error embeds its @examples marker bottom-right through the subtitle and retires the interim 'Example:' header row - all pinned by tests.

Context

When a punk::args definition carries an @examples block, the usage/error table should advertise it without displaying the examples text itself. As of punk::args 0.12.5 this is an interim 'Example: eg ' header row (scheme colour CLR(check)). The desired display is a short marker embedded at the bottom-right of the table frame - the visual counterpart of the 'Usage' title embedded at the top - which the table class cannot currently render.

State of the table class (textblock::class::table, defined in the punk built-shell environment via textblock):

  • No -subtitle/-subtitlealign options. textblock::frame already has both (subtitle overtyped onto the bottombar via overtype::block with -blockalign, gx0-aware - see textblock frame implementation around the opt_subtitle bottombar handling).
  • Footer exists only as latent styling knobs (-show_footer, -ansibase_footer, -ansiborder_footer in opts_table_defaults); there are no footer-row methods - configure_header/header_colspans have no footer counterparts.

Approach

Two deliverables, deliberately severable:

  1. Bottom-edge subtitle (the near-term need). Add -subtitle/-subtitlealign to class::table with the same semantics as textblock::frame, overtyping the table's bottom border line the way frame treats its bottombar. This must work whether or not footer rows exist - the examples marker embedding must not depend on deliverable 2. arg_error then replaces the interim 'Example:' header row with -subtitle "eg " -subtitlealign right (scheme-coloured; raw id, not @cmd -name, which is display text and not always invocable).

  2. Footer block with independent spans (the fuller feature). configure_footer + footer_colspans mirroring the header API, so renderers can put row-structured content below the body with its own spans. The latent -*_footer styling options become live. When footer rows are present the subtitle embeds in the frame edge below them.

Notes

  • Origin: user direction 2026-07-17 during the @examples usage-table indication work (punk::args 0.12.5). The interim header row ships in 0.12.5 and is pinned by examples.test atexamples_eg_and_usage_row - that pin flips when this goal lands.
  • An alternative interim considered and rejected: post-processing the rendered table in arg_error by overtyping the last border line - workable but puts frame-drawing knowledge in a consumer; the table class is the right owner.