[DOC] New file RI.md

[BurdetteLamar]

Replaces the very spare RI.rdoc with the robust RI.md.

This is meant for new or less-experienced RI users (who may have found this page in a browser search).

[peterzhu2118]

I find this document to be very wordy and repetitive. I have a few concerns:

1. Who is this targeted towards? Users of ri want a quick reference and are probably using the ri -h or the man ri documentation.
2. There are many repeated parts in this documentation. The "Class and Module Documents" section on line 326 is pretty similar to the "Ruby Class and Module Documents" section on 572. The documentation for static and interactive are very similar and are repeats of one another.

[BurdetteLamar]

1. Who is this targeted towards? Users of `ri` want a quick reference and are probably using the `ri -h` or the `man ri` documentation.

I'm thinking more of the new user (possibly the never-before-user). This content will need to be someplace where both the user and the search engines will find it.

An eventual aim is to show (in -h and --help) ri commands that will fetch relevant documentation.

I'd never heard of man ri. It's very old (and no doubt out-of-date). Seems to be actual source (not derived); is that right? I find that it's available on my Linux machine, but not on Windows; don't know about elsewhere.

[BurdetteLamar]

2. There are many repeated parts in this documentation. The "Class and Module Documents" section on line 326 is pretty similar to the "Ruby Class and Module Documents" section on 572. The documentation for static and interactive are very similar and are repeats of one another.

Some of the repetition arises from my misunderstanding about how many things are here. I'd thought four (class/page ruby/gem), but it may be more useful to think of two (class/page only). All classes (including gem classes) are already available in the class list; if we think of ruby: is a pseudo-gem, all pages are of one kind.

I'll look into how to avoid repetition between static/interactive.

[peterzhu2118]

I'd never heard of man ri. It's very old (and no doubt out-of-date). Seems to be actual source (not derived); is that right? I find that it's available on my Linux machine, but not on Windows; don't know about elsewhere.

I'm not sure what you mean by "actual source (not derived)". The source is in the file /man/ri.1. I think it's better to improve the man page rather than this document since man pages are the de facto way of reading the documentation for commands in Linux.

I'm not sure that it's out-of-date because the ri command hasn't really changed in the past few years.

[BurdetteLamar]

I'm not sure what you mean by "actual source (not derived)". The source is in the file /man/ri.1.

Just meant source text -- not derived from something else; e.g., .{html|ri} derived from .{c|rb|rdoc|md}.

I think it's better to improve the man page rather than this document since man pages are the de facto way of reading the documentation for commands in Linux.

I'm willing to work with the man page later on. This page RI.md (though it still needs major work) is for everyone, not just for those on Linux.

[BurdetteLamar]

Much more work to be done here, so marking as Draft and removing review requests.

[BurdetteLamar]

I have converted the links to markdown-style reference links:

• Those that have URLs work fine, both in the HTML and on the GitHub page.
• Those that have rdoc-ref work in the HTML, but not on the GitHub page.

I've experimented, and have found various forms that work on one or the other, but not on both.
Any hints, anyone?

[BurdetteLamar]

I have converted the links to markdown-style reference links:

* Those that have URLs work fine, both in the HTML and on the GitHub page.

* Those that have `rdoc-ref` work in the HTML, but not on the GitHub page.

I've experimented, and have found various forms that work on one or the other, but not on both. Any hints, anyone?

@colby-swandalem, any ideas about this?

[colby-swandale]

I have converted the links to markdown-style reference links:

• Those that have URLs work fine, both in the HTML and on the GitHub page.
• Those that have rdoc-ref work in the HTML, but not on the GitHub page.

I've experimented, and have found various forms that work on one or the other, but not on both. Any hints, anyone?

I'm a bit lost sorry, if having URLs works for both renders of the document, then that's a good thing right? What issues are there going this route?

[BurdetteLamar]

I have converted the links to markdown-style reference links:

• Those that have URLs work fine, both in the HTML and on the GitHub page.
• Those that have rdoc-ref work in the HTML, but not on the GitHub page.

I've experimented, and have found various forms that work on one or the other, but not on both. Any hints, anyone?

I'm a bit lost sorry, if having URLs works for both renders of the document, then that's a good thing right? What issues are there going this route?

@colby-swandale, do you mean the route of all-URL, no rdoc-ref? Would work for both, but:

• At a minimum would need to be added to the Documentation Guide; thoughts from the Guide guide @jeremyevans?

• At a maximum, would need to be put up as an issue for the dev meeting.

Alternatively, RDoc could in its RI output convert rdoc-refs to URLs? Out-of-scope for me, but possibly interesting.

[jeremyevans]

In general, rdoc-ref is useful because it makes the references internally consistent. If all references are to URLs, then there is no need for rdoc-ref, but if you are referencing something else in the documentation currently being generated, you want to use rdoc-ref as opposed to URLs. It's a shame GitHub doesn't handle rdoc-ref, but that's a GitHub issue, and I don't think we should avoid rdoc-ref just because GitHub doesn't render it correctly. The goal should be something that works best with rdoc/ri generated documentation.

[BurdetteLamar]

Maintainers @drbrain and @hsbt, this won't be merged without your blessing, or one from someone you designate. Can we proceed here?

[colby-swandale]

A few small nitpicks, but i think overall this is nearly ready!

[colby-swandale]

Is the use of \ necessary here as it's hard to tell what it's for? Should we perhaps be wrapping these in code blocks?

[BurdetteLamar]

This idiom is what I found that keeps the double-hyphen from converting to a dash. Also, if in code block, the token would not link, which I think matters.

[colby-swandale]

Let's see how the community reacts to this. If it's clear what the intention is, than great. Otherwise we will probably need to review the use of these.

[st0012]

This look similar to to https://github.com/ruby/rdoc/pull/1100/files#r1618865177

(by @colby-swandale)

Is the use of \ necessary here as it's hard to tell what it's for? Should we perhaps be wrapping these in code blocks?

[BurdetteLamar]

Same as there. Stet, I think.

[st0012]

IRB now has its own dedicated doc site, let's use it:

Suggested change

	[9]: https://docs.ruby-lang.org/en/master/IRB.html
	[9]: https://ruby.github.io/irb/

[BurdetteLamar]

I disagree. I'm writing for Ruby, and prefer to stay on its site when practicable.

[BurdetteLamar]

Maintainers @hsbt and @nobu: any comments on this PR?

[colby-swandale]

@BurdetteLamar 👋🏻 myself and @st0012 now have commit access to RDoc with the aim of becoming maintainers. I think we will be happy to merge this once the last of the feedback has been addressed.

Let me know if you have any questions!

[BurdetteLamar]

@BurdetteLamar 👋🏻 myself and @st0012 now have commit access to RDoc with the aim of becoming maintainers. I think we will be happy to merge this once the last of the feedback has been addressed.

Let me know if you have any questions!

Thanks, @colby-swandale. I'll try to sort out what's unaddressed. (Won't be easy, with conversation of 77 parts!)

[BurdetteLamar]

@colby-swandale and @st0012: anything more needed here?

[BurdetteLamar]

Can I get a review, an approval, or a merge here? (At this point, I'd almost settle for a close.)

[colby-swandale]

I apologise for the wait @BurdetteLamar, but I hope you can understand that we are busy with our lives and can only volunteer so much of our time.