# Re: Rdoc with hyperlinks

**URL:** <https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921>\
**Category:** Ruby\
**Created:** [July 19, 2006, 2:21am UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921 "2006-07-19T02:21:05Z")\
**Posts on this page:** 9\
**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 19, 2006, 2:21am UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/1 "2006-07-19T02:21:05Z")

</div>

On Jul 18, 2006, at 8:05, removed\_email\_address@domain.invalid wrote:

Ken B. wrote:  
In general, you should not rely on knowledge of the source code to  
understand how a library works, because the library writer reserves  
the right to change the behavior of things that are not specified in  
the documentation.

Ken - I certainly agree in theory. However, in practice, that is often  
the only way to understand most Ruby libs.

No kidding.

OK, I gritted my teeth and ignored you the first time I saw your  
request, but this time I couldn’t let it go. Took almost five hours to  
solve. Sigh.

There’s a very good reason you couldn’t figure out how to do it by  
looking at the RDoc source. The necessary path simply isn’t available;  
by the time RDoc is generating output, it no longer knows where the  
original source code file was.

Make the following changes to files in …/lib/rdoc

```
code_objects.rb:
Insert at line 467
     attr_accessor :source_path
Insert at line 483
     @source_path = File.join(Dir.getwd,file_name)

```

This will modify class TopLevel so it looks like this:

class TopLevel \< Context  
attr\_accessor :file\_stat  
attr\_accessor :file\_relative\_name  
attr\_accessor :file\_absolute\_name  
attr\_accessor :source\_path  
attr\_accessor :diagram

```
 @@all_classes = {}
 @@all_modules = {}

 def TopLevel::reset
   @@all_classes = {}
   @@all_modules = {}
 end

 def initialize(file_name)
   super()
   @name = "TopLevel"
   @file_relative_name = file_name
   @file_absolute_name = file_name
   @source_path = File.join(Dir.getwd,file_name)
   @file_stat = File.stat(file_name)
   @diagram = nil
 end

```

Make the following changes to generators/html\_generator.rb  
Insert at line 877  
@values[“source\_path”] = CGI.escapeHTML(@context.source\_path)  
Change line 1031 from  
‘charset’ =\> @options.charset  
to  
‘charset’ =\> @options.charset,  
‘source\_path’=\> @context.parent.toplevel.source\_path,  
‘source\_file’=\> @context.parent.toplevel.file\_relative\_name

The first addition makes the “%source\_path%” variable available for  
most of the templates by changing HtmlFile::file\_attribute\_values to  
look like

```
   @values["short_name"] = CGI.escapeHTML(short_name)
   @values["full_path"] = CGI.escapeHTML(full_path)
   @values["source_path"] = CGI.escapeHTML(@context.source_path)
   @values["dtm_modified"] = @context.file_stat.mtime.to_s

```

The second makes the new source\_path available for the pop-up source  
code windows, by modifying HtmlMethod::create\_source\_code\_file to look  
like this:

```
def create_source_code_file(code_body)
   meth_path = @html_class.path.sub(/\.html$/, '.src')
   File.makedirs(meth_path)
   file_path = File.join(meth_path, @seq) + ".html"

   template = TemplatePage.new(RDoc::Page::SRC_PAGE)
   File.open(file_path, "w") do |f|
     values = {
       'title' => CGI.escapeHTML(index_name),
       'code' => code_body,
       'style_url' => style_url(file_path, @options.css),
       'charset' => @options.charset,
       'source_path'=> @context.parent.toplevel.source_path,
       'source_file'=> @context.parent.toplevel.file_relative_name
     }
     template.write_html_on(f, values)
   end
   HTMLGenerator.gen_url(path, file_path)
 end

```

Finally, you need to edit whatever HTML template you’re using. If  
you’re using the default HTML template  
(generators/templates/html/html.rb) you might want to find the  
FILE\_PAGE and change

```
      <td>%full_path%

```

to

%full\_path% [Source]

Another possible place to add a link is inside the pop-up source code  
pages. Find SRC\_PAGE, and change

```
%code%
```
  
  
to  
  

Open %source\_file%
  

```
%code%
```
  
  
or something along those lines.

---

<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 19, 2006, 7:37pm UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/2 "2006-07-19T19:37:04Z")

</div>

Dave H. wrote:

> OK, I gritted my teeth and ignored you the first time I saw your  
> request, but this time I couldn’t let it go. Took almost five hours to  
> solve. Sigh.

