Merge topic 'docs-cleanup-3.19'

95c14579f2 Help: Cleanup typos and grammar for the 3.19 release

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5419

7 files changed, 57 insertions, 45 deletions

diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index 00e1a69ccd..40a45e3be7 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -134,14 +134,14 @@ The options are:
 
 ``ID <id>``
   Specify an identification for the deferred call.
-  The id may not be empty and may not begin in a capital letter ``A-Z``.
-  The id may begin in a ``_`` only if it was generated by another call
-  that used ``ID_VAR`` to get the id.
+  The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
+  The ``<id>`` may begin with an underscore (``_``) only if it was generated
+  automatically by an earlier call that used ``ID_VAR`` to get the id.
 
 ``ID_VAR <var>``
-  Sepcify a variable in which to store the identification for the
+  Specify a variable in which to store the identification for the
   deferred call.  If ``ID <id>`` is not given, a new identification
-  will be generated starting in a ``_``.
+  will be generated and the generated id will start with an underscore (``_``).
 
 The currently scheduled list of deferred calls may be retrieved:
 
@@ -149,7 +149,7 @@ The currently scheduled list of deferred calls may be retrieved:
 
   cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
 
-This will store in ``<var>`` a :ref:`Semicolon-separated list <CMake Language
+This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
 Lists>` of deferred call ids.
 
 Details of a specific call may be retrieved from its id:
@@ -158,7 +158,7 @@ Details of a specific call may be retrieved from its id:
 
   cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
 
-This will store in ``<var>`` a :ref:`Semicolon-separated list <CMake Language
+This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
 Lists>` in which the first element is the name of the command to be
 called, and the remaining elements are its unevaluated arguments (any
 contained ``;`` characters are included literally and cannot be distinguished
diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst
index 46d1a05954..c59995ae2a 100644
--- a/Help/command/configure_file.rst
+++ b/Help/command/configure_file.rst
@@ -83,7 +83,7 @@ The arguments are:
   Restrict variable replacement to references of the form ``@VAR@``.
   This is useful for configuring scripts that use ``${VAR}`` syntax.
 
- ``NO_SOURCE_PERMISSIONS``
+``NO_SOURCE_PERMISSIONS``
   Does not transfer the file permissions of the original file to the copy.
   The copied file permissions default to the standard 644 value
   (-rw-r--r--).
diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst
index a6f141a4c0..268c3075bf 100644
--- a/Help/command/execute_process.rst
+++ b/Help/command/execute_process.rst
@@ -118,9 +118,17 @@ Options:
   This is analogous to the ``tee`` Unix command.
 
 ``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
-  ``COMMAND_ERROR_IS_FATAL ANY`` option stops processing if any command fails.
-  ``COMMAND_ERROR_IS_FATAL LAST`` option stops processing if the last command
-  in the command list fails.
+  The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when
+  an error is encountered:
+
+    ``ANY``
+    If any of the commands in the list of commands fail, the
+    ``execute_process()`` command halts with an error.
+
+    ``LAST``
+    If the last command in the list of commands fails, the
+    ``execute_process()`` command halts with an error.  Commands earlier in the
+    list will not cause a fatal error.
 
 If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
 same pipe the precedence is not specified.
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 4210bd4cb9..b406e10ff8 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -54,7 +54,7 @@ Synopsis
     file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
 
   `Transfer`_
-    file(`DOWNLOAD`_ <url> <file> [...])
+    file(`DOWNLOAD`_ <url> [<file>] [...])
     file(`UPLOAD`_ <file> <url> [...])
 
   `Locking`_
@@ -498,8 +498,9 @@ from the input content to produce the output content.  The options are:
   See policy :policy:`CMP0070`.
 
 ``TARGET <target>``
-  Specify target which to use when evaluating generator expressions.  Enables
-  use of generator expressions requiring a target.
+  Specify which target to use when evaluating generator expressions that
+  require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
+  ``$<TARGET_PROPERTY:prop>``).
 
 Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
 ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
@@ -763,7 +764,8 @@ which would make them unable to support a hard link.
 
 .. code-block:: cmake
 
-  file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...]
+  file(CHMOD <files>... <directories>...
+      [PERMISSIONS <permissions>...]
       [FILE_PERMISSIONS <permissions>...]
       [DIRECTORY_PERMISSIONS <permissions>...])
 
@@ -775,34 +777,36 @@ Valid permissions are  ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``,
 Valid combination of keywords are:
 
 ``PERMISSIONS``
-  all items are changed
+  All items are changed.
 
 ``FILE_PERMISSIONS``
-  only files are changed
+  Only files are changed.
 
 ``DIRECTORY_PERMISSIONS``
-  only directories are changed
+  Only directories are changed.
 
 ``PERMISSIONS`` and ``FILE_PERMISSIONS``
-  ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files
+  ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.
 
 ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
-  ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories
+  ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.
 
 ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
-  use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
-  directories
+  Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
+  directories.
 
 
 .. _CHMOD_RECURSE:
 
 .. code-block:: cmake
 
