sahib / rmlint

Extremely fast tool to remove duplicates and other lint from your filesystem
http://rmlint.rtfd.org
GNU General Public License v3.0
1.86k stars 128 forks source link

Fix usages of single backticks to double backticks #591

Open waldyrious opened 1 year ago

waldyrious commented 1 year ago

In RST, text wrapped in a `single backtick` is meant for "interpreted text", and is rendered using <cite> tags. Verbatim/literal text should instead be wrapped in ``double backticks``, which is rendered using <code> tags.

See https://docutils.sourceforge.io/docs/user/rst/quickref.html#inline-markup

waldyrious commented 1 year ago

Note: I only checked the docs/tutorial.rst file; it's possible that there are other files in the documentation with the same issue.

cebtenzzre commented 1 year ago

Based on the output of

grep -Prn '(^|[^`_])`[^`_][^`]*(?<!_)`([^`_]|$)' --include='*.rst'

this issue is also present in testing.rst, translators.rst, the manpage, and the README.

waldyrious commented 1 year ago

@Cebtenzzre thanks for looking that up! Would you like write access to my fork so you could make the changes to the other files?

cebtenzzre commented 1 year ago

Looks like I already had access. I pushed fixes for those files, and I also corrected a few references in the manpage (e.g. fdupes(1)) that I think are legitimate use of interpreted text - some of them were using inline literals. How do those changes look to you?

waldyrious commented 1 year ago

Looks like I already had access.

Oh, right, it didn't occur to me to check that you had collaborator status in this repo. In that case, yeah, it's expected that you would have write access to the PR branch.

I pushed fixes for those files, and I also corrected a few references in the manpage (e.g. fdupes(1)) that I think are legitimate use of interpreted text - some of them were using inline literals. How do those changes look to you?

Looks great! I confess I'm not 100% sure about when the interpreted text markup is supposed to be used, but those command references definitely don't look like things that should be marked up as code/verbatim.

Thanks for taking this on!