From 05f5b3ecc41ac3bb990e297fea1415567e4cfef1 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 Backport-PR-URL: https://github.com/nodejs/node/pull/32149 Reviewed-By: Richard Lau Reviewed-By: James M Snell Reviewed-By: Luigi Pinca --- CHANGELOG.md | 24 +++++++++++----------- 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 ++-- 12 files changed, 29 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dff504dfe0126b..2e75d92a23d503 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,18 +2,18 @@ Select a Node.js version below to view the changelog history: -* [Node.js 12](doc/changelogs/CHANGELOG_V12.md) - **Current** -* [Node.js 11](doc/changelogs/CHANGELOG_V11.md) - Current -* [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) — Long Term Support -* [Node.js 7](doc/changelogs/CHANGELOG_V7.md) — End-of-Life -* [Node.js 6](doc/changelogs/CHANGELOG_V6.md) — Long Term Support -* [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 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 5fb3dd5826bc21..2f374d22106953 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -239,7 +239,7 @@ NODE_MODULE_INIT(/* exports, module, context */) { 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 bc32c3c75ef4ef..93682d6421a73e 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -564,14 +564,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`][]. - `EPERM` (Operation not permitted): An attempt was made to perform an operation that requires elevated privileges. @@ -583,7 +583,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. diff --git a/doc/api/http.md b/doc/api/http.md index 1fe01915d680d2..c815cff05113c6 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: @@ -748,7 +748,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. @@ -1045,7 +1045,7 @@ affects new connections to the server, not any existing connections. added: v0.1.17 --> -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. The response inherits from [Stream][], and additionally implements the diff --git a/doc/api/http2.md b/doc/api/http2.md index a5cf2115f7b577..3e836f5dae35b6 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2916,7 +2916,7 @@ Url { added: v8.4.0 --> -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. The response inherits from [Stream][], and additionally implements the diff --git a/doc/api/modules.md b/doc/api/modules.md index 6706206f9b92ed..b032f168460c3e 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -885,7 +885,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 07df07d63f9c6e..a4eb7a62d2bf51 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -867,7 +867,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 4cfa4fa8ae37d5..a4157a10b60ddb 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -386,7 +386,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: @@ -408,7 +408,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 20f5e7c11a2ad9..2a91ca57326971 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -167,7 +167,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 0789ecf70cbe3d..8e86900e3cfda8 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -51,7 +51,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 5b531639e77de5..3ae1d6d6ea28e3 100644 --- a/doc/guides/backporting-to-release-lines.md +++ b/doc/guides/backporting-to-release-lines.md @@ -75,7 +75,7 @@ hint: and commit the result with 'git commit' 9. Open a pull request: 1. Be sure to target the `v8.x-staging` branch in the pull request. 1. Include the backport target in the pull request title in the following - format — `[v8.x backport] `. + format: `[v8.x backport] `. Example: `[v8.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