Modules: Format documentation to avoid over-long preformatted lines

Convert several preformatted code block literals that enumerate lists of
options or variables to use reST definition lists instead.  Manually
wrap other long lines in code blocks.

17 files changed, 279 insertions, 202 deletions

diff --git a/Modules/CMakeExpandImportedTargets.cmake b/Modules/CMakeExpandImportedTargets.cmake
index b6ab7efb57..8ac3364650 100644
--- a/Modules/CMakeExpandImportedTargets.cmake
+++ b/Modules/CMakeExpandImportedTargets.cmake
@@ -20,8 +20,9 @@
 #
 # ::
 #
-#     cmake_expand_imported_targets(expandedLibs LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
-#                                                CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
+#     cmake_expand_imported_targets(expandedLibs
+#       LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
+#       CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
 
 
 #=============================================================================
diff --git a/Modules/CMakeFindPackageMode.cmake b/Modules/CMakeFindPackageMode.cmake
index 9f97ee5728..fc3058d5a6 100644
--- a/Modules/CMakeFindPackageMode.cmake
+++ b/Modules/CMakeFindPackageMode.cmake
@@ -7,15 +7,24 @@
 # This file is executed by cmake when invoked with --find-package.  It
 # expects that the following variables are set using -D:
 #
-# ::
-#
-#    NAME = name of the package
-#    COMPILER_ID = the CMake compiler ID for which the result is, i.e. GNU/Intel/Clang/MSVC, etc.
-#    LANGUAGE = language for which the result will be used, i.e. C/CXX/Fortan/ASM
-#    MODE = EXIST : only check for existence of the given package
-#           COMPILE : print the flags needed for compiling an object file which uses the given package
-#           LINK : print the flags needed for linking when using the given package
-#    QUIET = if TRUE, don't print anything
+# ``NAME``
+#   name of the package
+# ``COMPILER_ID``
+#   the CMake compiler ID for which the result is,
+#   i.e. GNU/Intel/Clang/MSVC, etc.
+# ``LANGUAGE``
+#   language for which the result will be used,
+#   i.e. C/CXX/Fortan/ASM
+# ``MODE``
+#   ``EXIST``
+#     only check for existence of the given package
+#   ``COMPILE``
+#     print the flags needed for compiling an object file which uses
+#     the given package
+#   ``LINK``
+#     print the flags needed for linking when using the given package
+# ``QUIET``
+#   if TRUE, don't print anything
 
 #=============================================================================
 # Copyright 2006-2011 Alexander Neundorf, <neundorf@kde.org>
diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake
index c6dc14199e..206ea7a48c 100644
--- a/Modules/CMakePackageConfigHelpers.cmake
+++ b/Modules/CMakePackageConfigHelpers.cmake
@@ -15,12 +15,13 @@
 #
 #  Create a config file for a project::
 #
-#     configure_package_config_file(<input> <output> INSTALL_DESTINATION <path>
-#                                                    [PATH_VARS <var1> <var2> ... <varN>]
-#                                                    [NO_SET_AND_CHECK_MACRO]
-#                                                    [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
-#                                                    [INSTALL_PREFIX <path>])
-#
+#    configure_package_config_file(<input> <output>
+#      INSTALL_DESTINATION <path>
+#      [PATH_VARS <var1> <var2> ... <varN>]
+#      [NO_SET_AND_CHECK_MACRO]
+#      [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
+#      [INSTALL_PREFIX <path>]
+#      )
 #
 # ``configure_package_config_file()`` should be used instead of the plain
 # :command:`configure_file()` command when creating the ``<Name>Config.cmake``
@@ -51,13 +52,13 @@
 # Using ``configure_package_config_file`` helps.  If used correctly, it makes
 # the resulting ``FooConfig.cmake`` file relocatable.  Usage:
 #
-#    1. write a ``FooConfig.cmake.in`` file as you are used to
-#    2. insert a line containing only the string ``@PACKAGE_INIT@``
-#    3. instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
-#       ``set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")`` (this must be after the
-#       ``@PACKAGE_INIT@`` line)
-#    4. instead of using the normal :command:`configure_file()`, use
-#       ``configure_package_config_file()``
+# 1. write a ``FooConfig.cmake.in`` file as you are used to
+# 2. insert a line containing only the string ``@PACKAGE_INIT@``
+# 3. instead of ``set(FOO_DIR "@SOME_INSTALL_DIR@")``, use
+#    ``set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")`` (this must be after the
+#    ``@PACKAGE_INIT@`` line)
+# 4. instead of using the normal :command:`configure_file()`, use
+#    ``configure_package_config_file()``
 #
 #
 #
