bug#7291: 24.0.50; `non-essential' is incomprehensible

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

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'
 

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Stefan Monnier]

> 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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> > 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?

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Stefan Monnier]

>> > 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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Michael Albinus]

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.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> 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).

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Stefan Monnier]

>> 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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> 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.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Stefan Monnier]

>> 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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> >  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.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Stefan Monnier]

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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Andreas Schwab]

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."

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Stefan Monnier]

>> 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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Andreas Schwab]

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."

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Eli Zaretskii]

> 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?

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Andy Moreton]

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 ? 

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Eli Zaretskii]

> 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.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> > >> > 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'.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Michael Albinus]

"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.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> > 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'.

;-)

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Alan Mackenzie]

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).

bug#7291: 24.0.50; `non-essential' is incomprehensible

[James Cloos]

>>>>> "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

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Drew Adams]

> 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.

bug#7291: 24.0.50; `non-essential' is incomprehensible

[Lars Magne Ingebrigtsen]

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/

bug#7291: 24.0.50; `non-essential' is incomprehensible

[MON KEY]

>> 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\