Re: The RDoc Hyphen Anomaly (was Re: RDoc HTML links.)

On Jul 25, 2006, at 10:34, Eric Hodel wrote:

> When you put in flush-left hyphens you are writing a stopdoc.  If you 
> have whitespace before them you should get a Rule.  This works inside 
> ruby comments, if it doesn't work inside plain files then that would 
> be a bug, but I doubt anybody knew about it.

Eureka.

OK, I can now officially report A Bug. A line with whitespace and 
hyphens (that is, /^\s+\-{2,}/) in a plain text file does not generate 
a horizontal rule. It appears that it gets interpreted as code, to be 
displayed verbatim.

I don't know if I'm going to try to figure out how to patch that bug, 
though, because that feels like it will require going awfully deep into 
the mysteries in the bowels of RDoc. My higher priority item is 
building the .document file for RDoc.


Of course, since it turns out that RDoc was reading the "----" in the 
README file as a stopdoc, and that this is what it's supposed to do, 
then the question arises, "Why is there a stopdoc in the README file?" 
Apparently it wasn't originally a stopdoc, because the '02 version on 
the web shows a horizontal line. Maybe the --/++ forms of stop/start 
doc were added later, and nobody noticed this messed up the README 
file, since (as observed earlier), the docs aren't even generated with 
a normal install.


Therefore, I'd like to report a second bug. In the README file that was 
distributed in Ruby 1.8.4, and which I strongly suspect is still part 
of the code tree, line 85 should be changed from "----\n" to " ----\n". 
While this won't generate a horizontal line until the first bug is 
fixed, it WILL avoid suppressing all the other rather useful and 
relevant information contained in that file.