* bug#7291: 24.0.50; `non-essential' is incomprehensible @ 2010-10-27 22:30 Drew Adams 2010-10-28 0:52 ` Stefan Monnier ` (2 more replies) 0 siblings, 3 replies; 25+ messages in thread From: Drew Adams @ 2010-10-27 22:30 UTC (permalink / raw) To: 7291 Variable `non-essential' was introduced in Emacs 24. The name is bad - doesn't say anything. Non-essential wrt what? The doc is bad: "Whether the currently executing code is performing an essential task. This variable should be non-nil only when running code which should not disturb the user. E.g. it can be used to prevent Tramp from prompting the user for a password when we are simply scanning a set of files in the background or displaying possible completions before the user even asked for it." So does nil mean the code is performing an essential task? Or does non-nil mean that? What's an "essential task"? A task that should disturb the user (because it is important) or a task that should not disturb the user? What does "code which should not disturb the user" even mean? Sounds like this var should almost always be non-nil. But in fact it is almost always nil. So does that mean that almost all Emacs code SHOULD disturb the user? Is the doc backwards maybe? If not, then maybe the variable is named backwards: should it be `essential'? I cannot understand this. What does it really mean? Grepping the source code shows that this varis used only in `tramp-completion-mode-p' (so why isn't it called `tramp-non-essential...'?). If this is non-nil, that predicate returns non-nil, which indicates what? It supposedly indicates "whether method / user name / host name completion is active". Huh? How is anyone supposed to understand this? So let's look at where this is bound to non-nil... In icomplete.el, during `icomplete-completions'. No comment in the code. No clue as to why this code should be considered "non-essential" for Tramp. Why would icompleting necessarily indicate that "method / user name / host name completion is active" (whatever that might mean)? The only other place this is bound is in ido.el. Same questions apply. Please clean this up. It's incomprehensible. Presumably, this variable needs to be known to users who write Lisp code. If it is needed in `icomplete-completions' and for ido file-name completion then why wouldn't it also be needed in user code that does something similar (for some unknown meaning of "similar"). There are lots of 3rd-party libraries that define completion code. Why wouldn't they need to do something similar to what icomplete and ido do? How would a Lisp library writer know whether to do anything or what to do? If this variable is this important and global (no `tramp-' prefix) then it should be documented in the Elisp manual. In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600) of 2010-10-25 on 3249CTO Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/imagesupport/include' ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-27 22:30 bug#7291: 24.0.50; `non-essential' is incomprehensible Drew Adams @ 2010-10-28 0:52 ` Stefan Monnier 2010-10-28 16:22 ` Drew Adams 2010-10-28 17:33 ` James Cloos 2010-10-31 2:34 ` MON KEY 2 siblings, 1 reply; 25+ messages in thread From: Stefan Monnier @ 2010-10-28 0:52 UTC (permalink / raw) To: Drew Adams; +Cc: 7291 > So does nil mean the code is performing an essential task? Or does > non-nil mean that? Let's see, you're asking whether "non-essential = nil" means "performing an essential task" or "performing a non-essential task"? Hmm... now that's a difficult question which I wouldn't expect any Lisp coder to be able to answer. > I cannot understand this. What does it really mean? If you can't understand it, then just ignore it. > If this variable is this important and global (no `tramp-' prefix) then > it should be documented in the Elisp manual. Emacs lived happily for more than 20 years without it, so I really have no clue whatsoever what makes you think "it's this important". Stefan ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 0:52 ` Stefan Monnier @ 2010-10-28 16:22 ` Drew Adams 2010-10-28 17:14 ` Stefan Monnier 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2010-10-28 16:22 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: 7291 > > So does nil mean the code is performing an essential task? Or does > > non-nil mean that? > > Let's see, you're asking whether "non-essential = nil" means > "performing an essential task" or "performing a non-essential > task"? Actually, I asked whether `non-essential'=nil or `non-essential'=t means performing a non-essential task (whatever that in turn might mean). I asked about the variable value: what it's for, what it means. Do you know? The variable's only use is in Tramp. Why isn't it named with the prefix `tramp-'? Is there something more general going on? > Hmm... now that's a difficult question which I wouldn't > expect any Lisp coder to be able to answer. How cute. But if you cannot tell by reading the code and you cannot tell by reading the doc, then where are we? The doc apparently does try to answer that "difficult question", but it is not clear. Hence this doc-bug report. (Imagine a nuclear submarine with a big red flashing button labeled "UNIMPORTANT *", where the footnote `*' says "UNimportant ONLY if ______ - otherwise, IMPORTANT - push now!", where the _____ part is illegible...) The doc says something about the value determining whether or not users will be disturbed. It is unclear which value disturbs them, how it disturbs them, why or when it does so. > > I cannot understand this. What does it really mean? > > If you can't understand it, then just ignore it. Do you understand it? If so, then please clean up the doc string. That shouldn't be hard. If you do not, then let's find someone who does. > > If this variable is this important and global (no `tramp-' > > prefix) then it should be documented in the Elisp manual. > > Emacs lived happily for more than 20 years without it, so I > really have no clue whatsoever what makes you think "it's > this important". By that reasoning, we should simply remove the variable altogether. It wasn't needed during the last 20 years so it must not be needed now. (!?) You admit that the doc for this is incomprehensible and misleading. But you say that doesn't matter because this variable wasn't necessary for the previous 20 years. Huh? Still, I would like to know what this is about. Especially since it apparently matters for code that involves file-name completion. Is there something special about Ido and Icomplete that this should single them out for its treatment (whatever that treatment might be)? Or does it apply generally to file-name completion code? ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 16:22 ` Drew Adams @ 2010-10-28 17:14 ` Stefan Monnier 2010-10-28 18:43 ` Michael Albinus 2010-10-28 18:51 ` Drew Adams 0 siblings, 2 replies; 25+ messages in thread From: Stefan Monnier @ 2010-10-28 17:14 UTC (permalink / raw) To: Drew Adams; +Cc: 7291 >> > So does nil mean the code is performing an essential task? Or does >> > non-nil mean that? >> Let's see, you're asking whether "non-essential = nil" means >> "performing an essential task" or "performing a non-essential >> task"? > Actually, I asked whether `non-essential'=nil or `non-essential'=t means > performing a non-essential task (whatever that in turn might mean). Right, same thing: the answer can be found by using, not the code nor the docstring, but: your brain. > The variable's only use is in Tramp. Why isn't it named with the prefix > `tramp-'? Is there something more general going on? It's used by icomplete and ido as well, so clearly it's not a Tramp-only variable. The fact that only Tramp reacts to it right now is not significant. > You admit that the doc for this is incomprehensible and misleading. No I don't. Apparently you don't understand it, but since you can't even figure out which of "non-essential=nil" or "non-essential=t" means that the executed code is non-essential, I think you're disqualified to judge. Of course, I'm disqualified as well since I wrote it, so we're left with a lack of judgment. > Still, I would like to know what this is about. Especially since it > apparently matters for code that involves file-name completion. > Is there something special about Ido and Icomplete that this should > single them out for its treatment (whatever that treatment might be)? > Or does it apply generally to file-name completion code? Yes, they perform operations which are non-essential, i.e. during which we don't want to pester the user. The particular example where it's currently used is: prompt the user for a password just in order to show the list of possible completions when the user hasn't even asked for completion (other than by turning on icomplete or ido which causes completions to be displayed eagerly). Stefan ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 17:14 ` Stefan Monnier @ 2010-10-28 18:43 ` Michael Albinus 2010-10-28 18:51 ` Drew Adams 1 sibling, 0 replies; 25+ messages in thread From: Michael Albinus @ 2010-10-28 18:43 UTC (permalink / raw) To: Drew Adams; +Cc: 7291, Stefan Monnier Hi Drew, Stefan Monnier <monnier@IRO.UMontreal.CA> writes: > No I don't. Apparently you don't understand it, but since you can't > even figure out which of "non-essential=nil" or "non-essential=t" means > that the executed code is non-essential, I think you're disqualified > to judge. Of course, I'm disqualified as well since I wrote it, so > we're left with a lack of judgment. I'm also disqualified because I was involved in introducing this variable. But you could read the background story at <http://thread.gmane.org/gmane.emacs.bugs/35968/focus=36234>. HTH, Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 17:14 ` Stefan Monnier 2010-10-28 18:43 ` Michael Albinus @ 2010-10-28 18:51 ` Drew Adams 2010-10-28 20:12 ` Stefan Monnier 1 sibling, 1 reply; 25+ messages in thread From: Drew Adams @ 2010-10-28 18:51 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: 7291 > the answer can be found by using, not the code nor > the docstring, but: your brain. Personal insults are really not necessary, Stefan. > > The variable's only use is in Tramp. Why isn't it named > > with the prefix `tramp-'? Is there something more general > > going on? > > It's used by icomplete and ido as well, so clearly it's not > a Tramp-only variable. The fact that only Tramp reacts to it > right now is not significant. As I said in the original report, it is _used_ only in tramp.el, and it is _bound_ in ido.el and icomplete.el. AFAICT, the _reason_ it is bound there is for Tramp and Tramp alone. If some day this var were to have some additional effect, besides preventing Tramp from reading passwords, then ido.el and icomplete.el might need to be revisited. Any such additional (non-Tramp) effect would at least have to take into consideration any existing users such as ido.el and icomplete.el, in order to be sure not to break them. So the relation with Tramp is hardly insignificant. > Apparently you don't understand it, but since you can't > even figure out which of "non-essential=nil" or > "non-essential=t" means that the executed code is non-essential, > I think you're disqualified to judge. I am qualified to judge that the doc string is confusing to at least one reader, me. And as a longtime professional doc writer, it is likely that I'm somewhat qualified to guess that it might be confusing to some other readers as well. It's not so much that I can't figure things out from the code as it is that I think the current doc can confuse readers. FWIW, I have bound this var for six months now in my own completion code. It is the doc string that this bug report is about. The typical Emacs convention for such a doc string is to say clearly, preferably in the first line, what a nil or non-nil value means. For example: "Non-nil means the currently executing code is performing a non-essential task" or "nil means the executing code is performing an essential task". Not "_Whether_ the currently executing code is performing an essential task", which is ambiguous. That's the first change that should be made: state explicitly the particular value that means "non-essential" (or "essential"). The second change is to state what "non-essential" means here. It apparently means that the task being performed is so IMPORTANT that the user should NOT be interrupted (e.g. to read a password). And that goes somewhat against the usual meaning of "non-essential". One could easily suppose that a non-essential task is one that it is NOT IMPORTANT enough to protect against interruption. Especially because of this unusual interpretation, the meaning (behavior) needs to be pointed out clearly. I am not arguing that you should call it "essential" instead of "non-essential". An argument can be made for either - the devil is in the details (the actual behavior). The password reading would, yes, be unimportant here, non-essential (useless in fact, since no access is really needed at that point), so we dispense with it in order not to disrupt the user. I get that. But the "currently executing code" that would be interrupted by a password reading is not performing an unimportant, non-essential task - what it is doing is more important than reading a password, and we don't want to interrupt it. My point is only that the behavior needs to be stated clearly, and that is not the case now. And interrupted by what? In practice, so far at least, the answer is password-prompting. The example in the doc string is OK for pointing this out. > Of course, I'm disqualified as well since I wrote it, so > we're left with a lack of judgment. You seem to be defending the doc as it is only because you wrote it. It doesn't matter that a user points out that it can be confusing? > > Still, I would like to know what this is about. Especially since it > > apparently matters for code that involves file-name completion. > > Is there something special about Ido and Icomplete that this should > > single them out for its treatment (whatever that treatment > > might be)? Or does it apply generally to file-name completion code? > > Yes, they perform operations which are non-essential, i.e. > during which we don't want to pester the user. Do you see how backward that sounds? Do we want to pester the user only when s?he is performing _essential_ tasks? The behavior is no doubt consistent, but the terminology is, well, "creative". That's OK, if you explain it clearly. You can call it a "throunbof" task if you like, as long as you say what is meant by that term. > The particular example where it's currently used is: prompt the > user for a password just in order to show > the list of possible completions when the user hasn't even asked for > completion (other than by turning on icomplete or ido which causes > completions to be displayed eagerly). Yes, and that's why I have had it bound to non-nil in Icicles since last May when Michael Albinus informed me about it. And that's why I'm suggesting that we make this feature clear in the doc, for the benefit of other 3rd-party completion libraries (and for users generally). ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 18:51 ` Drew Adams @ 2010-10-28 20:12 ` Stefan Monnier 2010-10-28 21:58 ` Drew Adams ` (2 more replies) 0 siblings, 3 replies; 25+ messages in thread From: Stefan Monnier @ 2010-10-28 20:12 UTC (permalink / raw) To: Drew Adams; +Cc: 7291 >> the answer can be found by using, not the code nor >> the docstring, but: your brain. > Personal insults are really not necessary, Stefan. Honestly, I can't think of any way someone who has the least bit of familiarity with Elisp can wonder "whether `non-essential'=nil or `non-essential'=t means performing a non-essential task (whatever that in turn might mean)". > AFAICT, the _reason_ it is bound there is for Tramp and Tramp alone. No. At most, the problem that triggered the introduction of this was linked to interactions between Tramp and ido/icomplete. So there's a link to Tramp, but it's not there "for Tramp alone". > If some day this var were to have some additional effect, besides > preventing Tramp from reading passwords, then ido.el and icomplete.el > might need to be revisited. No. The whole reason why it has such a docstring and a generic name is so that we can decide whether it's right for icomplete to use it regardless of what Tramp does with it, and similarly we can decide whether it's right for Tramp to use it regardless of where it's bound. > The second change is to state what "non-essential" means here. > It apparently means that the task being performed is so IMPORTANT that > the user should NOT be interrupted (e.g. to read a password). > And that goes somewhat against the usual meaning of "non-essential". That's because you have it backwards: It means that the task being performed is so UNimportant that the user should NOT be interrupted for it. > One could easily suppose that a non-essential task is one that it is > NOT IMPORTANT enough to protect against interruption. Yes, I thought it was so easy to suppose that, that the docstring was understandable. > You seem to be defending the doc as it is only because you wrote it. > It doesn't matter that a user points out that it can be confusing? No, I don't actually defend it. It sucks because I'm bad at it, and I know it. Your bug-report just rubbed me the wrong way: I know I'm bad at it, no need to rub my face in it. "As a longtime professional doc writer" you should be able to provide more constructive criticism, and not only after the Nth email exchange. >> Yes, they perform operations which are non-essential, i.e. >> during which we don't want to pester the user. > Do you see how backward that sounds? No I don't. > Do we want to pester the user only when s?he is performing > _essential_ tasks? We're talking about what the code does, not about what the user does. Stefan ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 20:12 ` Stefan Monnier @ 2010-10-28 21:58 ` Drew Adams 2010-10-29 16:20 ` Stefan Monnier 2010-10-29 8:36 ` Andreas Schwab 2010-10-29 18:56 ` Alan Mackenzie 2 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2010-10-28 21:58 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: 7291 > That's because you have it backwards: > > It means that the task being performed is so UNimportant that > the user should NOT be interrupted for it. And there's the potential confusion. Which task is the "currently executing code" whose task gets characterized as essential or non-essential? It is quite possible to read the doc and think that the "currently executing code" refers to the code that binds this var to non-nil in order to prevent it's own interruption. Now you are suggesting that the "task being performed" is the task that would be _doing_ the interrupting, not the task that would be interrupted. That comes across because you say "interrupted _for_ it" (for the task being performed). That one word makes all the difference - the difference between interrupted "by" some task and interrupted "for" (i.e. to perform) some task. The doc as written allows an interpretation of the "currently performing task" as the task that would (not) be interrupted. It is very easy to think that by "the currently performing task" you mean the currently running Ido or Icomplete code that binds the variable, and not the Tramp task of interrupting and reading the password. But either interpretation is possible; the result is confusion. > > One could easily suppose that a non-essential task is one that it is > > NOT IMPORTANT enough to protect against interruption. > > Yes, I thought it was so easy to suppose that, that the docstring > was understandable. And yet you just said above that "the task being performed is so UNimportant that the user should NOT be interrupted for it". In one case we're talking about the nonimportance of the task that might be interrupted (so no need to prevent interruption). In the other case we're talking about the nonimportance of the interrupting task. The doc string is understandable by some and misunderstandable by others. It is not clear. > > You seem to be defending the doc as it is only because you wrote it. > > It doesn't matter that a user points out that it can be confusing? > > No, I don't actually defend it. It sucks because I'm bad at it, and > I know it. Your bug-report just rubbed me the wrong way: I > know I'm bad at it, no need to rub my face in it. ... you should be > able to provide more constructive criticism, and > not only after the Nth email exchange. No one rubbed your face in it. Please don't be so defensive - it's not about you. If you feel I offended you then I am sorry for that. I did not at first know it was you who wrote this doc, and I really don't care who wrote it. I criticized the doc, not its writer. If I had had to guess, I would have guessed that Michael A. had written the doc string (only because he works on the Tramp code). My only intention was to help so that this doc string gets clarified a bit. That should not be a big deal. You immediately resisted, however, claiming in effect that it was already clear and only an idiot would misunderstand it. As to constructive criticism, my original report suggested that we say explicitly which value (nil or non-nil) means that the code is performing a non-essential task. You resisted that suggestion, for some reason (not given). By my third reply I gave an example in case my meaning wasn't clear: "Non-nil means the currently executing code is performing a non-essential task". Likewise, I pointed out from the beginning the possible confusion over what "non-essential" means and which task was non-essential, and the need to clarify this. > >> Yes, they perform operations which are non-essential, i.e. > >> during which we don't want to pester the user. > > > > Do you see how backward that sounds? > > No I don't. Here, you refer to the Ido and Icomplete code as performing the operations that we don't want to interrupt. ("They" refers to the Ido etc. code, _not_ to the potentially interrupting Tramp code - see the passage you replied to.) So which is it? Is it the Tramp password-reading task that is "so UNimportant that the user should NOT be interrupted for it" (i.e. to perform it). Or is it the Ido and Icomplete code that "performs operations which are non-essential, i.e. during which we don't want to pester the user"? Once you decide that, you can tell the story clearly and easily. What it really comes down to, besides a choice of words, is that both sections of code determine, together, where and whether a task should be skipped, the one by binding the var to non-nil, the other by checking its value and skipping some task if non-nil. I suggest something like the following, if you feel it agrees with the behavior. "Non-nil can prevent some tasks from interrupting the user. Code that might perform a non-essential task can test this variable and dispense with performing the task if the value is non-nil. E.g., Icomplete code binds this to non-nil while gathering a collection of file names. While it is non-nil, Tramp will not read a password to check for any of files that might be remote." HTH. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 21:58 ` Drew Adams @ 2010-10-29 16:20 ` Stefan Monnier 2010-10-29 16:47 ` Drew Adams 0 siblings, 1 reply; 25+ messages in thread From: Stefan Monnier @ 2010-10-29 16:20 UTC (permalink / raw) To: Drew Adams; +Cc: 7291 >> That's because you have it backwards: >> It means that the task being performed is so UNimportant that >> the user should NOT be interrupted for it. > And there's the potential confusion. Which task is the "currently executing > code" whose task gets characterized as essential or non-essential? Elisp is single-threaded, so there is never more than one task at any given time. So I don't understand the question. > It is quite possible to read the doc and think that the "currently > executing code" refers to the code that binds this var to non-nil in > order to prevent it's own interruption. No, the docstring of a variable always describes the meaning of that variable, i.e. "what does it mean for the variable to be set to a particular value". So the code that sets the non-essential variable states that "the code is non-essential" and the code that reads it checks whether it (itself) is non-essential. > Now you are suggesting that the "task being performed" is the task > that would be _doing_ the interrupting, not the task that would be > interrupted. Again, Elisp is single-threaded, so the current code can't interrupt some other. > That comes across because you say "interrupted _for_ it" > (for the task being performed). That one word makes all the > difference - the difference between interrupted "by" some task and > interrupted "for" (i.e. to perform) some task. The docstring says: Whether the currently executing code is performing an essential task. This variable should be non-nil only when running code which should not disturb the user. ... do you also see such a potential confusion there? > The doc as written allows an interpretation of the "currently > performing task" as the task that would (not) be interrupted. It is > very easy to think that by "the currently performing task" As you can see the doc has no such "the currently performing task". >> > One could easily suppose that a non-essential task is one that it is >> > NOT IMPORTANT enough to protect against interruption. >> Yes, I thought it was so easy to suppose that, that the docstring >> was understandable. > And yet you just said above that "the task being performed is so UNimportant > that the user should NOT be interrupted for it". Yes, sorry I didn't read your sentence carefully until the end. > In one case we're talking about the nonimportance of the task that might be > interrupted (so no need to prevent interruption). In the other case we're > talking about the nonimportance of the interrupting task. But the only place where the docstring refers to the word "task" it very clearly refers to "what the currently executing code is doing". And it never uses the word "interrupt" but instead uses "disturb". > "Non-nil can prevent some tasks from interrupting the user. Some of your confusion comes from the word "interrupt", so I'd rather stick to "disturb". > Code that might perform a non-essential task can test this > variable and dispense with performing the task if the value > is non-nil. No, this is backwards: e.g. Tramp doesn't know that what it does is non-essential, which is why it needs to look up non-essential to figure that out. The only reason it does such a look up is not because it suspects this is non-essential, but because it is about to do something that may disturb the user, so it first wants to make sure it is really necessary to do it. Stefan ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 16:20 ` Stefan Monnier @ 2010-10-29 16:47 ` Drew Adams 2010-10-29 17:36 ` Stefan Monnier 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2010-10-29 16:47 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: 7291 > > Code that might perform a non-essential task can test this > > variable and dispense with performing the task if the value > > is non-nil. > > No, this is backwards: e.g. Tramp doesn't know that what it does is > non-essential, Precisely why I said that the task to be performed _might_ be non-essential. Tramp knows that its operation might be disruptive, and it knows that some other code might not want that disruption, and that to communicate that the other code might indicate that the interruption action is "non-essential" (in which case it should be skipped). This variable is about conditionally inhibiting certain actions that could disrupt the user. It would be better for it to be named something that reflects that, but I'm not going to fight that battle. (Consequently, I won't bother to suggest a different name. I'll just say that that is what this var is about - it is not about "non-essential" anything.) > which is why it needs to look up non-essential > to figure that out. And that is why I said that Tramp can test the variable and skip the task if the value indicates non-essential. We are saying the same thing, or trying to. > The only reason it does such a look up is not because it > suspects this is non-essential, but because it is about to do > something that may disturb the user, so it first wants to make > sure it is really necessary to do it. We agree about you wrote in this paragraph (starting with "Tramp doesn't know"). That's just what I tried to say too. So I suggest you put such info into the doc string. I have no objection to your wording here or similar. Both parts of the story need to be presented clearly: (1) the code such as Tramp that conditionally disturbs the user (depending on the var value) and (2) the code such as Icomplete that binds the var during an operation that it does not want interrupted. HTH. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 16:47 ` Drew Adams @ 2010-10-29 17:36 ` Stefan Monnier 0 siblings, 0 replies; 25+ messages in thread From: Stefan Monnier @ 2010-10-29 17:36 UTC (permalink / raw) To: Drew Adams; +Cc: 7291 Other than the "non-nil" part on the first line, I still don't know what's ambiguous about the rest of the current docstring. Your suggested wording sounds largely incomprehensible to me, so while it may be better for some, it's clearly not good enough to replace the current wording. > Both parts of the story need to be presented clearly: (1) the code > such as Tramp that conditionally disturbs the user (depending on the > var value) and (2) the code such as Icomplete that binds the var > during an operation that it does not want interrupted. It's not that icomplete doesn't want an operation to be interrupted, it's that it doesn't want this operation to disturb the user. Stefan ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 20:12 ` Stefan Monnier 2010-10-28 21:58 ` Drew Adams @ 2010-10-29 8:36 ` Andreas Schwab 2010-10-29 16:03 ` Stefan Monnier 2010-10-29 18:56 ` Alan Mackenzie 2 siblings, 1 reply; 25+ messages in thread From: Andreas Schwab @ 2010-10-29 8:36 UTC (permalink / raw) To: Stefan Monnier; +Cc: 7291 Stefan Monnier <monnier@iro.umontreal.ca> writes: > Honestly, I can't think of any way someone who has the least bit of > familiarity with Elisp can wonder "whether `non-essential'=nil or > `non-essential'=t means performing a non-essential task (whatever that > in turn might mean)". The variable is badly named. It should be using a positive form, like allow-whatever. Andreas. -- Andreas Schwab, schwab@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 8:36 ` Andreas Schwab @ 2010-10-29 16:03 ` Stefan Monnier 2010-10-29 16:21 ` Andreas Schwab 2010-10-29 18:29 ` Eli Zaretskii 0 siblings, 2 replies; 25+ messages in thread From: Stefan Monnier @ 2010-10-29 16:03 UTC (permalink / raw) To: Andreas Schwab; +Cc: 7291 >> Honestly, I can't think of any way someone who has the least bit of >> familiarity with Elisp can wonder "whether `non-essential'=nil or >> `non-essential'=t means performing a non-essential task (whatever that >> in turn might mean)". > The variable is badly named. It should be using a positive form, like > allow-whatever. `allow-whatever' does strike me as being any better. Any other suggestion? Stefan ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 16:03 ` Stefan Monnier @ 2010-10-29 16:21 ` Andreas Schwab 2010-10-29 18:29 ` Eli Zaretskii 1 sibling, 0 replies; 25+ messages in thread From: Andreas Schwab @ 2010-10-29 16:21 UTC (permalink / raw) To: Stefan Monnier; +Cc: 7291 Stefan Monnier <monnier@iro.umontreal.ca> writes: >>> Honestly, I can't think of any way someone who has the least bit of >>> familiarity with Elisp can wonder "whether `non-essential'=nil or >>> `non-essential'=t means performing a non-essential task (whatever that >>> in turn might mean)". >> The variable is badly named. It should be using a positive form, like >> allow-whatever. > > `allow-whatever' does strike me as being any better. What's wrong with it? Andreas. -- Andreas Schwab, schwab@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 16:03 ` Stefan Monnier 2010-10-29 16:21 ` Andreas Schwab @ 2010-10-29 18:29 ` Eli Zaretskii 2010-10-29 23:00 ` Andy Moreton 1 sibling, 1 reply; 25+ messages in thread From: Eli Zaretskii @ 2010-10-29 18:29 UTC (permalink / raw) To: Stefan Monnier; +Cc: 7291, schwab > From: Stefan Monnier <monnier@iro.umontreal.ca> > Date: Fri, 29 Oct 2010 12:03:03 -0400 > Cc: 7291@debbugs.gnu.org > > > The variable is badly named. It should be using a positive form, like > > allow-whatever. > > `allow-whatever' does strike me as being any better. > Any other suggestion? suppress-non-essential-prompts? ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 18:29 ` Eli Zaretskii @ 2010-10-29 23:00 ` Andy Moreton 2010-10-30 6:52 ` Eli Zaretskii 0 siblings, 1 reply; 25+ messages in thread From: Andy Moreton @ 2010-10-29 23:00 UTC (permalink / raw) To: bug-gnu-emacs On Fri 29 Oct 2010, Eli Zaretskii wrote: >> From: Stefan Monnier <monnier@iro.umontreal.ca> >> Date: Fri, 29 Oct 2010 12:03:03 -0400 >> Cc: 7291@debbugs.gnu.org >> >> > The variable is badly named. It should be using a positive form, like >> > allow-whatever. >> >> `allow-whatever' does strike me as being any better. >> Any other suggestion? > > suppress-non-essential-prompts? allow-user-interaction ? ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-29 23:00 ` Andy Moreton @ 2010-10-30 6:52 ` Eli Zaretskii 2010-10-30 16:16 ` Drew Adams 0 siblings, 1 reply; 25+ messages in thread From: Eli Zaretskii @ 2010-10-30 6:52 UTC (permalink / raw) To: Andy Moreton; +Cc: bug-gnu-emacs > From: Andy Moreton <andrewjmoreton@gmail.com> > Date: Sat, 30 Oct 2010 00:00:33 +0100 > Cc: > > On Fri 29 Oct 2010, Eli Zaretskii wrote: > > >> From: Stefan Monnier <monnier@iro.umontreal.ca> > >> Date: Fri, 29 Oct 2010 12:03:03 -0400 > >> Cc: 7291@debbugs.gnu.org > >> > >> > The variable is badly named. It should be using a positive form, like > >> > allow-whatever. > >> > >> `allow-whatever' does strike me as being any better. > >> Any other suggestion? > > > > suppress-non-essential-prompts? > > allow-user-interaction ? "User interaction" is too general, IMO. Almost as general as the original name, which is one of the reasons for this bug report. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-30 6:52 ` Eli Zaretskii @ 2010-10-30 16:16 ` Drew Adams 2010-10-30 17:53 ` Michael Albinus 0 siblings, 1 reply; 25+ messages in thread From: Drew Adams @ 2010-10-30 16:16 UTC (permalink / raw) To: 'Eli Zaretskii', 'Andy Moreton'; +Cc: bug-gnu-emacs > > >> > The variable is badly named. It should be using a > > >> > positive form, like allow-whatever. > > >> > > >> `allow-whatever' does [NOT?] strike me as being any better. > > >> Any other suggestion? > > > > > > suppress-non-essential-prompts? > > > > allow-user-interaction ? > > "User interaction" is too general, IMO. Almost as general as the > original name, which is one of the reasons for this bug report. Stefan wants it to be general. He says it is not necessarily about Tramp or prompting or even interupting the user. It is about "disturbing" the user. --- One last attempt to get past the mauvaise foi... This var is a `PLEASE DO NOT DISTURB' sign for the user's hotel room. Nothing prevents firemen from entering. Maids know that their services are not important enough to ignore a do-not-disturb | no-molestar | ne-pas-deranger | nao-perturbe | non-disturbare request. This knowledge is built into their code. Firemen do not even notice the sign. Maids actively keep an eye out for it - that's part of their job. The user is a tempermental, often drunk&drugged musician who has a manager. The manager code hangs the sign on the door when appropriate. The maid code recognizes the sign and is polite enough not to enter to perform routine housekeeping. Icomplete is a musician manager. Tramp is a hotel maid. (defvar do-not-disturb nil "Non-nil is a sign to avoid disturbing the user. Code that performs a relatively unimportant action that might disturb the user can check this variable and choose not to act when it is non-nil. Code that wants to make other code aware that it might not be good to disturb the user now unnecessarily can bind this to non-nil. Example: Icomplete binds this to non-nil when collecting file names as completion candidates. Tramp checks the value before attempting to read a password for a remote file name: if non-nil then it does no password prompting.") --- Next week we will discuss room service. This code looks for the `do-not-disturb' sign, but it also checks the particular non-nil value for the advisory level. If it sees `this-means-YOU-too' or a list value that includes item `room-service' then it does not even think about knocking, let alone entering. The week after next we will study Homeland Security Advisory System threat levels: `severe', `high', `significant', `general', and `low'. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-30 16:16 ` Drew Adams @ 2010-10-30 17:53 ` Michael Albinus 2010-10-30 20:05 ` Drew Adams 0 siblings, 1 reply; 25+ messages in thread From: Michael Albinus @ 2010-10-30 17:53 UTC (permalink / raw) To: Drew Adams; +Cc: 'Andy Moreton', bug-gnu-emacs "Drew Adams" <drew.adams@oracle.com> writes: > One last attempt to get past the mauvaise foi... > > This var is a `PLEASE DO NOT DISTURB' sign for the user's hotel > room. > > Nothing prevents firemen from entering. Maids know that their > services are not important enough to ignore a do-not-disturb | > no-molestar | ne-pas-deranger | nao-perturbe | non-disturbare > request. This knowledge is built into their code. > > Firemen do not even notice the sign. Maids actively keep an > eye out for it - that's part of their job. > > The user is a tempermental, often drunk&drugged musician who > has a manager. The manager code hangs the sign on the door > when appropriate. The maid code recognizes the sign and is > polite enough not to enter to perform routine housekeeping. > > Icomplete is a musician manager. Tramp is a hotel maid. I insist in being informed in German. "Bitte nicht stören". Otherwise, I do whatever I want to do. > (defvar do-not-disturb nil > "Non-nil is a sign to avoid disturbing the user. > Code that performs a relatively unimportant action that might > disturb the user can check this variable and choose not to act > when it is non-nil. It is not about "disturbing". If non-essential^W^W do-not-disturb is non-nil, Tramp does not open a remote connection. That's all until now, and that's the reason I have asked for this kind of variable. > The week after next we will study Homeland Security Advisory System > threat levels: `severe', `high', `significant', `general', and `low'. Oh, surprise. I thought there's only the threat level `severe'. Best regards, Michael. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-30 17:53 ` Michael Albinus @ 2010-10-30 20:05 ` Drew Adams 0 siblings, 0 replies; 25+ messages in thread From: Drew Adams @ 2010-10-30 20:05 UTC (permalink / raw) To: 'Michael Albinus'; +Cc: 'Andy Moreton', bug-gnu-emacs > > do-not-disturb | no-molestar | ne-pas-deranger | > > nao-perturbe | non-disturbare > > I insist in being informed in German. "Bitte nicht stören". > Otherwise, I do whatever I want to do. ;-) > > (defvar do-not-disturb nil > > "Non-nil is a sign to avoid disturbing the user. > > Code that performs a relatively unimportant action that might > > disturb the user can check this variable and choose not to act > > when it is non-nil. > > It is not about "disturbing". If non-essential^W^W do-not-disturb is > non-nil, Tramp does not open a remote connection. That's all > until now, and that's the reason I have asked for this kind of variable. I understand. And in practice, today, objectively, this is used only by Tramp (bound by Ido and Icomplete, handled by Tramp). But Stefan has been clear that he wants this to be something more general: not necessarily about Tramp, not necessarily about remote connection, not necessarily about password-prompting, not necessarily about interrupting the user,... He wants this to be something so general that its intention is recorded only in terms of "disturbing the user". That's his point, not mine. I just tried to follow up with a name and description that supports that intention. To reflect what you say and just the current situation, the name would instead speak about Tramp not accessing remote files, not opening a remote connection, not prompting for a password, or some such. But that is not Stefan's intention for this variable, AFAICT. Whatever gets done about this bug (probably nothing, if I had to guess), I would like to see the doc let developers of code involving file names - in particular, completion of possibly remote file names, know that they can bind this to non-nil to prevent Tramp from opening a remote connection and possibly prompting for a password. That's the most important use case, _for now_ at least. I thank you for letting me know about this var for Icicles. My point in filing the bug was to have the doc let others who write file-name completion code know also. I also thought that the var name and description could be made a bit clearer. > > The week after next we will study Homeland Security Advisory System > > threat levels: `severe', `high', `significant', `general', > > and `low'. > > Oh, surprise. I thought there's only the threat level `severe'. ;-) ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 20:12 ` Stefan Monnier 2010-10-28 21:58 ` Drew Adams 2010-10-29 8:36 ` Andreas Schwab @ 2010-10-29 18:56 ` Alan Mackenzie 2 siblings, 0 replies; 25+ messages in thread From: Alan Mackenzie @ 2010-10-29 18:56 UTC (permalink / raw) To: Stefan Monnier; +Cc: 7291 Hi, Stefan! On Thu, Oct 28, 2010 at 04:12:16PM -0400, Stefan Monnier wrote: > Honestly, I can't think of any way someone who has the least bit of > familiarity with Elisp can wonder "whether `non-essential'=nil or > `non-essential'=t means performing a non-essential task (whatever that > in turn might mean)". Me. How should I get the notion of "task" from the logically incomplete phrase "non-essential? Please change the name of this variable to say what it means. "Non-essential" is way, way too abstract (in the sense of woolly, meaningless). I write the following as a native English speaker. The word "essential" describes a _RELATIONSHIP_ between _TWO_ nouns: A is essential to B if B without A wouldn't be B at all. For example, an extension language is essential to Emacs (?Emacs without an extension language?), and love is essential to a marriage (?a marriage without love?). To say that something is "essential" is like saying something is "better". Lacking the other noun (possibly implied), it's meaningless. The variable name "non-essential" is meaningless. The doc string helps a little, but not enough. It doesn't say what the task being executed is essential _to_. What would not be what it is to be, were the "essential task" to be missing? Such vagueness and linguistic misuse causes not only puzzlement, but also anger, revulsion and contempt. Please rename the variable to say what it means. Thanks! > Stefan -- Alan Mackenzie (Nuremberg, Germany). ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-27 22:30 bug#7291: 24.0.50; `non-essential' is incomprehensible Drew Adams 2010-10-28 0:52 ` Stefan Monnier @ 2010-10-28 17:33 ` James Cloos 2010-10-28 18:53 ` Drew Adams 2011-07-14 14:35 ` Lars Magne Ingebrigtsen 2010-10-31 2:34 ` MON KEY 2 siblings, 2 replies; 25+ messages in thread From: James Cloos @ 2010-10-28 17:33 UTC (permalink / raw) To: Drew Adams; +Cc: 7291 >>>>> "DA" == Drew Adams <drew.adams@oracle.com> writes: DA> Variable `non-essential' was introduced in Emacs 24. DA> The name is bad - doesn't say anything. Non-essential wrt what? DA> The doc is bad: DA> "Whether the currently executing code is performing an essential DA> task. This variable should be non-nil only when running code which DA> should not disturb the user. E.g. it can be used to prevent Tramp DA> from prompting the user for a password when we are simply scanning a DA> set of files in the background or displaying possible completions DA> before the user even asked for it." [Just translating between english and english here -JimC] Seems clear here. If the variable is nil tramp will be happy to do user-interactive stuff, such as prompting the user for a password. But tramp would prefer that the variable be set to non-nil in any function which does remote work which will not require such user- interaction. DA> So does nil mean the code is performing an essential task? Or does DA> non-nil mean that? What's an "essential task"? A task that should DA> disturb the user (because it is important) or a task that should not DA> disturb the user? I think you are thinking about it the wrong way -- or at least sufficiently differently than the authors as to fail to see their meaning. (Please do not take that as a flame.) Don't think "importance" but rather "will this require user interaction to succeed?". And set to nil if it will require user interaction to succeed. -JimC -- James Cloos <cloos@jhcloos.com> OpenPGP: 1024D/ED7DAEA6 ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 17:33 ` James Cloos @ 2010-10-28 18:53 ` Drew Adams 2011-07-14 14:35 ` Lars Magne Ingebrigtsen 1 sibling, 0 replies; 25+ messages in thread From: Drew Adams @ 2010-10-28 18:53 UTC (permalink / raw) To: 'James Cloos'; +Cc: 7291 > Seems clear here. If the variable is nil tramp will be happy to do > user-interactive stuff, such as prompting the user for a password. Which means that the task that was interrupted was "essential"? Can you imagine that a reader might think that an "essential" task would be one that you do NOT want interrupted, not the opposite? > But tramp would prefer that the variable be set to non-nil in any > function which does remote work which will not require such user- > interaction. Actually, it is set to non-nil in functions that are NOT (yet) doing any remote work, functions that (so far) just want to gather a list of possible file names (for completion), whether the files are remote or not. The idea is that the user should be prompted for a password only when s?he actually tries to visit the remote file (real access). > I think you are thinking about it the wrong way -- or at least > sufficiently differently than the authors as to fail to see their > meaning. No, I get the author's meaning. My point is that some readers will not. The doc as written lends itself easily to confusion. It is not the author's meaning that is in question here, but how that meaning is communicated. > Don't think "importance" but rather "will this require user > interaction to succeed?". If we have to tell readers how to think when they try to read the explanation, in particular that "essential" does not mean "important" (and what does that mean?), then the doc could benefit from clarification. To write clear doc one needs to look for ways that readers might interpret differently what is said, giving them an understanding that does not match what was meant. Writing doc is similar to writing a spec: if an alternate model also fits, then the spec is too loose. > And set to nil if it will require user interaction to succeed. What does "it succeeds" mean in this context? Stefan makes the point that this is something general, it's not just about password reading. If so, then the explanation needs to make sense at that level. ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-28 17:33 ` James Cloos 2010-10-28 18:53 ` Drew Adams @ 2011-07-14 14:35 ` Lars Magne Ingebrigtsen 1 sibling, 0 replies; 25+ messages in thread From: Lars Magne Ingebrigtsen @ 2011-07-14 14:35 UTC (permalink / raw) To: James Cloos; +Cc: 7291 James Cloos <cloos@jhcloos.com> writes: > Seems clear here. I think the rough consensus here is that the doc string is clear enough as it is. Closing the report. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ ^ permalink raw reply [flat|nested] 25+ messages in thread
* bug#7291: 24.0.50; `non-essential' is incomprehensible 2010-10-27 22:30 bug#7291: 24.0.50; `non-essential' is incomprehensible Drew Adams 2010-10-28 0:52 ` Stefan Monnier 2010-10-28 17:33 ` James Cloos @ 2010-10-31 2:34 ` MON KEY 2 siblings, 0 replies; 25+ messages in thread From: MON KEY @ 2010-10-31 2:34 UTC (permalink / raw) To: 7291 >> allow-user-interaction ? > "User interaction" is too general, IMO. Almost as general as the > original name, which is one of the reasons for this bug report. can-do-interactive can-do-allowed ok-to-disturb can-do-disturb can-disturb-user permit-to-tickle-cthulu <- Personal Favorite :) -- /s_P\ ^ permalink raw reply [flat|nested] 25+ messages in thread
end of thread, other threads:[~2011-07-14 14:35 UTC | newest] Thread overview: 25+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2010-10-27 22:30 bug#7291: 24.0.50; `non-essential' is incomprehensible Drew Adams 2010-10-28 0:52 ` Stefan Monnier 2010-10-28 16:22 ` Drew Adams 2010-10-28 17:14 ` Stefan Monnier 2010-10-28 18:43 ` Michael Albinus 2010-10-28 18:51 ` Drew Adams 2010-10-28 20:12 ` Stefan Monnier 2010-10-28 21:58 ` Drew Adams 2010-10-29 16:20 ` Stefan Monnier 2010-10-29 16:47 ` Drew Adams 2010-10-29 17:36 ` Stefan Monnier 2010-10-29 8:36 ` Andreas Schwab 2010-10-29 16:03 ` Stefan Monnier 2010-10-29 16:21 ` Andreas Schwab 2010-10-29 18:29 ` Eli Zaretskii 2010-10-29 23:00 ` Andy Moreton 2010-10-30 6:52 ` Eli Zaretskii 2010-10-30 16:16 ` Drew Adams 2010-10-30 17:53 ` Michael Albinus 2010-10-30 20:05 ` Drew Adams 2010-10-29 18:56 ` Alan Mackenzie 2010-10-28 17:33 ` James Cloos 2010-10-28 18:53 ` Drew Adams 2011-07-14 14:35 ` Lars Magne Ingebrigtsen 2010-10-31 2:34 ` MON KEY
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).