Overlay priority description in the Lisp manual.

Overlay priority description in the Lisp manual.

[Luc Teirlinck]

>From emacs/lispref/display.texi:

    @table @code
    @item priority
    @kindex priority @r{(overlay property)}
    This property's value (which should be a nonnegative number) determines
    the priority of the overlay.  The priority matters when two or more
    overlays cover the same character and both specify a face for display;
    the one whose @code{priority} value is larger takes priority over the
    other, and its face attributes override the face attributes of the lower
    priority overlay.

    Currently, all overlays take priority over text properties.  Please
    avoid using negative priority values, as we have not yet decided just
    what they should mean.

I only have problems with the first paragraph, the second is included
for context.

First problem: `number' is consistently used elsewhere in the Elisp
manual to mean `integer or floating point'.  Thus the above suggests
that floating point values will work, whereas they are ignored.

Second problem: The above text clearly suggest that the priority
_only_ matters for the `face' property, whereas it matters for _all_
properties.

Third problem: It is not clear what the default is if no priority is
specified.

I suggest the following replacement and could commit it, if desired:

    @table @code
    @item priority
    @kindex priority @r{(overlay property)}
    This property's value (which should be a nonnegative integer)
    determines the priority of the overlay.  The priority matters when two
    or more overlays cover the same character and specify a different
    value for a property.  The default priority is 0.

    Currently, all overlays take priority over text properties.  Please
    avoid using negative priority values, as we have not yet decided just
    what they should mean.

Sincerely,

Luc.