KEMBAR78
[DOC] Improve formatting in Markdown files by amomchilov · Pull Request #12322 · ruby/ruby · GitHub
Skip to content

Conversation

@amomchilov
Copy link
Contributor

Best reviewed commit-by-commit.

This PR:

  1. Corrects issues with the indentation in the WASM docs
  2. Uses the console highlight language in some code blocks, which better handles the $ at the start of lines when viewed on GitHub (and behaves the same in RDoc)
  3. Migrates the the feature request template to MarkDown
  4. Sets the highlight language for any all code blocks that didn't have it, and corrects it in some places.

@amomchilov amomchilov marked this pull request as ready for review December 12, 2024 21:35
@matzbot matzbot requested a review from a team December 12, 2024 21:36
NEWS.md Outdated
Old:
```
```text
Copy link
Member

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?

Copy link
Contributor Author

@amomchilov amomchilov Dec 12, 2024

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.

Copy link
Member

@k0kubun k0kubun Dec 12, 2024

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.

Copy link
Contributor Author

@amomchilov amomchilov Dec 13, 2024

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).

@XrXr XrXr added the Documentation Improvements to documentation. label Dec 12, 2024
@amomchilov amomchilov changed the title Improve syntax highlighting in Markdown files [DOC] Improve syntax highlighting in Markdown files Dec 12, 2024
Copy link
Member

@hsbt hsbt left a 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.

@amomchilov
Copy link
Contributor Author

@hsbt Ah yes, I always forget about that when I'm doing bulk changes across this repo. Will update

@amomchilov
Copy link
Contributor Author

@k0kubun
Copy link
Member

k0kubun commented Dec 12, 2024

amomchilov requested review from hsbt and k0kubun

Did you see #12322 (comment)?

Copy link
Contributor Author

@amomchilov amomchilov left a 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
Copy link
Contributor Author

@amomchilov amomchilov Dec 13, 2024

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).

kou pushed a commit to ruby/strscan that referenced this pull request Dec 13, 2024
@amomchilov amomchilov changed the title [DOC] Improve syntax highlighting in Markdown files [DOC] Improve formatting in Markdown files Dec 13, 2024
@k0kubun k0kubun merged commit 0ea5c13 into ruby:master Dec 13, 2024
19 checks passed
@k0kubun k0kubun deleted the doc-formatting branch December 13, 2024 01:49
@hsbt
Copy link
Member

hsbt commented Dec 13, 2024

👌

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation Improvements to documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants