[Openmcl-devel] Lisp DOC

[Robert Goldman]

Alexander Repenning wrote:
> It is simple to write little code producing a LOT of documentation  
> with Lisp. The trivial little hack below produces documentation for  
> the entire CL class tree. Especially when classes  
> include :documentation even the code below is somewhat useful.  
> However, my real question is this. Is anybody aware of some Java DOC- 
> like tool for Lisp? That is, something like that thing below but with  
> formated output (e.g., HTML with style sheet)? It would seem to be  
> such an obvious and simple thing to do in Lisp that I would assume it  
> already exists?

Edi Weitz has developed an asdf package, documentation-template
(http://www.weitz.de/documentation-template/), that grovels over the
symbols of a package and assembles them into an HTML manual.  We have
used it at my company, because it's simple, but it's not very general
--- it's very tailored to Edi's own uses, and he's not able to support
it.  We have modified it to be more general (e.g., allow for different
licenses, different download instructions, apply an arbitrary function
to filter the symbols whose documentation is to be incorporated, etc.),
but haven't released our changes.  We could probably be persuaded to do
so, if anyone was interested.

Gary King has a much more ambitious doc tool, but it relies on a very
large tree of software libraries.  We have been too cautious to use it
for that reason.

One thing that would be nice would be if we had a markup language (e.g.,
Markdown, texinfo) to use in documentation strings that would be
readable by just invoking DOCUMENTATION, but that could be postprocessed
to support hyperlinks and rudimentary text attributes.

Best,
Robert