doc/: Switch to a manually maintained bibliography database.

[sod] / doc / structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index 6532dbd..01e1ecd 100644 (file)
--- 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.
 
 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.
 
 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|.
 
 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;                          \-\\
      \};}
     {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}
 
   \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;                                          \-\\
     {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.
 
 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}
 
 
 \subsection{The SodObject class} \label{sec:structures.root.sodobject}
 


@@ -118,11 +130,11 @@ recommended.
   \label{fig:structures.root.sodobject}
 \end{figure}
 
   \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
     {[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
      \}}
 
   The @|SodObject| class defines no slots.  Because @|SodObject| has no


@@ -139,7 +151,7 @@ recommended.
 
   The following messages are defined.
 
 
   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
     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}
 
     \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
     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}
 
 
 \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;                                        \\
     {[nick = cls, link = SodObject]                             \\
      class SodClass: SodObject \{                               \\ \ind
        const char *name;                                        \\


@@ -289,7 +301,7 @@ recommended.
   \end{description}
 \end{describe}
 
   \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;                          \\
     {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
 \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
 
 \subsubsection{The ichain structure}
 The @|ichain| structure contains (in order), a pointer


@@ -450,9 +462,9 @@ superclass in the same chain, and each slot must be stored in exactly one
 place.  The layout of vtables doesn't have this second requirement: it
 doesn't matter that there are multiple method entry pointers for the same
 effective method as long as they all work correctly.  Indeed, it's essential
 place.  The layout of vtables doesn't have this second requirement: it
 doesn't matter that there are multiple method entry pointers for the same
 effective method as long as they all work correctly.  Indeed, it's essential

-that they do, because each chain's method entry function will need to apply a
-different offset to the receiver pointer before invoking the effective
-method.
+that there are multiple entry pointers, because each chain's method entry
+function will need to apply a different offset to the receiver pointer before
+invoking the effective method.

 
 A vtable for a class $C$ with chain head $H$ has the following general
 structure.
 
 A vtable for a class $C$ with chain head $H$ has the following general
 structure.