Help: Revise docs on Scripting Commands

Revise docs for all "Scripting Commands", except four find_XXX
that use a macro suite of their own.

* Take full advantage of the improved syntax highlighting.
* Make consequential use of <..> placeholders.
* Clarify things here and there in the text.

Specific improvements to some command docs:

* "math": Correct description of novel hexadecimal capability.
* "if", "foreach", "while": Provide link to "endif" etc
* "foreach", "while": Mention "break" and "continue".
* "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures;
   advise against negative arguments or reverse ranges (compare issue #18461)
* "endif", "endfunction" etc: Explain that the argument is optional and
   maintained for compatibility only

Help/command/break.rst

@@ -3,10 +3,10 @@ break
 
 Break from an enclosing foreach or while loop.
 
-::
+.. code-block:: cmake
 
   break()
 
-Breaks from an enclosing foreach loop or while loop
+Breaks from an enclosing :command:`foreach` or :command:`while` loop.
 
 See also the :command:`continue` command.

Help/command/cmake_host_system_information.rst

@@ -3,7 +3,7 @@ cmake_host_system_information
 
 Query host system specific information.
 
-::
+.. code-block:: cmake
 
   cmake_host_system_information(RESULT <variable> QUERY <key> ...)
 

Help/command/cmake_minimum_required.rst

@@ -1,11 +1,15 @@
 cmake_minimum_required
 ----------------------
 
-Set the minimum required version of cmake for a project and
-update `Policy Settings`_ to match the version given::
+Require a minimum version of cmake.
+
+.. code-block:: cmake
 
   cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
 
+Sets the minimum required version of cmake for a project.
+Also updates the policy settings as explained below.
+
 ``<min>`` and the optional ``<max>`` are each CMake versions of the form
 ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
 
@@ -47,13 +51,17 @@ as of a given CMake version and tells newer CMake versions to warn
 about their new policies.
 
 When a ``<min>`` version higher than 2.4 is specified the command
-implicitly invokes::
+implicitly invokes
+
+.. code-block:: cmake
 
   cmake_policy(VERSION <min>[...<max>])
 
 which sets CMake policies based on the range of versions specified.
 When a ``<min>`` version 2.4 or lower is given the command implicitly
-invokes::
+invokes
+
+.. code-block:: cmake
 
   cmake_policy(VERSION 2.4[...<max>])
 

Help/command/cmake_parse_arguments.rst

@@ -1,26 +1,28 @@
 cmake_parse_arguments
 ---------------------
 
-``cmake_parse_arguments`` is intended to be used in macros or functions for
-parsing the arguments given to that macro or function.  It processes the
-arguments and defines a set of variables which hold the values of the
-respective options.
+Parse function or macro arguments.
 
-::
+.. code-block:: cmake
 
   cmake_parse_arguments(<prefix> <options> <one_value_keywords>
-                        <multi_value_keywords> args...)
+                        <multi_value_keywords> <args>...)
 
-  cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
-                        <multi_value_keywords>)
+  cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
+                        <one_value_keywords> <multi_value_keywords>)
+
+This command is for use in macros or functions.
+It processes the arguments given to that macro or function,
+and defines a set of variables which hold the values of the
+respective options.
 
-The first signature reads processes arguments passed in the ``args...``.
+The first signature reads processes arguments passed in the ``<args>...``.
 This may be used in either a :command:`macro` or a :command:`function`.
 
 The ``PARSE_ARGV`` signature is only for use in a :command:`function`
 body.  In this case the arguments that are parsed come from the
 ``ARGV#`` variables of the calling function.  The parsing starts with
-the Nth argument, where ``N`` is an unsigned integer.  This allows for
+the ``<N>``-th argument, where ``<N>`` is an unsigned integer.  This allows for
 the values to have special characters like ``;`` in them.
 
 The ``<options>`` argument contains all options for the respective macro,

Help/command/cmake_policy.rst

@@ -22,7 +22,9 @@ Setting Policies by CMake Version
 
 The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
 behavior.  While setting policies individually is supported, we
-encourage projects to set policies based on CMake versions::
+encourage projects to set policies based on CMake versions:
+
+.. code-block:: cmake
 
   cmake_policy(VERSION <min>[...<max>])
 
@@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
 Setting Policies Explicitly
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   cmake_policy(SET CMP<NNNN> NEW)
   cmake_policy(SET CMP<NNNN> OLD)
@@ -66,7 +68,7 @@ policy state to ``NEW``.
 Checking Policy Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   cmake_policy(GET CMP<NNNN> <variable>)
 
@@ -85,7 +87,9 @@ scripts loaded by :command:`include` and :command:`find_package` commands
 except when invoked with the ``NO_POLICY_SCOPE`` option
 (see also policy :policy:`CMP0011`).
 The ``cmake_policy`` command provides an interface to manage custom
-entries on the policy stack::
+entries on the policy stack:
+
+.. code-block:: cmake
 
   cmake_policy(PUSH)
   cmake_policy(POP)

Help/command/configure_file.rst

@@ -3,7 +3,7 @@ configure_file
 
 Copy a file to another location and modify its contents.
 
