Re: Improving the help interface

[Andy Wingo]

Hi Marius,

Glad to hear you have improved your email setup ;-)

On Mon, 09 Aug 2004, Marius Vollmer wrote:

> Andy Wingo <address@hidden> 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 <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 ...)

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 <address@hidden>
http://ambient.2y.net/wingo/