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

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

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