X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/3a774b55edfea441c1715994924c2999e9202143..054e8f8f1ea255ff77b19df82bd845e5686dac0d:/doc/concepts.tex?ds=sidebyside

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 9cc5be7..187a6f8 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -122,11 +122,11 @@ superclasses.
 If an object is a direct instance of class~$C$ then the object is also an
 (indirect) instance of every superclass of $C$.
 
-If $C$ has a proper superclass $B$, then $B$ is not allowed to have $C$ has a
-direct superclass.  In different terms, if we construct a graph, whose
-vertices are classes, and draw an edge from each class to each of its direct
-superclasses, then this graph must be acyclic.  In yet other terms, the `is a
-superclass of' relation is a partial order on classes.
+If $C$ has a proper superclass $B$, then $B$ must not have $C$ as a direct
+superclass.  In different terms, if we construct a graph, whose vertices are
+classes, and draw an edge from each class to each of its direct superclasses,
+then this graph must be acyclic.  In yet other terms, the `is a superclass
+of' relation is a partial order on classes.
 
 \subsubsection{The class precedence list}
 This partial order is not quite sufficient for our purposes.  For each class
@@ -177,11 +177,12 @@ a link superclass, and the link superclass of a class $C$, if it exists, need
 not be a direct superclass of $C$.
 
 Superclass links must obey the following rule: if $C$ is a class, then there
-must be no three superclasses $X$, $Y$ and~$Z$ of $C$ such that $Z$ is the
-link superclass of both $X$ and $Y$.  As a consequence of this rule, the
-superclasses of $C$ can be partitioned into linear \emph{chains}, such that
-superclasses $A$ and $B$ are in the same chain if and only if one can trace a
-path from $A$ to $B$ by following superclass links, or \emph{vice versa}.
+must be no three distinct superclasses $X$, $Y$ and~$Z$ of $C$ such that $Z$
+is the link superclass of both $X$ and $Y$.  As a consequence of this rule,
+the superclasses of $C$ can be partitioned into linear \emph{chains}, such
+that superclasses $A$ and $B$ are in the same chain if and only if one can
+trace a path from $A$ to $B$ by following superclass links, or \emph{vice
+versa}.
 
 Since a class links only to one of its proper superclasses, the classes in a
 chain are naturally ordered from most- to least-specific.  The least specific
@@ -287,8 +288,10 @@ and its type is usually @|SodClass|; @|SodClass|'s nickname is @|cls|.
 
 A class object's slots contain or point to useful information, tables and
 functions for working with that class's instances.  (The @|SodClass| class
-doesn't define any messages, so it doesn't have any methods.  In Sod, a class
-slot containing a function pointer is not at all the same thing as a method.)
+doesn't define any messages, so it doesn't have any methods other than for
+the @|SodObject| lifecycle messages @|init| and @|teardown|; see
+\xref{sec:concepts.lifecycle}.  In Sod, a class slot containing a function
+pointer is not at all the same thing as a method.)
 
 \subsubsection{Conversions}
 Suppose one has a value of type pointer-to-class-type for some class~$C$, and
@@ -313,7 +316,7 @@ There are three main cases to distinguish.
   conversion can fail: the object in question might not be an instance of~$B$
   after all.  The macro \descref{SOD_CONVERT}{mac} and the function
   \descref{sod_convert}{fun} perform general conversions.  They return a null
