Width and height argtypes, kdesc --argtypes from ref/, txt @define/@left_right/@columns, kdiag --check value validation (from dev d6993110e9b3)

Also: the klammertext argtype (descriptions kept as source), txt table
wrapping and :hpos/:offset, @c between ‹ ›, txt section headings, the
ktext newline-only trim, capitalize(), and the argtype test suite.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

tst/Makefile

@@ -19,6 +19,7 @@ test:
 	./katomize_test.sh
 	./filename_test.sh
 	./alone_test.sh
+	./argtype_test.sh
 	./state_test.sh
 	./target_test.sh
 	./modulepath_test.sh

tst/argtype_test.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+#
+# argtype_test.sh -- the @@@argtype description is Klammertext source
+# (engine tier: -k none, every definition inline).
+#
+# Decided 2026-09-13 (Andy): the second argument of @@@argtype has the
+# "klammertext" type, so Argtype::m_desc holds the description EXACTLY AS
+# WRITTEN --
+# a quoted "^@date" keeps its caret -- and whoever displays it hands the
+# text to a Machine (kdesc's listing through ref/, the Handbook).  Before,
+# the description was assembled from katom text, where the katomizer has
+# already stripped the caret of a quoted special, so "(^@date and
+# ^@datetime)" reached the generator as "(@date and @datetime)" and re-read
+# as two klammer applications.  A display that cannot render -- an argument
+# error -- shows the source unquoted instead.
+#
+# Note the neighbour: tst/argtype_test (no .sh) is the C++ diagnostic
+# program, the fourth such name collision after eval, state and target.
+#
+# Usage: ./argtype_test.sh   (needs KLAMMERTEXT_HOME set; ktext/kdiag on PATH)
+# Exit code: 0 if all tests pass, 1 otherwise.
+
+KTEXT="${KTEXT:-ktext}"; KDIAG="${KDIAG:-kdiag}"
+PASS=0; FAIL=0
+red=$'\033[31m'; green=$'\033[32m'; bold=$'\033[1m'; reset=$'\033[0m'
+pass() { echo "${green}PASS${reset} $1"; PASS=$((PASS+1)); }
+fail() { echo "${red}FAIL${reset} $1"; [ -n "$2" ] && echo "       $2"; FAIL=$((FAIL+1)); }
+flat() { tr '\n' ' ' | tr -s ' '; }   # error text is justified: match wrap-insensitively
+
+echo "${bold}@@@argtype description tests${reset}"
+echo "============================"
+echo
+
+DEF='@@@target tt | T @@@ @@@argtype lang | see ^@date and ^: here, ^| bar too :pattern [a-z][a-z] @@@'
+T=$(mktemp -d)
+
+# 1. The registry holds the source as written (kdiag --machine is the
+#    programmer's dump and shows the stored text).
+out=$("$KDIAG" --system --machine "$DEF" 2>&1 | flat)
+if echo "$out" | grep -qF 'see ^@date and ^: here, ^| bar too'; then pass " 1. the description is stored exactly as written (carets kept)"
+else fail " 1. the description is stored exactly as written (carets kept)" "$(echo "$out" | grep -o 'lang.\{0,60\}' | head -1)"; fi
+
+# 2. A quoted ":" inside the description does not start an option: the
+#    :pattern that follows is still the pattern (a valid value passes).
+out=$("$KTEXT" --klammersets none -s "$DEF @@w.k c.lang : W @@ @@w.tt :: [*c*] @@ @w de @" -t tt -d 2>&1 | flat)
+if echo "$out" | grep -qF '[de]'; then pass " 2. ^: in the description does not end it; :pattern still applies"
+else fail " 2. ^: in the description does not end it; :pattern still applies" "$out"; fi
+
+# 3. An invalid value's error shows the description UNQUOTED -- plain text
+#    for a reader who cannot render it.
+out=$("$KTEXT" --klammersets none -s "$DEF @@w.k c.lang : W @@ @@w.tt :: [*c*] @@ @w 123 @" -t tt -d 2>&1 | flat)
+if echo "$out" | grep -qF 'describes see @date and : here, | bar too'; then pass " 3. an argument error shows the description unquoted"
+else fail " 3. an argument error shows the description unquoted" "$out"; fi
+if ! echo "$out" | grep -qF '^@'; then pass " 4. ... and no caret leaks into the error"
+else fail " 4. ... and no caret leaks into the error"; fi
+
+# 5. A klammer's LITERAL parameter is a different type and is untouched:
+#    its "^" forms are processed ("^@" prints "@"), as they always were.  The application is in a
+#    FILE after the -s definitions: the literal-marking pass needs the
+#    klammer registered before the unit holding the application is read,
+#    and "--" ends the --klammersets list before the filename.
+printf '@lit ^@ and # and | x lit@\n' > "$T/lit.kt"
+out=$("$KTEXT" --klammersets none -s '@@@target tt | T @@@ @@lit.k t.literal : L @@ @@lit.tt :: [*t*] @@' -- "$T/lit.kt" -t tt -d 2>&1 | flat)
+if echo "$out" | grep -qF '[@ and # and | x]'; then pass " 5. the literal parameter of a klammer still holds its content as written"
+else fail " 5. the literal parameter of a klammer still holds its content as written" "$out"; fi
+
+rm -rf "$T"
+echo
+echo "============================"
+echo "Results: ${green}$PASS passed${reset}, ${red}$FAIL failed${reset}"
+[ $FAIL -eq 0 ]

