Problem setting main file for rdoc

[James Britt]

I'm running ruby 1.8.2 (2004-07-29) [i386-mswin32] with RDoc V1.0pr1:
2004/04/04 23:19:58 (1.1.2.6) on Win2k.

My project layout has the main code in lib\OOo4R, I want my docs in
doc\, and I want the main doc file to be lib\OOo4R\OOo.rb, so from the
root directory of my project I ran


D:\development\RubyForge\ooo4r>rdoc -m lib\OOo4R\OOo.rb lib\OOo4R

It creates the rdoc files fine, so it has no problem finding the
lib\OOo4R directory, but I get these messages along the way:

Generating HTML...
Could not find main page lib\OOo4R\OOo.rb
Could not find main page lib\OOo4R\OOo.rb
Could not find main page lib\OOo4R\OOo.rb
Could not find main page lib\OOo4R\OOo.rb

But it finds that file well enough to doc it along with the other files
in the given path.

If I leave off the directory path and just give the file name (OOo.rb),
I get a similar set of messages. Using a complete file path doesn't
help; neither does full-path using unix-style forward slashes.

The rdoc help just says
--main, -m name 'name' will be the initial page displayed

but says nothing about specifying the path to the file.

(I'm guessing that 'name' refers to the name of the source file, though
I suppose it could mean the name of the generated page, or the name of a
class or module.)

What's the correct syntax?


Thanks,


James

 

[Dave Thomas]

D:\development\RubyForge\ooo4r>rdoc -m lib\OOo4R\OOo.rb lib\OOo4R

Try using the name of a class in the main file.

Cheers

Dave

 

[James Britt]

Try using the name of a class in the main file.

I got it working by using
rdoc -m OOo:oc lib\OOo4R

Thanks; there is no way I would have guessed this from the rdoc
command-line help, though.

Suppose I want to have a general-info page (e.g. README.rdoc) be the
main page, or if several files define different parts of the same class?

Is there some way to simply say, "Rdoc this arbitrary file and set it
as the main page"?


Thanks,

James

 

[Dave Thomas]

Is there some way to simply say, "Rdoc this arbitrary file and set it
as the main page"?

Does putting it as the first file on the command line not work?

Cheers

Dave

 

[James Britt]

Does putting it as the first file on the command line not work?

That was what I was trying at first. There is a specific Ruby source
file I wanted to serve as the main doc page, so passed the path as the
first file. But none of the paths made rdoc happy.

Passing in the name of a class worked, but that likely won't help for a
general text file.

As an experiment, I tried to specify a file in the current directory
(while rdocing code in a subdirectory):

rdoc -m README.txt lib\OOo4R

The file README.txt exists in the current directory, but rdoc reports
that it cannot find it.

rdoc -m ./README.txt lib\OOo4R

doesn't work either (nor .\README.txt). Even passing in the complete
windows file path does not help.

But, on re-reading your suggestion, I tried again, omitting the -m and
just passing in the relative path to README.txt as the first argument.

This works, but seems a little counter-intuitive, given that the
command-line help says to use " -m name " to set the initial page

My understanding now is to use "-m fully_qualified_name_of_class" to
have the file defining that class appear as the initial page, or leave
out the -m and just pass the path to the disk file to be used (after
rdoc'ing) as the initial file.

Question: If I pass rdoc a complete list of files, rather than a
directory, will the files appear in list order in the Files frames?

That could be handy for pushing boring, least-used docs to the bottom.


Thanks,


James

 

[Dave Thomas]

That was what I was trying at first. There is a specific Ruby source
file I wanted to serve as the main doc page, so passed the path as the
first file. But none of the paths made rdoc happy.

rdoc -m README.txt lib\OOo4R

The first regular file is the main file in the absence of a -m

rdoc README.txt lib\OOo4R

This works, but seems a little counter-intuitive, given that the
command-line help says to use " -m name " to set the initial page

The doc also says that the first file is the deault main file.,,

Cheers

Dave

 

[James Britt]

The doc also says that the first file is the deault main file.,,

Does this appear in the command line help?

I don't see it when I run rdoc -help, though maybe I'm just misreading it.


Thanks,


James