X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/e160ec736350f63d5127d954418eef5d667c7f30..4307347660f48628e307f299eb4fac58ba35fd1a:/doc/structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index 8be9a65..0b6be0a 100644
--- a/doc/structures.tex
+++ b/doc/structures.tex
@@ -32,8 +32,8 @@ works very differently from the standard @|SodObject| described here.
 
 The concrete types described in \xref{sec:structures.common} and
 \ref{sec:structures.root} are declared by the header file @|<sod/sod.h>|.
-The definitions described in sections \ref{sec:structures.layout} are defined
-in the header file generated by the containing module.
+The definitions described in \xref{sec:structures.layout} are defined in the
+header file generated by the containing module.
 
 %%%--------------------------------------------------------------------------
 \section{Common instance structure} \label{sec:structures.common}
@@ -92,7 +92,7 @@ recommended.
 
 \begin{figure}[tbp]
   \begin{tabular}{p{10pt}p{10pt}}
-    \begin{prog}
+    \begin{nprog}
       struct SodObject__ilayout \{ \\ \ind
         union \{ \\ \ind
           struct SodObject__ichain_obj \{ \\ \ind
@@ -100,21 +100,21 @@ recommended.
           \} obj; \- \\
         \} obj; \- \\
       \};
-    \end{prog}
+    \end{nprog}
     &
-    \begin{prog}
+    \begin{nprog}
       struct SodObject__vt_obj \{ \\ \ind
         const SodClass *_class; \\
         size_t _base; \- \\
       \};
-    \end{prog} \\
+    \end{nprog} \\
   \end{tabular}
   \caption{Instance and vtable layout of @|SodObject|}
   \label{fig:structures.root.sodobject}
 \end{figure}
 
 \begin{describe}[SodObject]{cls}
