Improving the help interface

[Andy Wingo]

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 <address@hidden>

session.scm.diff
Description: Text Data