rdoc and hyperlinks

[Joel VanderWerf]

For some reason, my rdoc installation isn't generating hyperlinks for
file names. I seem to remember that this used to work, but now this
simple example:

==== t.rb ====
# See docs/file.txt
class MyClass
end
==============

leads to just plain text in the html, not a hyperlink. Rdoc is
definitely aware of docs/file.txt, and is generating the expected html
for it, and listing it in the "files" frame. I have a pretty recent
version of rdoc:

$ rdoc -v
RDoc V1.0pr1: 2004/01/02 05:59:48 (1.2)

Should this be working?

 

[Joel VanderWerf]

Ack, forget this.

I found the docs. link:// is needed to make it realize its a hyperlink
to a local file.

Well, that does _something_. It can be used to link to a file, which is
displayed in my browser as plain text. But I'd really rather link to one
of the files that I've marked up with the rdoc notation and which rdoc
has generated HTML for and which shows up in the Files frame.

The Rdoc readme says:

7. Names of classes, source files, and any method names
containing an underscore or preceded by a hash
character are automatically hyperlinked from
comment text to their description.

I was hoping that this meant that you could link to the HTML output file
generated from one of your input files. If a file named "doc/info.txt"
is listed in the Files frame, then it would be nice if all uses of that
string were hyperlinked in the same way as in the File frame.

 

[Joel VanderWerf]

I found that this works, sort of:

link:files/doc/my_file_txt.html

if I have a file named doc/my_file.txt (relative to the dir I run rdoc
in). The -o dir is 'doc/api/'.

The problem is that the link is displayed in my browser as

my_file_txt.html

but I'd really prefer

doc/my_file.txt

I tried using the label[link:...] construct to control this, but that
just confused my browser.

If I use the label[file:...] construct, relative file paths never seem
to work, no matter where I start them from.

Actually,

my_file[file:my_file_txt.html]

works in mozilla but not in konqueror. Go figure...

 

[Dave Thomas]

I found that this works, sort of:

link:files/doc/my_file_txt.html

I've been looking at this, but it turns out to be somewhat harder that
it should be. The issue is one of relative file paths. In order to do
the hyperlinking, RDoc has to read all the source and then generate the
HTML (because there may be references to classes that haven;t been read
yet in early files). However, that also means that one class may be
defined in multiple files. The way RDoc builds its information about
class and module documentation, I can't tell which particular file a
comment came from. Instead, I just know the list of files that
contribute to the class the comment is associated with.

However, when you say doc/my_file.rb, I need to see if I know anything
about a file called 'my_file.rb' in the doc subdirectory or the
directory containing the file containing the comment (phew!). I just
don't have that information.

I'm looking to see what it would take to add it, but I'm also worried
about performance: with a large number of files and the potential for
large numbers of spurious matches on things that look like file names,
this could get slow.


Cheers

Dave

 

[Joel VanderWerf]

I've been looking at this, but it turns out to be somewhat harder that
it should be. The issue is one of relative file paths. In order to do
the hyperlinking, RDoc has to read all the source and then generate the
HTML (because there may be references to classes that haven;t been read
yet in early files). However, that also means that one class may be
defined in multiple files. The way RDoc builds its information about
class and module documentation, I can't tell which particular file a
comment came from. Instead, I just know the list of files that
contribute to the class the comment is associated with.

However, when you say doc/my_file.rb, I need to see if I know anything
about a file called 'my_file.rb' in the doc subdirectory or the
directory containing the file containing the comment (phew!). I just
don't have that information.

I'm looking to see what it would take to add it, but I'm also worried
about performance: with a large number of files and the potential for
large numbers of spurious matches on things that look like file names,
this could get slow.

Sounds painful, and not worth the effort. As a workaround, how about
some way of relabeling a link: entry? Something like:

label[link:files/doc/my_file_txt.html]

which would behave just like

link:files/doc/my_file_txt.html

(which works now) but would look like

label

in the browser?

 

[Dave Thomas]

Sounds painful, and not worth the effort. As a workaround, how about
some way of relabeling a link: entry? Something like:

label[link:files/doc/my_file_txt.html]

which would behave just like

link:files/doc/my_file_txt.html

Oh.. I always thought that link: already worked in a tidylink, but
you're right. It didn't.

It should work now.


Cheers

Dave