Re: [Chicken-users] YADT: yet another documentation thread

[Ivan Raikov]

  Well, thanks for the thoughtful response, your suggestions are very
sensible. I also think it would be nice to have a Chicken-specific
introduction to functional programming, and I would support any effort
in the Chicken community to put together such a document. If anybody
is interested, I would really like to take parts of SICP and _Standard
ML for the Working Programmer_ -- both books do a very good job at
highlighting the idioms of functional programming -- I think a good
tutorial can be constructed by recycling the structure of existing
textbooks, while of course modifying it to fit the specifics of
Chicken.

  I disagree that new users should know how to put together a R5RS
environment with Chicken. As a new user of Chicken, my concern was not
with standards-conforming code; my concern was how to get code to work
using the functional programming idioms I had learned from Standard
ML. That's why the concept of core eggs doesn't make sense to me --
"core eggs" already implies some assumptions about programming style
that may or may not be necessary. If I don't give a address@hidden about
rational numbers, why do I need the numbers egg? On the other hand, if
I want to write code that involves arbitrary precision arithmetic, I
will figure out that I need the numbers egg pretty quickly, and I
don't need any "core eggs" to tell me that. And so on. 

  Basically, the concept of core eggs is highly redundant and
unnecessarily restrictive. Better focus on general concepts such as
recursion and dynamic data structures -- things applicable to all
functional programming languages, not just one implementation of one
language. From there you can decide which eggs are important for the
kind of programming you want to do, so you have your own personal set
of core eggs.

  As for your note about visual appeal -- I agree 110%. I find the
wiki documentation ugly, ugly, ugly. And the Texinfo and eggdoc
documentation is pretty, pretty, pretty :-) We need to continue
including a Texinfo manual with Chicken, because Texinfo can generate
beautiful printed documents (as of course it uses TeX as the
underlying layout engine). And we need better stylesheets for the
wiki. 

  I also like the idea about creating addenda to the
documentation. This way, we can require that there is always a "core"
documentation page in the egg SVN repository, but users can add to it
on the wiki, and perhaps periodically the core document will be
updated with new information from the wiki. Would you be interested in
developing a more detailed proposal about that?


  -Ivan


Vincent Manis <address@hidden> writes:

> I was offline for almost all of the documentation discussion, so
> please pardon my beating a somewhat dead horse. I'd like to make the
> following points, which (mostly) haven't been raised.
>