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

[Alex]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Alex <agrambot@gmail.com>
>> Cc: Drew Adams <drew.adams@oracle.com>,  20253@debbugs.gnu.org
>> Date: Wed, 21 Sep 2016 12:11:08 -0600
>> 
>> My curiosity about the meaning of a cons cell priority is what pushed me
>> to find and respond to this bug, so I guess that would count as one
>> question.
>> 
>> Since the region overlay is a very common overlay, I think it is
>> important enough to at least have a passing statement about its priority
>> value type in the documentation. Even something like "For example, some
>> overlays use a cons cell priority (PRIMARY . SECONDARY), where SECONDARY
>> is used as a tie-breaker if the PRIMARY priorities and boundaries of the
>> overlays are equal." would be nice.
>
> I hoped to hear some practical reasons for this, not just curiosity.
> Like practical use cases where knowing that internal detail (as
> opposed to using the documented methods of comparing priorities etc.)
> is imperative for that use case.

I should have mentioned that aside from curiosity I did need to know
about what the region overlay's priority represented so that I can know
what priority to give overlays that interacted with the region overlay.

> People often ask questions here out of curiosity about the display
> engine's inner workings, for example, and I try to answer them as best
> as I can.  But that doesn't mean all I write here in those discussions
> should be in the manual.

Right, but I think that the region overlay is prominent enough to have
all of its properties be in a documented form.

> IOW, the need to have some internal detail described in the manual
> (which implies we will have to update and maintain it for the years to
> come) should have more important reasons than just curiosity.

Hopefully the above is enough to warrant an extra sentence or two in the
manual.