RE: Documentation of transient-mark-mode is sloppy, wrong, and confused.

[Drew Adams]

I really didn't want to add to this thread, but it sounds like you might
actually end up changing the doc for this, so I will.

I don't know what the doc (including both manuals and all doc strings) says now,
in detail, and I don't have time to check. I think my recollection is probably
pretty correct about this, but if the doc somewhere doesn't fit my impression,
it can be fixed.

Summary: "active" applies only to transient-mark-mode. It is misguided to
interpret it otherwise or explain it otherwise, in the doc or here.


1. The mark's existence in a given buffer, and hence the region's existence
there, is an accessory question. It affects Lisp code and it affects whether you
can do region things (obviously), but it is not related to the notion of
"active" region or mark.

2. Similarly, whether the region is empty (point=mark) is accessory to the
question of region activeness - and to the question of region existence. These
things each need to be dealt with separately, before discussing them together
(e.g. in the description of the behavior of some command that tests one or more
of them).

3. It is OK to call the region, and even the mark, "active" and "inactive", if
we want to. (Sorry, Alan.) Stephen is right here. We could perhaps come up with
better terms, but we should not, at this point.

4. Davis is right about there being two notions of activeness (in this thread).
But only if we confuse things by applying the term "active" to things it has
never been applied to (in the doc).

AFAIK, we have never, in the doc, referred to activeness other than in the
context of transient-mark-mode, that is, when t-m-m is on. Activeness of the
region or mark is a notion that is applicable only to t-m-m. If t-m-m mode is
off, then the region is neither active nor inactive. It just is (or isn't, if
there is no mark). Once we make this clear (to each other and to doc readers),
the "problem" disappears.

5. Both Davis's active1 and active2 reflect this (#4).

With t-m-m on, the region is active1 iff the "region is active" in traditional
parlance. With t-m-m off, the region is active1 always (provided the mark
exists). That last statement says that active1 is only a t-m-m notion.

Likewise, for Davis's active2. With t-m-m on, the region is active2 iff the
"region is active" in traditional parlance. With t-m-m off, the region is never
active2. Again, that last statement says that active2 is only a t-m-m notion.

If you are always happy, regardless of the phase of the moon, then the moon
phase no bearing on your happiness. Likewise, if you are never happy.

6. Temporary t-m-m does not complicate things, in terms of the notion of
"active" region. It is just a temporary use of t-m-m. Everything is consistent
in this regard, AFAIK. (I'm no expert on temporary t-m-m, however, and I'm not
vouching for its doc.)

7. The proper predicate for testing whether the region is (in)active is (null
mark-active). That's all. But again, such a test makes sense only when t-m-m
mode is on. If you are testing only `mark-active' outside of t-m-m, then you are
wasting your time.

8. Whether or not you can do certain things with the region, and knowing whether
a given command will operate on the region (or the whole buffer or whatever), is
orthogonal to whether you are in t-m-m and, if so, whether the region is active.
That is, whether the command even looks at the region and the t-m-m state
(`mark-active') is up to the command.

It is the particular command that decides what happens in any given context:
whether it acts on the region; whether it does so regardless of t-m-m; whether,
if in t-m-m, the action is different whether the region is active or not; and so
on.

9. The confusion for Alan and perhaps some other users and doc readers is that
they have gotten the impression that the region being "active" has some meaning
outside t-m-m. They (mis)read doc that talks about some command's acting or not
acting on the region depending on whether the region is active. They interpret
the use of "active" here to apply also when t-m-m is off, as if it speaks to
whether or not the region is _usable_ by the command or whether the command is
region-aware.

This confusion comes perhaps from imperfect wording - dunno. The doc should
state clearly (remind readers) that any behavior that is conditional on whether
the region is active is conditional only when t-m-m is on, because the region
can be active only when t-m-m is on.

10. A further consideration is whether the region is empty, that is, point=mark.
This distinction makes sense independently of t-m-m. "Active region" applies
only to t-m-m, but "empty region" applies whether t-m-m is on or off. (It does
not apply always, however. A region cannot be empty or non-empty if it does not
yet exist.)

11. Similarly, for the existence of the mark (hence the region) in a given
buffer. This distinction makes sense independently of t-m-m. This distinction is
always available - it is the only condition of the three that can always be
tested. You cannot test (numerically) whether point=mark unless the mark exists.
You cannot test whether the mark is active unless t-m-m is on. 

12. "Well, hold it", you say. You can test `mark-active' anytime. Yes, but
without also testing t-m-m the value of variable `mark-active' won't tell you
whether the mark/region is active. This is a possible source of confusion for
those readers who use Emacs Lisp. The doc of `mark-active' just needs to make it
clear that it is a variable that applies only to t-m-m.

13. The behavior of some commands can be conditional on: (1) t-m-m region
activeness (so with t-m-m mode off there is no distinction/condition); (2)
region emptiness; (3) region existence; or some combination of 1-3.

The existence test can always be used to change command behavior. The emptiness
test can be used anytime the mark exists. Testing for an active region can be
done only when t-m-m mode is on.

14. The doc for a given command needs to make clear the various behavior changes
and the conditions that determine them. The introduction of such conditional
commands, especially those that check for an active region, has, I think, led to
confusion for some people. We need to be very clear in their doc about these
notions and tests.

In particular, to help readers understand such doc strings (after we've made the
strings clear), we need to _remind_ readers here and there of these things: (1)
The mark might not exist in some buffer; it does not exist until you set mark.
(2) The region might be empty, which means point=mark. (3) If t-m-m mode is off,
then whether the region is active cannot be tested: active region is a t-m-m
concept.

15. If it helps, we can state somewhere that the full name of the notion "active
region" is "transient-mark-mode active region". The former is really an
abbreviation for the latter. Speaking only of "active region" is like speaking
only of "the length" instead of "the line length".

As long as we were speaking only in the context of t-m-m, there was no problem.
But as soon as we speak of "active region" in a context (e.g. some command
behavior) where t-m-m does not necessarily apply, we need to make it very clear
that this is a t-m-m notion only.

16. I don't have a concrete suggestion for changing any terminology. A priori, I
think we should keep the current terminology, which fits with `mark-active' etc.

17. But we should clarify the doc wherever that might be needed. The doc string
for `mark-active', for instance, is one place to start: "Non-nil means the mark
and region are currently active in this buffer." We need to add something like
this: "The value is used only when transient-mark-mode is on. Active and
inactive mark and region apply only to transient-mark-mode."

HTH. In sum, the solution is to recognize and make clear(er) that "active"
applies only to t-m-m. It is misguided to try to describe or define "active"
outside t-m-m. Trust me, that attempt would ultimately make things far _more_
confusing. (Sorry, Alan.)