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

[Drew Adams]

> Thanks very much for this post!

You're welcome.

> > 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).
> 
> I don't think you're right about this.

Notice the parts in parens. "Active" should never be used in the doc to mean
anything other than _transient-mark-mode_ active region (or mark). In this
thread, people, including Davis, have applied "active" to other things. But the
doc should not.

[It _should_ not, IMO, and I thought that it also _did_ not, but I see that
Emacs 22 Emacs manual node Transient Mark does speak about the "normal mode of
use" (i.e. with t-m-m turned off) having mark-setting commands "activate" the
mark. I think this language is not helpful. 

That node attempts to introduce the concept of active region, which is purely
for t-m-m, by an analogy to the situation where t-m-m is off. Which is OK. But
it should not use the terms "active" or "activate" when referring to the mark or
region with t-m-m off. This abuse of language hurts more than it helps.

Proof that this is slippery analogy, and not the definition of "active", is that
this explanation of the "normal mode" activating the mark is said to be so
because "there is _always_ a region". This confuses region existence with region
activeness. And a few sentences later, it says that in t-m-m "most of the time
there is no region"!

No wonder people are confused. And in the Emacs 23 manual, things are not
necessarily much better. It speaks of the region being "highlighted whenever it
exists", and so on.

I'll leave the manual alone now. I'll speak about what I think it should say,
rather than what it might really say at the moment.]

> Even with t-m-m enabled, there's both types of "active"ness
> - the one which highlights,

That is the only activeness, as far as the doc use of the word is concerned
(modulo the exceptions mentioned above). If the region is not active (which
means not active in t-m-m), then it is not highlighted. If it is not
highlighted, then it is not active (which means not active in t-m-m).

Region highlighting outside of t-m-m (e.g. using a mouse, with t-m-m off) is
perhaps another gray area. I don't know much about that. Does it have the same
effect in all cases as a temporary t-m-m? I kind of doubt it. But let's leave
this aside, for the moment. We might have to rationalize that behavior, to bring
it into line with t-m-m, - or not: leave it as something different altogether.
But in any case, my suggestion is that we not use the work "active" to describe
it (unless it can be made 100% identical to a temporary t-m-m).

> and the other which you permanently activate by setting
> `mark-even-if-inactive'.

Non-nil `mark-even-if-inactive' does not make the region _active_ (in the sense
I favor). It simply means that you can _use_ the region (or mark) even when it
is inactive. That is to say, in (some?) situations where a command would not
make use of the region when it is inactive, that command will still make use of
it. This variable has meaning (effect) only for t-m-m.

Yes, it is not clearly expressed (though the code must clearly define) which
commands make use of the inactive region to do what. IOW, what does it mean to
"use" the inactive region, "as if it were active"?

I agree that this is not clearly expressed in the doc, but changing the meaning
of "active" to mean anything other than t-m-m active would not be helpful, IMO.

> > AFAIK, we have never, in the doc, referred to activeness 
> > other than in the context of transient-mark-mode,

[I correct myself above. But that doc is poor, IMO. The doc _should_ never refer
to region activeness other than for t-m-m.]

