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

[Phil Sainty]

On 14/10/19 5:46 PM, Drew Adams wrote:
> 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)
=> completion-at-point-functions (list)
=> comint-completion-at-point (function)
=> comint-dynamic-complete-functions (for me, a list of seven
   possiblities)
=> pcomplete-completions-at-point (function "using pcomplete's
   completion tables", however one establishes what that means --
   certainly not in the elisp manual; AFAICS the pcomplete.el
   Commentary and code would need to be consulted)
=> pcomplete-completions (function which examines the buffer and
   employs various logic to figure out the appropriate completion
   function)
=> pcomplete/ssh (function)
=> pcmpl-ssh-hosts (function which actually does the thing)

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


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


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

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.


-Phil