[DOC] New file RI.md #1100

BurdetteLamar · 2024-03-22T16:36:41Z

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:

Who is this targeted towards? Users of ri want a quick reference and are probably using the ri -h or the man ri documentation.
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.

RI.md

BurdetteLamar · 2024-03-29T17:11:11Z

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 · 2024-03-29T17:15:23Z

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 · 2024-03-31T01:59:25Z

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 · 2024-03-31T16:57:35Z

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 · 2024-04-01T16:43:58Z

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

RI.md

peterzhu2118 · 2024-04-12T19:56:26Z

RI.md

+| 'IO#readlines'                       | Document for RUbyinstance method IO::readlines.                                  |
+| 'IO.readlines'                       | Documents for Ruby instance method IO::readlines and class method IO::readlines. |
+| '::readlines'                        | Documents for all class methods ::readlines.                                     |
+| '#readlines'                         | Documents for all instance methods #readlines; see note below.                   |


Can we just include the note here inline? It doesn't seem to be referred by anything else.

Inline note would be (IMO) too big for a table cell; I have just omitted it entirely.

The "see note below" part hasn't been removed.

Removed.

RI.md

peterzhu2118 · 2024-04-12T20:15:19Z

RI.md

+
+See also {ri at the Ready}[rdoc-ref:RI.md@ri+at+the+Ready].
+
+## Shell Quoting or Escaping


I don't think we need this section. We can briefly mention it in the "static mode" section, but the user should know what needs escaping and what doesn't for their shell.

RI.md

peterzhu2118 · 2024-04-12T20:25:21Z

RI.md

+| --server=NUMBER | Set port for RDoc server; default is 8214. |
+<br>
+
+### \Options Details


Many of the entries in this section are basically the exact same description as the table above and don't offer any additional details.

I'm reluctant to remove just some of these (the ones that don't contribute). Leaving all of them in has the virtue of their showing in the TOC (for quick user nav).

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

RI.md

peterzhu2118 · 2024-04-14T17:29:41Z

RI.md

+| Name                                 | Shows                                                                            |
+|--------------------------------------|----------------------------------------------------------------------------------|
+| 'IO::readlines'                      | Document for Ruby class method IO::readlines.                                    |
+| 'IO#readlines'                       | Document for RUby instance method IO::readlines.                                 |


peterzhu2118 · 2024-04-14T17:30:35Z

RI.md

+| 'IO#readlines'                       | Document for RUbyinstance method IO::readlines.                                  |
+| 'IO.readlines'                       | Documents for Ruby instance method IO::readlines and class method IO::readlines. |
+| '::readlines'                        | Documents for all class methods ::readlines.                                     |
+| '#readlines'                         | Documents for all instance methods #readlines; see note below.                   |


The "see note below" part hasn't been removed.

Removed.

peterzhu2118 · 2024-04-14T17:32:53Z

RI.md

+| --server=NUMBER | Set port for RDoc server; default is 8214. |
+<br>
+
+### \Options Details


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

BurdetteLamar · 2024-04-22T21:06:54Z

@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 · 2024-04-22T21:10:07Z

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

BurdetteLamar · 2024-04-29T19:00:09Z

@peterzhu2118, will you be reviewing this?

peterzhu2118 · 2024-04-30T02:35:16Z

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

BurdetteLamar · 2024-04-30T02:52:32Z

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?

colby-swandale · 2024-04-30T03:38:44Z

RI.md

+- Omits options; in interactive mode the only options in effect
+  are those taken from environment variable `RI`.
+  See {Options}[rdoc-ref:RI.md@Options].
+- Supports tab auto-completion for the names of a classes, modules, and methods;


Suggested change

- Supports tab auto-completion for the names of a classes, modules, and methods;

- Supports tab auto-completion for the names of a class, modules, and methods;

colby-swandale · 2024-04-30T04:13:45Z

.document

@@ -2,5 +2,6 @@ History.txt
 LICENSE.txt
 README.txt
 RI.txt
+RI.md


👋🏻 You identified this document's primary audience is people new to the ri command, and they would find this document mostly through GitHub. But, when rendering the document in GitHub, there are lots of weird and missing formatting artifacts coming through that make it challenging to read:

Document's title header is not rendered correctly

