Subject: [Patch] Clarify the distinction between "syntax codes" and the cons cells that contain them

From: Nathan Trapuzzano <[email-masked]>
Date: Fri, 07 Sep 2012 20:43:23 -0400

The lispref info node on "Syntax Table Internals" uses "syntax code"
interchangeably to refer to both the car of syntax table elements and
the elements (cons cells) themselves. This is confusing, for example,
because the function "syntax-class" throws a wrong-type-argument error
if its argument is the bare integer syntax code instead of a cons
cell. I propose the following minor changes:

diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 91ae435..fa000c3 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -996,18 +996,20 @@ corresponding internal form, a cons cell @code{(@var{syntax-code}
 @end defun
 
 @defun syntax-after pos
-This function returns the syntax code of the character in the buffer
-after position @var{pos}, taking account of syntax properties as well
-as the syntax table.  If @var{pos} is outside the buffer's accessible
-portion (@pxref{Narrowing, accessible portion}), this function returns
+This function returns the syntax cons cell @code{(@var{syntax-code}
+. @var{matching-char})} of the character in the buffer after position
+@var{pos}, taking account of syntax properties as well as the syntax
+table.  If @var{pos} is outside the buffer's accessible portion
+(@pxref{Narrowing, accessible portion}), this function returns
 @code{nil}.
 @end defun
 
 @defun syntax-class syntax
-This function returns the syntax class of the syntax code
+This function returns the syntax class of the syntax table entry
 @var{syntax}.  (It masks off the high 16 bits that hold the flags
-encoded in the syntax descriptor.)  If @var{syntax} is @code{nil}, it
-returns @code{nil}; this is so evaluating the expression
+encoded in the syntax descriptor given by the car of @var{syntax}.)
+If @var{syntax} is @code{nil}, it returns @code{nil}; this is so
+evaluating the expression
 
 @example
 (syntax-class (syntax-after pos))