Help: Fix CMakePackageConfigHelpers typos, grammar and formatting

1 files changed, 56 insertions, 57 deletions

diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake
index dfe1ec7dcc..ba8568930c 100644
--- a/Modules/CMakePackageConfigHelpers.cmake
+++ b/Modules/CMakePackageConfigHelpers.cmake
@@ -5,7 +5,7 @@
 CMakePackageConfigHelpers
 -------------------------
 
-Helpers functions for creating config files that can be included by other
+Helper functions for creating config files that can be included by other
 projects to find and use a package.
 
 Generating a Package Configuration File
@@ -26,11 +26,11 @@ Generating a Package Configuration File
 ``configure_package_config_file()`` should be used instead of the plain
 :command:`configure_file()` command when creating the ``<PackageName>Config.cmake``
 or ``<PackageName>-config.cmake`` file for installing a project or library.
-It helps making the resulting package relocatable by avoiding hardcoded paths
-in the installed ``Config.cmake`` file.
+It helps make the resulting package relocatable by avoiding hardcoded paths
+in the installed ``<PackageName>Config.cmake`` file.
 
 In a ``FooConfig.cmake`` file there may be code like this to make the install
-destinations know to the using project:
+destinations known to the using project:
 
 .. code-block:: cmake
 
@@ -40,27 +40,25 @@ destinations know to the using project:
    #...logic to determine installedPrefix from the own location...
    set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
 
-All 4 options shown above are not sufficient, since the first 3 hardcode the
-absolute directory locations, and the 4th case works only if the logic to
+All four options shown above are not sufficient  The first three hardcode the
+absolute directory locations.  The fourth case works only if the logic to
 determine the ``installedPrefix`` is correct, and if ``CONFIG_INSTALL_DIR``
 contains a relative path, which in general cannot be guaranteed.  This has the
 effect that the resulting ``FooConfig.cmake`` file would work poorly under
-Windows and OSX, where users are used to choose the install location of a
+Windows and macOS, where users are used to choosing the install location of a
 binary package at install time, independent from how
 :variable:`CMAKE_INSTALL_PREFIX` was set at build/cmake time.
 
-Using ``configure_package_config_file`` helps.  If used correctly, it makes
+Using ``configure_package_config_file()`` helps.  If used correctly, it makes
 the resulting ``FooConfig.cmake`` file relocatable.  Usage:
 
-1. write a ``FooConfig.cmake.in`` file as you are used to
-2. insert a line containing only the string ``@PACKAGE_INIT@``
-3. instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
+1. Write a ``FooConfig.cmake.in`` file as you are used to.
+2. Insert a line at the top containing only the string ``@PACKAGE_INIT@``.
+3. Instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
    ``set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")`` (this must be after the
-   ``@PACKAGE_INIT@`` line)
-4. instead of using the normal :command:`configure_file()`, use
-   ``configure_package_config_file()``
-
-
+   ``@PACKAGE_INIT@`` line).
+4. Instead of using the normal :command:`configure_file()` command, use
+   ``configure_package_config_file()``.
 
 The ``<input>`` and ``<output>`` arguments are the input and output file, the
 same way as in :command:`configure_file()`.
@@ -70,48 +68,47 @@ the ``FooConfig.cmake`` file will be installed to.  This path can either be
 absolute, or relative to the ``INSTALL_PREFIX`` path.
 
 The variables ``<var1>`` to ``<varN>`` given as ``PATH_VARS`` are the
-variables which contain install destinations.  For each of them the macro will
+variables which contain install destinations.  For each of them, the macro will
 create a helper variable ``PACKAGE_<var...>``.  These helper variables must be
 used in the ``FooConfig.cmake.in`` file for setting the installed location.
-They are calculated by ``configure_package_config_file`` so that they are
+They are calculated by ``configure_package_config_file()`` so that they are
 always relative to the installed location of the package.  This works both for
-relative and also for absolute locations.  For absolute locations it works
+relative and also for absolute locations.  For absolute locations, it works
 only if the absolute location is a subdirectory of ``INSTALL_PREFIX``.
 
 .. versionadded:: 3.1
-  If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to
+  If the ``INSTALL_PREFIX`` argument is passed, this is used as the base path to
   calculate all the relative paths.  The ``<path>`` argument must be an absolute
   path.  If this argument is not passed, the :variable:`CMAKE_INSTALL_PREFIX`
   variable will be used instead.  The default value is good when generating a
-  FooConfig.cmake file to use your package from the install tree.  When
-  generating a FooConfig.cmake file to use your package from the build tree this
-  option should be used.
+  ``FooConfig.cmake`` file to use your package from the install tree.  When
+  generating a ``FooConfig.cmake`` file to use your package from the build tree,
+  this option should be used.
 
-By default ``configure_package_config_file`` also generates two helper macros,
-``set_and_check()`` and ``check_required_components()`` into the
+By default, ``configure_package_config_file()`` also generates two helper
+macros, ``set_and_check()`` and ``check_required_components()``, into the
 ``FooConfig.cmake`` file.
 
-``set_and_check()`` should be used instead of the normal ``set()`` command for
-setting directories and file locations.  Additionally to setting the variable
-it also checks that the referenced file or directory actually exists and fails
-with a ``FATAL_ERROR`` otherwise.  This makes sure that the created
+``set_and_check()`` should be used instead of the normal :command:`set` command
+for setting directories and file locations.  In addition to setting the
+variable, it also checks that the referenced file or directory actually exists
+and fails with a fatal error if it doesn't.  This ensures that the generated
 ``FooConfig.cmake`` file does not contain wrong references.
