doc/sod.sty, doc/*.tex: New notation for line control in `prog'.

[sod] / doc / concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index f332be1bf3f4330bc263868c621461a120abcf85..20402dc0807aa3e1a0b80cc763b27525f8f9e3e7 100644 (file)
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -110,6 +110,7 @@ appropriate C declarations, tables, and functions.  An object cannot
 (usually) change its direct class, and the direct class of an object is not
 affected by, for example, the static type of a pointer to it.
 
+
 \subsection{Superclasses and inheritance}
 \label{sec:concepts.classes.inherit}
 
@@ -232,6 +233,7 @@ Classes have a number of other attributes:
   then all the superclasses of $C$ must have distinct nicknames.
 \end{itemize}
 
+
 \subsection{Slots} \label{sec:concepts.classes.slots}
 
 Each class defines a number of \emph{slots}.  Much like a structure member, a
@@ -257,6 +259,7 @@ expressions if the generated code is expected to be processed by a
 implementation of C89.  Initializers will be evaluated once each time an
 instance is initialized.
 
+
 \subsection{C language integration} \label{sec:concepts.classes.c}
 
 For each class~$C$, the Sod translator defines a C type, the \emph{class
@@ -278,7 +281,7 @@ about these slot members: C code can access them in the usual way.
 For example, if @|MyClass| has the nickname @|mine|, and defines a slot @|x|
 of type @|int|, then the simple function
 \begin{prog}
-  int get_x(MyClass *m) \{ return (m->mine.x); \}
+  int get_x(MyClass *m) \{ return (m@->mine.x); \}
 \end{prog}
 will extract the value of @|x| from an instance of @|MyClass|.
 
@@ -346,15 +349,15 @@ interim approach is to specify slot initializers where appropriate and send
 class-specific messages for more complicated parametrized initialization.
 
 Automatic-duration instances can be conveniently constructed and initialized
-using the @|SOD_DECL| macro (page~\pageref{mac:SOD-DECL}).  No special
-support is currently provided for dynamically allocated instances.  A simple
-function using @|malloc| might work as follows.
+using the \descref{SOD_DECL}[macro]{mac}.  No special support is currently
+provided for dynamically allocated instances.  A simple function using
+@|malloc| might work as follows.
 \begin{prog}
   void *new_instance(const SodClass *c) \\
   \{ \\ \ind
-    void *p = malloc(c->cls.initsz); \\
+    void *p = malloc(c@->cls.initsz); \\
     if (!p) return (0); \\
-    c->cls.init(p); \\
+    c@->cls.init(p); \\
     return (p); \- \\
   \}
 \end{prog}
@@ -363,26 +366,27 @@ function using @|malloc| might work as follows.
 There is currently no provided assistance for finalization or deallocation.
 It is the programmer's responsibility to decide and implement an appropriate
 protocol.  Note that to free an instance allocated from the heap, one must
-correctly find its base address: the @|SOD_INSTBASE| macro
-(page~\pageref{mac:SOD-INSTBASE}) will do this for you.
+correctly find its base address: the \descref{SOD_INSTBASE}[macro]{mac} will
+do this for you.
 
 The following simple mixin class is suggested.
 \begin{prog}
-  [nick = disposable] \\*
-  class DisposableObject : SodObject \{ \\*[\jot] \ind
-    void release() \{ ; \} \\*
-    \quad /\=\+* Release resources held by the receiver. */ \-\- \\*[\jot]
-  \} \\[\bigskipamount]
-  code c : user \{ \\* \ind
-    /\=\+* Free object p's instance storage.  If p is a DisposableObject \\*
-       {}* then release its resources beforehand. \\*
-       {}*/ \- \\*
-    void free_instance(void *p) \\*
-    \{ \\* \ind
-      DisposableObject *d = SOD_CONVERT(DisposableObject, p); \\*
-      if (d) DisposableObject_release(d); \\*
-      free(d); \- \\*
-    \} \- \\*
+  [nick = disposable] \\
+  class DisposableObject : SodObject \{ \\- \ind
+    void release() \{ ; \} \\
+    \quad /* Release resources held by the receiver. */ \- \\-
+  \}
+  \\+
+  code c : user \{ \\- \ind
+    /\=\+* Free object p's instance storage.  If p is a DisposableObject \\
+       {}* then release its resources beforehand. \\
+       {}*/ \- \\
+    void free_instance(void *p) \\
+    \{ \\ \ind
+      DisposableObject *d = SOD_CONVERT(DisposableObject, p); \\
+      if (d) DisposableObject_release(d); \\
+      free(d); \- \\
+    \} \- \\
   \}
 \end{prog}
 
@@ -403,13 +407,13 @@ There are three main cases to distinguish.
   a lookup at runtime to find the appropriate offset by which to adjust the
   pointer.  The conversion can be performed using the appropriate generated
   upcast macro (see below); the general case is handled by the macro
-  @|SOD_XCHAIN| (page~\pageref{mac:SOD-XCHAIN}).
+  \descref{SOD_XCHAIN}{mac}.
 \item If $B$ is a subclass of~$C$ then the conversion is an \emph{upcast};
   otherwise the conversion is a~\emph{cross-cast}.  In either case, the
   conversion can fail: the object in question might not be an instance of~$B$
-  at all.  The macro @|SOD_CONVERT| (page~\pageref{mac:SOD-CONVERT}) and the
-  function @|sod_convert| (page~\pageref{fun:sod-convert}) perform general
-  conversions.  They return a null pointer if the conversion fails.
+  at 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.
 \end{itemize}
 The Sod translator generates macros for performing both in-chain and
 cross-chain upcasts.  For each class~$C$, and each proper superclass~$B$
@@ -473,6 +477,7 @@ contains a copy of the direct method body.  Within the body of a direct
 method defined for a class $C$, the variable @|me|, of type pointer to class
 type of $C$, refers to the receiving object.
 
+
 \subsection{Effective methods and method combinations}
 \label{sec:concepts.methods.combination}