From: Richard M. Stallman Date: Mon, 1 Oct 2007 21:19:22 +0000 (+0000) Subject: (Overlay Properties): Explain nil as priority. Explain that conflicts X-Git-Tag: emacs-pretest-23.0.90~10555 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=f7a7f4eb9a64b2d427f64dd854a45c405ffde917;p=emacs.git (Overlay Properties): Explain nil as priority. Explain that conflicts are unpredictable if not resolved by priorities. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 9e16ae4500c..84546f303fe 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2007-10-01 Richard Stallman + + * display.texi (Overlay Properties): Explain nil as priority. + Explain that conflicts are unpredictable if not resolved by + priorities. + 2007-09-23 Richard Stallman * macros.texi (Backquote): Minor clarification. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 7ad3f2cc2be..d0875dd36d4 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1291,6 +1291,11 @@ while moving an overlay or changing its properties does not. Unlike text property changes, overlay property changes are not recorded in 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. You should not make assumptions about which overlay will +prevail when there is a conflict and they have the same priority. + These functions read and set the properties of an overlay: @defun overlay-get overlay prop @@ -1321,13 +1326,16 @@ of them: @item priority @kindex priority @r{(overlay property)} This property's value (which should be a nonnegative integer number) -determines the priority of the overlay. 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 takes priority -over the other. For the @code{face} property, the higher priority -value does not completely replace the other; instead, its face -attributes override the face attributes of the lower priority -@code{face} property. +determines the priority of the overlay. No priority, or @code{nil}, +means zero. + +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{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. Currently, all overlays take priority over text properties. Please avoid using negative priority values, as we have not yet decided just