@@ -116,9 +117,9 @@
 #
 #  Create a version file for a project::
 #
-#     write_basic_package_version_file(<filename>
-#                                      [VERSION <major.minor.patch>]
-#                                      COMPATIBILITY <AnyNewerVersion|SameMajorVersion|ExactVersion> )
+#    write_basic_package_version_file(<filename>
+#      [VERSION <major.minor.patch>]
+#      COMPATIBILITY <AnyNewerVersion|SameMajorVersion|ExactVersion> )
 #
 #
 # Writes a file for use as ``<package>ConfigVersion.cmake`` file to
@@ -172,13 +173,16 @@
 #    set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
 #    ...
 #    include(CMakePackageConfigHelpers)
-#    configure_package_config_file(FooConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
-#                                  INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
-#                                  PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
-#    write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
-#                                     VERSION 1.2.3
-#                                     COMPATIBILITY SameMajorVersion )
-#    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
+#    configure_package_config_file(FooConfig.cmake.in
+#      ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
+#      INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
+#      PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
+#    write_basic_package_version_file(
+#      ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
+#      VERSION 1.2.3
+#      COMPATIBILITY SameMajorVersion )
+#    install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
+#                  ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
 #            DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
 #
 # ``FooConfig.cmake.in``:
diff --git a/Modules/CMakeParseArguments.cmake b/Modules/CMakeParseArguments.cmake
index 4248176ad6..8553f38f5f 100644
--- a/Modules/CMakeParseArguments.cmake
+++ b/Modules/CMakeParseArguments.cmake
@@ -45,7 +45,8 @@
 #      set(options OPTIONAL FAST)
 #      set(oneValueArgs DESTINATION RENAME)
 #      set(multiValueArgs TARGETS CONFIGURATIONS)
-#      cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
+#      cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
+#                            "${multiValueArgs}" ${ARGN} )
 #      ...
 #
 #
diff --git a/Modules/CMakePrintHelpers.cmake b/Modules/CMakePrintHelpers.cmake
index ad3b0d585b..474fa41b96 100644
--- a/Modules/CMakePrintHelpers.cmake
+++ b/Modules/CMakePrintHelpers.cmake
@@ -15,11 +15,10 @@
 #
 # This macro prints the values of the properties of the given targets,
 # source files, directories, tests or cache entries.  Exactly one of the
-# scope keywords must be used.  Example:
+# scope keywords must be used.  Example::
 #
-# ::
-#
-#    cmake_print_properties(TARGETS foo bar PROPERTIES LOCATION INTERFACE_INCLUDE_DIRS)
+#    cmake_print_properties(TARGETS foo bar PROPERTIES
+#                           LOCATION INTERFACE_INCLUDE_DIRS)
 #
 # This will print the LOCATION and INTERFACE_INCLUDE_DIRS properties for
 # both targets foo and bar.
@@ -29,17 +28,13 @@
 # CMAKE_PRINT_VARIABLES(var1 var2 ..  varN)
 #
 # This macro will print the name of each variable followed by its value.
-# Example:
-#
-# ::
-#
-#    cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION THIS_ONE_DOES_NOT_EXIST)
+# Example::
 #
-# Gives:
+#   cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
 #
-# ::
+# Gives::
 #
-#    -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; THIS_ONE_DOES_NOT_EXIST=""
+#   -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
 
 #=============================================================================
 # Copyright 2013 Alexander Neundorf, <neundorf@kde.org>
diff --git a/Modules/DeployQt4.cmake b/Modules/DeployQt4.cmake
index 9b31567c90..b1a2370b47 100644
--- a/Modules/DeployQt4.cmake
+++ b/Modules/DeployQt4.cmake
@@ -37,7 +37,8 @@
 #
 # ::
 #
-#   FIXUP_QT4_EXECUTABLE(<executable> [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
+#   FIXUP_QT4_EXECUTABLE(<executable>
+#     [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
 #
 # Copies Qt plugins, writes a Qt configuration file (if needed) and
 # fixes up a Qt4 executable using BundleUtilities so it is standalone
@@ -63,7 +64,8 @@
 #
 # ::
 #
-#   INSTALL_QT4_PLUGIN_PATH(plugin executable copy installed_plugin_path_var <plugins_dir> <component> <configurations>)
+#   INSTALL_QT4_PLUGIN_PATH(plugin executable copy installed_plugin_path_var
+#                           <plugins_dir> <component> <configurations>)
 #
 # Install (or copy) a resolved <plugin> to the default plugins directory
 # (or <plugins_dir>) relative to <executable> and store the result in
@@ -77,7 +79,8 @@
 #
 # ::
 #
