Commit 2c72c46a authored by Eli Zaretskii's avatar Eli Zaretskii

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)
parent f6fa160e
......@@ -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}.
......
......@@ -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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment