New feature: messages with keyword arguments!

[sod] / doc / structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index 2fcbb2e964bb98d3c3193e11b320fe330ec32341..0b6be0a7bd250b82d3345ed5ce4ebf73fb411702 100644 (file)
--- 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,14 +100,14 @@ 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}
@@ -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>)