From: Michal Suchanek <hramrach@...>
Date: 2009-10-07T03:59:05+09:00
Subject: Re: Ruby for the wrong reason

2009/10/6 7stud -- <bbxx789_05ss@yahoo.com>:
> James Edward Gray II wrote:
>> On Oct 6, 2009, at 1:16 AM, 7stud -- wrote:
>>
>>> No.  I think in ruby the code would be almost exactly the same--except
>>> it's significantly harder to figure out in ruby because there is no
>>> documentation about the format specifiers you can use with strftime()
>>> and strptime().  Amazing, huh?
>>
>> Amazingly wrong, yeah:
>>
>
> Not at all:
>
> 1) $ri Date::strptime
>
> --------------------------------------------------------- Date::strptime
>     Date::strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
> ------------------------------------------------------------------------
>     Create a new Date object by parsing from a String according to a
>     specified format.
>
>     +str+ is a String holding a date representation. +fmt+ is the
>     format that the date is in. See date/format.rb for details on
>     supported formats.
>
>     The default +str+ is '-4712-01-01', and the default +fmt+ is '%F',
>     which means Year-Month-Day_of_Month. This gives Julian Day Number
>     day 0.
>
>     +sg+ specifies the Day of Calendar Reform.
>
>     An ArgumentError will be raised if +str+ cannot be parsed.
> -----------------------------
>
> Good luck finding and then digging through the **source code** of
> format.rb to locate anything on the format specifiers.
>
>
> 2) $ri Date#strftime
>
> ---------------------------------------------------------- Date#strftime
>     strftime(fmt='%F')
> ------------------------------------------------------------------------
>     (no description...)
>
>
>
> And from the official Standard Library Documentation for 'date':
>
> 1)
> strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
> ----------------------------------------
>
> Create a new Date object by parsing from a String according to a
> specified format.
>
> str is a String holding a date representation. fmt is the format that
> the date is in. See date/format.rb for details on supported formats.
>
> The default str is ’-4712-01-01’, and the default fmt is ’%F’, which
> means Year-Month-Day_of_Month. This gives Julian Day Number day 0.
>
> sg specifies the Day of Calendar Reform.
>
> An ArgumentError will be raised if str cannot be parsed.
> =================
>
>
> 2)
> strftime(fmt='%F')
> --------------
> [Source]
>
> That last one is a real doozy--and quite typical of ruby Standard
> Library documentation.
>

In this case I use the strftime(3) man page but windows users are at a
disadvantage here.

The man pages can be found on the web, though.

And while there are things that could use better documentation there
is no need to replicate documentation of ancient function which is
standardized in POSIX and wherever else.

Thanks

Michal