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 09:40:03 -0700 Message-ID: <79C872A753DA460C822745F1B95D7EE3@us.oracle.com> References: <20090528122927.GA2175@muc.de> <87fxepf9s8.fsf@cyd.mit.edu><20090528201529.GA4605@muc.de> <87bppdx8c0.fsf@cyd.mit.edu><20090528230359.GA1474@muc.de> <83zlcwqp89.fsf@gnu.org> <20090529092709.GB2793@muc.de><831vq85ict.fsf@gnu.org> 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 1243615239 30393 80.91.229.12 (29 May 2009 16:40:39 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 29 May 2009 16:40:39 +0000 (UTC) Cc: 'Alan Mackenzie' , cyd@stupidchicken.com, emacs-devel@gnu.org To: "'Stefan Monnier'" , "'Eli Zaretskii'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri May 29 18:40:34 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 1MA58A-0003QN-CC for ged-emacs-devel@m.gmane.org; Fri, 29 May 2009 18:40:30 +0200 Original-Received: from localhost ([127.0.0.1]:60456 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MA589-0001eD-GI for ged-emacs-devel@m.gmane.org; Fri, 29 May 2009 12:40:29 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MA584-0001dz-1v for emacs-devel@gnu.org; Fri, 29 May 2009 12:40:24 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MA57z-0001cz-LU for emacs-devel@gnu.org; Fri, 29 May 2009 12:40:23 -0400 Original-Received: from [199.232.76.173] (port=36079 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MA57z-0001cw-Ic for emacs-devel@gnu.org; Fri, 29 May 2009 12:40:19 -0400 Original-Received: from rcsinet12.oracle.com ([148.87.113.124]:39095 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 1MA57v-0000jX-R7; Fri, 29 May 2009 12:40:16 -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 n4TGdxaT025628 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 29 May 2009 16:40:00 GMT Original-Received: from abhmt006.oracle.com (abhmt006.oracle.com [141.146.116.15]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n4TGexeL006129; Fri, 29 May 2009 16:40:59 GMT Original-Received: from dradamslap1 (/141.144.81.143) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 29 May 2009 09:40:06 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 Thread-Index: AcngaYEqIpbbMrvARK27IZfv94BM2gABTnWw X-Source-IP: abhmt006.oracle.com [141.146.116.15] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010209.4A200FE7.01C0: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:111202 Archived-At: 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.)