Re: a ruby-core primer

On Aug 22, 2006, at 15:13, why the lucky stiff wrote:

> Hello, all.  I've been working on the ruby-core page for the new Ruby 
> site.
> I'd like this page to be our English primer to this mailing list and 
> to core
> development among English speakers.

Outstanding. :)

"Aha," says I, to myself. "Why not take this as an opportunity to 
expand RDoc's documentation?"

The results might be instructive. :/ Whether they're relevant to the 
ruby-core primer or not, I'm not entirely sure, so I'll let y'all 
decide.

***

I endorse somebody else's suggestion of adding links to the "Using CVS" 
section. I didn't get any error messages, so I guess it worked 
correctly, but I have absolutely no idea what was actually happening. 
Poof! Mysterious magic.

Well enough. On to ruby/lib/rdoc. Yup, looks a lot like my 1.8.4 
version. First, I figure I should RDoc the RDoc directory, so I have 
documentation that matches the actual code.

Hmm. Well, "ruby rdoc.rb --fmt html" didn't work. I'm not shocked, 
since rdoc.rb doesn't seem to include any code that'd actually get 
executed. So I resort to using my 1.8.4 binary at first. A bit of 
poking around, and I'm still getting the error messages I get with the 
1.8.4 source, specifically

	README: Couldn't find file to include: 'EXAMPLE.rb'
and
	Unrecognized directive 'section' in README

No problem; that's on my list of things to fix. I poke around a bit 
more, noting that generators/chm_generator.rb is one of those files 
that displays a cryptically empty page. "Does it have any documentation 
in it?" I wonder? So I open it. The answer is "no, it's extremely 
sparse." But I at least find out what on earth it's for. If I were 
running Windows, I might have guessed earlier.

But now I really want to generate the docs using the 1.9 source files. 
I still can't figure out how to get myself just an "rdoc" binary, so I 
figure I'll at least start to compile the whole thing.

	jabberwock/ruby snarke$ ./configure
	-bash: ./configure: No such file or directory

Off to the README. Aha. Autoconf. OK.

	jabberwock/ruby snarke$ autoconf
	configure.in:4: error: Autoconf version 2.58 or higher is required
	configure.in:4: the top level
	autom4te: /usr/bin/gm4 failed with exit status: 1


No no no. I've been down this path before, spending hours trying to 
figure out how to make some thingamabob work, because I have to have a 
working thingamabob before I can build a zingaboo which is required by 
the gwing needed to compile ruby, or run irb, or do whatever today's 
task was supposed to have been.

	jabberwock/ruby snarke$ autoconf -V
	autoconf (GNU Autoconf) 2.57

For crying out loud.

***

So anyway, to come back to topic....

Maybe the ruby-core primer could contain information, or a link to 
information, about what's going to be required to work with it? (In 
this case, OSX 10.3.9 apparently isn't good enough. I suppose 10.4's 
autoconf has that extra critical 1/100th of a whatever that makes all 
the difference.) I'm thinking of something relatively broad, like "OSX 
10.4, RedHat n.n.n, Windows something with development kit X" not 
something as gory as "Autoconf 2.58, gcc compiler 3.3, gcc linker" OK, 
I have no idea what to put after linker, since mine (I think) is 
"version cctools-525.obj~1". But you get my point.

Now, it would be *nice* if there were some hint along the lines of "If 
you don't have [some necessary piece], go *here* and/or do *this.*" But 
I recognize that at some point, ya just have to say "OK, if you don't 
know where to find your command line, then you're on your own. Go 
figure it out yourself." The question is, how far down is it worth 
reaching?

Take me, for instance. Hey, I want to help, but what I want to do is 
add text to the code. Not add/fix/change code (by which I mean RUBY 
code, although I'm sure I'll end up doing some of that, too), but text. 
I like English. I like Ruby. I do NOT like Unix or its command line 
minions, and they don't like me back. (Being the cantankerous sort I 
sometimes am, I don't like, use, or read C, either.) So the more 
information the primer page has that helps me not get error messages, 
the more likely I'll get to the point that I might be able to 
contribute something.

To continue to use myself as a convenient example, it's possible that 
I'm just too clueless to be worth the effort it'd take to get me up and 
running. There really is some minimum reasonable expectation of 
knowledge before somebody can contribute usefully to the development of 
Ruby itself. So as you refine your page, Why, figure out what a 
reasonable 'cutoff' of knowledge should be, add information above that 
line, and gently encourage people below that line to find other ways to 
contribute.

I hope this message is useful, and thanks again for creating that page; 
already vastly superior to what we had last week. :)