[hyperspec-lookup-devel] Hyperdoc directions (fwd)

[Nikodemus Siivola]

Apparently I wasn't subscribed, so the original bounced. 'ere we go:

---------- Forwarded message ----------
Date: Sat, 24 Apr 2004 23:59:15 +0300 (EEST)
From: Nikodemus Siivola <tsiivola at kosh.hut.fi>
To: slime-devel at common-lisp.net
Cc: Edi Weitz <edi at agharta.de>, Daniel Barlow <dan at telent.net>,
     stig at users.sourceforge.net, hyperspec-lookup-devel at common-lisp.net
Subject: Hyperdoc directions

First some background to get everyone up to speed:

Hyperdoc is a project to provide CLHS-style documentation lookup for
libraries.

 http://www.common-lisp.net/project/hyperdoc/

Edi Weitz recently added support for the hyperdoc protocol to his
packages, and the hyperdoc CVS contains horrid buggy hack in slime.patch
which replaces the clhs lookup in Slime by similar functionality powered
by hyperdoc. (Hyperdoc delegates undocumented symbols to
hyperspec-lookup <http://www.common-lisp.net/project/hyperspec-lookup/>.)

Calling (hyperdoc:lookup package-name symbol-name &optional doc-type-name)
gives either NIL, an URI, or if multiple docs for the same symbol
exist an alist of the form ((doc-type-name . uri)*).

The URIs related to a package can be stared in files, and if this has been
done with (hyperdoc:generate-index package), then lookup can be done even
if the package is not loaded. The idea is that these lookup files could
also be used directly by Slime/Emacs if it isn't connected to a lisp.

In it's current state it's basically usable, but some refinements are
probably necessary for serious use:

 1) Hook the index generation to compiling, either by doing

     (eval-when (:compile-toplevel)
       (when (find-package :hyperdoc)
          (funcall (intern "GENERATE-INDEX" :hyperdoc) :this-package)))

    in client packages, or maybe/preferebly this could be
    delegated to ASDF.

 2) Do the Emacs/Slime binding:

     * If connected use hyperdoc.

     * If not connected use the indices and hyperspec.el.

     * When the query gives multiple results (eg. a structure
       and a function of the same name) prompt the user to choose
       which type of documentation should be fetched.

"Fair enough, but get to the point already!" Ok, ok...

Do people have ideas/opinions on number 1? Once it is done, I think
essentially all work on the CL side is complete. Then, if desired, the
API can be integrated with cl:documentation or asdf:hyperdocumentation.

What do Slime folks think of the Emacs integration? Is someone willing to
do the grunt work on it? As the patch to current Slime shows, my elisp-fu
and slime-fu are rather lacking.

Anything I've forgotten?

Cheers,

 -- Nikodemus