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 - drbrain@xxxxxxxxxxxx - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant
http://trackmap.robotcoop.com
|
