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?
ยทยทยท
On Jul 19, 2006, at 10:35, listrecv@gmail.com wrote: