X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/2249baa7c8a9b7a4a7d774d6de857b1aa46c3177..684d95c7eb6ec755d38efacbc377e9e60ba7044e:/doc/clang.tex

diff --git a/doc/clang.tex b/doc/clang.tex
index f2a0b42..de9e8df 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -53,7 +53,7 @@ The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}.
         @|c-keyword-function-type|                            \-
   \end{tabbing}}
   \caption{Classes representing C types}
-\label{fig:codegen.c-types.classes}
+  \label{fig:codegen.c-types.classes}
 \end{figure}
 
 C type objects are immutable unless otherwise specified.
@@ -68,11 +68,11 @@ specified to return interned objects: programs may rely on receiving the same
 not specified, clients may still not rely on receiving fresh objects.
 
 A convenient S-expression notation is provided by the
-\descref{c-type}[macro]{mac}.  Use of this macro is merely an abbreviation
+\descref{mac}{c-type}[macro].  Use of this macro is merely an abbreviation
 for corresponding use of the various constructor functions, and therefore
 interns type objects in the same manner.  The syntax accepted by the macro
-can be extended in order to support new classes: see \descref{defctype}{mac},
-\descref{c-type-alias}{mac} and \descref{define-c-type-syntax}{mac}.
+can be extended in order to support new classes: see \descref{mac}{defctype},
+\descref{mac}{c-type-alias} and \descref{mac}{define-c-type-syntax}.
 
 The descriptions of each of the various classes include descriptions of the
 initargs which may be passed to @|make-instance| when constructing a new
@@ -83,14 +83,17 @@ syntax are strongly recommended over direct use of @|make-instance|.
 There are two protocols for printing C types.  Unfortunately they have
 similar names.
 \begin{itemize}
-\item The \descref{print-c-type}[function]{gf} prints a C type value using
+\item The \descref{gf}{print-c-type}[function] prints a C type value using
   the S-expression notation.  It is mainly useful for diagnostic purposes.
-\item The \descref{pprint-c-type}[function]{gf} prints a C type as a
+\item The \descref{gf}{pprint-c-type}[function] prints a C type as a
   C-syntax declaration.
 \end{itemize}
 Neither generic function defines a default primary method; subclasses of
 @|c-type| must define their own methods in order to print correctly.
 
+\begin{describe}{fun}{c-name-case @<name> @> @<string>}
+\end{describe}
+
 
 \subsection{The C type root class} \label{sec:clang.c-types.root}
 
@@ -169,7 +172,7 @@ type specifier.  Type specifiers fit into two syntactic categories.
 \begin{describe}{gf}{expand-c-type-spec @<type-spec> @> @<form>}
   Returns the Lisp form that @|(c-type @<type-spec>)| would expand into.
 
-  If @<type-spec> is a list, then \descref{expand-c-type-form}{gf} is
+  If @<type-spec> is a list, then \descref{gf}{expand-c-type-form} is
   invoked.
 \end{describe}
 
@@ -178,6 +181,11 @@ type specifier.  Type specifiers fit into two syntactic categories.
   into.
 \end{describe}
 
+\begin{describe}{cty}{lisp @<form>^*}
+  Evaluates the @<form>s as an implicit @|progn|, and returns the value(s) of
+  the final @<form> as a C type.
+\end{describe}
+
 \begin{describe}{gf}
     {print-c-type @<stream> @<type> \&optional @<colon> @<atsign>}
   Print the C type object @<type> to @<stream> in S-expression form.  The
@@ -190,6 +198,28 @@ type specifier.  Type specifiers fit into two syntactic categories.
   default method.
 \end{describe}
 
