From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3928 invoked from network); 26 Sep 1999 16:57:28 -0000 Received: from sunsite.auc.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 26 Sep 1999 16:57:28 -0000 Received: (qmail 12689 invoked by alias); 26 Sep 1999 16:57:20 -0000 Mailing-List: contact zsh-workers-help@sunsite.auc.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 8053 Received: (qmail 12682 invoked from network); 26 Sep 1999 16:57:17 -0000 From: "Bart Schaefer" Message-Id: <990926165712.ZM4999@candle.brasslantern.com> Date: Sun, 26 Sep 1999 16:57:12 +0000 In-Reply-To: <9909261502.AA30070@ibmth.df.unipi.it> Comments: In reply to Peter Stephenson "Re: PATCH: improvement to user@host completions" (Sep 26, 5:02pm) References: <9909261502.AA30070@ibmth.df.unipi.it> X-Mailer: Z-Mail (5.0.0 30July97) To: zsh workers mailing list Subject: Re: PATCH: improvement to user@host completions MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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