Re: Improving the help interface

[Marius Vollmer <mvo@zagadka.de>]

Andy Wingo <wingo@pobox.com> 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 <gtk-object>))
      ...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 <std-guile-doc-source>))
      ..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