[DOC] Change indexes.rdoc to indexes.md #812
Conversation
| { | ||
| "$": :show_source, | ||
| "@": :whereami, | ||
| } |
There was a problem hiding this comment.
Let's wrap them in a code block
| { | |
| "$": :show_source, | |
| "@": :whereami, | |
| } | |
| ```rb | |
| { | |
| "$": :show_source, | |
| "@": :whereami, | |
| } | |
| ``` |
There was a problem hiding this comment.
Triple backticks in list item did not work for me (displayed as code, backticks and all). Does non the currently indented code block work for you>?
There was a problem hiding this comment.
The spaces work. But all other markdown docs (mostly readme) uses backticks for code blocks, I want to standardise the format. If this doesn't work for you, I'll try update it later 👍
There was a problem hiding this comment.
Does not work for me; please update later.
|
We should remove the rdoc syntax because it becomes difficult to read on GitHub. For example, in the following example, I think it would be better to make these changes. - <tt>-d</tt>: Set <tt>$DEBUG</tt> and {$VERBOSE}[rdoc-ref:IRB@Verbosity] to +true+.
+ `-d`: Set `$DEBUG` and `$VERBOSE` to `true`.convert rdoc to html
Markdown in GitHub
|
|
About this format change: this is at @st0012's request; for my part, I'm now aware of any trend in the Ruby world from .rdoc to .md. |
If this matters, it should be remarked upon in the Ruby doc guide, doc/contributing/documentation_guide.md. |
The entire contributing docs were rewritten with markdown in ruby/ruby#5899, with all the subsequent new pages being markdown too. And even though it's not a rdoc to markdown rewrite, all new Ruby wiki pages are written in markdown as well. Consider it's one of the most popular documentation format and has a rich set of supporting tools (e.g. VS Code extensions), I think in the long-term it'll be beneficial if we gradually migrate RDoc to markdown.
I don't think I'm the right person, nor are we at the right time, to make this a universal guideline. Consider the amount of Ruby documentation written in RDoc, rewriting all of them at once would be basically impossible. But to gradually migrate them, it will require a consensus and a plan from the Ruby Core. And I don't think this is a priority anyway. The reason I suggested this change in the last doc PR was because I think it's a good opportunity to do so now that we're thinking about IRB docs again. But that doesn't mean I feel such rewrite is a priority to the community. |
|
@st0012, ready for your review. |
(ruby/irb#812) * Change indexes.rdoc to indexes.md * Change indexes.rdoc to indexes.md * Change indexes.rdoc to indexes.md ruby/irb@b1cd53cbf7
Per @st0012 request.