Merge from emacs-24; up to 2014-04-16T15:28:26Z!monnier@iro.umontreal.ca

3 files changed, 39 insertions, 22 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 89a26a6b38a..d4514904c77 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2014-04-16  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Cursor Display): Explain better how to customize
+        'blink-cursor-blinks'.
+
 2014-04-07  Glenn Morris  <rgm@gnu.org>
 
         * trouble.texi (Checklist): Dribble files may contain passwords.
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d53c80acafd..03de755aff3 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1482,18 +1482,27 @@ pixels tall), or @code{nil} (no cursor at all).
 @vindex blink-cursor-mode
 @vindex blink-cursor-blinks
 @vindex blink-cursor-alist
-  By default, the cursor stops blinking after 10 blinks.  This can be
-changed by customizing the variable @code{blink-cursor-blinks}.  To
-disable cursor blinking altogether, change the variable
-@code{blink-cursor-mode} to @code{nil} (@pxref{Easy Customization}),
-or add the line @code{(blink-cursor-mode 0)} to your init file.
-Alternatively, you can change how the cursor looks when it ``blinks
-off'' by customizing the list variable @code{blink-cursor-alist}.
-Each element in the list should have the form @code{(@var{on-type}
-. @var{off-type})}; this means that if the cursor is displayed as
-@var{on-type} when it blinks on (where @var{on-type} is one of the
-cursor types described above), then it is displayed as @var{off-type}
-when it blinks off.
+  By default, the cursor stops blinking after 10 blinks, if Emacs does
+not get any input during that time; any input event restarts the
+count.  You can customize the variable @code{blink-cursor-blinks} to
+control that: its value says how many times to blink without input
+before stopping.  Setting that variable to a zero or negative value
+will make the cursor blink forever.  To disable cursor blinking
+altogether, change the variable @code{blink-cursor-mode} to @code{nil}
+(@pxref{Easy Customization}), or add the line
+
+@lisp
+  (blink-cursor-mode 0)
+@end lisp
+
+@noindent
+to your init file.  Alternatively, you can change how the cursor
+looks when it ``blinks off'' by customizing the list variable
+@code{blink-cursor-alist}.  Each element in the list should have the
+form @code{(@var{on-type} . @var{off-type})}; this means that if the
+cursor is displayed as @var{on-type} when it blinks on (where
+@var{on-type} is one of the cursor types described above), then it is
+displayed as @var{off-type} when it blinks off.
 
 @vindex x-stretch-cursor
 @cindex wide block cursor
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 0246d1a44de..acbef6b9495 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1475,8 +1475,10 @@ the buffer's undo list.
 
   Since more than one overlay can specify a property value for the
 same character, Emacs lets you specify a priority value of each
-overlay.  You should not make assumptions about which overlay will
-prevail when there is a conflict and they have the same priority.
+overlay.  In case two overlays have the same priority value, and one
+is nested in the other, then the inner one will have priority over the
+outer one.  If neither is nested in the other then you should not make
+assumptions about which overlay will prevail.
 
   These functions read and set the properties of an overlay:
 
@@ -1507,9 +1509,9 @@ of them:
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
-This property's value (which should be a non-negative integer)
-determines the priority of the overlay.  No priority, or @code{nil},
-means zero.
+This property's value determines the priority of the overlay.  No priority, or
+@code{nil}, means zero.  A non-nil and non-integer value has
+undefined behavior.
 
 The priority matters when two or more overlays cover the same
 character and both specify the same property; the one whose
@@ -1706,11 +1708,12 @@ Properties}.
 @node Finding Overlays
 @subsection Searching for Overlays
 
-@defun overlays-at pos
-This function returns a list of all the overlays that cover the
-character at position @var{pos} in the current buffer.  The list is in
-no particular order.  An overlay contains position @var{pos} if it
-begins at or before @var{pos}, and ends after @var{pos}.
+@defun overlays-at pos &optional sorted
+This function returns a list of all the overlays that cover the character at
+position @var{pos} in the current buffer.  If @var{sorted} is non-nil, the list
+is in decreasing order of priority, otherwise it is in no particular order.
+An overlay contains position @var{pos} if it begins at or before @var{pos}, and
+ends after @var{pos}.
 
 To illustrate usage, here is a Lisp function that returns a list of the
 overlays that specify property @var{prop} for the character at point: