# Re: Rdoc with hyperlinks

**URL:** <https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/99113>\
**Category:** Ruby\
**Created:** [July 20, 2006, 11:17am UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/99113 "2006-07-20T11:17:11Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![daveh](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/85e7bf/32.png) [@daveh](https://www.ruby-forum.com/u/daveh)\
**Post date:** [July 20, 2006, 11:17am UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/99113/1 "2006-07-20T11:17:11Z")

</div>

On Jul 19, 2006, at 10:35, removed\_email\_address@domain.invalid wrote:

Dave H. wrote:

> > original source code file was.
> 
> Dave - I’m a little confused here. RDoc templates

(I assume you mean the actual generated documentation, not the template  
files used by RDoc when generating documentation)

> always have a link  
> to the files where the class comes from. However, the “file” pages  
> have no source code - only any file level RDoc, if there is any. But  
> RDoc must have the path to those files.

First, RDoc reads the actual source files, and constructs an internal  
data structure representing all the stuff it’s going to document.  
However, it does not include the path to the source file in the data  
structure itself. It does include a fragmentary relative path. Relative  
to RDoc at the time it ran, I think. It’s only useful for finding what  
subdirectory (if any) that particular source file is in, relative to  
the “home” directory for that gem, package, or whatever.

Once the structure is done (it’s parsed all the source files), then it  
starts constructing the documentation files. Since the data structure  
doesn’t include the full path of the original source file, the  
documentation can’t either. Until you apply my modifications.

> How would you modify RDoc to, instead of just including file level Rdoc  
> on file pages,

Huh? What do you mean by “file-level RDoc on file pages?”

RDoc pages do not have any links to the files where the class came  
from. They have links to the HTML documentation file that corresponds  
to the source file, as you mentioned above.

For example, if you go to Date, there’s a link in the upper right that  
says “In: date.rb”. It’s not linked to a file named “date.rb”, it’s  
linked to “date\_rb.html”. The full path is probably something like  
/usr/local/lib/ruby/1.8/doc/files/date\_rb.html.

If you’ve installed the modifications I posted, on THAT page there’s a  
link named “Source”. And it doesn’t link to an HTML page. It’s going to  
be something like file:///usr/local/lib/ruby/1.8/lib/date.rb; that is,  
it’s a link to the actual source file itself, not a copy for  
documentations’ sake.

> include the full, formatted, source of the file (just  
> like it does for methods)?

I wouldn’t. RDoc normally skips major amounts of the source; it doesn’t  
document private methods by default, and the Ruby 1.8.4 source install  
has .document files to instruct RDoc to completely ignore the majority  
of the code in the standard library. If you need more than just the  
method, you’ll probably need to look at a lot more than what RDoc would  
normally document anyway. That’s why the code I provided creates links  
to the actual production \*.rb files, not to \*.html files.

[Rather ironically, if you do the usual “./configure; make; make  
install” for the standard installation (including documentation) of  
Ruby 1.8.4, one of the things that _doesn’t_ get documented is . . .  
RDoc. ]

All RDoc does to code is embed it in HTML with some styles. An editor  
with code coloring should do the same (on OSX, I use TextWrangler,  
although rumor has it I could do even better). Or, if I pull it into  
XCode, I can get an index of the classes and methods and leap around  
the file by pulling them off the pop-down list.

I don’t know what your browser does when it gets a  
file:///…filename.rb URL. Mine (Safari) opens a Finder window with  
the file highlighted, ready to double-click open into an editor. I  
suspect Firefox would simply display it in a browser window as it would  
a text file, until/unless I changed the association. Perhaps you can  
teach your browser to open the file in a Ruby syntax-aware editor?