[Bese-devel] ucw documentation effort

[Marco Baringer]

Adam Jones <ajones1 at gmail.com> writes:

> Looking at the documentation provided from the source code I was
> thinking that a decent place to start a reference would be to
> restructure the current source documentation into a one page per
> function/macro/class/(computational object just to have a generic term
> for everything involved). From there the next step I see would be to
> add descriptions for it and provide a facility for user comments. Yes,
> this is almost exactly like the PHP documentation system, but that
> works really well and I think it would be good here.

allowing user comments will take a bit more work. however i did change
qbook to output one html page per computational object (the latex
output is unchanged), indexes (cross referencing is next on the todo
list) and there's the infrastructre neccessary for having extra info
extracted from defmethod, defgeneric, defWHATEVER forms. we now also
look for and process docstrings (and have the neccosary code to
extract docstrings from methods, classes, functions, etc.) the names
of the pages for computational elements are strange, but they're
chosen so that 1) they'll work on all file systems no matter what the
symbol's name is and 2) they won't change unless the symbol's name
changes (so book marks will live even when the docs are regenerated)

see:

http://uncommon-web.com/qbook/arnesi/
http://uncommon-web.com/qbook/qbook/
http://uncommon-web.com/qbook/yaclml/

(i'm still having some trouble building ucw's docs so those aren't
available yet)

comments welcome.

(these are updated automatically from the darcs repos every night at
midnight).

-- 
-Marco
Ring the bells that still can ring.
Forget the perfect offering.
There is a crack in everything.
That's how the light gets in.
	-Leonard Cohen