I'm searching a tool for generating HTML documentation like JavaDoc or
Doxygen produces, but for Lisp. http://albert.sourceforge.net/ looks
interesting, but I'm not sure how difficult it is to setup DocBook, a pure
Lisp solution would be nice.
The program should provide features know from JavaDoc, like generating not
only plain documentation from the documentation string, but like e.g. in
http://www.lisp.org/HyperSpec/Body/fun_format.html it should be possible to
describe every parameter of a function with tags and different sections for
"examples", "see also" etc. And it should generate various index entry
points, like a permutated symbol index. Finally it should generate all
necessary project files to start the Microsoft Help Compiler for producing
a chm-file from the HTML pages.
--
Frank Buss, ··@frank-buss.de
http://www.frank-buss.de, http://www.it4-systems.de
Not having an automatic doc generator certainly ticks down CL in
potential users' eyes. That we still don't have one (Javadoc has been
around for nearly a decade) also doesn't shed a good light on the
community's ability to develop standards. (not a flame, just an
observation). That having been said and knowing that this will sound
like heresy, here goes...
The most used data structure now is XML. I think that the community
should develop a DTD/schema for describing CL information - types,
function, macros, etc. It should be a find-grained structure to provide
the greatest amount of context. How the XML is actually generated is an
implementation issue. But once created, the are many existing tools -
in particular XSL - that can transform the XML into any of the common
formats - DocBook, HTML, etc.
I have a student developing just such a system for CLforJava. It
generates XML that is stored along with compiled code (on disk or in
memory). The various Documentation functions use XSL transforms to
create the appropriate user view of the doc at runtime. The DTD also
supports reference to system-defined resources for translated doc
strings. If anyone is interested, drop me an email. I'll post the final
DTD (and possibly a schema) around the end of the semester. It's
licensed under the MIT license.
Jerry
Frank Buss wrote:
> I'm searching a tool for generating HTML documentation like JavaDoc or
> Doxygen produces, but for Lisp. http://albert.sourceforge.net/ looks
> interesting, but I'm not sure how difficult it is to setup DocBook, a pure
> Lisp solution would be nice.
>
> The program should provide features know from JavaDoc, like generating not
> only plain documentation from the documentation string, but like e.g. in
> http://www.lisp.org/HyperSpec/Body/fun_format.html it should be possible to
> describe every parameter of a function with tags and different sections for
> "examples", "see also" etc. And it should generate various index entry
> points, like a permutated symbol index. Finally it should generate all
> necessary project files to start the Microsoft Help Compiler for producing
> a chm-file from the HTML pages.
>
> --
> Frank Buss, ··@frank-buss.de
> http://www.frank-buss.de, http://www.it4-systems.de