Re: First timer: lib/date/format.rb

On Jun 19, 2006, at 4:09 PM, Sam Roberts wrote:
> On Mon, Jun 19, 2006 at 01:20:46PM -0400, Mat Schaffer wrote:
>>   #Mapping English day of the week names to numebers (reverse  
>> lookup for DAYNAMES)
>
> Spelling error ----------------------------------^

Which brings a question to mind.  Anyone have any good tips for  
spellchecking just the documentation?  I guess I could whip together  
something with ispell quickly enough.

> Also, doesn't DAYNAMES need to be +DAYNAMES+ for rdoc to make a  
> link for
> it to the docs for that constant? Perhaps my memory is failing, and  
> rdoc
> is smart enough to make the link.
No idea.  Which brings another question.  To check my rdoc syntax, I  
generated documentation for just that file, which made links to  
Time#... not work.  Is there an easy way to generate the whole rdoc  
tree in place so I can make sure all the links work?

>>   #A list of common timezone abbreviations and their respective  
>> offset from GMT in seconds.
>>   ZONES = {
>>     'ut'  =>  0*3600, 'gmt' =>  0*3600, 'est' => -5*3600, 'edt' =>  
>> -4*3600,
> ...
>
> Timezone abbreviations aren't even close to unique on this world,  
> use of
> the ZONES table is a terrible hack (IMNSHO).

The whole file is pretty hackish, IMHO.  Especially since it seems to  
duplicate all the functionality of Time#strftime.  I'm not sure how  
important it really is from the look of it.

> Could I request that if you are putting in docs that you explicitly
> caution users about the way this ZONES table is used, and the  
> effect it
> will have if, for example, you live in Australia or Brazil instead of
> North America (EST)?
>
>   http://en.wikipedia.org/wiki/Eastern_Standard_Time
>
> Information about landmines in an API are particularly useful to users
> of documentation, so if you have a bit more time to go through the  
> code,
> figure out what the effect of this magic handling of certain zone
> abbreviations is, and can describe it in the API documentaion, I think
> it would be very, very handy.

I'll look into it an submit another patch.

Did you use the patch I sent?  It's the first time I've used  
Eclipse's "create patch" utility, so I have no idea of it's  
effectiveness.  Lastly, is this list the right place to post it?  I  
sent to list and Gavin Sinclair on the last one (that's what the  
status page says to do).  Is Gavin the filter for all documentation?

Also, I felt like the contribution process was a little tricky and  
not very well described on ruby-doc.org.  I'd be happy to make a step  
by step once I know the process.  Would someone with access to ruby- 
lang be interested in such a thing?  It'd be great to get a little  
"Want to help?" link on the main page of ruby-doc.org with clear  
instructions.

Thanks,
Mat