Thanks, greatly appreciated!

> There’s a very good reason you couldn’t figure out how to do it by  
> looking at the RDoc source. The necessary path simply isn’t available;  
> by the time RDoc is generating output, it no longer knows where the  
> original source code file was.

Dave - I’m a little confused here. RDoc templates 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.

How would you modify RDoc to, instead of just including file level Rdoc  
on file pages, include the full, formatted, source of the file (just  
like it does for methods)?

---

<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, 7:46pm UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/3 "2006-07-20T19:46:27Z")

</div>

On Jul 18, 2006, at 5:19 PM, Dave H. wrote:

> Make the following changes to files in …/lib/rdoc

Can you turn this into a patch?

–  
Eric H. - removed\_email\_address@domain.invalid - [http://blog.segment7.net](http://blog.segment7.net)  
This implementation is HODEL-HASH-9600 compliant

[http://trackmap.robotcoop.com](http://trackmap.robotcoop.com)

---

<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 21, 2006, 4:56am UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/4 "2006-07-21T04:56:02Z")

</div>

On Jul 20, 2006, at 5:47 PM, Dave H. wrote:

> Slightly longer answer: “Um, I dunno. What kind of a patch, to be  
> applied with what tool? I’ve never made a patch. Is it hard?”

One way:

diff -u your\_version\_with\_changes.rb original\_version.rb \> your.patch

If you changed more than one file I would suggest

diff -u your\_version\_of\_whole\_src\_tree\_directory  
original\_version\_of\_source\_tree\_directory \> your.patch

the people who ask for patches will know how to use the patch tool to  
apply it.

---

<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:48pm UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/5 "2006-07-20T23:48:42Z")

</div>

On Jul 20, 2006, at 10:43, Eric H. wrote:

> On Jul 18, 2006, at 5:19 PM, Dave H. wrote:
> 
> > Make the following changes to files in …/lib/rdoc
> 
> Can you turn this into a patch?

Short answer: “no”.

Slightly longer answer: “Um, I dunno. What kind of a patch, to be  
applied with what tool? I’ve never made a patch. Is it hard?”

---

<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 21, 2006, 4:59am UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/6 "2006-07-21T04:59:11Z")

</div>

On Jul 20, 2006, at 10:53 PM, Logan C. wrote:

> > > Can you turn this into a patch?
> 
> diff -u your\_version\_with\_changes.rb original\_version.rb \> your.patch
> 
> If you changed more than one file I would suggest
> 
> diff -u your\_version\_of\_whole\_src\_tree\_directory  
> original\_version\_of\_source\_tree\_directory \> your.patch
> 
> the people who ask for patches will know how to use the patch tool  
> to apply it.

Ack!!! I lied. I always mix that up.

its diff -u original your\_version

Sorry :(.

---

<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 21, 2006, 4:43pm UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/7 "2006-07-21T16:43:39Z")

</div>

On 7/20/06, Logan C. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> > > >
> > 
> > One way:
> 
> Ack!!! I lied. I always mix that up.
> 
> its diff -u original your\_version
> 
> Sorry :(.

If making a patch between two directory trees, you’ll also need the -r  
option:

diff -ur foo\_original foo\_modified \> foo\_mychanges.patch

—John

---

<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 21, 2006, 10:20pm UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/8 "2006-07-21T22:20:40Z")

</div>

I think we should have options for linking to the actual file (in the  
original source), a rdoc highlighted html copy, or both.

---

<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 21, 2006, 6:54pm UTC](https://www.ruby-forum.com/t/re-rdoc-with-hyperlinks/98921/9 "2006-07-21T18:54:29Z")

</div>

On Jul 20, 2006, at 7:53 PM, Logan C. wrote:

> > applied with what tool? I’ve never made a patch. Is it hard?"  
> > the people who ask for patches will know how to use the patch tool  
> > to apply it.

The easiest way is to check out ruby from CVS:

[http://www.ruby-lang.org/en/20020106.html](http://www.ruby-lang.org/en/20020106.html)

Make your changes, test them, then run cvs diff -u and send the  
output to me.

–  
Eric H. - removed\_email\_address@domain.invalid - [http://blog.segment7.net](http://blog.segment7.net)  
This implementation is HODEL-HASH-9600 compliant

[http://trackmap.robotcoop.com](http://trackmap.robotcoop.com)