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, 68 insertions, 31 deletions

diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst
index 106ba73..ae2afb2 100644
--- a/Help/command/foreach.rst
+++ b/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