[DOC] RDoc for module IRB

[BurdetteLamar]

I think everything from the beginning of the module doc down through section "Color Highlighting" is review-worthy. Below that, not, so I'll mark this as a draft.

I'm striving organize this by features, and not by command-line options and IRB.conf entries. But to make sure they're available as two coherent groups I've added an index for each.

It's taken me weeks to do this much, and will likely take weeks to complete and get reviewed/approved.

It may be good to review/revise piecemeal.

[BurdetteLamar]

@st0012, @peterzhu2118: Do you consider this still active? If not, what sort of different approach can we take?

[st0012]

@BurdetteLamar sorry that I had to prioritise feature/bug fixes for Ruby 3.3's release 🙏 I will review this PR in several gos soon.

I do have a question though: is it possible we can rewrite irb.rb's documents in Markdown? I'm not familiar with RDoc format so I don't know if we'd lose anything by doing so.
I'd also prefer having indexes.md instead of indexes.rdoc so we align with ruby/ruby's trend to embrace Markdown format. WDYT?

[BurdetteLamar]

@BurdetteLamar sorry that I had to prioritise feature/bug fixes for Ruby 3.3's release 🙏 I will review this PR in several gos soon.

I do have a question though: is it possible we can rewrite irb.rb's documents in Markdown? I'm not familiar with RDoc format so I don't know if we'd lose anything by doing so. I'd also prefer having indexes.md instead of indexes.rdoc so we align with ruby/ruby's trend to embrace Markdown format. WDYT?

Ok, will look at switching to Markdown. Will mark this as a draft (once more).

[st0012]

Let's remove anything related to tracer for now as the current integration needs an upgrade before being usable again.

[BurdetteLamar]

If we're looking to switch to Markdown, let's hold off on reviewing this here, and instead review the Markdown. I'll be beginning that work shortly.

[BurdetteLamar]

I think things are starting to get out of hand here. My aim in this PR is to revise the stated sections (top through "Encodings"), adding value and avoiding regressions or new errors. When we've reached that state (which we may have already), I'd like this to be approved and merged. Otherwise, we can keep proposing further improvements and refinements indefinitely.

I'd like this to be completed in my lifetime (I'll be 81 soon), so let's figure out how to pinch this off and put it to bed.

Also, I think changing to Markdown is out-of-scope for this PR, as are revisions to the previously-existing sections "Commands" through "Example using IRB Sessions."

[st0012]

My aim in this PR is to revise the stated sections (top through "Encodings"), adding value and avoiding regressions or new errors.

Sorry that I wasn't aware of this. If that's the case, yeah we can split this into multiple PRs.

I will go through this again and unless there's any incorrect information, I'll merge this first. Does that sound good to you?
@ruby/irb-reline WDYT?

[BurdetteLamar]

My aim in this PR is to revise the stated sections (top through "Encodings"), adding value and avoiding regressions or new errors.

Sorry that I wasn't aware of this. If that's the case, yeah we can split this into multiple PRs.

I will go through this again and unless there's any incorrect information, I'll merge this first. Does that sound good to you? @ruby/irb-reline WDYT?

I'd have loved to do this much as multiple PRs, but I don't think that works, b/c all of the new here needs to replace all of the target old all at once (cannot be replaced as 1-1 fragments, I didn't think).

That having been done, I'll look forward to reworking the remaining sections (the trailing ones, except the last), and will also be happy to work further on whatever anyone thinks useful.

[st0012]

I'd have loved to do this much as multiple PRs, but I don't think that works, b/c all of the new here needs to replace all of the target old all at once (cannot be replaced as 1-1 fragments, I didn't think).

Sorry that I wasn't clear. By splitting I meant the changes I suggested and the markdown rewrite. I'm aware that this PR's changes are not easy to split 😄

[BurdetteLamar]

@st0012, I will endeavor to capture some of your comments elsewhere. There's no cattle documentor prod per se, but we can put up some Issues. Please feel free to add doc issues as you like and assign to me.

[st0012]

I think some of my comments should still addressed in this PR, like outdated values and example prompts...etc. I've resolved the ones that could be be splitted out. Once they're addressed, I think we can merge this first 👍

[BurdetteLamar]

I think some of my comments should still addressed in this PR, like outdated values and example prompts...etc. I've resolved the ones that could be be splitted out. Once they're addressed, I think we can merge this first 👍

@st0012: Example prompts updated (can you spell tedious) in new doc, but not in old (sessions stuff, etc.).

Which are the 'outdated values'?

[st0012]

Thanks for the rewrite 🙌
I'll make a few small changes to hide/hint about deprecated features after merging this.

[BurdetteLamar]

Thanks for the rewrite 🙌 I'll make a few small changes to hide/hint about deprecated features after merging this.

@st0012, thanks for your help in reviewing and commenting.

Going forward:

• I'll work on changing the indexes to markdown (good learning for me).
• If we are going to change the main page to markdown, its text must be stable across that change; some agreed-upon time in the future.
• Two things still to look at: sessions and commands; I'll see to those.
• Anything else you think needs attention can be put up as documentation Issues?