[Emacs-diffs] /srv/bzr/emacs/trunk r107316: Clarify doc of scan-lists.

[Chong Yidong]

------------------------------------------------------------
revno: 107316
fixes bug(s): http://debbugs.gnu.org/10833
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2012-02-17 22:01:05 +0800
message:
  Clarify doc of scan-lists.
  
  * doc/lispref/syntax.texi (Motion via Parsing): Doc fix for scan-lists.
  
  * src/syntax.c (Fscan_lists): Doc fix.
modified:
  doc/lispref/ChangeLog
  doc/lispref/syntax.texi
  src/ChangeLog
  src/syntax.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-17 07:44:31 +0000
+++ b/doc/lispref/ChangeLog     2012-02-17 14:01:05 +0000
@@ -1,3 +1,7 @@
+2012-02-17  Chong Yidong  <address@hidden>
+
+       * syntax.texi (Motion via Parsing): Doc fix for scan-lists.
+
 2012-02-17  Glenn Morris  <address@hidden>
 
        * hooks.texi (Standard Hooks): Fix cross-ref to Emacs manual.

=== modified file 'doc/lispref/syntax.texi'
--- a/doc/lispref/syntax.texi   2012-02-16 14:43:41 +0000
+++ b/doc/lispref/syntax.texi   2012-02-17 14:01:05 +0000
@@ -646,25 +646,25 @@
 based on parsing expressions.
 
 @defun scan-lists from count depth
-This function scans forward @var{count} balanced parenthetical groupings
-from position @var{from}.  It returns the position where the scan stops.
-If @var{count} is negative, the scan moves backwards.
+This function scans forward @var{count} balanced parenthetical
+groupings from position @var{from}.  It returns the position where the
+scan stops.  If @var{count} is negative, the scan moves backwards.
 
-If @var{depth} is nonzero, assume that the starting point is already
address@hidden parentheses deep.  This function counts out @var{count}
-number of points where the parenthesis depth goes back to zero, then
-stops.  Thus, a positive value for @var{depth} has the effect of
-moving out @var{depth} levels of parenthesis, whereas a negative
address@hidden has the effect of moving deeper by @var{-depth} levels of
-parenthesis.
+If @var{depth} is nonzero, treat the starting position as being
address@hidden parentheses deep.  The scanner moves forward or backward
+through the buffer until the depth changes to zero @var{count} times.
+Hence, a positive value for @var{depth} has the effect of moving out
address@hidden levels of parenthesis from the starting position, while a
+negative @var{depth} has the effect of moving deeper by @var{-depth}
+levels of parenthesis.
 
 Scanning ignores comments if @code{parse-sexp-ignore-comments} is
 address@hidden
 
-If the scan reaches the beginning or end of the buffer (or its
-accessible portion), and the depth is not zero, an error is signaled.
-If the depth is zero but the count is not used up, @code{nil} is
-returned.
+If the scan reaches the beginning or end of the accessible part of the
+buffer before it has scanned over @var{count} parenthetical groupings,
+the return value is @code{nil} if the depth at that point is zero; if
+the depth is non-zero, a @code{scan-error} error is signaled.
 @end defun
 
 @defun scan-sexps from count

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-02-15 06:40:08 +0000
+++ b/src/ChangeLog     2012-02-17 14:01:05 +0000
@@ -1,3 +1,7 @@
+2012-02-17  Chong Yidong  <address@hidden>
+
+       * syntax.c (Fscan_lists): Doc fix (Bug#10833).
+
 2012-02-15  Paul Eggert  <address@hidden>
 
        * image.c (MAX_IMAGE_SIZE): Increase from 6.0 to 10.0; see

=== modified file 'src/syntax.c'
--- a/src/syntax.c      2012-01-19 07:21:25 +0000
+++ b/src/syntax.c      2012-02-17 14:01:05 +0000
@@ -2844,18 +2844,23 @@
 
 DEFUN ("scan-lists", Fscan_lists, Sscan_lists, 3, 3, 0,
        doc: /* Scan from character number FROM by COUNT lists.
-Returns the character number of the position thus found.
-
-If DEPTH is nonzero, paren depth begins counting from that value,
-only places where the depth in parentheses becomes zero
-are candidates for stopping; COUNT such places are counted.
-Thus, a positive value for DEPTH means go out levels.
+Scan forward if COUNT is positive, backward if COUNT is negative.
+Return the character number of the position thus found.
+
+A \"list", in this context, refers to a balanced parenthetical
+grouping, as determined by the syntax table.
+
+If DEPTH is nonzero, treat that as the nesting depth of the starting
+point (i.e. the starting point is DEPTH parentheses deep).  This
+function scans over parentheses until the depth goes to zero COUNT
+times.  Hence, positive DEPTH moves out that number of levels of
+paretheses, while negative DEPTH moves to a deeper level.
 
 Comments are ignored if `parse-sexp-ignore-comments' is non-nil.
 
-If the beginning or end of (the accessible part of) the buffer is reached
-and the depth is wrong, an error is signaled.
-If the depth is right but the count is not used up, nil is returned.  */)
+If we reach the beginning or end of the accessible part of the buffer
+before we have scanned over COUNT lists, return nil if the depth at
+that point is zero, and signal a error if the depth is nonzero.  */)
   (Lisp_Object from, Lisp_Object count, Lisp_Object depth)
 {
   CHECK_NUMBER (from);