From: Brian Candler <B.Candler@...>
Date: 2007-03-30T03:59:34+09:00
Subject: Re: Rdoc - ignores Rakefile & Rspecs

On Thu, Mar 29, 2007 at 08:35:25PM +0900, Suraj Kurapati wrote:
> 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

I live in *NIX land, and I would *not* expect rdoc to work that way. It has
to collate information from a whole series of different sources to build its
file, class and method indexes - basically it has to read and parse
everything before it can generate output. And it needs to know the names of
each of the source files to build the file index.

rdoc which worked on a single file would not be much like the current rdoc.

I think a summary of the problem is: you want rdoc to process a file as if
it were ruby source, but where it has no extension. Or: rdoc doesn't let you
specify on a file-by-file basis whether it's plain text or ruby source.
Correct?

A simple workaround, I think, is to rename Rakefile to Rakefile.rake
(or make a symlink from Rakefile.rake to Rakefile), and then use
rdoc -E rake=rb

> 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 is a completely different kettle of fish: it's a filter which
converts one blob of text into another blob of text. It's nothing to do with
redcloth being "new" and rdoc being "old".

Brian.