Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PLEASE make cross references actually work w/ ri #1097

Open
zenspider opened this issue Mar 14, 2024 · 6 comments · May be fixed by #1141
Open

PLEASE make cross references actually work w/ ri #1097

zenspider opened this issue Mar 14, 2024 · 6 comments · May be fixed by #1141

Comments

@zenspider
Copy link
Contributor

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
Copy link
Member

@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
Copy link
Contributor Author

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
Copy link
Member

@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
Copy link

jcoglan commented Jul 14, 2024

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
Copy link
Member

st0012 commented Jul 14, 2024

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

Screenshot 2024-07-15 at 00 08 51

and

Screenshot 2024-07-15 at 00 21 53

@st0012 st0012 linked a pull request Jul 15, 2024 that will close this issue
@adam12
Copy link
Contributor

adam12 commented Jul 15, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging a pull request may close this issue.

5 participants