doc: use ASCII apostrophes consistently

[tniessen]

We can use non-ASCII apostrophes, but we should be consistent. Because the vast majority of apostrophes in our docs is ASCII, this changes the few non-ASCII apostrophes (’) to ASCII apostrophes ('). This resolves such minor inconsistencies:

[nodejs-github-bot]

Review requested:

• @nodejs/modules
• @nodejs/tsc

[tniessen]

I am going to blindly trust the linter here.

[ljharb]

This is the wrong direction; straight quotes are never typographically correct in prose, and only curly quotes should be used.

[tniessen]

@ljharb English isn't my first language so I'll gladly defer that decision to someone else. This change is in line with the Wikipedia style guide.

These are very few occurrences. If we do want to go the other way, we have to change thousands of apostrophes.

[RaisinTen]

I'm fine with either of these provided we use one consistently throughout the docs. Any chance we can enforce the usage of ' with a linter rule?

[Trott]

straight quotes are never typographically correct in prose,

That is incorrect. For an overview of the nuance and ambiguity, see https://graphicdesign.stackexchange.com/a/66812

only curly quotes should be used.

If we had sufficient oversight of the markdown documents that we could ensure consistent and correct usage, that might make sense. But we don't. And, as evidenced by the lint issues that were uncovered with this change, our tooling doesn't account for these characters. Using ASCII punctuation helps with grep and other use cases (including our tooling).

[Trott]

It looks like the Microsoft Style Guide (which is what we follow in the Node.js docs etc.) uses straight apostrophes although they don't specifically call that out in their text as far as I can tell. https://docs.microsoft.com/en-us/style-guide/punctuation/apostrophes

In the headers, the apostrophe character is rendered at an angle, but it is still the ASCII apostrophe and not a non-ASCII Unicode character.

[JakobJingleheimer]

I don't particularly have an opinion except that if there is no lint rule, this PR will surely become undone very quickly (so why bother).

[Trott]

Any chance we can enforce the usage of ' with a linter rule?

Yes. We'd likely need to identify all the possible non-ASCII apostrophe and "smart" quote characters, and then create a remark-lint rule to find them and flag them. Maybe open an issue (or even a pull request) at https://github.com/nodejs/remark-preset-lint-node?

[tniessen]

This is the wrong direction; straight quotes are never typographically correct in prose, and only curly quotes should be used.

I don't know about "typographically correct". The Google style guide, the Microsoft style guide, and the Wikipedia style guide all use straight apostrophes and the latter explicitly recommends not to use curly apostrophes. I've found some other style guides that use straight apostrophes for possessives but curly quotation marks for actual quotes (e.g., the SUSE Documentation Style Guide).

Enforcing curly apostrophes would probably be difficult because straight apostrophes are used in code, but this direction should be relatively simple to enforce.

[GeoffreyBooth]

I feel pretty strongly that curly quotes are the correct style for humans to read. Perhaps the original files can have straight quotes and we generate curly ones as part of generating the HTML?

[tniessen]

I feel pretty strongly that curly quotes are the correct style for humans to read. Perhaps the original files can have straight quotes and we generate curly ones as part of generating the HTML?

That seems reasonable to me if we have a method that produces consistent and correct output, and a good justification for the added complexity in doc/README.md.

[Trott]

I feel pretty strongly that curly quotes are the correct style for humans to read. Perhaps the original files can have straight quotes and we generate curly ones as part of generating the HTML?

I wouldn't want to literally change the character from ASCII 39 to some other code point, but might we consider choosing a font for text that renders ASCII 39 curved while continue using a font for code that renders it straight? I'm not even sure if that's a thing, though.

[aduh95]

I feel pretty strongly that using the ASCII quote is the "correct" choice for our markdown documents, because that's the one that's on most keyboard layouts. Sure that's something that could be addressed by making make format-md silently convert to curly quotes, but it would still be a pain when e.g. making suggestions on a PR review.

I wouldn't want to literally change the character from ASCII 39 to some other code point, but might we consider choosing a font for text that renders ASCII 39 curved while continue using a font for code that renders it straight? I'm not even sure if that's a thing, though.

That sounds reasonable, if that's "not a thing" we could fork an existing open source font and make it happen if folks feel strongly about it.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/44024/

[GeoffreyBooth]

That sounds reasonable, if that’s “not a thing” we could fork an existing open source font and make it happen if folks feel strongly about it.

The way I’ve usually seen this implemented is that plugins do this during HTML generation. Then you can use any font you want.

From a cursory glance at our docs generation scripts, it appears that we use https://github.com/remarkjs/remark to parse our Markdown, with a bunch of plugins added. There’s a Remark plugin https://github.com/silvenon/remark-smartypants which adds the SmartyPants typography, which is smart/curly quotes plus hyphens and ellipses. Perhaps we could investigate an approach like this?

[nodejs-github-bot]

Landed in 895cc57