-#   INSTALL_QT4_PLUGIN(plugin executable copy installed_plugin_path_var <plugins_dir> <component>)
+#   INSTALL_QT4_PLUGIN(plugin executable copy installed_plugin_path_var
+#                      <plugins_dir> <component>)
 #
 # Install (or copy) an unresolved <plugin> to the default plugins
 # directory (or <plugins_dir>) relative to <executable> and store the
@@ -86,7 +89,8 @@
 #
 # ::
 #
-#   INSTALL_QT4_EXECUTABLE(<executable> [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
+#   INSTALL_QT4_EXECUTABLE(<executable>
+#     [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
 #
 # Installs Qt plugins, writes a Qt configuration file (if needed) and
 # fixes up a Qt4 executable using BundleUtilities so it is standalone
diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake
index 12ea384773..37bc6b5230 100644
--- a/Modules/FeatureSummary.cmake
+++ b/Modules/FeatureSummary.cmake
@@ -55,21 +55,32 @@
 # The WHAT option is the only mandatory option.  Here you specify what
 # information will be printed:
 #
-# ::
-#
-#     ALL: print everything
-#     ENABLED_FEATURES: the list of all features which are enabled
-#     DISABLED_FEATURES: the list of all features which are disabled
-#     PACKAGES_FOUND: the list of all packages which have been found
-#     PACKAGES_NOT_FOUND: the list of all packages which have not been found
-#     OPTIONAL_PACKAGES_FOUND: only those packages which have been found which have the type OPTIONAL
-#     OPTIONAL_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type OPTIONAL
-#     RECOMMENDED_PACKAGES_FOUND: only those packages which have been found which have the type RECOMMENDED
-#     RECOMMENDED_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type RECOMMENDED
-#     REQUIRED_PACKAGES_FOUND: only those packages which have been found which have the type REQUIRED
-#     REQUIRED_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type REQUIRED
-#     RUNTIME_PACKAGES_FOUND: only those packages which have been found which have the type RUNTIME
-#     RUNTIME_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type RUNTIME
+# ``ALL``
+#  print everything
+# ``ENABLED_FEATURES``
+#  the list of all features which are enabled
+# ``DISABLED_FEATURES``
+#  the list of all features which are disabled
+# ``PACKAGES_FOUND``
+#  the list of all packages which have been found
+# ``PACKAGES_NOT_FOUND``
+#  the list of all packages which have not been found
+# ``OPTIONAL_PACKAGES_FOUND``
+#  only those packages which have been found which have the type OPTIONAL
+# ``OPTIONAL_PACKAGES_NOT_FOUND``
+#  only those packages which have not been found which have the type OPTIONAL
+# ``RECOMMENDED_PACKAGES_FOUND``
+#  only those packages which have been found which have the type RECOMMENDED
+# ``RECOMMENDED_PACKAGES_NOT_FOUND``
+#  only those packages which have not been found which have the type RECOMMENDED
+# ``REQUIRED_PACKAGES_FOUND``
+#  only those packages which have been found which have the type REQUIRED
+# ``REQUIRED_PACKAGES_NOT_FOUND``
+#  only those packages which have not been found which have the type REQUIRED
+# ``RUNTIME_PACKAGES_FOUND``
+#  only those packages which have been found which have the type RUNTIME
+# ``RUNTIME_PACKAGES_NOT_FOUND``
+#  only those packages which have not been found which have the type RUNTIME
 #
 # With the exception of the ``ALL`` value, these values can be combined
 # in order to customize the output. For example:
@@ -118,10 +129,11 @@
 #
 # ::
 #
-#     SET_PACKAGE_PROPERTIES(<name> PROPERTIES [ URL <url> ]
-#                                              [ DESCRIPTION <description> ]
-#                                              [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
-#                                              [ PURPOSE <purpose> ]
+#     SET_PACKAGE_PROPERTIES(<name> PROPERTIES
+#                            [ URL <url> ]
+#                            [ DESCRIPTION <description> ]
+#                            [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
+#                            [ PURPOSE <purpose> ]
 #                           )
 #
 #
@@ -171,26 +183,30 @@
 # ::
 #
 #    find_package(LibXml2)
-#    set_package_properties(LibXml2 PROPERTIES DESCRIPTION "A XML processing library."
-#                                              URL "http://xmlsoft.org/")
+#    set_package_properties(LibXml2 PROPERTIES
+#                           DESCRIPTION "A XML processing library."
+#                           URL "http://xmlsoft.org/")
 #
 #
 #
 # ::
 #
-#    set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED
-#                                              PURPOSE "Enables HTML-import in MyWordProcessor")
+#    set_package_properties(LibXml2 PROPERTIES
+#                           TYPE RECOMMENDED
+#                           PURPOSE "Enables HTML-import in MyWordProcessor")
 #    ...
