Merge topic 'patch-find-modules'

1526655507 Find*: Add intro code blocks

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

Modules/FindASPELL.cmake

@@ -5,12 +5,23 @@
 FindASPELL
 ----------
 
-Finds the GNU Aspell spell checker library.
+Finds the GNU Aspell spell checker library:
+
+.. code-block:: cmake
+
+  find_package(ASPELL [<version>] [COMPONENTS <components>] [...])
 
 Components
 ^^^^^^^^^^
 
-This module supports the following components:
+This module supports optional components which can be specified using the
+:command:`find_package` command:
+
+.. code-block:: cmake
+
+  find_package(ASPELL [COMPONENTS <components>...])
+
+Supported components include:
 
 ``ASPELL``
   .. versionadded:: 4.1
@@ -22,13 +33,7 @@ This module supports the following components:
 
   Finds the Aspell command-line interactive spell checker executable.
 
-Components can be specified using the standard CMake syntax:
-
-.. code-block:: cmake
-
-  find_package(ASPELL [COMPONENTS <components>...])
-
-If no ``COMPONENTS`` are specified, the module searches for both the ``ASPELL``
+If no components are specified, the module searches for both the ``ASPELL``
 and ``Executable`` components by default.
 
 Imported Targets

Modules/FindBISON.cmake

@@ -10,7 +10,7 @@ generate custom build rules for using Bison:
 
 .. code-block:: cmake
 
-  find_package(BISON [<version>] ...)
+  find_package(BISON [<version>] [...])
 
 Bison is a parser generator that replaced earlier Yacc (Yet Another
 Compiler-Compiler).  On Unix-like systems, most common implementation is

Modules/FindBacktrace.cmake

@@ -62,7 +62,7 @@ Examples
 Finding Backtrace and linking it to a project target as of CMake 3.30:
 
 .. code-block:: cmake
-  :caption: CMakeLists.txt
+  :caption: ``CMakeLists.txt``
 
   find_package(Backtrace)
   target_link_libraries(app PRIVATE Backtrace::Backtrace)
@@ -71,7 +71,7 @@ The ``Backtrace_HEADER`` variable can be used, for example, in a configuration
 header file created by :command:`configure_file`:
 
 .. code-block:: cmake
-  :caption: CMakeLists.txt
+  :caption: ``CMakeLists.txt``
 
   add_library(app app.c)
 
@@ -81,7 +81,7 @@ header file created by :command:`configure_file`:
   configure_file(config.h.in config.h)
 
 .. code-block:: c
-  :caption: config.h.in
+  :caption: ``config.h.in``
 
   #cmakedefine01 Backtrace_FOUND
   #if Backtrace_FOUND
@@ -89,7 +89,7 @@ header file created by :command:`configure_file`:
   #endif
 
 .. code-block:: c
-  :caption: app.c
+  :caption: ``app.c``
 
   #include "config.h"
 
@@ -97,7 +97,7 @@ If the project needs to support CMake 3.29 or earlier, the imported target can
 be defined manually:
 
 .. code-block:: cmake
-  :caption: CMakeLists.txt
+  :caption: ``CMakeLists.txt``
 
   find_package(Backtrace)
   if(Backtrace_FOUND AND NOT TARGET Backtrace::Backtrace)

Modules/FindBoost.cmake

@@ -47,7 +47,7 @@ Result Variables
 This module defines the following variables:
 
 ``Boost_FOUND``
-  True if headers and requested libraries were found.
+  Boolean indicating whether headers and requested libraries were found.
 
 ``Boost_INCLUDE_DIRS``
   Boost include directories.
@@ -59,7 +59,8 @@ This module defines the following variables:
   Boost component libraries to be linked.
 
 ``Boost_<COMPONENT>_FOUND``
