From 054e8f8f1ea255ff77b19df82bd845e5686dac0d Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Thu, 21 Jun 2018 19:43:51 +0100
Subject: [PATCH] doc/: Some minor tweaks and corrections.

---
 doc/clang.tex    |  4 ++--
 doc/concepts.tex | 22 ++++++++++++----------
 doc/intro.tex    |  2 +-
 doc/misc.tex     |  2 +-
 doc/parsing.tex  |  8 ++++----
 doc/syntax.tex   |  6 ++++--
 6 files changed, 24 insertions(+), 20 deletions(-)

diff --git a/doc/clang.tex b/doc/clang.tex
index 6d256ec..b273a2c 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -169,12 +169,12 @@ type specifier.  Type specifiers fit into two syntactic categories.
 \begin{describe}{gf}{expand-c-type-spec @<type-spec> @> @<form>}
   Returns the Lisp form that @|(c-type @<type-spec>)| would expand into.
 
-  If @<type-spec> is a list, then \descref{expand-c-type-form}{fun} is
+  If @<type-spec> is a list, then \descref{expand-c-type-form}{gf} is
   invoked.
 \end{describe}
 
 \begin{describe}{gf}{expand-c-type-form @<head> @<tail> @> @<form>}
-  Returns the Lisp form that @|(c-type (@<head> . @<tail>)| would expand
+  Returns the Lisp form that @|(c-type (@<head> . @<tail>))| would expand
   into.
 \end{describe}
 
diff --git a/doc/concepts.tex b/doc/concepts.tex
index e301ae7..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
@@ -288,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
@@ -314,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
@@ -847,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}
diff --git a/doc/intro.tex b/doc/intro.tex
index 3e5e8f7..67a220f 100644
--- a/doc/intro.tex
+++ b/doc/intro.tex
@@ -164,7 +164,7 @@ the various @|_f| functions in the right order, like this:
     void _f() \{ std::cout <{}< "B@\\n"; \}                   \-\\
   public:                                                       \\ \ind
     virtual void f() \{ _f(); \}                                \\
-    virtual ~B() \{ \}                                        \-\\
+    virtual @~B() \{ \}                                        \-\\
   \};                                                           \\+
                                                                 %
   class X: virtual public B \{                                  \\
diff --git a/doc/misc.tex b/doc/misc.tex
index e77d512..7de8a23 100644
--- a/doc/misc.tex
+++ b/doc/misc.tex
@@ -272,7 +272,7 @@ These symbols are defined in the @|sod-parser| package.
 %%%--------------------------------------------------------------------------
 \section{Option parser} \label{sec:misc.optparse}
 
-These symbols are defined in the @!optparse| package.
+These symbols are defined in the @|optparse| package.
 
 \begin{describe}{fun}{exit \&optional (@<code> 0) \&key :abrupt}
 \end{describe}
diff --git a/doc/parsing.tex b/doc/parsing.tex
index 8ed8d65..51cc5bb 100644
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -241,7 +241,7 @@ depends on the type of scanner.  Given a captured place, the scanner can be
 rewound to the position held in it.
 
 Depending on how the scanner works, holding onto a captured place might
-consume a lot of memory or case poor performance.  For example, if the
+consume a lot of memory or cause poor performance.  For example, if the
 scanner is reading from an input stream, having a captured place means that
 data from that point on must be buffered in case the program needs to rewind
 the scanner and read that data again.  Therefore it's possible to
@@ -327,7 +327,7 @@ Character scanners are scanners which read sequences of characters.
 \begin{describe}{gf}{scanner-unread @<scanner> @<character>}
   Rewind the @<scanner> by one step.  The @<chararacter> must be the previous
   current character, and becomes the current character again.  It is an error
-  if: the @<scanner> has reached end-of-file; the @<scanner> is never been
+  if: the @<scanner> has reached end-of-file; the @<scanner> has never been
   stepped; or @<character> was not the previous current character.
 \end{describe}
 
@@ -421,7 +421,7 @@ file-location protocols.
 
 \begin{describe}{gf}
     {charbuf-scanner-map @<scanner> @<func> \&optional @<fail>
-      \nlret @<result> @<successp> @<consumedp>}
+      \nlret @<result> @<success-flag> @<consumed-flag>}
   Read characters from the @<scanner>'s buffers.
 
   This is intended to be an efficient and versatile interface for reading
@@ -437,7 +437,7 @@ file-location protocols.
   @<start> (inclusive) and @<end> (exclusive) should be processed.  If
   @<func>'s return value @<donep> is nil then @<used> is ignored: the
   function has consumed the entire buffer and wishes to read more.  If
-  @<donep> is non-nil, then it must be a fixnum such that $@<start> \le
+  @<donep> is non-nil, then @<used> must be a fixnum such that $@<start> \le
   @<used> \le @<end>$: the function has consumed the buffer as far as @<used>
   (exclusive) and has completed successfully.
 
diff --git a/doc/syntax.tex b/doc/syntax.tex
index 6ebdc78..7c2ee75 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -635,6 +635,8 @@ Properties:
 \item[@"initarg"] An identifier naming an initialization argument which can
   be used to provide a value for the slot.  See
   \xref{sec:concepts.lifecycle.birth} for the details.
+\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
+  the initarg.  Only permitted if @"initarg" is also set.
 \end{description}
 
 An @<initializer>, if present, is treated as if a separate
@@ -661,7 +663,7 @@ class Example: Super \{                                         \\ \ind
 
 <slot-initializer> ::= <dotted-name> @["=" <initializer>@]
 
-<initializer> :: <c-fragment>
+<initializer> ::= <c-fragment>
 \end{grammar}
 
 An @<initializer-item> provides an initial value for one or more slots.  If
@@ -735,7 +737,7 @@ Properties for the @|custom| aggregating method combination:
   in the effective method.  The default is @|sod__val|.  Only permitted if
   the method return type (see @"methty" below) is not @|void|.
 \item[@"methty"] A C type, which is the return type for direct methods of
-  this message.
+  this message.  The default is the return type of the message.
 \item[@"decls"] A code fragment containing declarations to be inserted at the
   head of the effective method body.  The default is to insert nothing.
 \item[@"before"] A code fragment containing initialization to be performed at
-- 
2.11.0