-#    set_package_properties(LibXml2 PROPERTIES TYPE OPTIONAL
-#                                              PURPOSE "Enables odt-export in MyWordProcessor")
+#    set_package_properties(LibXml2 PROPERTIES
+#                           TYPE OPTIONAL
+#                           PURPOSE "Enables odt-export in MyWordProcessor")
 #
 #
 #
 # ::
 #
 #    find_package(DBUS)
-#    set_package_properties(DBUS PROPERTIES TYPE RUNTIME
-#                                              PURPOSE "Necessary to disable the screensaver during a presentation" )
+#    set_package_properties(DBUS PROPERTIES
+#      TYPE RUNTIME
+#      PURPOSE "Necessary to disable the screensaver during a presentation" )
 #
 #
 #
diff --git a/Modules/FindBacktrace.cmake b/Modules/FindBacktrace.cmake
index 07109b01f9..cb4f60a576 100644
--- a/Modules/FindBacktrace.cmake
+++ b/Modules/FindBacktrace.cmake
@@ -5,18 +5,24 @@
 # Find provider for backtrace(3).
 #
 # Checks if OS supports backtrace(3) via either libc or custom library.
-# This module defines the following variables::
+# This module defines the following variables:
 #
-#  Backtrace_HEADER       - The header file needed for backtrace(3). Cached.
-#                           Could be forcibly set by user.
-#  Backtrace_INCLUDE_DIRS - The include directories needed to use backtrace(3) header.
-#  Backtrace_LIBRARIES    - The libraries (linker flags) needed to use backtrace(3), if any.
-#  Backtrace_FOUND        - Is set if and only if backtrace(3) support detected.
+# ``Backtrace_HEADER``
+#   The header file needed for backtrace(3). Cached.
+#   Could be forcibly set by user.
+# ``Backtrace_INCLUDE_DIRS``
+#   The include directories needed to use backtrace(3) header.
+# ``Backtrace_LIBRARIES``
+#   The libraries (linker flags) needed to use backtrace(3), if any.
+# ``Backtrace_FOUND``
+#   Is set if and only if backtrace(3) support detected.
 #
-# The following cache variables are also available to set or use::
+# The following cache variables are also available to set or use:
 #
-#  Backtrace_LIBRARY     - The external library providing backtrace, if any.
-#  Backtrace_INCLUDE_DIR - The directory holding the backtrace(3) header.
+# ``Backtrace_LIBRARY``
+#   The external library providing backtrace, if any.
+# ``Backtrace_INCLUDE_DIR``
+#   The directory holding the backtrace(3) header.
 #
 # Typical usage is to generate of header file using configure_file() with the
 # contents like the following::
diff --git a/Modules/FindKDE3.cmake b/Modules/FindKDE3.cmake
index ea898a6508..dda453050f 100644
--- a/Modules/FindKDE3.cmake
+++ b/Modules/FindKDE3.cmake
@@ -8,29 +8,29 @@
 #
 # This module defines the following variables:
 #
-# ::
-#
-#   KDE3_DEFINITIONS         - compiler definitions required for compiling KDE software
-#   KDE3_INCLUDE_DIR         - the KDE include directory
-#   KDE3_INCLUDE_DIRS        - the KDE and the Qt include directory, for use with include_directories()
-#   KDE3_LIB_DIR             - the directory where the KDE libraries are installed, for use with link_directories()
-#   QT_AND_KDECORE_LIBS      - this contains both the Qt and the kdecore library
-#   KDE3_DCOPIDL_EXECUTABLE  - the dcopidl executable
-#   KDE3_DCOPIDL2CPP_EXECUTABLE - the dcopidl2cpp executable
-#   KDE3_KCFGC_EXECUTABLE    - the kconfig_compiler executable
-#   KDE3_FOUND               - set to TRUE if all of the above has been found
-#
-#
+# ``KDE3_DEFINITIONS``
+#   compiler definitions required for compiling KDE software
+# ``KDE3_INCLUDE_DIR``
+#   the KDE include directory
+# ``KDE3_INCLUDE_DIRS``
+#   the KDE and the Qt include directory, for use with include_directories()
+# ``KDE3_LIB_DIR``
+#   the directory where the KDE libraries are installed, for use with link_directories()
+# ``QT_AND_KDECORE_LIBS``
+#   this contains both the Qt and the kdecore library
+# ``KDE3_DCOPIDL_EXECUTABLE``
+#   the dcopidl executable
+# ``KDE3_DCOPIDL2CPP_EXECUTABLE``
+#   the dcopidl2cpp executable
+# ``KDE3_KCFGC_EXECUTABLE``
+#   the kconfig_compiler executable
+# ``KDE3_FOUND``
+#   set to TRUE if all of the above has been found
 #
 # The following user adjustable options are provided:
 #
