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

On Tue, 22 Aug 2006, James Britt wrote:

> Hugh Sasse wrote:
> 
        [...]
> > I'd be inclined to mention the "Pragmatic Version Control with CVS"
        [...]
> 
> 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.

Agreed, see other reply.
> 
> (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

Yes, that's why I put that goal paragraph in, to try to help us keep 
focus as we write.  We can throw it out later when it has served its use.

> 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

That was my thinking: my first forays into Rdoc were stymied by not
knowing the importance of -d in `cvs update -d`

> 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?)

Hmm, "Ubiquitous Automation" -- good point.
        [...]
> > 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
        [...]
> 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?

Well, it doesn't get formatted.  Even developers get tired eyes at
times.  Sometimes mistakes show up in the formatted version that
were somehow invisible in the source.
> 
> James
> 
        Thank you,
        Hugh