(Special Properties): More accurate description of what the `cursor'

property does.

2 files changed, 18 insertions, 6 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 9bbb7c72308..79a552e0626 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2009-11-28  Eli Zaretskii  <eliz@gnu.org>
+
+        * text.texi (Special Properties): More accurate description of
+        what the `cursor' property does.
+
 2009-11-26  Kevin Ryde  <user42@zip.com.au>
 
         * commands.texi (Misc Events): vindex mouse-wheel-up-event and
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index cb9636d199e..91b65017754 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3166,13 +3166,20 @@ Consecutive characters with the same @code{field} property constitute a
 @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 window position.  You can
+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 non-@code{nil} @code{cursor} text property.  If the
-value of the @code{cursor} property is an integer number, it specifies
-the number of buffer's character positions associated with the overlay
-or text property string; this helps Emacs display the cursor correctly
-when point moves across these character positions.
+that character a non-@code{nil} @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
+@code{[@var{ovpos}..@var{ovpos}+@var{n}]}, where @var{ovpos} is the
+starting buffer position covered by the overlay (@pxref{Managing
+Overlays}).
 
 @item pointer
 @kindex pointer @r{(text property)}