Merge topic 'docs-cleanup-3.19' into release-3.19

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

Acked-by: Kitware Robot <[email protected]>
Merge-request: !5419

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

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

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.

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

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.

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:
 

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

Help/cpack_gen/external.rst

@@ -285,6 +285,6 @@ Variables specific to CPack External generator
 .. variable:: CPACK_EXTERNAL_BUILT_PACKAGES
 
   The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the
-  full paths of generated package files.  CPack copy these files from the stage
-  directory back to the top build directory and possibly produce checksum files
-  if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.
+  full paths of generated package files.  CPack will copy these files from the
+  staging directory back to the top build directory and possibly produce
+  checksum files if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.

Help/policy/CMP0112.rst

@@ -21,13 +21,13 @@ file name components no longer add a dependency on the evaluated target.
 
 
 In CMake 3.18 and lower a dependency on the evaluated target of the above
-generator expressions would be always added.  CMake 3.19 and above prefer
+generator expressions would always be added.  CMake 3.19 and above prefer
 to not add this dependency.  This policy provides compatibility for projects
 that have not been updated to expect the new behavior.
 
 The ``OLD`` behavior for this policy is to add a dependency on the evaluated
-target for the the above generator expressions.  The ``NEW`` behavior of
-this policy is to not add a dependency on the evaluated target for the the
+target for the above generator expressions.  The ``NEW`` behavior of
+this policy is to not add a dependency on the evaluated target for the
 above generator expressions.
 
 This policy was introduced in CMake version 3.19.  Unlike many policies,

Help/policy/CMP0114.rst

@@ -47,7 +47,7 @@ a revised design to address these problems:
   * The ``download``, ``update``, and ``patch`` steps are independent.
   * The ``configure``, ``build``, ``test``, and ``install`` steps are not.
 
-  For custom steps, the :command:`ExternalProject_Add_Step` command provies
+  For custom steps, the :command:`ExternalProject_Add_Step` command provides
   an ``INDEPENDENT`` option to mark them as independent.  It is an error to
   mark a step as independent if it depends on other steps that are not.  Note
   that this use of the term "independent" refers only to independence from

Help/release/3.19.rst

@@ -14,7 +14,8 @@ Presets
 -------
 
 * :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
-  ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
+  ``CMakePresets.json`` and ``CMakeUserPresets.json`` files (see
+  :manual:`cmake-presets(7)`).
 
 Generators
 ----------
@@ -105,21 +106,22 @@ Commands
 * The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
   support resolving target-dependent generator expressions.
 
-* The :command:`file` gained sub-command `REAL_PATH` to compute a path with
-  symlinks resolved.
+* The :command:`file` command gained a new ``REAL_PATH`` sub-command to
+  compute a path with symlinks resolved.
 
 * The :command:`find_package` command learned to handle a version range.
 
-* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
-  search program.
+* The :command:`separate_arguments` command gained a new ``PROGRAM`` option.
+  It allows the arguments to be treated as a program invocation and will
+  resolve the executable to a full path if it can be found.
 
-* The :command:`set_property`, :command:`get_property`,
-  and :command:`get_directory_property` commands' ``DIRECTORY``
-  options now accept references to binary directory paths,
-  such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
+* The ``DIRECTORY`` option of the :command:`set_property`,
+  :command:`get_property`, and :command:`get_directory_property` commands
+  now accepts references to binary directory paths, such as the value of
+  :variable:`CMAKE_CURRENT_BINARY_DIR`.
 
-* The :command:`string` command gained set of new ``JSON`` sub commands
-  to provide JSON parsing capabilities.
+* The :command:`string` command gained a set of new ``JSON`` sub commands
+  that provide JSON parsing capabilities.
 
 Variables
 ---------
@@ -134,6 +136,9 @@ Variables
   initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and
   avoid unnecessarily building dependencies for a static library.
 
+* The :variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable was added to
+  initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property.
+
 * The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
   was added to tell the :ref:`Visual Studio Generators` what maximum
   version of the Windows SDK to choose.
@@ -149,8 +154,8 @@ Properties
 
 * The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
   template instantiation in the precompiled header. This is enabled by default
-  and offers a roughly 20% compile time improvement. Currently only supported
-  by Clang 11.
+  and may significantly improve compile times. Currently only supported for
+  Clang (version 11 or later).
 
 * The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
@@ -175,19 +180,20 @@ Modules
   :module:`CheckCXXSourceRuns` to more languages.
   It also supports the ``CUDA`` language.
 
