Dave Howell
7/20/2006 9:16:00 AM
On Jul 19, 2006, at 10:35, listrecv@gmail.com wrote:
Dave Howell 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
(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?