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

On Jul 24, 2006, at 23:48, Eric Hodel wrote:

> I started replying at the bottom of this email then came back to the 
> top.  Let me preface my entire response by saying your email has 
> rubbed me the wrong way.

My apologies for letting my puzzlement and frustration color my 
response.

> On this mailing list adding documentation to ruby is discussed, 
> patches are presented for review and so-on.  If you have issue with 
> missing documentation I suggest you put patches where your mouth is.

I intend to, but I'm also trying not to go off half-patched. I'm here 
in no small part because I was asked to submit my patch for adding the 
source-code path to the variables available in RDoc. I want my 
submission to be as useful and trouble-free as possible.

Should a patch submission for RDoc itself be posted here, in ruby-core, 
or somewhere else (or to someone else, I guess)?

>> Since getting RDoc to generate HTML documentation was nigh-impossible 
>> without instructions,
>
> rdoc --help is complete enough to tell you how to generate HTML.

I'm afraid I found that information insufficient for my needs. I 
couldn't find anything explaining what a 'template' was, for instance, 
until I finally stumbled across the folder of templates a couple of 
levels down in the RDoc folders. Perhaps this represents insufficient 
imagination or knowledge on my part.

>> 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?

> --- 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.


>> 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? 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?

> 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.

>> 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?

- * -

As a test, I created the following file, named "test.txt" (not 
including the line numbers):

	1)	== A header
  	2)
	3)	---
	4)
	5)	== The Other Header

I ran the following command in that directory:

	rdoc --fmt html --op test test.txt

And here is an excerpt of the contents of the file 
./test/files/test_txt.html, from the "banner header" comment to the "if 
method_list" comment:

   <!-- banner header -->

   <div id="bodyContent">



   <div id="contextContent">

     <div id="description">
       <h2>A header</h2>

     </div>


    </div>


   </div>


     <!-- if includes -->

     <div id="section">








     <!-- if method_list -->



Very mysterious.