-* :module:`CMakePackageConfigHelpers` module learned to manage version range.
+* The :module:`CMakePackageConfigHelpers` module gained support for version
+  ranges.
 
 * The :module:`FindCUDAToolkit` module gained support for finding CUDA
   toolkits that do not contain ``nvcc``, as well as for finding scattered
   toolkit installations when cross-compiling.
 
 * The :module:`FindPackageHandleStandardArgs` module learned to handle
-  version range. It also gained the ``find_package_check_version()`` command to
-  check the validity of a version against version-related arguments of
+  version ranges. It also gained the ``find_package_check_version()`` command
+  to check the validity of a version against version-related arguments of
   :command:`find_package` command.
 
 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
-  modules gained the capability to manage a version range.
+  modules gained the ability to handle a version range.
 
 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
   modules provide, respectively, the variable ``Python3_LINK_OPTIONS``,
@@ -195,14 +201,14 @@ Modules
 
 * The :module:`FindSDL` module now provides:
 
-  * imported target ``SDL::SDL``,
+  * An imported target ``SDL::SDL``.
 
-  * result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,
+  * Result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``.
 
-  * version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
+  * Version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``,
     ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
 
-* :module:`FindSWIG` module gains the capability to manage a version range.
+* The :module:`FindSWIG` module gained the ability to handle a version range.
 
 * The :module:`FindTIFF` module gained a ``CXX`` component to
   find the ``tiffxx`` library containing C++ bindings.
@@ -211,15 +217,17 @@ Modules
   target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain
   the path to the GLSL SPIR-V compiler.
 
-* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
-  ``OUTFILE_DIR`` to manage output directories on per source basis.
+* The :module:`UseSWIG` module gained support for new source file properties
+  ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a
+  per-source basis.
 
 CTest
 -----
 
-* :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as
-  ``CTEST_MEMORYCHECK_COMMAND``.  The different tools (memcheck, racecheck,
-  synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by
+* :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker
+  (previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``.
+  The different tools (``memcheck``, ``racecheck``, ``synccheck`` and
+  ``initcheck``) supported by ``compute-sanitizer`` can be selected by
   adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
   variable.  The default flags are ``--tool memcheck --leak-check full``.
 

Modules/CMakePackageConfigHelpers.cmake

@@ -161,8 +161,8 @@ macro.
 
 .. note:: ``COMPATIBILITY_MODE`` ``AnyNewerVersion`` handles the version range
   if any is specified (see :command:`find_package` command for the details).
-  All other modes are incompatible with version range and will display an
-  author warning if a one is specified.
+  All other modes are incompatible with version ranges and will display an
+  author warning if one is specified.
 
 If ``ARCH_INDEPENDENT`` is given, the installed package version will be
 considered compatible even if it was built for a different architecture than

Modules/CheckCompilerFlag.cmake

@@ -19,7 +19,7 @@ Check that the ``<flag>`` is accepted by the compiler without a diagnostic.
 Stores the result in an internal cache entry named ``<var>``.
 
 This command temporarily sets the ``CMAKE_REQUIRED_DEFINITIONS`` variable
-and calls the ``check_source_compiles(<LANG>`` function from the
+and calls the ``check_source_compiles(<LANG>)`` function from the
 :module:`CheckSourceCompiles` module.  See documentation of that
 module for a listing of variables that can otherwise modify the build.
 

Modules/CheckLinkerFlag.cmake

@@ -19,15 +19,12 @@ Check that the link ``<flag>`` is accepted by the ``<lang>`` compiler without
 a diagnostic.  Stores the result in an internal cache entry named ``<var>``.
 
 This command temporarily sets the ``CMAKE_REQUIRED_LINK_OPTIONS`` variable
-and calls the ``check_<lang>_source_compiles`` macro from the
-``Check<lang>SourceCompiles`` module (:module:`CheckCSourceCompiles`,
-:module:`CheckCSourceCompiles`, :module:`CheckCXXSourceCompiles`,
-:module:`CheckOBJCSourceCompiles`, :module:`CheckOBJCXXSourceCompiles` or
-:module:`CheckFortranSourceCompiles`).  See documentation of these
-modules for a listing of variables that can otherwise modify the build.
-
-The underlying implementation rely on :prop_tgt:`LINK_OPTIONS` property to
-check the specified flag. The ``LINKER:`` prefix, as described in
+and calls the :command:`check_source_compiles` command from the
+:module:`CheckSourceCompiles` module.  See that module's documentation
+for a listing of variables that can otherwise modify the build.
+
+The underlying implementation relies on the :prop_tgt:`LINK_OPTIONS` property
+to check the specified flag. The ``LINKER:`` prefix, as described in the
 :command:`target_link_options` command, can be used as well.
 
 A positive result from this check indicates only that the compiler did not