Unicode sequences, @typeface, and the font/typeface distinction

A run of Unicode code points now needs one pair of carets, not one pair
each: ^9053 53EF 9053^ renders the characters adjacently, and a single
character inside such a run stands for itself.  An invalid code point is
an error naming the position that wrote it, rather than an apology
rendered into the finished document; noncharacters are refused alongside
surrogates; and a code point that lands on a Klammertext special is safe
through the re-reads that assemble a document.  The character tables now
produce the precomposed form, so a diacritic written as ^a" and one typed
directly are the same text to a search or a copy-paste.

"kdesc -u" describes how to write a Unicode character, with tables of
glyphs beside the codes that produce them.  It is new and not yet
complete: it predates the sequence form and the typeface klammer below.

A typeface and a style are no longer both called "font".  A typeface is a
family resolved by name; a style code is the one letter naming a type
style.  So @document takes :serif_typeface and its siblings, a table takes
:style, captions take :caption_style and :caption_size, the uniform scale
is :text_scale, and the command is "kdesc --typeface".  This renames
arguments a document may already use; an old name is a located error
rather than a silent omission.

@typeface sets a passage in another typeface for the length of that
passage:

    @typeface Noto Sans Egyptian Hieroglyphs | ^132AA 133CF^ :scale 1.5 @

Writing the klammer is the whole declaration -- the document resolves the
typeface, embeds it in what it produces, and carries its license along.
Two typefaces for scripts no text font covers now ship with Klammertext:
Noto Sans Egyptian Hieroglyphs and Noto Sans Cuneiform.  Every typeface in
the distribution now carries its license file.

(from dev 61e598698891)

mac/character.h

@@ -11,6 +11,8 @@
 #include <regex>
 #include <unistd.h>
 
+#include "locator.h"
+
 // ^UUUU^ — a Unicode code point in hex, 4 to 6 digits (^263A^ is the BMP,
 // ^13000^ EGYPTIAN HIEROGLYPH A001, ^10FFFD^ the top of the range), or a
 // single digit.  Lengths 2-3 are NOT accepted: two- and three-letter
@@ -89,21 +91,61 @@ std::map<std::string, std::pair<std::string, std::string>> pinyin_tones {
     {"3", {"030C", "falling-rising"}},
     {"4", {"0300", "falling"}}};
 
+inline
+std::vector<std::vector<std::string>> ptolemy {
+    {"Q3",   "P",    "132AA"},
+    {"X1",   "t",    "133CF"},
+    {"V4",   "o/wa", "13371"},
+    {"E23",  "l/r",  "130ED"},
+    {"Aa15", "m",    "1340D"},
+    {"M17A", "e/y",  "131CC"},
+    {"S29",  "s",    "132F4"}};
+
+/*
+  道 (dào): U+9053
+  可 (kě): U+53EF
+  道 (dào): U+9053
+  非 (fēi): U+975E
+  常 (cháng): U+5E38
+  道 (dào): U+9053
+*/
+
+inline
+std::vector<std::vector<std::string>> dao {
+    {"dào", "9053"},
+    {"kě", "53EF"},
+    {"dào", "9053"},
+    {"fēi", "975E"},
+    {"cháng", "5E38"},
+    {"dào", "9053"}};
 
 inline
 bool is_tty() { return isatty(fileno(stdout)); }
-//const char* italic_on() { return tty() ? "\033[3m" : ""; }
-//const char* italic_off() { return tty() ? "\033[0m" : ""; }
 inline
 const std::string italic_on() { return is_tty() ? "\033[3m" : ""; }
 inline
 const std::string italic_off() { return is_tty() ? "\033[0m" : ""; }
 
+std::string encode(const std::string& s, const Locator& loc);
 
-std::string encode(const std::string& s);
+// UTF-8 encoding of one code point (to U+10FFFF; surrogates and values
+// above the range yield an "Invalid Unicode: N" text).  Used by the
+// character tables here and by the ^UUUU UUUU ...^ sequence pass
+// (process_unicode_sequences in katom_list.cpp).
+std::string utf8char(int cp);
+
+// Whether cp may be written in a ^...^ form: within the Unicode range,
+// not a surrogate, and not a NONCHARACTER (U+FDD0-U+FDEF and the last two
+// code points of every plane) -- the standard reserves those for internal
+// use, never for interchange.  An invalid code point in a document is a
+// located Parsing_error (the no-warn-and-continue policy; the in-band
+// "Invalid Unicode" text is no longer reachable from input).
+bool valid_codepoint(int cp);
+std::string invalid_codepoint_reason(int cp);
 
 void diacritics_examples(const std::string& kt_filename = "");
 void extended_latin_examples(const std::string& kt_filename = "");
 void pinyin_examples(const std::string& kt_filename = "");
+void unicode_examples(const std::string& kt_filename = "");
 
 void show_special_characters();