Help: Fix module documentation markup in cmake-developer.7 manual

Convert the content moved from Modules/readme.txt to valid
reStructuredText markup.  Mainly, convert the lists of variables to
definition lists, wrap long lines in paragraph text, and add literal
block markup and indentation.

Help/manual/cmake-developer.7.rst

@@ -19,60 +19,108 @@ Modules
 
 Note to authors of FindXxx.cmake files
 
-We would like all FindXxx.cmake files to produce consistent variable names.
+We would like all FindXxx.cmake files to produce consistent variable
+names.
 
 Please use the following consistent variable names for general use.
 
-Xxx_INCLUDE_DIRS        The final set of include directories listed in one variable for use by client code.
-                        This should not be a cache entry.
-Xxx_LIBRARIES           The libraries to link against to use Xxx. These should include full paths.
-                        This should not be a cache entry.
-Xxx_DEFINITIONS         Definitions to use when compiling code that uses Xxx. This really shouldn't include options such
-                        as (-DHAS_JPEG)that a client source-code file uses to decide whether to #include <jpeg.h>
-Xxx_EXECUTABLE          Where to find the Xxx tool.
-Xxx_Yyy_EXECUTABLE      Where to find the Yyy tool that comes with Xxx.
-Xxx_LIBRARY_DIRS        Optionally, the final set of library directories listed in one variable for use by client code.
-                        This should not be a cache entry.
-Xxx_ROOT_DIR            Where to find the base directory of Xxx.
-Xxx_VERSION_Yy          Expect Version Yy if true. Make sure at most one of these is ever true.
-Xxx_WRAP_Yy             If False, do not try to use the relevant CMake wrapping command.
-Xxx_Yy_FOUND            If False, optional Yy part of Xxx sytem is not available.
-Xxx_FOUND               Set to false, or undefined, if we haven't found, or don't want to use Xxx.
-Xxx_NOT_FOUND_MESSAGE   Should be set by config-files in the case that it has set Xxx_FOUND to FALSE.
-                        The contained message will be printed by the find_package() command and by
-                        find_package_handle_standard_args() to inform the user about the problem.
-Xxx_RUNTIME_LIBRARY_DIRS Optionally, the runtime library search path for use when running an executable linked to
-                         shared libraries.
-                         The list should be used by user code to create the PATH on windows or LD_LIBRARY_PATH on unix.
-                         This should not be a cache entry.
-Xxx_VERSION_STRING      A human-readable string containing the version of the package found, if any.
-Xxx_VERSION_MAJOR       The major version of the package found, if any.
-Xxx_VERSION_MINOR       The minor version of the package found, if any.
-Xxx_VERSION_PATCH       The patch version of the package found, if any.
-
-You do not have to provide all of the above variables. You should provide Xxx_FOUND under most circumstances.
-If Xxx is a library, then  Xxx_LIBRARIES, should also be defined, and Xxx_INCLUDE_DIRS should usually be
-defined (I guess libm.a might be an exception)
-
-The following names should not usually be used in CMakeLists.txt files, but they may be usefully modified in
-users' CMake Caches to control stuff.
-
-Xxx_LIBRARY             Name of Xxx Library. A User may set this and Xxx_INCLUDE_DIR to ignore to force non-use of Xxx.
-Xxx_Yy_LIBRARY          Name of Yy library that is part of the Xxx system. It may or may not be required to use Xxx.
-Xxx_INCLUDE_DIR         Where to find xxx.h, etc.  (Xxx_INCLUDE_PATH was considered bad because a path includes an
-                        actual filename.)
-Xxx_Yy_INCLUDE_DIR      Where to find xxx_yy.h, etc.
-
-For tidiness's sake, try to keep as many options as possible out of the cache, leaving at least one option which can be
-used to disable use of the module, or locate a not-found library (e.g. Xxx_ROOT_DIR).
-For the same reason, mark most cache options as advanced.
-
-If you need other commands to do special things then it should still begin with Xxx_. This gives a sort of namespace
-effect and keeps things tidy for the user. You should put comments describing all the exported settings, plus
+Xxx_INCLUDE_DIRS
+ The final set of include directories listed in one variable for use by client
+ code.  This should not be a cache entry.
+
+Xxx_LIBRARIES
+ The libraries to link against to use Xxx. These should include full paths.
+ This should not be a cache entry.
+
+Xxx_DEFINITIONS
+ Definitions to use when compiling code that uses Xxx. This really shouldn't
+ include options such as (-DHAS_JPEG)that a client source-code file uses to
+ decide whether to #include <jpeg.h>
+
+Xxx_EXECUTABLE
+ Where to find the Xxx tool.
+
+Xxx_Yyy_EXECUTABLE
+ Where to find the Yyy tool that comes with Xxx.
+
+Xxx_LIBRARY_DIRS
+ Optionally, the final set of library directories listed in one variable for
+ use by client code.  This should not be a cache entry.
+
+Xxx_ROOT_DIR
+ Where to find the base directory of Xxx.
+
+Xxx_VERSION_Yy
+ Expect Version Yy if true. Make sure at most one of these is ever true.
+
+Xxx_WRAP_Yy
+ If False, do not try to use the relevant CMake wrapping command.
+
+Xxx_Yy_FOUND
+ If False, optional Yy part of Xxx sytem is not available.
+
+Xxx_FOUND
+ Set to false, or undefined, if we haven't found, or don't want to use Xxx.
+
+Xxx_NOT_FOUND_MESSAGE
+ Should be set by config-files in the case that it has set Xxx_FOUND to FALSE.
+ The contained message will be printed by the find_package() command and by
+ find_package_handle_standard_args() to inform the user about the problem.
+
+Xxx_RUNTIME_LIBRARY_DIRS
+ Optionally, the runtime library search path for use when running an
+ executable linked to shared libraries.  The list should be used by user code
+ to create the PATH on windows or LD_LIBRARY_PATH on unix.  This should not be
+ a cache entry.
+
+Xxx_VERSION_STRING
+ A human-readable string containing the version of the package found, if any.
+
+Xxx_VERSION_MAJOR
+ The major version of the package found, if any.
+
+Xxx_VERSION_MINOR
+ The minor version of the package found, if any.
+
+Xxx_VERSION_PATCH
+ The patch version of the package found, if any.
+
+You do not have to provide all of the above variables. You should provide
+Xxx_FOUND under most circumstances.  If Xxx is a library, then Xxx_LIBRARIES,
+should also be defined, and Xxx_INCLUDE_DIRS should usually be defined (I
+guess libm.a might be an exception)
+
+The following names should not usually be used in CMakeLists.txt files, but
+they may be usefully modified in users' CMake Caches to control stuff.
+
+Xxx_LIBRARY
+ Name of Xxx Library. A User may set this and Xxx_INCLUDE_DIR to ignore to
+ force non-use of Xxx.
+
+Xxx_Yy_LIBRARY
+ Name of Yy library that is part of the Xxx system. It may or may not be
+ required to use Xxx.
+
+Xxx_INCLUDE_DIR
+ Where to find xxx.h, etc.  (Xxx_INCLUDE_PATH was considered bad because a path
+ includes an actual filename.)
+
+Xxx_Yy_INCLUDE_DIR
+ Where to find xxx_yy.h, etc.
+
+For tidiness's sake, try to keep as many options as possible out of the cache,
+leaving at least one option which can be used to disable use of the module, or
+locate a not-found library (e.g. Xxx_ROOT_DIR).  For the same reason, mark
+most cache options as advanced.
+
+If you need other commands to do special things then it should still begin
+with ``Xxx_``. This gives a sort of namespace effect and keeps things tidy for the
+user. You should put comments describing all the exported settings, plus
 descriptions of any the users can use to control stuff.
 
