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

["Drew Adams" <drew.adams@oracle.com>]

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