mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-16 19:00:55 -08:00
Code Issues Projects Releases Wiki Activity

Improve documentation of overlay priorities

Browse source 
* doc/lispref/display.texi (Overlay Properties): Minor copyedits.
By popular demand, mention the '(PRIMNARY . SECONDARY)' form of
overlay properties used for the region.  (Bug#20253)
This commit is contained in:
Eli Zaretskii 2016-09-23 11:27:18 +03:00
parent f6fa160e91
commit 2c72c46af1
2 changed files with 19 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

23
doc/lispref/display.texi
View file

@ -1553,10 +1553,8 @@ the buffer's undo list.
Since more than one overlay can specify a property value for the Since more than one overlay can specify a property value for the
same character, Emacs lets you specify a priority value of each same character, Emacs lets you specify a priority value of each
overlay. In case two overlays have the same priority value, and one overlay. The priority value is used to decide which of the
is nested in the other, then the inner one will have priority over the overlapping overlays will ``win''.
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: These functions read and set the properties of an overlay:
@ -1593,17 +1591,26 @@ If you want to specify a priority value, use either @code{nil}
The priority matters when two or more overlays cover the same The priority matters when two or more overlays cover the same
character and both specify the same property; the one whose character and both specify the same property; the one whose
@code{priority} value is larger overrides the other. For the @code{priority} value is larger overrides the other. (For the
@code{face} property, the higher priority overlay's value does not @code{face} property, the higher priority overlay's value does not
completely override the other value; instead, its face attributes completely override the other value; instead, its face attributes
override the face attributes of the lower priority @code{face} override the face attributes of the lower priority @code{face}
property. property.) 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.
Currently, all overlays take priority over text properties. Currently, all overlays take priority over text properties.
Note that Emacs sometimes uses non-numeric priority values for some of Note that Emacs sometimes uses non-numeric priority values for some of
its internal overlays, so do not try to do arithmetic on the its internal overlays, so do not try to do arithmetic on the priority
priority of an overlay (unless it is one that you created). If you 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 need to put overlays in priority order, use the @var{sorted} argument
of @code{overlays-at}. @xref{Finding Overlays}. of @code{overlays-at}. @xref{Finding Overlays}.

8
lisp/dired.el
View file

@ -3919,7 +3919,7 @@ Ask means pop up a menu for the user to select one of copy, move or link."
;;; Start of automatically extracted autoloads. ;;; Start of automatically extracted autoloads.
;;;### (autoloads nil "dired-aux" "dired-aux.el" "c1ea036dd5d740f00b18a76bfb32f887") ;;;### (autoloads nil "dired-aux" "dired-aux.el" "daa0a32a5bdfcf4de80c31cf7833b26d")
;;; Generated autoloads from dired-aux.el ;;; Generated autoloads from dired-aux.el
(autoload 'dired-diff "dired-aux" "\ (autoload 'dired-diff "dired-aux" "\
@ -4113,9 +4113,9 @@ command with a prefix argument (the value does not matter).
(autoload 'dired-do-compress-to "dired-aux" "\ (autoload 'dired-do-compress-to "dired-aux" "\
Compress selected files and directories to an archive. Compress selected files and directories to an archive.
You are prompted for the archive name. Prompt for the archive file name.
The archiving command is chosen based on the archive name extension and Choose the archiving command based on the archive file-name extension
`dired-compress-files-alist'. and `dired-compress-files-alist'.
\(fn)" t nil) \(fn)" t nil)