From: Dave Thomas <Dave@...>
Date: 2000-12-28T01:36:44+09:00
Subject: [ruby-talk:8125] Re: Code examples in the pickaxe book [long]

jstern@foshay.citilink.com (Josh Stern) writes:

> >A couple of people have mentioned here that they're having problems
> >because they're typing in code from the book, and some of the code
> >fragments aren't self contained.
> 
> I think that within the book you should should refer to a web
> address for getting the source code.  At the web address, there 
> should be sections for each book chapter (and maybe sub-section)
> that try to present the code in the order presented, as accurately 
> as possible.  Then there can be other sections that include more 
> complete/real world final and worked examples.  Comments
> in the fragments could contain links to the more complete
> examples.

If we were to do that, would each of the individual examples show
_all_ the source of (for example) class Song, or just enough to have
the example run?

Indirectly, my question is "how much manual code munging should we
do?", because the more we do, the more chance of errors creeping in.

> Also it would be great if there were a complete reference to
> the C API somewhere on the web and the book referred to that.

I don't think there is a C API as such. Most people write extensions
using a fairly limited set of calls (such as those we document). Then, 
when they have a specific need, they'll look at the source of some
built-in library or distributed extension to find just the call they
need. Pretty much all of the public rb_xxx methods are available.

Regards


Dave