+\begin{describe*}
+    {\dhead{sym}{c-type}
+     \dhead{meth}{symbol,(eql 'c-type)}
+                 {documentation (@<symbol> symbol)
+                                (@<doc-type> (eql 'c-type))}
+     \dhead{meth}{symbol,(eql 'c-type)}
+                 {setf \=(documentation (@<symbol> symbol)
+                                        (@<doc-type> (eql 'c-type))) \\
+                       \>@<string>}}
+\end{describe*}
+
+\begin{describe*}
+    {\dhead{sym}{c-type-form}
+     \dhead{meth}{symbol,(eql 'c-type-form)}
+                 {documentation (@<symbol> symbol)
+                                (@<doc-type> (eql 'c-type-form))}
+     \dhead{meth}{symbol,(eql 'c-type-form)}
+                 {setf \=(documentation (@<symbol> symbol)
+                                        (@<doc-type> (eql 'c-type-form))) \\
+                       \>@<string>}}
+\end{describe*}
+
 
 \subsection{Comparing C types} \label{sec:clang.c-types.cmp}
 
@@ -208,12 +238,12 @@ argument lists for methods.  This is done by @|c-type-equal-p|.
 
   The generic function @|c-type-equal-p| uses the @|and| method combination.
 
-  \begin{describe}{meth}{c-type-equal-p @<c-type>_1 @<c-type>_2}
+  \begin{describe}{meth}{t,t}{c-type-equal-p @<c-type>_1 @<c-type>_2}
     A default primary method for @|c-type-equal-p| is defined.  It simply
     returns @|nil|.  This way, methods can specialize on both arguments
     without fear that a call will fail because no methods are applicable.
   \end{describe}
-  \begin{describe}{ar-meth}{c-type-equal-p @<c-type>_1 @<c-type>_2}
+  \begin{describe}{ar-meth}{}{c-type-equal-p @<c-type>_1 @<c-type>_2}
     A default around-method for @|c-type-equal-p| is defined.  It returns
     true if @<c-type>_1 and @<c-type>_2 are @|eql|; otherwise it delegates to
     the primary methods.  Since several common kinds of C types are interned,
@@ -258,19 +288,19 @@ argument lists for methods.  This is done by @|c-type-equal-p|.
   directly attached.  If the @<kernel> function intends to provide its own
   additional declarator operators, it should check the @<priority> in order
   to determine whether parentheses are necessary.  See also the
-  \descref{maybe-in-parens}[macro]{mac}.
+  \descref{mac}{maybe-in-parens}[macro].
 
   The @<spacep> argument indicates whether a space needs to be printed in
   order to separate the declarator from the declaration specifiers.  A kernel
   which contains an identifier should insert a space before the identifier
   when @<spacep> is non-nil.  An `empty' kernel, as found in an abstract
   declarator (one that specifies no name), looks more pleasing without a
-  trailing space.  See also the \descref{c-type-space}[function]{fun}.
+  trailing space.  See also the \descref{fun}{c-type-space}[function].
 
   Every concrete subclass of @|c-type| is expected to provide a primary
   method on this function.  There is no default primary method.
 
-  \begin{describe}{ar-meth}{pprint-c-type @<c-type> @<stream> @<kernel>}
+  \begin{describe}{ar-meth}{}{pprint-c-type @<c-type> @<stream> @<kernel>}
     A default around method is defined on @|pprint-c-type| which `canonifies'
     non-function @<kernel> arguments.  In particular:
     \begin{itemize}
@@ -318,18 +348,18 @@ is shown in \xref{tab:clang.ctypes.qual}.
 
 \begin{table}
   \begin{tabular}[C]{*2{>{\codeface}l}l}                           \hlx*{hv}
-    \thd{\textbf{C name}}       & \thd{\textbf{Lisp name}}      \\ \hlx{vhv}
-    _Atomic                     & :atomic                       \\
-    const                       & :const                        \\
-    restrict                    & :restrict                     \\
-    volatile                    & :volatile                     \\ \hlx*{vh}
+    \thd{C name}        & \thd{Lisp name}                       \\ \hlx{vhv}
+    _Atomic             & :atomic                               \\
+    const               & :const                                \\
+    restrict            & :restrict                             \\
+    volatile            & :volatile                             \\ \hlx*{vh}
   \end{tabular}
   \caption{C and Lisp qualifier names} \label{tab:clang.ctypes.qual}
 \end{table}
 
 The default behaviour, on output, is to convert keywords to lowercase and
 hope for the best: special cases can be dealt with by adding appropriate
-methods to \descref{c-qualifier-keyword}{gf}.
+methods to \descref{gf}{c-qualifier-keyword}.
 
 \begin{describe}{cls}{qualifiable-c-type (c-type) \&key :qualifiers}
   The class @|qualifiable-c-type| describes C types which can bear
@@ -347,12 +377,16 @@ methods to \descref{c-qualifier-keyword}{gf}.
   The class @|qualifiable-c-type| is abstract.
 \end{describe}
 
+\begin{describe}{fun}
+    {canonify-qualifiers @<qualifiers> @> @<canonfied-qualifiers>}
+\end{describe}
+
 \begin{describe}{gf}{c-type-qualifiers @<c-type> @> @<list>}
   Returns the qualifiers of the @|qualifiable-c-type| instance @<c-type> as
   an immutable list.
 \end{describe}
 
-\begin{describe}{fun}{qualify-type @<c-type> @<qualifiers> @> @<c-type>}
+\begin{describe}{fun}{qualify-c-type @<c-type> @<qualifiers> @> @<c-type>}
   The argument @<c-type> must be an instance of @|qualifiable-c-type|,
   currently bearing no qualifiers, and @<qualifiers> a list of qualifier
   keywords.  The result is a C type object like @<c-type> except that it
@@ -375,7 +409,8 @@ methods to \descref{c-qualifier-keyword}{gf}.
   methods exist for qualifier keywords which need special handling, such as
   @|:atomic|; they are not listed here explicitly.
 
-  \begin{describe}{meth}{c-qualifier-keyword @<keyword> @> @<string>}
+  \begin{describe}{meth}{keyword}
+      {c-qualifier-keyword @<keyword> @> @<string>}
     Returns the @<keyword>'s print-name, in lower case.  This is sufficient
     for the standard qualifiers @|:const|, @|:restrict|, and @|:volatile|.
   \end{describe}
@@ -399,16 +434,18 @@ Every Lisp keyword is potentially a storage specifier, which simply maps to
 its lower-case print name in C; but other storage specifiers may be more
 complicated objects.
 
-\begin{describe}{cls}
-    {c-storage-specifiers-type (c-type) \&key :subtype :specifiers}
+\begin{describe*}
+    {\dhead{cls}{c-storage-specifiers-type (c-type)
+                                           \&key :subtype :specifiers}
+     \dhead{cty}{specs @<subtype> @<specifier>^*}}
   A type which carries storage specifiers.  The @<subtype> is the actual
   type, and may be any C type; the @<specifiers> are a list of
   storage-specifier objects.
 
-  The type specifier @|(specs @<subtype> @<specifier>^*)| wraps the
-  @<subtype> in a @|c-storage-specifiers-type|, carrying the @<specifier>s,
-  which are a list of storage specifiers in S-expression notation.
-\end{describe}
+  The type specifier @|specs| wraps the @<subtype> in a
+  @|c-storage-specifiers-type|, carrying the @<specifier>s, which are a list
+  of storage specifiers in S-expression notation.
+\end{describe*}
 
 \begin{describe}{fun}{c-type-specifiers @<type> @> @<list>}
   Returns the list of type specifiers attached to the @<type> object, which
@@ -437,7 +474,7 @@ complicated objects.
   Returns the Lisp form that @<spec> expands to within @|(c-type (specs
   @<subtype> @<spec>))|.
 
-  If @<spec> is a list, then \descref{expand-c-storage-specifier-form} is
+  If @<spec> is a list, then \descref{gf}{expand-c-storage-specifier-form} is
   invoked.
 \end{describe}
 
@@ -446,7 +483,13 @@ complicated objects.
   @|(c-type (specs @<subtype> (@<head> . @<tail>)))|.
 \end{describe}
 
+\begin{describe}{cstg}{lisp @<form>^*}
+  Evaluates the @<form>s as an implicit @|progn|, and returns the value(s) of
+  the final @<form> as a storage-specifier.
+\end{describe}
+
 \begin{describe}{gf}{pprint-c-storage-specifier @<spec> @<stream>}
+  Prints the storage-specifier @<spec> to @<stream>, in C syntax.
 \end{describe}
 
 \begin{describe}{gf}
@@ -466,14 +509,16 @@ complicated objects.
   @<base-type>.
 \end{describe}
 
-\begin{describe}{cls}{alignas-storage-specifier () \&key :alignment}
-  The class of @|_Alignas| storage specifiers; an instance denotes the
-  specifier @|_Alignas(@<alignment>)|.  The @<alignment> parameter may be any
-  printable object, but is usually a string or C fragment.
-
-  The storage specifier form @|(alignas @<alignment>)| returns a storage
-  specifier @|_Alignas(@<alignment>)|, where @<alignment> is evaluated.
-\end{describe}
+\begin{describe*}
+    {\dhead{cls}{alignas-storage-specifier () \&key :alignment}
+     \dhead{cstg}{alignas @<alignment>}}
+  The class of \mbox{@|_Alignas|} storage specifiers; an instance denotes the
+  specifier \mbox{@|_Alignas(@<alignment>)|}.  The @<alignment> parameter may
+  be any printable object, but is usually a string or C fragment.
+
+  The storage specifier form @|alignas| returns a storage specifier
+  \mbox{@|_Alignas(@<alignment>)|}, where @<alignment> is evaluated.
+\end{describe*}
 
 
 \subsection{Leaf types} \label{sec:clang.c-types.leaf}
@@ -500,6 +545,22 @@ In Sod, the leaf types are
   Two simple type objects are equal if and only if they have @|string=| names
   and matching qualifiers.
 
+  \def\x#1{\desclabel{cty}{#1}}
+  \def\y#1{\desclabel{const}{c-type-#1}\x{#1}}
+  \y{bool} \y{wchar-t}
+  \y{int} \x{signed} \y{unsigned} \y{signed-char}
+  \crossproduct\y{{{}{unsigned-}}{{char}{short}{long}{long-long}}}
+  \crossproduct\x{{{}{signed-}{unsigned-}}{{short}{long}{long-long}}{{-int}}}
+  \crossproduct\x{{{signed-}{unsigned-}}{{int}}}
+  \crossproduct\x{{{signed-}}{{short}{int}{long}{long-long}}}
+  \crossproduct\x{{{s}{u}}{{char}{short}{int}{long}{llong}}} \x{llong}
+  \y{size-t} \y{ptrdiff-t} \y{float}
+  \y{double} \y{long-double} \y{float-imaginary} \y{double-imaginary}
+  \y{long-double-imaginary} \y{float-complex} \y{double-complex}
+  \y{long-double-complex} \y{va-list} \y{void}
+  \crossproduct\y{{{int}{uint}}{{}{-least}{-fast}}{{8}{16}{32}{64}}{{-t}}}
+  \crossproduct\y{{{int}{uint}}{{ptr}{max}}{{-t}}}
+
   A number of symbolic type specifiers for builtin types are predefined as
   shown in \xref{tab:codegen.c-types.simple}.  These are all defined as if by
   @|define-simple-c-type|, so can be used to construct qualified types.
@@ -534,6 +595,18 @@ In Sod, the leaf types are
                           @|ullong|                             \\ \hlx{v}
     @|size_t|           & @|size-t|                             \\ \hlx{}
     @|ptrdiff_t|        & @|ptrdiff-t|                          \\ \hlx{v}
+    @|int$n$_t|         & @|int$n$-t|
+                          (for $n \in \{ @|8|, @|16|, @|32|, @|64| \}$)
+                                                                \\ \hlx{}
+    @|uint$n$_t|        & @|uint$n$-t|                          \\ \hlx{}
+    @|int_least$n$_t|   & @|int_least$n$-t|                     \\ \hlx{}
+    @|uint_least$n$_t|  & @|uint_least$n$-t|                    \\ \hlx{}
+    @|int_fast$n$_t|    & @|int_fast$n$-t|                      \\ \hlx{}
+    @|uint_fast$n$_t|   & @|uint_fast$n$-t|                     \\ \hlx{v}
+    @|intptr_t|         & @|intptr-t|                           \\ \hlx{}
+    @|uintptr_t|        & @|uintptr-t|                          \\ \hlx{}
+    @|intmax_t|         & @|intmax-t|                           \\ \hlx{}
+    @|uintmax_t|        & @|uintmax-t|                          \\ \hlx{v}
     @|float|            & @|float|                              \\ \hlx{}
     @|double|           & @|double|                             \\ \hlx{}
     @|long double|      & @|long-double|                        \\ \hlx{v}
@@ -578,7 +651,7 @@ In Sod, the leaf types are
   evaluated).
 
   Each of the @<string>s is associated with the resulting type for retrieval
-  by \descref{find-simple-c-type}{fun}.  Furthermore, a variable
+  by \descref{fun}{find-simple-c-type}.  Furthermore, a variable
   @|c-type-@<name>| is defined, for the first @<name> only, and initialized
   with the newly constructed C type object.
 
@@ -589,7 +662,7 @@ In Sod, the leaf types are
 \begin{describe}{fun}
     {find-simple-c-type @<string> @> @{ @<simple-c-type> @! @|nil| @}}
   If @<string> is the name of a simple C type, as established by the
-  \descref{define-simple-c-type}[macro]{mac}, then return the corresponding
+  \descref{mac}{define-simple-c-type}[macro], then return the corresponding
   @|simple-c-type| object; otherwise, return @|nil|.
 \end{describe}
 
@@ -609,6 +682,14 @@ In Sod, the leaf types are
   structs and unions.
 \end{boxy}
 
+\begin{describe}{gf}{c-type-tag @<c-type> @> @<keyword>}
+\end{describe}
+
+\begin{describe}{fun}
+    {make-c-tagged-type @<kind> @<tag> \&optional @<qualifiers>
+      @> @<tagged-type>}
+\end{describe}
+
 \begin{describe}{gf}{c-tagged-type-kind @<c-type> @> @<keyword>}
   Returns a keyword classifying the tagged @<c-type>: one of @|:enum|,
   @|:struct| or @|:union|.  User-defined subclasses of @|tagged-c-type|
@@ -627,14 +708,16 @@ In Sod, the leaf types are
   type class as a symbol.
 \end{describe}
 
-\begin{describe}{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag}
+\begin{describe*}
+    {\dhead{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag}
+     \dhead{cty}{enum @<tag> @<qualifier>^*}}
   Represents a C enumerated type.  An instance denotes the C type @|enum|
   @<tag>.  See the direct superclass @|tagged-c-type| for details.
 
-  The type specifier @|(enum @<tag> @<qualifier>^*)| returns the (unique
-  interned) enumerated type with the given @<tag> and @<qualifier>s (all
-  evaluated).
-\end{describe}
+  The type specifier @|enum| returns the (unique interned) enumerated type
+  with the given @<tag> and @<qualifier>s (all evaluated).
+\end{describe*}
+
 \begin{describe}{fun}
     {make-enum-type @<tag> \&optional @<qualifiers> @> @<c-enum-type>}
   Return the (unique interned) C type object for the enumerated C type whose
@@ -642,14 +725,16 @@ In Sod, the leaf types are
   keywords).
 \end{describe}
 
-\begin{describe}{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag}
+\begin{describe*}
+    {\dhead{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag}
+     \dhead{cty}{struct @<tag> @<qualifier>^*}}
   Represents a C structured type.  An instance denotes the C type @|struct|
   @<tag>.  See the direct superclass @|tagged-c-type| for details.
 
-  The type specifier @|(struct @<tag> @<qualifier>^*)| returns the (unique
-  interned) structured type with the given @<tag> and @<qualifier>s (all
-  evaluated).
-\end{describe}
+  The type specifier @|struct| returns the (unique interned) structured type
+  with the given @<tag> and @<qualifier>s (all evaluated).
+\end{describe*}
+
 \begin{describe}{fun}
     {make-struct-type @<tag> \&optional @<qualifiers> @> @<c-struct-type>}
   Return the (unique interned) C type object for the structured C type whose
@@ -657,15 +742,17 @@ In Sod, the leaf types are
   keywords).
 \end{describe}
 
-\begin{describe}{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag}
+\begin{describe*}
+    {\dhead{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag}
+     \dhead{cty}{union @<tag> @<qualifier>^*}}
   Represents a C union type.  An instance denotes the C type @|union|
   @<tag>.  See the direct superclass @|tagged-c-type|
   for details.
 
-  The type specifier @|(union @<tag> @<qualifier>^*)| returns the (unique
-  interned) union type with the given @<tag> and @<qualifier>s (all
-  evaluated).
-\end{describe}
+  The type specifier @|union| returns the (unique interned) union type with
+  the given @<tag> and @<qualifier>s (all evaluated).
+\end{describe*}
+
 \begin{describe}{fun}
     {make-union-type @<tag> \&optional @<qualifiers> @> @<c-union-type>}
   Return the (unique interned) C type object for the union C type whose tag
@@ -693,8 +780,10 @@ underlying type of the object.  Note that, as far as Sod is concerned, atomic
 types are not the same as atomic-qualified types: you must be consistent
 about which you use.
 
-\begin{describe}{cls}
-    {c-atomic-type (qualifiable-c-type) \&key :qualifiers :subtype}
+\begin{describe*}
+    {\dhead{cls}{c-atomic-type (qualifiable-c-type)
+                               \&key :qualifiers :subtype}
+     \dhead{cty}{atomic @<type-spec> @<qualifier>^*}}
   Represents an atomic type.  An instance denotes the C type
   @|_Atomic(@<subtype>)|.
 
@@ -704,11 +793,10 @@ about which you use.
   have matching qualifiers.  It is possible, though probably not useful, to
   have an atomic-qualified atomic type.
 
-  The type specifier @|(atomic @<type-spec> @<qualifier>^*)| returns a type
-  qualified atomic @<subtype>, where @<subtype> is the type specified by
-  @<type-spec> and the @<qualifier>s are qualifier keywords (which are
-  evaluated).
-\end{describe}
+  The type specifier @|atomic| returns a type qualified atomic @<subtype>,
+  where @<subtype> is the type specified by @<type-spec> and the
+  @<qualifier>s are qualifier keywords (which are evaluated).
+\end{describe*}
 
 \begin{describe}{fun}
     {make-atomic-type @<c-type> \&optional @<qualifiers> @> @<c-atomic-type>}
@@ -723,24 +811,29 @@ about which you use.
 Pointers are compound types.  The subtype of a pointer type is the type it
 points to.
 
-\begin{describe}{cls}
-    {c-pointer-type (qualifiable-c-type) \&key :qualifiers :subtype}
+\begin{describe*}
+    {\dhead{cls}{c-pointer-type (qualifiable-c-type)
+                                \&key :qualifiers :subtype}
+     \dhead{cty}{* @<type-spec> @<qualifier>^*}
+     \dhead{cty}{string}
+     \dhead{cty}{const-string}}
   Represents a C pointer type.  An instance denotes the C type @<subtype>
   @|*|@<qualifiers>.
 
   The @<subtype> may be any C type.  Two pointer types are equal if and only
   if their subtypes are equal and they have matching qualifiers.
 
-  The type specifier @|(* @<type-spec> @<qualifier>^*)| returns a type
-  qualified pointer-to-@<subtype>, where @<subtype> is the type specified by
-  @<type-spec> and the @<qualifier>s are qualifier keywords (which are
-  evaluated).  The synonyms @|ptr| and @|pointer| may be used in place of the
-  star @`*'.
+  \desclabel{cty}{ptr}
+  \desclabel{cty}{pointer}
+  The type specifier @|*| returns a type qualified pointer-to-@<subtype>,
+  where @<subtype> is the type specified by @<type-spec> and the
+  @<qualifier>s are qualifier keywords (which are evaluated).  The synonyms
+  @|ptr| and @|pointer| may be used in place of the star @`*'.
 
   The symbol @|string| is a type specifier for the type pointer to
   characters; the symbol @|const-string| is a type specifier for the type
   pointer to constant characters.
-\end{describe}
+\end{describe*}
 
 \begin{describe}{fun}
     {make-pointer-type @<c-type> \&optional @<qualifiers>
@@ -756,7 +849,11 @@ points to.
 Arrays implement the compound-type protocol.  The subtype of an array type is
 the array element type.
 
-\begin{describe}{cls}{c-array-type (c-type) \&key :subtype :dimensions}
+\begin{describe*}
+    {\dhead{cls}{c-array-type (c-type) \&key :subtype :dimensions}
+     \dhead{cty}{[] @<type-spec> @<dimension>^*}}
+  \desclabel{cty}{array}[|(]
+  \desclabel{cty}{vec}[|(]
   Represents a multidimensional C array type.  The @<dimensions> are a list
   of dimension specifiers $d_0$, $d_1$, \ldots, $d_{n-1}$; an instance then
   denotes the C type @<subtype> @|[$d_0$][$d_1$]$\ldots$[$d_{n-1}$]|.  An
@@ -773,12 +870,15 @@ the array element type.
   $d_1$ of \ldots\ arrays of $d_{n-1}$ elements of type @<subtype>.  We shall
   continue to abuse terminology and refer to multidimensional arrays.
 
-  The type specifier @|([] @<type-spec> @<dimension>^*)| constructs a
-  multidimensional array with the given @<dimension>s whose elements have the
-  type specified by @<type-spec>.  If no dimensions are given then a
-  single-dimensional array with unspecified extent.  The synonyms @|array|
-  and @|vector| may be used in place of the brackets @`[]'.
-\end{describe}
+  The type specifier @|[]| constructs a multidimensional array with the given
+  @<dimension>s whose elements have the type specified by @<type-spec>.  If
+  no dimensions are given then a single-dimensional array with unspecified
+  extent.  The synonyms @|array| and @|vec| may be used in place of the
+  brackets @`[]'.
+
+  \desclabel{cty}{array}[|)]
+  \desclabel{cty}{vec}[|)]
+\end{describe*}
 
 \begin{describe}{fun}
     {make-array-type @<subtype> @<dimensions> @> @<c-array-type>}
@@ -819,8 +919,8 @@ function type is the type of the function's return value.
   argument name.
 
   A @<default> may be supplied.  If the argument is used in a
-  keyword-argument list (e.g., in a \descref{c-keyword-function-type}
-  [object]{cls}), and the @<default> value is provided and non-nil, then its
+  keyword-argument list (e.g., in a \descref{cls}{c-keyword-function-type}
+  [object]), and the @<default> value is provided and non-nil, then its
   (unescaped) printed representation is used to provide a default value if
   the keyword argument is not supplied by the caller.
 \end{describe}
@@ -844,11 +944,13 @@ function type is the type of the function's return value.
   including file from defining such names as macros.  This generic function
   is used to convert names into a safe form.
 
-  \begin{describe}{meth}{commentify-argument-name (@<name> null) @> nil}
+  \begin{describe}{meth}{null}
+      {commentify-argument-name (@<name> null) @> nil}
     Returns nil: if the argument name is already omitted, it's safe for use
     in a header file.
   \end{describe}
-  \begin{describe}{meth}{commentify-argument-name (@<name> t) @> @<string>}
+  \begin{describe}{meth}{t}
+      {commentify-argument-name (@<name> t) @> @<string>}
     Returns the print form of @<name> wrapped in a C comment, as
     @`/*@<name>*/'.
   \end{describe}
@@ -868,7 +970,16 @@ function type is the type of the function's return value.
   unchanged.
 \end{describe}
 
-\begin{describe}{cls}{c-function-type (c-type) \&key :subtype :arguments}
+\begin{describe*}
+    {\dhead{cls}{c-function-type (c-type) \&key :subtype :arguments}
+     \dhead*{cty}{fun @<return-type>
+                      @{ (@<arg-name> @<arg-type>) @}^*
+                      @[:ellipsis @! . @<form>@]}}
+  \desclabel{cty}{()}[|(]
+  \desclabel{cty}{fn}[|(]
+  \desclabel{cty}{func}[|(]
+  \desclabel{cty}{function}[|(]
+  \descindex{cty}{fun}[|(]
   Represents C function types.  An instance denotes the type of a C
   function which accepts the @<arguments> and returns @<subtype>.
 
@@ -886,19 +997,13 @@ function type is the type of the function's return value.
   in the same order, and either both or neither argument list ends with
   @|:ellipsis|; argument names are not compared.
 
-  The type specifier
-  \begin{prog}
-    (fun @<return-type>
-         @{ (@<arg-name> @<arg-type>) @}^*
-         @[:ellipsis @! . @<form>@])
-  \end{prog}
-  constructs a function type.  The function has the subtype @<return-type>.
-  The remaining items in the type-specifier list are used to construct the
-  argument list.  The argument items are a possibly improper list, beginning
-  with zero or more \emph{explicit arguments}: two-item
-  @<arg-name>/@<arg-type> lists.  For each such list, an @|argument| object
-  is constructed with the given name (evaluated) and type.  Following the
-  explicit arguments, there may be
+  The type specifier @|fun| constructs a function type.  The function has the
+  subtype @<return-type>.  The remaining items in the type-specifier list are
+  used to construct the argument list.  The argument items are a possibly
+  improper list, beginning with zero or more \emph{explicit arguments}:
+  two-item @<arg-name>/@<arg-type> lists.  For each such list, an @|argument|
+  object is constructed with the given name (evaluated) and type.  Following
+  the explicit arguments, there may be
   \begin{itemize}
   \item nothing, in which case the function's argument list consists only of
     the explicit arguments;
@@ -926,11 +1031,18 @@ function type is the type of the function's return value.
             (ret (c-type-subtype other-func)))                \-\\ \ind
       (c-type (fun \=(lisp ret) ("first" int) . args)
   \end{prog}
-\end{describe}
+  \descindex{cty}{fun}[|)]
+\end{describe*}
 
-\begin{describe}{cls}
-    {c-keyword-function-type (c-function-type)
-      \&key :subtype :arguments :keywords}
+\begin{describe*}
+    {\dhead{cls}{c-keyword-function-type (c-function-type)
+                                         \&key :subtype :arguments :keywords}
+     \dhead{cty}{fun \=@<return-type>
+                       @{ (@<arg-name> @<arg-type>) @}^*      \+\\
+                       @{ \=:keys @{ (@<kw-name> @<kw-type>
+                                      @[@<kw-default>@]) @}^*
+                               @[. @<form>@] @!               \+\\
+                             . @<form> @}}}
   Represents `functions' which accept keyword arguments.  Of course, actual C
   functions can't accept keyword arguments directly, but this type is useful
   for describing messages and methods which deal with keyword arguments.
@@ -951,32 +1063,29 @@ function type is the type of the function's return value.
 
   Keyword functions are never considered to be the same as ordinary
   functions.  Two keyword function types are considered to be the same if
-  their return types are the same, and their positional argument lists consist of
-  arguments with the same type, in the same order: the keyword arguments
-  accepted by the functions is not significant.
+  their return types are the same, and their positional argument lists
+  consist of arguments with the same type, in the same order: the keyword
+  arguments accepted by the functions is not significant.
 
   Keyword functions are constructed using an extended version of the @|fun|
-  specifier used for ordinary C function types.  The extended syntax is as
-  follows.
-  \begin{prog}
-    (fun \=@<return-type>
-           @{ (@<arg-name> @<arg-type>) @}^*                  \+\\
-           @{ \=:keys @{ (@<kw-name> @<kw-type> @[@<kw-default>@]) @}^*
-                   @[. @<form>@] @!                           \+\\
-                 . @<form> @}
-  \end{prog}
-  where either the symbol @|:keys| appears literally in the specifier, or the
-  @<form> evaluates to a list containing the symbol @|:keys|.  (If neither of
-  these circumstances obtains, then the specifier constructs an ordinary
-  function type.)
+  specifier (or any of its synonyms) used for ordinary C function types.
+  Either the symbol @|:keys| must appear literally in the specifier, or the
+  @<form> must evaluate to a list containing the symbol @|:keys|.  (If
+  neither of these circumstances obtains, then the specifier constructs an
+  ordinary function type.)
 
-  See the description of \descref{c-function-type}{cls} for how a trailing
+  See the description of \descref{cls}{c-function-type} for how a trailing
   @<form> is handled.
 
   The list of @<arg-name>s and @<arg-type>s describes the positional
   arguments.  The list of @<kw-name>s, @<kw-type>s and @<kw-defaults>s
   describes the keyword arguments.
-\end{describe}
+
+  \descindex{cty}{()}[|)]
+  \descindex{cty}{fn}[|)]
+  \descindex{cty}{func}[|)]
+  \descindex{cty}{function}[|)]
+\end{describe*}
 
 \begin{describe}{fun}
     {make-function-type @<subtype> @<arguments> @> @<c-function-type>}
@@ -984,7 +1093,7 @@ function type is the type of the function's return value.
   accepting the @<arguments>.
 
   If the @<arguments> list contains a @|:keys| marker, then a
-  \descref{c-keyword-function-type}[object]{cls} is returned: those arguments
+  \descref{cls}{c-keyword-function-type}[object] is returned: those arguments
   preceding the @|:keys| marker form the positional argument list, and those
   following the marker form the list of keyword arguments.
 \end{describe}
@@ -998,7 +1107,12 @@ function type is the type of the function's return value.
 
 \begin{describe}{gf}
     {c-function-arguments @<c-function-type> @> @<arguments>}
-  Return the arguments list of the @<c-function-type>.
+  Return the (non-keyword) argument list of the @<c-function-type>.
+\end{describe}
+
+\begin{describe}{gf}
+    {c-function-keywords @<c-function-type> @> @<keywords>}
+  Return the keyword-argument list of the @<c-function-type>.
 \end{describe}
 
 \begin{describe}{fun}
@@ -1013,7 +1127,7 @@ function type is the type of the function's return value.
 \begin{describe}{fun}{reify-variable-argument-tail @<arguments> @> @<list>}
   If the @<argument> list contains an @|:ellipsis| marker, then replace it
   with a @|va_list|.  The name for the new argument, if any, is taken from
-  the \descref{*sod-ap*}[variable]{var}.  The new list is returned; the
+  the \descref{var}{*sod-ap*}[variable].  The new list is returned; the
   original list is not modified, but may share structure with the new list.
 \end{describe}
 
@@ -1026,7 +1140,7 @@ function type is the type of the function's return value.
   The @<lists> parameter is a list consisting of a number of
   @|(@<report-function> . @<args>)| pairs: in each pair, @<report-function>
   is either nil or a function designator, and @<args> is a list of
-  \descref{argument}{cls} objects.
+  \descref{cls}{argument} objects.
 
   The resulting list contains exactly one argument for each distinct argument
   name appearing in the input @<lists>; this argument will contain the
@@ -1040,7 +1154,7 @@ function type is the type of the function's return value.
   arguments and is expected to return two values:
   \begin{itemize}
   \item a file location @<floc> or other object acceptable to
-    \descref{file-location}{gf}, to be used as the location of the main
+    \descref{gf}{file-location}, to be used as the location of the main
     error; and
   \item an object @<what>, whose printed representation should be a noun
     phrase describing the object for which the argument lists are being
@@ -1053,7 +1167,7 @@ function type is the type of the function's return value.
   for the @<args> lists containing the conflicting argument objects are
   called, in an arbitrary order, with a single argument which is the
   offending @|argument| object; the function is expected to issue information
-  messages (see \descref{info}{fun}) to give more detail for diagnosing the
+  messages (see \descref{fun}{info}) to give more detail for diagnosing the
   conflict.  If a @<report-function> is nil, then nothing happens; this is
   considered poor practice.
 \end{describe}
@@ -1069,7 +1183,7 @@ function type is the type of the function's return value.
   arguments, if any, will be printed by @<print-args>.
 
   The @<print-kernel> function is a standard kernel-printing function
-  following the \descref{pprint-c-type}[protocol]{gf}.
+  following the \descref{gf}{pprint-c-type}[protocol].
 
   The @<print-args> function is given a single argument, which is the
   @<stream> to print on.  It should not print the surrounding parentheses.
@@ -1083,7 +1197,7 @@ function type is the type of the function's return value.
 \begin{describe}{fun}{pprint-argument-list @<args> @<stream> @> @<flag>}
   Print an argument list to @<stream>.
 
-  The @<args> is a list of \descref{argument}[objects]{cls}, optionally
+  The @<args> is a list of \descref{cls}{argument}[objects], optionally
   containing an @|:ellipsis| marker.  The function returns true if any
   arguments were actually printed.
 \end{describe}
@@ -1104,9 +1218,11 @@ function type is the type of the function's return value.
 
 \subsection{Class types} \label{sec:clang.c-types.class}
 
-\begin{describe}{cls}
-    {c-class-type (simple-c-type) \&key :class :tag :qualifiers :name}
-\end{describe}
+\begin{describe*}
+    {\dhead{cls}{c-class-type (simple-c-type)
+                              \&key :class :tag :qualifiers :name}
+     \dhead{cty}{class @<name> @<qualifier>^*}}
+\end{describe*}
 
 \begin{describe*}
     {\dhead{gf}{c-type-class @<class-type> @> @<class>}
@@ -1120,10 +1236,6 @@ function type is the type of the function's return value.
     {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>}
 \end{describe}
 
-\begin{describe}{fun}
-    {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>}
-\end{describe}
-
 \begin{describe}{fun}{find-sod-class @<name> @> @<class>}
 \end{describe}
 
@@ -1158,8 +1270,7 @@ Temporary names are represented by objects which implement a simple protocol.
 
 \begin{describe*}
     {\dhead{gf}{var-in-use-p @<var> @> @<generalized-boolean>}
-     \dhead[setf var-in-use-p]
-       {gf}{setf (var-in-use-p @<var>) @<generalized-boolean>}}
+     \dhead{gf}{setf (var-in-use-p @<var>) @<generalized-boolean>}}
 \end{describe*}
 
 \subsubsection{Temporary name objects}
@@ -1169,17 +1280,20 @@ Temporary names are represented by objects which implement a simple protocol.
   subclasses, but is also usable on its own.
 \end{describe}
 
-\begin{describe}{meth}
+\begin{describe}{gf}{temp-tag @<name> @> @<tag>}
+\end{describe}
+
+\begin{describe}{meth}{temporary-name}
     {commentify-argument-name (@<name> temporary-name) @> nil}
 \end{describe}
 
 \begin{table}
   \begin{tabular}[C]{*2{>{\codeface}l}}                            \hlx*{hv}
-    \thd{\textbf{Class}} & \thd{\textbf{Name format}}           \\ \hlx{vhv}
-    temporary-name              & @<tag>                        \\
-    temporary-argument          & sod__a@<tag>                  \\
-    temporary-function          & sod__f@<tag>                  \\
-    temporary-variable          & sod__v@<tag>                  \\ \hlx*{vh}
+    \thd{Class}         & \thd{Name format}                     \\ \hlx{vhv}
+    temporary-name      & @<tag>                                \\
+    temporary-argument  & sod__a@<tag>                          \\
+    temporary-function  & sod__f@<tag>                          \\
+    temporary-variable  & sod__v@<tag>                          \\ \hlx*{vh}
   \end{tabular}
   \caption{Temporary name formats}
   \label{tab:codegen.codegen.temps-format}
@@ -1201,11 +1315,13 @@ Temporary names are represented by objects which implement a simple protocol.
 \subsubsection{Well-known `temporary' names}
 
 \begin{table}
+  \def\x#1{\desclabel{var}{#1}}
+  \x{*sod-ap*} \x{*sod-master-ap*} \x{*null-pointer*}
   \begin{tabular}[C]{*2{>{\codeface}l}}                            \hlx*{hv}
-    \thd{\textbf{Variable}} & \thd{\textbf{Name format}}        \\ \hlx{vhv}
-    {}*sod-ap*                  & sod__ap                       \\
-    {}*sod-master-ap*           & sod__master_ap                \\
-    {}*null-pointer*            & NULL                          \\ \hlx*{vh}
+    \thd{Variable}      & \thd{Name format}                     \\ \hlx{vhv}
+    {}*sod-ap*          & sod__ap                               \\
+    {}*sod-master-ap*   & sod__master_ap                        \\
+    {}*null-pointer*    & NULL                                  \\ \hlx*{vh}
   \end{tabular}
   \caption{Well-known temporary names}
   \label{tab:codegen.codegen.well-known-temps}
@@ -1241,8 +1357,8 @@ Temporary names are represented by objects which implement a simple protocol.
 \begin{table}
   \begin{tabular}[C]{ll>{\codeface}l}                              \hlx*{hv}
     \thd{Class name} &
-    \thd{Arguments} &
-    \thd{Output format}                                         \\ \hlx{vhv}
+                  \thd{Arguments} &
+                                             \thd{Output format}\\ \hlx{vhv}
     @|var|      & @<name> @<type> @|\&optional| @<init>
                                            & @<type> @<name> @[= @<init>@];
                                                                 \\ \hlx{v}
@@ -1286,6 +1402,33 @@ Temporary names are represented by objects which implement a simple protocol.
   \label{tab:codegen.codegen.insts}
 \end{table}
 
+\begin{describe*}
+    {\dhead*{cls}{@<code>-inst (inst) \&key \dots}
+     \dhead*{fun}{make-@<code>-inst \dots}
+     \dhead*{gf}{inst-@<slot> @<inst> @> @<value>}}
+  \def\instclass#1#2#3{%
+    #1{cls}{#3-inst}[#2]%
+    #1{fun}{make-#3-inst}[#2]%
+  }
+  \def\instslot#1#2#3{#1{gf}{inst-#3}[#2]}
+  \def\makelabels#1#2{%
+    \def\x{\instclass{#1}{#2}}
+      \x{var} \x{set} \x{update} \x{cond} \x{return} \x{break} \x{continue}
+      \x{expr} \x{call} \x{banner} \x{block} \x{if} \x{for} \x{while}
+      \x{do-while} \x{function}
+    \def\x{\instslot{#1}{#2}}
+      \x{name} \x{type} \x{init} \x{var} \x{expr} \x{op} \x{cond} \x{conseq}
+      \x{alt} \x{func} \x{args} \x{control} \x{decls} \x{body} \x{update}
+      \x{banner} \x{banner-args}
+  }
+  \makelabels{\desclabel}{|(}
+
+  Sod provides a number of built-in instruction types generated by
+  \descref{mac}{definst}: see \xref{tab:codegen.codegen.insts}.
+
+  \makelabels{\descindex}{|)}
+\end{describe*}
+
 
 \subsection{Code generation} \label{sec:clang.codegen.codegen}
 
@@ -1361,8 +1504,11 @@ Temporary names are represented by objects which implement a simple protocol.
 \begin{describe}{cls}{c-fragment () \&key :location :text}
 \end{describe}
 
-\begin{describe}{gf}{c-fragment-text @<fragment> @> @<string>}
-\end{describe}
+\begin{describe*}
+    {\dhead{gf}{c-fragment-text @<fragment> @> @<string>}
+     \dhead{meth}{c-fragment}
+       {file-location (@<fragment> c-fragment) @> @<floc>}}
+\end{describe*}
 
 \begin{describe}{fun}
     {scan-c-fragment @<scanner> @<end-chars>
