From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Marius Vollmer Newsgroups: gmane.lisp.guile.devel Subject: Re: Improving the help interface Date: Mon, 09 Aug 2004 22:47:12 +0200 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <878yco11kf.fsf@zagadka.ping.de> References: <1083942714.953.427.camel@localhost> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1092084485 17942 80.91.224.253 (9 Aug 2004 20:48:05 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 9 Aug 2004 20:48:05 +0000 (UTC) Cc: guile-devel Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Aug 09 22:47:58 2004 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BuH3m-0004GB-00 for ; Mon, 09 Aug 2004 22:47:58 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BuH7X-0002rk-D9 for guile-devel@m.gmane.org; Mon, 09 Aug 2004 16:51:51 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1BuH7J-0002lR-Sm for guile-devel@gnu.org; Mon, 09 Aug 2004 16:51:38 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1BuH7H-0002kR-Tn for guile-devel@gnu.org; Mon, 09 Aug 2004 16:51:36 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BuH7H-0002jv-HL for guile-devel@gnu.org; Mon, 09 Aug 2004 16:51:35 -0400 Original-Received: from [195.253.8.218] (helo=mail.dokom.net) by monty-python.gnu.org with esmtp (Exim 4.34) id 1BuH39-00060Y-Sh for guile-devel@gnu.org; Mon, 09 Aug 2004 16:47:20 -0400 Original-Received: from [195.138.45.200] (helo=zagadka.ping.de) by mail.dokom.net with smtp (Exim 4.34) id 1BuH37-000086-PF for guile-devel@gnu.org; Mon, 09 Aug 2004 22:47:18 +0200 Original-Received: (qmail 6766 invoked by uid 1000); 9 Aug 2004 20:47:12 -0000 Original-To: Andy Wingo In-Reply-To: <1083942714.953.427.camel@localhost> (Andy Wingo's message of "Fri, 07 May 2004 16:11:56 +0100") User-Agent: Gnus/5.1006 (Gnus v5.10.6) Emacs/21.3 (gnu/linux) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:3924 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:3924 Andy Wingo writes: > I've been working a bit on the (help ...) interface. I'll explain why > changes are needed, and what my proposed solution does. Thanks, and sorry for the late answer. (I have now organized my mail better so that I can reply from wherever I am, that should help a bit...) > [0] Pretty nifty screenshot: > http://ambient.2y.net/soundscrape/shots/17-dec-2003.png Cool! > The attached patch implements "value help handlers" (as opposed to the > former "variable help handlers" or such). A value help handler is a proc > that takes a value. If it returns #f, help keeps looking for > documentation, perhaps falling back on its normal behavior. If it > returns a string, that string is taken to be its help. If it returns #t, > it means that the help has been handled in some other way (graphically, > perhaps), and `help' has nothing else to do. I think it is better to separate the action of retrieving the help text for some feature (value, variable, etc), and the action of displaying it. Thus, a help-value-handler handler should not display the help itself, it should just retrieve it. Different ways of displaying help can be implemented by different versions of 'help', say. > Value help handlers are added with `add-value-help-handler!', and > removed in a similar way. What about using Goops for this? First, it would suffice to only talk about 'the helpstring for a value': variables, procedures, macros etc are all values. Then there would be two levels of dispatching, I'd say: first on the type of the value, and the default method for that is to ask a list of 'help sources' with a second generic function. Like this, maybe: (define-generic help-for-value) (define-generic help-from-source) (define help-sources ...) (define-method (help-for-value (val )) ...get it from the gtk docs, say...) (define-method (help-for-value val) (find-if help-from-source help-sources)) (define-method (help-from-source (src )) ..use documentation-files ...) > Thoughts? I'd like this in sometime soon. In the meantime I'm > throwing it in my branch of guile-lib, with handlers for texinfo and > stext in (text structured help). As long as you can cleanly do this, I would prefer not to change the guile help system in small ways. I think we should first write a comprehensive documentation for it "This is how the Guile Help System Should Work" and then implement it insofar as it differs from what we have now. -- GPG: D5D4E405 - 2F9B BCCC 8527 692A 04E3 331E FAF8 226A D5D4 E405 _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://lists.gnu.org/mailman/listinfo/guile-devel