From b6cd2155c3442a8c56aa6f6ffa0dc9b6a308a7b1 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 3 Mar 2020 21:23:59 -0800 Subject: [PATCH] doc: remove em dashes Our documentation uses em dashes inconsistently. They are treated inconsistently typographically too. (For example, they are sometimes surrounded by spaces and sometimes not.) They are also often confused with ordinary hyphens such as in the CHANGELOG, where they are inadvertently mixed together in a single list. The difference is not obvious in the raw markdown but is very noticeable when rendered, appearing to be a typographical error (which it in fact is). The em dash is never needed. There are always alternatives. Remove em dashes entirely. PR-URL: https://github.com/nodejs/node/pull/32080 Reviewed-By: Richard Lau Reviewed-By: James M Snell Reviewed-By: Luigi Pinca --- CHANGELOG.md | 26 +++++++++++----------- doc/api/addons.md | 2 +- doc/api/errors.md | 6 ++--- doc/api/http.md | 6 ++--- doc/api/http2.md | 2 +- doc/api/modules.md | 2 +- doc/api/net.md | 2 +- doc/api/path.md | 4 ++-- doc/api/process.md | 2 +- doc/api/url.md | 2 +- doc/guides/backporting-to-release-lines.md | 2 +- doc/guides/contributing/issues.md | 4 ++-- doc/guides/doc-style-guide.md | 8 ++----- doc/guides/maintaining-icu.md | 2 +- tools/doc/versions.js | 2 +- 15 files changed, 34 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1dec016f811479..b32c52810ccc8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,19 +2,19 @@ Select a Node.js version below to view the changelog history: -* [Node.js 13](doc/changelogs/CHANGELOG_V13.md) - **Current** -* [Node.js 12](doc/changelogs/CHANGELOG_V12.md) - **Long Term Support** -* [Node.js 11](doc/changelogs/CHANGELOG_V11.md) - End-of-Life -* [Node.js 10](doc/changelogs/CHANGELOG_V10.md) — Long Term Support -* [Node.js 9](doc/changelogs/CHANGELOG_V9.md) — End-of-Life -* [Node.js 8](doc/changelogs/CHANGELOG_V8.md) — End-of-Life -* [Node.js 7](doc/changelogs/CHANGELOG_V7.md) — End-of-Life -* [Node.js 6](doc/changelogs/CHANGELOG_V6.md) — End-of-Life -* [Node.js 5](doc/changelogs/CHANGELOG_V5.md) — End-of-Life -* [Node.js 4](doc/changelogs/CHANGELOG_V4.md) — End-of-Life -* [io.js](doc/changelogs/CHANGELOG_IOJS.md) — End-of-Life -* [Node.js 0.12](doc/changelogs/CHANGELOG_V012.md) — End-of-Life -* [Node.js 0.10](doc/changelogs/CHANGELOG_V010.md) — End-of-Life +* [Node.js 13](doc/changelogs/CHANGELOG_V13.md) **Current** +* [Node.js 12](doc/changelogs/CHANGELOG_V12.md) **Long Term Support** +* [Node.js 11](doc/changelogs/CHANGELOG_V11.md) End-of-Life +* [Node.js 10](doc/changelogs/CHANGELOG_V10.md) Long Term Support +* [Node.js 9](doc/changelogs/CHANGELOG_V9.md) End-of-Life +* [Node.js 8](doc/changelogs/CHANGELOG_V8.md) End-of-Life +* [Node.js 7](doc/changelogs/CHANGELOG_V7.md) End-of-Life +* [Node.js 6](doc/changelogs/CHANGELOG_V6.md) End-of-Life +* [Node.js 5](doc/changelogs/CHANGELOG_V5.md) End-of-Life +* [Node.js 4](doc/changelogs/CHANGELOG_V4.md) End-of-Life +* [io.js](doc/changelogs/CHANGELOG_IOJS.md) End-of-Life +* [Node.js 0.12](doc/changelogs/CHANGELOG_V012.md) End-of-Life +* [Node.js 0.10](doc/changelogs/CHANGELOG_V010.md) End-of-Life * [Archive](doc/changelogs/CHANGELOG_ARCHIVE.md) Please use the following table to find the changelog for a specific Node.js diff --git a/doc/api/addons.md b/doc/api/addons.md index 6b77338348ed96..93f99afbeee7e7 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -313,7 +313,7 @@ require('./build/Release/addon'); Once the source code has been written, it must be compiled into the binary `addon.node` file. To do so, create a file called `binding.gyp` in the top-level of the project describing the build configuration of the module -using a JSON-like format. This file is used by [node-gyp][] — a tool written +using a JSON-like format. This file is used by [node-gyp][], a tool written specifically to compile Node.js Addons. ```json diff --git a/doc/api/errors.md b/doc/api/errors.md index c244bfd7f0042f..26685f0ebcdc69 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -533,14 +533,14 @@ program. For a comprehensive list, see the [`errno`(3) man page][]. `ulimit -n 2048` in the same shell that will run the Node.js process. * `ENOENT` (No such file or directory): Commonly raised by [`fs`][] operations - to indicate that a component of the specified pathname does not exist — no + to indicate that a component of the specified pathname does not exist. No entity (file or directory) could be found by the given path. * `ENOTDIR` (Not a directory): A component of the given pathname existed, but was not a directory as expected. Commonly raised by [`fs.readdir`][]. * `ENOTEMPTY` (Directory not empty): A directory with entries was the target - of an operation that requires an empty directory — usually [`fs.unlink`][]. + of an operation that requires an empty directory, usually [`fs.unlink`][]. * `ENOTFOUND` (DNS lookup failed): Indicates a DNS failure of either `EAI_NODATA` or `EAI_NONAME`. This is not a standard POSIX error. @@ -555,7 +555,7 @@ program. For a comprehensive list, see the [`errno`(3) man page][]. * `ETIMEDOUT` (Operation timed out): A connect or send request failed because the connected party did not properly respond after a period of time. Usually - encountered by [`http`][] or [`net`][] — often a sign that a `socket.end()` + encountered by [`http`][] or [`net`][]. Often a sign that a `socket.end()` was not properly called. ## Class: `TypeError` diff --git a/doc/api/http.md b/doc/api/http.md index cf1e5d76bf42bc..f6aa93ecedc2eb 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -9,7 +9,7 @@ To use the HTTP server and client one must `require('http')`. The HTTP interfaces in Node.js are designed to support many features of the protocol which have been traditionally difficult to use. In particular, large, possibly chunk-encoded, messages. The interface is -careful to never buffer entire requests or responses — the +careful to never buffer entire requests or responses, so the user is able to stream data. HTTP message headers are represented by an object like this: @@ -882,7 +882,7 @@ added: v0.1.29 Sends a chunk of the body. By calling this method many times, a request body can be sent to a -server — in that case it is suggested to use the +server. In that case, it is suggested to use the `['Transfer-Encoding', 'chunked']` header line when creating the request. @@ -1214,7 +1214,7 @@ added: v0.1.17 * Extends: {Stream} -This object is created internally by an HTTP server — not by the user. It is +This object is created internally by an HTTP server, not by the user. It is passed as the second parameter to the [`'request'`][] event. ### Event: `'close'` diff --git a/doc/api/http2.md b/doc/api/http2.md index 11f41224c4e1d3..69252121f71daf 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -3008,7 +3008,7 @@ added: v8.4.0 * Extends: {Stream} -This object is created internally by an HTTP server — not by the user. It is +This object is created internally by an HTTP server, not by the user. It is passed as the second parameter to the [`'request'`][] event. #### Event: `'close'` diff --git a/doc/api/modules.md b/doc/api/modules.md index d69a2a2f1516d7..4c91c27f52bc33 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -945,7 +945,7 @@ added: v0.3.7 * {Object} Provides general utility methods when interacting with instances of -`Module` — the `module` variable often seen in file modules. Accessed +`Module`, the `module` variable often seen in file modules. Accessed via `require('module')`. ### `module.builtinModules` diff --git a/doc/api/net.md b/doc/api/net.md index 84bda5e4e9bfed..ea0b9139fd33f1 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -939,7 +939,7 @@ added: v0.1.90 * Returns: {boolean} Sends data on the socket. The second parameter specifies the encoding in the -case of a string — it defaults to UTF8 encoding. +case of a string. It defaults to UTF8 encoding. Returns `true` if the entire data was flushed successfully to the kernel buffer. Returns `false` if all or part of the data was queued in user memory. diff --git a/doc/api/path.md b/doc/api/path.md index 477ef2cab09e82..c05a5c29efb12f 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -389,7 +389,7 @@ path.parse('/home/user/dir/file.txt'); │ root │ │ name │ ext │ " / home/user/dir / file .txt " └──────┴──────────────┴──────┴─────┘ -(all spaces in the "" line should be ignored — they are purely for formatting) +(All spaces in the "" line should be ignored. They are purely for formatting.) ``` On Windows: @@ -411,7 +411,7 @@ path.parse('C:\\path\\dir\\file.txt'); │ root │ │ name │ ext │ " C:\ path\dir \ file .txt " └──────┴──────────────┴──────┴─────┘ -(all spaces in the "" line should be ignored — they are purely for formatting) +(All spaces in the "" line should be ignored. They are purely for formatting.) ``` A [`TypeError`][] is thrown if `path` is not a string. diff --git a/doc/api/process.md b/doc/api/process.md index 598a75cc9a7813..dfd98517829ff5 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -190,7 +190,7 @@ rejection handler. There is no notion of a top level for a `Promise` chain at which rejections can always be handled. Being inherently asynchronous in nature, a `Promise` -rejection can be handled at a future point in time — possibly much later than +rejection can be handled at a future point in time, possibly much later than the event loop turn it takes for the `'unhandledRejection'` event to be emitted. Another way of stating this is that, unlike in synchronous code where there is diff --git a/doc/api/url.md b/doc/api/url.md index a198b699cd31d8..49f56509fe41e9 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -47,7 +47,7 @@ WHATWG URL's `origin` property includes `protocol` and `host`, but not ├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤ │ href │ └────────────────────────────────────────────────────────────────────────────────────────────────┘ -(all spaces in the "" line should be ignored — they are purely for formatting) +(All spaces in the "" line should be ignored. They are purely for formatting.) ``` Parsing the URL string using the WHATWG API: diff --git a/doc/guides/backporting-to-release-lines.md b/doc/guides/backporting-to-release-lines.md index 4a4657d0815a21..55fbcb7e5bc344 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -75,7 +75,7 @@ replace that with the staging branch for the targeted release line. 9. Open a pull request: 1. Be sure to target the `v10.x-staging` branch in the pull request. 1. Include the backport target in the pull request title in the following - format — `[v10.x backport] `. + format: `[v10.x backport] `. Example: `[v10.x backport] process: improve performance of nextTick` 1. Check the checkbox labeled "Allow edits from maintainers". 1. In the description add a reference to the original PR. diff --git a/doc/guides/contributing/issues.md b/doc/guides/contributing/issues.md index 054bbd7b2775f9..31a47c1cd33c16 100644 --- a/doc/guides/contributing/issues.md +++ b/doc/guides/contributing/issues.md @@ -89,8 +89,8 @@ around it. Some contributors may have differing opinions about the issue, including whether the behavior being seen is a bug or a feature. This discussion is part of the process and should be kept focused, helpful, and professional. -Short, clipped responses—that provide neither additional context nor supporting -detail—are not helpful or professional. To many, such responses are simply +Short, clipped responses that provide neither additional context nor supporting +detail are not helpful or professional. To many, such responses are simply annoying and unfriendly. Contributors are encouraged to help one another make forward progress as much diff --git a/doc/guides/doc-style-guide.md b/doc/guides/doc-style-guide.md index f0221991b79be2..7ee2cac4ec366f 100644 --- a/doc/guides/doc-style-guide.md +++ b/doc/guides/doc-style-guide.md @@ -25,12 +25,10 @@ * Outside of the wrapping element if the wrapping element contains only a fragment of a clause. * Documents must start with a level-one heading. -* Prefer affixing links to inlining links — prefer `[a link][]` to - `[a link](http://example.com)`. +* Prefer affixing links (`[a link][]`) to inlining links + (`[a link](http://example.com)`). * When documenting APIs, update the YAML comment associated with the API as appropriate. This is especially true when introducing or deprecating an API. -* Use [Em dashes][] ("—" or `Option+Shift+"-"` on macOS) surrounded by spaces, - as per [The New York Times Manual of Style and Usage][]. * For code blocks: * Use language aware fences. ("```js") * Code need not be complete. Treat code blocks as an illustration or aid to @@ -67,9 +65,7 @@ See also API documentation structure overview in [doctools README][]. -[Em dashes]: https://en.wikipedia.org/wiki/Dash#Em_dash [Javascript type]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Data_structures_and_types [serial commas]: https://en.wikipedia.org/wiki/Serial_comma -[The New York Times Manual of Style and Usage]: https://en.wikipedia.org/wiki/The_New_York_Times_Manual_of_Style_and_Usage [plugin]: https://editorconfig.org/#download [doctools README]: ../tools/doc/README.md diff --git a/doc/guides/maintaining-icu.md b/doc/guides/maintaining-icu.md index 4add40b7fa2046..85f13c91298423 100644 --- a/doc/guides/maintaining-icu.md +++ b/doc/guides/maintaining-icu.md @@ -218,7 +218,7 @@ following the steps above in the prior section of this document ought to be repeatable without concern for overriding a patch. 2. **Verifiability.** Given the number of files modified in an ICU PR, -a floating patch could easily be missed — or dropped altogether next time +a floating patch could easily be missed or dropped altogether next time something is landed. 3. **Compatibility.** There are a number of ways that ICU can be loaded into diff --git a/tools/doc/versions.js b/tools/doc/versions.js index 782ce90ee2c616..bff6ac3617fbde 100644 --- a/tools/doc/versions.js +++ b/tools/doc/versions.js @@ -61,7 +61,7 @@ module.exports = { } } const ltsRE = /Long Term Support/i; - const versionRE = /\* \[Node\.js ([0-9.]+)\][^-—]+[-—]\s*(.*)\r?\n/g; + const versionRE = /\* \[Node\.js ([0-9.]+)\]\S+ (.*)\r?\n/g; _versions = []; let match; while ((match = versionRE.exec(changelog)) != null) {