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

On Jul 25, 2006, at 3:24 AM, Dave Howell wrote:

> On Jul 24, 2006, at 23:48, Eric Hodel wrote:
>
> Should a patch submission for RDoc itself be posted here, in ruby- 
> core, or somewhere else (or to someone else, I guess)?

For changes/fixes to RDoc itself, ruby-core.

>>> It's the four hyphens that are supposed to create a horizontal  
>>> line. There's no error, it just stops processing everything below  
>>> it. When I took out the hyphens, then it ran the whole file.
>>
>> No, those four hyphens aren't supposed to do that.
>
> Aren't supposed to . . . cut off the rest of the file, or aren't  
> supposed to generate a horizontal line?

Hyphens flush left aren't supposed to create a rule.

>> --- generates a rule just fine, so long as you don't write a  
>> stopdoc when you meant to write an rule.
>
> Well, in this case the file in question is the README file that  
> arrived inside my Ruby-1.8.4 archive. I don't think anybody put a  
> stopdoc (which would resemble :stopdoc:, yes? no?) in the file. I  
> did try three hyphens instead of four, and I used the default  
> template. Well, actually, I simply failed to specify a template,  
> which I believe gets me the default. The results were the same.  
> Three hyphens suppressed the output of the contents that followed  
> them.

/^\+{2,}/ and /^-{2,}/ are also startdoc/stopdoc.

>>> So the questions for THIS message are, were there known bugs in  
>>> the RDoc released with Ruby 1.8.4?
>>
>> If you're alluding to the hr problem, there is no bug there.  RDoc  
>> is being 100% faithful to its design.  (Being a very complicated  
>> piece of software, and not being its original author, no I don't  
>> have a spec, so don't ask.  If you write it, I'll accept it for  
>> inclusion as a patch.)
>
> Well, there's a bug HERE. Of some kind. When you say "the hr  
> problem...RDoc is being faithful to its design", am I to understand  
> that four hyphens are another way of coding a stopdoc?

Flush left hyhens are a stopdoc.

> If that's not what you mean, then I'm just not keeping up with you  
> here. RDoc is demonstrating its faithfulness by doing . . . what?

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.

>> Also, if you have problems with the quality of a software product  
>> largely built by volunteers I suggest you respond with clear bug  
>> reports and/or patches rather than insults, no matter how well  
>> veiled.
>
> OK. First I want to figure out if this is a bug, a hole in the  
> docs, or just user error. If a bug, then I will do my best to fix  
> it. Since I'm currently running 1.8.4, and the code's somewhere  
> north of 1.9, I wanted to make sure I wasn't trying to fix a bug  
> that somebody already fixed a long time ago. I take it the answer  
> is "no." At this point I guess I'll unpack a brand-new copy of  
> 1.8.4, compile it, and see if I get the same results as I do with  
> my current copy.

I have a CVS checkout of HEAD and ruby_1_8, if you can reproduce the  
bug in 1.8.4, be sure to also check against at least ruby_1_8 and HEAD.

>>> Does anybody have a valid HTML template that DOES provide control  
>>> over horizontal lines? (There's an <hr... command in the version  
>>> on rubyforge, for example, although it's also dated January 24,  
>>> 2003.)
>>
>> Rules work just fine with the default template.
>
> Well, aside from the fact that they're not doing that here in this  
> particular file, that wasn't actually my question. Allow me to  
> rephrase it, with fewer grating overtones: I cannot figure out how  
> RDoc turns a "Line::RULE" object into an "<hr>" command. I grepped  
> for both the name of the object and the expected HTML in the entire  
> RDoc code tree (a couple of different ways), but the answer eludes  
> me. Can somebody give me a pointer toward the relevant code or  
> templating?

It is in SimpleMarkup.

> [attempt at generating a rule]

I did it this way:

$ cat x.rb
##
# Some class
# ---
# blah
#--
# FIXME yeah, and stuff

class Some
end
$ rdoc x.rb

                                x.rb: c
Generating HTML...

Files:   1
Classes: 1
Modules: 0
Methods: 0
Elapsed: 0.147s
$ grep '<hr' doc/classes/Some.html
<hr size="1"></hr><p>
$ grep 'FIXME' doc/classes/Some.html
$

-- 
Eric Hodel - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com