OK, I’m probably being stupid here, but I’d appreciate being put right.
I’ve just started playing with rdoc, and have installed rdoc-0.9.0 under
ruby-1.8.0
Running rdoc on itself:
$ cd rdoc-0.9.0
$ rdoc
gives me ‘tokenstream.rb’ as the first page displayed when I view
index.html. Doing “rdoc --main rdoc/rdoc.rb” gives me that page instead. But
how do I get the README file as the front page?
If I try “rdoc --main README” then I get:
Generating HTML…
Could not find main page README
Could not find main page README
Could not find main page README
Could not find main page README
In fact, README does not appear under the ‘Files’ list in the generated HTML
at all.
And yet, rdoc’s own documentation at
http://rdoc.sourceforge.net/doc/index.html
manages to make the README the front page.
So what am I doing wrong…? It would certainly be useful if rdoc’s
documentation included the command to run to generate rdoc’s docs 
Cheers,
Brian.
Brian Candler wrote:
Running rdoc on itself:
$ cd rdoc-0.9.0
$ rdoc
gives me ‘tokenstream.rb’ as the first page displayed when I view
index.html. Doing “rdoc --main rdoc/rdoc.rb” gives me that page instead. But
how do I get the README file as the front page?
If I try “rdoc --main README” then I get:
Generating HTML…
Could not find main page README
Could not find main page README
Could not find main page README
Could not find main page README
In fact, README does not appear under the ‘Files’ list in the generated HTML
at all.
I think that by default, RDoc only processes the *.rb files it sees. So
in your case, you’re specifying that README should be the main page, but
since it doesn’t have a .rb extension it doesn’t get added to the file
list. Try:
rdoc --main README README rdoc
and see what happens.
Thank you for pointing me in the right direction. That misses EXAMPLE.rb, so
I tried
rdoc --main README README .
which gives more entries in the ‘Files’ section than the one on Dave’s
site, but at least I understand what I need to do.
I ran rdoc on some existing code of mine and got no comments - but I have
been using ‘=begin … =end’ rather than #'s in front of large blocks. Do
you know whether there’s a way to get it to process such things, or do I
need to reformat all my comments?
Cheers,
Brian.
···
On Fri, Aug 15, 2003 at 11:12:53PM +0900, Lyle Johnson wrote:
I think that by default, RDoc only processes the *.rb files it sees. So
in your case, you’re specifying that README should be the main page, but
since it doesn’t have a .rb extension it doesn’t get added to the file
list. Try:
rdoc --main README README rdoc
and see what happens.
Thank you for pointing me in the right direction. That misses
EXAMPLE.rb, so
I tried
rdoc --main README README .
which gives more entries in the ‘Files’ section than the one on
Dave’s
site, but at least I understand what I need to do.
Have a look at web/upload.sh for the command I issue to generate the
sample documentation. It’s more complex than you’d normally use,
because I wanted to show features without formatting up all the source
code’s documentation.
I ran rdoc on some existing code of mine and got no comments - but I
have
been using ‘=begin … =end’ rather than #'s in front of large blocks.
Do
you know whether there’s a way to get it to process such things, or do
I
need to reformat all my comments?
Right now it ignores =begin/=end - I once included them, but discovered
that
- It clashes with RD
- Some folks use =begin/=end to comment out large chunks of code.
I guess I could add an option to support them if there was a big-enough
need. What do folks think?
Dave
···
On Friday, August 15, 2003, at 09:23 AM, Brian Candler wrote:
Brian Candler wrote:
I ran rdoc on some existing code of mine and got no comments - but I have
been using ‘=begin … =end’ rather than #'s in front of large blocks. Do
you know whether there’s a way to get it to process such things, or do I
need to reformat all my comments?
Don’t know, you probably need to ask Dave (Thomas) about that one.
Actually not important to me now, I discovered that my RD-like comments at
the top of the file needed moving individually in front of each method
anyway…
Cheers,
Brian.
···
On Fri, Aug 15, 2003 at 11:38:36PM +0900, Dave Thomas wrote:
Right now it ignores =begin/=end - I once included them, but discovered
that
- It clashes with RD
- Some folks use =begin/=end to comment out large chunks of code.
- Some folks use =begin/=end to comment out large chunks of code.
I guess I could add an option to support them if there was a big-enough
need. What do folks think?
The =begin, =end can be followed by a string. What about
=begin rdoc
…
=end rdoc
for comments that are not necessarily in RDtool format?
Dave
Hugh
···
On Fri, 15 Aug 2003, Dave Thomas wrote:
No, there isn’t - at the time, there was a lot of rd documentation out
there in =begin comments, so I decided to ignore them.
If there’s a lot of demand I could add support, I guess…
···
On Wednesday, Sep 17, 2003, at 10:30 US/Central, Lyle Johnson wrote:
Brian Candler wrote:
I ran rdoc on some existing code of mine and got no comments - but I
have
been using ‘=begin … =end’ rather than #'s in front of large
blocks. Do
you know whether there’s a way to get it to process such things, or
do I
need to reformat all my comments?
Don’t know, you probably need to ask Dave (Thomas) about that one.
That’s usually the case. If you just so happen to write a program to
do hte conversion for you, please share 
Gavin
···
On Saturday, August 16, 2003, 2:27:10 AM, Brian wrote:
On Fri, Aug 15, 2003 at 11:38:36PM +0900, Dave Thomas wrote:
Right now it ignores =begin/=end - I once included them, but discovered
that
- It clashes with RD
- Some folks use =begin/=end to comment out large chunks of code.
Actually not important to me now, I discovered that my RD-like comments at
the top of the file needed moving individually in front of each method
anyway…