PLEASE make cross references actually work w/ ri

[zenspider]

9982 $ ri File.new | tail -6
Optional keyword arguments opts specify:

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


9983 $ ri rdoc-ref:IO@Open+Options
Nothing known about rdoc-ref
9984 $ ri rdoc-ref:encodings.rdoc@Encoding+Options
Nothing known about rdoc-ref

(Also, why are there 2 blank lines at the end of File.new output?)

or:

9989 $ ri Array#pack
= Array#pack

(from ruby core)
------------------------------------------------------------------------
  pack(template, buffer: nil) -> string

------------------------------------------------------------------------

Formats each element in self into a binary string; returns that string.
See {Packed Data}[rdoc-ref:packed_data.rdoc].


9990 $ ri rdoc-ref:packed_data.rdoc | head -1
Nothing known about rdoc-ref
9991 $ ri ruby:packed_data.rdoc | head -1
= Packed Data
9992 $ ri ruby:packed_data | head -1
= Packed Data

This just isn't right. rdoc-ref isn't a thing yet ri refers to it ALL OVER the place. There's not the faintest clue that ruby: is the correct prefix. Please make this tool usable again OR stop extracting the useful bits of the doco into cross referenced files that don't work.

[BurdetteLamar]

@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.

[zenspider]

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.

[BurdetteLamar]

@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.

[jcoglan]

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.

[st0012]

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

and

[adam12]

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.

[eregon]

I have noticed this issue as well and it's very inconvenient to look at the docs e.g. of Array#pack. I think the best fix would be to treat rdoc-ref like C's include for ri, i.e. immediately expand the contents inline.