-You really should also provide backwards compatibility any old settings that were actually in use.
-Make sure you comment them as deprecated, so that no-one starts using them.
+You really should also provide backwards compatibility any old settings that
+were actually in use.  Make sure you comment them as deprecated, so that
+no-one starts using them.
 
 To add a module to the CMake documentation, follow these steps:
 
@@ -100,7 +148,7 @@ To add a module to the CMake documentation, follow these steps:
 
 For example::
 
- #.rst
+ #.rst:
  # FindXxx
  # -------
  #
@@ -114,49 +162,60 @@ For example::
  # * VAR_COOL: this is great isn't it?
  # * VAR_REALLY_COOL: cool right?
 
-Test the documentation formatting by running "cmake --help-module FindXxx",
-and ideally by enabling the SPHINX_HTML and SPHINX_MAN options to build the
-documentation.  Edit the comments until generated documentation looks
-satisfactory.
-
-To have a .cmake file in this directory NOT show up in the modules
-documentation, simply leave out the ``Help/module/<module>.rst`` file and the
-``Help/manual/cmake-modules.7.rst`` toctree entry.
+Test the documentation formatting by running cmake --help-module FindXxx,
+and ideally by enabling the SPHINX_HTML and SPHINX_MAN options to
+build the documentation.  Edit the comments until generated documentation
+looks satisfactory.  To have a .cmake file in this directory NOT show up in
+the modules documentation, simply leave out the ``Help/module/<module>.rst``
+file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
 
 After the documentation, leave a *BLANK* line, and then add a