-  file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>...
-       FILE_PERMISSIONS <permissions>... DIRECTORY_PERMISSIONS <permissions>...)
+  file(CHMOD_RECURSE <files>... <directories>...
+       [PERMISSIONS <permissions>...]
+       [FILE_PERMISSIONS <permissions>...]
+       [DIRECTORY_PERMISSIONS <permissions>...])
 
 Same as `CHMOD`_, but change the permissions of files and directories present in
-the ``<directories>..`` recursively.
+the ``<directories>...`` recursively.
 
 Path Conversion
 ^^^^^^^^^^^^^^^
@@ -859,11 +863,11 @@ Transfer
   file(DOWNLOAD <url> [<file>] [<options>...])
   file(UPLOAD   <file> <url> [<options>...])
 
-The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. If
-``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. This
-can be useful if you want to know if a file can be downloaded (for example, to
-check that it exists) without actually saving it anywhere. The ``UPLOAD`` mode
-uploads a local ``<file>`` to a given ``<url>``.
+The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``.
+If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved.
+This can be useful if you want to know if a file can be downloaded (for example,
+to check that it exists) without actually saving it anywhere. The ``UPLOAD``
+mode uploads a local ``<file>`` to a given ``<url>``.
 
 Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 
@@ -986,8 +990,7 @@ Archiving
   file(ARCHIVE_CREATE OUTPUT <archive>
     PATHS <paths>...
     [FORMAT <format>]
-    [COMPRESSION <compression>]
-    [COMPRESSION_LEVEL <compression level>]
+    [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
     [MTIME <mtime>]
     [VERBOSE])
 
@@ -1005,9 +1008,9 @@ compression.  The other formats use no compression by default, but can be
 directed to do so with the ``COMPRESSION`` option.  Valid values for
 ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
 
-Compression level can be specied by using ``COMPRESSION_LEVEL`` option.
-Compression level should be between 0-9. 0 is the default compression.
-``COMPRESSION`` option must be specified for ``COMPRESSION_LEVEL``.
+The compression level can be specified with the ``COMPRESSION_LEVEL`` option.
+The ``<compression-level>`` should be between 0-9, with the default being 0.
+The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given.
 
 .. note::
   With ``FORMAT`` set to ``raw`` only one file will be compressed with the
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 87265cebc0..1be2e09eef 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -44,7 +44,8 @@ specified:
   * A version range with the format ``versionMin...[<]versionMax`` where
     ``versionMin`` and ``versionMax`` have the same format as the single
     version.  By default, both end points are included.  By specifying ``<``,
-    the upper end point will be excluded.
+    the upper end point will be excluded.  Version ranges are only supported
+    with CMake 3.19 or later.
 
 The ``EXACT`` option requests that the version be matched exactly. This option
 is incompatible with the specification of a version range.
diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst
index 3c094aaedc..69fb726723 100644
--- a/Help/command/separate_arguments.rst
+++ b/Help/command/separate_arguments.rst
@@ -37,7 +37,7 @@ be one of the following keywords:
 
 ``PROGRAM``
   The first item in ``<args>`` is assumed to be an executable and will be
-  search in the system search path or left as a full path. If not found,
+  searched in the system search path or left as a full path. If not found,
   ``<variable>`` will be empty. Otherwise, ``<variable>`` is a list of 2
   elements:
 
diff --git a/Help/command/string.rst b/Help/command/string.rst
index 0bc2b484d9..0c2f57e68b 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -484,12 +484,12 @@ where each ``x`` represents a lower case hexadecimal character.
 Where required, an uppercase representation can be requested
 with the optional ``UPPER`` flag.
 
+.. _JSON:
+
 JSON
 ^^^^
 
-.. _JSON:
-
-Functionality for querying a JSON string
+Functionality for querying a JSON string.
 
 .. _GET:
 .. code-block:: cmake
@@ -522,7 +522,7 @@ will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
          MEMBER <json-string>
          [<member|index> ...] <index>)
 
-Get the name of the ``<index>``:th member in ``<json-string>`` at the location
+Get the name of the ``<index>``-th member in ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments.
 Requires an element of object type.
 
@@ -534,7 +534,7 @@ Requires an element of object type.
 
 Get the length of an element in ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments.
-Required an element of array or object type.
+Requires an element of array or object type.
 
 .. _REMOVE:
 .. code-block:: cmake
@@ -544,7 +544,7 @@ Required an element of array or object type.
 
 Remove an element from ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments. The JSON string
-without the removed element will we written in ``<out-var>``.
+without the removed element will be stored in ``<out-var>``.
 
 .. _SET:
 .. code-block:: cmake
@@ -566,8 +566,8 @@ Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>``
 for equality
 
 
-If the optional ``ERROR_VARIABLE`` argument is given errors will be
-reported in ``<error-variable>``. If no error occurs the ``<error-variable>``
+If the optional ``ERROR_VARIABLE`` argument is given, errors will be
+reported in ``<error-variable>``. If no error occurs, the ``<error-variable>``
 will be set to ``NOTFOUND``. If ``ERROR_VARIABLE`` is not set a CMake error
 will be issued.
 When an error occurs the ``<out-var>`` will be set to