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, 23 insertions, 17 deletions

diff --git a/Help/command/math.rst b/Help/command/math.rst
index 63af931..4fa55f6 100644
--- a/Help/command/math.rst
+++ b/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"