-    {[metaclass = SodClass, lisp_metaclass = sod_class] \\
+    {[nick = obj, metaclass = SodClass, lisp_metaclass = sod_class] \\
      class SodObject \{ \}}
 
   The @|SodObject| class defines no slots or messages.  Because @|SodObject|
@@ -134,7 +134,8 @@ recommended.
 \subsection{The SodClass class} \label{sec:structures.root.sodclass}
 
 \begin{describe}[SodClass]{cls}
-    {class SodClass : SodObject \{ \\ \ind
+    {[nick = cls, link = SodObject] \\
+     class SodClass : SodObject \{ \\ \ind
        const char *name; \\
        const char *nick; \\
        size_t initsz; \\
@@ -191,7 +192,7 @@ recommended.
 
   \item[cpl] A pointer to an array of pointers to class objects listing all
     of the class's superclasses, from most- to least-specific, starting with
-    the class itself, so $c@->@|cls|.@|cpl|[0] = c$ for all class objects
+    the class itself, so $@|$c$@->cls.cpl[0]| = c$ for all class objects
     $c$.
 
   \item[link] If the class is a chain head, then this is a null pointer;
@@ -199,21 +200,20 @@ recommended.
     might or might not be a direct superclass).
 
   \item[head] A pointer to the least-specific class in this class's chain; so
-    $c@->@|cls|.@|head|@->@|cls|.@|link|$ is always null, and either
-    $c@->@|cls|.@|link|$ is null (in which case $c@->@|cls|.@|head| = c$) or
-    $c@->@|cls|.@|head| = c@->@|cls|.@|link|@->@|cls|.@|head|$.
+    @|$c$@->cls.head@->cls.link| is always null, and either @|$c$@->cls.link|
+    is null (in which case $@|$c$@->cls.head| = c$) or $@|$c$@->cls.head| =
+    @|$c$@->cls.link@->cls.head|$.
 
   \item[level] The number of less specific superclasses in this class's
-    chain.  If $c@->@|cls|.@|link|$ is null then $c@->@|cls|.@|level|$ is
-    zero; otherwise $c@->@|cls|.@|level| =
-    c@->@|cls|.@|link|@->@|cls|.@|level| + 1$.
+    chain.  If @|$c$@->cls.link| is null then @|$c$@->cls.level| is zero;
+    otherwise $@|$c$@->cls.level| = @|$c$@->cls.link@->cls.level| + 1$.
 
   \item[n_chains] The number of chains formed by the class's superclasses.
 
   \item[chains] A pointer to an array of @|struct sod_chain| structures (see
     below) describing the class's superclass chains, in decreasing order of
     specificity of their most specific classes.  It is always the case that
-    $c@->@|cls|.@|chains|[0].@|classes|[c@->@|cls|.@|level|] = c$.
+    $@|$c$@->cls.chains[0].classes[$c$@->cls.level]| = c$.
 
   \item[off_islots] The offset of the class's @|islots| structure relative to
     its containing @|ichain| structure.  The class doesn't define any slots
@@ -245,9 +245,9 @@ recommended.
 
   \item[classes] A pointer to an array of class pointers listing the classes
     in the chain from least- to most-specific.  So
-    $@<classes>[i]@->@|cls|.@|head| = @<classes>[0]$ for all $0 \le i <
-    @<n_classes>$, $@<classes>[0]@->@|cls|.@|link|$ is always null, and
-    $@<classes>[i]@->@|cls|.@|link| = @<classes>[i - 1]$ if $1 \le i <
+    $@|@<classes>[$i$]@->cls.head| = @|@<classes>[0]|$ for all $0 \le i <
+    @<n_classes>$, @|@<classes>[0]@->cls.link| is always null, and
+    $@|@<classes>[$i$]@->cls.link| = @|@<classes>[$i - 1$]|$ if $1 \le i <
     @<n_classes>$.
 
   \item[off_ichain] The size of the @|ichain| structure for this chain.
@@ -307,7 +307,7 @@ type @|struct $C$__ilayout|.
     union $B$__ichainu_$i$ $i$; \\
     \quad$\vdots$ \- \\
   \};
-  \\[\bigskipamount]
+  \\+
   typedef struct $C$__ichain_$h$ $C$;
 \end{prog}
 
@@ -412,7 +412,7 @@ structure.
       \quad$\vdots$ \- \\
     \} $c$; \- \\
   \};
-  \\[\bigskipamount]
+  \\+
   extern const union $C$__vtu_$h$ $C$__vtable_$h$;
 \end{prog}
 
@@ -526,10 +526,16 @@ defined as
 \begin{prog}
   @<type>_0 $m$(@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n, \dots);
 \end{prog}
+or a standard message which takes keyword arguments, defined as
+\begin{prog}
+  @<type>_0 $m$(\=@<type>_1 @<arg>_1, $\ldots$, @<type>_n @<arg>_n? \+ \\
+                  @<type>_{n+1} @<kw>_{n+1} @[= @<dflt>_{n+1}@], $\ldots$,
+                  @<type>_m @<kw>_m @[= @<dflt>_m@]);
+\end{prog}
 two entry points are defined: the usual `main' entry point which accepts a
 variable number of arguments, and a `valist' entry point which accepts an
 argument of type @|va_list| in place of the variable portion of the argument
-list.
+list or keywords.
 \begin{prog}
   @<type>_0 $m$($C$ *me, @<type>_1 @<arg>_1, $\ldots$,
                 @<type>_n @<arg>_n, \dots); \\
@@ -550,10 +556,10 @@ For each message $m$ directly defined by $C$ there is a macro definition
 which makes sending the message $m$ to an instance of (any subclass of) $C$
 somewhat less ugly.
 
-If $m$ takes a variable number of arguments, the macro is more complicated
-and is only available in compilers advertising C99 support, but the effect is
-the same.  For each variable-argument message, there is also an additional
-macro for calling the `valist' entry point.
+If $m$ takes a variable number of arguments, or keyword arguments, the macro
+is more complicated and is only available in compilers advertising C99
+support, but the effect is the same.  For each variable-argument message,
+there is also an additional macro for calling the `valist' entry point.
 \begin{prog}
   \#define $C$_$m$__v(@<me>, $\ldots$, @<sod__ap>)
     @<me>@->_vt@->$c$.$m$__v(@<me>, $\ldots$, @<sod__ap>)