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

1 files changed, 22 insertions, 16 deletions

diff --git a/Help/command/function.rst b/Help/command/function.rst
index 7ffdfee..4a223b4 100644
--- a/Help/command/function.rst
+++ b/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.