From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: Documentation of transient-mark-mode is sloppy, wrong, and confused. Date: Fri, 29 May 2009 17:11:48 -0700 Message-ID: References: <20090528122927.GA2175@muc.de><79C872A753DA460C822745F1B95D7EE3@us.oracle.com> <20090529222014.GA2335@muc.de> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1243642340 5904 80.91.229.12 (30 May 2009 00:12:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 30 May 2009 00:12:20 +0000 (UTC) Cc: cyd@stupidchicken.com, 'Eli Zaretskii' , 'Stefan Monnier' , emacs-devel@gnu.org To: "'Alan Mackenzie'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat May 30 02:12:14 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 1MACBI-00031T-FQ for ged-emacs-devel@m.gmane.org; Sat, 30 May 2009 02:12:14 +0200 Original-Received: from localhost ([127.0.0.1]:40623 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MACBE-0004to-58 for ged-emacs-devel@m.gmane.org; Fri, 29 May 2009 20:12:08 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MACB9-0004tP-3F for emacs-devel@gnu.org; Fri, 29 May 2009 20:12:03 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MACB3-0004sO-VB for emacs-devel@gnu.org; Fri, 29 May 2009 20:12:02 -0400 Original-Received: from [199.232.76.173] (port=53002 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MACB3-0004sD-Rz for emacs-devel@gnu.org; Fri, 29 May 2009 20:11:57 -0400 Original-Received: from rcsinet12.oracle.com ([148.87.113.124]:22328 helo=rgminet12.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MACAx-0003tL-P3; Fri, 29 May 2009 20:11:52 -0400 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet12.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n4U0Bcuq003912 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 30 May 2009 00:11:40 GMT Original-Received: from abhmt005.oracle.com (abhmt005.oracle.com [141.146.116.14]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n4U0CdJ6012022; Sat, 30 May 2009 00:12:40 GMT Original-Received: from dradamslap1 (/141.144.81.143) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 29 May 2009 17:11:46 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <20090529222014.GA2335@muc.de> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 Thread-Index: Acngq68wifCVfeOGS0KQK0IcZut6OwAAHzyQ X-Source-IP: abhmt005.oracle.com [141.146.116.14] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A01020A.4A2079C3.02B9:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) 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:111208 Archived-At: > 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. ;-)