generating documentation

[Tamas Papp]

Content preview: Hi, I am about to complete a revision of LLA and I thought
I would write some decent documentation. I have most of the documentation
in docstrings, though some of general discussions are in ;;; comments in
files. [...]

Content analysis details: (-3.4 points, 5.0 required)

pts rule name description
---- ---------------------- --------------------------------------------------
-2.3 RCVD_IN_DNSWL_MED RBL: Sender listed at http://www.dnswl.org/, medium
trust
[80.91.229.12 listed in list.dnswl.org]
0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider
(tkpapp[at]gmail.com)
-0.0 SPF_HELO_PASS SPF: HELO matches SPF record
-0.0 SPF_PASS SPF: sender matches SPF record
-1.1 RP_MATCHES_RCVD Envelope sender domain matches handover relay domain
0.0 T_TO_NO_BRKTS_FREEMAIL To: misformatted and free email service
Archived-At: <http://permalink.gmane.org/gmane.lisp.cl-pro/522>

Hi,

I am about to complete a revision of LLA and I thought I would write some
decent documentation. I have most of the documentation in docstrings,
though some of general discussions are in ;;; comments in files.

I am looking for a reasonably automatic way of generating documentation
(eg texinfo or HTML) from the source. I found many libraries for this on
cliki, and instead of trying all of them out, I thought I would ask for
advice here.

Portability would be nice is not necessarily a requirement, so tools like
sbcl's texinfo are fine too. However, if possible, I would like to put
the documentation on the interface and the internal details in separate
sections somehow. I would also be interested in including tutorial-like
sections with examples.

Thanks,

Tamas

PS.: I have searched the cl-pro and c.l.l archives and found some
discussions about this question, but my impression was that a lot of new
libraries appeared on the scene in the past few years.

[Didier Verna]

Content preview: Tamas Papp <tkpapp-***@public.gmane.org> wrote: > I am looking for a
reasonably automatic way of generating > documentation (eg texinfo or HTML)
from the source. I found many > libraries for this on cliki, and instead
of trying all of them out, I > thought I would ask for advice here. > > Portability
would be nice is not necessarily a requirement [...]

Content analysis details: (-101.1 points, 5.0 required)

pts rule name description
---- ---------------------- --------------------------------------------------
-100 USER_IN_WHITELIST From: address is in the user's white-list
-1.1 RP_MATCHES_RCVD Envelope sender domain matches handover relay domain
Archived-At: <http://permalink.gmane.org/gmane.lisp.cl-pro/523>

Post by Tamas Papp
I am looking for a reasonably automatic way of generating
documentation (eg texinfo or HTML) from the source. I found many
libraries for this on cliki, and instead of trying all of them out, I
thought I would ask for advice here.
Portability would be nice is not necessarily a requirement

Then, if you don't mind trying an SBCL-only thing, I would of course
recommend my Declt package. It generates Texinfo so you can in turn get
Info, HTML and PDF output. It takes one function call (with many
options) to generate the Texinfo file. Perhaps you can look at an
example to see how things are organized and what gets documented.

The Decl reference manual is such an example:
http://www.lrde.epita.fr/~didier/software/lisp/declt/reference.pdf

Good luck.

[Gary King]

Content preview: Hi Tamas, From the looks of it Didier's Declt is far more
complete than Tinaa ever was. Also, Declt looks like it's actually maintained
(which I hardly have time to do with my own stuff :-(.). OTOH, Docudown and
CL-Markdown provide a non-automated way to write documentation that can produce
much a more useful product (IMHO). The great thing about tools like Declt
is that they are automated. The bad thing is that the end product is closer
to a dictionary than a encyclopedia. Docudown lets you write documentation
and easily add in your docstrings. E.g., [...]

Content analysis details: (-100.0 points, 5.0 required)

pts rule name description
---- ---------------------- --------------------------------------------------
-100 USER_IN_WHITELIST From: address is in the user's white-list
-0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at http://www.dnswl.org/, no
trust
[216.119.134.130 listed in list.dnswl.org]
Archived-At: <http://permalink.gmane.org/gmane.lisp.cl-pro/524>

Hi Tamas,

From the looks of it Didier's Declt is far more complete than Tinaa ever was. Also, Declt looks like it's actually maintained (which I hardly have time to do with my own stuff :-(.).

OTOH, Docudown and CL-Markdown provide a non-automated way to write documentation that can produce much a more useful product (IMHO). The great thing about tools like Declt is that they are automated. The bad thing is that the end product is closer to a dictionary than a encyclopedia. Docudown lets you write documentation and easily add in your docstrings. E.g.,

### Introspection

{docs print-tests}
{docs map-testsuites}
{docs testsuites}
{docs testsuite-tests}
{docs find-testsuite}

As an example, http://common-lisp.net/project/lift/user-guide.html#function.find-testsuite and http://common-lisp.net/project/lift/user-guide.text for the source.

The ideal, I think, is to use something like Declt for the reference and something like Docudown for the user-guide.

that's my two cents.

Hi,
I am about to complete a revision of LLA and I thought I would write some
decent documentation. I have most of the documentation in docstrings,
though some of general discussions are in ;;; comments in files.
I am looking for a reasonably automatic way of generating documentation
(eg texinfo or HTML) from the source. I found many libraries for this on
cliki, and instead of trying all of them out, I thought I would ask for
advice here.
Portability would be nice is not necessarily a requirement, so tools like
sbcl's texinfo are fine too. However, if possible, I would like to put
the documentation on the interface and the internal details in separate
sections somehow. I would also be interested in including tutorial-like
sections with examples.
Thanks,
Tamas
PS.: I have searched the cl-pro and c.l.l archives and found some
discussions about this question, but my impression was that a lot of new
libraries appeared on the scene in the past few years.
_______________________________________________
pro mailing list
http://lists.common-lisp.net/cgi-bin/mailman/listinfo/pro

--
Gary Warren King, metabang.com
Cell: [phone]
Fax: [phone]
gwkkwg on Skype * garethsan on AIM * gwking on twitter

[Didier Verna]

Content preview: Gary King <gwking-KFOG0ziCLXtWk0Htik3J/***@public.gmane.org> wrote: > The ideal, I think,
is to use something like Declt for the reference > and something like Docudown
for the user-guide. Absolutely. Declt is intentionally meant to be a reference
manual generator and nothing else. I've never been a fan of litterate programming
and always write my user manuals by hand. But you've caught my attention
about docudown and cl-markdown. I should have a closer look at what they do.
[...]

Content analysis details: (-101.1 points, 5.0 required)

pts rule name description
---- ---------------------- --------------------------------------------------
-100 USER_IN_WHITELIST From: address is in the user's white-list
-1.1 RP_MATCHES_RCVD Envelope sender domain matches handover relay domain
Archived-At: <http://permalink.gmane.org/gmane.lisp.cl-pro/525>

Post by Gary King
The ideal, I think, is to use something like Declt for the reference
and something like Docudown for the user-guide.

Absolutely. Declt is intentionally meant to be a reference manual
generator and nothing else. I've never been a fan of litterate
programming and always write my user manuals by hand. But you've caught
my attention about docudown and cl-markdown. I should have a closer look
at what they do.