kdesc --rewrite from the reflection klammerset; txt caption rules the block's width

Assembled from klammertext-dev e99530408517. The katom rewrite patterns
are rendered from ref/ (a table in dispatch order, patterns through @c),
the procedural listing having left mac/; a plain-text caption's rule is
as long as the table or listing it captions; the editor-support comments
name the tools' new dev/ location.

ref/ref.k

@@ -48,3 +48,10 @@
 
 @@katom_descriptions.* ::
   @eval :cpp *KLAMMERTEXT_HOME*/ref/reflect katom_descriptions @ @@
+
+@@katom_rewrite_patterns.k :
+  Show the rewrite patterns for parsed text that is not a katom @@
+
+@@katom_rewrite_patterns.* ::
+  @eval :cpp *KLAMMERTEXT_HOME*/ref/reflect katom_rewrite_patterns @ @@
+

ref/reflect.cpp

@@ -194,6 +194,24 @@ std::string argtype_definitions(Machine& machine)
 }
 
 
+// Verbatim text as a table cell: a regex, a replacement string.  It goes
+// through @c, whose literal content is exempt from every special (a bar, a
+// hash, an at sign) -- but a literal value has its caret forms processed as
+// it is built, so a caret is written quoted: bare, "[^^@#|]+" would display
+// as "[^@#|]+" and "[@|#^:*]" would lose its caret to the colon.  The
+// exception is a caret before an apostrophe: "^'" is not a quoting form (it
+// opens a literal span elsewhere) and passes through as written.
+static std::string code_cell(const std::string& text)
+{
+    std::string quoted {};
+    for (size_t i = 0; i < text.size(); i++) {
+        const char c = text[i];
+        const bool before_apostrophe = i + 1 < text.size() && text[i + 1] == '\'';
+        quoted += (c == '^' && !before_apostrophe) ? "^^" : std::string(1, c);
+    }
+    return "@c :nd | " + quoted + " c@";
+}
+
 // The Regex cell of a katom type.  A type the Machine assigns is matched by
 // no regex and its cell is empty -- ws_added among them, whose m_pattern is a
 // description and not a regex (see the note in mac/katom_matching.cpp).  The
@@ -209,18 +227,7 @@ static std::string katom_regex_cell(const Ktype& k)
     if (k.m_type == katom_t::newline) {
         return "@t \\n @";
     }
-    // A literal value has its caret forms processed as it is built, so a
-    // caret is written quoted: bare, "[^^@#|]+" would display as "[^@#|]+"
-    // and "[@|#^:*]" would lose its caret to the colon.
-    // The exception is a caret before an apostrophe: "^'" is not a quoting
-    // form (it opens a literal span elsewhere) and passes through as written.
-    std::string quoted {};
-    for (size_t i = 0; i < k.m_pattern.size(); i++) {
-        const char c = k.m_pattern[i];
-        const bool before_apostrophe = i + 1 < k.m_pattern.size() && k.m_pattern[i + 1] == '\'';
-        quoted += (c == '^' && !before_apostrophe) ? "^^" : std::string(1, c);
-    }
-    return "@c :nd | " + quoted + " c@";
+    return code_cell(k.m_pattern);
 }
 
 extern "C"
@@ -290,3 +297,41 @@ characters can be displayed by the @t-kdesc command: @t kdesc -c -u @
     kt << rows.str() << "table@\n";
     return kt.str();
 }
+
+
+extern "C"
+std::string katom_rewrite_patterns([[maybe_unused]] Machine& machine)
+{
+    std::stringstream kt {};
+    kt << "@s2 Katom rewrite patterns @\n\n"
+       << R"(The table lists how a text is reformed or split into one or more katoms.
+ @i [Need a longer description here.] @
+
+)"
+       << "@table :caption The rewriting patterns for elements that are not katoms | "
+       << "Category | Description | Pattern | Replacement ||\n";
+
+    // Dispatch order, not declaration order: what a reader needs is the
+    // sequence the rules are actually TRIED in, since that is what decides
+    // which one fires.
+    rule_category shown {};
+    bool first = true;
+    std::string b = " | ";
+    for (size_t i : rule_order(rewrite_order::by_category)) {
+        const Rewrite_rule& rule = rewrite_rules[i];
+        std::string category = category_name(rule.category);
+        if (first || rule.category != shown) {
+            shown = rule.category;
+            first = false;
+        } else {
+            category = "";              // name a category once, at its head
+        }
+        std::string desc = rule.description;
+        desc[0] = static_cast<char>(toupper(desc[0]));
+        kt << category << b << desc << b << code_cell(rule.pattern.m_pattern) << b
+           << (rule.special ? "(hyphens separate word arguments)" : code_cell(rule.replacement))
+           << " ||\n";
+    }
+    kt << "table@\n";
+    return kt.str();
+}