Re: The Secret of RDoc HTML links.

On Jul 24, 2006, at 6:16 PM, Dave Howell wrote:

> On Jul 24, 2006, at 16:16, Eric Hodel wrote:
>
>>> [p.s. There's also the whole issue of SimpleMarkup's link markup,  
>>> but that's for a different message...]
>>
>> RDoc just linkifies http://...
>>
>> See: http://rdoc.sourceforge.net/doc/files/README.html
>
> Looks like the same readme that comes with RDoc itself. There's  
> nothing whatsoever on that page about how to . . . what the heck?
>
> Oh, that's really remarkable.

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.  I'm co-maintainer of RDoc, and de-facto  
documentation patch committer.  I appreciate patches, even patches  
with rants, much more than rants that imply I'm not doing something  
I've volunteered to do.

Continuing to write emails in this tone only serves to drive  
volunteers away.  When you're paying me my going rate to document or  
fix RDoc I'll find emails of this nature appropriate, but not when  
I'm doing this for my personal enjoyment during my highly valuable  
free time.  (Of course, after enough abuse, I may just quit.)

> So, first, if one installs Ruby, RDoc pointedly installs absolutely  
> no documentation about itself.

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.

> 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 eventually convinced it that maybe documenting itself would be a  
> good thing. I even suggested that it start its little section with  
> the README file. Which it did. Because it's kind of important to me  
> that I have documentation on my hard drive, linked together, ready  
> to to go without the requirement of having a live net connection  
> and putting up with the time delays inherent therein.
>
> Except that my local RDoc-processed HTML version of the README  
> conveniently stops right after "CREDITS". Thus eliminating all the  
> documentation for "USAGE" and "MARKUP". The stuff that, oh, you  
> know, explains how the heck markup's supposed to work.

These last two paragraphs only served the purpose of annoying one of  
the people most capable of helping you.

> It's the four hyphens that (according to the invisible  
> documentation) 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.

> And finally, although I have GREPped everything I can think of, I  
> can find absolutely no reference in any of the generator files to  
> Line::RULE. No "rule", no "line", no "<hr" command. Nothing in the  
> templates or in html_generator that would appear to in any way  
> translate from a Line::RULE structure into something that would  
> create a horizontal line in HTML.

--- generates a rule just fine, so long as you don't write a stopdoc  
when you meant to write an rule.

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

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.

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

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

http://trackmap.robotcoop.com