emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Alan Mackenzie
Subject: Re: Documentation of transient-mark-mode is sloppy, wrong, and confused.
Date: Fri, 29 May 2009 22:20:14 +0000
User-agent: Mutt/1.5.9i

Hi, Drew,

Thanks very much for this post!

On Fri, May 29, 2009 at 09:40:03AM -0700, Drew Adams wrote:
> 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.

:-)  No apologies needed.  I don't like "active", but clearly it's going
to stay.  The bad thing is not having it defined, and thus everybody
having a different idea of what it means.

> 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.  Even with t-m-m enabled, there's
both types of "active"ness - the one which highlights, and the other
which you permanently activate by setting `mark-even-if-inactive'.

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

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.

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

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

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

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

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

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

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

> 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?  ;-)

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

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.  The "active" in `mark-active'
is active1.  Something needs to give, somewhere.

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

-- 
Alan Mackenzie (Nuremberg, Germany).




reply via email to

[Prev in Thread] Current Thread [Next in Thread]