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