Help: Cleanup typos and grammar for the 3.19 release

2026-03-01 12:18:36 -06:00 · 2020-10-24 22:48:30 +11:00
parent f2a59d400e
commit 95c14579f2
14 changed files with 106 additions and 89 deletions
--- 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
--- 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--).
--- 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.
--- 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
--- 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.
--- 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:

--- 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