-  True if component ``<COMPONENT>`` was found (``<COMPONENT>`` name is upper-case).
+  Boolean indicating whether the component ``<COMPONENT>`` was found
+  (``<COMPONENT>`` name is upper-case).
 
 ``Boost_<COMPONENT>_LIBRARY``
   Libraries to link for component ``<COMPONENT>`` (may include
@@ -102,7 +103,7 @@ This module defines the following variables:
 .. versionadded:: 3.15
   The ``Boost_VERSION_<PART>`` variables.
 
-Cache variables
+Cache Variables
 ^^^^^^^^^^^^^^^
 
 Search results are saved persistently in CMake cache entries:
@@ -172,7 +173,7 @@ Imported Targets
 
 .. versionadded:: 3.5
 
-This module defines the following :prop_tgt:`IMPORTED` targets:
+This module provides the following :ref:`Imported Targets`:
 
 ``Boost::boost``
   Target for header-only dependencies. (Boost include directory).

Modules/FindBullet.cmake

@@ -5,7 +5,11 @@
 FindBullet
 ----------
 
-Finds the Bullet physics engine.
+Finds the Bullet physics engine:
+
+.. code-block:: cmake
+
+  find_package(Bullet [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -13,8 +17,8 @@ Result Variables
 This module defines the following variables:
 
 ``Bullet_FOUND``
-  Boolean true if Bullet was found.  For backward compatibility, the
-  ``BULLET_FOUND`` variable is also set to the same value.
+  Boolean indicating whether Bullet was found.  For backward compatibility,
+  the ``BULLET_FOUND`` variable is also set to the same value.
 ``BULLET_INCLUDE_DIRS``
   The Bullet include directories.
 ``BULLET_LIBRARIES``
@@ -33,11 +37,25 @@ This module accepts the following variables:
 Examples
 ^^^^^^^^
 
-Finding Bullet:
+Finding Bullet and conditionally creating an interface :ref:`imported target
+<Imported Targets>` that encapsulates its usage requirements for linking to a
+project target:
 
 .. code-block:: cmake
 
   find_package(Bullet)
+
+  if(Bullet_FOUND AND NOT TARGET Bullet::Bullet)
+    add_library(Bullet::Bullet INTERFACE IMPORTED)
+    set_target_properties(
+      Bullet::Bullet
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${BULLET_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${BULLET_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE Bullet::Bullet)
 #]=======================================================================]
 
 macro(_FIND_BULLET_LIBRARY _var)

Modules/FindCABLE.cmake

@@ -8,7 +8,11 @@ FindCABLE
 .. versionchanged:: 4.1
   This module is available only if policy :policy:`CMP0191` is not set to ``NEW``.
 
-Finds the CABLE installation and determines its include paths and libraries.
+Finds the CABLE installation and determines its include paths and libraries:
+
+.. code-block:: cmake
+
+  find_package(CABLE [...])
 
 Package called CABLE (CABLE Automates Bindings for Language Extension) was
 initially developed by Kitware to generate bindings to C++ classes for use in
@@ -25,7 +29,7 @@ package.
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-The following cache variables may be set when using this module:
+The following cache variables may also be set:
 
 ``CABLE``
   Path to the ``cable`` executable.

Modules/FindCUDAToolkit.cmake

@@ -107,7 +107,7 @@ Imported Targets
 
 An :ref:`imported target <Imported targets>` named ``CUDA::toolkit`` is provided.
 
-This module defines :prop_tgt:`IMPORTED` targets for each
+This module provides :ref:`Imported Targets` for each
 of the following libraries that are part of the CUDAToolkit:
 
 - `CUDA Runtime Library`_
@@ -568,8 +568,6 @@ Result variables
     found to determine the CUDA Toolkit version as well as determining other
     features of the Toolkit.  This variable is set for the convenience of
     modules that depend on this one.
-
-
 #]=======================================================================]
 
 # NOTE: much of this was simply extracted from FindCUDA.cmake.

Modules/FindCURL.cmake

@@ -6,7 +6,11 @@ FindCURL
 --------
 
 Finds the native curl installation (include directories and libraries) for
-transferring data with URLS.
+transferring data with URLS:
+
+.. code-block:: cmake
+
+  find_package(CURL [<version>] [COMPONENTS <components>...] [...])
 
 .. versionadded:: 3.17
   If curl is built using its CMake-based build system, it will provide its own

Modules/FindCVS.cmake

@@ -5,7 +5,11 @@
 FindCVS
 -------
 
-Finds the Concurrent Versions System (CVS).
+Finds the Concurrent Versions System (CVS):
+
+.. code-block:: cmake
+
+  find_package(CVS [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -13,7 +17,7 @@ Result Variables
 This module defines the following variables:
 
 ``CVS_FOUND``
-  True if the command-line client was found.
+  Boolean indicating whether the command-line client was found.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
@@ -78,8 +82,5 @@ find_program(CVS_EXECUTABLE cvs
   )
 mark_as_advanced(CVS_EXECUTABLE)
 
-# Handle the QUIETLY and REQUIRED arguments and set CVS_FOUND to TRUE if
-# all listed variables are TRUE
-
 include(FindPackageHandleStandardArgs)
 find_package_handle_standard_args(CVS DEFAULT_MSG CVS_EXECUTABLE)

Modules/FindCoin3D.cmake

@@ -5,7 +5,11 @@
 FindCoin3D
 ----------
 
-Finds Coin3D (Open Inventor).
+Finds Coin3D (Open Inventor):
+
+.. code-block:: cmake
+
+  find_package(Coin3D [...])
 
 Coin3D is an implementation of the Open Inventor API.  It provides
 data structures and algorithms for 3D visualization.
@@ -16,8 +20,8 @@ Result Variables
 This module defines the following variables:
 
 ``Coin3D_FOUND``
-  True if Coin3D, Open Inventor was found.  For backward compatibility, the
-  ``COIN3D_FOUND`` variable is also set to the same value.
+  Boolean indicating whether Coin3D, Open Inventor is found.  For backward
+  compatibility, the ``COIN3D_FOUND`` variable is also set to the same value.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
@@ -32,11 +36,25 @@ The following cache variables may also be set:
 Examples
 ^^^^^^^^
 
-Finding Coin3D:
+Finding Coin3D and conditionally creating an interface :ref:`imported target
+<Imported Targets>` that encapsulates its usage requirements for linking to a
+project target:
 
 .. code-block:: cmake
 
   find_package(Coin3D)
+
+  if(Coin3D_FOUND AND NOT TARGET Coin3D::Coin3D)
+    add_library(Coin3D::Coin3D INTERFACE IMPORTED)
+    set_target_properties(
+      Coin3D::Coin3D
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${COIN3D_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${COIN3D_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE Coin3D::Coin3D)
 #]=======================================================================]
 
 if (WIN32)

Modules/FindCurses.cmake

@@ -5,7 +5,11 @@
 FindCurses
 ----------
 
-Finds the curses or ncurses library.
+Finds the curses or ncurses library:
+
+.. code-block:: cmake
+
+  find_package(Curses [...])
 
 Curses is a terminal control library for Unix-like systems, used to build text
 user interface (TUI) applications.  Originally developed in 1978, it has since

Modules/FindCxxTest.cmake

@@ -6,7 +6,11 @@ FindCxxTest
 -----------
 
 Finds `CxxTest`_, a C++ unit testing framework suite, and provides a helper
-command to create test runners and integrate them with CTest.
+command to create test runners and integrate them with CTest:
+
+.. code-block:: cmake
+
+  find_package(CxxTest [...])
 
 .. _`CxxTest`: https://github.com/CxxTest/cxxtest
 

Modules/FindCygwin.cmake

@@ -6,7 +6,11 @@ FindCygwin
 ----------
 
 Finds Cygwin, a POSIX-compatible environment that runs natively on Microsoft
-Windows.
+Windows:
+
+.. code-block:: cmake
+
+  find_package(Cygwin [...])
 
 .. note::
 
@@ -30,7 +34,7 @@ Examples
 Finding the Cygwin installation and using its path in a custom find module:
 
 .. code-block:: cmake
-  :caption: FindFoo.cmake
+  :caption: ``FindFoo.cmake``
 
   find_package(Cygwin)
   find_program(Foo_EXECUTABLE NAMES foo PATHS ${CYGWIN_INSTALL_PATH}/bin)

Modules/FindDart.cmake

@@ -8,10 +8,20 @@ FindDart
 .. deprecated:: 3.27
   This module is available only if policy :policy:`CMP0145` is not set to ``NEW``.
 
-Find DART
+Finds DART:
 
-This module looks for the dart testing software and sets DART_ROOT to
+.. code-block:: cmake
+
+  find_package(DART [...])
+
+This module looks for the dart testing software and sets ``DART_ROOT`` to
 point to where it found it.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+``DART_ROOT``
+  The path to the Dart root installation.
 #]=======================================================================]
 
 if(_FindDart_testing)

Modules/FindDevIL.cmake

@@ -5,7 +5,11 @@
 FindDevIL
 ---------
 
-Finds the Developer's Image Library, `DevIL <https://openil.sourceforge.net/>`_.
+Finds the Developer's Image Library, `DevIL <https://openil.sourceforge.net/>`_:
+
+.. code-block:: cmake
+
+  find_package(DevIL [...])
 
 The DevIL package internally consists of the following libraries, all
 distributed as part of the same release:

Modules/FindEXPAT.cmake

@@ -27,7 +27,7 @@ This module provides the following :ref:`Imported Targets`:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``EXPAT_FOUND``
   Boolean indicating whether (the requested version of) Expat is found.

Modules/FindFLEX.cmake

@@ -10,7 +10,7 @@ and provides CMake commands to create custom build rules for using Flex:
 
 .. code-block:: cmake
 
-  find_package(FLEX [<version>] ...)
+  find_package(FLEX [<version>] [...])
 
 Flex generates lexical analyzers, also known as *scanners* or *lexers*.  It also
 includes a runtime library (``fl``) that supplies support functions for the

Modules/FindFLTK.cmake

@@ -6,7 +6,11 @@ FindFLTK
 --------
 
 Finds the Fast Light Toolkit (FLTK), a cross-platform toolkit for GUI
-development.
+development:
+
+.. code-block:: cmake
+
+  find_package(FLTK [...])
 
 FLTK uses CMake-based build system and provides a package configuration file for
 projects to find it.  As of its 1.4.0 version it also provides
@@ -18,8 +22,8 @@ This module takes that into account and first attempts to find FLTK in
 documentation for more information, how to use FLTK with CMake.
 
 .. versionadded:: 3.11
-  Debug and Release library variants are found separately and use
-  per-configuration variables.
+  Debug and release (optimized) library variants are found separately and use
+  :ref:`per-configuration <Build Configurations>` variables.
 
 Result Variables
 ^^^^^^^^^^^^^^^^

Modules/FindFLTK2.cmake

@@ -14,7 +14,11 @@ FindFLTK2
   modern versions, use the :module:`FindFLTK` module instead.
 
 Finds the Fast Light Toolkit (FLTK) version 2.x, a cross-platform toolkit for
-GUI development.
+GUI development:
+
+.. code-block:: cmake
+
+  find_package(FLTK2 [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^

Modules/FindFontconfig.cmake

@@ -7,7 +7,11 @@ FindFontconfig
 
 .. versionadded:: 3.14
 
-Finds Fontconfig, a library for font configuration and customization.
+Finds Fontconfig, a library for font configuration and customization:
+
+.. code-block:: cmake
+
+  find_package(Fontconfig [<version>] [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^

Modules/FindFreetype.cmake

@@ -11,6 +11,9 @@ Finds the FreeType font renderer library:
 
   find_package(Freetype [<version>] [...])
 
+.. versionadded:: 3.7
+  Debug and Release (optimized) library variants are found separately.
+
 Imported Targets
 ^^^^^^^^^^^^^^^^
 

Modules/FindGCCXML.cmake

@@ -7,14 +7,30 @@ FindGCCXML
 
 .. versionchanged:: 4.1
   This module is available only if policy :policy:`CMP0188` is not set to ``NEW``.
-  Port projects to search for CastXML by calling ``find_program`` directly.
+  Port projects to search for CastXML by calling :command:`find_program` directly.
 
-Find the GCC-XML front-end executable.
+Finds the GCC-XML front-end executable:
 
-This module will define the following variables:
+.. code-block:: cmake
+
+  find_package(GCCXML [...])
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
 
 ``GCCXML``
   The GCC-XML front-end executable.
+
+Examples
+^^^^^^^^
+
+In new code, find CastXML with :command:`find_program` instead:
+
+.. code-block:: cmake
+
+  find_program(CASTXML_EXECUTABLE castxml)
 #]=======================================================================]
 
 cmake_policy(GET CMP0188 _FindGCCXML_CMP0188)

Modules/FindGLEW.cmake

@@ -5,7 +5,11 @@
 FindGLEW
 --------
 
-Finds the OpenGL Extension Wrangler Library (GLEW).
+Finds the OpenGL Extension Wrangler Library (GLEW):
+
+.. code-block:: cmake
+
+  find_package(GLEW [<version>] [...])
 
 GLEW is a cross-platform C/C++ library that helps manage OpenGL extensions by
 providing efficient run-time mechanisms to query and load OpenGL functionality
@@ -53,7 +57,7 @@ Result Variables
 This module defines the following variables:
 
 ``GLEW_FOUND``
-  Boolean indicating whether GLEW is found.
+  Boolean indicating whether (the requested version of) GLEW is found.
 
 ``GLEW_VERSION``
   .. versionadded:: 3.15

Modules/FindGLUT.cmake

@@ -5,8 +5,13 @@
 FindGLUT
 --------
 
-Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API for
-creating windows, handling input, and managing events in OpenGL applications.
+Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API
+for creating windows, handling input, and managing events in OpenGL
+applications:
+
+.. code-block:: cmake
+
+  find_package(GLUT [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^

Modules/FindHDF5.cmake

@@ -10,7 +10,7 @@ self-describing array data:
 
 .. code-block:: cmake
 
-  find_package(HDF5 [<version>] ... [COMPONENTS <components>...] ...)
+  find_package(HDF5 [<version>] [COMPONENTS <components>...] [...])
 
 If the HDF5 library is built using its CMake-based build system, it will as
 of HDF5 version 1.8.15 provide its own CMake Package Configuration file

Modules/FindHTMLHelp.cmake

@@ -5,8 +5,12 @@
 FindHTMLHelp
 ------------
 
-This module finds the Microsoft HTML Help Compiler and its API.  It is part of
-the HTML Help Workshop.
+Finds the Microsoft HTML Help Compiler and its API which is part of the HTML
+Help Workshop:
+
+.. code-block:: cmake
+
+  find_package(HTMLHelp [...])
 
 .. note::
 
@@ -17,7 +21,7 @@ the HTML Help Workshop.
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-This module may set the following cache variables:
+The following cache variables may also be set:
 
 ``HTML_HELP_COMPILER``
   Full path to the HTML Help Compiler (``hhc.exe``), used to compile ``.chm``

Modules/FindICU.cmake

@@ -7,7 +7,11 @@ FindICU
 
 .. versionadded:: 3.7
 
-Finds the International Components for Unicode (ICU) libraries and programs.
+Finds the International Components for Unicode (ICU) libraries and programs:
+
+.. code-block:: cmake
+
+  find_package(ICU [<version>] COMPONENTS <components>... [...])
 
 .. versionadded:: 3.11
   Support for static libraries on Windows.
@@ -15,7 +19,13 @@ Finds the International Components for Unicode (ICU) libraries and programs.
 Components
 ^^^^^^^^^^
 
-This module supports the following components:
+This module supports components, which can be specified with:
+
+.. code-block:: cmake
+
+  find_package(ICU COMPONENTS <components>...)
+
+The following components are supported:
 
 ``data``
   Finds the ICU Data library.  On Windows, this library component is named
@@ -49,12 +59,8 @@ This module supports the following components:
   all other ICU libraries and is recommended to include when working with ICU
   components.
 
-At least one component should be specified for this module to successfully find
-ICU:
-
-.. code-block:: cmake
-
-  find_package(ICU COMPONENTS <components>...)
+At least one component should be specified for this module to successfully
+find ICU.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -74,13 +80,14 @@ Result Variables
 This module defines the following variables:
 
 ``ICU_FOUND``
-  Boolean indicating whether the main programs and libraries were found.
+  Boolean indicating whether the (requested version of) main ICU programs
+  and libraries were found.
+``ICU_VERSION``
+  The version of the ICU release found.
 ``ICU_INCLUDE_DIRS``
   The include directories containing the ICU headers.
 ``ICU_LIBRARIES``
   Component libraries to be linked.
-``ICU_VERSION``
-  The version of the ICU release found.
 
 ICU programs are defined in the following variables:
 

Modules/FindIce.cmake

@@ -7,7 +7,12 @@ FindIce
 
 .. versionadded:: 3.1
 
-Finds the Internet Communication Engine (Ice) programs, libraries and datafiles.
+Finds the Internet Communication Engine (Ice) programs, libraries and datafiles:
+
+.. code-block:: cmake
+
+  find_package(Ice [<version>] COMPONENTS <components>... [...])
+
 Ice is an open-source remote procedure call (RPC) framework developed by ZeroC
 and provides SDKs for various languages to develop network applications.
 

Modules/FindIconv.cmake

@@ -7,9 +7,14 @@ FindIconv
 
 .. versionadded:: 3.11
 
-This module finds the ``iconv()`` POSIX.1 functions on the system.  These
-functions might be provided in the standard C library or externally in the form
-of an additional library.
+Finds the ``iconv()`` POSIX.1 functions on the system:
+
+.. code-block:: cmake
+
+  find_package(Iconv [<version>] [...])
+
+Iconv functions might be provided in the standard C library or externally
+in the form of an additional library.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -26,13 +31,8 @@ Result Variables
 This module defines the following variables:
 
 ``Iconv_FOUND``
-  Boolean indicating if the iconv support was found.
-
-``Iconv_INCLUDE_DIRS``
-  The include directories containing the iconv headers.
-
-``Iconv_LIBRARIES``
-  The iconv libraries to be linked.
+  Boolean indicating whether the (requested version of) iconv support was
+  found.
 
 ``Iconv_VERSION``
   .. versionadded:: 3.21
@@ -53,17 +53,23 @@ This module defines the following variables:
 
   The minor version of iconv.
 
-``Iconv_IS_BUILT_IN``
-  A boolean variable indicating whether iconv support is stemming from the C
-  standard library or not.  Even if the C library provides ``iconv()``, the
-  presence of an external ``libiconv`` implementation might lead to this being
-  false.
+``Iconv_INCLUDE_DIRS``
+  The include directories containing the iconv headers.
+
+``Iconv_LIBRARIES``
+  The iconv libraries to be linked.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
 
 The following cache variables may also be set:
 
+``Iconv_IS_BUILT_IN``
+  A boolean variable indicating whether iconv support is stemming from the C
+  standard library or not.  Even if the C library provides ``iconv()``, the
+  presence of an external ``libiconv`` implementation might lead to this being
+  false.
+
 ``Iconv_INCLUDE_DIR``
   The directory containing the iconv headers.
 

Modules/FindIntl.cmake

@@ -8,9 +8,15 @@ FindIntl
 .. versionadded:: 3.2
 
 Finds internationalization support that includes message translation functions
-such as ``gettext()``.  These functions originate from the GNU ``libintl``
-library, which is part of the GNU gettext utilities, but may also be provided by
-the standard C library.
+such as ``gettext()``:
+
+.. code-block:: cmake
+
+  find_package(Intl [<version>] [...])
+
+These functions originate from the GNU ``libintl`` library, which is part
+of the GNU gettext utilities, but may also be provided by the standard C
+library.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -28,13 +34,7 @@ Result Variables
 This module defines the following variables:
 
 ``Intl_FOUND``
-  Boolean indicating whether the Intl is found.
-
-``Intl_INCLUDE_DIRS``
-  Include directories containing headers needed to use Intl.
-
-``Intl_LIBRARIES``
-  The libraries needed to link against to use Intl.
+  Boolean indicating whether (the requested version of) Intl is found.
 
 ``Intl_VERSION``
   .. versionadded:: 3.21
@@ -61,23 +61,29 @@ This module defines the following variables:
 
   The patch version of Intl found.
 
+``Intl_INCLUDE_DIRS``
+  Include directories containing headers needed to use Intl.
+
+``Intl_LIBRARIES``
+  The libraries needed to link against to use Intl.
+
 Cache Variables
 ^^^^^^^^^^^^^^^
 
 The following cache variables may also be set:
 
-``Intl_INCLUDE_DIR``
-  The directory containing the ``libintl.h`` header file.
-
-``Intl_LIBRARY``
-  The path to the Intl library (if any).
-
 ``Intl_IS_BUILT_IN``
   .. versionadded:: 3.20
 
   Boolean indicating whether the found Intl functionality is provided by the
   standard C library rather than a separate ``libintl`` library.
 
+``Intl_INCLUDE_DIR``
+  The directory containing the ``libintl.h`` header file.
+
+``Intl_LIBRARY``
+  The path to the Intl library (if any).
+
 .. note::
   On some platforms, such as Linux with GNU libc, the gettext functions are
   present in the C standard library and libintl is not required.  The

Modules/FindJNI.cmake

@@ -5,7 +5,11 @@
 FindJNI
 -------
 
-Finds the Java Native Interface (JNI) include directories and libraries.
+Finds the Java Native Interface (JNI) include directories and libraries:
+
+.. code-block:: cmake
+
+  find_package(JNI [<version>] [COMPONENTS <components>...] [...])
 
 JNI enables Java code running in a Java Virtual Machine (JVM) or Dalvik Virtual
 Machine (DVM) on Android to call and be called by native applications and

Modules/FindJava.cmake

@@ -6,7 +6,11 @@ FindJava
 --------
 
 Finds the Java installation and determines its runtime tools and development
-components.
+components:
+
+.. code-block:: cmake
+
+  find_package(Java [<version>] [COMPONENTS <components>...] [...])
 
 .. versionadded:: 3.10
   Support for Java 9+ version parsing.
@@ -14,7 +18,14 @@ components.
 Components
 ^^^^^^^^^^
 
-This module supports the following components:
+This module supports optional components, which can be specified with the
+:command:`find_package` command:
+
+.. code-block:: cmake
+
+  find_package(Java [COMPONENTS <components>...])
+
+Supported components include:
 
 ``Runtime``
   Finds the Java Runtime Environment used to execute Java byte-compiled
@@ -35,13 +46,7 @@ This module supports the following components:
 
   Finds the signer and verifier tool for Java Archive (JAR) files.
 
-Components can optionally be specified using the standard syntax with:
-
-.. code-block:: cmake
-
-  find_package(Java [COMPONENTS <components>...])
-
-If no ``COMPONENTS`` are specified, the module searches for the ``Runtime``
+If no components are specified, the module searches for the ``Runtime``
 component by default.
 
 Result Variables

Modules/FindKDE3.cmake

@@ -13,9 +13,15 @@ FindKDE3
   `KDE documentation
   <https://develop.kde.org/docs/getting-started/building/cmake-build/>`_.
 
-This module finds KDE 3 include directories, libraries, and KDE-specific
-preprocessor tools.  It provides usage requirements for building KDE 3 software
-and defines several helper commands to simplify working with KDE 3 in CMake.
+Finds KDE 3 include directories, libraries, and KDE-specific preprocessor
+tools:
+
+.. code-block:: cmake
+
+  find_package(KDE3 [...])
+
+This module provides usage requirements for building KDE 3 software and
+defines several helper commands to simplify working with KDE 3 in CMake.
 
 Result Variables
 ^^^^^^^^^^^^^^^^

Modules/FindLATEX.cmake

@@ -5,8 +5,14 @@
 FindLATEX
 ---------
 
-Finds LaTeX compiler and Latex-related software like BibTeX.  LaTeX is a
-typesetting system for the production of technical and scientific documentation.
+Finds LaTeX compiler and Latex-related software like BibTeX:
+
+.. code-block:: cmake
+
+  find_package(LATEX [...])
+
+LaTeX is a typesetting system for the production of technical and scientific
+documentation.
 
 Components
 ^^^^^^^^^^
@@ -40,7 +46,7 @@ Supported components are:
   Finds the MakeIndex compiler.
 
 ``XINDY``
-  Find the xindy compiler.
+  Finds the xindy compiler.
 
 ``DVIPS``
   Finds the DVI-to-PostScript (DVIPS) converter.

Modules/FindLTTngUST.cmake

@@ -17,7 +17,7 @@ user space tracing library (LTTng-UST):
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :ref:`Imported Targets`:
+This module provides the following :ref:`Imported Targets`:
 
 ``LTTng::UST``
   Target providing the LTTng-UST library usage requirements.  This target is
@@ -26,7 +26,7 @@ This module defines the following :ref:`Imported Targets`:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``LTTngUST_FOUND``
   Boolean indicating whether the LTTng-UST library is found.  For backward

Modules/FindLibArchive.cmake

@@ -5,18 +5,24 @@
 FindLibArchive
 --------------
 
-Finds the libarchive library and include directories.  Libarchive is a
-multi-format archive and compression library.
+Finds the libarchive library and include directories:
 
-Import Targets
-^^^^^^^^^^^^^^
+.. code-block:: cmake
 
-This module defines the following :ref:`Imported Targets`:
+  find_package(LibArchive [<version>] [...])
+
+Libarchive is a multi-format archive and compression library.
+
+Imported Targets
+^^^^^^^^^^^^^^^^
+
+This module provides the following :ref:`Imported Targets`:
 
 ``LibArchive::LibArchive``
   .. versionadded:: 3.17
 
-  A target for linking against libarchive.
+  A target encapsulating the libarchive usage requirements, available only
+  if libarchive is found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -24,11 +30,8 @@ Result Variables
 This module defines the following variables:
 
 ``LibArchive_FOUND``
-  Boolean indicating whether libarchive was found.
-``LibArchive_INCLUDE_DIRS``
-  Include search path for using libarchive.
-``LibArchive_LIBRARIES``
-  Libraries to link against libarchive.
+  Boolean indicating whether (the requested version of) libarchive was found.
+
 ``LibArchive_VERSION``
   A 3-component version string (``major.minor.patch``) of libarchive found.
 
@@ -40,10 +43,16 @@ This module defines the following variables:
     only for libarchive versions 3.1 and earlier.  In CMake 3.6 and newer, this
     variable will be set for all libarchive versions.
 
+``LibArchive_INCLUDE_DIRS``
+  Include search path for using libarchive.
+
+``LibArchive_LIBRARIES``
+  Libraries to link against libarchive.
+
 Examples
 ^^^^^^^^
 
-Finding LibArchive and linking it to a project target:
+Finding libarchive and linking it to a project target:
 
 .. code-block:: cmake
 

Modules/FindLibXslt.cmake

@@ -37,7 +37,7 @@ This module provides the following :ref:`Imported Targets`:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``LibXslt_FOUND``
   Boolean indicating whether (the requested version of) libxslt is found.

Modules/FindLibinput.cmake

@@ -8,7 +8,11 @@ FindLibinput
 .. versionadded:: 3.14
 
 Finds the libinput library which handles input devices in Wayland compositors
-and provides a generic X.Org input driver.
+and provides a generic X.Org input driver:
+
+.. code-block:: cmake
+
+  find_package(Libinput [<version>] [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^

Modules/FindMFC.cmake

@@ -6,7 +6,11 @@ FindMFC
 -------
 
 Finds the native Microsoft Foundation Class Library (MFC) for developing MFC
-applications on Windows.
+applications on Windows:
+
+.. code-block:: cmake
+
+  find_package(MFC [...])
 
 .. note::
 

Modules/FindMPEG.cmake

@@ -5,7 +5,11 @@
 FindMPEG
 --------
 
-Finds the native MPEG library (libmpeg2).
+Finds the native MPEG library (libmpeg2):
+
+.. code-block:: cmake
+
+  find_package(MPEG [...])
 
 .. note::
 
@@ -31,7 +35,7 @@ This module defines the following variables:
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-The following cache variables may be also set:
+The following cache variables may also be set:
 
 ``MPEG_INCLUDE_DIR``
   The directory containing the ``mpeg2.h`` and related headers needed to use

Modules/FindMPEG2.cmake

@@ -5,7 +5,11 @@
 FindMPEG2
 ---------
 
-Finds the native MPEG2 library (libmpeg2).
+Finds the native MPEG2 library (libmpeg2):
+
+.. code-block:: cmake
+
+  find_package(MPEG2 [...])
 
 .. note::
 
@@ -26,7 +30,7 @@ This module defines the following variables:
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-The following cache variables may be also set:
+The following cache variables may also be set:
 
 ``MPEG2_INCLUDE_DIR``
   The directory containing the ``mpeg2.h`` and related headers needed to use

Modules/FindMotif.cmake

@@ -5,7 +5,11 @@
 FindMotif
 ---------
 
-Finds Motif (or LessTif) graphical user interface toolkit.
+Finds Motif (or LessTif) graphical user interface toolkit:
+
+.. code-block:: cmake
+
+  find_package(Motif [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -21,19 +25,33 @@ Cache Variables
 
 The following cache variables may also be set:
 
-``MOTIF_LIBRARIES``
-  Libraries needed to link to Motif.
 ``MOTIF_INCLUDE_DIR``
   Include directories needed to use Motif.
 
+``MOTIF_LIBRARIES``
+  Libraries needed to link to Motif.
+
 Examples
 ^^^^^^^^
 
-Finding Motif:
+Finding Motif and creating an imported interface target for linking it to a
+project target:
 
 .. code-block:: cmake
 
   find_package(Motif)
+
+  if(Motif_FOUND AND NOT TARGET Motif::Motif)
+    add_library(Motif::Motif INTERFACE IMPORTED)
+    set_target_properties(
+      Motif::Motif
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${MOTIF_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${MOTIF_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE Motif::Motif)
 #]=======================================================================]
 
 if(UNIX)

Modules/FindMsys.cmake

@@ -8,7 +8,11 @@ FindMsys
 .. versionadded:: 3.21
 
 Finds MSYS, a POSIX-compatible environment that runs natively on Microsoft
-Windows.
+Windows:
+
+.. code-block:: cmake
+
+  find_package(Msys [...])
 
 .. note::
 
@@ -32,7 +36,7 @@ Examples
 Finding the MSYS installation and using its path in a custom find module:
 
 .. code-block:: cmake
-  :caption: FindFoo.cmake
+  :caption: ``FindFoo.cmake``
 
   find_package(Msys)
   find_program(Foo_EXECUTABLE NAMES foo PATHS ${MSYS_INSTALL_PATH}/usr/bin)

Modules/FindODBC.cmake

@@ -7,11 +7,16 @@ FindODBC
 
 .. versionadded:: 3.12
 
-Finds the Open Database Connectivity (ODBC) library, which implements a standard
-API for accessing database systems.  ODBC enables applications to communicate
-with different database management systems (DBMS) using a common set of
-functions.  Communication with a specific database is handled through ODBC
-drivers, which the library loads at runtime.
+Finds the Open Database Connectivity (ODBC) library, which implements a
+standard API for accessing database systems:
+
+.. code-block:: cmake
+
+  find_package(ODBC [...])
+
+ODBC enables applications to communicate with different database management
+systems (DBMS) using a common set of functions.  Communication with a specific
+database is handled through ODBC drivers, which the library loads at runtime.
 
 On Windows, when building with Visual Studio, this module assumes the ODBC
 library is provided by the available Windows SDK.
@@ -76,19 +81,19 @@ Limitations
 Examples
 ^^^^^^^^
 
-Finding and using ODBC
-""""""""""""""""""""""
+Example: Finding and Using ODBC
+"""""""""""""""""""""""""""""""
 
 Finding ODBC and linking it to a project target:
 
 .. code-block:: cmake
-  :caption: CMakeLists.txt
+  :caption: ``CMakeLists.txt``
 
   find_package(ODBC)
   target_link_libraries(project_target PRIVATE ODBC::ODBC)
 
-Finding a custom ODBC installation on Unix-like systems
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Example: Finding a Custom ODBC Installation
+"""""""""""""""""""""""""""""""""""""""""""
 
 The following examples are for Unix-like systems and demonstrate how to set hint
 and cache variables during the CMake configuration phase to help this module

Modules/FindOpenACC.cmake

@@ -7,9 +7,12 @@ FindOpenACC
 
 .. versionadded:: 3.10
 
-Detect OpenACC support by the compiler.
+Finds and detects the OpenACC support in a compiler:
+
+.. code-block:: cmake
+
+  find_package(OpenACC [<version>] [...])
 
-This module can be used to detect OpenACC support in a compiler.
 If the compiler supports OpenACC, the flags required to compile with
 OpenACC support are returned in variables for the different languages.
 Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
@@ -17,28 +20,31 @@ Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-.. versionadded:: 3.16
-
-The module provides :prop_tgt:`IMPORTED` targets:
+This module provides the following :ref:`Imported Targets`:
 
 ``OpenACC::OpenACC_<lang>``
-  Target for using OpenACC from ``<lang>``.
+  .. versionadded:: 3.16
 
-Variables
-^^^^^^^^^
+  Target encapsulating the usage requirements for using OpenACC from
+  ``<lang>``.  This target is available only if OpenACC support is found.
+  ``<lang>`` is one of C, CXX, or Fortran.
 
-The module defines the following variables:
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
 
 ``OpenACC_FOUND``
   .. versionadded:: 3.25
 
-  Variable indicating that OpenACC flags for at least one languages have been found.
+  Boolean variable indicating that OpenACC flags for at least one languages
+  have been found.
 
-This module will set the following variables per language in your
+This module will set the following variables per language in the
 project, where ``<lang>`` is one of C, CXX, or Fortran:
 
 ``OpenACC_<lang>_FOUND``
-  Variable indicating if OpenACC support for ``<lang>`` was detected.
+  Boolean variable indicating if OpenACC support for ``<lang>`` was detected.
 ``OpenACC_<lang>_FLAGS``
   OpenACC compiler flags for ``<lang>``, separated by spaces.
 ``OpenACC_<lang>_OPTIONS``
@@ -65,9 +71,21 @@ the OpenACC specification implemented by the ``<lang>`` compiler.
 Input Variables
 ^^^^^^^^^^^^^^^
 
+This module accepts the following variables:
+
 ``OpenACC_ACCEL_TARGET=<target>``
-If set, will the correct target accelerator flag set to the <target> will
-be returned with OpenACC_<lang>_FLAGS.
+  If set, the correct target accelerator flag set to the ``<target>``
+  will be returned with the ``OpenACC_<lang>_FLAGS`` variable.
+
+Examples
+^^^^^^^^
+
+Finding OpenACC support and linking the imported target to a project target:
+
+.. code-block:: cmake
+
+  find_package(OpenACC)
+  target_link_libraries(example PRIVATE OpenACC::OpenACC_C)
 #]=======================================================================]
 
 cmake_policy(PUSH)

Modules/FindOpenSP.cmake

@@ -7,8 +7,14 @@ FindOpenSP
 
 .. versionadded:: 3.25
 
-Finds the OpenSP library.  OpenSP is an open-source implementation of the SGML
-(Standard Generalized Markup Language) parser.
+Finds the OpenSP library:
+
+.. code-block:: cmake
+
+  find_package(OpenSP [<version>] [...])
+
+OpenSP is an open-source implementation of the SGML (Standard Generalized
+Markup Language) parser.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
@@ -25,7 +31,7 @@ Result Variables
 This module defines the following variables:
 
 ``OpenSP_FOUND``
-  Boolean indicating whether the (requested version of) OpenSP is available.
+  Boolean indicating whether (the requested version of) OpenSP is available.
 
 ``OpenSP_VERSION``
   The version of found OpenSP.

Modules/FindOpenThreads.cmake

@@ -5,7 +5,11 @@
 FindOpenThreads
 ---------------
 
-Finds the OpenThreads C++ based threading library.
+Finds the OpenThreads C++ based threading library:
+
+.. code-block:: cmake
+
+  find_package(OpenThreads [...])
 
 OpenThreads header files are intended to be included as:
 

Modules/FindPHP4.cmake

@@ -5,7 +5,11 @@
 FindPHP4
 --------
 
-Finds PHP version 4, a general-purpose scripting language.
+Finds PHP version 4, a general-purpose scripting language:
+
+.. code-block:: cmake
+
+  find_package(PHP4 [...])
 
 .. note::
 

Modules/FindPNG.cmake

@@ -19,17 +19,18 @@ Finds libpng, the official reference library for the PNG image format:
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :ref:`Imported Targets`:
+This module provides the following :ref:`Imported Targets`:
 
 ``PNG::PNG``
   .. versionadded:: 3.5
 
-  The libpng library, if found.
+  Target encapsulating the libpng library usage requirements, available if
+  libpng is found.
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``PNG_FOUND``
   Boolean indicating whether (the requested version of) PNG library is found.

Modules/FindPhysFS.cmake

@@ -5,7 +5,11 @@
 FindPhysFS
 ----------
 
-Finds the PhysicsFS library (PhysFS) for file I/O abstraction.
+Finds the PhysicsFS library (PhysFS) for file I/O abstraction:
+
+.. code-block:: cmake
+
+  find_package(PhysFS [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -21,11 +25,11 @@ Cache Variables
 
 The following cache variables may also be set:
 
+``PHYSFS_INCLUDE_DIR``
+  Directory containing the ``<physfs.h>`` and related headers needed for using
+  the library.
 ``PHYSFS_LIBRARY``
   Path to the PhysicsFS library needed to link against.
-``PHYSFS_INCLUDE_DIR``
-  Directory containing the ``physfs.h`` and related headers needed for using
-  the library.
 
 Hints
 ^^^^^

Modules/FindProducer.cmake

@@ -15,7 +15,11 @@ FindProducer
   OpenSceneGraph usage, refer to the :module:`FindOpenSceneGraph` module.
 
 This module finds the Producer library, a windowing and event handling library
-designed primarily for real-time graphics applications.
+designed primarily for real-time graphics applications:
+
+.. code-block:: cmake
+
+  find_package(Producer [...])
 
 Producer library headers are intended to be included in C++ project source code
 as:

Modules/FindPython.cmake

@@ -87,7 +87,7 @@ To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :ref:`Imported Targets <Imported Targets>`:
+This module provides the following :ref:`Imported Targets`:
 
 .. versionchanged:: 3.14
   :ref:`Imported Targets <Imported Targets>` are only created when
@@ -138,7 +138,7 @@ This module defines the following :ref:`Imported Targets <Imported Targets>`:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module will set the following variables in your project
+This module defines the following variables
 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
 
 ``Python_FOUND``

Modules/FindPython2.cmake

@@ -81,7 +81,7 @@ for you.
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :ref:`Imported Targets <Imported Targets>`:
+This module provides the following :ref:`Imported Targets`:
 
 .. versionchanged:: 3.14
   :ref:`Imported Targets <Imported Targets>` are only created when
@@ -125,7 +125,7 @@ This module defines the following :ref:`Imported Targets <Imported Targets>`:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module will set the following variables in your project
+This module defines the following variables
 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
 
 ``Python2_FOUND``

Modules/FindPython3.cmake

@@ -89,7 +89,7 @@ for you.
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :ref:`Imported Targets <Imported Targets>`:
+This module provides the following :ref:`Imported Targets`:
 
 .. versionchanged:: 3.14
   :ref:`Imported Targets <Imported Targets>` are only created when
@@ -140,7 +140,7 @@ This module defines the following :ref:`Imported Targets <Imported Targets>`:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module will set the following variables in your project
+This module defines the following variables
 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):
 
 ``Python3_FOUND``

Modules/FindQt.cmake

@@ -31,7 +31,7 @@ Behavior:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``QT4_INSTALLED``
   ``TRUE`` if Qt4 is found.

Modules/FindQt3.cmake

@@ -5,8 +5,12 @@
 FindQt3
 -------
 
-This module finds Qt3, a cross-platform application development framework for
-creating graphical user interfaces and applications.
+Finds Qt3, a cross-platform application development framework for creating
+graphical user interfaces and applications:
+
+.. code-block:: cmake
+
+  find_package(Qt3 [<version>] [...])
 
 .. note::
 
@@ -17,13 +21,13 @@ creating graphical user interfaces and applications.
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``Qt3_FOUND``
-  True if Qt3 has been found.
+  Boolean indicating whether Qt3 has been found.
 ``QT_FOUND``
-  True if Qt3 has been found.  This variable is for compatibility with other Qt
-  find modules.
+  Boolean indicating whether Qt3 has been found.  This variable is for
+  compatibility with other Qt find modules.
 ``QT_VERSION_STRING``
   The version of Qt3 that was found.
 ``QT_LIBRARIES``

Modules/FindQt4.cmake

@@ -5,9 +5,15 @@
 FindQt4
 -------
 
-This module finds Qt4, a cross-platform application development framework for
-creating graphical user interfaces and applications.  It defines a number of
-imported targets, macros, and variables to use Qt4 in the project.
+Finds Qt4, a cross-platform application development framework for creating
+graphical user interfaces and applications:
+
+.. code-block:: cmake
+
+  find_package(Qt4 [<version>] [...])
+
+This module defines a number of imported targets, macros, and variables to
+use Qt4 in the project.
 
 .. note::
 
@@ -39,7 +45,7 @@ Imported Targets
 ^^^^^^^^^^^^^^^^
 
 Qt libraries can be linked using their corresponding
-:ref:`IMPORTED target <Imported Targets>` with the
+:ref:`Imported Target <Imported Targets>` with the
 :command:`target_link_libraries` command:
 
 .. code-block:: cmake
@@ -118,7 +124,7 @@ This module provides the following imported targets, if found:
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module sets the following variables:
+This module defines the following variables:
 
 ``Qt4_FOUND``
   Boolean whether Qt4 has been found.  If false, don't try to use Qt4.

Modules/FindQuickTime.cmake

@@ -6,7 +6,11 @@ FindQuickTime
 -------------
 
 Finds the QuickTime multimedia framework, which provides support for video,
-audio, and interactive media.
+audio, and interactive media:
+
+.. code-block:: cmake
+
+  find_package(QuickTime [...])
 
 .. note::
 
@@ -48,11 +52,24 @@ This module accepts the following variables:
 Examples
 ^^^^^^^^
 
-Finding QuickTime library:
+Finding QuickTime library and creating an imported interface target for
+linking it to a project target:
 
 .. code-block:: cmake
 
   find_package(QuickTime)
+
+  if(QuickTime_FOUND AND NOT TARGET QuickTime::QuickTime)
+    add_library(QuickTime::QuickTime INTERFACE IMPORTED)
+    set_target_properties(
+      QuickTime::QuickTime
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${QUICKTIME_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${QUICKTIME_LIBRARY}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE QuickTime::QuickTime)
 #]=======================================================================]
 
 find_path(QUICKTIME_INCLUDE_DIR QuickTime/QuickTime.h QuickTime.h

Modules/FindRTI.cmake

@@ -5,7 +5,11 @@
 FindRTI
 -------
 
-Finds HLA RTI standard libraries and their include directories.
+Finds HLA RTI standard libraries and their include directories:
+
+.. code-block:: cmake
+
+  find_package(RTI [...])
 
 `RTI <https://en.wikipedia.org/wiki/Run-time_infrastructure_(simulation)>`_
 (Run-Time Infrastructure) is a simulation infrastructure standardized by IEEE
@@ -19,7 +23,7 @@ Result Variables
 This module defines the following variables:
 
 ``RTI_FOUND``
-  Set to FALSE if any HLA RTI was not found.
+  Boolean indicating whether HLA RTI is found.
 ``RTI_LIBRARIES``
   The libraries to link against to use RTI.
 ``RTI_DEFINITIONS``
@@ -37,11 +41,25 @@ The following cache variables may also be set:
 Examples
 ^^^^^^^^
 
-Finding RTI:
+Finding RTI and creating an imported interface target for linking it to a
+project target:
 
 .. code-block:: cmake
 
   find_package(RTI)
+
+  if(RTI_FOUND AND NOT TARGET RTI::RTI)
+    add_library(RTI::RTI INTERFACE IMPORTED)
+    set_target_properties(
+      RTI::RTI
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${RTI_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${RTI_LIBRARIES}"
+        INTERFACE_COMPILE_DEFINITIONS "${RTI_DEFINITIONS}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE RTI::RTI)
 #]=======================================================================]
 
 macro(RTI_MESSAGE_QUIETLY QUIET TYPE MSG)

Modules/FindSelfPackers.cmake

@@ -5,7 +5,11 @@
 FindSelfPackers
 ---------------
 
-Finds `UPX <https://upx.github.io/>`_, the Ultimate Packer for eXecutables.
+Finds `UPX <https://upx.github.io/>`_, the Ultimate Packer for eXecutables:
+
+.. code-block:: cmake
+
+  find_package(SelfPackers [...])
 
 This module searches for executable packers-tools that compress executables or
 shared libraries into on-the-fly, self-extracting versions.  It currently
@@ -14,7 +18,7 @@ supports ``UPX``.
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-The following cache variables may be set:
+The following cache variables may also be set:
 
 ``SELF_PACKER_FOR_EXECUTABLE``
   Path to the executable packer for compressing executables.

Modules/FindTCL.cmake

@@ -5,7 +5,11 @@
 FindTCL
 -------
 
-Finds the Tcl (Tool Command Language), dynamic programming language.
+Finds the Tcl (Tool Command Language), dynamic programming language:
+
+.. code-block:: cmake
+
+  find_package(TCL [...])
 
 This module locates a Tcl installation, including its include directories and
 libraries, and determines the appropriate Tcl library name for linking.  As part
@@ -44,14 +48,12 @@ The following cache variables may also be set:
 ``TK_WISH``
   The path to the ``wish`` windowing shell command-line executable.
 
-
 Other Libraries
 ^^^^^^^^^^^^^^^
 
 The Tcl Stub Library can be found using the separate :module:`FindTclStub`
 module.
 
-
 Examples
 ^^^^^^^^
 

Modules/FindTclStub.cmake

@@ -6,7 +6,11 @@ FindTclStub
 -----------
 
 Finds the Tcl Stub Library, which is used for building version-independent Tcl
-extensions.
+extensions:
+
+.. code-block:: cmake
+
+  find_package(TclStub [...])
 
 Tcl (Tool Command Language) is a dynamic programming language, and the Tcl Stub
 Library provides a mechanism to allow Tcl extensions to be compiled in a way

Modules/FindTclsh.cmake

@@ -6,7 +6,11 @@ FindTclsh
 ---------
 
 Finds the Tcl shell command-line executable (``tclsh``), which includes the Tcl
-(Tool Command Language) interpreter.
+(Tool Command Language) interpreter:
+
+.. code-block:: cmake
+
+  find_package(Tclsh [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^

Modules/FindVulkan.cmake

@@ -8,8 +8,13 @@ FindVulkan
 .. versionadded:: 3.7
 
 Finds Vulkan, a low-overhead, cross-platform 3D graphics and computing API,
-along with related development tools typically provided by the Vulkan SDK.  This
-includes commonly used utilities such as shader compilers and SPIR-V tools
+along with related development tools typically provided by the Vulkan SDK:
+
+.. code-block:: cmake
+
+  find_package(Vulkan [<version>] [COMPONENTS <components>...] [...])
+
+Vulkan includes commonly used utilities such as shader compilers and SPIR-V tools
 (e.g., DXC, ``glslc``, ``glslang``, etc.) that support Vulkan-based development
 workflows.
 

Modules/FindWget.cmake

@@ -6,15 +6,19 @@ FindWget
 --------
 
 This module finds the ``wget`` command-line tool for retrieving content from web
-servers.
+servers:
+
+.. code-block:: cmake
+
+  find_package(Wget [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
 
-This module defines the following local variables:
+This module defines the following variables:
 
 ``Wget_FOUND``
-  True if ``wget`` has been found.
+  Boolean indicating whether ``wget`` has been found.
 
 Cache Variables
 ^^^^^^^^^^^^^^^

Modules/FindWish.cmake

@@ -5,7 +5,11 @@
 FindWish
 --------
 
-Finds ``wish``, a simple windowing shell command-line executable.
+Finds ``wish``, a simple windowing shell command-line executable:
+
+.. code-block:: cmake
+
+  find_package(Wish [...])
 
 This module is commonly used in conjunction with finding a TCL installation (see
 the :module:`FindTCL` module).  It helps determine where the TCL include paths
@@ -17,7 +21,7 @@ for the Cygwin version of ``wish`` executable.
 Cache Variables
 ^^^^^^^^^^^^^^^
 
-The following cache variables may be set:
+The following cache variables may also be set:
 
 ``TK_WISH``
   The path to the ``wish`` executable.

Modules/FindXCTest.cmake

@@ -7,7 +7,11 @@ FindXCTest
 
 .. versionadded:: 3.3
 
-Finds the XCTest framework for writing unit tests in Xcode projects.
+Finds the XCTest framework for writing unit tests in Xcode projects:
+
+.. code-block:: cmake
+
+  find_package(XCTest [...])
 
 .. note::
 

Modules/FindXMLRPC.cmake

@@ -5,9 +5,15 @@
 FindXMLRPC
 ----------
 
-Finds the native XML-RPC library for C and C++.  XML-RPC is a standard network
-protocol that enables remote procedure calls (RPC) between systems.  It encodes
-requests and responses in XML and uses HTTP as the transport mechanism.
+Finds the native XML-RPC library for C and C++:
+
+.. code-block:: cmake
+
+  find_package(XMLRPC [...] [COMPONENTS <components>...] [...])
+
+XML-RPC is a standard network protocol that enables remote procedure calls
+(RPC) between systems.  It encodes requests and responses in XML and uses
+HTTP as the transport mechanism.
 
 Components
 ^^^^^^^^^^
@@ -21,7 +27,7 @@ To list the available features on a system, the ``xmlrpc-c-config`` command-line
 utility can be used.
 
 In CMake, these features can be specified as components with the
-``find_package()`` command:
+:command:`find_package` command:
 
 .. code-block:: cmake
 
@@ -50,29 +56,46 @@ Components may be:
 ``openssl``
   OpenSSL convenience functions.
 
+If no components are specified, this module searches for XML-RPC library and
+its include directories without additional features.
+
 Result Variables
 ^^^^^^^^^^^^^^^^
 
 This module defines the following variables:
 
+``XMLRPC_FOUND``
+  Boolean indicating whether the XML-RPC library and all its requested
+  components are found.
 ``XMLRPC_INCLUDE_DIRS``
   Include directories containing ``xmlrpc.h`` and other headers needed to use
   the XML-RPC library.
 ``XMLRPC_LIBRARIES``
   List of libraries needed for linking to XML-RPC library and its requested
   features.
-``XMLRPC_FOUND``
-  Boolean indicating whether the XML-RPC library and all its requested
-  components are found.
 
 Examples
 ^^^^^^^^
 
-Finding XML-RPC library and its ``client`` feature to use in the project:
+Finding XML-RPC library and its ``client`` feature, and conditionally
+creating an interface :ref:`imported target <Imported Targets>` that
+encapsulates its usage requirements for linking to a project target:
 
 .. code-block:: cmake
 
   find_package(XMLRPC REQUIRED COMPONENTS client)
+
+  if(XMLRPC_FOUND AND NOT TARGET XMLRPC::XMLRPC)
+    add_library(XMLRPC::XMLRPC INTERFACE IMPORTED)
+    set_target_properties(
+      XMLRPC::XMLRPC
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${XMLRPC_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${XMLRPC_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE XMLRPC::XMLRPC)
 #]=======================================================================]
 
 # First find the config script from which to obtain other values.

Modules/FindXalanC.cmake

@@ -7,7 +7,11 @@ FindXalanC
 
 .. versionadded:: 3.5
 
-Finds the Apache Xalan-C++ XSL transform processor headers and libraries.
+Finds the Apache Xalan-C++ XSL transform processor headers and libraries:
+
+.. code-block:: cmake
+
+  find_package(XalaxC [<version>] [...])
 
 .. note::
 
@@ -29,7 +33,7 @@ Result Variables
 This module defines the following variables:
 
 ``XalanC_FOUND``
-  Boolean indicating whether the Xalan-C++ is found.
+  Boolean indicating whether (the requested version of) Xalan-C++ is found.
 ``XalanC_VERSION``
   The version of the found Xalan-C++ library.
 ``XalanC_INCLUDE_DIRS``

Modules/FindXercesC.cmake

@@ -7,12 +7,16 @@ FindXercesC
 
 .. versionadded:: 3.1
 
-Finds the Apache Xerces-C++ validating XML parser headers and libraries.
+Finds the Apache Xerces-C++ validating XML parser headers and libraries:
+
+.. code-block:: cmake
+
+  find_package(XercesC [<version>] [...])
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the following :ref:`Imported Targets`:
+This module provides the following :ref:`Imported Targets`:
 
 ``XercesC::XercesC``
   .. versionadded:: 3.5
@@ -26,7 +30,7 @@ Result Variables
 This module defines the following variables:
 
 ``XercesC_FOUND``
-  Boolean indicating whether the Xerces-C++ is found.
+  Boolean indicating whether (the requested version of) Xerces-C++ is found.
 ``XercesC_VERSION``
   The version of the found Xerces-C++ library.
 ``XercesC_INCLUDE_DIRS``