Introduce "raw syntax descriptor" terminology, and use it.

* syntax.texi (Syntax Table Internals): Define "raw syntax
descriptor" terminology.
(Syntax Descriptors): Mention raw syntax descriptors.

* lisp/subr.el (syntax-after, syntax-class): Doc fix.

* syntax.c (Fstring_to_syntax): Doc fix.

Fixes: debbugs:12383

6 files changed, 62 insertions, 32 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 4bd7210d7d6..57ee374af49 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-09-08  Chong Yidong  <cyd@gnu.org>
+
+        * syntax.texi (Syntax Table Internals): Define "raw syntax
+        descriptor" terminology (Bug#12383).
+        (Syntax Descriptors): Mention raw syntax descriptors.
+
 2012-09-07  Chong Yidong  <cyd@gnu.org>
 
         * variables.texi (Creating Buffer-Local): Fix description of
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 91ae4359af7..624b5a92d6e 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -130,6 +130,10 @@ comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
 punctuation, matching character slot unused, first character of a
 comment-starter, second character of a comment-ender).
 
+  Emacs also defines @dfn{raw syntax descriptors}, which are used to
+describe syntax classes at a lower level.  @xref{Syntax Table
+Internals}.
+
 @menu
 * Syntax Class Table::      Table of syntax classes.
 * Syntax Flags::            Additional flags each character can have.
@@ -531,8 +535,9 @@ the current buffer's syntax table to determine the syntax for the
 underlying text character.
 
 @item @code{(@var{syntax-code} . @var{matching-char})}
-A cons cell of this format specifies the syntax for the underlying
-text character.  (@pxref{Syntax Table Internals})
+A cons cell of this format is a raw syntax descriptor (@pxref{Syntax
+Table Internals}), which directly specifies a syntax class for the
+underlying text character.
 
 @item @code{nil}
 If the property is @code{nil}, the character's syntax is determined from
@@ -940,16 +945,20 @@ documented in this section.  This internal format can also be assigned
 as syntax properties (@pxref{Syntax Properties}).
 
 @cindex syntax code
-  Each entry in a syntax table is a cons cell of the form
-@code{(@var{syntax-code} . @var{matching-char})}.  @var{syntax-code}
-is an integer that encodes the syntax class and syntax flags,
-according to the table below.  @var{matching-char}, if non-@code{nil},
-specifies a matching character (similar to the second character in a
-syntax descriptor).
+@cindex raw syntax descriptor
+  Each entry in a syntax table is a @dfn{raw syntax descriptor}: a
+cons cell of the form @code{(@var{syntax-code}
+. @var{matching-char})}.  @var{syntax-code} is an integer which
+encodes the syntax class and syntax flags, according to the table
+below.  @var{matching-char}, if non-@code{nil}, specifies a matching
+character (similar to the second character in a syntax descriptor).
+
+  Here are the syntax codes corresponding to the various syntax
+classes:
 
 @multitable @columnfractions .2 .3 .2 .3
 @item
-@i{Syntax code} @tab @i{Class} @tab @i{Syntax code} @tab @i{Class}
+@i{Code} @tab @i{Class} @tab @i{Code} @tab @i{Class}
 @item
 0 @tab whitespace @tab 8 @tab paired delimiter
 @item
@@ -970,7 +979,7 @@ syntax descriptor).
 
 @noindent
 For example, in the standard syntax table, the entry for @samp{(} is
-@code{(4 . 41)}.  (41 is the character code for @samp{)}.)
+@code{(4 . 41)}.  41 is the character code for @samp{)}.
 
   Syntax flags are encoded in higher order bits, starting 16 bits from
 the least significant bit.  This table gives the power of two which
@@ -990,33 +999,35 @@ corresponds to each syntax flag.
 @end multitable
 
 @defun string-to-syntax @var{desc}
-Given a syntax descriptor @var{desc}, this function returns the
-corresponding internal form, a cons cell @code{(@var{syntax-code}
-. @var{matching-char})}.
+Given a syntax descriptor @var{desc} (a string), this function returns
+the corresponding raw syntax descriptor.
 @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
