From tsiivola at cc.hut.fi Sat Apr 24 21:44:55 2004 From: tsiivola at cc.hut.fi (Nikodemus Siivola) Date: Sun, 25 Apr 2004 00:44:55 +0300 (EEST) Subject: [hyperspec-lookup-devel] Hyperdoc directions (fwd) Message-ID: 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 To: slime-devel at common-lisp.net Cc: Edi Weitz , Daniel Barlow , 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 .) 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