From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. Date: Fri, 29 May 2009 22:20:14 +0000 Message-ID: <20090529222014.GA2335@muc.de> References: <20090528122927.GA2175@muc.de> <79C872A753DA460C822745F1B95D7EE3@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1243635632 24545 80.91.229.12 (29 May 2009 22:20:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 29 May 2009 22:20:32 +0000 (UTC) Cc: cyd@stupidchicken.com, 'Eli Zaretskii' , 'Stefan Monnier' , emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat May 30 00:20:28 2009 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1MAAR9-0005p2-1v for ged-emacs-devel@m.gmane.org; Sat, 30 May 2009 00:20:28 +0200 Original-Received: from localhost ([127.0.0.1]:57718 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MAAR8-00056y-Bj for ged-emacs-devel@m.gmane.org; Fri, 29 May 2009 18:20:26 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MAAR0-00050v-OG for emacs-devel@gnu.org; Fri, 29 May 2009 18:20:18 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MAAQv-0004lO-5V for emacs-devel@gnu.org; Fri, 29 May 2009 18:20:18 -0400 Original-Received: from [199.232.76.173] (port=42594 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MAAQu-0004lD-W4 for emacs-devel@gnu.org; Fri, 29 May 2009 18:20:13 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:3441 helo=mail.muc.de) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MAAQu-0003PV-2Z for emacs-devel@gnu.org; Fri, 29 May 2009 18:20:12 -0400 Original-Received: (qmail 88171 invoked by uid 3782); 29 May 2009 22:19:20 -0000 Original-Received: from acm.muc.de (pD9E50BF6.dip.t-dialin.net [217.229.11.246]) by colin2.muc.de (tmda-ofmipd) with ESMTP; Sat, 30 May 2009 00:19:16 +0200 Original-Received: (qmail 4707 invoked by uid 1000); 29 May 2009 22:20:14 -0000 Content-Disposition: inline In-Reply-To: <79C872A753DA460C822745F1B95D7EE3@us.oracle.com> User-Agent: Mutt/1.5.9i X-Delivery-Agent: TMDA/1.1.5 (Fettercairn) X-Primary-Address: acm@muc.de X-detected-operating-system: by monty-python.gnu.org: FreeBSD 4.6-4.9 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:111207 Archived-At: 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).