-When using the ``NO_SET_AND_CHECK_MACRO``, this macro is not generated
-into the ``FooConfig.cmake`` file.
+Add the ``NO_SET_AND_CHECK_MACRO`` option to prevent the generation of the
+``set_and_check()`` macro in the ``FooConfig.cmake`` file.
 
 ``check_required_components(<PackageName>)`` should be called at the end of
 the ``FooConfig.cmake`` file. This macro checks whether all requested,
-non-optional components have been found, and if this is not the case, sets
-the ``Foo_FOUND`` variable to ``FALSE``, so that the package is considered to
+non-optional components have been found, and if this is not the case, it sets
+the ``Foo_FOUND`` variable to ``FALSE`` so that the package is considered to
 be not found.  It does that by testing the ``Foo_<Component>_FOUND``
 variables for all requested required components.  This macro should be
 called even if the package doesn't provide any components to make sure
-users are not specifying components erroneously.  When using the
-``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option, this macro is not generated
-into the ``FooConfig.cmake`` file.
+users are not specifying components erroneously.  Add the
+``NO_CHECK_REQUIRED_COMPONENTS_MACRO`` option to prevent the generation of the
+``check_required_components()`` macro in the ``FooConfig.cmake`` file.
 
-For an example see below the documentation for
-:command:`write_basic_package_version_file()`.
+See also :ref:`CMakePackageConfigHelpers Examples`.
 
 Generating a Package Version File
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -126,11 +123,11 @@ Generating a Package Version File
      [ARCH_INDEPENDENT] )
 
 
-Writes a file for use as ``<PackageName>ConfigVersion.cmake`` file to
+Writes a file for use as a ``<PackageName>ConfigVersion.cmake`` file to
 ``<filename>``.  See the documentation of :command:`find_package()` for
-details on this.
+details on such files.
 
-``<filename>`` is the output filename, it should be in the build tree.
+``<filename>`` is the output filename, which should be in the build tree.
 ``<major.minor.patch>`` is the version number of the project to be installed.
 
 If no ``VERSION`` is given, the :variable:`PROJECT_VERSION` variable is used.
@@ -153,9 +150,9 @@ the requested version matches exactly its own version number (not considering
 the tweak version).  For example, version 1.2.3 of a package is only
 considered compatible to requested version 1.2.3.  This mode is for packages
 without compatibility guarantees.
-If your project has more elaborated version matching rules, you will need to
-write your own custom ``ConfigVersion.cmake`` file instead of using this
-macro.
+If your project has more elaborate version matching rules, you will need to
+write your own custom ``<PackageName>ConfigVersion.cmake`` file instead of
+using this macro.
 
 .. versionadded:: 3.11
   The ``SameMinorVersion`` compatibility mode.
@@ -170,13 +167,13 @@ macro.
   unless ``ARCH_INDEPENDENT`` is given, in which case the package is considered
   compatible on any architecture.
 
-.. note:: ``ARCH_INDEPENDENT`` is intended for header-only libraries or similar
-  packages with no binaries.
+  .. note:: ``ARCH_INDEPENDENT`` is intended for header-only libraries or
+    similar packages with no binaries.
 
 .. versionadded:: 3.19
   The version file generated by ``AnyNewerVersion``, ``SameMajorVersion`` and
-  ``SameMinorVersion`` arguments of ``COMPATIBILITY`` handle the version range
-  if any is specified (see :command:`find_package` command for the details).
+  ``SameMinorVersion`` arguments of ``COMPATIBILITY`` handle the version range,
+  if one is specified (see :command:`find_package` command for the details).
   ``ExactVersion`` mode is incompatible with version ranges and will display an
   author warning if one is specified.
 
@@ -184,8 +181,9 @@ Internally, this macro executes :command:`configure_file()` to create the
 resulting version file.  Depending on the ``COMPATIBILITY``, the corresponding
 ``BasicConfigVersion-<COMPATIBILITY>.cmake.in`` file is used.
 Please note that these files are internal to CMake and you should not call
-:command:`configure_file()` on them yourself, but they can be used as starting
-point to create more sophisticated custom ``ConfigVersion.cmake`` files.
+:command:`configure_file()` on them yourself, but they can be used as a starting
+point to create more sophisticated custom ``<PackageName>ConfigVersion.cmake``
+files.
 
 Generating an Apple Platform Selection File
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -328,15 +326,16 @@ Generating an Apple Platform Selection File
     information to pretend the package was not found.  If this option
     is not given, the default behavior is to issue a fatal error.
 
+.. _`CMakePackageConfigHelpers Examples`:
+
 Example Generating Package Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Example using both :command:`configure_package_config_file` and
-``write_basic_package_version_file()``:
-
-``CMakeLists.txt``:
+Example using both the :command:`configure_package_config_file` and
+:command:`write_basic_package_version_file()` commands:
 
 .. code-block:: cmake
+   :caption: ``CMakeLists.txt``
 
    include(GNUInstallDirs)
    set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}/Foo
@@ -357,9 +356,9 @@ Example using both :command:`configure_package_config_file` and
                  ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
            DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo )
 
-``FooConfig.cmake.in``:
-
-::
+.. code-block:: cmake
+   :caption: ``FooConfig.cmake.in``
+   :force:
 
    set(FOO_VERSION x.y.z)
    ...