-# ::
-#
-#   KDE3_BUILD_TESTS - enable this to build KDE testcases
-#
-#
-#
-#
+# ``KDE3_BUILD_TESTS``
+#   enable this to build KDE testcases
 #
 # It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
 # always the variable which contains the list of source files for your
@@ -101,7 +101,8 @@
 #
 # ::
 #
-#     Currently identical to add_executable(), may provide some advanced features in the future.
+#     Currently identical to add_executable(), may provide some advanced
+#     features in the future.
 #
 #
 #
@@ -110,7 +111,8 @@
 # ::
 #
 #     Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
-#     If WITH_PREFIX is given, the resulting plugin will have the prefix "lib", otherwise it won't.
+#     If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
+#     otherwise it won't.
 #     It creates and installs an appropriate libtool la-file.
 #
 #
@@ -120,7 +122,8 @@
 # ::
 #
 #     Create a KDE application in the form of a module loadable via kdeinit.
-#     A library named kdeinit_<name> will be created and a small executable which links to it.
+#     A library named kdeinit_<name> will be created and a small executable
+#     which links to it.
 #
 #
 #
diff --git a/Modules/FindOpenSceneGraph.cmake b/Modules/FindOpenSceneGraph.cmake
index 68adff746e..5a800e4768 100644
--- a/Modules/FindOpenSceneGraph.cmake
+++ b/Modules/FindOpenSceneGraph.cmake
@@ -40,13 +40,14 @@
 # OSG and it's various components.  CMAKE_PREFIX_PATH can also be used
 # for this (see find_library() CMake documentation).
 #
-# ::
-#
-#     <MODULE>_DIR (where MODULE is of the form "OSGVOLUME" and there is a FindosgVolume.cmake file)
-#     OSG_DIR
-#     OSGDIR
-#     OSG_ROOT
-#
+# ``<MODULE>_DIR``
+#   (where MODULE is of the form "OSGVOLUME" and there is a FindosgVolume.cmake file)
+# ``OSG_DIR``
+#   ..
+# ``OSGDIR``
+#   ..
+# ``OSG_ROOT``
+#   ..
 #
 #
 # [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
diff --git a/Modules/FindPNG.cmake b/Modules/FindPNG.cmake
index fa04bf0b4a..7cf3f22931 100644
--- a/Modules/FindPNG.cmake
+++ b/Modules/FindPNG.cmake
@@ -10,19 +10,22 @@
 #
 # It defines the following variables
 #
-# ::
-#
-#   PNG_INCLUDE_DIRS, where to find png.h, etc.
-#   PNG_LIBRARIES, the libraries to link against to use PNG.
-#   PNG_DEFINITIONS - You should add_definitons(${PNG_DEFINITIONS}) before compiling code that includes png library files.
-#   PNG_FOUND, If false, do not try to use PNG.
-#   PNG_VERSION_STRING - the version of the PNG library found (since CMake 2.8.8)
+# ``PNG_INCLUDE_DIRS``
+#   where to find png.h, etc.
+# ``PNG_LIBRARIES``
+#   the libraries to link against to use PNG.
+# ``PNG_DEFINITIONS``
+#   You should add_definitons(${PNG_DEFINITIONS}) before compiling code
+#   that includes png library files.
+# ``PNG_FOUND``
+#   If false, do not try to use PNG.
+# ``PNG_VERSION_STRING``
+#   the version of the PNG library found (since CMake 2.8.8)
 #
 # Also defined, but not for general use are
 #
-# ::
-#
-#   PNG_LIBRARY, where to find the PNG library.
+# ``PNG_LIBRARY``
+#   where to find the PNG library.
 #
 # For backward compatiblity the variable PNG_INCLUDE_DIR is also set.
 # It has the same value as PNG_INCLUDE_DIRS.
diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake
index 23f3f0511b..6bcf1e788b 100644
--- a/Modules/FindPackageHandleStandardArgs.cmake
+++ b/Modules/FindPackageHandleStandardArgs.cmake
@@ -20,7 +20,8 @@
 #
 # ::
 #
-#     FIND_PACKAGE_HANDLE_STANDARD_ARGS(<name> (DEFAULT_MSG|"Custom failure message") <var1>...<varN> )
+#     FIND_PACKAGE_HANDLE_STANDARD_ARGS(<name>
+#       (DEFAULT_MSG|"Custom failure message") <var1>...<varN> )
 #
 # If the variables <var1> to <varN> are all valid, then
 # <UPPERCASED_NAME>_FOUND will be set to TRUE.  If DEFAULT_MSG is given
