From: Dave Howell <groups@...>
Date: 2006-07-19T09:19:44+09:00
Subject: Re: Rdoc with hyperlinks


On Jul 18, 2006, at 8:05, listrecv@gmail.com wrote:


Ken Bloom 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
	      <td>%full_path%  [<a href="%source_path%">Source</a>]

Another possible place to add a link is inside the pop-up source code 
pages. Find SRC_PAGE, and change
	<body class="standalone-code">
	  <pre>%code%</pre>
	</body>
to
	<body class="standalone-code">
		<div style="text-align: right;">Open <a 
href="%source_path%">%source_file%</a></div>
		<pre>%code%</pre>
	</body>
or something along those lines.