Dave Howell
7/19/2006 12:20:00 AM
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.