@@ -32,14 +33,13 @@
 #
 # ::
 #
-#     FIND_PACKAGE_HANDLE_STANDARD_ARGS(NAME [FOUND_VAR <resultVar>]
-#                                            [REQUIRED_VARS <var1>...<varN>]
-#                                            [VERSION_VAR   <versionvar>]
-#                                            [HANDLE_COMPONENTS]
-#                                            [CONFIG_MODE]
-#                                            [FAIL_MESSAGE "Custom failure message"] )
-#
-#
+#     FIND_PACKAGE_HANDLE_STANDARD_ARGS(NAME
+#       [FOUND_VAR <resultVar>]
+#       [REQUIRED_VARS <var1>...<varN>]
+#       [VERSION_VAR   <versionvar>]
+#       [HANDLE_COMPONENTS]
+#       [CONFIG_MODE]
+#       [FAIL_MESSAGE "Custom failure message"] )
 #
 # In this mode, the name of the result-variable can be set either to
 # either <UPPERCASED_NAME>_FOUND or <OriginalCase_Name>_FOUND using the
@@ -75,7 +75,8 @@
 #
 # ::
 #
-#     find_package_handle_standard_args(LibXml2  DEFAULT_MSG  LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
+#     find_package_handle_standard_args(LibXml2  DEFAULT_MSG
+#       LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
 #
 #
 #
@@ -90,9 +91,10 @@
 #
 # ::
 #
-#     find_package_handle_standard_args(LibXslt FOUND_VAR LibXslt_FOUND
-#                                              REQUIRED_VARS LibXslt_LIBRARIES LibXslt_INCLUDE_DIRS
-#                                              VERSION_VAR LibXslt_VERSION_STRING)
+#     find_package_handle_standard_args(LibXslt
+#       FOUND_VAR LibXslt_FOUND
+#       REQUIRED_VARS LibXslt_LIBRARIES LibXslt_INCLUDE_DIRS
+#       VERSION_VAR LibXslt_VERSION_STRING)
 #
 # In this case, LibXslt is considered to be found if the variable(s)
 # listed after REQUIRED_VAR are all valid, i.e.  LibXslt_LIBRARIES and
diff --git a/Modules/FindQt4.cmake b/Modules/FindQt4.cmake
index 06a891748f..2c39de570d 100644
--- a/Modules/FindQt4.cmake
+++ b/Modules/FindQt4.cmake
@@ -111,12 +111,14 @@
 #
 # ::
 #
-#   macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname [basename] [classname])
+#   macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
+#                              [basename] [classname])
 #         create a dbus adaptor (header and implementation file) from the xml file
 #         describing the interface, and add it to the list of sources. The adaptor
 #         forwards the calls to a parent class, defined in parentheader and named
 #         parentclassname. The name of the generated files will be
-#         <basename>adaptor.{cpp,h} where basename defaults to the basename of the xml file.
+#         <basename>adaptor.{cpp,h} where basename defaults to the basename of the
+#         xml file.
 #         If <classname> is provided, then it will be used as the classname of the
 #         adaptor itself.
 #
@@ -128,7 +130,8 @@
 #         If the optional argument interfacename is omitted, the name of the
 #         interface file is constructed from the basename of the header with
 #         the suffix .xml appended.
-#         Options may be given to qdbuscpp2xml, such as those found when executing "qdbuscpp2xml --help"
+#         Options may be given to qdbuscpp2xml, such as those found when
+#         executing "qdbuscpp2xml --help"
 #
 #
 # ::
@@ -170,10 +173,11 @@
 #         want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
 #         #include "foo.moc"
 #         in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will the
-#         scan all listed files at cmake-time for such included moc files and if it finds
-#         them cause a rule to be generated to run moc at build time on the
+#         scan all listed files at cmake-time for such included moc files and if it
+#         finds them cause a rule to be generated to run moc at build time on the
 #         accompanying header file foo.h.
-#         If a source file has the SKIP_AUTOMOC property set it will be ignored by this macro.
+#         If a source file has the SKIP_AUTOMOC property set it will be ignored by
+#         this macro.
 #         If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
 #         INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
 #
@@ -181,16 +185,17 @@
 # ::
 #
 #  function QT4_USE_MODULES( target [link_type] modules...)
-#         This function is obsolete. Use target_link_libraries with IMPORTED targets instead.
+#         This function is obsolete. Use target_link_libraries with IMPORTED targets
+#         instead.
 #         Make <target> use the <modules> from Qt. Using a Qt module means
 #         to link to the library, add the relevant include directories for the module,
 #         and add the relevant compiler defines for using the module.
 #         Modules are roughly equivalent to components of Qt4, so usage would be
 #         something like:
 #          qt4_use_modules(myexe Core Gui Declarative)
