From gwking at metabang.com  Tue Jan  5 18:04:58 2010
From: gwking at metabang.com (Gary King)
Date: Tue, 5 Jan 2010 13:04:58 -0500
Subject: [docudown-devel] Docudown general usage
In-Reply-To: <47C32BE5-C038-4F42-9FD2-C4CD2A8ED7AA@gmail.com>
References: <47C32BE5-C038-4F42-9FD2-C4CD2A8ED7AA@gmail.com>
Message-ID: <45F97E0B-1F5A-440D-90B9-B9E3ED02C238@metabang.com>

Hi JM,

tinaa and docudown serve very different needs (and both are in need of tender loving care that I won't get to any time soon).

tinaa was an attempt to do a good job at automatic documentation; docudown is an attempt to make it easier to write good documentation. tinaa introspects the structure of the system/package/whatever and documents the hierarchies it finds. docudown relies on you to write documentation and helps pull that documentation together along with docstrings, etc. It also adds extensions to markdown that make things like table of contents, etc. easier.

As for cl-markdown, it is a port of markdown that docudown uses as its formatting engine. I'll look later today to see what the best top-level forms are for documenting a system. 

Finally, it is true that AllegroGraph uses docudown for some of its documentation and those db.agraph forms in some of the comments crept back into the docudown source!

The particular forms in question are related to some of the reports that docudown can produce describing things like "which exported symbols aren't documented" or "which exported symbols" don't seem to be used anywhere".

HTH,

On Jan 4, 2010, at 6:23 PM, Jean-Marc Fran?ois wrote:

> Hi,
> 
> 
> Sorry for the newbie question.  I've used Tinaa and generating a website documenting the :my.package package was as simple as:
> (tinaa:document-system 'package :my.package (pathname "/tmp/test/"))
> 
> Now as far as I've understood the preferred way is to use cl-markdown together with docudown.  Yet I can't find a form doing the same job
> as the one above. 
> 
> I have a followup :-)  I've seen references to db.agraph in cl-markdown/dev/reports.lisp.  Is it because some tuning have been needed in order to generate Franz's agraph API doc (I've seen they are using cl-markdown, that's basically how I heard about your package)?
> 
> 
> Thanks in advance for your answer!
> Best,
> JM

--
Gary Warren King, metabang.com 
Cell: (413) 559 8738
Fax: (206) 338-4052
gwkkwg on Skype * garethsan on AIM * gwking on twitter




From jm.francois at gmail.com  Tue Jan  5 00:27:34 2010
From: jm.francois at gmail.com (=?iso-8859-1?Q?Jean-Marc_Fran=E7ois?=)
Date: Tue, 05 Jan 2010 00:27:34 -0000
Subject: [docudown-devel] Docudown general usage
Message-ID: <47C32BE5-C038-4F42-9FD2-C4CD2A8ED7AA@gmail.com>

Hi,


Sorry for the newbie question.  I've used Tinaa and generating a website documenting the :my.package package was as simple as:
(tinaa:document-system 'package :my.package (pathname "/tmp/test/"))

Now as far as I've understood the preferred way is to use cl-markdown together with docudown.  Yet I can't find a form doing the same job
as the one above. 

I have a followup :-)  I've seen references to db.agraph in cl-markdown/dev/reports.lisp.  Is it because some tuning have been needed in order to generate Franz's agraph API doc (I've seen they are using cl-markdown, that's basically how I heard about your package)?


Thanks in advance for your answer!
Best,
JM