From eacd75df4e475c3d2483c64f32e3edb3be5c7785 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 18 Jun 2023 09:13:02 +0300 Subject: [PATCH] ; 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) --- doc/lispref/display.texi | 55 +++++++++++++++++++++++----------------- 1 file 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, -- 2.39.2