-#         to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument can
-#         be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the same argument
-#         to the target_link_libraries call.
+#         to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
+#         can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
+#         same argument to the target_link_libraries call.
 #
 #
 # IMPORTED Targets
diff --git a/Modules/FindRuby.cmake b/Modules/FindRuby.cmake
index aafdc09cf1..b5ac703cf9 100644
--- a/Modules/FindRuby.cmake
+++ b/Modules/FindRuby.cmake
@@ -14,19 +14,21 @@
 # It also determines what the name of the library is.  This code sets
 # the following variables:
 #
-# ::
+# ``RUBY_EXECUTABLE``
+#   full path to the ruby binary
+# ``RUBY_INCLUDE_DIRS``
+#   include dirs to be used when using the ruby library
+# ``RUBY_LIBRARY``
+#   full path to the ruby library
+# ``RUBY_VERSION``
+#   the version of ruby which was found, e.g. "1.8.7"
+# ``RUBY_FOUND``
+#   set to true if ruby ws found successfully
 #
-#   RUBY_EXECUTABLE   = full path to the ruby binary
-#   RUBY_INCLUDE_DIRS = include dirs to be used when using the ruby library
-#   RUBY_LIBRARY      = full path to the ruby library
-#   RUBY_VERSION      = the version of ruby which was found, e.g. "1.8.7"
-#   RUBY_FOUND        = set to true if ruby ws found successfully
+# Also:
 #
-#
-#
-# ::
-#
-#   RUBY_INCLUDE_PATH = same as RUBY_INCLUDE_DIRS, only provided for compatibility reasons, don't use it
+# ``RUBY_INCLUDE_PATH``
+#   same as RUBY_INCLUDE_DIRS, only provided for compatibility reasons, don't use it
 
 #=============================================================================
 # Copyright 2004-2009 Kitware, Inc.
diff --git a/Modules/FindSquish.cmake b/Modules/FindSquish.cmake
index 2b7fd22612..4fdecb4561 100644
--- a/Modules/FindSquish.cmake
+++ b/Modules/FindSquish.cmake
@@ -21,7 +21,8 @@
 #
 # ::
 #
-#   SQUISH_INSTALL_DIR              The Squish installation directory (containing bin, lib, etc)
+#   SQUISH_INSTALL_DIR              The Squish installation directory
+#                                   (containing bin, lib, etc)
 #   SQUISH_SERVER_EXECUTABLE        The squishserver executable
 #   SQUISH_CLIENT_EXECUTABLE        The squishrunner executable
 #
@@ -47,21 +48,26 @@
 #
 # The arguments have the following meaning:
 #
-# ::
-#
-#    cmakeTestName: this will be used as the first argument for add_test()
-#    AUT targetName: the name of the cmake target which will be used as AUT, i.e. the
-#                    executable which will be tested.
-#    SUITE suiteName: this is either the full path to the squish suite, or just the
-#                     last directory of the suite, i.e. the suite name. In this case
-#                     the CMakeLists.txt which calls squish_add_test() must be located
-#                     in the parent directory of the suite directory.
-#    TEST squishTestName: the name of the squish test, i.e. the name of the subdirectory
-#                         of the test inside the suite directory.
-#    SETTINGSGROUP group: if specified, the given settings group will be used for executing the test.
-#                         If not specified, the groupname will be "CTest_<username>"
-#    PRE_COMMAND command:  if specified, the given command will be executed before starting the squish test.
-#    POST_COMMAND command: same as PRE_COMMAND, but after the squish test has been executed.
+# ``cmakeTestName``
+#   this will be used as the first argument for add_test()
+# ``AUT targetName``
+#   the name of the cmake target which will be used as AUT, i.e. the
+#   executable which will be tested.
+# ``SUITE suiteName``
+#   this is either the full path to the squish suite, or just the
+#   last directory of the suite, i.e. the suite name. In this case
+#   the CMakeLists.txt which calls squish_add_test() must be located
+#   in the parent directory of the suite directory.
+# ``TEST squishTestName``
+#   the name of the squish test, i.e. the name of the subdirectory
+#   of the test inside the suite directory.
+# ``SETTINGSGROUP group``
+#   if specified, the given settings group will be used for executing the test.
+#   If not specified, the groupname will be "CTest_<username>"
+# ``PRE_COMMAND command``
+#   if specified, the given command will be executed before starting the squish test.
+# ``POST_COMMAND command``
+#   same as PRE_COMMAND, but after the squish test has been executed.
 #
 #
 #