-::
+.. code-block:: cmake
 
   configure_file(<input> <output>
                  [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
@@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` file and substitutes
 variable values referenced as ``@VAR@`` or ``${VAR}`` in the input
 file content.  Each variable reference will be replaced with the
 current value of the variable, or the empty string if the variable
-is not defined.  Furthermore, input lines of the form::
+is not defined.  Furthermore, input lines of the form
+
+.. code-block:: c
 
   #cmakedefine VAR ...
 
-will be replaced with either::
+will be replaced with either
+
+.. code-block:: c
 
   #define VAR ...
 
-or::
+or
+
+.. code-block:: c
 
   /* #undef VAR */
 
@@ -33,12 +39,16 @@ either ``#define VAR 1`` or ``#define VAR 0`` similarly.
 The result lines (with the exception of the ``#undef`` comments) can be
 indented using spaces and/or tabs between the ``#`` character
 and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
-indentation will be preserved in the output lines::
+indentation will be preserved in the output lines:
+
+.. code-block:: c
 
   #  cmakedefine VAR
   #  cmakedefine01 VAR
 
-will be replaced, if ``VAR`` is defined, with::
+will be replaced, if ``VAR`` is defined, with
+
+.. code-block:: c
 
   #  define VAR
   #  define VAR 1

Help/command/continue.rst

@@ -3,10 +3,12 @@ continue
 
 Continue to the top of enclosing foreach or while loop.
 
-::
+.. code-block:: cmake
 
   continue()
 
 The ``continue`` command allows a cmake script to abort the rest of a block
 in a :command:`foreach` or :command:`while` loop, and start at the top of
-the next iteration.  See also the :command:`break` command.
+the next iteration.
+
+See also the :command:`break` command.

Help/command/else.rst

@@ -3,8 +3,8 @@ else
 
 Starts the else portion of an if block.
 
-::
+.. code-block:: cmake
 
-  else(expression)
+  else([<condition>])
 
 See the :command:`if` command.

Help/command/elseif.rst

@@ -1,10 +1,11 @@
 elseif
 ------
 
-Starts the elseif portion of an if block.
+Starts an elseif portion of an if block.
 
-::
+.. code-block:: cmake
 
-  elseif(expression)
+  elseif(<condition>)
 
-See the :command:`if` command.
+See the :command:`if` command, especially for the syntax and logic
+of the ``<condition>``.

Help/command/endforeach.rst

@@ -3,8 +3,12 @@ endforeach
 
 Ends a list of commands in a foreach block.
 
-::
+.. code-block:: cmake
 
-  endforeach(expression)
+  endforeach([<loop_var>])
 
 See the :command:`foreach` command.
+
+The optional ``<loop_var>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
+the opening ``foreach`` clause.

Help/command/endfunction.rst

@@ -3,8 +3,12 @@ endfunction
 
 Ends a list of commands in a function block.
 
-::
+.. code-block:: cmake
 
-  endfunction(expression)
+  endfunction([<name>])
 
 See the :command:`function` command.
+
+The optional ``<name>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the ``<name>`` argument
+of the opening ``function`` command.

Help/command/endif.rst

@@ -3,8 +3,12 @@ endif
 
 Ends a list of commands in an if block.
 
-::
+.. code-block:: cmake
 
-  endif(expression)
+  endif([<condition>])
 
 See the :command:`if` command.
+
+The optional ``<condition>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the argument of the opening
+``if`` clause.

Help/command/endmacro.rst

@@ -3,8 +3,12 @@ endmacro
 
 Ends a list of commands in a macro block.
 
-::
+.. code-block:: cmake
 
-  endmacro(expression)
+  endmacro([<name>])
 
 See the :command:`macro` command.
+
+The optional ``<name>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the ``<name>`` argument
+of the opening ``macro`` command.

Help/command/endwhile.rst

@@ -3,8 +3,12 @@ endwhile
 
 Ends a list of commands in a while block.
 
-::
+.. code-block:: cmake
 
-  endwhile(expression)
+  endwhile([<condition>])
 
 See the :command:`while` command.
+
+The optional ``<condition>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the argument of the opening
+``while`` clause.

Help/command/file.rst

@@ -42,7 +42,7 @@ Reading
 
 .. _READ:
 
-::
+.. code-block:: cmake
 
   file(READ <filename> <variable>
        [OFFSET <offset>] [LIMIT <max-in>] [HEX])
@@ -54,7 +54,7 @@ be converted to a hexadecimal representation (useful for binary data).
 
 .. _STRINGS:
 
-::
+.. code-block:: cmake
 
   file(STRINGS <filename> <variable> [<options>...])
 
@@ -105,7 +105,7 @@ from the input file.
 
 .. _HASH:
 
-::
+.. code-block:: cmake
 
   file(<HASH> <filename> <variable>)
 
@@ -116,7 +116,7 @@ command.
 
 .. _TIMESTAMP:
 
-::
+.. code-block:: cmake
 
   file(TIMESTAMP <filename> <variable> [<format>] [UTC])
 
@@ -133,7 +133,7 @@ Writing
 .. _WRITE:
 .. _APPEND:
 
-::
+.. code-block:: cmake
 
   file(WRITE <filename> <content>...)
   file(APPEND <filename> <content>...)
@@ -150,7 +150,7 @@ to update the file only when its content changes.
 .. _TOUCH:
 .. _TOUCH_NOCREATE:
 
-::
+.. code-block:: cmake
 
   file(TOUCH [<files>...])
   file(TOUCH_NOCREATE [<files>...])
@@ -167,7 +167,7 @@ modified.
 
 .. _GENERATE:
 
-::
+.. code-block:: cmake
 
   file(GENERATE OUTPUT output-file
        <INPUT input-file|CONTENT content>
@@ -217,7 +217,7 @@ Filesystem
 .. _GLOB:
 .. _GLOB_RECURSE:
 
-::
+.. code-block:: cmake
 
   file(GLOB <variable>
        [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
@@ -272,7 +272,7 @@ Examples of recursive globbing include::
 
 .. _RENAME:
 
-::
+.. code-block:: cmake
 
   file(RENAME <oldname> <newname>)
 
@@ -282,7 +282,7 @@ Move a file or directory within a filesystem from ``<oldname>`` to
 .. _REMOVE:
 .. _REMOVE_RECURSE:
 
-::
+.. code-block:: cmake
 
   file(REMOVE [<files>...])
   file(REMOVE_RECURSE [<files>...])
@@ -293,7 +293,7 @@ given file does not exist.
 
 .. _MAKE_DIRECTORY:
 
-::
+.. code-block:: cmake
 
   file(MAKE_DIRECTORY [<directories>...])
 
@@ -302,7 +302,7 @@ Create the given directories and their parents as needed.
 .. _COPY:
 .. _INSTALL:
 
-::
+.. code-block:: cmake
 
   file(<COPY|INSTALL> <files>... DESTINATION <dir>
        [FILE_PERMISSIONS <permissions>...]
@@ -338,7 +338,7 @@ Path Conversion
 
 .. _RELATIVE_PATH:
 
-::
+.. code-block:: cmake
 
   file(RELATIVE_PATH <variable> <directory> <file>)
 
@@ -348,7 +348,7 @@ store it in the ``<variable>``.
 .. _TO_CMAKE_PATH:
 .. _TO_NATIVE_PATH:
 
-::
+.. code-block:: cmake
 
   file(TO_CMAKE_PATH "<path>" <variable>)
   file(TO_NATIVE_PATH "<path>" <variable>)
@@ -370,7 +370,7 @@ Transfer
 .. _DOWNLOAD:
 .. _UPLOAD:
 
-::
+.. code-block:: cmake
 
   file(DOWNLOAD <url> <file> [<options>...])
   file(UPLOAD   <file> <url> [<options>...])
@@ -460,7 +460,7 @@ Locking
 
 .. _LOCK:
 
-::
+.. code-block:: cmake
 
   file(LOCK <path> [DIRECTORY] [RELEASE]
        [GUARD <FUNCTION|FILE|PROCESS>]

Help/command/find_package.rst

@@ -12,7 +12,7 @@ Find an external project, and load its settings.
 Basic Signature and Module Mode
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
                [REQUIRED] [[COMPONENTS] [components...]]
@@ -67,7 +67,9 @@ full command signature and details of the search process.  Project
 maintainers wishing to provide a package to be found by this command
 are encouraged to read on.
 
-The complete Config mode command signature is::
+The complete Config mode command signature is
+
+.. code-block:: cmake
 
   find_package(<PackageName> [version] [EXACT] [QUIET]
                [REQUIRED] [[COMPONENTS] [components...]]
@@ -202,7 +204,9 @@ is set no attempt is made to choose a highest or closest version number.
 To control the order in which ``find_package`` checks for compatibility use
 the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
 :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
-For instance in order to select the highest version one can set::
+For instance in order to select the highest version one can set
+
+.. code-block:: cmake
 
   SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
   SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

Help/command/foreach.rst

@@ -3,45 +3,82 @@ foreach
 
 Evaluate a group of commands for each value in a list.
 
-::
+.. code-block:: cmake
 
-  foreach(loop_var arg1 arg2 ...)
-    COMMAND1(ARGS ...)
-    COMMAND2(ARGS ...)
-    ...
-  endforeach(loop_var)
+  foreach(<loop_var> <items>)
+    <commands>
+  endforeach()
 
-All commands between foreach and the matching endforeach are recorded
-without being invoked.  Once the endforeach is evaluated, the recorded
-list of commands is invoked once for each argument listed in the
-original foreach command.  Before each iteration of the loop
-``${loop_var}`` will be set as a variable with the current value in the
-list.
+where ``<items>`` is a list of items that are separated by
+semicolon or whitespace.
+All commands between ``foreach`` and the matching ``endforeach`` are recorded
+without being invoked.  Once the ``endforeach`` is evaluated, the recorded
+list of commands is invoked once for each item in ``<items>``.
+At the beginning of each iteration the variable ``loop_var`` will be set
+to the value of the current item.
 
-::
+The commands :command:`break` and :command:`continue` provide means to
+escape from the normal control flow.
 
-  foreach(loop_var RANGE total)
-  foreach(loop_var RANGE start stop [step])
+Per legacy, the :command:`endforeach` command admits
+an optional ``<loop_var>`` argument.
+If used, it must be a verbatim
+repeat of the argument of the opening
+``foreach`` command.
 
-Foreach can also iterate over a generated range of numbers.  There are
-three types of this iteration:
+.. code-block:: cmake
 
-* When specifying single number, the range will have elements [0, ... to
-  "total"] (inclusive).
+  foreach(<loop_var> RANGE <stop>)
 
-* When specifying two numbers, the range will have elements from the
-  first number to the second number (inclusive).
+In this variant, ``foreach`` iterates over the numbers
+0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
 
-* The third optional number is the increment used to iterate from the
-  first number to the second number (inclusive).
+.. code-block:: cmake
 
-::
+  foreach(<loop_var> RANGE <start> <stop> [<step>])
+
+In this variant, ``foreach`` iterates over the numbers from
+``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
+If ``<step>`` is not specified, then the step size is 1.
+The three arguments ``<start>`` ``<stop>`` ``<step>`` must
+all be nonnegative integers, and ``<stop>`` must not be
+smaller than ``<start>``; otherwise you enter the danger zone
+of undocumented behavior that may change in future releases.
+
+.. code-block:: cmake
+
+  foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
 
-  foreach(loop_var IN [LISTS [list1 [...]]]
-                      [ITEMS [item1 [...]]])
+In this variant, ``<lists>`` is a whitespace or semicolon
+separated list of list-valued variables. The ``foreach``
+command iterates over each item in each given list.
+The ``<items>`` following the ``ITEMS`` keyword are processed
+as in the first variant of the ``foreach`` command.
+The forms ``LISTS A`` and ``ITEMS ${A}`` are
+equivalent.
+
+The following example shows how the ``LISTS`` option is
+processed:
+
+.. code-block:: cmake
+
+  set(A 0;1)
+  set(B 2 3)
+  set(C "4 5")
+  set(D 6;7 8)
+  set(E "")
+  foreach(X IN LISTS A B C D E)
+      message(STATUS "X=${X}")
+  endforeach()
+
+yields
+::
 
-Iterates over a precise list of items.  The ``LISTS`` option names
-list-valued variables to be traversed, including empty elements (an
-empty string is a zero-length list).  (Note macro
-arguments are not variables.)  The ``ITEMS`` option ends argument
-parsing and includes all arguments following it in the iteration.
+  -- X=0
+  -- X=1
+  -- X=2
+  -- X=3
+  -- X=4 5
+  -- X=6
+  -- X=7
+  -- X=8

Help/command/function.rst

@@ -1,27 +1,29 @@
 function
 --------
 
-Start recording a function for later invocation as a command::
-
-  function(<name> [arg1 [arg2 [arg3 ...]]])
-    COMMAND1(ARGS ...)
-    COMMAND2(ARGS ...)
-    ...
-  endfunction(<name>)
-
-Define a function named ``<name>`` that takes arguments named ``arg1``,
-``arg2``, ``arg3``, (...).
-Commands listed after function, but before the matching
-:command:`endfunction()`, are not invoked until the function is invoked.
-When it is invoked, the commands recorded in the function are first
-modified by replacing formal parameters (``${arg1}``) with the arguments
-passed, and then invoked as normal commands.
+Start recording a function for later invocation as a command.
+
+.. code-block:: cmake
+
+  function(<name> [<arg1> ...])
+    <commands>
+  endfunction()
+
+Defines a function named ``<name>`` that takes arguments
+named ``<arg1>``, ...
+The ``<commands>`` in the function definition are recorded;
+they are not invoked until the function is invoked. When
+the function is invoked, the recorded ``<commands>`` are first
+modified by replacing formal parameters (``${arg1}``, ...)
+with the arguments passed, and then invoked as normal commands.
+
 In addition to referencing the formal parameters you can reference the
 ``ARGC`` variable which will be set to the number of arguments passed
 into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ...  which
 will have the actual values of the arguments passed in.
 This facilitates creating functions with optional arguments.
-Additionally ``ARGV`` holds the list of all arguments given to the
+
+Furthermore, ``ARGV`` holds the list of all arguments given to the
 function and ``ARGN`` holds the list of arguments past the last expected
 argument.
 Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
@@ -29,6 +31,10 @@ behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
 to ensure that ``ARGV#`` was passed to the function as an extra
 argument.
 
+Per legacy, the :command:`endfunction` command admits an optional
+``<name>`` argument. If used, it must be a verbatim repeat of the
+argument of the opening ``function`` command.
+
 A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
 details.
 

Help/command/get_cmake_property.rst

@@ -3,14 +3,14 @@ get_cmake_property
 
 Get a global property of the CMake instance.
 
-::
+.. code-block:: cmake
 
-  get_cmake_property(VAR property)
+  get_cmake_property(<var> <property>)
 
-Get a global property from the CMake instance.  The value of the property is
-stored in the variable ``VAR``.  If the property is not found, ``VAR``
-will be  set to "NOTFOUND".  See the :manual:`cmake-properties(7)` manual
-for available properties.
+Gets a global property from the CMake instance.  The value of
+the ``<property>`` is stored in the variable ``<var>``.
+If the property is not found, ``<var>`` will be set to ``"NOTFOUND"``.
+See the :manual:`cmake-properties(7)` manual for available properties.
 
 See also the :command:`get_property` command ``GLOBAL`` option.
 

Help/command/get_directory_property.rst

@@ -3,11 +3,11 @@ get_directory_property
 
 Get a property of ``DIRECTORY`` scope.
 
-::
+.. code-block:: cmake
 
   get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
 
-Store a property of directory scope in the named ``<variable>``.
+Stores a property of directory scope in the named ``<variable>``.
 The ``DIRECTORY`` argument specifies another directory from which
 to retrieve the property value instead of the current directory.
 The specified directory must have already been traversed by CMake.
@@ -18,7 +18,7 @@ if the property is not found for the nominated directory scope,
 the search will chain to a parent scope as described for the
 :command:`define_property` command.
 
-::
+.. code-block:: cmake
 
   get_directory_property(<variable> [DIRECTORY <dir>]
                          DEFINITION <var-name>)

Help/command/get_filename_component.rst

@@ -3,13 +3,11 @@ get_filename_component
 
 Get a specific component of a full filename.
 
-------------------------------------------------------------------------------
+.. code-block:: cmake
 
-::
-
-  get_filename_component(<VAR> <FileName> <COMP> [CACHE])
+  get_filename_component(<var> <FileName> <mode> [CACHE])
 
-Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
+Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
 
 ::
 
@@ -24,15 +22,11 @@ The longest file extension is always considered.  If the optional
 ``CACHE`` argument is specified, the result variable is added to the
 cache.
 
-------------------------------------------------------------------------------
-
-::
+.. code-block:: cmake
 
-  get_filename_component(<VAR> <FileName>
-                         <COMP> [BASE_DIR <BASE_DIR>]
-                         [CACHE])
+  get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
 
-Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one
+Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
 of:
 
 ::
@@ -41,7 +35,7 @@ of:
  REALPATH  = Full path to existing file with symlinks resolved
 
 If the provided ``<FileName>`` is a relative path, it is evaluated relative
-to the given base directory ``<BASE_DIR>``.  If no base directory is
+to the given base directory ``<dir>``.  If no base directory is
 provided, the default base directory will be
 :variable:`CMAKE_CURRENT_SOURCE_DIR`.
 
@@ -49,16 +43,12 @@ Paths are returned with forward slashes and have no trailing slashes.  If the
 optional ``CACHE`` argument is specified, the result variable is added to the
 cache.
 
-------------------------------------------------------------------------------
-
-::
+.. code-block:: cmake
 
-  get_filename_component(<VAR> <FileName>
-                         PROGRAM [PROGRAM_ARGS <ARG_VAR>]
-                         [CACHE])
+  get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
 
 The program in ``<FileName>`` will be found in the system search path or
 left as a full path.  If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
 any command-line arguments present in the ``<FileName>`` string are split
-from the program name and stored in ``<ARG_VAR>``.  This is used to
+from the program name and stored in ``<arg_var>``.  This is used to
 separate a program name from its arguments in a command line string.

Help/command/get_property.rst

@@ -3,32 +3,33 @@ get_property
 
 Get a property.
 
-::
+.. code-block:: cmake
 
   get_property(<variable>
                <GLOBAL             |
-                DIRECTORY [dir]    |
+                DIRECTORY [<dir>]  |
                 TARGET    <target> |
                 SOURCE    <source> |
                 INSTALL   <file>   |
                 TEST      <test>   |
                 CACHE     <entry>  |
-                VARIABLE>
+                VARIABLE           >
                PROPERTY <name>
                [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
 
-Get one property from one object in a scope.  The first argument
-specifies the variable in which to store the result.  The second
-argument determines the scope from which to get the property.  It must
-be one of the following:
+Gets one property from one object in a scope.
+
+The first argument specifies the variable in which to store the result.
+The second argument determines the scope from which to get the property.
+It must be one of the following:
 
 ``GLOBAL``
   Scope is unique and does not accept a name.
 
 ``DIRECTORY``
   Scope defaults to the current directory but another
-  directory (already processed by CMake) may be named by full or
-  relative path.
+  directory (already processed by CMake) may be named by the
+  full or relative path ``<dir>``.
 
 ``TARGET``
   Scope must name one existing target.
@@ -58,6 +59,7 @@ value indicating whether the property has been set.  If the ``DEFINED``
 option is given the variable is set to a boolean value indicating
 whether the property has been defined such as with the
 :command:`define_property` command.
+
 If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
 string containing documentation for the requested property.  If
 documentation is requested for a property that has not been defined

Help/command/if.rst

@@ -6,7 +6,7 @@ Conditionally execute a group of commands.
 Synopsis
 ^^^^^^^^
 
-::
+.. code-block:: cmake
 
   if(<condition>)
     <commands>
@@ -23,8 +23,11 @@ Otherwise, optional ``elseif`` blocks are processed in the same way.
 Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
 block are executed.
 
-Per legacy, the ``else`` and ``endif`` clause may also have a ``condition`` argument,
-which then must be a verbatim repeat of the argument of the opening ``if`` clause.
+Per legacy, the :command:`else` and :command:`elseif` commands admit
+an optional ``<condition>`` argument.
+If used, it must be a verbatim
+repeat of the argument of the opening
+``if`` command.
 
 Condition Syntax
 ^^^^^^^^^^^^^^^^
@@ -202,21 +205,27 @@ The if command was written very early in CMake's history, predating
 the ``${}`` variable evaluation syntax, and for convenience evaluates
 variables named by its arguments as shown in the above signatures.
 Note that normal variable evaluation with ``${}`` applies before the if
-command even receives the arguments.  Therefore code like::
+command even receives the arguments.  Therefore code like
+
+.. code-block:: cmake
 
  set(var1 OFF)
  set(var2 "var1")
  if(${var2})
 
-appears to the if command as::
+appears to the if command as
+
+.. code-block:: cmake
 
- if(var1)
+  if(var1)
 
 and is evaluated according to the ``if(<variable>)`` case documented
 above.  The result is ``OFF`` which is false.  However, if we remove the
-``${}`` from the example then the command sees::
+``${}`` from the example then the command sees
+
+.. code-block:: cmake
 
- if(var2)
+  if(var2)
 
 which is true because ``var2`` is defined to "var1" which is not a false
 constant.

Help/command/include.rst

@@ -3,16 +3,16 @@ include
 
 Load and run CMake code from a file or module.
 
-::
+.. code-block:: cmake
 
-  include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
+  include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
                         [NO_POLICY_SCOPE])
 
-Load and run CMake code from the file given.  Variable reads and
+Loads and runs CMake code from the file given.  Variable reads and
 writes access the scope of the caller (dynamic scoping).  If ``OPTIONAL``
 is present, then no error is raised if the file does not exist.  If
-``RESULT_VARIABLE`` is given the variable will be set to the full filename
-which has been included or NOTFOUND if it failed.
+``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
+full filename which has been included or ``NOTFOUND`` if it failed.
 
 If a module is specified instead of a file, the file with name
 ``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,

Help/command/include_guard.rst

@@ -3,7 +3,7 @@ include_guard
 
 Provides an include guard for the file currently being processed by CMake.
 
-::
+.. code-block:: cmake
 
   include_guard([DIRECTORY|GLOBAL])
 

Help/command/list.rst

@@ -64,7 +64,7 @@ Reading
 
 .. _LENGTH:
 
-::
+.. code-block:: cmake
 
   list(LENGTH <list> <output variable>)
 
@@ -72,7 +72,7 @@ Returns the list's length.
 
 .. _GET:
 
-::
+.. code-block:: cmake
 
   list(GET <list> <element index> [<element index> ...] <output variable>)
 
@@ -80,7 +80,7 @@ Returns the list of elements specified by indices from the list.
 
 .. _JOIN:
 
-::
+.. code-block:: cmake
 
   list(JOIN <list> <glue> <output variable>)
 
@@ -90,7 +90,7 @@ from :command:`string` command.
 
 .. _SUBLIST:
 
-::
+.. code-block:: cmake
 
   list(SUBLIST <list> <begin> <length> <output variable>)
 
@@ -104,7 +104,7 @@ Search
 
 .. _FIND:
 
-::
+.. code-block:: cmake
 
   list(FIND <list> <value> <output variable>)
 
@@ -116,7 +116,7 @@ Modification
 
 .. _APPEND:
 
-::
+.. code-block:: cmake
 
   list(APPEND <list> [<element> ...])
 
@@ -124,7 +124,7 @@ Appends elements to the list.
 
 .. _FILTER:
 
-::
+.. code-block:: cmake
 
   list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
 
@@ -136,7 +136,7 @@ For more information on regular expressions see also the
 
 .. _INSERT:
 
-::
+.. code-block:: cmake
 
   list(INSERT <list> <element_index> <element> [<element> ...])
 
@@ -144,7 +144,7 @@ Inserts elements to the list to the specified location.
 
 .. _REMOVE_ITEM:
 
-::
+.. code-block:: cmake
 
   list(REMOVE_ITEM <list> <value> [<value> ...])
 
@@ -152,7 +152,7 @@ Removes the given items from the list.
 
 .. _REMOVE_AT:
 
-::
+.. code-block:: cmake
 
   list(REMOVE_AT <list> <index> [<index> ...])
 
@@ -160,7 +160,7 @@ Removes items at given indices from the list.
 
 .. _REMOVE_DUPLICATES:
 
-::
+.. code-block:: cmake
 
   list(REMOVE_DUPLICATES <list>)
 
@@ -168,7 +168,7 @@ Removes duplicated items in the list.
 
 .. _TRANSFORM:
 
-::
+.. code-block:: cmake
 
   list(TRANSFORM <list> <ACTION> [<SELECTOR>]
                         [OUTPUT_VARIABLE <output variable>])
@@ -190,30 +190,40 @@ The actions have exactly the same semantics as sub-commands of
 The ``<ACTION>`` may be one of:
 
 ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
-the list. ::
+the list.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
 
 ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
-characters. ::
+characters.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
 
 ``STRIP``: Remove leading and trailing spaces from each element of the
-list. ::
+list.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> STRIP ...)
 
 ``GENEX_STRIP``: Strip any
 :manual:`generator expressions <cmake-generator-expressions(7)>` from each
-element of the list. ::
+element of the list.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> GENEX_STRIP ...)
 
 ``REPLACE``: Match the regular expression as many times as possible and
 substitute the replacement expression for the match for each element
 of the list
-(Same semantic as ``REGEX REPLACE`` from :command:`string` command). ::
+(Same semantic as ``REGEX REPLACE`` from :command:`string` command).
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> REPLACE <regular_expression>
                                 <replace_expression> ...)
@@ -223,17 +233,23 @@ type of selector can be specified at a time.
 
 The ``<SELECTOR>`` may be one of:
 
-``AT``: Specify a list of indexes. ::
+``AT``: Specify a list of indexes.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
 
 ``FOR``: Specify a range with, optionally, an increment used to iterate over
-the range. ::
+the range.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
 
 ``REGEX``: Specify a regular expression. Only elements matching the regular
-expression will be transformed. ::
+expression will be transformed.
+
+.. code-block:: cmake
 
   list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
 
@@ -243,7 +259,7 @@ Ordering
 
 .. _REVERSE:
 
-::
+.. code-block:: cmake
 
   list(REVERSE <list>)
 
@@ -251,7 +267,7 @@ Reverses the contents of the list in-place.
 
 .. _SORT:
 
-::
+.. code-block:: cmake
 
   list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
 

Help/command/macro.rst

@@ -1,27 +1,29 @@
 macro
 -----
 
-Start recording a macro for later invocation as a command::
+Start recording a macro for later invocation as a command
 
-  macro(<name> [arg1 [arg2 [arg3 ...]]])
-    COMMAND1(ARGS ...)
-    COMMAND2(ARGS ...)
-    ...
+.. code-block:: cmake
+
+  macro(<name> [<arg1> ...])
+    <commands>
   endmacro(<name>)
 
-Define a macro named ``<name>`` that takes arguments named ``arg1``,
-``arg2``, ``arg3``, (...).
+Defines a macro named ``<name>`` that takes arguments
+named ``<arg1>``, ...
 Commands listed after macro, but before the matching
 :command:`endmacro()`, are not invoked until the macro is invoked.
 When it is invoked, the commands recorded in the macro are first
-modified by replacing formal parameters (``${arg1}``) with the arguments
-passed, and then invoked as normal commands.
+modified by replacing formal parameters (``${arg1}``, ...)
+with the arguments passed, and then invoked as normal commands.
+
 In addition to referencing the formal parameters you can reference the
 values ``${ARGC}`` which will be set to the number of arguments passed
 into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
 ...  which will have the actual values of the arguments passed in.
 This facilitates creating macros with optional arguments.
-Additionally ``${ARGV}`` holds the list of all arguments given to the
+
+Furthermore, ``${ARGV}`` holds the list of all arguments given to the
 macro and ``${ARGN}`` holds the list of arguments past the last expected
 argument.
 Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
@@ -38,7 +40,9 @@ Macro Argument Caveats
 Note that the parameters to a macro and values such as ``ARGN`` are
 not variables in the usual CMake sense.  They are string
 replacements much like the C preprocessor would do with a macro.
-Therefore you will NOT be able to use commands like::
+Therefore you will NOT be able to use commands like
+
+.. code-block:: cmake
 
  if(ARGV1) # ARGV1 is not a variable
  if(DEFINED ARGV2) # ARGV2 is not a variable
@@ -50,18 +54,22 @@ In the second and third case, the proper way to check if an optional
 variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
 In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
 will skip empty arguments.
-If you need to include them, you can use::
+If you need to include them, you can use
+
+.. code-block:: cmake
 
  set(list_var "${ARGN}")
  foreach(loop_var IN LISTS list_var)
 
 Note that if you have a variable with the same name in the scope from
 which the macro is called, using unreferenced names will use the
-existing variable instead of the arguments. For example::
+existing variable instead of the arguments. For example:
+
+.. code-block:: cmake
 
  macro(_BAR)
    foreach(arg IN LISTS ARGN)
-     [...]
+     <commands>
    endforeach()
  endmacro()
 

Help/command/mark_as_advanced.rst

@@ -3,17 +3,22 @@ mark_as_advanced
 
 Mark cmake cached variables as advanced.
 
-::
+.. code-block:: cmake
 
-  mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])
+  mark_as_advanced([CLEAR|FORCE] <var1> ...)
 
-Mark the named cached variables as advanced.  An advanced variable
-will not be displayed in any of the cmake GUIs unless the show
-advanced option is on.  If ``CLEAR`` is the first argument advanced
-variables are changed back to unadvanced.  If ``FORCE`` is the first
-argument, then the variable is made advanced.  If neither ``FORCE`` nor
-``CLEAR`` is specified, new values will be marked as advanced, but if the
-variable already has an advanced/non-advanced state, it will not be
-changed.
+Sets the advanced/non-advanced state of the named
+cached variables.
 
-It does nothing in script mode.
+An advanced variable will not be displayed in any
+of the cmake GUIs unless the ``show advanced`` option is on.
+In script mode, the advanced/non-advanced state has no effect.
+
+If the keyword ``CLEAR`` is given
+then advanced variables are changed back to unadvanced.
+If the keyword ``FORCE`` is given
+then the variables are made advanced.
+If neither ``FORCE`` nor ``CLEAR`` is specified,
+new values will be marked as advanced, but if a
+variable already has an advanced/non-advanced state,
+it will not be changed.

Help/command/math.rst

@@ -1,30 +1,36 @@
 math
 ----
 
-Mathematical expressions.
+Evaluate a mathematical expression.
 
-::
+.. code-block:: cmake
 
-  math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>])
+  math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
 
-``EXPR`` evaluates mathematical expression and returns result in the
-output variable.  Example mathematical expression is ``5 * (10 + 13)``.
+Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
+resulting value.
+
+The mathematical expression must be given as a string (i.e. enclosed in
+double quotation marks). An example is ``"5 * (10 + 13)"``.
 Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
-``^``, ``~``, ``<<``, ``>>``, and ``(...)``.  They have the same meaning
-as they do in C code.
+``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
+as in C code.
+
+Hexadecimal numbers are recognized when prefixed with "0x", as in C code.
 
-Numeric constants are evaluated in decimal or hexadecimal representation.
+The result is formatted according to the option ``OUTPUT_FORMAT``,
+where ``<format>`` is one of
 
-The result is formatted according to the option "OUTPUT_FORMAT" ,
-where ``<format>`` is one of:
-::
+``HEXADECIMAL``
+  Hexadecimal notation as in C code, i. e. starting with "0x".
+``DECIMAL``
+  Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option
+  is specified.
 
- HEXADECIMAL = Result in output variable will be formatted in C code
- Hexadecimal notation.
- DECIMAL = Result in output variable will be formatted in decimal notation.
 
+For example
 
-For example::
+.. code-block:: cmake
 
-  math(EXPR value "100 * 0xA" DECIMAL)  results in value is set to "1000"
-  math(EXPR value "100 * 0xA" HEXADECIMAL)  results in value is set to "0x3e8"
+  math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL)      # value is set to "1000"
+  math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL)  # value is set to "0x3e8"

Help/command/message.rst

@@ -3,7 +3,7 @@ message
 
 Display a message to the user.
 
-::
+.. code-block:: cmake
 
   message([<mode>] "message to display" ...)
 

Help/command/option.rst

@@ -1,17 +1,16 @@
 option
 ------
 
-Provides an option that the user can optionally select.
+Provide an option that the user can optionally select.
 
-::
+.. code-block:: cmake
 
-  option(<option_variable> "help string describing option"
-         [initial value])
+  option(<variable> "<help_text>" [value])
 
-Provide an option for the user to select as ``ON`` or ``OFF``.  If no
-initial value is provided, ``OFF`` is used.  If the option is already
-set as a normal variable then the command does nothing
-(see policy :policy:`CMP0077`).
+Provides an option for the user to select as ``ON`` or ``OFF``.
+If no initial ``<value>`` is provided, ``OFF`` is used.
+If ``<variable>`` is already set as a normal variable
+then the command does nothing (see policy :policy:`CMP0077`).
 
 If you have options that depend on the values of other options, see
 the module help for :module:`CMakeDependentOption`.

Help/command/return.rst

@@ -3,7 +3,7 @@ return
 
 Return from a file, directory or function.
 
-::
+.. code-block:: cmake
 
   return()
 
@@ -14,5 +14,6 @@ and control is returned to the including file.  If it is encountered in a
 file which is not included by another file, e.g.  a ``CMakeLists.txt``,
 control is returned to the parent directory if there is one.  If return is
 called in a function, control is returned to the caller of the function.
-Note that a macro is not a function and does not handle return like a
-function does.
+
+Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
+is expanded in place and therefore cannot handle ``return()``.

Help/command/separate_arguments.rst

@@ -1,33 +1,43 @@
 separate_arguments
 ------------------
 
-Parse space-separated arguments into a semicolon-separated list.
+Parse command-line arguments into a semicolon-separated list.
 
-::
+.. code-block:: cmake
 
-  separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>")
+  separate_arguments(<variable> <mode> <args>)
 
-Parses a UNIX- or Windows-style command-line string "<args>" and
-stores a semicolon-separated list of the arguments in ``<var>``.  The
-entire command line must be given in one "<args>" argument.
+Parses a space-separated string ``<args>`` into a list of items,
+and stores this list in semicolon-separated standard form in ``<variable>``.
 
-The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace.  It
-recognizes both single-quote and double-quote pairs.  A backslash
-escapes the next literal character (``\"`` is ``"``); there are no special
-escapes (``\n`` is just ``n``).
+This function is intended for parsing command-line arguments.
+The entire command line must be passed as one string in the
+argument ``<args>``.
 
-The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same
-syntax the runtime library uses to construct argv at startup.  It
-separates arguments by whitespace that is not double-quoted.
-Backslashes are literal unless they precede double-quotes.  See the
-MSDN article `Parsing C Command-Line Arguments`_ for details.
+The exact parsing rules depend on the operating system.
+They are specified by the ``<mode>`` argument which must
+be one of the following keywords:
 
-The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host
-system is Windows, and a UNIX command-line otherwise.
+``UNIX_COMMAND``
+  Arguments are separated by by unquoted whitespace.
+  Both single-quote and double-quote pairs are respected.
+  A backslash escapes the next literal character (``\"`` is ``"``);
+  there are no special escapes (``\n`` is just ``n``).
+
+``WINDOWS_COMMAND``
+  A Windows command-line is parsed using the same
+  syntax the runtime library uses to construct argv at startup.  It
+  separates arguments by whitespace that is not double-quoted.
+  Backslashes are literal unless they precede double-quotes.  See the
+  MSDN article `Parsing C Command-Line Arguments`_ for details.
+
+``NATIVE_COMMAND``
+  Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows.
+  Otherwise proceeds as in ``UNIX_COMMAND`` mode.
 
 .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
 
-::
+.. code-block:: cmake
 
   separate_arguments(<var>)
 

Help/command/set.rst

@@ -15,11 +15,11 @@ unset.  See the :command:`unset` command to unset variables explicitly.
 Set Normal Variable
 ^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   set(<variable> <value>... [PARENT_SCOPE])
 
-Set the given ``<variable>`` in the current function or directory scope.
+Sets the given ``<variable>`` in the current function or directory scope.
 
 If the ``PARENT_SCOPE`` option is given the variable will be set in
 the scope above the current scope.  Each new directory or function
@@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value).
 Set Cache Entry
 ^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   set(<variable> <value>... CACHE <type> <docstring> [FORCE])
 
-Set the given cache ``<variable>`` (cache entry).  Since cache entries
+Sets the given cache ``<variable>`` (cache entry).  Since cache entries
 are meant to provide user-settable values this does not overwrite
 existing cache entries by default.  Use the ``FORCE`` option to
 overwrite existing entries.
@@ -84,8 +84,8 @@ current working directory and convert it to an absolute path.
 Set Environment Variable
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   set(ENV{<variable>} <value>...)
 
-Set the current process environment ``<variable>`` to the given value.
+Sets the current process environment ``<variable>`` to the given value.

Help/command/set_directory_properties.rst

@@ -1,11 +1,13 @@
 set_directory_properties
 ------------------------
 
-Set properties of the current directory and subdirectories in key-value pairs.
+Set properties of the current directory and subdirectories.
 
-::
+.. code-block:: cmake
 
-  set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
+  set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
+
+Sets properties of the current directory and its subdirectories in key-value pairs.
 
 See :ref:`Directory Properties` for the list of properties known to CMake
 and their individual documentation for the behavior of each property.

Help/command/set_property.rst

@@ -3,21 +3,22 @@ set_property
 
 Set a named property in a given scope.
 
-::
-
-  set_property(<GLOBAL                            |
-                DIRECTORY [dir]                   |
-                TARGET    [target1 [target2 ...]] |
-                SOURCE    [src1 [src2 ...]]       |
-                INSTALL   [file1 [file2 ...]]     |
-                TEST      [test1 [test2 ...]]     |
-                CACHE     [entry1 [entry2 ...]]>
+.. code-block:: cmake
+
+  set_property(<GLOBAL                      |
+                DIRECTORY [<dir>]           |
+                TARGET    [<target1> ...]   |
+                SOURCE    [<src1> ...]      |
+                INSTALL   [<file1> ...]     |
+                TEST      [<test1> ...]     |
+                CACHE     [<entry1> ...]    >
                [APPEND] [APPEND_STRING]
-               PROPERTY <name> [value1 [value2 ...]])
+               PROPERTY <name> [value1 ...])
 
-Set one property on zero or more objects of a scope.  The first
-argument determines the scope in which the property is set.  It must
-be one of the following:
+Sets one property on zero or more objects of a scope.
+
+The first argument determines the scope in which the property is set.
+It must be one of the following:
 
 ``GLOBAL``
   Scope is unique and does not accept a name.

Help/command/site_name.rst

@@ -3,6 +3,6 @@ site_name
 
 Set the given variable to the name of the computer.
 
-::
+.. code-block:: cmake
 
   site_name(variable)

Help/command/string.rst

@@ -48,7 +48,7 @@ Search and Replace
 
 .. _FIND:
 
-::
+.. code-block:: cmake
 
   string(FIND <string> <substring> <output variable> [REVERSE])
 
@@ -59,7 +59,7 @@ substring.  If the substring is not found, a position of -1 is returned.
 
 .. _REPLACE:
 
-::
+.. code-block:: cmake
 
   string(REPLACE <match_string>
          <replace_string> <output variable>
@@ -73,7 +73,7 @@ Regular Expressions
 
 .. _`REGEX MATCH`:
 
-::
+.. code-block:: cmake
 
   string(REGEX MATCH <regular_expression>
          <output variable> <input> [<input>...])
@@ -83,7 +83,7 @@ All ``<input>`` arguments are concatenated before matching.
 
 .. _`REGEX MATCHALL`:
 
-::
+.. code-block:: cmake
 
   string(REGEX MATCHALL <regular_expression>
          <output variable> <input> [<input>...])
@@ -94,7 +94,7 @@ All ``<input>`` arguments are concatenated before matching.
 
 .. _`REGEX REPLACE`:
 
-::
+.. code-block:: cmake
 
   string(REGEX REPLACE <regular_expression>
          <replace_expression> <output variable>
@@ -177,7 +177,7 @@ Manipulation
 
 .. _APPEND:
 
-::
+.. code-block:: cmake
 
   string(APPEND <string variable> [<input>...])
 
@@ -185,7 +185,7 @@ Append all the input arguments to the string.
 
 .. _PREPEND:
 
-::
+.. code-block:: cmake
 
   string(PREPEND <string variable> [<input>...])
 
@@ -193,7 +193,7 @@ Prepend all the input arguments to the string.
 
 .. _CONCAT:
 
-::
+.. code-block:: cmake
 
   string(CONCAT <output variable> [<input>...])
 
@@ -202,7 +202,7 @@ the result in the named output variable.
 
 .. _JOIN:
 
-::
+.. code-block:: cmake
 
   string(JOIN <glue> <output variable> [<input>...])
 
@@ -215,7 +215,7 @@ special characters like ``;`` in them.
 
 .. _TOLOWER:
 
-::
+.. code-block:: cmake
 
   string(TOLOWER <string1> <output variable>)
 
@@ -223,7 +223,7 @@ Convert string to lower characters.
 
 .. _TOUPPER:
 
-::
+.. code-block:: cmake
 
   string(TOUPPER <string1> <output variable>)
 
@@ -231,7 +231,7 @@ Convert string to upper characters.
 
 .. _LENGTH:
 
-::
+.. code-block:: cmake
 
   string(LENGTH <string> <output variable>)
 
@@ -239,7 +239,7 @@ Store in an output variable a given string's length.
 
 .. _SUBSTRING:
 
-::
+.. code-block:: cmake
 
   string(SUBSTRING <string> <begin> <length> <output variable>)
 
@@ -253,7 +253,7 @@ If string is shorter than length then end of string is used instead.
 
 .. _STRIP:
 
-::
+.. code-block:: cmake
 
   string(STRIP <string> <output variable>)
 
@@ -262,7 +262,7 @@ trailing spaces removed.
 
 .. _GENEX_STRIP:
 
-::
+.. code-block:: cmake
 
   string(GENEX_STRIP <input string> <output variable>)
 
@@ -274,7 +274,7 @@ Comparison
 
 .. _COMPARE:
 
-::
+.. code-block:: cmake
 
   string(COMPARE LESS <string1> <string2> <output variable>)
   string(COMPARE GREATER <string1> <string2> <output variable>)
@@ -292,7 +292,7 @@ Hashing
 
 .. _`HASH`:
 
-::
+.. code-block:: cmake
 
   string(<HASH> <output variable> <input>)
 
@@ -325,7 +325,7 @@ Generation
 
 .. _ASCII:
 
-::
+.. code-block:: cmake
 
   string(ASCII <number> [<number> ...] <output variable>)
 
@@ -333,7 +333,7 @@ Convert all numbers into corresponding ASCII characters.
 
 .. _CONFIGURE:
 
-::
+.. code-block:: cmake
 
   string(CONFIGURE <string1> <output variable>
          [@ONLY] [ESCAPE_QUOTES])
@@ -342,7 +342,7 @@ Transform a string like :command:`configure_file` transforms a file.
 
 .. _MAKE_C_IDENTIFIER:
 
-::
+.. code-block:: cmake
 
   string(MAKE_C_IDENTIFIER <input string> <output variable>)
 
@@ -353,7 +353,7 @@ the result.
 
 .. _RANDOM:
 
-::
+.. code-block:: cmake
 
   string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
          [RANDOM_SEED <seed>] <output variable>)
@@ -366,7 +366,7 @@ random number generator.
 
 .. _TIMESTAMP:
 
-::
+.. code-block:: cmake
 
   string(TIMESTAMP <output variable> [<format string>] [UTC])
 
@@ -421,7 +421,7 @@ If no explicit ``<format string>`` is given it will default to:
 
 .. _UUID:
 
-::
+.. code-block:: cmake
 
   string(UUID <output variable> NAMESPACE <namespace> NAME <name>
          TYPE <MD5|SHA1> [UPPER])

Help/command/unset.rst

@@ -3,7 +3,7 @@ unset
 
 Unset a variable, cache variable, or environment variable.
 
-::
+.. code-block:: cmake
 
   unset(<variable> [CACHE | PARENT_SCOPE])
 
@@ -24,7 +24,7 @@ for further details.
 
 ``<variable>`` can be an environment variable such as:
 
-::
+.. code-block:: cmake
 
   unset(ENV{LD_LIBRARY_PATH})
 

Help/command/variable_watch.rst

@@ -3,11 +3,13 @@ variable_watch
 
 Watch the CMake variable for change.
 
-::
+.. code-block:: cmake
 
-  variable_watch(<variable name> [<command to execute>])
+  variable_watch(<variable> [<command>])
 
-If the specified variable changes, the message will be printed about
-the variable being changed.  If the command is specified, the command
-will be executed.  The command will receive the following arguments:
-COMMAND(<variable> <access> <value> <current list file> <stack>)
+If the specified ``<variable>`` changes, a message will be printed
+to inform about the change.
+
+Additionally, if ``<command>`` is given, this command will be executed.
+The command will receive the following arguments:
+``COMMAND(<variable> <access> <value> <current_list_file> <stack>)``

Help/command/while.rst

@@ -3,15 +3,23 @@ while
 
 Evaluate a group of commands while a condition is true
 
-::
+.. code-block:: cmake
 
-  while(condition)
-    COMMAND1(ARGS ...)
-    COMMAND2(ARGS ...)
-    ...
-  endwhile(condition)
+  while(<condition>)
+    <commands>
+  endwhile()
 
 All commands between while and the matching :command:`endwhile` are recorded
 without being invoked.  Once the :command:`endwhile` is evaluated, the
-recorded list of commands is invoked as long as the condition is true.  The
-condition is evaluated using the same logic as the :command:`if` command.
+recorded list of commands is invoked as long as the ``<condition>`` is true.
+
+The ``<condition>`` has the same syntax and is evaluated using the same logic
+as described at length for the :command:`if` command.
+
+The commands :command:`break` and :command:`continue` provide means to
+escape from the normal control flow.
+
+Per legacy, the :command:`endwhile` command admits
+an optional ``<condition>`` argument.
+If used, it must be a verbatim repeat of the argument of the opening
+``while`` command.