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>

ref/ref.k

@@ -30,3 +30,9 @@
 
 @@unicode_examples.* ::
   @eval :cpp *KLAMMERTEXT_HOME*/ref/reflect unicode_examples @ @@
+
+@@argtype_definitions.k :
+  Show the defined klammer argument types @@
+
+@@argtype_definitions.* ::
+  @eval :cpp *KLAMMERTEXT_HOME*/ref/reflect argtype_definitions @ @@

ref/reflect.cpp

@@ -1,3 +1,5 @@
+#include <set>
+
 #include "machine.h"
 #include "character.h"
 #include "error.h"
@@ -53,7 +55,6 @@ std::string extended_latin_examples([[maybe_unused]] Machine& machine)
     return kt.str();
 }
 
-
 extern "C"
 std::string pinyin_examples([[maybe_unused]] Machine& machine)
 {
@@ -74,7 +75,7 @@ extern "C"
 std::string unicode_examples([[maybe_unused]] Machine& machine)
 {
     std::stringstream kt {};
-    kt << "\n@b Including Unicode in Klammertext files @\n\n"
+    kt << "\n@s2 Including Unicode in Klammertext files @\n\n"
        << "To specify a wide variety of different letter forms, the Unicode Standard "
        << "defines a large set of \"code points\" organized by groups.  To include a "
        << "Unicode character in Klammertext, you surround its hexadecimal number with "
@@ -83,8 +84,8 @@ std::string unicode_examples([[maybe_unused]] Machine& machine)
        << "To search for Unicode characters by their description, see: @nl@\n"
        << "@link https://www.fileformat.info/info/unicode/char/search.htm @\n\n";
 
-    kt << "@table :caption Examples of Chinese characters :cell_hpos c |\n"
-       << " Character | Unicode | Pinyin ||\n";
+    kt << "@table :caption Examples of Chinese characters :cell_hpos c c l |\n"
+       << " Character | Written | Pinyin ||\n";
 
     for (auto chr : dao) {
         std::string code = "^" + chr[1] + "^";
@@ -96,7 +97,7 @@ std::string unicode_examples([[maybe_unused]] Machine& machine)
 
 
     kt << "@table :caption Examples of Egyptian hieroglyphs :cell_hpos c c c l |\n"
-       << "Hieroglyph | Unicode | Sound | Gardiner ||\n";
+       << "Hieroglyph | Written | Sound | Gardiner ||\n";
 
     // The body font carries no hieroglyphs, so the glyph names the
     // typeface it needs (shipped in fnt/); @document declares and localizes
@@ -115,3 +116,51 @@ std::string unicode_examples([[maybe_unused]] Machine& machine)
 
     return kt.str();
 }
+
+extern "C"
+std::string argtype_definitions(Machine& machine)
+{
+    auto argtypes = machine.m_argtypes;
+    std::stringstream kt {};
+    std::set<std::string> custom {};
+
+    std::map<std::string, std::vector<std::string>> custom_types {};
+
+    kt << "@s2 Types of klammer arguments @\n\n"
+       << "@define :style r | \n";
+    // Hack to make the "Pattern:" label line up vertically;
+    // there should be a klammer that aligns text at "tab stops".
+    auto name_width = std::string("klammertext").size() + 1;
+    for (const auto& name : argtypes.m_names) {
+        auto argtype = argtypes.m_types.at(name);
+        auto filename = argtype.m_loc.m_filename;
+        if (contains(filename, "argtype_registry")) {
+            std::string fill(name_width - name.size(), '~');
+            kt << "\n@c " << name  << " c@ @t " << fill << " t@ @i Pattern: i@ @c "
+               << argtype.m_symbolic_pattern << " c@ |\n"
+               << capitalize(trim(argtype.m_desc)) << " ||\n";
+        } else {
+            custom.insert(filename);
+            custom_types[filename].push_back(name);
+        }
+    }
+    kt << "\ndefine@\n\n"
+       << "@vspace .5 @\n@s3 Reusing argtype symbols @\n\n"
+       << "A previously defined type can be included in the definition of a new type "
+       << "by surrounding the name of the existing type in single quotation marks. "
+       << "For example, the @c uint c@ type (unsigned integer) is used to define an integer with a "
+       << "`+' or `-' character before it.\n\n"
+       << "@vspace .5 @\n@s3 Custom argument types @\n\n"
+       << "Other argtypes are defined for special purposes for klammers defined in the following files:\n\n";
+
+    kt << "@define :style t |\n";
+    for (auto [filename, types] : custom_types) {
+        auto type_count = types.size();
+        int column_count = type_count < 4 ? 1 : int(float(type_count)/3);
+        // auto count = int(float(types.size()) / 3);
+        kt << symbolic_klammertext_filename(filename) << " |\n"
+           << "@columns :style c :n " << column_count << " | " << join(types, " ") << " @ ||\n\n";
+    }
+    kt << "define@\n\n";
+    return kt.str();
+}