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

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

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