[DOC] New file RI.md #1100

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

👋🏻 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

-Original file line number
+Diff line change
@@ Expand Up / @@ -2,5 +2,6 @@ History.txt @@
     LICENSE.txt
     README.txt
     RI.txt
+    RI.md
     lib
     doc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] New file RI.md #1100

Diff view

Diff view

There are no files selected for viewing

colby-swandale Apr 30, 2024

st0012 Apr 30, 2024

BurdetteLamar May 1, 2024

colby-swandale May 1, 2024

[DOC] New file RI.md #1100

[DOC] New file RI.md #1100

Diff view

Diff view

There are no files selected for viewing

colby-swandale Apr 30, 2024

Choose a reason for hiding this comment

st0012 Apr 30, 2024

Choose a reason for hiding this comment

BurdetteLamar May 1, 2024

Choose a reason for hiding this comment

colby-swandale May 1, 2024

Choose a reason for hiding this comment