On Wednesday, March 9, 2005, 9:57:59 AM, James wrote:
>> Yeah, but where do you stop? RI is clearly aimed at documenting
>> classes and methods. If it's to go beyond that to include ARGV etc.,
>> then you need a new rationale for it. Arbitrarily adding things makes
>> it difficult to remember what's in there and what's not.
> Isn't ARGV defined in a class or a module?
Dunno, got me there :)
[...]
>>
>> Beyond that, I'd recommend getting the FAQ in good condition and
>> offering a command-line interface to that, viz.
>>
>> $ rubyfaq ARGV
>> [shows all Q&A involving "ARGV"]
> Nice idea, though I tend not to think of inquiring about core syntax or
> expressions as a FAQ per se.
Good point. So probably copying Perl wholesale (perldoc/perlfaq ->
rubydoc/rubyfaq) is the best idea. I always thought they were great
features of Perl. It's just that the documentation itself is awful to
read because the language is so complex (e.g. references and objects).
Adapting these for Ruby would be easy, technologically. It's just the
content...
Thinking aloud, I suggest a single authoratitive online place
(ruby-doc.org?) where the content for rubydoc and rubyfaq are stored.
The command-line tools mirror that content locally, and run with an
--update flag whenever the user wants to. I'd rather not see content
dissemination locked in with Ruby releases. The content could also be
downloaded manually from the website and unpacked into the correct
place for those who would prefer that.
Of course, there's an existing Ruby FAQ online, but it's (by design)
chaotic. I'd prefer to see a FAQ equal in quality to the best in the
world, but maybe that's just me.
Any thoughts?
Gavin
|
