Merge topic 'help-syntax-highlighting'

93f3f65516 Help: Revise docs of modules AddFileDependencies..CheckFunctionExists
fc7ee1ca45 Help: Override pygments CMakeLexer to support <..> and [..]
74b3eacdc7 Help: Use appropriate list types in FindPkgConfig

Acked-by: Kitware Robot <[email protected]>
Merge-request: !2468

Help/command/execute_process.rst

@@ -5,8 +5,8 @@ Execute one or more child processes.
 
 .. code-block:: cmake
 
-  execute_process(COMMAND <cmd1> [args1...]]
-                  [COMMAND <cmd2> [args2...] [...]]
+  execute_process(COMMAND <cmd1> [<arguments>]
+                  [COMMAND <cmd2> [<arguments>]]...
                   [WORKING_DIRECTORY <directory>]
                   [TIMEOUT <seconds>]
                   [RESULT_VARIABLE <variable>]

Help/manual/cmake-language.7.rst

@@ -206,9 +206,10 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_,
 is performed.  A bracket argument is always given to the command
 invocation as exactly one argument.
 
-For example:
+.. No code-block syntax highlighting in the following example
+   (long string literal not supported by our cmake.py)
 
-.. code-block:: cmake
+For example::
 
  message([=[
  This is the first line in a bracket argument with bracket length 1.
@@ -253,9 +254,10 @@ closing quotes.  Both `Escape Sequences`_ and `Variable References`_
 are evaluated.  A quoted argument is always given to the command
 invocation as exactly one argument.
 
-For example:
+.. No code-block syntax highlighting in the following example
+   (escape \" not supported by our cmake.py)
 
-::
+For example::
 
  message("This is a quoted argument containing multiple lines.
  This is always one argument even though it contains a ; character.
@@ -264,11 +266,12 @@ For example:
  It does end in an unescaped double quote.
  ")
 
+.. No code-block syntax highlighting in the following example
+   (for conformity with the two above examples)
+
 The final ``\`` on any line ending in an odd number of backslashes
 is treated as a line continuation and ignored along with the
-immediately following newline character.  For example:
-
-.. code-block:: cmake
+immediately following newline character.  For example::
 
  message("\
  This is the first line of a quoted argument. \

Help/policy/CMP0049.rst

@@ -3,14 +3,14 @@ CMP0049
 
 Do not expand variables in target source entries.
 
-CMake 2.8.12 and lower performed and extra layer of variable expansion
-when evaluating source file names:
-
-.. code-block:: cmake
+CMake 2.8.12 and lower performed an extra layer of variable expansion
+when evaluating source file names::
 
   set(a_source foo.c)
   add_executable(foo \${a_source})
 
+.. note: no cmake highlighting since this syntax is deprecated
+
 This was undocumented behavior.
 
 The OLD behavior for this policy is to expand such variables when processing

Modules/AddFileDependencies.cmake

@@ -5,9 +5,13 @@
 # AddFileDependencies
 # -------------------
 #
-# ADD_FILE_DEPENDENCIES(source_file depend_files...)
+# Add dependencies to a source file.
 #
-# Adds the given files as dependencies to source_file
+# .. code-block:: cmake
+#
+#   ADD_FILE_DEPENDENCIES(<source> <files>)
+#
+# Adds the given ``<files>`` to the dependencies of file ``<source>``.
 
 macro(ADD_FILE_DEPENDENCIES _file)
 

Modules/AndroidTestUtilities.cmake

@@ -40,7 +40,7 @@ Module Functions
 
 .. command:: android_add_test_data
 
-  ::
+  .. code-block:: cmake
 
     android_add_test_data(<test-name>
       [FILES <files>...] [FILES_DEST <device-dir>]

Modules/BundleUtilities.cmake

@@ -12,7 +12,7 @@ bundles on the Mac and bundle-like directories on any OS.
 
 The following functions are provided by this module:
 
-::
+.. code-block:: cmake
 
    fixup_bundle
    copy_and_fixup_bundle
@@ -39,7 +39,7 @@ DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from ``CMakeLists.txt``)!
 Instead, invoke them from an :command:`install(CODE)` or
 :command:`install(SCRIPT)` rule.
 
-::
+.. code-block:: cmake
 
   FIXUP_BUNDLE(<app> <libs> <dirs>)
 
@@ -62,14 +62,14 @@ ensure that it is truly standalone.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   COPY_AND_FIXUP_BUNDLE(<src> <dst> <libs> <dirs>)
 
 Makes a copy of the bundle <src> at location <dst> and then fixes up
 the new copied bundle in-place at <dst>...
 
-::
+.. code-block:: cmake
 
   VERIFY_APP(<app>)
 
@@ -80,14 +80,14 @@ is not verified.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_MAIN_EXECUTABLE(<bundle> <result_var>)
 
 The result will be the full path name of the bundle's main executable
 file or an "error:" prefixed string if it could not be determined.
 
-::
+.. code-block:: cmake
 
   GET_DOTAPP_DIR(<exe> <dotapp_dir_var>)
 
@@ -97,7 +97,7 @@ simply return the dir containing the executable.
 
 The returned directory may or may not exist.
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_AND_EXECUTABLE(<app> <bundle_var> <executable_var> <valid_var>)
 
@@ -106,14 +106,14 @@ nested inside a ".app" directory and returns the path to the ".app"
 directory in <bundle_var> and the path to its main executable in
 <executable_var>
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
 
 Scans the given bundle recursively for all executable files and
 accumulates them into a variable.
 
-::
+.. code-block:: cmake
 
   GET_ITEM_KEY(<item> <key_var>)
 
@@ -125,7 +125,7 @@ extension with "." replaced by "_"
 This key is used as a prefix for CMake variables so that we can
 associate a set of variables with a given item based on its key.
 
-::
+.. code-block:: cmake
 
   CLEAR_BUNDLE_KEYS(<keys_var>)
 
@@ -135,7 +135,7 @@ each key.  After the loop, clear the list of keys itself.
 Caller of get_bundle_keys should call clear_bundle_keys when done with
 list of keys.
 
-::
+.. code-block:: cmake
 
   SET_BUNDLE_KEY_VALUES(<keys_var> <context> <item> <exepath> <dirs>
                         <copyflag> [<rpaths>])
@@ -143,7 +143,7 @@ list of keys.
 Add a key to the list (if necessary) for the given item.  If added,
 also set all the variables associated with that key.
 
-::
+.. code-block:: cmake
 
   GET_BUNDLE_KEYS(<app> <libs> <dirs> <keys_var>)
 
@@ -156,7 +156,7 @@ appropriate install_name_tool fixups.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   COPY_RESOLVED_ITEM_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
 
@@ -164,7 +164,7 @@ Copy a resolved item into the bundle if necessary.  Copy is not
 necessary if the resolved_item is "the same as" the
 resolved_embedded_item.
 
-::
+.. code-block:: cmake
 
   COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
 
@@ -178,7 +178,7 @@ BU_COPY_FULL_FRAMEWORK_CONTENTS to ON before calling fixup_bundle.  By
 default, COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework
 dylib itself plus the framework Resources directory.
 
-::
+.. code-block:: cmake
 
   FIXUP_BUNDLE_ITEM(<resolved_embedded_item> <exepath> <dirs>)
 
@@ -204,7 +204,7 @@ once.
 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
 marked writable before install_name_tool tries to change them.
 
-::
+.. code-block:: cmake
 
   VERIFY_BUNDLE_PREREQUISITES(<bundle> <result_var> <info_var>)
 
@@ -215,7 +215,7 @@ presumed to exist everywhere.
 As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
 which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
 
-::
+.. code-block:: cmake
 
   VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
 

Modules/CheckCCompilerFlag.cmake

@@ -9,7 +9,7 @@ Check whether the C compiler supports a given flag.
 
 .. command:: check_c_compiler_flag
 
-  ::
+  .. code-block:: cmake
 
     check_c_compiler_flag(<flag> <var>)
 

Modules/CheckCSourceCompiles.cmake

@@ -9,15 +9,16 @@ Check if given C source compiles and links into an executable.
 
 .. command:: check_c_source_compiles
 
-  ::
+  .. code-block:: cmake
 
-    check_c_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
+    check_c_source_compiles(<code> <resultVar>
+                            [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``code`` can be compiled as a C source
+  Check that the source supplied in ``<code>`` can be compiled as a C source
   file and linked as an executable (so it must contain at least a ``main()``
   function). The result will be stored in the internal cache variable specified
-  by ``resultVar``, with a boolean true value for success and boolean false for
-  failure. If ``FAIL_REGEX`` is provided, then failure is determined by
+  by ``<resultVar>``, with a boolean true value for success and boolean false
+  for failure. If ``FAIL_REGEX`` is provided, then failure is determined by
   checking if anything in the output matches any of the specified regular
   expressions.
 
@@ -34,7 +35,7 @@ Check if given C source compiles and links into an executable.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +54,10 @@ Check if given C source compiles and links into an executable.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -131,4 +132,3 @@ macro(CHECK_C_SOURCE_COMPILES SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCSourceRuns.cmake

@@ -10,16 +10,16 @@ subsequently be run.
 
 .. command:: check_c_source_runs
 
-  ::
+  .. code-block:: cmake
 
-    check_c_source_runs(code resultVar)
+    check_c_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``code`` can be compiled as a C source
-  file, linked as an executable and then run. The ``code`` must contain at
-  least a ``main()`` function. If the code could be built and run successfully,
-  the internal cache variable specified by ``resultVar`` will be set to 1,
-  otherwise it will be set to an value that evaluates to boolean false (e.g.
-  an empty string or an error message).
+  Check that the source supplied in ``<code>`` can be compiled as a C source
+  file, linked as an executable and then run. The ``<code>`` must contain at
+  least a ``main()`` function. If the ``<code>`` could be built and run
+  successfully, the internal cache variable specified by ``<resultVar>`` will
+  be set to 1, otherwise it will be set to an value that evaluates to boolean
+  false (e.g. an empty string or an error message).
 
   The underlying check is performed by the :command:`try_run` command. The
   compile and link commands can be influenced by setting any of the following
@@ -34,7 +34,7 @@ subsequently be run.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +53,10 @@ subsequently be run.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -132,4 +132,3 @@ macro(CHECK_C_SOURCE_RUNS SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCXXCompilerFlag.cmake

@@ -9,7 +9,7 @@ Check whether the CXX compiler supports a given flag.
 
 .. command:: check_cxx_compiler_flag
 
-  ::
+  .. code-block:: cmake
 
     check_cxx_compiler_flag(<flag> <var>)
 
@@ -61,4 +61,3 @@ macro (CHECK_CXX_COMPILER_FLAG _FLAG _RESULT)
 
    set (CMAKE_REQUIRED_DEFINITIONS "${SAFE_CMAKE_REQUIRED_DEFINITIONS}")
 endmacro ()
-

Modules/CheckCXXSourceCompiles.cmake

@@ -9,15 +9,16 @@ Check if given C++ source compiles and links into an executable.
 
 .. command:: check_cxx_source_compiles
 
-  ::
+  .. code-block:: cmake
 
-    check_cxx_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
+    check_cxx_source_compiles(<code> <resultVar>
+                              [FAIL_REGEX <regex1> [<regex2>...]])
 
-  Check that the source supplied in ``code`` can be compiled as a C++ source
+  Check that the source supplied in ``<code>`` can be compiled as a C++ source
   file and linked as an executable (so it must contain at least a ``main()``
   function). The result will be stored in the internal cache variable specified
-  by ``resultVar``, with a boolean true value for success and boolean false for
-  failure. If ``FAIL_REGEX`` is provided, then failure is determined by
+  by ``<resultVar>``, with a boolean true value for success and boolean false
+  for failure. If ``FAIL_REGEX`` is provided, then failure is determined by
   checking if anything in the output matches any of the specified regular
   expressions.
 
@@ -34,7 +35,7 @@ Check if given C++ source compiles and links into an executable.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +54,10 @@ Check if given C++ source compiles and links into an executable.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -132,4 +133,3 @@ macro(CHECK_CXX_SOURCE_COMPILES SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCXXSourceRuns.cmake

@@ -10,16 +10,16 @@ subsequently be run.
 
 .. command:: check_cxx_source_runs
 
-  ::
+  .. code-block:: cmake
 
-    check_cxx_source_runs(code resultVar)
+    check_cxx_source_runs(<code> <resultVar>)
 
-  Check that the source supplied in ``code`` can be compiled as a C++ source
-  file, linked as an executable and then run. The ``code`` must contain at
-  least a ``main()`` function. If the code could be built and run successfully,
-  the internal cache variable specified by ``resultVar`` will be set to 1,
-  otherwise it will be set to an value that evaluates to boolean false (e.g.
-  an empty string or an error message).
+  Check that the source supplied in ``<code>`` can be compiled as a C++ source
+  file, linked as an executable and then run. The ``<code>`` must contain at
+  least a ``main()`` function. If the ``<code>`` could be built and run
+  successfully, the internal cache variable specified by ``<resultVar>`` will
+  be set to 1, otherwise it will be set to an value that evaluates to boolean
+  false (e.g. an empty string or an error message).
 
   The underlying check is performed by the :command:`try_run` command. The
   compile and link commands can be influenced by setting any of the following
@@ -34,7 +34,7 @@ subsequently be run.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -53,10 +53,10 @@ subsequently be run.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 
@@ -127,4 +127,3 @@ macro(CHECK_CXX_SOURCE_RUNS SOURCE VAR)
     endif()
   endif()
 endmacro()
-

Modules/CheckCXXSymbolExists.cmake

@@ -7,10 +7,12 @@
 #
 # Check if a symbol exists as a function, variable, or macro in C++
 #
-# CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
+# .. code-block:: cmake
 #
-# Check that the <symbol> is available after including given header
-# <files> and store the result in a <variable>.  Specify the list of
+#   CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
+#
+# Check that the ``<symbol>`` is available after including given header
+# ``<files>`` and store the result in a ``<variable>``.  Specify the list of
 # files in one argument as a semicolon-separated list.
 # CHECK_CXX_SYMBOL_EXISTS() can be used to check in C++ files, as
 # opposed to CHECK_SYMBOL_EXISTS(), which works only for C.
@@ -24,13 +26,16 @@
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
 #
-# ::
-#
-#   CMAKE_REQUIRED_FLAGS = string of compile command line flags
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# ``CMAKE_REQUIRED_FLAGS``
+#    string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
+#    list of macros to define (-DFOO=bar)
+# ``CMAKE_REQUIRED_INCLUDES``
+#    list of include directories
+# ``CMAKE_REQUIRED_LIBRARIES``
+#    list of libraries to link
+# ``CMAKE_REQUIRED_QUIET``
+#    execute quietly without messages
 
 include_guard(GLOBAL)
 include(CheckSymbolExists)

Modules/CheckFortranCompilerFlag.cmake

@@ -9,7 +9,7 @@ Check whether the Fortran compiler supports a given flag.
 
 .. command:: check_fortran_compiler_flag
 
-  ::
+  .. code-block:: cmake
 
     check_fortran_compiler_flag(<flag> <var>)
 

Modules/CheckFortranFunctionExists.cmake

@@ -5,24 +5,24 @@
 # CheckFortranFunctionExists
 # --------------------------
 #
-# macro which checks if the Fortran function exists
+# :command:`Macro <macro>` which checks if a Fortran function exists.
 #
-# CHECK_FORTRAN_FUNCTION_EXISTS(FUNCTION VARIABLE)
+# .. code-block:: cmake
 #
-# ::
-#
-#   FUNCTION - the name of the Fortran function
-#   VARIABLE - variable to store the result
-#              Will be created as an internal cache variable.
+#   CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
 #
+# where
 #
+# ``<function>``
+#   the name of the Fortran function
+# ``<result>``
+#   variable to store the result; will be created as an internal cache variable.
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
 #
-# ::
-#
-#   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
+# ``CMAKE_REQUIRED_LIBRARIES``
+#   list of libraries to link
 
 include_guard(GLOBAL)
 

Modules/CheckFortranSourceCompiles.cmake

@@ -9,23 +9,24 @@ Check if given Fortran source compiles and links into an executable.
 
 .. command:: check_fortran_source_compiles
 
-  ::
+  .. code-block:: cmake
 
-    check_fortran_source_compiles(code resultVar
-        [FAIL_REGEX regex1 [regex2...]]
-        [SRC_EXT ext]
+    check_fortran_source_compiles(<code> <resultVar>
+        [FAIL_REGEX <regex>...]
+        [SRC_EXT <extension>]
     )
 
-  Check that the source supplied in ``code`` can be compiled as a Fortran
+  Checks that the source supplied in ``<code>`` can be compiled as a Fortran
   source file and linked as an executable (so it must contain at least a
   ``PROGRAM`` entry point). The result will be stored in the internal cache
-  variable specified by ``resultVar``, with a boolean true value for success
-  and boolean false for failure. If ``FAIL_REGEX`` is provided, then failure is
-  determined by checking if anything in the output matches any of the specified
-  regular expressions.
+  variable ``<resultVar>``, with a boolean true value for success and boolean
+  false for failure.
+
+  If ``FAIL_REGEX`` is provided, then failure is determined by checking
+  if anything in the output matches any of the specified regular expressions.
 
   By default, the test source file will be given a ``.F`` file extension. The
-  ``SRC_EXT`` option can be used to override this with ``.ext`` instead.
+  ``SRC_EXT`` option can be used to override this with ``.<extension>`` instead.
 
   The underlying check is performed by the :command:`try_compile` command. The
   compile and link commands can be influenced by setting any of the following
@@ -40,7 +41,7 @@ Check if given Fortran source compiles and links into an executable.
   ``CMAKE_REQUIRED_DEFINITIONS``
     A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
     ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
-    ``resultVar`` will also be added automatically.
+    ``<resultVar>`` will also be added automatically.
 
   ``CMAKE_REQUIRED_INCLUDES``
     A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
@@ -59,10 +60,10 @@ Check if given Fortran source compiles and links into an executable.
     associated with the check will be suppressed.
 
   The check is only performed once, with the result cached in the variable
-  named by ``resultVar``. Every subsequent CMake run will re-use this cached
-  value rather than performing the check again, even if the ``code`` changes.
+  named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
+  value rather than performing the check again, even if the ``<code>`` changes.
   In order to force the check to be re-evaluated, the variable named by
-  ``resultVar`` must be manually removed from the cache.
+  ``<resultVar>`` must be manually removed from the cache.
 
 #]=======================================================================]
 

Modules/CheckFunctionExists.cmake

@@ -5,24 +5,29 @@
 # CheckFunctionExists
 # -------------------
 #
-# Check if a C function can be linked::
+# Check if a C function can be linked
+#
+# .. code-block:: cmake
 #
 #   check_function_exists(<function> <variable>)
 #
-# Check that the ``<function>`` is provided by libraries on the system and store
-# the result in a ``<variable>``. ``<variable>`` will be created as an internal
+# Checks that the ``<function>`` is provided by libraries on the system and store
+# the result in a ``<variable>``, which will be created as an internal
 # cache variable.
 #
 # The following variables may be set before calling this macro to modify the
 # way the check is run:
 #
-# ::
-#
-#   CMAKE_REQUIRED_FLAGS = string of compile command line flags
-#   CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
-#   CMAKE_REQUIRED_INCLUDES = list of include directories
-#   CMAKE_REQUIRED_LIBRARIES = list of libraries to link
-#   CMAKE_REQUIRED_QUIET = execute quietly without messages
+# ``CMAKE_REQUIRED_FLAGS``
+#   string of compile command line flags
+# ``CMAKE_REQUIRED_DEFINITIONS``
+#   list of macros to define (-DFOO=bar)
+# ``CMAKE_REQUIRED_INCLUDES``
+#   list of include directories
+# ``CMAKE_REQUIRED_LIBRARIES``
+#   list of libraries to link
+# ``CMAKE_REQUIRED_QUIET``
+#   execute quietly without messages
 #
 # .. note::
 #

Modules/ExternalProject.cmake

@@ -16,7 +16,9 @@ External Project Definition
 
   The ``ExternalProject_Add()`` function creates a custom target to drive
   download, update/patch, configure, build, install and test steps of an
-  external project::
+  external project:
+
+  .. code-block:: cmake
 
     ExternalProject_Add(<name> [<option>...])
 
@@ -608,7 +610,9 @@ External Project Definition
       appended to them by following them with as many ``COMMAND ...`` options
       as needed
       (:manual:`generator expressions <cmake-generator-expressions(7)>` are
-      supported). For example::
+      supported). For example:
+
+      .. code-block:: cmake
 
         ExternalProject_Add(example
           ... # Download options, etc.
@@ -627,7 +631,9 @@ Obtaining Project Properties
 .. command:: ExternalProject_Get_Property
 
   The ``ExternalProject_Get_Property()`` function retrieves external project
-  target properties::
+  target properties:
+
+  .. code-block:: cmake
 
     ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
 
@@ -655,7 +661,9 @@ control needed to implement such step-level capabilities.
 
   The ``ExternalProject_Add_Step()`` function specifies an additional custom
   step for an external project defined by an earlier call to
-  :command:`ExternalProject_Add`::
+  :command:`ExternalProject_Add`:
+
+  .. code-block:: cmake
 
     ExternalProject_Add_Step(<name> <step> [<option>...])
 
@@ -722,7 +730,9 @@ control needed to implement such step-level capabilities.
 
   The ``ExternalProject_Add_StepTargets()`` function generates targets for the
   steps listed. The name of each created target will be of the form
-  ``<name>-<step>``::
+  ``<name>-<step>``:
+
+  .. code-block:: cmake
 
     ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
 
@@ -773,7 +783,9 @@ control needed to implement such step-level capabilities.
   The ``ExternalProject_Add_StepDependencies()`` function can be used to add
   dependencies to a step. The dependencies added must be targets CMake already
   knows about (these can be ordinary executable or library targets, custom
-  targets or even step targets of another external project)::
+  targets or even step targets of another external project):
+
+  .. code-block:: cmake
 
     ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
 

Modules/FindPkgConfig.cmake

@@ -9,12 +9,14 @@ A ``pkg-config`` module for CMake.
 
 Finds the ``pkg-config`` executable and adds the :command:`pkg_get_variable`,
 :command:`pkg_check_modules` and :command:`pkg_search_module` commands. The
-following variables will also be set::
+following variables will also be set:
 
-  PKG_CONFIG_FOUND          ... if pkg-config executable was found
-  PKG_CONFIG_EXECUTABLE     ... pathname of the pkg-config program
-  PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
-                                (since CMake 2.8.8)
+``PKG_CONFIG_FOUND``
+  if pkg-config executable was found
+``PKG_CONFIG_EXECUTABLE``
+  pathname of the pkg-config program
+``PKG_CONFIG_VERSION_STRING``
+  version of pkg-config (since CMake 2.8.8)
 
 #]========================================]
 
@@ -86,7 +88,9 @@ endmacro()
 .. command:: pkg_get_variable
 
   Retrieves the value of a pkg-config variable ``varName`` and stores it in the
-  result variable ``resultVar`` in the calling scope. ::
+  result variable ``resultVar`` in the calling scope.
+
+  .. code-block:: cmake
 
     pkg_get_variable(<resultVar> <moduleName> <varName>)
 
@@ -512,7 +516,9 @@ endmacro()
 .. command:: pkg_check_modules
 
   Checks for all the given modules, setting a variety of result variables in
-  the calling scope. ::
+  the calling scope.
+
+  .. code-block:: cmake
 
     pkg_check_modules(<prefix>
                       [REQUIRED] [QUIET]
@@ -543,27 +549,36 @@ endmacro()
   Each ``<moduleSpec>`` can be either a bare module name or it can be a
   module name with a version constraint (operators ``=``, ``<``, ``>``,
   ``<=`` and ``>=`` are supported).  The following are examples for a module
-  named ``foo`` with various constraints::
-
-    foo           # Any version matches
-    foo<2         # Only match versions before 2
-    foo>=3.1      # Match any version from 3.1 or later
-    foo=1.2.3     # Foo must be exactly version 1.2.3
-
-  The following variables may be set upon return.  Two sets of values exist,
-  one for the common case (``<XXX> = <prefix>``) and another for the
-  information ``pkg-config`` provides when it is called with the ``--static``
-  option (``<XXX> = <prefix>_STATIC``)::
-
-    <XXX>_FOUND          ... set to 1 if module(s) exist
-    <XXX>_LIBRARIES      ... only the libraries (without the '-l')
-    <XXX>_LINK_LIBRARIES ... the libraries and their absolute paths
-    <XXX>_LIBRARY_DIRS   ... the paths of the libraries (without the '-L')
-    <XXX>_LDFLAGS        ... all required linker flags
-    <XXX>_LDFLAGS_OTHER  ... all other linker flags
-    <XXX>_INCLUDE_DIRS   ... the '-I' preprocessor flags (without the '-I')
-    <XXX>_CFLAGS         ... all required cflags
-    <XXX>_CFLAGS_OTHER   ... the other compiler flags
+  named ``foo`` with various constraints:
+
+  - ``foo`` matches any version.
+  - ``foo<2`` only matches versions before 2.
+  - ``foo>=3.1`` matches any version from 3.1 or later.
+  - ``foo=1.2.3`` requires that foo must be exactly version 1.2.3.
+
+  The following variables may be set upon return.  Two sets of values exist:
+  One for the common case (``<XXX> = <prefix>``) and another for the
+  information ``pkg-config`` provides when called with the ``--static``
+  option (``<XXX> = <prefix>_STATIC``).
+
+  ``<XXX>_FOUND``
+    set to 1 if module(s) exist
+  ``<XXX>_LIBRARIES``
+    only the libraries (without the '-l')
+  ``<XXX>_LINK_LIBRARIES``
+    the libraries and their absolute paths
+  ``<XXX>_LIBRARY_DIRS``
+    the paths of the libraries (without the '-L')
+  ``<XXX>_LDFLAGS``
+    all required linker flags
+  ``<XXX>_LDFLAGS_OTHER``
+    all other linker flags
+  ``<XXX>_INCLUDE_DIRS``
+    the '-I' preprocessor flags (without the '-I')
+  ``<XXX>_CFLAGS``
+    all required cflags
+  ``<XXX>_CFLAGS_OTHER``
+    the other compiler flags
 
   All but ``<XXX>_FOUND`` may be a :ref:`;-list <CMake Language Lists>` if the
   associated variable returned from ``pkg-config`` has multiple values.
@@ -571,14 +586,18 @@ endmacro()
   There are some special variables whose prefix depends on the number of
   ``<moduleSpec>`` given.  When there is only one ``<moduleSpec>``,
   ``<YYY>`` will simply be ``<prefix>``, but if two or more ``<moduleSpec>``
-  items are given, ``<YYY>`` will be ``<prefix>_<moduleName>``::
+  items are given, ``<YYY>`` will be ``<prefix>_<moduleName>``.
 
-    <YYY>_VERSION    ... version of the module
-    <YYY>_PREFIX     ... prefix directory of the module
-    <YYY>_INCLUDEDIR ... include directory of the module
-    <YYY>_LIBDIR     ... lib directory of the module
+  ``<YYY>_VERSION``
+    version of the module
+  ``<YYY>_PREFIX``
+    prefix directory of the module
+  ``<YYY>_INCLUDEDIR``
+    include directory of the module
+  ``<YYY>_LIBDIR``
+    lib directory of the module
 
-  Examples
+  Examples:
 
   .. code-block:: cmake
 
@@ -638,7 +657,9 @@ endmacro()
 
   The behavior of this command is the same as :command:`pkg_check_modules`,
   except that rather than checking for all the specified modules, it searches
-  for just the first successful match. ::
+  for just the first successful match.
+
+  .. code-block:: cmake
 
     pkg_search_module(<prefix>
                       [REQUIRED] [QUIET]
@@ -647,7 +668,7 @@ endmacro()
                       [IMPORTED_TARGET [GLOBAL]]
                       <moduleSpec> [<moduleSpec>...])
 
-  Examples
+  Example:
 
   .. code-block:: cmake
 

Utilities/Sphinx/cmake.py

@@ -4,14 +4,55 @@
 import os
 import re
 
-# Monkey patch for pygments reporting an error when generator expressions are
-# used.
-# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled
+# Override much of pygments' CMakeLexer.
+# We need to parse CMake syntax definitions, not CMake code.
+
+# For hard test cases that use much of the syntax below, see
+# - module/FindPkgConfig.html (with "glib-2.0>=2.10 gtk+-2.0" and similar)
+# - module/ExternalProject.html (with http:// https:// git@; also has command options -E --build)
+# - manual/cmake-buildsystem.7.html (with nested $<..>; relative and absolute paths, "::")
+
 from pygments.lexers import CMakeLexer
-from pygments.token import Name, Operator
+from pygments.token import Name, Operator, Punctuation, String, Text, Comment, Generic, Whitespace, Number
 from pygments.lexer import bygroups
-CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)',
-                                  bygroups(Operator, Name.Variable, Operator)))
+
+# Notes on regular expressions below:
+# - [\.\+-] are needed for string constants like gtk+-2.0
+# - Unix paths are recognized by '/'; support for Windows paths may be added if needed
+# - (\\.) allows for \-escapes (used in manual/cmake-language.7)
+# - $<..$<..$>..> nested occurence in cmake-buildsystem
+
+CMakeLexer.tokens["root"] = [
+  (r'\b(\w+)([ \t]*)(\()', bygroups(Name.Function, Text, Name.Function), '#push'),     # fctn(
+  (r'\(', Name.Function, '#push'),
+  (r'\)', Name.Function, '#pop'),
+  (r'\[', Punctuation, '#push'),
+  (r'\]', Punctuation, '#pop'),
+  (r'[|;,.=*\-]', Punctuation),
+  (r'\\\\', Punctuation),                                   # used in commands/source_group
+  (r'[:]', Operator),
+  (r'[<>]=', Punctuation),                                  # used in FindPkgConfig.cmake
+  (r'\$<', Operator, '#push'),                              # $<...>
+  (r'<[^<|]+?>(\w*\.\.\.)?', Name.Variable),                # <expr>
+  (r'(\$\w*\{)(.+?)(\})', bygroups(Operator, Name.Tag, Operator)),   # ${..} $ENV{..}
+  (r'([A-Z]+\{)(.+?)(\})', bygroups(Operator, Name.Tag, Operator)),  # DATA{ ...}
+  (r'[a-z]+(@|(://))((\\.)|[\w.+-:/\\])+', Name.Attribute),          # URL, git@, ...
+  (r'/\w[\w\.\+-/\\]*', Name.Attribute),                    # absolute path
+  (r'/', Name.Attribute),
+  (r'\w[\w\.\+-]*/[\w.+-/\\]*', Name.Attribute),            # relative path
+  (r'[A-Z]((\\.)|[\w.+-])*[a-z]((\\.)|[\w.+-])*', Name.Builtin), # initial A-Z, contains a-z
+  (r'@?[A-Z][A-Z0-9_]*', Name.Constant),
+  (r'[a-z_]((\\;)|(\\ )|[\w.+-])*', Name.Builtin),
+  (r'[0-9][0-9\.]*', Number),
+  (r'(?s)"(\\"|[^"])*"', String),                           # "string"
+  (r'\.\.\.', Name.Variable),
+  (r'<', Operator, '#push'),                                # <..|..> is different from <expr>
+  (r'>', Operator, '#pop'),
+  (r'\n', Whitespace),
+  (r'[ \t]+', Whitespace),
+  (r'#.*\n', Comment),
+  #  (r'[^<>\])\}\|$"# \t\n]+', Name.Exception),            # fallback, for debugging only
+]
 
 # Monkey patch for sphinx generating invalid content for qcollectiongenerator
 # https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords

Utilities/Sphinx/colors.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+
+from pygments.style import Style
+from pygments.token import Name, Comment, String, Number, Operator, Whitespace
+
+class CMakeTemplateStyle(Style):
+    """
+        for more token names, see pygments/styles.default
+    """
+
+    background_color = "#f8f8f8"
+    default_style = ""
+
+    styles = {
+        Whitespace:                "#bbbbbb",
+        Comment:                   "italic #408080",
+        Operator:                  "bold #000000",
+        String:                    "#217A21",
+        Number:                    "#105030",
+        Name.Builtin:              "#400080",          # anything lowercase
+        Name.Function:             "bold #1010A0",     # function
+        Name.Variable:             "#1080B0",          # <..>
+        Name.Tag:                  "#19177C",          # ${..}
+        Name.Constant:             "#6020E0",          # uppercase only
+        Name.Entity:               "italic #70A020",   # @..@
+        Name.Attribute:            "#906060",          # paths, URLs
+        Name.Label:                "#A0A000",          # anything left over
+        Name.Exception:            "bold #FF0000",     # for debugging only
+    }

Utilities/Sphinx/conf.py.in

@@ -15,6 +15,7 @@ project = 'CMake'
 copyright = '@conf_copyright@'
 version = '@conf_version@' # feature version
 release = '@conf_release@' # full version string
+pygments_style = 'colors.CMakeTemplateStyle'
 
 primary_domain = 'cmake'
 highlight_language = 'none'