* Documentation of transient-mark-mode is sloppy, wrong, and confused. @ 2009-05-28 12:29 Alan Mackenzie 2009-05-28 16:54 ` Chong Yidong 0 siblings, 1 reply; 33+ messages in thread From: Alan Mackenzie @ 2009-05-28 12:29 UTC (permalink / raw) To: emacs-devel Hi, Emacs! The description in the Emacs manual of Transient Mark Mode and related topics falls somewhat short of being adequate. In particular: On page "Mark": (i) There are no @dfn{active}, @dfn{active mark}, @dfn{active region}. o - My suggestion: "The region is termed @dfn{active} when it is highlighted. The mark is @dfn{active} whenever the region is active. This usage of ``active'' is largely historical, originating from the time when region commands were disabled when the region wasn't highlighted." (BTW: what is the correct past participle of "highlight"? Is it "highlighted" or "highlit"?) (ii) "If the mark is active, the region always extends between point and the mark," is gibberish. Does the region only sometimes extend between point and mark in other circumstances? (iii) There is confusion here as to whether a region continues to exist when it is "inactive". My personal view is that the region comes into existence when the mark is first set, and both continue existing until the buffer is killed, regardless of whether they happen to be "active" at any particular time. (iii) "The text between point and the mark is called \"the region\"", coupled with "The region persists only until you use it" implies that this text no longer "persists" after the region is "used". This sort of suggests that "using" a region kills the text in it. At any rate, this bit of manual gives a very sloppy impression, even if it does have a coherent meaning. (iv) "The mark is automatically \"deactivated\" after certain non-motion commands, including any command that changes the text in the buffer." appears to be false. (It's not possible to be definite here without knowing exactly what "active" means.) At any rate, when the region is not highlit, C-w works. (This is due to the default setting of the perplexingly named `mark-even-if-inactive'; I think this variable should be renamed to `allow-commands-on-inactive-region'.) On page "Persistent Mark": (v) The page title "Persistent Marks" is stupid. Marks ARE persistent (see (iii) above) (unless you're talking about the ones which were superseded by euros in 2001). This page should be renamed "Transient Mark Mode", or perhaps "Disabling Transient Mark Mode". This comment also applies to most of the uses of "persistent" in this page. (vi) "By default, the region is highlighted whenever it exists, and disappears once you use it or explicitly deactivate the mark.". This is untrue, or at best horribly confused. (See (iii) above). What does it mean to say that a region "disappears"? Given the given @dfn{region} (see (iii)), "disappears" can only mean "is killed", which is absurd. (vii) This page fails explicitly to state the essence of deactivated transient mark mode, namely that the region isn't highlit. Or, rather it mentions it only in the small print section, which nobody reads unless desperate. (viii) "When Transient Mark mode is off, the mark is persistent: it is _never_ deactivated, but can be set to different locations using commands such as `C-<SPC>'. After the first time you set the mark in a buffer, there is always a region in that buffer." is horribly confusing. o - This paragraph seems to hold, regardless of whether t-m-m is enabled, hence doesn't belong on this page. Maybe. o - If an @dfn{active} region means a highlighted one (as I suggest above), then with disabled t-m-m, the region is NEVER ACTIVE, not "always active". (ix) Etc. There're more things sloppy in this page, but this email is already long enough. ######################################################################### Additionally, there appears to be a conspiracy to marginalise the classical Emacs mark handling. Surely discussion of this belongs in the main "Mark" page, not hidden in some misnamed subsidiary page. I would be prepared to make this change myself. Other than that, the best way to fix all these faults, I believe, is to replace all occurances of the ridiculous phrases "active region" and "active mark" by the accurate "highlit region" (or "highlighted region"), after which the absurdities will pretty much resolve themselves. -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 12:29 Documentation of transient-mark-mode is sloppy, wrong, and confused Alan Mackenzie @ 2009-05-28 16:54 ` Chong Yidong 2009-05-28 20:15 ` Alan Mackenzie 0 siblings, 1 reply; 33+ messages in thread From: Chong Yidong @ 2009-05-28 16:54 UTC (permalink / raw) To: Alan Mackenzie; +Cc: emacs-devel Thanks; I've made some changes to the text to address these concerns. Please take another look. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 16:54 ` Chong Yidong @ 2009-05-28 20:15 ` Alan Mackenzie 2009-05-28 20:48 ` Chong Yidong 0 siblings, 1 reply; 33+ messages in thread From: Alan Mackenzie @ 2009-05-28 20:15 UTC (permalink / raw) To: Chong Yidong; +Cc: emacs-devel Hi, Yidong! On Thu, May 28, 2009 at 12:54:15PM -0400, Chong Yidong wrote: > Thanks; I've made some changes to the text to address these concerns. > Please take another look. ;-). The essence of my unhappiness is that "active" isn't defined. You've put in a formal @dfn{active}, but weaselled out of actually defining it. You state what happens _when_ the mark is "active", but not what a mark has to do or to be to acquire or to lose the essence of "active"ness. You also haven't defined what a region has to do, be, or become, to be "active". The phrase "when the region is active" occurs several times in the rest of the manual. For the rest of this email, I'm going to presume that the region is "active" exactly whenever the mark is. If the term "active" cannot be defined, it should be purged from the manual and the software, being replaced by terms we can define. Surely? As I see it, an "active" region has three attributes: (i) C-w kills it; (ii) It's highlit; (iii) M-$ checks the spelling of EACH WORD IN THE REGION (as opposed to just the one surrounding point). Now, which of these (or which combination of them) constitutes "active"ness? (i)? I guess it originally was, but due to the default setting of `mark-even-if-inactive', all regions are now active(i) all the time, rendering the entire description redundant and confusing. (ii)? "Active" is a strange way of writing "highlit", but if this is the meaning, then when transient-mark-mode is nil (as described in "Persistent Mark"), the mark is NEVER active(ii). (iii)? This cannot be. The semantic chasm between "check the spelling of lots of words, not just one" and the dictionary meaning of "active" is just too vast. Anyhow, with null t-m-m, the mark is NEVER active(iii). ######################################################################## In *scratch*, disable Transient Mark Mode, write the following line and put the region as indicated: one two threeee ^ ^ | | point mark The mark is now active (since t-m-m is nil). Therefore the region is "active". Execute the command `ispell-word' with M-$; this is a command which supposedly works on the region when the region is "active". It fails to flag the non-word "threeee", suggesting that it regards the region as "inactive". Energise transient transient-mark-mode with C-u C-x C-x, and repeat M-$. It now flags "threeee", as it should have done before. ######################################################################### I assert that the use of "active" in pages "Mark" and "Persistent Mark" and most of the rest of the book, renders them incoherent and meaningless, and that the only way to restore coherence is to get rid of "active". -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 20:15 ` Alan Mackenzie @ 2009-05-28 20:48 ` Chong Yidong 2009-05-28 23:03 ` Alan Mackenzie 0 siblings, 1 reply; 33+ messages in thread From: Chong Yidong @ 2009-05-28 20:48 UTC (permalink / raw) To: Alan Mackenzie; +Cc: emacs-devel Alan Mackenzie <acm@muc.de> writes: > The essence of my unhappiness is that "active" isn't defined. You've > put in a formal @dfn{active}, but weaselled out of actually defining > it. You state what happens _when_ the mark is "active", but not what > a mark has to do or to be to acquire or to lose the essence of > "active"ness. Good point; I've changed this accordingly. As for changing the "active mark" terminology, that's not particularly profitable, because it's already deeply embedded in the C and Lisp code for over a decade. (There are, of course, many other terminology problems of this sort in Emacs.) The main thing that's important, I think, is that the description of the "transient-mark-mode enabled" behavior and the "transient-mark-mode disabled" behavior are each internally consistent; they aren't always mutually consistent, but that's too bad. > In *scratch*, disable Transient Mark Mode, write the following line and > put the region as indicated: > > one two threeee > ^ ^ > | | > point mark > > The mark is now active (since t-m-m is nil). Therefore the region is > "active". Execute the command `ispell-word' with M-$; this is a command > which supposedly works on the region when the region is "active". It > fails to flag the non-word "threeee", suggesting that it regards the > region as "inactive". As described in the section about what happens when Transient Mark mode is disabled: Some commands, which ordinarily operate on the region when the mark is active, instead act on the entire buffer. For instance, @kbd{C-x u} normally reverses changes within the region if the mark is active; when Transient Mark mode is off, it acts on the entire buffer. However, you can type @kbd{C-u C-x u} to make it operate on the region. @xref{Undo}. Other commands that act this way are identified in their own documentation. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 20:48 ` Chong Yidong @ 2009-05-28 23:03 ` Alan Mackenzie 2009-05-28 23:53 ` Davis Herring ` (3 more replies) 0 siblings, 4 replies; 33+ messages in thread From: Alan Mackenzie @ 2009-05-28 23:03 UTC (permalink / raw) To: Chong Yidong; +Cc: emacs-devel Good midnight, Yidong! On Thu, May 28, 2009 at 04:48:15PM -0400, Chong Yidong wrote: > Alan Mackenzie <acm@muc.de> writes: > > The essence of my unhappiness is that "active" isn't defined. You've > > put in a formal @dfn{active}, but weaselled out of actually defining > > it. You state what happens _when_ the mark is "active", but not what > > a mark has to do or to be to acquire or to lose the essence of > > "active"ness. > Good point; I've changed this accordingly. Hmmm. No you haven't. You have noted one of the circumstances in which a mark becomes active, yet haven't said what it is for a mark to BE active. It is as though a young child has asked you what "pregnant" means, and the entire gist of your answer is "a woman becomes pregnant after a kissing and cuddling session". Unless you mention the growing foetus, your answer is evasive and unhelpful, in fact not really an answer at all. What, exactly, is the essence of "active"ness, in the same way that the foetus is the essence of pregnancy? I think the answer has got to be along the following lines: "The region is called @dfn{active} when Emacs marks it internally as the portion of buffer which any of a certain set of commands is to work on, when otherwise the command would use the whole buffer, or a single word, or some other portion of buffer. When the region is active, the mark is also said to be @dfn{active}." - essentially the (iii) from my previous email. Sorry for the poor wording - it's late and I'm tired. With an actual definition such as this, it becomes clear that when transient-mark-mode is disabled, the region and mark are always inactive. > As for changing the "active mark" terminology, that's not particularly > profitable, because it's already deeply embedded in the C and Lisp code > for over a decade. Bugs should be fixed, regardless of how long they've been in the source. What's new here is that the current bug is no longer a mere option, it's become a factory default. > (There are, of course, many other terminology problems of this sort in > Emacs.) Are there? I don't think there are. "of this sort" here means "so vague that you've got to struggle to pick up the meaning by osmosis". I can't think of any others, off hand. > The main thing that's important, I think, is that the description of > the "transient-mark-mode enabled" behavior and the "transient-mark-mode > disabled" behavior are each internally consistent; they aren't always > mutually consistent, but that's too bad. Manuals shouldn't be patronising. When a manual implicitly says "if you can't even figure out what I mean by \"active\", you're stupid", that's patronising. A concrete example of this is in T. Capers Jones's book "Estimating Software Costs", where he expounds expansively about "function points" (some sort of measurement of functional content), yet regards it as beneath him actually to say what a "function point" is, for the benefit of ignorant cretins like me. > > In *scratch*, disable Transient Mark Mode, write the following line > > and put the region as indicated: > > one two threeee > > ^ ^ > > | | > > point mark > > The mark is now active (since t-m-m is nil). Therefore the region is > > "active". Execute the command `ispell-word' with M-$; this is a command > > which supposedly works on the region when the region is "active". It > > fails to flag the non-word "threeee", suggesting that it regards the > > region as "inactive". > As described in the section about what happens when Transient Mark mode > is disabled: > Some commands, which ordinarily operate on the region when the mark is > active, instead act on the entire buffer. That is a definition of "active", surely, as I suggested above. Surely, it is better to regard the mark and region as being inactive when t-m-m is disabled? > For instance, @kbd{C-x u} normally reverses changes within the region > if the mark is active; when Transient Mark mode is off, it acts on > the entire buffer. However, you can type @kbd{C-u C-x u} to make it > operate on the region. @xref{Undo}. Other commands that act this > way are identified in their own documentation. -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 23:03 ` Alan Mackenzie @ 2009-05-28 23:53 ` Davis Herring 2009-05-29 11:01 ` Alan Mackenzie 2009-05-29 0:21 ` Chong Yidong ` (2 subsequent siblings) 3 siblings, 1 reply; 33+ messages in thread From: Davis Herring @ 2009-05-28 23:53 UTC (permalink / raw) To: Alan Mackenzie; +Cc: Chong Yidong, emacs-devel >> Some commands, which ordinarily operate on the region when the mark is >> active, instead act on the entire buffer. > > That is a definition of "active", surely, as I suggested above. Surely, > it is better to regard the mark and region as being inactive when t-m-m > is disabled? It seems to me that there are two kinds of activeness of the mark (and the region; they have between them only one state). The first kind (call it active1) is associated with commands like `kill-region', which refuse to do anything unless the region is active1. Outside of transient mark mode, the mark is always active1 if it exists at all; with tmm, the mark is frequently activated1 and deactivated1. The other kind (active2) is associated with commands like `undo', `insert-parentheses', and `how-many', which restrict, extend, or change (respectively) their area of effect to be the region iff it is active2. Outside of transient mark mode, the mark is never active2 at all; with tmm, the mark is active2 iff it is active1. So we see that while there are two predicates, they can be resolved as (or (not transient-mark-mode) (mark-active)) and (and transient-mark-mode (mark-active)). Since my imaginary function `mark-active' is only ever called when tmm is on, we may take it to return nil otherwise and replace active2 with just (mark-active). There is then only one variable "active", but tmm has different effects on different interpretations of its value. Sidebar: I like the 22 feature of turning tmm on temporarily; I don't like it in general (partly because I like the mark being active1), but otherwise I cannot have an active2 mark at all. Davis -- This product is sold by volume, not by mass. If it appears too dense or too sparse, it is because mass-energy conversion has occurred during shipping. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 23:53 ` Davis Herring @ 2009-05-29 11:01 ` Alan Mackenzie 0 siblings, 0 replies; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 11:01 UTC (permalink / raw) To: Davis Herring; +Cc: Chong Yidong, emacs-devel Hi, Davis! On Thu, May 28, 2009 at 04:53:14PM -0700, Davis Herring wrote: > >> Some commands, which ordinarily operate on the region when the > >> mark is active, instead act on the entire buffer. > > That is a definition of "active", surely, as I suggested above. > > Surely, it is better to regard the mark and region as being inactive > > when t-m-m is disabled? > It seems to me that there are two kinds of activeness of the mark (and > the region; they have between them only one state). The first kind > (call it active1) is associated with commands like `kill-region', which > refuse to do anything unless the region is active1. Outside of > transient mark mode, the mark is always active1 if it exists at all; > with tmm, the mark is frequently activated1 and deactivated1. > The other kind (active2) is associated with commands like `undo', > `insert-parentheses', and `how-many', which restrict, extend, or change > (respectively) their area of effect to be the region iff it is active2. > Outside of transient mark mode, the mark is never active2 at all; with > tmm, the mark is active2 iff it is active1. Bingo! That's the answer! Thanks! So an honest @dfn{active} would be along the lines: Historically, @dfn{active region} has had two distinct, sometimes contradictory meanings: @itemize @bullet @item Certain commands which use the region, such as @key{C-w} (@code{kill-region}) are disabled when the region isn't @dfn{active}. As from Emacs 23, the region is now always ``active'' in this sense, unless you set the user option @code{mark-even-when-inactive} (@pxref{...}). @item Certain commands work in an enhanced manner when the region is @dfn{active}: for example, `fill-paragraph' (@pxref{..}) fills the region when it is active, rather than just the current paragraph. When the region is ``active'' in this sense, it is highlit. @end @itemize Most uses of ``active'' in this manual have the second meaning. > So we see that while there are two predicates, they can be resolved as (or > (not transient-mark-mode) (mark-active)) and (and transient-mark-mode > (mark-active)). I think these can be more simply expressed as (i) mark-active and (ii) (use-region-p). > Since my imaginary function `mark-active' is only ever called when tmm > is on, we may take it to return nil otherwise and replace active2 with > just (mark-active). There is then only one variable "active", but tmm > has different effects on different interpretations of its value. > Sidebar: I like the 22 feature of turning tmm on temporarily; I don't like > it in general (partly because I like the mark being active1), but > otherwise I cannot have an active2 mark at all. Doesn't (setq mark-even-if-inactive t) do what you want? > Davis -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 23:03 ` Alan Mackenzie 2009-05-28 23:53 ` Davis Herring @ 2009-05-29 0:21 ` Chong Yidong 2009-05-29 1:55 ` Stefan Monnier 2009-05-29 8:38 ` Eli Zaretskii 3 siblings, 0 replies; 33+ messages in thread From: Chong Yidong @ 2009-05-29 0:21 UTC (permalink / raw) To: Alan Mackenzie; +Cc: emacs-devel Alan Mackenzie <acm@muc.de> writes: >> As for changing the "active mark" terminology, that's not particularly >> profitable, because it's already deeply embedded in the C and Lisp code >> for over a decade. > > Bugs should be fixed, regardless of how long they've been in the source. > What's new here is that the current bug is no longer a mere option, it's > become a factory default. No, changing the variable `mark-active' is a non-starter. There's too much code outside the Emacs source tree that depends on its current meaning. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 23:03 ` Alan Mackenzie 2009-05-28 23:53 ` Davis Herring 2009-05-29 0:21 ` Chong Yidong @ 2009-05-29 1:55 ` Stefan Monnier 2009-05-29 4:30 ` Kevin Rodgers 2009-05-29 8:37 ` Eli Zaretskii 2009-05-29 8:38 ` Eli Zaretskii 3 siblings, 2 replies; 33+ messages in thread From: Stefan Monnier @ 2009-05-29 1:55 UTC (permalink / raw) To: Alan Mackenzie; +Cc: Chong Yidong, emacs-devel > Hmmm. No you haven't. You have noted one of the circumstances in which > a mark becomes active, yet haven't said what it is for a mark to BE > active. It is as though a young child has asked you what "pregnant" > means, and the entire gist of your answer is "a woman becomes pregnant > after a kissing and cuddling session". Unless you mention the growing > foetus, your answer is evasive and unhelpful, in fact not really an > answer at all. What, exactly, is the essence of "active"ness, in the > same way that the foetus is the essence of pregnancy? The problkem is that the activeness of the mark doesn't describe some property of some other state. It's a state itself. In your analogy, there's no foetus that would allow us to determine whether the mark is active. All we have is the `mark-active' variable, so in the end all we can say is "the mark is active if the mark is active". > I think the answer has got to be along the following lines: "The region > is called @dfn{active} when Emacs marks it internally as the portion of > buffer which any of a certain set of commands is to work on, when > otherwise the command would use the whole buffer, or a single word, or > some other portion of buffer. When the region is active, the mark is > also said to be @dfn{active}." - essentially the (iii) from my previous > email. Sorry for the poor wording - it's late and I'm tired. I would find this fairly confusing, giving the impression that Emacs magically sometimes marks the region in some way outside of the user's control. > Surely, it is better to regard the mark and region as being inactive > when t-m-m is disabled? That's a delicate question, because mark-active sadly disagrees with you. Basically, I'd agree, but the code needs to be changed to reflect that (by basically introducing a notion of "existing mark" as distinct from "mark active"). Stefan ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 1:55 ` Stefan Monnier @ 2009-05-29 4:30 ` Kevin Rodgers 2009-05-29 5:47 ` Andreas Roehler 2009-05-29 8:37 ` Eli Zaretskii 1 sibling, 1 reply; 33+ messages in thread From: Kevin Rodgers @ 2009-05-29 4:30 UTC (permalink / raw) To: emacs-devel Stefan Monnier wrote: >> Hmmm. No you haven't. You have noted one of the circumstances in which >> a mark becomes active, yet haven't said what it is for a mark to BE >> active. It is as though a young child has asked you what "pregnant" >> means, and the entire gist of your answer is "a woman becomes pregnant >> after a kissing and cuddling session". Unless you mention the growing >> foetus, your answer is evasive and unhelpful, in fact not really an >> answer at all. What, exactly, is the essence of "active"ness, in the >> same way that the foetus is the essence of pregnancy? > > The problkem is that the activeness of the mark doesn't describe some > property of some other state. It's a state itself. In your analogy, > there's no foetus that would allow us to determine whether the mark > is active. All we have is the `mark-active' variable, so in the end all > we can say is "the mark is active if the mark is active". Can't we say that "the mark is active if `mark-active' is non-nil"? Note that mark-active is not mentioned in the Emacs manual, only in the Emacs Lisp manual. -- Kevin Rodgers Denver, Colorado, USA ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 4:30 ` Kevin Rodgers @ 2009-05-29 5:47 ` Andreas Roehler 2009-05-29 8:25 ` Stephen J. Turnbull 0 siblings, 1 reply; 33+ messages in thread From: Andreas Roehler @ 2009-05-29 5:47 UTC (permalink / raw) To: Kevin Rodgers; +Cc: emacs-devel Kevin Rodgers wrote: > Stefan Monnier wrote: >>> Hmmm. No you haven't. You have noted one of the circumstances in which >>> a mark becomes active, yet haven't said what it is for a mark to BE >>> active. It is as though a young child has asked you what "pregnant" >>> means, and the entire gist of your answer is "a woman becomes pregnant >>> after a kissing and cuddling session". Unless you mention the growing >>> foetus, your answer is evasive and unhelpful, in fact not really an >>> answer at all. What, exactly, is the essence of "active"ness, in the >>> same way that the foetus is the essence of pregnancy? >> >> The problkem is that the activeness of the mark doesn't describe some >> property of some other state. It's a state itself. In your analogy, >> there's no foetus that would allow us to determine whether the mark >> is active. All we have is the `mark-active' variable, so in the end all >> we can say is "the mark is active if the mark is active". > > Can't we say that "the mark is active if `mark-active' is non-nil"? > > Note that mark-active is not mentioned in the Emacs manual, only in the > Emacs Lisp manual. > We have three states but two words for now to describe it States are: - the mark is set - the mark is set and exists at different location from point, i.e. region has an extent - region has an extent and is visible (transient-mark-mode on) The both first may be described with `exist' The both latter with `active' Confusion might be solved naming the states 1) region-exists-p 2) region-has-extent 3) region-is-visible Best regards Andreas Röhler ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 5:47 ` Andreas Roehler @ 2009-05-29 8:25 ` Stephen J. Turnbull 2009-05-29 8:58 ` Alan Mackenzie 0 siblings, 1 reply; 33+ messages in thread From: Stephen J. Turnbull @ 2009-05-29 8:25 UTC (permalink / raw) To: Andreas Roehler; +Cc: Kevin Rodgers, emacs-devel Andreas Roehler writes: > 1) region-exists-p > 2) region-has-extent Please don't use this term this way. It would be very confusing for XEmacs. It's not clear to me why anybody cares about whether the region has non-zero length or not, anyway. It seems to me that `region-exists-p' and `region-active-p' as used in XEmacs would be sufficient. > 3) region-is-visible I don't understand what Alan's problem with "active regions" is. As I've pointed out in the past, although "receptive" might be a better term, usages like "active receptor" (in biochemistry) are very common. If Alan is essentially unique in this objection, and he seems to be (sorry, Alan!) then I see no need to cater to him. > > Best regards > > Andreas Röhler > ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 8:25 ` Stephen J. Turnbull @ 2009-05-29 8:58 ` Alan Mackenzie 2009-06-01 2:34 ` Stephen J. Turnbull 0 siblings, 1 reply; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 8:58 UTC (permalink / raw) To: Stephen J. Turnbull; +Cc: Kevin Rodgers, Andreas Roehler, emacs-devel Hi, Stephen! On Fri, May 29, 2009 at 05:25:44PM +0900, Stephen J. Turnbull wrote: > Andreas Roehler writes: > > 1) region-exists-p > > 2) region-has-extent > Please don't use this term this way. It would be very confusing for > XEmacs. > It's not clear to me why anybody cares about whether the region has > non-zero length or not, anyway. <sarcasm> Obviously the situation was too simple and obvious, so it was necessary to introduce some complication to make people sit up and think. </sarcasm> I'm speculating here: When a region has zero length, it's difficult to see the highlighting on it. Because it "looks" as thought the region is not "active", it's possibly better to handle user commands as though it weren't "active". Maybe. > It seems to me that `region-exists-p' and `region-active-p' as used in > XEmacs would be sufficient. Does XEmacs have a definition of an "active region"? ;-) > > 3) region-is-visible > I don't understand what Alan's problem with "active regions" is. As > I've pointed out in the past, although "receptive" might be a better > term, usages like "active receptor" (in biochemistry) are very common. > If Alan is essentially unique in this objection, and he seems to be > (sorry, Alan!) then I see no need to cater to him. No problem! But that's not my gripe here. (My objection to using words like "active" to describe a state which isn't "being an agent" is that such loose usage is liable to lead to confusion. Here, it has manifestly lead to massive confusion.) My problem is that the technical word "active" is used without being defined. I surely can't be the only Emacs user who feels patronised and insulted when manuals talk down at me by using fancy words without saying what they mean. Often, when manual authors do this, it is because they themselves don't know what their fancy word means either, as is the case here. "But EVERYBODY know what \"active\" means!" just won't do. -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 8:58 ` Alan Mackenzie @ 2009-06-01 2:34 ` Stephen J. Turnbull 2009-06-01 9:40 ` Lennart Borgman 2009-06-02 6:23 ` Andreas Roehler 0 siblings, 2 replies; 33+ messages in thread From: Stephen J. Turnbull @ 2009-06-01 2:34 UTC (permalink / raw) To: Alan Mackenzie; +Cc: Kevin Rodgers, Andreas Roehler, emacs-devel Alan Mackenzie writes: > Does XEmacs have a definition of an "active region"? ;-) Yes, although it's a little hard to find because of the heritage of XEmacs in the Lisp machine world. C-h v zmacs-regions RET sez: ------------------------------------------------------------------------ `zmacs-regions' is a built-in boolean variable. -- loaded from "/playpen/src/XEmacs/xemacs/src/editfns.c" Value: t Documentation: *Whether LISPM-style active regions should be used. This means that commands which operate on the region (the area between the point and the mark) will only work while the region is in the ``active'' state, which is indicated by highlighting. Executing most commands causes the region to not be in the active state, so (for example) C-w will only work immediately after activating the region. More specifically: - Commands which operate on the region only work if the region is active. - Only a very small set of commands cause the region to become active: Those commands whose semantics are to mark an area, like `mark-defun'. - The region is deactivated after each command that is executed, except that: - "Motion" commands do not change whether the region is active or not. set-mark-command (C-SPC) pushes a mark and activates the region. Moving the cursor with normal motion commands (C-n, C-p, etc) will cause the region between point and the recently-pushed mark to be highlighted. It will remain highlighted until some non-motion command is executed. exchange-point-and-mark (C-x C-x) activates the region. So if you mark a region and execute a command that operates on it, you can reactivate the same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it again. Generally, commands which push marks as a means of navigation (like beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the region. But commands which push marks as a means of marking an area of text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h)) do activate the region. The way the command loop actually works with regard to deactivating the region is as follows: - If the variable `zmacs-region-stays' has been set to t during the command just executed, the region is left alone (this is how the motion commands make the region stay around; see the `_' flag in the `interactive' specification). `zmacs-region-stays' is reset to nil before each command is executed. - If the function `zmacs-activate-region' has been called during the command just executed, the region is left alone. Very few functions should actually call this function. - Otherwise, if the region is active, the region is deactivated and the `zmacs-deactivate-region-hook' is called. ------------------------------------------------------------------------ > Here, it has manifestly lead to massive confusion. I suspect that is mostly just the unfortunate Emacs terminology, variable names, and documentation for the concept (sorry guys, but "unfortunate" is the nicest thing I can say about the stuff quoted in this thread), not because the word "active" itself is confusing. > "But EVERYBODY know what \"active\" means!" just won't do. I don't think XEmacs's definition has that problem. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-06-01 2:34 ` Stephen J. Turnbull @ 2009-06-01 9:40 ` Lennart Borgman 2009-06-02 6:23 ` Andreas Roehler 1 sibling, 0 replies; 33+ messages in thread From: Lennart Borgman @ 2009-06-01 9:40 UTC (permalink / raw) To: Stephen J. Turnbull Cc: Alan Mackenzie, Kevin Rodgers, Andreas Roehler, emacs-devel On Mon, Jun 1, 2009 at 4:34 AM, Stephen J. Turnbull <stephen@xemacs.org> wrote: > Alan Mackenzie writes: > > > Does XEmacs have a definition of an "active region"? ;-) > > Yes, although it's a little hard to find because of the heritage of > XEmacs in the Lisp machine world. C-h v zmacs-regions RET sez: > > ------------------------------------------------------------------------ > `zmacs-regions' is a built-in boolean variable. > -- loaded from "/playpen/src/XEmacs/xemacs/src/editfns.c" > > Value: t > > Documentation: > *Whether LISPM-style active regions should be used. > This means that commands which operate on the region (the area between the > point and the mark) will only work while the region is in the ``active'' > state, which is indicated by highlighting. Executing most commands causes > the region to not be in the active state, so (for example) C-w will only > work immediately after activating the region. > > More specifically: > > - Commands which operate on the region only work if the region is active. > - Only a very small set of commands cause the region to become active: > Those commands whose semantics are to mark an area, like `mark-defun'. > - The region is deactivated after each command that is executed, except that: > - "Motion" commands do not change whether the region is active or not. > > set-mark-command (C-SPC) pushes a mark and activates the region. Moving the > cursor with normal motion commands (C-n, C-p, etc) will cause the region > between point and the recently-pushed mark to be highlighted. It will > remain highlighted until some non-motion command is executed. This sounds good to me and is easy to read. > exchange-point-and-mark (C-x C-x) activates the region. So if you mark a > region and execute a command that operates on it, you can reactivate the > same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it > again. That seems useful. (But the cua hint is a bit obscure.) > Generally, commands which push marks as a means of navigation (like > beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the > region. But commands which push marks as a means of marking an area of > text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h)) > do activate the region. This is also clear. > The way the command loop actually works with regard to deactivating the > region is as follows: > > - If the variable `zmacs-region-stays' has been set to t during the command > just executed, the region is left alone (this is how the motion commands > make the region stay around; see the `_' flag in the `interactive' > specification). `zmacs-region-stays' is reset to nil before each command > is executed. > - If the function `zmacs-activate-region' has been called during the command > just executed, the region is left alone. Very few functions should > actually call this function. > - Otherwise, if the region is active, the region is deactivated and > the `zmacs-deactivate-region-hook' is called. > ------------------------------------------------------------------------ > > > Here, it has manifestly lead to massive confusion. > > I suspect that is mostly just the unfortunate Emacs terminology, > variable names, and documentation for the concept (sorry guys, but > "unfortunate" is the nicest thing I can say about the stuff quoted in > this thread), not because the word "active" itself is confusing. I think something like the text above could make "(emacs) Mark" more easy to read. > > "But EVERYBODY know what \"active\" means!" just won't do. > > I don't think XEmacs's definition has that problem. > > > ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-06-01 2:34 ` Stephen J. Turnbull 2009-06-01 9:40 ` Lennart Borgman @ 2009-06-02 6:23 ` Andreas Roehler 2009-06-02 11:50 ` Stephen J. Turnbull 1 sibling, 1 reply; 33+ messages in thread From: Andreas Roehler @ 2009-06-02 6:23 UTC (permalink / raw) To: Stephen J. Turnbull Cc: Alan Mackenzie, Kevin Rodgers, Stefan Monnier, emacs-devel Stephen J. Turnbull wrote: > Alan Mackenzie writes: > > > Does XEmacs have a definition of an "active region"? ;-) > > Yes, although it's a little hard to find because of the heritage of > XEmacs in the Lisp machine world. C-h v zmacs-regions RET sez: > > ------------------------------------------------------------------------ > `zmacs-regions' is a built-in boolean variable. > -- loaded from "/playpen/src/XEmacs/xemacs/src/editfns.c" > > Value: t > > Documentation: > *Whether LISPM-style active regions should be used. > This means that commands which operate on the region (the area between the > point and the mark) will only work while the region is in the ``active'' > state, which is indicated by highlighting. Executing most commands causes > the region to not be in the active state, so (for example) C-w will only > work immediately after activating the region. > > More specifically: > > - Commands which operate on the region only work if the region is active. > - Only a very small set of commands cause the region to become active: > Those commands whose semantics are to mark an area, like `mark-defun'. > - The region is deactivated after each command that is executed, except that: > - "Motion" commands do not change whether the region is active or not. > > set-mark-command (C-SPC) pushes a mark and activates the region. Moving the > cursor with normal motion commands (C-n, C-p, etc) will cause the region > between point and the recently-pushed mark to be highlighted. It will > remain highlighted until some non-motion command is executed. > > exchange-point-and-mark (C-x C-x) activates the region. So if you mark a > region and execute a command that operates on it, you can reactivate the > same region with C-x C-x (or perhaps C-x C-x C-x C-x) to operate on it > again. > > Generally, commands which push marks as a means of navigation (like > beginning-of-buffer and end-of-buffer (M-< and M->)) do not activate the > region. But commands which push marks as a means of marking an area of > text (like mark-defun (M-C-h), mark-word (M-@) or mark-whole-buffer (C-x h)) > do activate the region. > > The way the command loop actually works with regard to deactivating the > region is as follows: > > - If the variable `zmacs-region-stays' has been set to t during the command > just executed, the region is left alone (this is how the motion commands > make the region stay around; see the `_' flag in the `interactive' > specification). `zmacs-region-stays' is reset to nil before each command > is executed. > - If the function `zmacs-activate-region' has been called during the command > just executed, the region is left alone. Very few functions should > actually call this function. > - Otherwise, if the region is active, the region is deactivated and > the `zmacs-deactivate-region-hook' is called. > ------------------------------------------------------------------------ > > > Here, it has manifestly lead to massive confusion. > > I suspect that is mostly just the unfortunate Emacs terminology, > variable names, and documentation for the concept (sorry guys, but > "unfortunate" is the nicest thing I can say about the stuff quoted in > this thread), not because the word "active" itself is confusing. > > > "But EVERYBODY know what \"active\" means!" just won't do. > > I don't think XEmacs's definition has that problem. > > > IMHO XEmacs has another problem, see the docstrings of related functions ` ... (region-active-p) ... Return non-nil if the region is active in the current buffer. If `zmacs-regions' is true, this is equivalent to `region-exists-p'. Otherwise, this function always returns false. ` ... (region-exists-p) ... Return t if the region exists. If active regions are in use (i.e. `zmacs-regions' is true), this means that the region is active. Otherwise, this means that the user has pushed a mark in this buffer at some point in the past. AFAIU definitions (including zmacs-regions) are here intermixed. At least one may be dropped. For me GNU variable `mark-active' is more straightforward by its value, but should be named `mark-set' rather. Info about an existing extend I understand by `region-exists-p' in the word-sense (not the current definition). Writing `region-extends-p' might be still better. Third command may (but must not) require a visibility of region. Would leave that to the programmers to decide, delivering `region-visible-p' for the purpose. My wishlist so far for all Emacsen: `mark-set' `region-extends-p' `region-visible-p' Andreas ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-06-02 6:23 ` Andreas Roehler @ 2009-06-02 11:50 ` Stephen J. Turnbull 0 siblings, 0 replies; 33+ messages in thread From: Stephen J. Turnbull @ 2009-06-02 11:50 UTC (permalink / raw) To: Andreas Roehler Cc: Alan Mackenzie, Kevin Rodgers, Stefan Monnier, emacs-devel Andreas Roehler writes: > AFAIU definitions (including zmacs-regions) are here intermixed. At > least one may be dropped. I don't think so. zmacs-regions is a variable that controls a feature. Some people dislike that feature, so it is a user option. The other two are functions that retrieve internal state. None of the three can be defined in terms of the others without changing the semantics radically. > For me GNU variable `mark-active' is more straightforward by its value, > but should be named `mark-set' rather. What do you need it to do that plain `mark' doesn't already do? Note that since all of these APIs are of long standing in XEmacs at least, I'm pretty sure they're not going to change in XEmacs, despite the sheer perversity of the current semantics of `region-exists-p', `region-active-p', and `mark'. But it would be reasonable to add new ones if there are things that can't be easily done with the current ones, or if it would make code clearer. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 1:55 ` Stefan Monnier 2009-05-29 4:30 ` Kevin Rodgers @ 2009-05-29 8:37 ` Eli Zaretskii 2009-05-29 9:27 ` Alan Mackenzie 2009-05-29 9:55 ` Stephen J. Turnbull 1 sibling, 2 replies; 33+ messages in thread From: Eli Zaretskii @ 2009-05-29 8:37 UTC (permalink / raw) To: Stefan Monnier; +Cc: acm, cyd, emacs-devel > From: Stefan Monnier <monnier@iro.umontreal.ca> > Date: Thu, 28 May 2009 21:55:51 -0400 > Cc: Chong Yidong <cyd@stupidchicken.com>, emacs-devel@gnu.org > > > I think the answer has got to be along the following lines: "The region > > is called @dfn{active} when Emacs marks it internally as the portion of > > buffer which any of a certain set of commands is to work on, when > > otherwise the command would use the whole buffer, or a single word, or > > some other portion of buffer. When the region is active, the mark is > > also said to be @dfn{active}." - essentially the (iii) from my previous > > email. Sorry for the poor wording - it's late and I'm tired. > > I would find this fairly confusing So would I. If you read this text carefully, it actually says something like "the region is active when Emacs marks it as active." That's hardly a definition of what "active" is. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 8:37 ` Eli Zaretskii @ 2009-05-29 9:27 ` Alan Mackenzie 2009-05-29 10:11 ` Eli Zaretskii 2009-05-29 9:55 ` Stephen J. Turnbull 1 sibling, 1 reply; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 9:27 UTC (permalink / raw) To: Eli Zaretskii; +Cc: cyd, Stefan Monnier, emacs-devel Hi, Eli! On Fri, May 29, 2009 at 11:37:26AM +0300, Eli Zaretskii wrote: > > From: Stefan Monnier <monnier@iro.umontreal.ca> > > Date: Thu, 28 May 2009 21:55:51 -0400 > > Cc: Chong Yidong <cyd@stupidchicken.com>, emacs-devel@gnu.org > > > I think the answer has got to be along the following lines: "The region > > > is called @dfn{active} when Emacs marks it internally as the portion of > > > buffer which any of a certain set of commands is to work on, when > > > otherwise the command would use the whole buffer, or a single word, or > > > some other portion of buffer. When the region is active, the mark is > > > also said to be @dfn{active}." - essentially the (iii) from my previous > > > email. Sorry for the poor wording - it's late and I'm tired. > > I would find this fairly confusing > So would I. If you read this text carefully, it actually says > something like "the region is active when Emacs marks it as active." > That's hardly a definition of what "active" is. Well, it's just as good as anybody else has come up with, so far! But the criticism isn't quite fair. My definition says "a region is active, when it will make itself the object manipulated by any of the commands `replace-string', `how-many', `keep-lines', `undo', `ispell-word', `ispell', `Mouse-3', `indent-for-tab-command', `fill-paragraph', `sgml-tag', <setting of colour text properties>, `set-justification-left/right/center/full/none', `comment-dwim', <VC-Directory-Mode's m, u commands>, <Stuff when delete-selection-mode is enabled>, `keyboard-quit'". At least, it would have done if I'd've been wide enough awake. Do you agree or disagree with me that this is what "active" means, regardless of my clumsy way of saying it? If you disagree, what do think "active" actually does mean? -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 9:27 ` Alan Mackenzie @ 2009-05-29 10:11 ` Eli Zaretskii 2009-05-29 13:13 ` Alan Mackenzie 2009-05-29 14:19 ` Stefan Monnier 0 siblings, 2 replies; 33+ messages in thread From: Eli Zaretskii @ 2009-05-29 10:11 UTC (permalink / raw) To: Alan Mackenzie; +Cc: cyd, monnier, emacs-devel > Date: Fri, 29 May 2009 09:27:09 +0000 > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, cyd@stupidchicken.com, > emacs-devel@gnu.org > From: Alan Mackenzie <acm@muc.de> > > My definition says "a region is > active, when it will make itself the object manipulated by any of the > commands `replace-string', `how-many', `keep-lines', `undo', > `ispell-word', `ispell', `Mouse-3', `indent-for-tab-command', > `fill-paragraph', `sgml-tag', <setting of colour text properties>, > `set-justification-left/right/center/full/none', `comment-dwim', > <VC-Directory-Mode's m, u commands>, <Stuff when delete-selection-mode > is enabled>, `keyboard-quit'". You are replacing a possibly obscure definition with one that is even more obscure. Your text says "a region is active when it is an object manipulated by commands XXX, YYY, ZZZ, etc." I cannot make heads or tails of this definition. And even if I could, it is not instrumental, I cannot apply this definition to know when the region is active and when it isn't. I'm guessing that you wanted to say something like "region is active when these and those commands operate on the region only, as opposed to the entire buffer." But that is a circular definition, because the manual will say in a short while that "when region is active, some commands operate on the region rather than on the whole buffer." So I think trying to go in this direction will result in an impasse. > Do you agree or disagree with me that this is what "active" means, > regardless of my clumsy way of saying it? I disagree. You in effect say how an active region changes behavior of Emacs commands, which is exactly what you didn't like in the original text. > If you disagree, what do think "active" actually does mean? How about something along the following lines: The region can be in one of two states: active or inactive. When the region is active, certain Emacs commands automatically operate on the text in the region, instead of on the whole buffer. For example, bla-bla-bla. By contrast, an inactive region can only be operated upon by commands specially designed for that job, such as @code{call-process-region}, @code{count-lines-region}, @code{write-region}, etc. When the region is active, the function @code{region-active-p} returns a non-@code{nil} value. The region becomes active when: <describe here the various ways of activating the region> WDYT? ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 10:11 ` Eli Zaretskii @ 2009-05-29 13:13 ` Alan Mackenzie 2009-05-29 14:19 ` Stefan Monnier 1 sibling, 0 replies; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 13:13 UTC (permalink / raw) To: Eli Zaretskii; +Cc: cyd, monnier, emacs-devel Hi, Eli! On Fri, May 29, 2009 at 01:11:30PM +0300, Eli Zaretskii wrote: > > Date: Fri, 29 May 2009 09:27:09 +0000 > > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, cyd@stupidchicken.com, > > emacs-devel@gnu.org > > From: Alan Mackenzie <acm@muc.de> > > My definition says "a region is > > active, when .... > You are replacing a possibly obscure definition with one that is even > more obscure. Your text says "a region is active when it is an object > manipulated by commands XXX, YYY, ZZZ, etc." I cannot make heads or > tails of this definition. And even if I could, it is not instrumental, > I cannot apply this definition to know when the region is active and > when it isn't. I think what you come up with below is more or less the same as I was trying to construct. But I'm glad we agree about what the definition is needed for. > I'm guessing that you wanted to say something like "region is active > when these and those commands operate on the region only, as opposed to > the entire buffer." But that is a circular definition, because the > manual will say in a short while that "when region is active, some > commands operate on the region rather than on the whole buffer." I think that isn't circularity, it's repetition - the first bit stands on its own. Even if it is formally circular, I think its meaning is clear. We're in danger of descending into philosophy, here. > So I think trying to go in this direction will result in an impasse. It would result in something better than what was there before, even if perhaps not 100% formally valid. > > Do you agree or disagree with me that this is what "active" means, > > regardless of my clumsy way of saying it? > I disagree. You in effect say how an active region changes behavior of > Emacs commands, which is exactly what you didn't like in the original > text. I'm not sure whether that's a fair criticism or not. The original "Mark" page didn't define "active" at all. Yidong's second amendment still didn't define "active", instead describing how you made a region "active". The one in the middle? I can't remember it exactly, and cvs.savannah.gnu.org is down at the moment. There was something about it which either didn't define "active", or wasn't clearly a definition. Defining a state by saying what its effect on Emacs is is the canonical way to define it. > > If you disagree, what do think "active" actually does mean? > How about something along the following lines: > The region can be in one of two states: active or inactive. When > the region is active, certain Emacs commands automatically operate > on the text in the region, instead of on the whole buffer. For > example, bla-bla-bla. By contrast, an inactive region can only be > operated upon by commands specially designed for that job, such as > @code{call-process-region}, @code{count-lines-region}, > @code{write-region}, etc. > When the region is active, the function @code{region-active-p} > returns a non-@code{nil} value. > The region becomes active when: > <describe here the various ways of activating the region> > WDYT? I pretty much agree with you. Except, Davis has discerned that we have been using "active" in two incompatible ways. -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 10:11 ` Eli Zaretskii 2009-05-29 13:13 ` Alan Mackenzie @ 2009-05-29 14:19 ` Stefan Monnier 2009-05-29 16:40 ` Drew Adams 1 sibling, 1 reply; 33+ messages in thread From: Stefan Monnier @ 2009-05-29 14:19 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Alan Mackenzie, cyd, emacs-devel > The region can be in one of two states: active or inactive. When > the region is active, certain Emacs commands automatically operate > on the text in the region, instead of on the whole buffer. For > example, bla-bla-bla. By contrast, an inactive region can only be > operated upon by commands specially designed for that job, such as > @code{call-process-region}, @code{count-lines-region}, > @code{write-region}, etc. > When the region is active, the function @code{region-active-p} > returns a non-@code{nil} value. > The region becomes active when: > <describe here the various ways of activating the region> That looks pretty good to me. Of course it also needs to say when the region becomes inactive. Stefan ^ permalink raw reply [flat|nested] 33+ messages in thread
* RE: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 14:19 ` Stefan Monnier @ 2009-05-29 16:40 ` Drew Adams 2009-05-29 22:20 ` Alan Mackenzie 0 siblings, 1 reply; 33+ messages in thread From: Drew Adams @ 2009-05-29 16:40 UTC (permalink / raw) To: 'Stefan Monnier', 'Eli Zaretskii' Cc: 'Alan Mackenzie', cyd, emacs-devel 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.) ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 16:40 ` Drew Adams @ 2009-05-29 22:20 ` Alan Mackenzie 2009-05-30 0:11 ` Drew Adams 0 siblings, 1 reply; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 22:20 UTC (permalink / raw) To: Drew Adams Cc: cyd, 'Eli Zaretskii', 'Stefan Monnier', emacs-devel 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). ^ permalink raw reply [flat|nested] 33+ messages in thread
* RE: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 22:20 ` Alan Mackenzie @ 2009-05-30 0:11 ` Drew Adams 0 siblings, 0 replies; 33+ messages in thread From: Drew Adams @ 2009-05-30 0:11 UTC (permalink / raw) To: 'Alan Mackenzie' Cc: cyd, 'Eli Zaretskii', 'Stefan Monnier', emacs-devel > 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. ;-) ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 8:37 ` Eli Zaretskii 2009-05-29 9:27 ` Alan Mackenzie @ 2009-05-29 9:55 ` Stephen J. Turnbull 2009-05-29 10:14 ` Eli Zaretskii 2009-05-29 10:45 ` Andreas Roehler 1 sibling, 2 replies; 33+ messages in thread From: Stephen J. Turnbull @ 2009-05-29 9:55 UTC (permalink / raw) To: Eli Zaretskii; +Cc: acm, cyd, Stefan Monnier, emacs-devel Eli Zaretskii writes: > > > email. Sorry for the poor wording - it's late and I'm tired. > > > > I would find this fairly confusing > > So would I. If you read this text carefully, it actually says > something like "the region is active when Emacs marks it as active." > That's hardly a definition of what "active" is. Read a little more carefully. It also explains how the behavior of Emacs changes when the mark is active. That *is* a definition of "active". ACM did say he was tired, but he's rarely *that* tired. How about In Emacs, the region is the substring of buffer text between point and mark. If the mark is not set, then there is no region. (Point always exists, and the mark is normally set early in the life of a buffer, and is moved, not unset, thereafter.) Some commands operate on this region, copying it, killing it, deleting it, or transforming it. [Insert list here if you like.] In transient mark mode, the region may be active or inactive. This is implemented as an internal flag which is set implicitly by commands which highlight the region (for example, "shifted motion commands"). The flag's value is accessed with `region-active-p'. In transient mark mode, commands that operate on the region require it to be active, or they signal an error. That is, when transient mark mode is on, we say the region is @def{active} when region commands are effective. Otherwise, we say the region is @def{not active}. When transient mark mode is off, the region is never highlighted, and commands that operate on the region will error only in the case that the mark is unset in that buffer, and the region does not exist. We also say the region is @def{not active} whenever transient mark mode is off. As a sort of abuse of terminology, it is often said that "the mark is active" (resp. "not active"), when what is meant is "the region is active" (resp. "not active"). "Inactive" may be used as a synonym for "not active". I'm probably missing or wrong on some details, but as an outline something like the above should do. IMO, a large part of the problem here is confusing the mark with the region. If the mark is set, you can always do `(goto-char (mark))' or M-x pop-mark, etc. The mark is *not* transient. The region is. But I guess it's too late to fix that. I swear on a stack of Bibles that the above text was written by me, my employer has no clue or claim on it, and I hereby contribute it to XEmacs (and veto its application since we don't have transient mark mode, thank Jamie!) But it's now the FSF's; do with it what you will, my papers for XEmacs are on file. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 9:55 ` Stephen J. Turnbull @ 2009-05-29 10:14 ` Eli Zaretskii 2009-06-01 2:09 ` Stephen J. Turnbull 2009-05-29 10:45 ` Andreas Roehler 1 sibling, 1 reply; 33+ messages in thread From: Eli Zaretskii @ 2009-05-29 10:14 UTC (permalink / raw) To: Stephen J. Turnbull; +Cc: acm, cyd, monnier, emacs-devel > From: "Stephen J. Turnbull" <stephen@xemacs.org> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, > acm@muc.de, > cyd@stupidchicken.com, > emacs-devel@gnu.org > Date: Fri, 29 May 2009 18:55:29 +0900 > > Eli Zaretskii writes: > > > > > email. Sorry for the poor wording - it's late and I'm tired. > > > > > > I would find this fairly confusing > > > > So would I. If you read this text carefully, it actually says > > something like "the region is active when Emacs marks it as active." > > That's hardly a definition of what "active" is. > > Read a little more carefully. It also explains how the behavior of > Emacs changes when the mark is active. That *is* a definition of > "active". Right, but that "definition-through-behavior" was exactly what Alan opposed to in the first place! ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 10:14 ` Eli Zaretskii @ 2009-06-01 2:09 ` Stephen J. Turnbull 0 siblings, 0 replies; 33+ messages in thread From: Stephen J. Turnbull @ 2009-06-01 2:09 UTC (permalink / raw) To: Eli Zaretskii; +Cc: acm, cyd, monnier, emacs-devel Eli Zaretskii writes: > > From: "Stephen J. Turnbull" <stephen@xemacs.org> > > Eli Zaretskii writes: > > > > > > > email. Sorry for the poor wording - it's late and I'm tired. > > > > > > > > I would find this fairly confusing > > > > > > So would I. If you read this text carefully, it actually says > > > something like "the region is active when Emacs marks it as active." > > > That's hardly a definition of what "active" is. > > > > Read a little more carefully. It also explains how the behavior of > > Emacs changes when the mark is active. That *is* a definition of > > "active". > > Right, but that "definition-through-behavior" was exactly what Alan > opposed to in the first place! No. Alan objected to d-t-b where "behavior" refers to "how to make Emacs 'activate' the mark" (behavior changes activity). What he wants is "how does Emacs's behavior change when the mark is 'active'?" (activity changes behavior). These are quite different. ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 9:55 ` Stephen J. Turnbull 2009-05-29 10:14 ` Eli Zaretskii @ 2009-05-29 10:45 ` Andreas Roehler 1 sibling, 0 replies; 33+ messages in thread From: Andreas Roehler @ 2009-05-29 10:45 UTC (permalink / raw) To: Stephen J. Turnbull; +Cc: emacs-devel Stephen J. Turnbull wrote: > Eli Zaretskii writes: > > > > > email. Sorry for the poor wording - it's late and I'm tired. > > > > > > I would find this fairly confusing > > > > So would I. If you read this text carefully, it actually says > > something like "the region is active when Emacs marks it as active." > > That's hardly a definition of what "active" is. > > Read a little more carefully. It also explains how the behavior of > Emacs changes when the mark is active. That *is* a definition of > "active". ACM did say he was tired, but he's rarely *that* tired. > > How about > > In Emacs, the region is the substring of buffer text between point > and mark. If the mark is not set, then there is no region. > (Point always exists, and the mark is normally set early in the > life of a buffer, and is moved, not unset, thereafter.) Some > commands operate on this region, copying it, killing it, deleting > it, or transforming it. [Insert list here if you like.] > > In transient mark mode, the region may be active or inactive. > This is implemented as an internal flag which is set implicitly by > commands which highlight the region (for example, "shifted motion > commands"). The flag's value is accessed with `region-active-p'. > In transient mark mode, commands that operate on the region > require it to be active, or they signal an error. That is, when > transient mark mode is on, we say the region is @def{active} when > region commands are effective. Otherwise, we say the region is > @def{not active}. > > When transient mark mode is off, the region is never highlighted, > and commands that operate on the region will error only in the > case that the mark is unset in that buffer, and the region does > not exist. IMHO its better to let this up to the programmer/circumstances. It might be well useful to make user aware of region via highlighting, preventing accidently killing and the like. Raised was just the question if the highlighting should be called ´transient-mark-mode' - as there is no transition so far. Why not introduce `region-highlight-mode' instead? We also say the region is @def{not active} whenever > transient mark mode is off. > > As a sort of abuse of terminology, it is often said that "the mark > is active" (resp. "not active"), when what is meant is "the region > is active" (resp. "not active"). "Inactive" may be used as a > synonym for "not active". > > I'm probably missing or wrong on some details, but as an outline > something like the above should do. > > IMO, a large part of the problem here is confusing the mark with the > region. If the mark is set, you can always do `(goto-char (mark))' or > M-x pop-mark, etc. The mark is *not* transient. The region is. But > I guess it's too late to fix that. > > I swear on a stack of Bibles that the above text was written by me, my > employer has no clue or claim on it, and I hereby contribute it to > XEmacs (and veto its application since we don't have transient mark > mode, thank Jamie!) But it's now the FSF's; do with it what you will, > my papers for XEmacs are on file. > > > ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-28 23:03 ` Alan Mackenzie ` (2 preceding siblings ...) 2009-05-29 1:55 ` Stefan Monnier @ 2009-05-29 8:38 ` Eli Zaretskii 2009-05-29 9:35 ` Alan Mackenzie 3 siblings, 1 reply; 33+ messages in thread From: Eli Zaretskii @ 2009-05-29 8:38 UTC (permalink / raw) To: Alan Mackenzie; +Cc: cyd, emacs-devel > Date: Thu, 28 May 2009 23:03:59 +0000 > From: Alan Mackenzie <acm@muc.de> > Cc: emacs-devel@gnu.org > > > The main thing that's important, I think, is that the description of > > the "transient-mark-mode enabled" behavior and the "transient-mark-mode > > disabled" behavior are each internally consistent; they aren't always > > mutually consistent, but that's too bad. > > Manuals shouldn't be patronising. When a manual implicitly says "if you > can't even figure out what I mean by \"active\", you're stupid", that's > patronising. Did the manual actually say that? where? ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 8:38 ` Eli Zaretskii @ 2009-05-29 9:35 ` Alan Mackenzie 2009-05-29 9:48 ` Eli Zaretskii 0 siblings, 1 reply; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 9:35 UTC (permalink / raw) To: Eli Zaretskii; +Cc: cyd, emacs-devel Hi, Eli! On Fri, May 29, 2009 at 11:38:26AM +0300, Eli Zaretskii wrote: > > Date: Thu, 28 May 2009 23:03:59 +0000 > > From: Alan Mackenzie <acm@muc.de> > > Cc: emacs-devel@gnu.org > > > The main thing that's important, I think, is that the description > > > of the "transient-mark-mode enabled" behavior and the > > > "transient-mark-mode disabled" behavior are each internally > > > consistent; they aren't always mutually consistent, but that's too > > > bad. > > Manuals shouldn't be patronising. When a manual implicitly says "if > > you can't even figure out what I mean by \"active\", you're stupid", > > that's patronising. > Did the manual actually say that? where? No, it didn't _actually_ say that, it _implicitly_ said it; or, more precisely, that's the message I would hear if I were an Emacs user trying to make sense of that page of the manual. -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 9:35 ` Alan Mackenzie @ 2009-05-29 9:48 ` Eli Zaretskii 2009-05-29 13:17 ` Alan Mackenzie 0 siblings, 1 reply; 33+ messages in thread From: Eli Zaretskii @ 2009-05-29 9:48 UTC (permalink / raw) To: Alan Mackenzie; +Cc: cyd, emacs-devel > Date: Fri, 29 May 2009 09:35:33 +0000 > Cc: cyd@stupidchicken.com, emacs-devel@gnu.org > From: Alan Mackenzie <acm@muc.de> > > > > Manuals shouldn't be patronising. When a manual implicitly says "if > > > you can't even figure out what I mean by \"active\", you're stupid", > > > that's patronising. > > > Did the manual actually say that? where? > > No, it didn't _actually_ say that, it _implicitly_ said it; or, more > precisely, that's the message I would hear if I were an Emacs user trying > to make sense of that page of the manual. What text, exactly, could send such a message? ^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: Documentation of transient-mark-mode is sloppy, wrong, and confused. 2009-05-29 9:48 ` Eli Zaretskii @ 2009-05-29 13:17 ` Alan Mackenzie 0 siblings, 0 replies; 33+ messages in thread From: Alan Mackenzie @ 2009-05-29 13:17 UTC (permalink / raw) To: Eli Zaretskii; +Cc: cyd, emacs-devel On Fri, May 29, 2009 at 12:48:39PM +0300, Eli Zaretskii wrote: > > Date: Fri, 29 May 2009 09:35:33 +0000 > > Cc: cyd@stupidchicken.com, emacs-devel@gnu.org > > From: Alan Mackenzie <acm@muc.de> > > > > Manuals shouldn't be patronising. When a manual implicitly says > > > > "if you can't even figure out what I mean by \"active\", you're > > > > stupid", that's patronising. > > > Did the manual actually say that? where? > > No, it didn't _actually_ say that, it _implicitly_ said it; or, more > > precisely, that's the message I would hear if I were an Emacs user > > trying to make sense of that page of the manual. > What text, exactly, could send such a message? All the text using the obscure undefined word "active". ^ permalink raw reply [flat|nested] 33+ messages in thread
end of thread, other threads:[~2009-06-02 11:50 UTC | newest] Thread overview: 33+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-05-28 12:29 Documentation of transient-mark-mode is sloppy, wrong, and confused Alan Mackenzie 2009-05-28 16:54 ` Chong Yidong 2009-05-28 20:15 ` Alan Mackenzie 2009-05-28 20:48 ` Chong Yidong 2009-05-28 23:03 ` Alan Mackenzie 2009-05-28 23:53 ` Davis Herring 2009-05-29 11:01 ` Alan Mackenzie 2009-05-29 0:21 ` Chong Yidong 2009-05-29 1:55 ` Stefan Monnier 2009-05-29 4:30 ` Kevin Rodgers 2009-05-29 5:47 ` Andreas Roehler 2009-05-29 8:25 ` Stephen J. Turnbull 2009-05-29 8:58 ` Alan Mackenzie 2009-06-01 2:34 ` Stephen J. Turnbull 2009-06-01 9:40 ` Lennart Borgman 2009-06-02 6:23 ` Andreas Roehler 2009-06-02 11:50 ` Stephen J. Turnbull 2009-05-29 8:37 ` Eli Zaretskii 2009-05-29 9:27 ` Alan Mackenzie 2009-05-29 10:11 ` Eli Zaretskii 2009-05-29 13:13 ` Alan Mackenzie 2009-05-29 14:19 ` Stefan Monnier 2009-05-29 16:40 ` Drew Adams 2009-05-29 22:20 ` Alan Mackenzie 2009-05-30 0:11 ` Drew Adams 2009-05-29 9:55 ` Stephen J. Turnbull 2009-05-29 10:14 ` Eli Zaretskii 2009-06-01 2:09 ` Stephen J. Turnbull 2009-05-29 10:45 ` Andreas Roehler 2009-05-29 8:38 ` Eli Zaretskii 2009-05-29 9:35 ` Alan Mackenzie 2009-05-29 9:48 ` Eli Zaretskii 2009-05-29 13:17 ` Alan Mackenzie
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).