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

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

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'