I would like to know what people use for documentation. I am looking
for something that would extract documentation strings from functions
and other things and generate HTML and maybe other formats.
I know of Kirschke's Inverse Literate Programming,[1] but I wonder
what else has proven useful for people.
Thanks,
Tamas
[1] http://lki-www.informatik.uni-hamburg.de/~kirschke/invlit.html
--
Posted via a free Usenet account from http://www.teranews.com
On May 12, 11:50 am, Tamas Papp <······@gmail.com> wrote:
> I would like to know what people use for documentation. I am looking
> for something that would extract documentation strings from functions
> and other things and generate HTML and maybe other formats.
>
> I know of Kirschke's Inverse Literate Programming,[1] but I wonder
> what else has proven useful for people.
I've used CLDOC shttp://common-lisp.net/project/cldoc/ and found it
very nice. Documentation is extracted from documentation strings and
there /are/ formatting directives (ala TeX or Wiki markup). The only
issues that might be discouraging are that
1. Source has to be loaded into the Lisp before documentation can be
generated.
2. There doesn't seem to be a convenient way to provide more general
documentation (e.g., introductions, higher level descriptions of
program flow/design, &c.)
That said, it's still what we use at the lab for generating our docs.
>
> Thanks,
>
> Tamas
>
> [1]http://lki-www.informatik.uni-hamburg.de/~kirschke/invlit.html
>
> --
> Posted via a free Usenet account fromhttp://www.teranews.com
From: Edi Weitz
Subject: Re: what do you use for generating generating documentation?
Date:
Message-ID: <uy7jtri0g.fsf@agharta.de>
On Sat, 12 May 2007 11:50:00 -0400, Tamas Papp <······@gmail.com> wrote:
> I would like to know what people use for documentation. I am
> looking for something that would extract documentation strings from
> functions and other things and generate HTML and maybe other
> formats.
I use this:
http://weitz.de/documentation-template/
But is wasn't intended as a general-purpose library. I mainly use it
for my own stuff. As the name says, the library just generates a
/template/ which I then modify manually using Emacs macros.
--
Lisp is not dead, it just smells funny.
Real email: (replace (subseq ·········@agharta.de" 5) "edi")
On 2007-05-12, Tamas Papp <······@gmail.com> wrote:
> I would like to know what people use for documentation. I am looking
> for something that would extract documentation strings from functions
> and other things and generate HTML and maybe other formats.
Glad you asked.
I could not find a solution for Lisp package documentation that I liked,
so I wrote my own, called Atdoc. My plan was to blog it shortly, but I
guess a good old-fashioned Usenet announcement will also work.
You can find it at
http://www.lichteblau.com/atdoc/doc/
Atdoc extracts documentation strings written in a special syntax, and
builds HTML documentation out of that. It is heavily based on XSLT
stylesheets, but unless you want to customize the output, it should be
easy to use without any knowledge of XML, XSLT, or HTML.
The inspiration was, of course, Javadoc. But what works for Java does
not immediately translate to Lisp, so there are some differences.
Another inspiration are the LispWorks reference manuals, which I found
to be refreshingly usable even though they just have a long list of
symbols for each package, and the most helpful form of navigation
between those is the "See also" section on each page.
My experience with generated Lisp documentation was that fully automated
output listing all classes and their slots is extremely uninformative
and boring.
Instead, Atdoc requires the author to explicitly state most information
in the docstrings. Some data will be extracted from the Lisp image
automatically, but most links between different classes and functions
have to specified by the docstring author. This is probably the biggest
difference between Javadoc and Atdoc.
Compared to LispWorks, the difference is mostly the addition of longer
documentation sections, which are meant for introductory information
giving an overview of the software and its organization. Every
package's page will include this longer description in one column, and
the alphabetical symbol index in the other.
d.