[DOC] New file RI.md

[BurdetteLamar]

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

[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]

@nobu, I have removed section "Pager Options" and slightly revised section "Output Filters"; I think this accommodates your comment.

[BurdetteLamar]

@peterzhu2118, if this PR does not interest you, I can try to find another primary reviewer.

[peterzhu2118]

Sorry, I've been very busy recently with various things at work and this PR is very large, so I haven't been able to spend enough time on this. I will try to look at this when I have time, but I can't guarantee when that will be.

[BurdetteLamar]

Sorry, I've been very busy recently with various things at work and this PR is very large, so I haven't been able to spend enough time on this. I will try to look at this when I have time, but I can't guarantee when that will be.

All good, Will be away through April 20 (celebrating 25th wedding anniversary).

[BurdetteLamar]

@peterzhu2118 said:

Alternatively, what do you think about removing the table and instead moving the headings for each table as headings for each command?

Done.

[BurdetteLamar]

@peterzhu2118, do we need to hear from a maintainer (@drbrain or @hsbt) before merging?

[BurdetteLamar]

@peterzhu2118, will you be reviewing this?

[peterzhu2118]

I think this looks good, but I would like one of the maintainers to give input before merging.

[BurdetteLamar]

I think this looks good, but I would like one of the maintainers to give input before merging.

Agreed. @drbrain and @hsbt, can you review or recommend a reviewer?

[BurdetteLamar]

@drbrain and @hsbt: Are you at all interested in this work? If so, will you (or someone you suggest) be reviewing? If not, I think no one should spend more time on this.

[BurdetteLamar]

Thanks much, @colby-swandale! I'll work with the links.

(I have done some other .md pages that will also need attention.)

[BurdetteLamar]

Marking as draft while I work on the links (etc.).

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