[admin] net-nittin-hyperspec

[Nikodemus Siivola]

On Thu, Nov 13, 2003 at 10:27:56AM -0500, Erik Enge wrote:

> Nikodemus Siivola <nikodemus at random-state.net> writes:

>   * (hyperdoc:lookup "myfunction" "mypackage") 
> 
> Or something like that?  Then hyperdoc would know how to go into that
> package, ask for *hyperdoc-info* or whatever and figure out how to
> compose the return value?  What possible return values are there?  Just
> URLs?

I was too cute with the *h-i*, it seems. We should probably move this
off admin, btw...

Basing this on:

 http://www.cliki.net/hyperdoc

Lookup:

 (defun hyperdoc (thing &optional doc-type)
   (let ((uri (hyperdoc-lookup (symbol-package thing) thing doc-type)))
      (if (or doc-type uri)
	   uri
	   (hyperdoc-lookup-all-types (symbol-package thing) thing))))

The ..all-types should call hyperdoc lookup on all types, and return
an assoc list of unique non-NIL URI's and their types. Client code can
then offer choise, etc.

In random package:

 (defvar *hyperdoc-base-uri* "http://www.foobar.com/foo/docs/")

 (defmethod hyperdoc-lookup ((package (eql #.*package*)) symbol type)
   (concatenate 'string *hyperdoc-base-uri* 
                        (string-downcase (symbol-name symbol)) 
                        ".html"))

The important thing here is that this should be simple to use in any
given package. So small-low-tech packages can just cat a few strings
and be done. Big, involved packages may do more sophisticated things.

Providing documentation on objects:

I can see how this would be neat, but am not sold not it being the
sensible way to do things in the "random client package", since it
seems fairly easy to get it slightly wrong.

I'd rather do something like this:

 (defun ensure-hyperdoc-for-objects (package)
    (loop for x being the external-symbols of package
	  when (fboundp x) 
	  do (setf (documentation (fdefinition x) (intern "T" :hyperdoc)) (hyperdoc x 'function))
          ...other types...))

...and then add the DOCUMENTATION lookup to hyperdoc for non-symbols.


Also, the real bells and whistles pipe-dream would be to autogenerate
the hypertext markup from the documentation strings in the system,
parsing wiki-like markup to allow linking to other symbols...

Cheers,

 -- Nikodemus
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://mailman.common-lisp.net/pipermail/admin/attachments/20031114/2dbb1b6d/attachment.sig>