Re: PATCH: improvement to user@host completions

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxxxxxxxxx>]

On Sep 26,  5:02pm, Peter Stephenson wrote:
} Subject: Re: PATCH: improvement to user@host completions
}
} This is an excellent idea, but it could do with some documentation.
} Currently that just means comments in the appropriate functions.
} 
} However (long digresion), in the long run I'm hoping for some
} context-sensitive help.  Something like _description would be used to add
} it.

I faced a similar problem when I was working on Z-Mail:  Functions written
in the "Z-Script" language could be attached to GUI elements like buttons
or menus; the Motif UI spec says that if the mouse is over such an element
when the user presses F1, he's supposed to get context-sensitive help.

The Z-Mail builtins all accept -? to display a usage message, so the most
obvious thing to do for context help was to run the command with -? and
display the output in a help dialog.  The -? argument was implemented by
intercepting it at the equivalent of zsh's exec.c:execcmd() and branching
into the help code, which did a lookup on the command name.  It was simple
to do the same for user functions.

So then we needed a way to get the help text for the function into the
help system, without actually running the function.  So we implemented a
special comment syntax:  If the function definition began with a block
comment, and that comment contained a line beginning with #%, then the
rest of the comment up to the next #% line was the help text.  This got
stashed in the help system when the function was parsed.  Any function
that did not have such a comment got a default "FOO is a user-defined
function ..." message.

This scheme had the additional good side-effect of encouraging people to
put readable descriptions of their functions at the top of each.

Of course this won't quite work for the completion system because of the
way _main_complete et al select other functions to do the actual work.  A
possible approach might be to set a global flag that means "we're getting
help, not performing actual completion" and then run the functions for the
current context as usual -- but whenever a match would be added, the help
text (previously collected) for that function (or the nearest surrounding
one) gets added instead.

This would omit (fail to emit) the help text for any function in which no
completion is currently found, but that may not be a bad thing.  Are there
any interesting cases in which a completion function is called if and only
if some previous function DID find some matches?

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com