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: Improving the help interface Date: Fri, 07 May 2004 16:11:56 +0100 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <1083942714.953.427.camel@localhost> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=_fridge-12479-1084027833-0001-2" X-Trace: sea.gmane.org 1084028242 4723 80.91.224.253 (8 May 2004 14:57:22 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 8 May 2004 14:57:22 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sat May 08 16:57:13 2004 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1BMTGK-0005d5-01 for ; Sat, 08 May 2004 16:57:12 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.33) id 1BMTAt-0001gn-MX for guile-devel@m.gmane.org; Sat, 08 May 2004 10:51:35 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.33) id 1BMTAW-0001gY-HU for guile-devel@gnu.org; Sat, 08 May 2004 10:51:12 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.33) id 1BMTA0-0001a7-FB for guile-devel@gnu.org; Sat, 08 May 2004 10:51:11 -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.33) id 1BMT9z-0001Zp-U4 for guile-devel@gnu.org; Sat, 08 May 2004 10:50:40 -0400 Original-Received: from localhost (mantis.schoolnet.na [::ffff:196.44.140.238]) (AUTH: LOGIN wingo) by johnson-resources.com with esmtp; Sat, 08 May 2004 10:50:27 -0400 Original-Received: from wingo by localhost with local (Exim 3.36 #1 (Debian)) id 1BM712-00033X-00 for ; Fri, 07 May 2004 16:11:57 +0100 Original-To: guile-devel X-Mailer: Ximian Evolution 1.4.4 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.4 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:3684 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:3684 This is a MIME-formatted message. If you see this text it means that your E-mail software does not support MIME-formatted messages. --=_fridge-12479-1084027833-0001-2 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 7bit Hey folks, I've been working a bit on the (help ...) interface. I'll explain why changes are needed, and what my proposed solution does. I have an app that has a command-line interface and a graphical interface. The graphical interface has a repl in it, as well as some other things. One part of the graphical interface is a help browser[0]. It's a traditional tree-on-left, docs-on-right browser that can import texinfo. In addition to that, it can show help for modules by putting the commentary (which can have texinfo markup) on top, and individual help for variables, functions, etc following that. The object-documentation of the variables can be normal text, texinfo, or my own ghetto sexp markup, which is nice for programmatic doc construction. [0] Pretty nifty screenshot: http://ambient.2y.net/soundscrape/shots/17-dec-2003.png The problem is that you want (help myvar) to show text in the command-line mode, and to open the help window to the appropriate node in graphical mode. It might need to convert the object-documentation to normal text for the command-line mode. Furthermore, particular packages might have their own ways of documenting things; GOOPS objects should be documented using `describe', for instance. In conclusion, the help system needs points of extensibility. There are two points at which customization would be nice: processing the unevaluated input to `help', and documenting a value (found in a module, for instance). This patch deals with the latter point. 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. Value help handlers are added with `add-value-help-handler!', and removed in a similar way. 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). This mechanism could be a way to enable more literate programming, with the docstrings for scheme code already marked up as texinfo, and presented in whatever format is appropriate. At least, that's what I do with it. ps. It's small, but I don't have papers in for Guile. -- Andy Wingo --=_fridge-12479-1084027833-0001-2 Content-Type: text/x-patch; name="session.scm.diff"; charset=iso-8859-1 Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename=session.scm.diff LS0tIHNyYy9zY2hlbWUvc2Vzc2lvbi5zY20JMjAwNC0wNS0wNyAxNDo1MDoyMy4wMDAwMDAwMDAg KzAxMDANCisrKyAvdXNyL3NoYXJlL2d1aWxlLzEuNi9pY2UtOS9zZXNzaW9uLnNjbQkyMDAzLTA4 LTI5IDIxOjI2OjE1LjAwMDAwMDAwMCArMDEwMA0KQEAgLTEsNCArMSw0IEBADQotOzs7OyAJQ29w eXJpZ2h0IChDKSAxOTk3LCAyMDAwLCAyMDAxLCAyMDA0IEZyZWUgU29mdHdhcmUgRm91bmRhdGlv biwgSW5jLg0KKzs7OzsgCUNvcHlyaWdodCAoQykgMTk5NywgMjAwMCwgMjAwMSBGcmVlIFNvZnR3 YXJlIEZvdW5kYXRpb24sIEluYy4NCiA7Ozs7DQogOzs7OyBUaGlzIHByb2dyYW0gaXMgZnJlZSBz b2Z0d2FyZTsgeW91IGNhbiByZWRpc3RyaWJ1dGUgaXQgYW5kL29yIG1vZGlmeQ0KIDs7OzsgaXQg dW5kZXIgdGhlIHRlcm1zIG9mIHRoZSBHTlUgR2VuZXJhbCBQdWJsaWMgTGljZW5zZSBhcyBwdWJs aXNoZWQgYnkNCkBAIC00NSwzNSArNDUsMTIgQEANCiAgIDp1c2UtbW9kdWxlIChpY2UtOSBkb2N1 bWVudGF0aW9uKQ0KICAgOnVzZS1tb2R1bGUgKGljZS05IHJlZ2V4KQ0KICAgOnVzZS1tb2R1bGUg KGljZS05IHJkZWxpbSkNCi0gIDpleHBvcnQgKGhlbHAgYWRkLXZhbHVlLWhlbHAtaGFuZGxlciEg cmVtb3ZlLXZhbHVlLWhlbHAtaGFuZGxlciENCi0gICAgICAgICAgIGFwcm9wb3MgYXByb3Bvcy1p bnRlcm5hbCBhcHJvcG9zLWZvbGQgYXByb3Bvcy1mb2xkLWFjY2Vzc2libGUNCi0gICAgICAgICAg IGFwcm9wb3MtZm9sZC1leHBvcnRlZCBhcHJvcG9zLWZvbGQtYWxsIHNvdXJjZSBhcml0eQ0KLSAg ICAgICAgICAgc3lzdGVtLW1vZHVsZSkpDQorICA6ZXhwb3J0IChoZWxwIGFwcm9wb3MgYXByb3Bv cy1pbnRlcm5hbCBhcHJvcG9zLWZvbGQNCisJICAgYXByb3Bvcy1mb2xkLWFjY2Vzc2libGUgYXBy b3Bvcy1mb2xkLWV4cG9ydGVkIGFwcm9wb3MtZm9sZC1hbGwNCisJICAgc291cmNlIGFyaXR5IHN5 c3RlbS1tb2R1bGUpKQ0KIA0KIAwNCiANCi0oZGVmaW5lICp2YWx1ZS1oZWxwLWhhbmRsZXJzKiAn KCkpDQotDQotKGRlZmluZSAoYWRkLXZhbHVlLWhlbHAtaGFuZGxlciEgcHJvYykNCi0gICJBZGRz IGEgaGFuZGxlciBmb3IgcGVyZm9ybWluZyBgaGVscCcgb24gYSB2YWx1ZS4NCi0NCi1gcHJvYycg d2lsbCBiZSBjYWxsZWQgd2l0aCB0aGUgdmFsdWUgYXMgYW4gYXJndW1lbnQuIGBwcm9jJyBzaG91 bGQNCi1yZXR1cm4gI3QgdG8gaW5kaWNhdGUgdGhhdCBpdCBoYXMgcGVyZm9ybWVkIGhlbHAsIGEg c3RyaW5nIHRvIG92ZXJyaWRlDQotdGhlIGRlZmF1bHQgb2JqZWN0IGRvY3VtZW50YXRpb24sIG9y ICNmIHRvIHRyeSB0aGUgb3RoZXIgaGFuZGxlcnMsDQotcG90ZW50aWFsbHkgZmFsbGluZyBiYWNr IG9uIHRoZSBub3JtYWwgYmVoYXZpb3IgZm9yIGBoZWxwJy4iDQotICAoc2V0ISAqdmFsdWUtaGVs cC1oYW5kbGVycyogKGNvbnMgcHJvYyAqdmFsdWUtaGVscC1oYW5kbGVycyopKSkNCi0NCi0oZGVm aW5lIChyZW1vdmUtdmFsdWUtaGVscC1oYW5kbGVyISBwcm9jKQ0KLSAgIlJlbW92ZXMgYSBoYW5k bGVyIGZvciBwZXJmb3JtaW5nIGBoZWxwJyBvbiBhIHZhbHVlLg0KLQ0KLVNlZSB0aGUgZG9jdW1l bnRhdGlvbiBmb3IgYGFkZC12YWx1ZS1oZWxwLWhhbmRsZXInIGZvciBtb3JlDQotaW5mb3JtYXRp b24uIg0KLSAgKHNldCEgKnZhbHVlLWhlbHAtaGFuZGxlcnMqIChkZWxldGUhIHByb2MgKnZhbHVl LWhlbHAtaGFuZGxlcnMqKSkpDQotDQotKGRlZmluZSAodHJ5LXZhbHVlLWhlbHAgdmFsdWUpDQot ICAob3ItbWFwIChsYW1iZGEgKHByb2MpIChwcm9jIHZhbHVlKSkgKnZhbHVlLWhlbHAtaGFuZGxl cnMqKSkNCi0NCi0NCiA7OzsgRG9jdW1lbnRhdGlvbg0KIDs7Ow0KIChkZWZpbmUgaGVscA0KQEAg LTEwOCwxMiArODUsMTAgQEANCiAgICAgICAgICAgICAgICAgKChhbmQgKGxpc3Q/IG5hbWUpDQog ICAgICAgICAgICAgICAgICAgICAgICg9IChsZW5ndGggbmFtZSkgMikNCiAgICAgICAgICAgICAg ICAgICAgICAgKGVxPyAoY2FyIG5hbWUpICd1bnF1b3RlKSkNCi0gICAgICAgICAgICAgICAgIChs ZXQgKCh2YWx1ZSAobG9jYWwtZXZhbCAoY2FkciBuYW1lKSBlbnYpKSkNCi0gICAgICAgICAgICAg ICAgICAgKGNvbmQgKCh0cnktdmFsdWUtaGVscCB2YWx1ZSkNCi0gICAgICAgICAgICAgICAgICAg ICAgICAgID0+IG5vb3ApDQotICAgICAgICAgICAgICAgICAgICAgICAgICgob2JqZWN0LWRvY3Vt ZW50YXRpb24gdmFsdWUpDQotICAgICAgICAgICAgICAgICAgICAgICAgICA9PiB3cml0ZS1saW5l KQ0KLSAgICAgICAgICAgICAgICAgICAgICAgICAoZWxzZSAobm90LWZvdW5kICdkb2N1bWVudGF0 aW9uIChjYWRyIG5hbWUpKSkpKSkNCisgICAgICAgICAgICAgICAgIChjb25kICgob2JqZWN0LWRv Y3VtZW50YXRpb24NCisgICAgICAgICAgICAgICAgICAgICAgICAgKGxvY2FsLWV2YWwgKGNhZHIg bmFtZSkgZW52KSkNCisgICAgICAgICAgICAgICAgICAgICAgICA9PiB3cml0ZS1saW5lKQ0KKyAg ICAgICAgICAgICAgICAgICAgICAgKGVsc2UgKG5vdC1mb3VuZCAnZG9jdW1lbnRhdGlvbiAoY2Fk ciBuYW1lKSkpKSkNCiANCiAgICAgICAgICAgICAgICAgOzsgKHF1b3RlIFNZTUJPTCkNCiAgICAg ICAgICAgICAgICAgKChhbmQgKGxpc3Q/IG5hbWUpDQpAQCAtMTU5LDggKzEzNCw3IEBADQogICAo bGV0ICgoZW50cmllcyAoYXByb3Bvcy1mb2xkIChsYW1iZGEgKG1vZHVsZSBuYW1lIG9iamVjdCBk YXRhKQ0KIAkJCQkgKGNvbnMgKGxpc3QgbW9kdWxlDQogCQkJCQkgICAgIG5hbWUNCi0JCQkJCSAg ICAgKG9yICh0cnktdmFsdWUtaGVscCBvYmplY3QpDQotICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgIChvYmplY3QtZG9jdW1lbnRhdGlvbiBvYmplY3QpKQ0K KwkJCQkJICAgICAob2JqZWN0LWRvY3VtZW50YXRpb24gb2JqZWN0KQ0KIAkJCQkJICAgICAoY29u ZCAoKGNsb3N1cmU/IG9iamVjdCkNCiAJCQkJCQkgICAgImEgcHJvY2VkdXJlIikNCiAJCQkJCQkg ICAoKHByb2NlZHVyZT8gb2JqZWN0KQ0KQEAgLTE4NiwyOCArMTYwLDIyIEBADQogICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAjZiAiflM6IH5TXG4iDQogICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAobW9kdWxlLW5hbWUg KG1vZHVsZSBlbnRyeSkpDQogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAobmFtZSBlbnRyeSkpKSkNCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAoY29u ZA0KLSAgICAgICAgICAgICAgICAgICAgICAgICAgICAoKGVxPyAoZG9jIGVudHJ5KSAjdCkNCi0g ICAgICAgICAgICAgICAgICAgICAgICAgICAgIDs7IGEgdmFsdWUgaGVscCBoYW5kbGVyIGhhcyBh bHJlYWR5IGhhbmRsZWQNCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAgIDs7IHRoaXMgZW50 cnkgLS0gZG9uJ3QgZG8gYW55dGhpbmcNCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAgICN0 KQ0KLSAgICAgICAgICAgICAgICAgICAgICAgICAgICAoKGRvYyBlbnRyeSkNCi0gICAgICAgICAg ICAgICAgICAgICAgICAgICAgIChzZXQhIGRvY3VtZW50ZWQtZW50cmllcw0KLSAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgKGNvbnMgZW50cnktc3VtbWFyeSBkb2N1bWVudGVkLWVu dHJpZXMpKQ0KLSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgOzsgKmZpeG1lKjogc2V0IHVw IGEgaGFuZGxlciBpbiBnb29wcy5zY20NCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAgIDs7 IHRvIHVzZSBgZGVzY3JpYmUnDQotICAgICAgICAgICAgICAgICAgICAgICAgICAgICAoc2V0ISBk b2N1bWVudGF0aW9ucw0KLSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgKGNvbnMg KHNpbXBsZS1mb3JtYXQNCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAjZiAiYH5TJyBpcyB+QSBpbiB0aGUgflMgbW9kdWxlLlxuXG5+QVxuIg0KLSAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIChuYW1lIGVudHJ5KQ0KLSAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICh0eXBlIGVudHJ5KQ0KLSAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIChtb2R1bGUtbmFtZSAobW9kdWxlIGVudHJ5 KSkNCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAoZG9jIGVudHJ5 KSkNCi0gICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGRvY3VtZW50YXRp b25zKSkpDQotICAgICAgICAgICAgICAgICAgICAgICAgICAgIChlbHNlDQotICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAoc2V0ISB1bmRvY3VtZW50ZWQtZW50cmllcw0KLSAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgKGNvbnMgZW50cnktc3VtbWFyeQ0KLSAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgdW5kb2N1bWVudGVkLWVudHJpZXMpKSkpKSkN CisgICAgICAgICAgICAgICAgICAgICAgICAgICAoaWYgKGRvYyBlbnRyeSkNCisgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgKGJlZ2luDQorICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgKHNldCEgZG9jdW1lbnRlZC1lbnRyaWVzDQorICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgKGNvbnMgZW50cnktc3VtbWFyeSBkb2N1bWVudGVkLWVudHJpZXMpKQ0K KyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDs7ICpmaXhtZSo6IFVzZSBgZGVzY3Jp YmUnIHdoZW4gd2UgaGF2ZSBHT09QUz8NCisgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAoc2V0ISBkb2N1bWVudGF0aW9ucw0KKyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgIChjb25zIChzaW1wbGUtZm9ybWF0DQorICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICNmICJgflMnIGlzIH5BIGluIHRoZSB+UyBtb2R1bGUuXG5cbn5B XG4iDQorICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIChuYW1l IGVudHJ5KQ0KKyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAo dHlwZSBlbnRyeSkNCisgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg ICAgKG1vZHVsZS1uYW1lIChtb2R1bGUgZW50cnkpKQ0KKyAgICAgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAoZG9jIGVudHJ5KSkNCisgICAgICAgICAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICBkb2N1bWVudGF0aW9ucykpKQ0KKyAgICAgICAgICAg ICAgICAgICAgICAgICAgICAgICAoc2V0ISB1bmRvY3VtZW50ZWQtZW50cmllcw0KKyAgICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAoY29ucyBlbnRyeS1zdW1tYXJ5DQorICAgICAg ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHVuZG9jdW1lbnRlZC1lbnRyaWVz KSkpKSkNCiAgICAgICAgICAgICAgICAgICAgICAgIGVudHJpZXMpDQogDQogICAgICAgICAgICAg IChpZiAoYW5kIChub3QgKG51bGw/IGRvY3VtZW50ZWQtZW50cmllcykpDQpAQCAtNTI4LDUgKzQ5 Niw0IEBADQogCSAoc3RyaW5nLWFwcGVuZCAiTW9kdWxlICIgKHN5bWJvbC0+c3RyaW5nIChtb2R1 bGUtbmFtZSBtKSkNCiAJCQkiIGlzIG5vdyBhICIgKGlmIHMgInN5c3RlbSIgInVzZXIiKSAiIG1v ZHVsZS4iKSkpKSkpDQogDQotOzs7IGFyY2gtdGFnOiA1MzQ4YzI2NC02MjYxLTRiMWUtYjI5ZC1j MTliYjBmYmM5NGUNCiA7Ozsgc2Vzc2lvbi5zY20gZW5kcyBoZXJlDQo= --=_fridge-12479-1084027833-0001-2 Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel --=_fridge-12479-1084027833-0001-2--