Option sets: a .o target for shared parameters

A named group of optional parameters, declared once and used by several
klammers, so a writer learns one vocabulary instead of a spelling per
klammer.  The "o" target is a pseudo-target beside "k": "k" declares a
klammer's interface and documents it, "o" declares an option interface and
documents it, and neither produces output for any target.

    @@caption_args.o :caption :number.bool true :caption_side.side
    : Arguments that define a caption for a block element @@

    @@code.k :filename @hpos_args :hpos left @ @caption_args :caption_side top @
    | text.literal : A source file displayed verbatim @@

A set is used only in the parameter list of a ".k" declaration -- the one
place a klammer's interface is declared once for all of its targets -- and
is resolved as that list is read.  Names and types come from the set; a
default may be overridden where it is used.  A klammer application in a
parameter list is now a definition-time error.

The SKS gains the sets caption_args and hpos_args (:hpos and :offset), and
@table, @image, @image_grid, @reference and @show gain .k declarations.  A
distance is no longer written as a position: :hpos 4em is rejected, and the
same layout is :hpos left :offset 4em.  Code listings are numbered by
default, like tables and figures.

New engine sources mac/option_set{,_registry}.{h,cpp}; tst/ ships two more
suites, option_set_test.sh and signature_test.sh (twelve in all).

 (from dev 34e536cb0329)

mac/option_set_registry.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "argtype_registry.h"
+#include "katom.h"
+#include "option_set.h"
+
+class Option_set_registry
+{
+public:
+    // Parse and register an "@@name.o <parameters> : <description> @@"
+    // declaration.  The name is passed in because the caller has already
+    // split it from its ".o" target suffix in order to route here.
+    void add(const Argtype_registry& argtypes, const std::string& name,
+             katom_iter begin, katom_iter end, katom_list& katoms);
+
+    bool has(const std::string& name) const;
+    const Option_set& get(const std::string& name, const Locator& loc) const;
+    void add_user(const std::string& set_name, const std::string& klammer_name);
+
+    std::string describe(int margin = 2) const;
+    // "a, b, c" -- the sets that exist, for a diagnostic about one that does not.
+    std::string available() const;
+
+    std::map<std::string, Option_set> m_option_sets {};
+    std::vector<std::string> m_names {};
+};
+
+// What one parameter inherited from an option set: which set it came from,
+// and whether its default was overridden where the set was used.  Default
+// resolution has three levels -- argument type, option set, use site -- and
+// kdesc says which one a klammer's effective default came from, so the level
+// has to be recorded rather than inferred from the value.
+struct Option_set_use
+{
+    std::string m_set {};
+    bool m_overridden {};
+};
+
+// parameter name -> where it came from
+using option_set_uses_t = std::map<std::string, Option_set_use>;
+
+// Replace every option-set use in a parameter list with the parameters it
+// stands for.  Any other klammer application in a parameter list is an
+// error: an option set is the only construct that may put parameters there,
+// and only in a ".k" declaration.
+//
+// `parameters` is modified in place.  Sets are recorded as used by
+// `klammer_name`, so `option_sets` is not const.
+option_set_uses_t expand_option_sets(
+    katom_list& parameters, const std::string& klammer_name,
+    const std::string& target_name, Option_set_registry& option_sets);
+
+// Record on each parameter that came from a set which set it came from and
+// whether its default was overridden.  Called after the expanded parameter
+// list has been parsed.
+void stamp_option_set_uses(Parameter_set& parameters, const option_set_uses_t& uses);