doc: perform minor cleanup on cli.md

* sort references in ASCII order * merge logically-connected single-sentence paragraphs * remove _please_ from referrals to other docs * remove unnecessary italics * make some text more concise * change some instances of future tense to present tense PR-URL: #35152 Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
nodejs · ruyadorno · Sep 22, 2020 · Sep 5, 2020 · Sep 5, 2020 · Sep 7, 2020
commit ae85228e54cad6f1ab002db51d50cc8d37f654c3
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -18,7 +18,7 @@ To view this documentation as a manual page in a terminal, run `man node`.
 
 Execute without arguments to start the [REPL][].
 
-_For more info about `node inspect`, please see the [debugger][] documentation._
+For more info about `node inspect`, see the [debugger][] documentation.
 
 ## Options
 <!-- YAML
@@ -30,22 +30,21 @@ changes:
 -->
 
 All options, including V8 options, allow words to be separated by both
-dashes (`-`) or underscores (`_`).
+dashes (`-`) or underscores (`_`). For example, `--pending-deprecation` is
+equivalent to `--pending_deprecation`.
 
-For example, `--pending-deprecation` is equivalent to `--pending_deprecation`.
-
-If an option that takes a single value, for example `--max-http-header-size`,
-is passed more than once, then the last passed value will be used. Options
-from the command line take precedence over options passed through the
-[`NODE_OPTIONS`][] environment variable.
+If an option that takes a single value (such as `--max-http-header-size`) is
+passed more than once, then the last passed value is used. Options from the
+command line take precedence over options passed through the [`NODE_OPTIONS`][]
+environment variable.
 
 ### `-`
 <!-- YAML
 added: v8.0.0
 -->
 
 Alias for stdin. Analogous to the use of `-` in other command line utilities,
-meaning that the script will be read from stdin, and the rest of the options
+meaning that the script is read from stdin, and the rest of the options
 are passed to that script.
 
 ### `--`
@@ -55,7 +54,7 @@ added: v6.11.0
 
 Indicate the end of node options. Pass the rest of the arguments to the script.
 If no script filename or eval/print script is supplied prior to this, then
-the next argument will be used as a script filename.
+the next argument is used as a script filename.
 
 ### `--abort-on-uncaught-exception`
 <!-- YAML
@@ -106,10 +105,10 @@ added: v12.0.0
 Starts the V8 CPU profiler on start up, and writes the CPU profile to disk
 before exit.
 
-If `--cpu-prof-dir` is not specified, the generated profile will be placed
+If `--cpu-prof-dir` is not specified, the generated profile is placed
 in the current working directory.
 
-If `--cpu-prof-name` is not specified, the generated profile will be
+If `--cpu-prof-name` is not specified, the generated profile is
 named `CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile`.
 
 ```console
@@ -152,7 +151,7 @@ Specify the file name of the CPU profile generated by `--cpu-prof`.
 
 ### `--diagnostic-dir=directory`
 
-Set the directory to which all diagnostic output files will be written to.
+Set the directory to which all diagnostic output files are written.
 Defaults to current working directory.
 
 Affects the default output directory of:
@@ -166,8 +165,8 @@ added: v13.12.0
 -->
 
 Disable the `Object.prototype.__proto__` property. If `mode` is `delete`, the
-property will be removed entirely. If `mode` is `throw`, accesses to the
-property will throw an exception with the code `ERR_PROTO_ACCESS`.
+property is removed entirely. If `mode` is `throw`, accesses to the
+property throw an exception with the code `ERR_PROTO_ACCESS`.
 
 ### `--disallow-code-generation-from-strings`
 <!-- YAML
@@ -254,10 +253,10 @@ Sets the resolution algorithm for resolving ES module specifiers. Valid options
 are `explicit` and `node`.
 
 The default is `explicit`, which requires providing the full path to a
-module. The `node` mode will enable support for optional file extensions and
+module. The `node` mode enables support for optional file extensions and
 the ability to import a directory that has an index file.
 
-Please see [customizing ESM specifier resolution][] for example usage.
+See [customizing ESM specifier resolution][] for example usage.
 
 ### `--experimental-vm-modules`
 <!-- YAML
@@ -347,10 +346,10 @@ added: v12.4.0
 Starts the V8 heap profiler on start up, and writes the heap profile to disk
 before exit.
 
-If `--heap-prof-dir` is not specified, the generated profile will be placed
+If `--heap-prof-dir` is not specified, the generated profile is placed
 in the current working directory.
 
-If `--heap-prof-name` is not specified, the generated profile will be
+If `--heap-prof-name` is not specified, the generated profile is
 named `Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile`.
 
 ```console
@@ -621,8 +620,8 @@ This flag exists so that the main module can be opted-in to the same behavior
 that `--preserve-symlinks` gives to all other imports; they are separate flags,
 however, for backward compatibility with older Node.js versions.
 
-`--preserve-symlinks-main` does not imply `--preserve-symlinks`; it
-is expected that `--preserve-symlinks-main` will be used in addition to
+`--preserve-symlinks-main` does not imply `--preserve-symlinks`; use
+`--preserve-symlinks-main` in addition to
 `--preserve-symlinks` when it is not desirable to follow symlinks before
 resolving relative paths.
 
@@ -1192,8 +1191,7 @@ compound after anything in `options...`. Node.js will exit with an error if
 an option that is not allowed in the environment is used, such as `-p` or a
 script file.
 
-In case an option value happens to contain a space (for example a path listed
-in `--require`), it must be escaped using double quotes. For example:
+If an option value contains a space, it can be escaped using double quotes:
 
 ```bash
 NODE_OPTIONS='--require "./my path/file.js"'
@@ -1555,22 +1553,22 @@ On a machine with 2GB of memory, consider setting this to
 $ node --max-old-space-size=1536 index.js
 ```
 
+[Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
+[REPL]: repl.html
+[ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage
+[Source Map]: https://sourcemaps.info/spec.html
+[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+[V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
 [`--openssl-config`]: #cli_openssl_config_file
 [`Atomics.wait()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics/wait
 [`Buffer`]: buffer.html#buffer_class_buffer
-[`SlowBuffer`]: buffer.html#buffer_class_slowbuffer
 [`NODE_OPTIONS`]: #cli_node_options_options
+[`SlowBuffer`]: buffer.html#buffer_class_slowbuffer
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`tls.DEFAULT_MAX_VERSION`]: tls.html#tls_tls_default_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.html#tls_tls_default_min_version
 [`unhandledRejection`]: process.html#process_event_unhandledrejection
 [`worker_threads.threadId`]: worker_threads.html#worker_threads_worker_threadid
-[Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
-[REPL]: repl.html
-[ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage
-[Source Map]: https://sourcemaps.info/spec.html
-[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
-[V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
 [context-aware]: addons.html#addons_context_aware_addons
 [customizing ESM specifier resolution]: esm.html#esm_customizing_esm_specifier_resolution_algorithm
 [debugger]: debugger.html