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

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

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