From: Mark Wooding <mdw@distorted.org.uk>
Date: Tue, 15 Dec 2015 14:31:01 +0000 (+0000)
Subject: doc/concepts.tex: Highlight method role names.
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/commitdiff_plain/b1254eb62a3ca4eb2839cd0f340d754f45d549a2

doc/concepts.tex: Highlight method role names.
---

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 46d99b1..9a77c44 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -507,9 +507,9 @@ argument lists which \emph{match} the message's argument list:
 \item if the message accepts a variable-length argument suffix then the
   direct method must instead have a final argument of type @|va_list|.
 \end{itemize}
-Primary and around methods must have the same return type as the message;
-before and after methods must return @|void| regardless of the message's
-return type.
+Primary and @|around| methods must have the same return type as the message;
+@|before| and @|after| methods must return @|void| regardless of the
+message's return type.
 
 If there are no applicable primary methods then no effective method is
 constructed: the vtables contain null pointers in place of pointers to method
@@ -523,21 +523,22 @@ follows.
   specific such method, with respect to the class of the receiving object, is
   invoked.
 
-  Within the body of an around method, the variable @|next_method| is
+  Within the body of an @|around| method, the variable @|next_method| is
   defined, having pointer-to-function type.  The method may call this
   function, as described below, any number of times.
 
-  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.  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.
+  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.  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.
 
-  The value returned by the most specific around method is the value returned
-  by the effective method.
+  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
   invoked, starting with the most specific.
@@ -554,20 +555,21 @@ follows.
   invoke the next most specific applicable primary method, and to return
   whichever value that method returns.
 
-  If there are no applicable around methods, then the value returned by the
-  most specific primary method is the value returned by the effective method;
-  otherwise the value returned by the most specific primary method is
-  returned to the least specific around method, which called it via its own
-  @|next_method| function.
+  If there are no applicable @|around| methods, then the value returned by
+  the most specific primary method is the value returned by the effective
+  method; otherwise the value returned by the most specific primary method is
+  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
   invoked, starting with the \emph{least} specific.  (Hence, the most
-  specific after method is invoked with the most `afterness'.)
+  specific @|after| method is invoked with the most `afterness'.)
 
 \end{enumerate}
 
-A typical use for around methods is to set up the dynamic environment
-appropriately for the primary methods, e.g., by claiming a lock.
+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.
 
 The @|next_method| function provided to methods with the @|primary| and
 @|around| roles accepts the same arguments, and returns the same type, as the
@@ -598,8 +600,8 @@ the applicable primary methods in turn and aggregate the return values from
 each.
 
 The aggregating method combinations accept the same four roles as the
-standard method combination, and around, before, and after methods work in
-the same way.
+standard method combination, and @|around|, @|before|, and @|after| methods
+work in the same way.
 
 The aggregating method combinations provided are as follows.
 \begin{description} \let\makelabel\code