tst/check_test.sh

@@ -209,6 +209,28 @@ check_clean "17. a correct document checks clean" \
 check_clean "18. the Standard Klammer Set checks clean" \
     "@read $K/sks/sks.k @"
 
+# Argument VALUES are checked against their argument types (2026-09-16):
+# the same test the engine applies at application time, run here on every
+# value that is LITERAL -- nothing but text -- so a height unit on a width,
+# or a word where a number is wanted, is found without rendering.  A value
+# holding a nested klammer, a *variable*, or a caret form is computed at run
+# time and is skipped: check what is fixed, not what is computed.
+W='@@@target tt | T @@@ @@@argtype em | a length in em :pattern \d+em @@@ @@f.k x.em :opt.em : F @@ @@f.tt :: [*x*] @@'
+check_finds "19. a literal positional value that fails its argument type" \
+    'does not match the "em" argument type' "$W @f 3px @"
+check_finds "20. ... and the argtype description is quoted" \
+    'a length in em' "$W @f 3px @"
+check_clean "21. a literal value that matches is clean" "$W @f 3em @"
+check_finds "22. a literal option value that fails its argument type" \
+    'does not match the "em" argument type' "$W @f 3em :opt 4 @"
+check_clean "23. an option written alone is not a value to check" "$W @f 3em :opt @"
+check_clean "24. a value holding a nested klammer is computed: skipped" \
+    "$W @@n : 3em @@ @f @n@ @"
+check_clean "25. a value holding a *variable* in a body is computed: skipped" \
+    "$W @@g.k v : G @@ @@g.tt :: @f *v* @ @@"
+check_clean "26. a value with a caret form is computed: skipped" \
+    "$W @f 3^:em @"
+
 echo
 echo "============================="
 echo "Results: ${green}$PASS passed${reset}, ${red}$FAIL failed${reset}"

tst/modulepath_test.sh

@@ -99,9 +99,13 @@ printf '@eval :cwd *K_input_dir* os.getcwd() @\n' > "$T/setb/pycwd.kt"
 check " 5. :cwd changes the Python working directory" \
       "$T/setb" "$T/setb/pycwd.kt"
 
+# The first @eval renders nothing, so the document begins with the space
+# the author wrote before the "/": ktext keeps it (it trims only newlines
+# from the result, as Machine::apply and the Python binding do -- a leading
+# space is the indent of a txt block that opens a document; TODO #60).
 printf '@eval :cwd *K_input_dir* :shell true @ / @eval :shell pwd @\n' > "$T/setb/restore.kt"
 check " 6. the cwd is restored after the eval" \
-      "/ $T/elsewhere" "$T/setb/restore.kt"
+      " / $T/elsewhere" "$T/setb/restore.kt"
 
 mkdir -p "$T/sp ace"
 printf 'spaced\n' > "$T/sp ace/f.txt"