Document incompatible overlay priority change

* doc/lispref/display.texi (Overlay Properties): Update re priority.

* etc/NEWS: Related edit.

Fixes: debbugs:17234

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 51f74f2..060dca1 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2014-06-06  Glenn Morris  <rgm@gnu.org>
+
+       * display.texi (Overlay Properties): Update re priority.  (Bug#17234)
+

 2014-06-05  Glenn Morris  <rgm@gnu.org>
 
        * package.texi (Package Archives): Mention signing packages.
 2014-06-05  Glenn Morris  <rgm@gnu.org>
 
        * package.texi (Package Archives): Mention signing packages.

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e93f9ab..3528213 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1515,9 +1515,9 @@ of them:
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}

-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.
+This property's value determines the priority of the overlay.
+If you want to specify a priority value, use either @code{nil}
+(or zero), or a positive integer.  Any other 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
 
 The priority matters when two or more overlays cover the same
 character and both specify the same property; the one whose


@@ -1527,9 +1527,13 @@ completely override the other value; instead, its face attributes
 override the face attributes of the lower priority @code{face}
 property.
 
 override the face attributes of the lower priority @code{face}
 property.
 

-Currently, all overlays take priority over text properties.  Please
-avoid using negative priority values, as we have not yet decided just
-what they should mean.
+Currently, all overlays take priority over text properties.
+
+Note that Emacs sometimes uses non-numeric priority values for some of
+its internal overlays, so do not try to do arithmetic on the
+priority of an overlay (unless it is one that you created).  If you
+need to put overlays in priority order, use the @var{sorted} argument
+of @code{overlays-at}.  @xref{Finding Overlays}.

 
 @item window
 @kindex window @r{(overlay property)}
 
 @item window
 @kindex window @r{(overlay property)}

diff --git a/etc/NEWS b/etc/NEWS
index fce3690..ebd816f 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1149,6 +1149,12 @@ low-level libraries gfilenotify.c, inotify.c or w32notify.c.
 \f
 * Incompatible Lisp Changes in Emacs 24.4
 
 \f
 * Incompatible Lisp Changes in Emacs 24.4
 

++++
+** Do not assume that the priority of all overlays will be numeric.
+(You should still only specify integer priorities on overlays you create.)
+If you need to sort arbitrary overlays into priority order, `overlays-at'
+can now optionally do this.
+

 ---
 ** `kill-region' has lost its `yank-handler' optional argument.
 
 ---
 ** `kill-region' has lost its `yank-handler' optional argument.
 


@@ -1248,8 +1254,6 @@ the other.
 \f
 * Lisp Changes in Emacs 24.4
 
 \f
 * Lisp Changes in Emacs 24.4
 

-** overlays-at can optionally sort its result by priority.
-

 +++
 ** The second argument of `eval' can now specify a lexical environment.
 
 +++
 ** The second argument of `eval' can now specify a lexical environment.