@zenspider, I've been aware of this issue, and agree that it would be good for RDoc to do better.

Meanwhile, I have been working on some enhanced documentation for ri (not yet in a PR), and have planned to include some advice about how to mentally 'translate' an rdoc-ref passage into a useful ri command that the reader can type to see the linked doc in ri. This will include advice about class/module, method, and page (such as ruby:) both in Ruby itself and in a gem.

Optional keyword arguments opts specify:

* {Open Options}[rdoc-ref:IO@Open+Options].
* {Encoding options}[rdoc-ref:encodings.rdoc@Encoding+Options].


9993 $ ri rdoc-ref:IO@Open+Options
Nothing known about rdoc-ref

This is unusable. Period. I don't want to "mentally translate it", I want it to work. If I'm supposed to type X to get information, then it should output X, not Y. If that means that all of the xrefs in the documentation need to be changed, then so be it. If it isn't copy/paste-able then it isn't working.

@zenspider, fixing this is out of scope for me (primarily a documentor, not a developer); best I can do is put a workaround in the documentation.

Personally, I think the cut-and-paste is also inadequate; generated RI should have maximal http(s) URLs (not rdoc-refs), which I find in several command windows are recognized as URLs and can be opened with Ctrl-click.

I would personally regard printing URLs as a regression. The point of ri is that it makes the docs available in the terminal and does not require a separate application, itself requiring a desktop environment and an internet connection, to be usable. The best-case outcome here is that references printed by ri can themselves be passed as arguments to ri and return the intended content.

I'm prototyping a feature to expand all the rdoc-refs after the main document, like:

and

I'm prototyping a feature to expand all the rdoc-refs after the main document, like:

This seems like a decent approach. I was going to suggest we scaled back on the number of rdoc-ref usages but this might be a nice compromise.