Re: 2nd try at date/format.rb & pty.c

Hugh Sasse wrote:

> 
> Now, I was wondering if it is worth putting links in to information
> for beginners about CVS.  Obviously turning this into a CVS tutorial
> is inappropriate, but people who want to get involved will need to
> know where to look for information about how to use CVS update, etc.
> I'd be inclined to mention the "Pragmatic Version Control with CVS"
> book as well: I think with the large role the Pragmatic Progammers
> have had in our Ruby community this need not be confused with
> commercial endorsement.  I only raise that in case anyone thinks
> that might be a problem.

I liked that book, though didn't learn as much as I had hoped.  I have 
no issue with listing it as a resource, but I'd prefer that there be 
references to a good set of *free* resources.

(I'd also prefer that the doc not try to be too many things to too many 
people, but that's often hard to sort out.  I sort of assume that anyone 
attempting to read Ruby or C, understand and verify behavior, and 
document it, also has CVS skills.  But I'd also like to reduce 
artificial barriers to participation and eliminate goofy mistakes, such 
as fetching the wrong branch or version of code, so a link to a good 
intro CVS guide is a Good Thing.  And I suspect that people have the 
same thoughts on using diff, something I could use a good reference for 
since, as a practical matter, I've had little use for in some time. 
Maybe some scripts that just Do The Right Thing?  A Ruby Doc'ers Rake Set?)


> 
> One more point that I'd like to raise somewhere: at present there is
> no way to keep *internal* documentation with the code. Rdoc doesn't
> provide a means to support it apart from turning off Rdoc processing
> (which is fair enough, it wasn't a goal of the project), but if
> there were a means to markup documentation as being internal would
> this be a Bad Thing?  The present guidelines are almost perjorative
> about internal documentation. Is this simply because it will be
> exposed to the general user, thus leading to breaking of
> encapsulation, or does it have detrimental effects on code
> maintenance?  I'm wondering if Rdoc should support internal
> documentation in the future?  I'd have thought that details of
> choice of algorithms, tradeoffs in design, etc would be useful for
> future maintainers. For one thing, constraints change.  Available
> memory and processor speed changes since the 1980's are extreme
> examples.

Interesting.    Yeah, might be nice to have alternate doc versions; one 
with the conventional API docs, and one with the developer narrative doc.

Is it not enough that one can just look at the source for these?

James