X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/1818107e8198734df843841a51bca3713bd37596..4effe5759a1229be4ce152db87172119ddcb45bb:/doc/structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index 561075b..9c0451e 100644
--- a/doc/structures.tex
+++ b/doc/structures.tex
@@ -87,33 +87,34 @@ metaclass, and @|SodClass| is a subclass of @|SodObject|.  Extensions can
 define additional root classes, but this is tricky, and not really to be
 recommended.
 
+
 \subsection{The SodObject class} \label{sec:structures.root.sodobject}
 
 \begin{figure}[tbp]
   \begin{tabular}{p{10pt}p{10pt}}
-    \begin{prog}
+    \begin{nprog}
       struct SodObject__ilayout \{ \\ \ind
         union \{ \\ \ind
           struct SodObject__ichain_obj \{ \\ \ind
             const struct SodObject__vt_obj *_vt; \- \\
-          \}; \- \\
+          \} 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|
@@ -129,10 +130,12 @@ recommended.
   \xref{fig:structures.root.sodobject}.
 \end{describe}
 
+
 \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; \\
@@ -189,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;
@@ -197,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
@@ -234,33 +236,33 @@ recommended.
        size_t ichainsz; \- \\
      \};}
 
-   The @|struct sod_chain| structure describes an individual chain of
-   superclasses.  It has the following members.
-   \begin{description} \let\makelabel\code
+  The @|struct sod_chain| structure describes an individual chain of
+  superclasses.  It has the following members.
+  \begin{description} \let\makelabel\code
 
-   \item[n_classes] The number of classes in the chain.  This is always at
-     least one.
+  \item[n_classes] The number of classes in the chain.  This is always at
+    least one.
 
-   \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 <
-     @<n_classes>$.
+  \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 <
+    @<n_classes>$.
 
-   \item[off_ichain] The size of the @|ichain| structure for this chain.
+  \item[off_ichain] The size of the @|ichain| structure for this chain.
 
-   \item[vt] The vtable for this chain.  (It is possible, therefore, to
-     partially duplicate the behaviour of the @<imprint> function by walking
-     the chain structure.\footnote{%
-       There isn't enough information readily available to fill in the class
-       pointers correctly.} %
-     The @<imprint> function is much faster, though.)
+  \item[vt] The vtable for this chain.  (It is possible, therefore, to
+    partially duplicate the behaviour of the @<imprint> function by walking
+    the chain structure.\footnote{%
+      There isn't enough information readily available to fill in the class
+      pointers correctly.} %
+    The @<imprint> function is much faster, though.)
 
-   \item[ichainsz] The size of the @|ichain| structure for this chain.
+  \item[ichainsz] The size of the @|ichain| structure for this chain.
 
-   \end{description}
- \end{describe}
+  \end{description}
+\end{describe}
 
 %%%--------------------------------------------------------------------------
 \section{Class and vtable layout} \label{sec:structures.layout}
@@ -279,6 +281,7 @@ In the description that follows, uppercase letters vary over class names,
 while the corresponding lowercase letters indicate the class nicknames.
 Throughout, we consider a class $C$ (therefore with nickname $c$).
 
+
 \subsection{Generic instance structure}
 \label{sec:structures.layout.instance}
 
@@ -304,7 +307,7 @@ type @|struct $C$__ilayout|.
     union $B$__ichainu_$i$ $i$; \\
     \quad$\vdots$ \- \\
   \};
-  \\[\bigskipamount]
+  \\+
   typedef struct $C$__ichain_$h$ $C$;
 \end{prog}
 
@@ -369,6 +372,7 @@ type system) to be a pointer to the @|struct $C$__ichain_$h$|.
 Finally, the @|islots| structure simply contains one member for each slot
 defined by $C$ in the order they appear in the class definition.
 
+
 \subsection{Generic vtable structure} \label{sec:structures.layout.vtable}
 
 As described above, each @|ichain| structure of an instance's storage has a
@@ -408,7 +412,7 @@ structure.
       \quad$\vdots$ \- \\
     \} $c$; \- \\
   \};
-  \\[\bigskipamount]
+  \\+
   extern const union $C$__vtu_$h$ $C$__vtable_$h$;
 \end{prog}
 
@@ -533,7 +537,8 @@ list.
                    @<type>_n @<arg>_n, va_list sod__ap);
 \end{prog}
 
-\subsection{Additional definitions} \label{sec:structures.additional}
+
+\subsection{Additional definitions} \label{sec:structures.layout.additional}
 
 In addition to the instance and vtable structures described above, the
 following definitions are made for each class $C$.