Links not being rendered correctly, i.e., {Ruby online documentation}[https://docs.ruby-lang.org/en/master]:

Lots of use of links using rdoc-ref, but these are not rendered on GitHub. Does this mean the document is intended to be read through ri? How do i do that?

Perhaps it would be helpful to either commit to Markdown and it's ways of formatting, or stick with the RDoc way and continue to use ri.rdoc?

Perhaps it would be helpful to either commit to Markdown and it's ways of formatting, or stick with the RDoc way and continue to use ri.rdoc?

I'd support committing to markdown format and will be happy to help with that conversion as I did something similar for IRB just not too long ago 🙂

👋🏻 You identified this document's primary audience is people new to the ri command, and they would find this document mostly through GitHub. But, when rendering the document in GitHub, there are lots of weird and missing formatting artifacts coming through that make it challenging to read:

* Document's title header is not rendered correctly * Links not being rendered correctly, i.e., `{Ruby online documentation}[https://docs.ruby-lang.org/en/master]:` * Lots of use of links using `rdoc-ref`, but these are not rendered on GitHub. Does this mean the document is intended to be read through `ri`? How do i do that?

Perhaps it would be helpful to either commit to Markdown and it's ways of formatting, or stick with the RDoc way and continue to use ri.rdoc?

@colby-swandale, is there a way I can view this new file as it's rendered on GitHub? I'd like to see the problems there firsthand.

Also, not sure what you mean by 'commit to markdown'; the new page is .md -- a markdown page. Maybe some of the text has an rdoc accent of which I'm not aware?

@colby-swandale, is there a way I can view this new file as it's rendered on GitHub? I'd like to see the problems there firsthand.

Sure! The current version is at: https://github.com/ruby/rdoc/blob/21505b91dd770e31c485205ac74ed44ef832432a/RI.md

Also, not sure what you mean by 'commit to markdown';

The page is Markdown, but the document is utilising RDoc ways of doing things, particularly around links. When Github renders the document, the links are being rendered as raw text:

Links in Markdown need to be denoted with [<text>](<link>) instead of {<text>}[<link>] as per the Markdown Spec

BurdetteLamar · 2024-05-01T19:45:14Z

@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 · 2024-05-01T22:12:19Z

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

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

BurdetteLamar · 2024-05-02T03:50:43Z

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

BurdetteLamar · 2024-05-02T13:52:27Z

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 · 2024-05-03T18:34:15Z

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 · 2024-05-10T14:32:33Z

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 · 2024-05-10T22:27:01Z

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 · 2024-05-11T00:00:11Z

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 added 2 commits March 22, 2024 11:32

Doc for RI

4b96f8b

Doc for RI

49288c7

BurdetteLamar added the Documentation label Mar 22, 2024

BurdetteLamar requested review from peterzhu2118, olleolleolle, drbrain and hsbt March 22, 2024 16:37

Doc for RI

5235b28

peterzhu2118 reviewed Mar 28, 2024

View reviewed changes

RI.md Outdated Show resolved Hide resolved

RI.md Outdated Show resolved Hide resolved

RI.md Outdated Show resolved Hide resolved

RI.md Outdated Show resolved Hide resolved

RI.md Outdated Show resolved Hide resolved

BurdetteLamar added 3 commits March 29, 2024 13:31

Doc for RI

2ae2f7c

Doc for RI

d47eafb

Doc for RI

b5ecfb0

BurdetteLamar marked this pull request as draft April 1, 2024 16:44

BurdetteLamar requested review from peterzhu2118 and removed request for olleolleolle, drbrain, hsbt and peterzhu2118 April 1, 2024 16:44

BurdetteLamar added 5 commits April 1, 2024 11:58

Doc for RI

421f841

Doc for RI

824a902

Doc for RI

eb15b7b

Doc for RI

a510c2d

Doc for RI

c06ca68

peterzhu2118 reviewed Apr 13, 2024

View reviewed changes

BurdetteLamar added 2 commits April 12, 2024 21:39

Doc for RI

dc661d0

Doc for RI

f0f4969

BurdetteLamar requested a review from peterzhu2118 April 13, 2024 16:54

peterzhu2118 reviewed Apr 14, 2024

View reviewed changes

BurdetteLamar added 3 commits April 21, 2024 11:45

Doc for RI

7f892db

Doc for RI

c158532

Doc for RI

21505b9

BurdetteLamar requested a review from peterzhu2118 April 22, 2024 21:09

colby-swandale reviewed Apr 30, 2024

View reviewed changes

BurdetteLamar marked this pull request as draft May 2, 2024 03:50

BurdetteLamar added 6 commits May 1, 2024 23:18

Change external links to markdown style

270c052

Change internal links to markdown style

b9ecfb8

Change internal links to markdown style

1fb22ff

Doc for RI

54aafab

Doc for RI

d99e195

Doc for RI

f07407b


		See also {ri at the Ready}[rdoc-ref:RI.md@ri+at+the+Ready].

		## Shell Quoting or Escaping

	\| 'IO#readlines' \| Document for RUby instance method IO::readlines. \|
	\| 'IO#readlines' \| Document for Ruby instance method IO::readlines. \|

	- Supports tab auto-completion for the names of a classes, modules, and methods;
	- Supports tab auto-completion for the names of a class, modules, and methods;

[DOC] New file RI.md #1100

Are you sure you want to change the base?

[DOC] New file RI.md #1100

Conversation

BurdetteLamar commented Mar 22, 2024 • edited

peterzhu2118 left a comment

Choose a reason for hiding this comment

BurdetteLamar commented Mar 29, 2024

BurdetteLamar commented Mar 29, 2024

peterzhu2118 commented Mar 31, 2024

BurdetteLamar commented Mar 31, 2024

BurdetteLamar commented Apr 1, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

peterzhu2118 Apr 14, 2024 • edited by BurdetteLamar

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

peterzhu2118 Apr 14, 2024 • edited by BurdetteLamar

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BurdetteLamar commented Apr 22, 2024

BurdetteLamar commented Apr 22, 2024

BurdetteLamar commented Apr 29, 2024

peterzhu2118 commented Apr 30, 2024

BurdetteLamar commented Apr 30, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BurdetteLamar commented May 1, 2024

BurdetteLamar commented May 1, 2024

BurdetteLamar commented May 2, 2024

BurdetteLamar commented May 2, 2024

BurdetteLamar commented May 3, 2024

colby-swandale commented May 10, 2024

BurdetteLamar commented May 10, 2024 • edited

jeremyevans commented May 11, 2024

BurdetteLamar commented Mar 22, 2024 •

edited

peterzhu2118 Apr 14, 2024 •

edited by BurdetteLamar

peterzhu2118 Apr 14, 2024 •

edited by BurdetteLamar

BurdetteLamar commented May 10, 2024 •

edited