From 2c72c46af18b586137c3cebde56f451c1b0b7a9b Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 23 Sep 2016 11:27:18 +0300 Subject: [PATCH] Improve documentation of overlay priorities * 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) --- doc/lispref/display.texi | 23 +++++++++++++++-------- lisp/dired.el | 8 ++++---- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 0d0ec671f7c..d3e424853ad 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1553,10 +1553,8 @@ 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. 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. +overlay. The priority value is used to decide which of the +overlapping overlays will ``win''. 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 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 completely override the other value; instead, its face attributes 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. 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 +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}. diff --git a/lisp/dired.el b/lisp/dired.el index 92aa65a9085..a4cb50533f2 100644 --- a/lisp/dired.el +++ b/lisp/dired.el @@ -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. -;;;### (autoloads nil "dired-aux" "dired-aux.el" "c1ea036dd5d740f00b18a76bfb32f887") +;;;### (autoloads nil "dired-aux" "dired-aux.el" "daa0a32a5bdfcf4de80c31cf7833b26d") ;;; Generated autoloads from dired-aux.el (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" "\ Compress selected files and directories to an archive. -You are prompted for the archive name. -The archiving command is chosen based on the archive name extension and -`dired-compress-files-alist'. +Prompt for the archive file name. +Choose the archiving command based on the archive file-name extension +and `dired-compress-files-alist'. \(fn)" t nil) -- 2.39.2