doc: revise introductory child_process text

This consolidates information about Windows environment variables and
has a few other smaller improvements (punctuation, present tense, etc.).

PR-URL: https://github.com/nodejs/node/pull/35344
Backport-PR-URL: https://github.com/nodejs/node/pull/35420
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

1 files changed, 15 insertions, 12 deletions

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index 34ee82e1441..c180176353d 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -6,7 +6,7 @@
 
 <!-- source_link=lib/child_process.js -->
 
-The `child_process` module provides the ability to spawn child processes in
+The `child_process` module provides the ability to spawn subprocesses in
 a manner that is similar, but not identical, to popen(3). This capability
 is primarily provided by the [`child_process.spawn()`][] function:
 
@@ -28,20 +28,23 @@ ls.on('close', (code) => {
 ```
 
 By default, pipes for `stdin`, `stdout`, and `stderr` are established between
-the parent Node.js process and the spawned child. These pipes have
-limited (and platform-specific) capacity. If the child process writes to
-stdout in excess of that limit without the output being captured, the child
-process will block waiting for the pipe buffer to accept more data. This is
+the parent Node.js process and the spawned subprocess. These pipes have
+limited (and platform-specific) capacity. If the subprocess writes to
+stdout in excess of that limit without the output being captured, the
+subprocess blocks waiting for the pipe buffer to accept more data. This is
 identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`
 option if the output will not be consumed.
 
-The command lookup will be performed using `options.env.PATH` environment
-variable if passed in `options` object, otherwise `process.env.PATH` will be
-used. To account for the fact that Windows environment variables are
-case-insensitive Node.js will lexicographically sort all `env` keys and choose
-the first one case-insensitively matching `PATH` to perform command lookup.
-This may lead to issues on Windows when passing objects to `env` option that
-have multiple variants of `PATH` variable.
+The command lookup is performed using the `options.env.PATH` environment
+variable if it is in the `options` object. Otherwise, `process.env.PATH` is
+used.
+
+On Windows, environment variables are case-insensitive. Node.js
+lexicographically sorts the `env` keys and uses the first one that
+case-insensitively matches. Only first (in lexicographic order) entry will be
+passed to the subprocess. This might lead to issues on Windows when passing
+objects to the `env` option that have multiple variants of the same key, such as
+`PATH` and `Path`.
 
 The [`child_process.spawn()`][] method spawns the child process asynchronously,
 without blocking the Node.js event loop. The [`child_process.spawnSync()`][]