Help: Override pygments CMakeLexer to support <..> and [..]

* The code snippets in the docs consist of CMake code mixed
  with syntax definition punctuation like < > [ ] ... Therefore
  a pure CMake lexer is inadequate. Here it is replaced by a
  CMake syntax definition parser.
* Fixed syntax definition snippets in FindPkgConfig.cmake to
  make best use of syntax highlighting. This source file is the
  hardest to support because it contains comparison operators
  <= = >=, which need special attention to avoid confusion
  with the placeholder indicators <...>.
* Fixed syntax in execute_process.rst (there were unbalanced
  brackets).
* Disabled syntax highlighting for long string examples in
  cmake-language.7.rst.
* No highlighting of removed syntax in CMP0049
* To inspect the outcome of this patch, see e.g. the pages
  * manual/cmake-buildsystem.7.html
  * module/ExternalProject.html
  * module/FindPkgConfig.html
  which are particularly rich in complex code snippets.

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