On Feb 12, 2008 10:16 PM, Shawn Rutledge <[EMAIL PROTECTED]> wrote: > On Feb 12, 2008 10:13 AM, Tobia Conforto <[EMAIL PROTECTED]> wrote: > > My idea is to devise a "smart" document format, preferably s-expr > > based (maybe SSAX-based if nothing better comes to mind) and convert > > every piece of Chicken API documentation to that format: both for eggs > > and for the base system. This includes any relevant SRFIs that are > > part of Chicken or of some eggs. > > I like the idea of being able to put the documentation into the code; > something like Doxygen is needed for Scheme. I think it's not the > first time such an idea has been proposed, but I don't know much about > what has been tried. >
In my experience separating the documentation from the code leads in the end to more consistent information. I've seen too much doxygen generated "documentation heaps" with no obvious start or beginning. Another effect is that documentation is structured to fit the doc-generating tool, instead of being easy to access for users. I happen to like svnwiki syntax. It's easy to use, non-obstructive and we have all the infrastructure to convert it into other formats. Besides, all these doc overhauls just eat up developer time... cheers, felix _______________________________________________ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