-@code{nil}.
+This function returns the raw syntax descriptor for 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}),
+the return value is @code{nil}.
 @end defun
 
 @defun syntax-class syntax
-This function returns the syntax class of the syntax code
-@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
+This function returns the syntax code for the raw syntax descriptor
+@var{syntax}.  More precisely, it takes the raw syntax descriptor's
+@var{syntax-code} component, masks off the high 16 bits which record
+the syntax flags, and returns the resulting integer.
+
+If @var{syntax} is @code{nil}, the return value is returns @code{nil}.
+This is so that the expression
 
 @example
 (syntax-class (syntax-after pos))
 @end example
 
 @noindent
-where @code{pos} is outside the buffer's accessible portion, will
-yield @code{nil} without throwing errors or producing wrong syntax
-class codes.
+evaluates to @code{nil} if @code{pos} is outside the buffer's
+accessible portion, without throwing errors or returning an incorrect
+code.
 @end defun
 
 @node Categories
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index e10fe9166e7..4d6210a16b9 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-09-08  Chong Yidong  <cyd@gnu.org>
+
+        * subr.el (syntax-after, syntax-class): Doc fix.
+
 2012-09-08  Martin Rudalics  <rudalics@gmx.at>
 
         * window.el (display-buffer-in-previous-window): New buffer
diff --git a/lisp/subr.el b/lisp/subr.el
index a3e0897e9fe..4f273a92a62 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3737,7 +3737,7 @@ from `standard-syntax-table' otherwise."
     table))
 
 (defun syntax-after (pos)
-  "Return the raw syntax of the char after POS.
+  "Return the raw syntax descriptor for the char after POS.
 If POS is outside the buffer's accessible portion, return nil."
   (unless (or (< pos (point-min)) (>= pos (point-max)))
     (let ((st (if parse-sexp-lookup-properties
@@ -3746,7 +3746,12 @@ If POS is outside the buffer's accessible portion, return nil."
         (aref (or st (syntax-table)) (char-after pos))))))
 
 (defun syntax-class (syntax)
-  "Return the syntax class part of the syntax descriptor SYNTAX.
+  "Return the code for the syntax class described by SYNTAX.
+
+SYNTAX should be a raw syntax descriptor; the return value is a
+integer which encodes the corresponding syntax class.  See Info
+node `(elisp)Syntax Table Internals' for a list of codes.
+
 If SYNTAX is nil, return nil."
   (and syntax (logand (car syntax) 65535)))
 
diff --git a/src/ChangeLog b/src/ChangeLog
index 40647d79589..ec6e39ad0b5 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2012-09-08  Chong Yidong  <cyd@gnu.org>
+
+        * syntax.c (Fstring_to_syntax): Doc fix.
+
 2012-09-08  Jan Djärv  <jan.h.d@swipnet.se>
 
         * nsterm.m (ns_clip_to_row): Remove code that deals with drawing fringe
diff --git a/src/syntax.c b/src/syntax.c
index f995b8f2cac..fdd9353bb87 100644
--- a/src/syntax.c
+++ b/src/syntax.c
@@ -921,11 +921,11 @@ DEFUN ("matching-paren", Fmatching_paren, Smatching_paren, 1, 1, 0,
 }
 
 DEFUN ("string-to-syntax", Fstring_to_syntax, Sstring_to_syntax, 1, 1, 0,
-       doc: /* Convert a syntax specification STRING into syntax cell form.
-STRING should be a string as it is allowed as argument of
-`modify-syntax-entry'.  Value is the equivalent cons cell
-\(CODE . MATCHING-CHAR) that can be used as value of a `syntax-table'
-text property.  */)
+       doc: /* Convert a syntax descriptor STRING into a raw syntax descriptor.
+STRING should be a string of the form allowed as argument of
+`modify-syntax-entry'.  The return value is a raw syntax descriptor: a
+cons cell \(CODE . MATCHING-CHAR) which can be used, for example, as
+the value of a `syntax-table' text property.  */)
   (Lisp_Object string)
 {
   register const unsigned char *p;