> > 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.
> 
> I would support this solution wholeheartedly.
> 
> > 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.
> 
> Yes.
> 
> > 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.
> 
> Yes.
> 
> > 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.
> 
> This is active1.  This is always t (unless
> `mark-even-if-inactive' is set to nil).

Not sure what you're saying. `mark-even-if-inactive' does not change whether the
mark is active.

BTW, there are only 17 occurrences of `mark-even-if-inactive' in the entire Lisp
source code, and 7 of them are for Viper. 1 is for Customize, just to give it
its standard value. 1 is in a doc string. 12 are defvars or set it or bind it or
save it. 

There are only 2 places in all of the Emac Lisp code where we _test_ the value
of `mark-even-if-inactive'. So we should be able to explain this better, in
terms of its intention and effect. Those occurrences are:

1. In `mouse-save-then-kill' - if it is non-nil, this essentially lets us ignore
t-m-m when selecting text.

2. In function `mark' - if it is non-nil, then we return the mark value even if
it is not active. IOW, it lets us ignore t-m-m when getting the mark value.

That's it. Admittedly, the second is a basic function, so there's no telling
which commands might check the `mark' value and decide to have a different
behavior depending, ultimately, on the value of `mark-even-if-inactive'.

But the behavior difference is just that with nil value t-m-m raises an error if
the mark is not active (unless the command catches that with `condition-case'
and does something different).

> > 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.
> 
> I'm not sure what you're saying here.  I agree with your 
> second sentence, but I'm not sure how it connects with the first,
> which doesn't seem right.

I should have phrased it better. I meant only that you cannot know anything
without consulting the doc for the particular command. Knowing you're in t-m-m
does not help here in any general way. A given command can do what it wants. No
behavioral generalization fits, wrt t-m-m. The followup sentences explain it
better:

> > 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.
> 
> Thanks!  That's a very helpful way of characterising the 
> problem.  There are a lot of places in the manual which say "when
> the region is active", without mentioning disabled t-m-m.

I'm beginning to realize that now. We need to decide on the terms to use. I've
made my proposal in that regard (reserve "active region/mark" for t-m-m). Once
we agree, the doc needs to be cleaned up. The Emacs 22 manual node Transient
Mark is a prime example of confusing people by talking about how the region is
always active when t-m-m is off and how the region always exists but does not
exist most of the time when t-m-m is on. And so on.

Let's save "active region" and "active mark" as notions relevant only to t-m-m.
Then, let's clean up the doc accordingly.

Then, let's figure out how best to handle (a) mouse highlighting (~activating)
of the region, and (b) `mark-even-if-inactive' - that is, how to talk about
them.

> > 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.
> 
> Agreed wholeheartedly.  This clarification should occur at 
> every point in the doc which mentions "active"ness.
> 
> > 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.)
> 
> Is this so important?  Some commands take the same action for empty
> region as inactive region.  This seems an orthogonal issue.

That's the point. Nonempty is something different from "active". But much of the
time it makes sense for a command to treat an empty region the same as an
inactive region (in t-m-m). That's the point. That means that the doc for such
commands should specifically mention "if the region is active and nonempty"...

In my functions, for instance, I typically say something like "If the region is
not active or is empty, then bob and eob are used." Or "This is used only if
Transient Mark mode is off or the region is inactive or empty."

> > 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. 
> 
> If you talk about "the region", what you say clearly only 
> applies after the mark has been set.

There is no region before there is a mark.

> > 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.
> 
> `mark-active' is active1, and can't now be changed.  Its doc string
> should make clear that its notion of "active" is different 
> from the more useful active2.

I don't understand (or else I don't agree). `mark-active' is a variable used
(only) by t-m-m. Nothing more. It concerns the notion of "active" that I've been
arguing for: "active" means something (wrt the region/mark) only in t-m-m.
`mark-active' is _the_ test for whether the region/mark is active. It's simply
that whether or not it is active has no meaning outside of t-m-m. That's my
standpoint, at least.

> > 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.
> 
> That means revising lots of doc strings, doesn't it?  ;-)

Dunno. It's more important to start with the manual, cleaning it up so it
reserves "active" region/mark for t-m-m and makes these notions clear. Once this
is clear, doc for individual commands can be cleared up progressively.

I think part of the problem is the lack of clarity in the minds of those who
wrote the doc strings - basing themselves on the existing doc mud. Once everyone
is on the same page wrt the notions, and uses the (cleaned up) doc for those
basic notions as a base, doc for commands will get cleaned up case by case.

> > 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.

BTW - This is probably not the place to bring this up ;-), but why do buffers
start out with no mark set? From a user conceptual standpoint, it would be
easier to say that every buffer always has a mark and region. By default, the
mark position for each buffer could be (point-min). IOW, mark could be treated
just like point in this regard.

It's just a question. Is there (still) a good reason not to have an initial
mark? Is it so that the mark is always set only by the user? Is it to reduce the
size of the global mark ring (or ensure that all of its entries are meaningful)?
Just wondering. 

> > 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".
> 
> A masterpiece of clear thinking!  Thanks.
> 
> > 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.
> 
> The "active" we usually mean is active2.

That's where we disagree. At least I don't usually (or ever) mean active2. As
Davis said, "with tmm, the mark is active2 iff it is active1." For me, "active"
has meaning only in t-m-m, and in that case, there is never any distinction
between active1 and active2.

I don't think it's helpful to speak of active1 and active2. Call them foo1 and
foo2, if you like. And it doesn't help to characterize them in terms of the
kinds of commands each supports, which was the initial description Davis gave.
_Defined_ as Davis defined them, however:

def foo1: (or (not transient-mark-mode) (mark-active))
def foo2: (and transient-mark-mode (mark-active))

they can help us reason. But I think they've already served their purpose, which
for me was to help show that (1) they are both only t-m-m notions, having
meaning only when t-m-m is on (see above, where you agreed "Yes" twice) and (2)
in the context of t-m-m being on, they mean the same thing (look at the
definitions): they both mean `mark-active' when t-m-m is on.

> The "active" in `mark-active' is active1.

It is active2 also. When t-m-m is on. And you've agreed that "active/inactive"
has meaning only when t-m-m is on.

> Something needs to give, somewhere.

I don't follow. (?)
 
> > 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.)
> 
> Thanks for such a helpful post, Drew.

Dunno if we'll all reach consensus on the terminology, but we can probably all
agree that the current doc is not all that clear. ;-)