[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Chicken-users] Comprehensive documentation rewrite
From: |
felix winkelmann |
Subject: |
Re: [Chicken-users] Comprehensive documentation rewrite |
Date: |
Wed, 13 Feb 2008 09:18:20 +0100 |
On Feb 12, 2008 10:16 PM, Shawn Rutledge <address@hidden> wrote:
> On Feb 12, 2008 10:13 AM, Tobia Conforto <address@hidden> 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
- Re: [Chicken-users] Comprehensive documentation rewrite, (continued)
- Re: [Chicken-users] Comprehensive documentation rewrite, Graham Fawcett, 2008/02/12
- Re: [Chicken-users] Comprehensive documentation rewrite, Mario Domenech Goulart, 2008/02/12
- Re: [Chicken-users] Comprehensive documentation rewrite, Tobia Conforto, 2008/02/12
- Re: [Chicken-users] Comprehensive documentation rewrite, Jim Ursetto, 2008/02/12
- Re: [Chicken-users] Comprehensive documentation rewrite, Shawn Rutledge, 2008/02/12
- Re: [Chicken-users] Comprehensive documentation rewrite, Matthew Flatt, 2008/02/12
- Re: [Chicken-users] Comprehensive documentation rewrite,
felix winkelmann <=
- Re: [Chicken-users] Comprehensive documentation rewrite, Peter Bex, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, felix winkelmann, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Shawn Rutledge, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Elf, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Shawn Rutledge, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Elf, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Leonardo Valeri Manera, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Elf, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Ivan Raikov, 2008/02/13
- Re: [Chicken-users] Comprehensive documentation rewrite, Elf, 2008/02/13