-copyright and licence notice block like this one:
-
-#=============================================================================
-# Copyright 2009-2011 Your Name
-#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
-# (To distribute this file outside of CMake, substitute the full
-#  License text for the above reference.)
-
-The layout of the notice block is strictly enforced by the ModuleNotices test.
-Only the year range and name may be changed freely.
-
-A FindXxx.cmake module will typically be loaded by the command
-
-  FIND_PACKAGE(Xxx [major[.minor[.patch[.tweak]]]] [EXACT]
-               [QUIET] [[REQUIRED|COMPONENTS] [components...]])
-
-If any version numbers are given to the command it will set the
-following variables before loading the module:
-
-  Xxx_FIND_VERSION       = full requested version string
-  Xxx_FIND_VERSION_MAJOR = major version if requested, else 0
-  Xxx_FIND_VERSION_MINOR = minor version if requested, else 0
-  Xxx_FIND_VERSION_PATCH = patch version if requested, else 0
-  Xxx_FIND_VERSION_TWEAK = tweak version if requested, else 0
-  Xxx_FIND_VERSION_COUNT = number of version components, 0 to 4
-  Xxx_FIND_VERSION_EXACT = true if EXACT option was given
+copyright and licence notice block like this one::
+
+ #=============================================================================
+ # Copyright 2009-2011 Your Name
+ #
+ # Distributed under the OSI-approved BSD License (the "License");
+ # see accompanying file Copyright.txt for details.
+ #
+ # This software is distributed WITHOUT ANY WARRANTY; without even the
+ # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ # See the License for more information.
+ #=============================================================================
+ # (To distribute this file outside of CMake, substitute the full
+ #  License text for the above reference.)
+
+The layout of the notice block is strictly enforced by the ``ModuleNotices``
+test.  Only the year range and name may be changed freely.
+
+A FindXxx.cmake module will typically be loaded by the command::
+
+ FIND_PACKAGE(Xxx [major[.minor[.patch[.tweak]]]] [EXACT]
+              [QUIET] [[REQUIRED|COMPONENTS] [components...]])
+
+If any version numbers are given to the command it will set the following
+variables before loading the module:
+
+Xxx_FIND_VERSION
+ full requested version string
+
+Xxx_FIND_VERSION_MAJOR
+ major version if requested, else 0
+
+Xxx_FIND_VERSION_MINOR
+ minor version if requested, else 0
+
+Xxx_FIND_VERSION_PATCH
+ patch version if requested, else 0
+
+Xxx_FIND_VERSION_TWEAK
+ tweak version if requested, else 0
+
+Xxx_FIND_VERSION_COUNT
+ number of version components, 0 to 4
+
+Xxx_FIND_VERSION_EXACT
+ true if EXACT option was given
 
 If the find module supports versioning it should locate a version of
 the package that is compatible with the version requested.  If a
@@ -180,27 +239,27 @@ FIND_PACKAGE() will set the variable CMAKE_FIND_PACKAGE_NAME to
 contain the actual name of the package.
 
 A package can provide sub-components.
-Those components can be listed after the COMPONENTS (or REQUIRED)
-or OPTIONAL_COMPONENTS keywords.  The set of all listed components will be
+Those components can be listed after the COMPONENTS (or REQUIRED) or
+OPTIONAL_COMPONENTS keywords.  The set of all listed components will be
 specified in a Xxx_FIND_COMPONENTS variable.
 For each package-specific component, say Yyy, a variable Xxx_FIND_REQUIRED_Yyy
 will be set to true if it listed after COMPONENTS and it will be set to false
 if it was listed after OPTIONAL_COMPONENTS.
-Using those variables a FindXxx.cmake module and also a XxxConfig.cmake package
-configuration file can determine whether and which components have been requested,
-and whether they were requested as required or as optional.
+Using those variables a FindXxx.cmake module and also a XxxConfig.cmake
+package configuration file can determine whether and which components have
+been requested, and whether they were requested as required or as optional.
 For each of the requested components a Xxx_Yyy_FOUND variable should be set
 accordingly.
 The per-package Xxx_FOUND variable should be only set to true if all requested
 required components have been found. A missing optional component should not
 keep the Xxx_FOUND variable from being set to true.
-If the package provides Xxx_INCLUDE_DIRS and Xxx_LIBRARIES variables, the include
-dirs and libraries for all components which were requested and which have been
-found should be added to those two variables.
+If the package provides Xxx_INCLUDE_DIRS and Xxx_LIBRARIES variables, the
+include dirs and libraries for all components which were requested and which
+have been found should be added to those two variables.
 
 To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS()
 macro, as an example see FindJPEG.cmake.
 
-For internal implementation, it's a generally accepted convention that variables starting with
-underscore are for temporary use only. (variable starting with an underscore
-are not intended as a reserved prefix).
+For internal implementation, it's a generally accepted convention that
+variables starting with underscore are for temporary use only. (variable
+starting with an underscore are not intended as a reserved prefix).