rdoc links differ between generated docs and github

From our conversation on irc:

15:01 < zzak> rdoc links, how do they work?
15:01 < injekt> magick
15:01 < drbrain> true fact
15:02 < drbrain> the extensive array of tests serve only to keep the magic working, not to explain it
15:02 < zzak> i currently dont know a way to link to a static file that works both in rdoc and on github
15:02 < drbrain> zzak: I think github uses rdoc 1.x-based processing code
15:02 < zzak> github suggestions [link: to/file]
15:03 < zzak> but this doesn't work with rdoc > 3.x
15:04 < zzak> it kills me that rake's readme direct links to the ./doc/* files on master branch
15:04 < zzak> and also there are broken links in rails/rails#readme
15:05 < drbrain> yeah, but I don't worry about it too much since ruby-doc.org is the primary place to read documentation from, github is for more for ruby contributors
15:07 < zzak> but anyone reading about Rake on there will be directed to master branch on github for the other static files
15:08 < drbrain> yeah :/
15:08 < zzak> not everyone is using master tho :(
15:09 < zzak> if only :rdoc-ref: worked on github
15:11 < zzak> drbrain: do you have any other ideas around this?
15:11 < zzak> i dont even know if i'd consider it an rdoc bug
15:12 < drbrain> I don't think rdoc-ref can work on github, it won't know about --page-dir
15:12 < drbrain> I think a solution can be found, but I'm not sure what it would be at this time
15:13 < drbrain> I should probably make link: work better in the face of --root and --page-dir
15:13 < drbrain> I have a feeling that rdoc-ref is a poor design, but I haven't yet figured out a better way

Start by investigating RDoc's link: handling with --root and --page-dir, and compare it with rdoc-ref and GitHub's link processing. Reproduce the differing links in generated documentation and on GitHub; done means a documented approach or resolved behavior that works in both environments.