[Emacs-diffs] /srv/bzr/emacs/trunk r109938: Introduce "raw syntax descriptor" terminology, and use it.

[Chong Yidong]

------------------------------------------------------------
revno: 109938
fixes bug: http://debbugs.gnu.org/12383
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-09-08 22:23:01 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/syntax.texi
  lisp/ChangeLog
  lisp/subr.el
  src/ChangeLog
  src/syntax.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-09-07 14:15:59 +0000
+++ b/doc/lispref/ChangeLog     2012-09-08 14:23:01 +0000
@@ -1,3 +1,9 @@
+2012-09-08  Chong Yidong  <address@hidden>
+
+       * syntax.texi (Syntax Table Internals): Define "raw syntax
+       descriptor" terminology (Bug#12383).
+       (Syntax Descriptors): Mention raw syntax descriptors.
+
 2012-09-07  Chong Yidong  <address@hidden>
 
        * variables.texi (Creating Buffer-Local): Fix description of

=== modified file 'doc/lispref/syntax.texi'
--- a/doc/lispref/syntax.texi   2012-09-07 04:51:26 +0000
+++ b/doc/lispref/syntax.texi   2012-09-08 14:23:01 +0000
@@ -130,6 +130,10 @@
 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 @@
 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 @@
 as syntax properties (@pxref{Syntax Properties}).
 
 @cindex syntax code
-  Each entry in a syntax table is a cons cell of the form
address@hidden(@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 address@hidden,
-specifies a matching character (similar to the second character in a
-syntax descriptor).
address@hidden 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 address@hidden, 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
address@hidden code} @tab @i{Class} @tab @i{Syntax code} @tab @i{Class}
address@hidden @tab @i{Class} @tab @i{Code} @tab @i{Class}
 @item
 0 @tab whitespace @tab 8 @tab paired delimiter
 @item
@@ -970,7 +979,7 @@
 
 @noindent
 For example, in the standard syntax table, the entry for @samp{(} is
address@hidden(4 . 41)}.  (41 is the character code for @samp{)}.)
address@hidden(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 @@
 @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
address@hidden
+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
address@hidden  (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
address@hidden  More precisely, it takes the raw syntax descriptor's
address@hidden 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-09-08 13:28:11 +0000
+++ b/lisp/ChangeLog    2012-09-08 14:23:01 +0000
@@ -1,3 +1,7 @@
+2012-09-08  Chong Yidong  <address@hidden>
+
+       * subr.el (syntax-after, syntax-class): Doc fix.
+
 2012-09-08  Martin Rudalics  <address@hidden>
 
        * window.el (display-buffer-in-previous-window): New buffer

=== modified file 'lisp/subr.el'
--- a/lisp/subr.el      2012-09-07 10:19:58 +0000
+++ b/lisp/subr.el      2012-09-08 14:23:01 +0000
@@ -3737,7 +3737,7 @@
     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 @@
        (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)))
 

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-09-08 12:48:33 +0000
+++ b/src/ChangeLog     2012-09-08 14:23:01 +0000
@@ -1,3 +1,7 @@
+2012-09-08  Chong Yidong  <address@hidden>
+
+       * syntax.c (Fstring_to_syntax): Doc fix.
+
 2012-09-08  Jan Djärv  <address@hidden>
 
        * nsterm.m (ns_clip_to_row): Remove code that deals with drawing fringe

=== modified file 'src/syntax.c'
--- a/src/syntax.c      2012-08-18 06:06:39 +0000
+++ b/src/syntax.c      2012-09-08 14:23:01 +0000
@@ -921,11 +921,11 @@
 }
 
 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;