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

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

[Nathan Trapuzzano]

[-- Attachment #1: Type: text/plain, Size: 392 bytes --]

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:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Clarify the distinction between "syntax codes" and the cons cells that contain them --]
[-- Type: text/x-patch, Size: 1488 bytes --]

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))

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

[Chong Yidong]

Nathan Trapuzzano <nbtrap@nbtrap.com> writes:

> 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:

Thank you for the suggestion.  It is on the right track, but I think the
fix needs to go further.  We need a new terminology for the cons cells
stored in the syntax table.  I think a good name is "raw syntax
descriptors", and I've amended the manual and docstrings accordingly.