5 files changed, 138 insertions, 6 deletions
diff --git a/Help/command/block.rst b/Help/command/block.rst
new file mode 100644
index 0000000..f9d85c8
--- /dev/null
+++ b/Help/command/block.rst
@@ -0,0 +1,74 @@
+block
+-----
+
+.. versionadded:: 3.25
+
+Evaluate a group of commands with a dedicated variable and/or policy scope.
+
+.. code-block:: cmake
+
+  block([SCOPE_FOR (POLICIES|VARIABLES)] [PROPAGATE <var-name>...])
+    <commands>
+  endblock()
+
+All commands between ``block()`` and the matching :command:`endblock` are
+recorded without being invoked.  Once the :command:`endblock` is evaluated, the
+recorded list of commands is invoked inside the requested scopes, and, finally,
+the scopes created by ``block()`` command are removed.
+
+``SCOPE_FOR``
+  Specify which scopes must be created.
+
+  ``POLICIES``
+    Create a new policy scope. This is equivalent to
+    :command:`cmake_policy(PUSH)`.
+
+  ``VARIABLES``
+    Create a new variable scope.
+
+  If ``SCOPE_FOR`` is not specified, this is equivalent to:
+
+  .. code-block:: cmake
+
+    block(SCOPE_FOR VARIABLES POLICIES)
+
+``PROPAGATE``
+  When a variable scope is created by :command:`block` command, this option
+  set or unset the specified variables in the parent scope. This is equivalent
+  to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)` commands.
+
+  .. code-block:: cmake
+
+    set(VAR1 "INIT1")
+    set(VAR2 "INIT2")
+
+    block(PROPAGATE VAR1 VAR2)
+      set(VAR1 "VALUE1")
+      unset(VAR2)
+    endblock()
+
+    # here, VAR1 holds value VALUE1 and VAR2 is unset
+
+  This option is only allowed when a variable scope is created. An error will
+  be raised in the other cases.
+
+When the ``block`` is local to a :command:`foreach` or :command:`while`
+command, the commands :command:`break` and :command:`continue` can be used
+inside this block.
+
+.. code-block:: cmake
+
+  while(TRUE)
+    block()
+       ...
+       # the break() command will terminate the while() command
+       break()
+    endblock()
+  endwhile()
+
+
+See Also
+^^^^^^^^
+
+  * :command:`endblock`
+  * :command:`cmake_policy`
diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index d0c7c19..8801a9f 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -51,6 +51,7 @@ is equivalent to
   To ensure consistency of the code, the following commands are not allowed:
 
   * ``if`` / ``elseif`` / ``else`` / ``endif``
+  * ``block`` / ``endblock``
   * ``while`` / ``endwhile``
   * ``foreach`` / ``endforeach``
   * ``function`` / ``endfunction``
diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst
index 94060d9..54fc548 100644
--- a/Help/command/cmake_policy.rst
+++ b/Help/command/cmake_policy.rst
@@ -103,6 +103,47 @@ Calls to the :command:`cmake_minimum_required(VERSION)`,
 ``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
 influence only the current top of the policy stack.
 
+.. versionadded:: 3.25
+  The :command:`block` and :command:`endblock` commands offer a more flexible
+  and more secure way to manage the policy stack. The pop action is done
+  automatically when the :command:`endblock` command is executed, so it avoid
+  to call the :command:`cmake_policy(POP)` command before each
+  :command:`return` command.
+
+  .. code-block:: cmake
+
+    # stack management with cmake_policy()
+    function(my_func)
+      cmake_policy(PUSH)
+      cmake_policy(SET ...)
+      if (<cond1>)
+        ...
+        cmake_policy(POP)
+        return()
+      elseif(<cond2>)
+        ...
+        cmake_policy(POP)
+        return()
+      endif()
+      ...
+      cmake_policy(POP)
+    endfunction()
+
+    # stack management with block()/endblock()
+    function(my_func)
+      block(SCOPE_FOR POLICIES)
+        cmake_policy(SET ...)
+        if (<cond1>)
+          ...
+          return()
+        elseif(<cond2>)
+          ...
+          return()
+        endif()
+        ...
+      endblock()
+    endfunction()
+
 Commands created by the :command:`function` and :command:`macro`
 commands record policy settings when they are created and
 use the pre-record policies when they are invoked.  If the function or
diff --git a/Help/command/endblock.rst b/Help/command/endblock.rst
new file mode 100644
index 0000000..3b21c12
--- /dev/null
+++ b/Help/command/endblock.rst
@@ -0,0 +1,11 @@
+endblock
+--------
+
+.. versionadded:: 3.25
+
+Ends a list of commands in a :command:`block` and removes the scopes
+created by the :command:`block` command.
+
+.. code-block:: cmake
+
+  endblock()
diff --git a/Help/command/set.rst b/Help/command/set.rst
index af862e4..aa2ea55 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -22,12 +22,17 @@ Set Normal Variable
 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
-creates a new scope.  This command will set the value of a variable
-into the parent directory or calling function (whichever is applicable
-to the case at hand). The previous state of the variable's value stays the
-same in the current scope (e.g., if it was undefined before, it is still
-undefined and if it had a value, it is still that value).
+the scope above the current scope.  Each new directory or :command:`function`
+command creates a new scope.  A scope can also be created with the
+:command:`block` command. This command will set the value of a variable into
+the parent directory, calling function or encompassing scope (whichever is
+applicable to the case at hand). The previous state of the variable's value
+stays the same in the current scope (e.g., if it was undefined before, it is
+still undefined and if it had a value, it is still that value).
+
+The :command:`block(PROPAGATE)` command can be used as an alternate method to
+:command:`set(PARENT_SCOPE)` and :command:`unset(PARENT_SCOPE)` commands to
+update the parent scope.
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^