X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/74bf1b29b8cef573908180e6ab00cfeb6f324b46..1edb774eed8bea3f6dbde5b02db6ecd209394cf8:/doc/structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index 37ca9e3..01e1ecd 100644
--- a/doc/structures.tex
+++ b/doc/structures.tex
@@ -30,8 +30,14 @@ classes and associated metadata.  Note that Sod's object system is very
 flexible and it's possible for an extension to define a new root class which
 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 concrete types described in
+\xref[\instead{sections}]{sec:structures.common} and
+\ref{sec:structures.root} are declared by the header file
+@|<sod/sod.h>|.\footnote{%
+  This isn't completely true.  The @|SodObject| and @|SodClass| structures
+  are defined in a header called @|<sod/sod-base.h>|, which is generated by
+  the Sod translator; but @|<sod/sod.h>| includes @|<sod/sod-base.h>|, so you
+  can forget about this detail.} %
 The definitions described in \xref{sec:structures.layout} are defined in the
 header file generated by the containing module.
 
@@ -45,7 +51,7 @@ structure.
 Instance chains contain slots and vtable pointers, as described below.  All
 instances have the basic structure of a @|struct sod_instance|.
 
-\begin{describe}[struct sod_instance]{type}
+\begin{describe}{ty}[struct sod_instance]
     {struct sod_instance \{                                     \\ \ind
        const struct sod_vtable *_vt;                          \-\\
      \};}
@@ -57,7 +63,7 @@ instances have the basic structure of a @|struct sod_instance|.
   \end{description}
 \end{describe}
 
-\begin{describe}[struct sod_vtable]{type}
+\begin{describe}{ty}[struct sod_vtable]
     {struct sod_vtable \{                                       \\ \ind
        const SodClass *_class;                                  \\
        size_t _base;                                          \-\\
@@ -87,6 +93,12 @@ metaclass, and @|SodClass| is a subclass of @|SodObject|.  Extensions can
 define additional root classes, but this is tricky, and not really to be
 recommended.
 
+The class definitions shown in the synopses are intended to be informative,
+but are fictional and can't really work: these classes are really defined by
+Lisp code in the Sod translator, in order to deal with the circularities
+involved at the top of the class/metaclass graph (see
+\xref{sec:concepts.metaclasses.runtime}).
+
 
 \subsection{The SodObject class} \label{sec:structures.root.sodobject}
 
@@ -118,11 +130,11 @@ recommended.
   \label{fig:structures.root.sodobject}
 \end{figure}
 
-\begin{describe}[SodObject]{cls}
+\begin{describe}{cls}[SodObject]
     {[nick = obj, metaclass = SodClass,
       lisp_metaclass = sod_class]                               \\
      class SodObject \{                                         \\ \ind
-       void init(?);
+       void init(?);                                          \-\\
      \}}
 
   The @|SodObject| class defines no slots.  Because @|SodObject| has no
@@ -139,7 +151,7 @@ recommended.
 
   The following messages are defined.
 
-  \begin{describe}[obj.init]{msg}{void init(?);}
+  \begin{describe}{msg}[obj.init]{void init(?);}
     Initialize a newly allocated instance.
 
     This message uses a custom method combination which works like the
@@ -171,7 +183,7 @@ recommended.
     \xref{sec:concepts.lifecycle.birth}.
   \end{describe}
 
-  \begin{describe}[obj.teardown]{msg}{int teardown();}
+  \begin{describe}{msg}[obj.teardown]{int teardown();}
     Teardown an instance which is no longer required.
 
     The message returns an integer flag.  A zero value means that the
@@ -199,7 +211,7 @@ recommended.
 
 \subsection{The SodClass class} \label{sec:structures.root.sodclass}
 
-\begin{describe}[SodClass]{cls}
+\begin{describe}{cls}[SodClass]
     {[nick = cls, link = SodObject]                             \\
      class SodClass: SodObject \{                               \\ \ind
        const char *name;                                        \\
@@ -289,7 +301,7 @@ recommended.
   \end{description}
 \end{describe}
 
-\begin{describe}[struct sod_chain]{type}
+\begin{describe}{ty}[struct sod_chain]
     {struct sod_chain \{                                        \\ \ind
        size_t n_classes;                                        \\
        const SodClass *const *classes;                          \\
@@ -410,7 +422,7 @@ and this is followed by corresponding members
 \end{prog}
 for each of $C$'s superclasses $A$ in the same chain in some (unimportant)
 order.  The (somewhat obtuse) purpose of this union is to engage the `common
-initial sequence' rule of \cite[6.5.2.3]{ISO:1990:IIP,ANSI:1999:AII}.
+initial sequence' rule of \cite[6.5.2.3]{iso-1990:c,ansi-1999:c}.
 
 \subsubsection{The ichain structure}
 The @|ichain| structure contains (in order), a pointer