[Emacs-diffs] /srv/bzr/emacs/trunk r107711: Improve documentation of 'cursor' text property.

[Eli Zaretskii]

------------------------------------------------------------
revno: 107711
committer: Eli Zaretskii <address@hidden>
branch nick: trunk
timestamp: Sat 2012-03-31 13:27:04 +0300
message:
  Improve documentation of 'cursor' text property.
  
   doc/lispref/text.texi (Special Properties): Clarify the description of the
   effect of integer values of the 'cursor' property on cursor
   position.  See the discussions in bug#11068 for more details and
   context.
modified:
  doc/lispref/ChangeLog
  doc/lispref/text.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-31 01:09:30 +0000
+++ b/doc/lispref/ChangeLog     2012-03-31 10:27:04 +0000
@@ -1,3 +1,10 @@
+2012-03-31  Eli Zaretskii  <address@hidden>
+
+       * text.texi (Special Properties): Clarify the description of the
+       effect of integer values of the 'cursor' property on cursor
+       position.  See the discussions in bug#11068 for more details and
+       context.
+
 2012-03-31  Glenn Morris  <address@hidden>
 
        * edebug.texi (Edebug Eval, Specification List, Edebug Options):

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2012-03-11 16:27:36 +0000
+++ b/doc/lispref/text.texi     2012-03-31 10:27:04 +0000
@@ -3179,21 +3179,41 @@
 
 @item cursor
 @kindex cursor @r{(text property)}
-Normally, the cursor is displayed at the end of any overlay and text
-property strings present at the current buffer position.  You can
-place the cursor on any desired character of these strings by giving
-that character a address@hidden @code{cursor} text property.  In
-addition, if the value of the @code{cursor} property of an overlay
-string is an integer number, it specifies the number of buffer's
-character positions associated with the overlay string; this way,
-Emacs will display the cursor on the character with that property
-regardless of whether the current buffer position is actually covered
-by the overlay.  Specifically, if the value of the @code{cursor}
-property of a character is the number @var{n}, the cursor will be
-displayed on this character for any buffer position in the range
address@hidden@address@hidden@var{n}]}, where @var{ovpos} is the
-starting buffer position covered by the overlay (@pxref{Managing
-Overlays}).
+Normally, the cursor is displayed at the beginning or the end of any
+overlay and text property strings present at the current buffer
+position.  You can place the cursor on any desired character of these
+strings by giving that character a address@hidden @code{cursor} text
+property.  In addition, if the value of the @code{cursor} property is
+an integer number, it specifies the number of buffer's character
+positions, starting with the position where the overlay or the
address@hidden property begins, for which the cursor should be
+displayed on that character.  Specifically, if the value of the
address@hidden property of a character is the number @var{n}, the
+cursor will be displayed on this character for any buffer position in
+the range @address@hidden@address@hidden)}, where @var{ovpos}
+is the overlay's starting position given by @code{overlay-start}
+(@pxref{Managing Overlays}), or the position where the @code{display}
+text property begins in the buffer.
+
+In other words, the string character with the @code{cursor} property
+of any address@hidden value is the character where to display the
+cursor.  The value of the property says for which buffer positions to
+display the cursor there.  If the value is an integer number @var{n},
+the cursor is displayed there when point is anywhere between the
+beginning of the overlay or @code{display} property and @var{n}
+positions after that.  If the value is anything else and
address@hidden, the cursor is displayed there only when point is at
+the beginning of the @code{display} property or at
address@hidden
+
address@hidden cursor position for @code{display} properties and overlays
+When the buffer has many overlay strings (e.g., @pxref{Overlay
+Properties, before-string}) or @code{display} properties that are
+strings, it is a good idea to use the @code{cursor} property on these
+strings to cue the Emacs display about the places where to put the
+cursor while traversing these strings.  This directly communicates to
+the display engine where the Lisp program wants to put the cursor, or
+where the user would expect the cursor.
 
 @item pointer
 @kindex pointer @r{(text property)}