Nikodemus Siivola nikodemus@random-state.net writes:
I have some other interactive documentation related ideas as well, but that might be a nice start.
So, we're looking at:
* (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?
Then Slime and REPL users can ask hyperdoc and have it as a consistent interface while hyperdoc knows how to get documentation from possible multiple types of systems, including what you mention about *hyperdoc-info*? (Although, perhaps it would be better to provide a function that returned the URL.)
Erik.
On Thu, Nov 13, 2003 at 10:27:56AM -0500, Erik Enge wrote:
Nikodemus Siivola nikodemus@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:
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
-
Erik Enge -
Nikodemus Siivola