-  pointer if the conversion fails.  (There are therefore your analogue to the
+  pointer if the conversion fails.  (These are therefore your analogue to the
   \Cplusplus\ @|dynamic_cast<>| operator.)
 \end{itemize}
 The Sod translator generates macros for performing both in-chain and
@@ -371,7 +374,7 @@ Keyword arguments can be provided in three ways.
 
 Keyword arguments are provided as a general feature for C functions.
 However, Sod has special support for messages which accept keyword arguments
-(\xref{sec:concepts.methods.keywords}); and they play an essential role in
+(\xref{sec:concepts.methods.keywords}); and they play an essential rÃ´le in
 the instance construction protocol (\xref{sec:concepts.lifecycle.birth}).
 
 %%%--------------------------------------------------------------------------
@@ -407,12 +410,12 @@ A class definition may include \emph{direct methods} for messages defined by
 it or any of its superclasses.
 
 Like messages, direct methods define argument lists and return types, but
-they may also have a \emph{body}, and a \emph{role}.
+they may also have a \emph{body}, and a \emph{rÃ´le}.
 
 A direct method need not have the same argument list or return type as its
 message.  The acceptable argument lists and return types for a method depend
 on the message, in particular its method combination
-(\xref{sec:concepts.methods.combination}), and the method's role.
+(\xref{sec:concepts.methods.combination}), and the method's rÃ´le.
 
 A direct method body is a block of C code, and the Sod translator usually
 defines, for each direct method, a function with external linkage, whose body
@@ -430,8 +433,8 @@ the object's class and its superclasses.  These direct methods are combined
 together to form the \emph{effective method} for that particular class and
 message.  Direct methods can be combined into an effective method in
 different ways, according to the \emph{method combination} specified by the
-message.  The method combination determines which direct method roles are
-acceptable, and, for each role, the appropriate argument lists and return
+message.  The method combination determines which direct method rÃ´les are
+acceptable, and, for each rÃ´le, the appropriate argument lists and return
 types.
 
 One direct method, $M$, is said to be more (resp.\ less) \emph{specific} than
@@ -442,7 +445,7 @@ defining $N$.
 \subsubsection{The standard method combination}
 The default method combination is called the \emph{standard method
 combination}; other method combinations are useful occasionally for special
-effects.  The standard method combination accepts four direct method roles,
+effects.  The standard method combination accepts four direct method rÃ´les,
 called `primary' (the default), @|before|, @|after|, and @|around|.
 
 All direct methods subject to the standard method combination must have
@@ -499,7 +502,7 @@ entry functions.
         node [midway, right, align=left]
         {Most to \\ least \\ specific};}
 
-    \delgstack{a}{}{Around method}
+    \delgstack{a}{}{@|around| method}
     \draw [<-] ($(a0.south)!.5!(a0.south west) - (0mm, 1mm)$) --
                ++(0mm, -4mm);
     \draw [->] ($(a0.south)!.5!(a0.south east) - (0mm, 1mm)$) --
@@ -511,7 +514,7 @@ entry functions.
       node [code, midway, left=3mm] {next_method}
       node (b0) [method, above left = 1mm + 4mm and -6mm - 4mm] {};
     \node (b1) [method] at ($(b0) - (2mm, 2mm)$) {};
-    \node (bn) [method] at ($(b1) - (2mm, 2mm)$) {Before method};
+    \node (bn) [method] at ($(b1) - (2mm, 2mm)$) {@|before| method};
     \draw [->, order] ($(bn.west) - (6mm, 0mm)$) -- ++(12mm, 12mm)
       node [midway, above left, align=center] {Most to \\ least \\ specific};
     \draw [->] ($(b0.north east) + (-10mm, 1mm)$) -- ++(8mm, 8mm)
@@ -537,7 +540,7 @@ entry functions.
       node [action, midway, right=3mm] {return}
       node (f0) [method, above right = 1mm and -6mm] {};
     \node (f1) [method] at ($(f0) + (-2mm, 2mm)$) {};
-    \node (fn) [method] at ($(f1) + (-2mm, 2mm)$) {After method};
+    \node (fn) [method] at ($(f1) + (-2mm, 2mm)$) {@|after| method};
     \draw [<-, order] ($(f0.east) + (6mm, 0mm)$) -- ++(-12mm, 12mm)
       node [midway, above right, align=center]
       {Least to \\ most \\ specific};
@@ -553,7 +556,7 @@ The effective method for a message with standard method combination works as
 follows (see also~\xref{fig:concepts.methods.stdmeth}).
 \begin{enumerate}
 
-\item If any applicable methods have the @|around| role, then the most
+\item If any applicable methods have the @|around| rÃ´le, then the most
   specific such method, with respect to the class of the receiving object, is
   invoked.
 
@@ -563,21 +566,21 @@ follows (see also~\xref{fig:concepts.methods.stdmeth}).
 
   If there any remaining @|around| methods, then @|next_method| invokes the
   next most specific such method, returning whichever value that method
-  returns; otherwise the behaviour of @|next_method| is to invoke the before
-  methods (if any), followed by the most specific primary method, followed by
-  the @|around| methods (if any), and to return whichever value was returned
-  by the most specific primary method, as described in the following items.
-  That is, the behaviour of the least specific @|around| method's
-  @|next_method| function is exactly the behaviour that the effective method
-  would have if there were no @|around| methods.  Note that if the
-  least-specific @|around| method calls its @|next_method| more than once
-  then the whole sequence of @|before|, primary, and @|after| methods occurs
-  multiple times.
+  returns; otherwise the behaviour of @|next_method| is to invoke the
+  @|before| methods (if any), followed by the most specific primary method,
+  followed by the @|after| methods (if any), and to return whichever value
+  was returned by the most specific primary method, as described in the
+  following items.  That is, the behaviour of the least specific @|around|
+  method's @|next_method| function is exactly the behaviour that the
+  effective method would have if there were no @|around| methods.  Note that
+  if the least-specific @|around| method calls its @|next_method| more than
+  once then the whole sequence of @|before|, primary, and @|after| methods
+  occurs multiple times.
 
   The value returned by the most specific @|around| method is the value
   returned by the effective method.
 
-\item If any applicable methods have the @|before| role, then they are all
+\item If any applicable methods have the @|before| rÃ´le, then they are all
   invoked, starting with the most specific.
 
 \item The most specific applicable primary method is invoked.
@@ -598,7 +601,7 @@ follows (see also~\xref{fig:concepts.methods.stdmeth}).
   returned to the least specific @|around| method, which called it via its
   own @|next_method| function.
 
-\item If any applicable methods have the @|after| role, then they are all
+\item If any applicable methods have the @|after| rÃ´le, then they are all
   invoked, starting with the \emph{least} specific.  (Hence, the most
   specific @|after| method is invoked with the most `afterness'.)
 
@@ -606,10 +609,10 @@ follows (see also~\xref{fig:concepts.methods.stdmeth}).
 
 A typical use for @|around| methods is to allow a base class to set up the
 dynamic environment appropriately for the primary methods of its subclasses,
-e.g., by claiming a lock, and restore it afterwards.
+e.g., by claiming a lock, and releasing it afterwards.
 
 The @|next_method| function provided to methods with the primary and
-@|around| roles accepts the same arguments, and returns the same type, as the
+@|around| rÃ´les accepts the same arguments, and returns the same type, as the
 message, except that one or two additional arguments are inserted at the
 front of the argument list.  The first additional argument is always the
 receiving object, @|me|.  If the message accepts a variable argument suffix,
@@ -619,7 +622,7 @@ second additional argument; otherwise, In the former case, a variable
 of the argument pointer (so the method body can process the variable argument
 suffix itself, and still pass a fresh copy on to the next method).
 
-A method with the primary or @|around| role may use the convenience macro
+A method with the primary or @|around| rÃ´le may use the convenience macro
 @|CALL_NEXT_METHOD|, which takes no arguments itself, and simply calls
 @|next_method| with appropriate arguments: the receiver @|me| pointer, the
 argument pointer @|sod__master_ap| (if applicable), and the method's
@@ -639,7 +642,7 @@ specific primary method, as the standard method combination does, they invoke
 the applicable primary methods in turn and aggregate the return values from
 each.
 
-The aggregating method combinations accept the same four roles as the
+The aggregating method combinations accept the same four rÃ´les as the
 standard method combination, and @|around|, @|before|, and @|after| methods
 work in the same way.
 
@@ -812,8 +815,8 @@ imprint storage for one of that class's instances.
 
 Once an instance's storage has been imprinted, it is technically possible to
 send messages to the instance; however the instance's slots are still
-uninitialized at this point, the applicable methods are unlikely to do much
-of any use unless they've been written specifically for the purpose.
+uninitialized at this point, so the applicable methods are unlikely to do
+much of any use unless they've been written specifically for the purpose.
 
 The following simple function imprints storage at address @<p> as an instance
 of a class, given a pointer to its class object @<cls>.
@@ -846,8 +849,8 @@ other method takes steps to prevent this.
 
 Slots are initialized in a well-defined order.
 \begin{itemize}
-\item Slots defined by a more specific superclasses are initialized after
-  slots defined by a less specific superclass.
+\item Slots defined by a more specific superclass are initialized after slots
+  defined by a less specific superclass.
 \item Slots defined by the same class are initialized in the order in which
   their definitions appear.
 \end{itemize}
@@ -875,9 +878,9 @@ There are two kinds of initarg definitions.  \emph{User initargs} are defined
 by an explicit @|initarg| item appearing in a class definition: the item
 defines a name, type, and (optionally) a default value for the initarg.
 \emph{Slot initargs} are defined by attaching an @|initarg| property to a
-slot or slot initializer item: the property's determines the initarg's name,
-while the type is taken from the underlying slot type; slot initargs do not
-have default values.  Both kinds define a \emph{direct initarg} for the
+slot or slot initializer item: the property's value determines the initarg's
+name, while the type is taken from the underlying slot type; slot initargs do
+not have default values.  Both kinds define a \emph{direct initarg} for the
 containing class.
 
 Initargs are inherited.  The \emph{applicable} direct initargs for an @|init|
