; Improve documentation of overlay priorities

* doc/lispref/display.texi (Overlay Properties): Don't advise
against using overlay property values that are cons cells.
(Bug#64101)

1 files changed, 32 insertions, 23 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9b6e4f609bf..e229935170f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1792,34 +1792,43 @@ of them:
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
-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.
+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, or a cons of two values.  Any other value triggers
+undefined behavior.
 
 The priority matters when two or more overlays cover the same
 character and both specify the same property with different values;
-the one whose @code{priority} value is larger overrides the other.
+the one whose @code{priority} value is higher overrides the other.
 (For the @code{face} property, the higher priority overlay's value
-does not completely override the other value; instead, its face
-attributes override the face attributes of the @code{face} property
-whose priority is lower.)  If two overlays have the same priority
-value, and one is nested in the other, then the inner one will prevail
-over the outer one.  If neither is nested in the other then you should
-not make assumptions about which overlay will prevail.
+does not completely override the other value; instead, its individual
+face attributes override the corresponding face attributes of the
+@code{face} property whose priority is lower.)  If two overlays have
+the same priority value, and one is ``nested'' in the other (i.e.,
+covers fewer buffer or string positions), then the inner one will
+prevail over the outer one.  If neither is nested in the other then
+you should not make assumptions about which overlay will prevail.
+
+When a Lisp program puts overlays with defined priorities on text that
+might have overlays without priorities, this could cause undesirable
+results, because any overlay with a positive priority value will
+override all the overlays without a priority.  Since most Emacs
+features that use overlays don't specify priorities for their
+overlays, integer priorities should be used with care.  Instead of
+using integer priorities and risk overriding other overlays, you can
+use priority values of the form @w{@code{(@var{primary} . @var{secondary})}},
+where the @var{primary} value is used as described above, and
+@var{secondary} is the fallback value used when @var{primary} and the
+nesting considerations fail to resolve the precedence between
+overlays.  In particular, priority value @w{@code{(nil . @var{n})}},
+with @var{n} a positive integer, allows to have the overlays ordered
+by priority when necessary without completely overriding other
+overlays.
 
 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).  In particular, the
-overlay used for showing the region uses a priority value of the form
-@w{@code{(@var{primary} . @var{secondary})}}, where the @var{primary}
-value is used as described above, and @var{secondary} is the fallback
-value used when @var{primary} and the nesting considerations fail to
-resolve the precedence between overlays.  However, you are advised not
-to design Lisp programs based on this implementation detail; if you
-need to put overlays in priority order, use the @var{sorted} argument
-of @code{overlays-at}.  @xref{Finding Overlays}.
+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)}
@@ -3329,8 +3338,8 @@ enough to the overlay, Emacs applies the face or face attributes
 specified by the @code{mouse-face} property instead.  @xref{Overlay
 Properties}.
 
-When multiple overlays cover one character, an overlay with higher
-priority overrides those with lower priority.  @xref{Overlays}.
+When multiple overlays cover the same character, an overlay with
+higher priority overrides those with lower priority.  @xref{Overlays}.
 
 @item
 If the text contains a @code{face} or @code{mouse-face} property,