Help: Improve formatting for FindBoost and FindCUDA

* Split large literal blocks into definitions lists.
* Add section headers.
* Add links to standard commands and variables.
* Use inline literals liberally.
* Enable code highlighting in literal blocks.
* Format command signatures according to modern conventions.

1 files changed, 237 insertions, 139 deletions

diff --git a/Modules/FindBoost.cmake b/Modules/FindBoost.cmake
index 00e4ff1..4683853 100644
--- a/Modules/FindBoost.cmake
+++ b/Modules/FindBoost.cmake
@@ -7,7 +7,9 @@ FindBoost
 
 Find Boost include dirs and libraries
 
-Use this module by invoking find_package with the form::
+Use this module by invoking :command:`find_package` with the form:
+
+.. code-block:: cmake
 
   find_package(Boost
     [version] [EXACT]      # Minimum or EXACT version e.g. 1.67.0
@@ -20,32 +22,61 @@ Use this module by invoking find_package with the form::
 
 This module finds headers and requested component libraries OR a CMake
 package configuration file provided by a "Boost CMake" build.  For the
-latter case skip to the "Boost CMake" section below.  For the former
-case results are reported in variables::
-
-  Boost_FOUND            - True if headers and requested libraries were found
-  Boost_INCLUDE_DIRS     - Boost include directories
-  Boost_LIBRARY_DIRS     - Link directories for Boost libraries
-  Boost_LIBRARIES        - Boost component libraries to be linked
-  Boost_<C>_FOUND        - True if component <C> was found (<C> is upper-case)
-  Boost_<C>_LIBRARY      - Libraries to link for component <C> (may include
-                           target_link_libraries debug/optimized keywords)
-  Boost_VERSION_MACRO    - BOOST_VERSION value from boost/version.hpp
-  Boost_VERSION_STRING   - Boost version number in x.y.z format
-  Boost_VERSION          - if CMP0093 NEW => same as Boost_VERSION_STRING
-                           if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
-  Boost_LIB_VERSION      - Version string appended to library filenames
-  Boost_VERSION_MAJOR    - Boost major version number (X in X.y.z)
-                           alias: Boost_MAJOR_VERSION
-  Boost_VERSION_MINOR    - Boost minor version number (Y in x.Y.z)
-                           alias: Boost_MINOR_VERSION
-  Boost_VERSION_PATCH    - Boost subminor version number (Z in x.y.Z)
-                           alias: Boost_SUBMINOR_VERSION
-  Boost_VERSION_COUNT    - Amount of version components (3)
-  Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
-                         - Pass to add_definitions() to have diagnostic
-                           information about Boost's automatic linking
-                           displayed during compilation
+latter case skip to the :ref:`Boost CMake` section below.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``Boost_FOUND``
+  True if headers and requested libraries were found.
+
+``Boost_INCLUDE_DIRS``
+  Boost include directories.
+
+``Boost_LIBRARY_DIRS``
+  Link directories for Boost libraries.
+
+``Boost_LIBRARIES``
+  Boost component libraries to be linked.
+
+``Boost_<COMPONENT>_FOUND``
+  True if component ``<COMPONENT>`` was found (``<COMPONENT>`` name is upper-case).
+
+``Boost_<COMPONENT>_LIBRARY``
+  Libraries to link for component ``<COMPONENT>`` (may include
+  :command:`target_link_libraries` debug/optimized keywords).
+
+``Boost_VERSION_MACRO``
+  ``BOOST_VERSION`` value from ``boost/version.hpp``.
+
+``Boost_VERSION_STRING``
+  Boost version number in ``X.Y.Z`` format.
+
+``Boost_VERSION``
+  If :policy:`CMP0093` policy is set to ``NEW``, same as ``Boost_VERSION_STRING``.
+  If :policy:`CMP0093` policy is set to ``OLD`` or unset, same as ``Boost_VERSION_MACRO``.
+
+``Boost_LIB_VERSION``
+  Version string appended to library filenames.
+
+``Boost_VERSION_MAJOR``, ``Boost_MAJOR_VERSION``
+  Boost major version number (``X`` in ``X.Y.Z``).
+
+``Boost_VERSION_MINOR``, ``Boost_MINOR_VERSION``
+  Boost minor version number (``Y`` in ``X.Y.Z``).
+
+``Boost_VERSION_PATCH``, ``Boost_SUBMINOR_VERSION``
+  Boost subminor version number (``Z`` in ``X.Y.Z``).
+
+``Boost_VERSION_COUNT``
+  Amount of version components (3).
+
+``Boost_LIB_DIAGNOSTIC_DEFINITIONS`` (Windows-specific)
+  Pass to :command:`add_definitions` to have diagnostic
+  information about Boost's automatic linking
+  displayed during compilation
 
 Note that Boost Python components require a Python version suffix
 (Boost 1.67 and later), e.g. ``python36`` or ``python27`` for the
@@ -56,61 +87,55 @@ distribution-specific suffixes such as ``2``, ``3`` or ``2.7``.
 These may also be used as suffixes, but note that they are not
 portable.
 
-This module reads hints about search locations from variables::
-
-  BOOST_ROOT             - Preferred installation prefix
-   (or BOOSTROOT)
-  BOOST_INCLUDEDIR       - Preferred include directory e.g. <prefix>/include
-  BOOST_LIBRARYDIR       - Preferred library directory e.g. <prefix>/lib
-  Boost_NO_SYSTEM_PATHS  - Set to ON to disable searching in locations not
-                           specified by these hint variables. Default is OFF.
-  Boost_ADDITIONAL_VERSIONS
-                         - List of Boost versions not known to this module
-                           (Boost install locations may contain the version)
-
-and saves search results persistently in CMake cache entries::
-
-  Boost_INCLUDE_DIR         - Directory containing Boost headers
-  Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
-  Boost_LIBRARY_DIR_DEBUG   - Directory containing debug Boost libraries
-  Boost_<C>_LIBRARY_DEBUG   - Component <C> library debug variant
-  Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
-
-The following :prop_tgt:`IMPORTED` targets are also defined::
-
-  Boost::headers                - Target for header-only dependencies
-                                  (Boost include directory)
-                                  alias: Boost::boost
-  Boost::<C>                    - Target for specific component dependency
-                                  (shared or static library); <C> is lower-
-                                  case
-  Boost::diagnostic_definitions - interface target to enable diagnostic
-                                  information about Boost's automatic linking
-                                  during compilation (adds BOOST_LIB_DIAGNOSTIC)
-  Boost::disable_autolinking    - interface target to disable automatic
-                                  linking with MSVC (adds BOOST_ALL_NO_LIB)
-  Boost::dynamic_linking        - interface target to enable dynamic linking
-                                  linking with MSVC (adds BOOST_ALL_DYN_LINK)
+Cache variables
+^^^^^^^^^^^^^^^
 
-Implicit dependencies such as ``Boost::filesystem`` requiring
-``Boost::system`` will be automatically detected and satisfied, even
-if system is not specified when using :command:`find_package` and if
-``Boost::system`` is not added to :command:`target_link_libraries`.  If using
-``Boost::thread``, then ``Threads::Threads`` will also be added automatically.
+Search results are saved persistently in CMake cache entries:
 
-It is important to note that the imported targets behave differently
-than variables created by this module: multiple calls to
-:command:`find_package(Boost)` in the same directory or sub-directories with
-different options (e.g. static or shared) will not override the
-values of the targets created by the first call.
+``Boost_INCLUDE_DIR``
+  Directory containing Boost headers.
+
+``Boost_LIBRARY_DIR_RELEASE``
+  Directory containing release Boost libraries.
+
+``Boost_LIBRARY_DIR_DEBUG``
+  Directory containing debug Boost libraries.
+
+``Boost_<COMPONENT>_LIBRARY_DEBUG``
+  Component ``<COMPONENT>`` library debug variant.
+
+``Boost_<COMPONENT>_LIBRARY_RELEASE``
+  Component ``<COMPONENT>`` library release variant.
+
+Hints
+^^^^^
+
+This module reads hints about search locations from variables:
+
+``BOOST_ROOT``, ``BOOSTROOT``
+  Preferred installation prefix.
+
+``BOOST_INCLUDEDIR``
+  Preferred include directory e.g. ``<prefix>/include``.
+
+``BOOST_LIBRARYDIR``
+  Preferred library directory e.g. ``<prefix>/lib``.
+
+``Boost_NO_SYSTEM_PATHS``
+  Set to ``ON`` to disable searching in locations not
+  specified by these hint variables. Default is ``OFF``.
+
+``Boost_ADDITIONAL_VERSIONS``
+  List of Boost versions not known to this module.
+  (Boost install locations may contain the version).
 
 Users may set these hints or results as ``CACHE`` entries.  Projects
 should not read these entries directly but instead use the above
 result variables.  Note that some hint names start in upper-case
-"BOOST".  One may specify these as environment variables if they are
+``BOOST``.  One may specify these as environment variables if they are
 not specified as CMake variables or cache entries.
 
-This module first searches for the ``Boost`` header files using the above
+This module first searches for the Boost header files using the above
 hint variables (excluding ``BOOST_LIBRARYDIR``) and saves the result in
 ``Boost_INCLUDE_DIR``.  Then it searches for requested component libraries
 using the above hints (excluding ``BOOST_INCLUDEDIR`` and
@@ -118,83 +143,148 @@ using the above hints (excluding ``BOOST_INCLUDEDIR`` and
 and the library name configuration settings below.  It saves the
 library directories in ``Boost_LIBRARY_DIR_DEBUG`` and
 ``Boost_LIBRARY_DIR_RELEASE`` and individual library
-locations in ``Boost_<C>_LIBRARY_DEBUG`` and ``Boost_<C>_LIBRARY_RELEASE``.
+locations in ``Boost_<COMPONENT>_LIBRARY_DEBUG`` and ``Boost_<COMPONENT>_LIBRARY_RELEASE``.
 When one changes settings used by previous searches in the same build
 tree (excluding environment variables) this module discards previous
 search results affected by the changes and searches again.
 
+Imported Targets
+^^^^^^^^^^^^^^^^
+
+This module defines the following :prop_tgt:`IMPORTED` targets:
+
+``Boost::headers``
+  Target for header-only dependencies. (Boost include directory).
+  ``Boost::boost`` is an alias.
+
+``Boost::<component>``
+  Target for specific component dependency (shared or static library);
+  ``<component>`` name is lower-case.
+
+``Boost::diagnostic_definitions``
+  Interface target to enable diagnostic information about Boost's automatic
+  linking during compilation (adds ``-DBOOST_LIB_DIAGNOSTIC``).
+
+``Boost::disable_autolinking``
+  Interface target to disable automatic linking with MSVC
+  (adds ``-DBOOST_ALL_NO_LIB``).
+
+``Boost::dynamic_linking``
+  Interface target to enable dynamic linking linking with MSVC
+  (adds ``-DBOOST_ALL_DYN_LINK``).
+
+Implicit dependencies such as ``Boost::filesystem`` requiring
+``Boost::system`` will be automatically detected and satisfied, even
+if system is not specified when using :command:`find_package` and if
+``Boost::system`` is not added to :command:`target_link_libraries`.  If using
+``Boost::thread``, then ``Threads::Threads`` will also be added automatically.
+
+It is important to note that the imported targets behave differently
+than variables created by this module: multiple calls to
+:command:`find_package(Boost)` in the same directory or sub-directories with
+different options (e.g. static or shared) will not override the
+values of the targets created by the first call.
+
+Other Variables
+^^^^^^^^^^^^^^^
+
 Boost libraries come in many variants encoded in their file name.
 Users or projects may tell this module which variant to find by
-setting variables::
-
-  Boost_USE_DEBUG_LIBS     - Set to ON or OFF to specify whether to search
-                             and use the debug libraries.  Default is ON.
-  Boost_USE_RELEASE_LIBS   - Set to ON or OFF to specify whether to search
-                             and use the release libraries.  Default is ON.
-  Boost_USE_MULTITHREADED  - Set to OFF to use the non-multithreaded
-                             libraries ('mt' tag).  Default is ON.
-  Boost_USE_STATIC_LIBS    - Set to ON to force the use of the static
-                             libraries.  Default is OFF.
-  Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
-                             libraries linked statically to the C++ runtime
-                             ('s' tag).  Default is platform dependent.
-  Boost_USE_DEBUG_RUNTIME  - Set to ON or OFF to specify whether to use
-                             libraries linked to the MS debug C++ runtime
-                             ('g' tag).  Default is ON.
-  Boost_USE_DEBUG_PYTHON   - Set to ON to use libraries compiled with a
-                             debug Python build ('y' tag). Default is OFF.
-  Boost_USE_STLPORT        - Set to ON to use libraries compiled with
-                             STLPort ('p' tag).  Default is OFF.
-  Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
-                           - Set to ON to use libraries compiled with
-                             STLPort deprecated "native iostreams"
-                             ('n' tag).  Default is OFF.
-  Boost_COMPILER           - Set to the compiler-specific library suffix
-                             (e.g. "-gcc43").  Default is auto-computed
-                             for the C++ compiler in use.  A list may be
-                             used if multiple compatible suffixes should
-                             be tested for, in decreasing order of
-                             preference.
-  Boost_LIB_PREFIX         - Set to the platform-specific library name
-                             prefix (e.g. "lib") used by Boost static libs.
-                             This is needed only on platforms where CMake
-                             does not know the prefix by default.
-  Boost_ARCHITECTURE       - Set to the architecture-specific library suffix
-                             (e.g. "-x64").  Default is auto-computed for the
-                             C++ compiler in use.
-  Boost_THREADAPI          - Suffix for "thread" component library name,
-                             such as "pthread" or "win32".  Names with
-                             and without this suffix will both be tried.
-  Boost_NAMESPACE          - Alternate namespace used to build boost with
-                             e.g. if set to "myboost", will search for
-                             myboost_thread instead of boost_thread.
-
-Other variables one may set to control this module are::
-
-  Boost_DEBUG              - Set to ON to enable debug output from FindBoost.
-                             Please enable this before filing any bug report.
-  Boost_REALPATH           - Set to ON to resolve symlinks for discovered
-                             libraries to assist with packaging.  For example,
-                             the "system" component library may be resolved to
-                             "/usr/lib/libboost_system.so.1.67.0" instead of
-                             "/usr/lib/libboost_system.so".  This does not
-                             affect linking and should not be enabled unless
-                             the user needs this information.
-  Boost_LIBRARY_DIR        - Default value for Boost_LIBRARY_DIR_RELEASE and
-                             Boost_LIBRARY_DIR_DEBUG.
+setting variables:
+
+``Boost_USE_DEBUG_LIBS``
+  Set to ``ON`` or ``OFF`` to specify whether to search and use the debug
+  libraries.  Default is ``ON``.
+
+``Boost_USE_RELEASE_LIBS``
+  Set to ``ON`` or ``OFF`` to specify whether to search and use the release
+  libraries.  Default is ``ON``.
+
+``Boost_USE_MULTITHREADED``
+  Set to OFF to use the non-multithreaded libraries ("mt" tag). Default is
+  ``ON``.
+
+``Boost_USE_STATIC_LIBS``
+  Set to ON to force the use of the static libraries.  Default is ``OFF``.
+
+``Boost_USE_STATIC_RUNTIME``
+  Set to ``ON`` or ``OFF`` to specify whether to use libraries linked
+  statically to the C++ runtime ("s" tag).  Default is platform dependent.
+
+``Boost_USE_DEBUG_RUNTIME``
+  Set to ``ON`` or ``OFF`` to specify whether to use libraries linked to the
+  MS debug C++ runtime ("g" tag).  Default is ``ON``.
+
+``Boost_USE_DEBUG_PYTHON``
+  Set to ``ON`` to use libraries compiled with a debug Python build ("y"
+  tag).  Default is ``OFF``.
+
+``Boost_USE_STLPORT``
+  Set to ``ON`` to use libraries compiled with STLPort ("p" tag). Default is
+  ``OFF``.
+
+``Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS``
+  Set to ON to use libraries compiled with STLPort deprecated "native
+  iostreams" ("n" tag).  Default is ``OFF``.
+
+``Boost_COMPILER``
+  Set to the compiler-specific library suffix (e.g. ``-gcc43``).  Default is
+  auto-computed for the C++ compiler in use.  A list may be used if multiple
+  compatible suffixes should be tested for, in decreasing order of preference.
+
+``Boost_LIB_PREFIX``
+  Set to the platform-specific library name prefix (e.g. ``lib``) used by
+  Boost static libs.  This is needed only on platforms where CMake does not
+  know the prefix by default.
+
+``Boost_ARCHITECTURE``
+  Set to the architecture-specific library suffix (e.g. ``-x64``).
+  Default is auto-computed for the C++ compiler in use.
+
+``Boost_THREADAPI``
+  Suffix for ``thread`` component library name, such as ``pthread`` or
+  ``win32``.  Names with and without this suffix will both be tried.
+
+``Boost_NAMESPACE``
+  Alternate namespace used to build boost with e.g. if set to ``myboost``,
+  will search for ``myboost_thread`` instead of ``boost_thread``.
+
+Other variables one may set to control this module are:
+
+``Boost_DEBUG``
+  Set to ``ON`` to enable debug output from ``FindBoost``.
+  Please enable this before filing any bug report.
+
+``Boost_REALPATH``
+  Set to ``ON`` to resolve symlinks for discovered libraries to assist with
+  packaging.  For example, the "system" component library may be resolved to
+  ``/usr/lib/libboost_system.so.1.67.0`` instead of
+  ``/usr/lib/libboost_system.so``.  This does not affect linking and should
+  not be enabled unless the user needs this information.
+
+``Boost_LIBRARY_DIR``
+  Default value for ``Boost_LIBRARY_DIR_RELEASE`` and
+  ``Boost_LIBRARY_DIR_DEBUG``.
 
 On Visual Studio and Borland compilers Boost headers request automatic
 linking to corresponding libraries.  This requires matching libraries
 to be linked explicitly or available in the link library search path.
 In this case setting ``Boost_USE_STATIC_LIBS`` to ``OFF`` may not achieve
 dynamic linking.  Boost automatic linking typically requests static
-libraries with a few exceptions (such as ``Boost.Python``).  Use::
+libraries with a few exceptions (such as ``Boost.Python``).  Use:
+
+.. code-block:: cmake
 
   add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
 
 to ask Boost to report information about automatic linking requests.
 
-Example to find Boost headers only::
+Examples
+^^^^^^^^
+
+Find Boost headers only:
+
+.. code-block:: cmake
 
   find_package(Boost 1.36.0)
   if(Boost_FOUND)
@@ -202,7 +292,9 @@ Example to find Boost headers only::
     add_executable(foo foo.cc)
   endif()
 
-Example to find Boost libraries and use imported targets::
+Find Boost libraries and use imported targets:
+
+.. code-block:: cmake
 
   find_package(Boost 1.56 REQUIRED COMPONENTS
                date_time filesystem iostreams)
@@ -210,17 +302,21 @@ Example to find Boost libraries and use imported targets::
   target_link_libraries(foo Boost::date_time Boost::filesystem
                             Boost::iostreams)
 
-Example to find Boost Python 3.6 libraries and use imported targets::
+Find Boost Python 3.6 libraries and use imported targets:
+
+.. code-block:: cmake
 
   find_package(Boost 1.67 REQUIRED COMPONENTS
                python36 numpy36)
   add_executable(foo foo.cc)
   target_link_libraries(foo Boost::python36 Boost::numpy36)
 
-Example to find Boost headers and some *static* (release only) libraries::
+Find Boost headers and some *static* (release only) libraries:
+
+.. code-block:: cmake
 
   set(Boost_USE_STATIC_LIBS        ON)  # only find static libs
-  set(Boost_USE_DEBUG_LIBS         OFF) # ignore debug libs and
+  set(Boost_USE_DEBUG_LIBS        OFF)  # ignore debug libs and
   set(Boost_USE_RELEASE_LIBS       ON)  # only find release libs
   set(Boost_USE_MULTITHREADED      ON)
   set(Boost_USE_STATIC_RUNTIME    OFF)
@@ -231,6 +327,8 @@ Example to find Boost headers and some *static* (release only) libraries::
     target_link_libraries(foo ${Boost_LIBRARIES})
   endif()
 
+.. _`Boost CMake`:
+
 Boost CMake
 ^^^^^^^^^^^
 
@@ -238,7 +336,7 @@ If Boost was built using the boost-cmake project or from Boost 1.70.0 on
 it provides a package configuration file for use with find_package's config mode.
 This module looks for the package configuration file called
 ``BoostConfig.cmake`` or ``boost-config.cmake`` and stores the result in
-``CACHE`` entry "Boost_DIR".  If found, the package configuration file is loaded
+``CACHE`` entry ``Boost_DIR``.  If found, the package configuration file is loaded
 and this module returns with no further action.  See documentation of
 the Boost CMake package configuration for details on what it provides.