Markup reference

[BurdetteLamar]

This PR is proposed as a replacement for the section "RDoc Markup Reference" in the documentation for class RDoc::Markup. The PR covers the topics found there.

I've built this as the separate "dummy" class RDoc::MarkupReference to allow examples of on-page links and references. This avoids adding illustrative dummy code in the class RDoc::Markup itself.

There are some specific questions and requests for reviewers, specifically where:

• I thought that the RDoc behavior may be wrong.
• I was not able to craft an example as I'd like.

I'm marking this as a draft at least until those issues are resolved.

[jeremyevans]

Seems strange to add this in a place where it could be required. Since this is only for documentation purposes, having this file under lib seems wrong.

I did a very brief review and don't see major issues with the text. I don't know the answer to any of the questions, though.

Note that I'm not an rdoc maintainer, and probably not a good person to review this.

[BurdetteLamar]

Seems strange to add this in a place where it could be required. Since this is only for documentation purposes, having this file under lib seems wrong.

I did a very brief review and don't see major issues with the text. I don't know the answer to any of the questions, though.

Note that I'm not an rdoc maintainer, and probably not a good person to review this.

Thanks, @jeremyevans. Your ideas, as always, are helpful. I can move the file do new directory doc/,
which also requires citing it in the Rakefile. Does that make sense?

[BurdetteLamar]

I have moved the dummy class MarkupReference from lib/ to new directory /doc, and have added the file to the Rakefile so that it will be built into the documentation.

[aycabta]

Okay, I think this is a good patch. It's a very valuable document. However, there are too many commits, would you squash them into one?

[BurdetteLamar]

Okay, I think this is a good patch. It's a very valuable document. However, there are too many commits, would you squash them into one?

Can I just use the "Squash and merge" button here?

BUT!! Before that, there are six questions and comments needing review. Search for "Reviewers:"

[BurdetteLamar]

@aycabta, can you suggest someone to answer the "Reviewers:" questions embedded in this PR?

[BurdetteLamar]

@aycabta, do you want this PR to be squashed and merged, even with its remaining questions unanswered?

[BurdetteLamar]

So, @Team, how does this get finished up?

As I said in the original comment, this covers the same topics as in the old markup reference. There's much more that can be added -- topics not previously covered. I'm eager to continue, but first need to get this finished and merged.

[BurdetteLamar]

I removed the 6 questions that were embedded in the text.

Now I find that I can no longer push to here:

remote: fatal error in commit_refs
To https://github.com/BurdetteLamar/rdoc.git
! [remote rejected] markup_reference -> markup_reference (failure)
error: failed to push some refs to 'https://github.com/BurdetteLamar/rdoc.git'

If no one objects, I'll close this and open another PR that will be ready to merge.

[BurdetteLamar]

Oh, now it did allow me to push. @aycabta, ready to squash and merge?

[BurdetteLamar]

@aycabta , still waiting for final approval (or disapproval).

[aycabta]

Sorry, I think I'll get some time to review later this month. Give me a little longer.

[BurdetteLamar]

Sorry, I think I'll get some time to review later this month. Give me a little longer.

Thanks, and no rush. Glad to know you're still interested.

[BurdetteLamar]

@aycabta, can you review this PR? Or suggest someone else who can?

[BurdetteLamar]

@aycabta, any progress on this?

[BurdetteLamar]

@aycabta, there is much more that can be done with the RDoc documentation, but that can't be started until this PR is merged. Is there anything more that needs to be done here?

[BurdetteLamar]

@aycabta, can this be reviewed by someone else? I'm thinking maybe @jeremyevans or @peterzhu2118. If not, where are we with this?

[BurdetteLamar]

Somehow I thought that @aycabta is the maintainer for RDoc; now I see that the maintainers are @drbrain and @hsbt. Can one of you review this PR?

[BurdetteLamar]

To avoid confusion, note that the "six questions" mentioned above are moot, and no longer relevant.

[BurdetteLamar]

Okay, I think this is a good patch. It's a very valuable document. However, there are too many commits, would you squash them into one?

That's from @aycabta, many months ago, yet I can't get a review from any committer, not even the RDoc maintainers? I'm baffled.

[hsbt]

@BurdetteLamar see https://twitter.com/aycabta/status/1458494862202789893

Not everyone has enough time, motivation, and health for the all-time. Your rush request seems rude attitude.

[hsbt]

Your contribution is valuable, I understand. After 1 year, there is no response from @aycabta . I will manage this.

Please wait a while.

[BurdetteLamar]

Thanks, @hsbt.

[BurdetteLamar]

Your contribution is valuable, I understand. After 1 year, there is no response from @aycabta . I will manage this.

Please wait a while.

@hsbt, may I have your permission to recruit reviewers for this PR?