From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.devel Subject: Re: Improving the help interface Date: Sun, 15 Aug 2004 12:41:28 +0100 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <20040815114128.GL27040@lark> References: <1083942714.953.427.camel@localhost> <877js811ju.fsf@zagadka.ping.de> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1092578337 28989 80.91.224.253 (15 Aug 2004 13:58:57 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 15 Aug 2004 13:58:57 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sun Aug 15 15:58:49 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 1BwLX7-0004Mq-00 for ; Sun, 15 Aug 2004 15:58:49 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BwLbA-0005Zg-IA for guile-devel@m.gmane.org; Sun, 15 Aug 2004 10:03:00 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.33) id 1BwLb3-0005Za-MZ for guile-devel@gnu.org; Sun, 15 Aug 2004 10:02:53 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.33) id 1BwLb3-0005ZO-5O for guile-devel@gnu.org; Sun, 15 Aug 2004 10:02:53 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.33) id 1BwLb3-0005ZL-3J for guile-devel@gnu.org; Sun, 15 Aug 2004 10:02:53 -0400 Original-Received: from [216.166.232.203] (helo=johnson-resources.com) by monty-python.gnu.org with esmtp (TLSv1:DES-CBC3-SHA:168) (Exim 4.34) id 1BwLWd-0002ZK-Ae for guile-devel@gnu.org; Sun, 15 Aug 2004 09:58:19 -0400 Original-Received: from localhost (mantis.schoolnet.na [::ffff:196.44.140.238]) (AUTH: LOGIN wingo) by johnson-resources.com with esmtp; Sun, 15 Aug 2004 09:58:19 -0400 id 001201C3.411F6BFC.00007AF9 Original-Received: from wingo by localhost with local (Exim 3.36 #1 (Debian)) id 1BwJOW-0007E8-00 for ; Sun, 15 Aug 2004 12:41:48 +0100 Original-To: guile-devel Mail-Followup-To: guile-devel Content-Disposition: inline In-Reply-To: <877js811ju.fsf@zagadka.ping.de> X-Operating-System: Linux lark 2.4.20-1-686 User-Agent: Mutt/1.5.6+20040803i 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:3949 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:3949 Hi Marius, Glad to hear you have improved your email setup ;-) On Mon, 09 Aug 2004, Marius Vollmer wrote: > Andy Wingo writes: > > > 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. Hm. I agree, and also disagree ;) The only issue is the format for the help. For some objects, help can be generated at runtime. It would be a bit of a pain to render this semantic documentation to some kind of serialization, e.g. as XML or texinfo, if it already exists in a native scheme format, e.g SXML or stexinfo. Having plain text as a bottleneck between retrieval and display would not be helpful[0]. If we allow the help "text" to be of any value type (as is the case now), this would not be a problem. As you mention, GOOPS could assist with this. [0] Ha! I'm punny. > 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 ...) Obviously this is a better solution ;) Would you mind autoloading GOOPS when `help' is called? [I've grown a bit wary of the object-orientation-everywhere tendency, but this seems to be a valid application.] > > 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. Sounds good. I was being a bit more timid, but as maintainer you were already thinking broadly. I'll see about writing something and send it to the list. Regards, -- Andy Wingo http://ambient.2y.net/wingo/ _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://lists.gnu.org/mailman/listinfo/guile-devel