-
Notifications
You must be signed in to change notification settings - Fork 5.5k
[DOC] Improve formatting in Markdown files #12322
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
f73c91a to
08483ac
Compare
08483ac to
9812d30
Compare
NEWS.md
Outdated
| Old: | ||
| ``` | ||
| ```text |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What difference does this change make?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It communicates that the syntax highlighting language was intentionally set to none, rather than having been forgotten to be set.
That way, when you search for opening bare triple-back ticks, this won't surface any more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I see. I was so used to ``` used for plain-text code blocks that I got rather confused by looking at this style as markdown code. It might help some people like you, but it could be rather hard to understand for people like me.
So I don't find it's necessarily a positive change. We probably also don't want to spend time reviewing PRs that change ``` to ```text, which does nothing visually and doesn't clarify the intention by itself (at least it didn't to me). I appreciate your effort to improve the doc but I would like this diff to be removed from the PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair enough, I've pulled it out.
It already served its purpose for me: I used a regexp for finding the triple-back-tick pairs that didn't have a language set, and setting the language to txt or text on these raw text blocks made it not break the matching.
This could be worth reconsidering in the future, if there was a lint step added to remind people to set the language on new code blocks they write. It's like the diff between void f() and void f(void).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you exclude doc/strscan, spec/ruby and tool/lrama? We should fix upstream, not this repository.
|
@hsbt Ah yes, I always forget about that when I'm doing bulk changes across this repo. Will update |
… which handles the prefix `$` correctly.
9812d30 to
c0f320b
Compare
Did you see #12322 (comment)? |
c0f320b to
a768bad
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missed it somehow @k0kubun. Addressed.
NEWS.md
Outdated
| Old: | ||
| ``` | ||
| ```text |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair enough, I've pulled it out.
It already served its purpose for me: I used a regexp for finding the triple-back-tick pairs that didn't have a language set, and setting the language to txt or text on these raw text blocks made it not break the matching.
This could be worth reconsidering in the future, if there was a lint step added to remind people to set the language on new code blocks they write. It's like the diff between void f() and void f(void).
|
👌 |
Best reviewed commit-by-commit.
This PR:
consolehighlight language in some code blocks, which better handles the$at the start of lines when viewed on GitHub (and behaves the same in RDoc)