@@ -70,7 +76,12 @@
 #    enable_testing()
 #    find_package(Squish 4.0)
 #    if (SQUISH_FOUND)
-#       squish_v4_add_test(myTestName AUT myApp SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite TEST someSquishTest SETTINGSGROUP myGroup )
+#       squish_v4_add_test(myTestName
+#         AUT myApp
+#         SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
+#         TEST someSquishTest
+#         SETTINGSGROUP myGroup
+#         )
 #    endif ()
 #
 #
diff --git a/Modules/GNUInstallDirs.cmake b/Modules/GNUInstallDirs.cmake
index 10956aac0e..c61e7e9a1a 100644
--- a/Modules/GNUInstallDirs.cmake
+++ b/Modules/GNUInstallDirs.cmake
@@ -6,36 +6,47 @@
 #
 # Provides install directory variables as defined for GNU software:
 #
-# ::
-#
 #   http://www.gnu.org/prep/standards/html_node/Directory-Variables.html
 #
 # Inclusion of this module defines the following variables:
 #
-# ::
-#
-#   CMAKE_INSTALL_<dir>      - destination for files of a given type
-#   CMAKE_INSTALL_FULL_<dir> - corresponding absolute path
+# ``CMAKE_INSTALL_<dir>``
+#   destination for files of a given type
+# ``CMAKE_INSTALL_FULL_<dir>``
+#   corresponding absolute path
 #
 # where <dir> is one of:
 #
-# ::
-#
-#   BINDIR           - user executables (bin)
-#   SBINDIR          - system admin executables (sbin)
-#   LIBEXECDIR       - program executables (libexec)
-#   SYSCONFDIR       - read-only single-machine data (etc)
-#   SHAREDSTATEDIR   - modifiable architecture-independent data (com)
-#   LOCALSTATEDIR    - modifiable single-machine data (var)
-#   LIBDIR           - object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian)
-#   INCLUDEDIR       - C header files (include)
-#   OLDINCLUDEDIR    - C header files for non-gcc (/usr/include)
-#   DATAROOTDIR      - read-only architecture-independent data root (share)
-#   DATADIR          - read-only architecture-independent data (DATAROOTDIR)
-#   INFODIR          - info documentation (DATAROOTDIR/info)
-#   LOCALEDIR        - locale-dependent data (DATAROOTDIR/locale)
-#   MANDIR           - man documentation (DATAROOTDIR/man)
-#   DOCDIR           - documentation root (DATAROOTDIR/doc/PROJECT_NAME)
+# ``BINDIR``
+#   user executables (bin)
+# ``SBINDIR``
+#   system admin executables (sbin)
+# ``LIBEXECDIR``
+#   program executables (libexec)
+# ``SYSCONFDIR``
+#   read-only single-machine data (etc)
+# ``SHAREDSTATEDIR``
+#   modifiable architecture-independent data (com)
+# ``LOCALSTATEDIR``
+#   modifiable single-machine data (var)
+# ``LIBDIR``
+#   object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian)
+# ``INCLUDEDIR``
+#   C header files (include)
+# ``OLDINCLUDEDIR``
+#   C header files for non-gcc (/usr/include)
+# ``DATAROOTDIR``
+#   read-only architecture-independent data root (share)
+# ``DATADIR``
+#   read-only architecture-independent data (DATAROOTDIR)
+# ``INFODIR``
+#   info documentation (DATAROOTDIR/info)
+# ``LOCALEDIR``
+#   locale-dependent data (DATAROOTDIR/locale)
+# ``MANDIR``
+#   man documentation (DATAROOTDIR/man)
+# ``DOCDIR``
+#   documentation root (DATAROOTDIR/doc/PROJECT_NAME)
 #
 # Each CMAKE_INSTALL_<dir> value may be passed to the DESTINATION
 # options of install() commands for the corresponding file type.  If the
diff --git a/Modules/WriteBasicConfigVersionFile.cmake b/Modules/WriteBasicConfigVersionFile.cmake
index 7d28e95bf7..bf55eb9643 100644
--- a/Modules/WriteBasicConfigVersionFile.cmake
+++ b/Modules/WriteBasicConfigVersionFile.cmake
@@ -6,7 +6,10 @@
 #
 # ::
 #
-#   WRITE_BASIC_CONFIG_VERSION_FILE( filename [VERSION major.minor.patch] COMPATIBILITY (AnyNewerVersion|SameMajorVersion) )
+#   WRITE_BASIC_CONFIG_VERSION_FILE( filename
+#     [VERSION major.minor.patch]
+#     COMPATIBILITY (AnyNewerVersion|SameMajorVersion)
+#     )
 #
 #
 #