From: Kevin Smith <sent@...>
Date: 2000-12-28T02:08:21+09:00
Subject: [ruby-talk:8127] Re: Code examples in the pickaxe book [long]

Dave Thomas wrote:
>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.

It would be nice if you could have a "final", 
complete version. You might need to add a flag 
code to your preprocessor (e.g. lines starting 
with '*' are final, others are not). This "final" 
version could be put up on a web site. At that 
point, it would also be a nice touch to include 
it in the book--probably in an appendix. 
Hopefully that would make everyone happy, with 
minimal effort on your part.

>> 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.

I would love to see more documentation about 
embedding Ruby inside apps. Most of the focus 
seems to be on writing extensions, which makes 
sense since. Of course, until I start cranking 
out documentation or other artifacts helpful to 
the Ruby community, I'll just continue to be 
thankful for whatever does exist.

Kevin