bug#9134: don't force mystery on user trying to find out what is completing after the word "ssh" in *shell*

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

> > Doesn't the command performing the completion know this
> > information?  Why isn't it sufficient for `C-h f' for that
> > command to provide the info?  I'd think that if it's not
> > obvious the command's doc should let you know what things
> > you're completing against.
> 
> Well, that can go through a LOT of indirection, so tracking down
> the actual source isn't that simple.  Here we have:
> 
> TAB => completion-at-point (command)

Oh, yes, of course.  I didn't realize that this
was about `completion-at-point' instead of just
`completing-read'.

Yes, that's (ahem) a mess.  Maybe a useful mess,
but more or less a mess (IMHO).

> And frankly I only figured that out by working backwards, after
> grepping the code base for "known_hosts", setting debug-on-entry
> for `pcmpl-ssh-hosts', and then hitting TAB and finding how it
> actually arrived there.
> 
> That's in no way simple to follow, even if the docstrings made
> everything really clear (which they do not; and possibly can't,
> given the involvement of "programmable completion" in the mix).

Indeed.  Not such a self-documenting editor, in
this regard.

> As a side note, has it always been the case that, when asking
> about a variable with a buffer-local value, if you follow links
> in that *Help* buffer to other variables which also have
> buffer-local values in the original buffer, you'll only see the
> global values (because you're now local to the *Help* buffer)?
> I feel like it would be nice if the *Help* remained local to the
> same buffer for as long as you remained in the *Help* window.
> (For some reason this caught me out, but I'm probably inventing
> the idea that it used to be different.)

Dunno.  Maybe give a complete recipe and I'll
check on older releases.

> > A priori, I don't think the info should be shown via a
> > transitory message or by putting an explanation in buffer
> > *Completions*.
> 
> On reflection I agree that my suggestion wasn't a great idea; but
> I also don't think it's remotely practical to say that command
> documentation should be sufficient, when we're trawling through
> so many layers.

I agree.  I misguessed that this was only about
completion from things like `completing-read' and
`read-file-name'.

> What would perhaps be nice is for the *actual* sequence of events
> to be tracked internally, and reported on request, so that the
> user could ask "where did the completion(s) actually come from?"
> and be told the answer.

+1