bug#20253: 24.4; Document `region' face behavior changes, overlay, priority

[Alex <agrambot@gmail.com>]

Drew Adams <drew.adams@oracle.com> writes:

> Since Emacs 24.3, if I recall correctly, face `region' uses an overlay.
> This produces changes in the user-observable behavior - that's why the
> change was made.
>
> But the NEWS for 24.3 and for 24.4 do not mention anything about this,
> AFAICT.  Not only does NEWS not seem to say anything about `region'
> using an overlay, but it does not even mention the observable behavior
> differences that this produces.
>
> And the Elisp manual is likewise silent on this change.
>
> Please tell users that such a change was made.  That's what NEWS is for.
>
> And please tell users, in the Elisp manual, what the default priority of
> the overlay is.  Testing shows a priority value of (nil . 100), which is
> not even a documented form that an overlay priority can take.  But even
> if that is what the value needs to be, for internal reasons, at least
> tell users what it is.
>
> And if, for some reason, users are supposed not to change the priority,
> then say so, in the doc.  And if there is no such restriction or
> recommendation, then let them know, if they should be assigning a
> priority value that is a cons, such as (nil . NUMBER).
>
> IOW, please communicate with your users about such changes: what they
> mean for users (what behavior differences they can expect), and how they
> can manipulate/customize the behavior.

The Elisp manual does mention that "Emacs sometimes uses non-numeric
priority values for some of its internal overlays", but it would be nice
if it documented what those were and what they mean.

The comments in simple.el mention that a cons cell value represents
primary/secondary priorities, but it's not clear what the difference is.