From: Hugh Sasse <hgs@...>
Date: 2006-08-24T02:10:48+09:00
Subject: Re: a ruby-core primer

On Wed, 23 Aug 2006, 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.
> 
>  <http://new.ruby-lang.org/en/community/ruby-core/>
> 

Thank you for creating this.  Firstly a couple of off-topic [more
applicable to the dev of the new site rather than this page] points.
Maybe you know whom to pass them on to??

   I'm finding the blue links on the blue background in the sidebars
   more difficult to read than the body of the article.  Maybe we
   could have an alternate stylesheet for those with "abnormal"
   eyesight ;-) ?  Thank you.

   With large print, the main body doesn't scale to fit the code
   -- it's marked up as <pre>...</pre>, this results in the code
   flowing under the sidebar, where it is invisible, and onto the
   dark background (when the text is really wide), where the
   contrast is thus very poor. This is with FireFox, IE folds the
   lines. This may be a bug in FF. OTOH maybe folding the lines for
   PRE is just WRONG :-).  I'll try to raise that scaling issue again
   on the FF forums but meanwhile...
   
Now, on to the stuff you really wanted to know (well, I hope this
is useful).

You can't have too much information about CVS for newcomers to it.
I'd suggest something like this:

  For information about CVS see http://www.nongnu.org/cvs/cvs.html,
  http://ximbiot.com/cvs/wiki/index.php?title=Main_Page, and you may
  find "Pragmatic Version Control with CVS" a useful introductory
  book (detals at
  http://www.pragmaticprogrammer.com/starter_kit/vcc/index.html .)

Given that YARV is based on Subvesion we probably need similar info
for that.  Just a moment:

  For information about Subversion see http://subversion.tigris.org/,
  http://svnbook.red-bean.com/, and you may
  find "Pragmatic Version Control with Subversion" a useful introductory
  book (detals at
  http://www.pragmaticprogrammer.com/titles/svn/index.html .)


Possibly the word "patches" in

  Please note: patches should be submitted as a unified diff. Use:

could link to :

http://www.gnu.org/software/diffutils/manual/html_node/Merging-with-patch.html#Merging%20with%20patch

in order to give a bit of an overview.

There are enough sections in this document (red headings) to merit a
Table of Contents. This would help people see the structure of the
doc from the outset.

That's about all I have to add for now.  

It does occur to me that there are a few details in here to get
right, options, tags, version control systems, repositories.  This 
is the sort of detail that computers handle better than people.  How
many of these protocols does Ruby itself support, and would it be 
possible to write a tool that would help people check out the right
bits, do the diffs properly and that sort of thing?  Lowering the
barrier to contributors doesn't just allow newbies to join in, it
allows busy people to contribute, "Oh, I could change that, it's
only a 5 minute job" sort of thing.

        Thank you,
        Hugh