diff --git a/src/scriptapps/tools/punkargs_punknative.tcl b/src/scriptapps/tools/punkargs_punknative.tcl
index 9cbd0200..d1ad20dc 100644
--- a/src/scriptapps/tools/punkargs_punknative.tcl
+++ b/src/scriptapps/tools/punkargs_punknative.tcl
@@ -48,6 +48,7 @@ foreach libdir [list [file normalize $project_root/src/bootsupport/lib] [file no
if {$libdir ni $::auto_path} {lappend ::auto_path $libdir}
}
package require punk::args
+package require punk::lib ;#punk::args::lib::tstr placeholder resolution uses punk::lib::undent
package require punk::ansi
lassign $argv pkgname outdir
@@ -102,7 +103,12 @@ namespace eval ansi2html {
#666666 #f14c4c #23d18b #f5f543 #3b8eea #d670d6 #29b8db #ffffff
}
variable default_fg "#d4d4d4"
- variable default_bg "#1e1e1e"
+ #terminal backdrop for rendered blocks: BLACK. overtype::renderspace
+ #overlay output uses explicit SGR 40 (black bg) and art/example helpers
+ #treat 'default background' as the terminal's - on a black pre they blend
+ #exactly as in a black terminal (a grey pre showed contrasting black bars
+ #inside example blocks). The page body stays lighter for contrast.
+ variable default_bg "#000000"
proc color256 {n} {
variable pal16
@@ -346,8 +352,11 @@ set fontstack "'Cascadia Mono','Cascadia Code','DejaVu Sans Mono','Noto Sans Mon
if {$fontface ne ""} {
set fontstack "'punkdoc-mono',$fontstack"
}
-append html "body {background:$ansi2html::default_bg; color:$ansi2html::default_fg; font-family:$fontstack;}\n"
-append html "h1,h2 {font-family:inherit; color:#e5e510;}\n"
+append html "body {background:#1e1e1e; color:$ansi2html::default_fg; font-family:$fontstack;}\n"
+append html "h1,h2,h3 {font-family:inherit; color:#e5e510;}\n"
+append html "nav.cmdindex {background:#000; padding:8px 12px; display:inline-block;}\n"
+append html "nav.cmdindex a {color:#29b8db; text-decoration:none; display:inline-block; margin-right:1.5em;}\n"
+append html "nav.cmdindex a:hover {text-decoration:underline;}\n"
#IMPORTANT: pre needs its own font-family - the UA stylesheet's
#'pre {font-family:monospace}' overrides inheritance from body, so without
#this the pre renders in the browser's default mono font regardless of the
@@ -355,13 +364,84 @@ append html "h1,h2 {font-family:inherit; color:#e5e510;}\n"
#punkdoc-mono cell geometry (see fontprep/README.md): advance is exactly
#0.5859375em - font-size 15.36px gives an integer 9px cell width (fractional
#advances round differently at styled-span boundaries -> vertical seams
-#through block/border glyphs). If the font stack falls back past
-#punkdoc-mono this exactness is lost but text-only content tolerates it.
-append html "pre.punkterm {font-family:$fontstack; line-height:1.15; font-size:15.36px; overflow-x:auto; padding:8px; background:$ansi2html::default_bg; font-variant-ligatures:none;}\n"
+#through block/border glyphs). Row pitch: browsers size inline BACKGROUNDS
+#to the font's hhea content area = 1.1621em = 17.85px here; a fractional
+#pitch (1.15em = 17.664px) put row boundaries at fractional positions and
+#showed periodic hairline gaps through solid-bg runs (~every 2 lines).
+#line-height:17px = integer pitch just under the bg height, so adjacent
+#rows' backgrounds overlap ~0.85px - sealed at any zoom/dpi (cost: bg rows
+#overpaint <1px of the row above's descenders - imperceptible in tables).
+#If the font stack falls back past punkdoc-mono this exactness is lost but
+#text-only content tolerates it.
+append html "pre.punkterm {font-family:$fontstack; line-height:17px; font-size:15.36px; overflow-x:auto; padding:8px; background:$ansi2html::default_bg; font-variant-ligatures:none;}\n"
append html "hr {border:0; border-top:1px solid #444;}\n"
append html "\n"
append html "
$pkgname $pkgversion
\n"
append html "
Command reference generated from punk::args definitions (terminal-faithful rendering).
\n"
+
+#module/package-level info when @package directives are registered (none in
+#older module versions - the hook is here for when dev modules surface them)
+set package_notes [list]
+foreach id $cmd_ids {
+ set spec [punk::args::get_spec $id]
+ #package_info key absent in older punk::args spec dicts (pre-@package)
+ if {![dict exists $spec package_info]} {break}
+ set pinfo [dict get $spec package_info]
+ if {[llength $pinfo] && $pinfo ni $package_notes} {
+ lappend package_notes $pinfo
+ }
+}
+foreach pinfo $package_notes {
+ append html "
\n"
+}
+
+#command index navigation (doctools-style jump list)
+append html "\n"
+
+#helper: one converted usage block.
+#-trim 1: keep only the Arg table (from its header separator down) - used for
+#per-form blocks so they don't repeat the whole command/description/synopsis
+#panel and drown the per-form differences (renderspace output lines are
+#colour-self-contained, so slicing at a line boundary is safe)
+proc usage_block {id args} {
+ global boxmap
+ set trim 0
+ set idx [lsearch -exact $args -trim]
+ if {$idx >= 0} {
+ set trim [lindex $args $idx+1]
+ set args [lreplace $args $idx $idx+1]
+ }
+ if {[catch {punk::args::usage {*}$args $id} u]} {
+ return "
(no usage rendering: [ansi2html::html_escape $u])
\n"
+ }
+ if {$trim} {
+ set lines [split $u \n]
+ set argidx -1
+ set i 0
+ foreach ln $lines {
+ if {[string match "┃Arg *" [punk::ansi::ansistrip $ln]]} {
+ set argidx $i
+ break
+ }
+ incr i
+ }
+ if {$argidx > 0} {
+ #include the separator line above the Arg header as the top border
+ set u [join [lrange $lines $argidx-1 end] \n]
+ }
+ }
+ if {$boxmap eq "light"} {
+ set u [ansi2html::to_lightbox $u]
+ }
+ return "
[ansi2html::convert $u]
\n"
+}
+
foreach id $cmd_ids {
set cmdname [string trimleft $id :]
append html "
$cmdname
\n"
@@ -369,14 +449,24 @@ foreach id $cmd_ids {
if {$aliastarget ne ""} {
append html "
Takes the same arguments as [ansi2html::html_escape [string trimleft $aliastarget :]] (shared argument definition).
\n"
}
- if {[catch {punk::args::usage $id} u]} {
- append html "
(no usage rendering: [ansi2html::html_escape $u])
\n"
- continue
- }
- if {$boxmap eq "light"} {
- set u [ansi2html::to_lightbox $u]
+ #the default usage table shows description + all form synopses, but for
+ #multiform commands its Arg table covers only the default form - render
+ #an additional per-form ARG TABLE (trimmed - no repeated header panel)
+ #for each form that has arguments (mirrors 'i -form N ').
+ append html [usage_block $id]
+ set spec [punk::args::get_spec $id]
+ set formnames [dict get $spec form_names]
+ if {[llength $formnames] > 1} {
+ foreach formname $formnames {
+ set form [dict get $spec FORMS $formname]
+ if {![dict size [dict get $form ARG_INFO]]} {
+ #form takes no arguments - the synopsis line says it all
+ continue
+ }
+ append html "
form: [ansi2html::html_escape $formname]
\n"
+ append html [usage_block $id -form $formname -trim 1]
+ }
}
- append html "