Eric Hodel wrote:
> On Mar 27, 2007, at 23:37, Larry Fast wrote:
> 
>> Is it possible to get Rdoc to generate information about  
>> Rakefiles?  It seems that I can't ask it to parse files that don't 
>> have an extension.
>
> As a workaround, move logic you want documented out of the Rakefile.

=begin
How long do we have to keep working around flaws in programs that are 
most central to the Ruby experience?  Why can't this be this fixed 
instead?  Although it was written by Dave Thomas and friends, rdoc is 
not perfect[1].  If this were 1997 instead of 2007, I'd bet this issue 
would be fixed almost instantaneously.
=end

It is understandable that rdoc ignores such files when it regresses 
directories automatically. That is, when it is run with either (1) no 
command-line arguments or (2) command-line arguments which are 
directories.

However, I think its file-extension based discrimination is implemented 
too strongly. So strongly, in fact, that it frustrates and alienates the 
user by counter-intuitively ignoring _explicitly_ specified command-line 
arguments.

For example, when I run

  rdoc foo_bar

I expect rdoc to parse the foo_bar file *indiscriminately* -- why does 
it care what file name I specify?  I, the user, a human being no less, 
have stated explicitly that I would like it to parse that file... it 
should *not* ignore me! :-(


Furthermore, rdoc does not operate on the standard input stream. I live 
in *NIX land, so it is reasonable for me to expect that rdoc would 
behave like a filter:

  cat foo_bar | rdoc

At least, it should accept '-' as an identifier for the standard input 
stream:

  cat foo_bar | rdoc -

In contrast, observe how newer tools (such as RedCloth) are 
indiscriminate to file extensions and play nicely with the standard 
input stream:

  % echo '*ruby*' | redcloth
  <p><strong>ruby</strong></p>

  % redcloth foo_bar # it doesn't care about file extension! :-)


[1] http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/130465
and http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/211297

-- 
Posted via http://www.ruby-forum.com/.