Merge topic 'scripting-commands'

c2efb3efcd Help: Revise docs on Scripting Commands

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2504

1 files changed, 16 insertions, 8 deletions

diff --git a/Help/command/while.rst b/Help/command/while.rst
index 7509da3..a4957c1 100644
--- a/Help/command/while.rst
+++ b/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.