Re: [Chicken-users] Comprehensive documentation rewrite

[Shawn Rutledge]

On Feb 13, 2008 12:04 PM, Elf <address@hidden> wrote:
> not always true.  tex was better before the cycle of 'continuous 
> improvements',

The early development was before my time, but I don't think TeX
emerged fully-formed.  Knuth came up with that version scheme where he
adds digits to pi for each new version (expressing the idea that it
more accurately conforms to the ideal with each rev), and even pays
people to find bugs in his code (which says to me that he believes in
continuous improvement).  And it was arguably further improved by some
of the forks, like LaTeX.  Then Knuth invented literate programming.
I have some respect for the idea, even though some of the uses and
implementations can be unwieldy and the ideals are a bit high-minded -
the kernel of the idea seems to me a good one, and has been inspiring
for others.  I find Doxygen extremely useful, and don't understand why
such a large number of developers who write C++ or Java can agree on
such a system, while Scheme people seem to think it's weird to put any
kind of special comment syntax in the code.  Some code could maybe be
considered self-documenting, and some not.

> i dont know where the idea that
> anyone was proposing a be-all-and-end-all of documentation systems came from,
> but its getting aggravating.  i proposed the following concepts:

I agree with all your concepts, and look forward to your proposal.

All I'm hoping for as a starting point is a way to write parseable
comments that can be converted into API docs.  The other stuff can be
added later; a "be-all" documentation system cannot be expected to
emerge fully formed either.  I will always think of separate
documentation files as being fundamentally an adjunct... if you want
to write a tutorial, sure it ought to be separate, but that's not
where you start; you'd typically write it after the code.