separate_arguments: add option PROGRAM

Fixes: #21217

3 files changed, 42 insertions, 7 deletions

diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst
index e8c68b2..1d93709 100644
--- a/Help/command/get_filename_component.rst
+++ b/Help/command/get_filename_component.rst
@@ -44,12 +44,6 @@ Paths are returned with forward slashes and have no trailing slashes.  If the
 optional ``CACHE`` argument is specified, the result variable is added to the
 cache.
 
-.. note::
-
-  All previous sub-commands has been superseded by
-  :command:`cmake_path` command, except ``REALPATH`` now offered by
-  :ref:`file(REAL_PATH) <REAL_PATH>` command.
-
 .. code-block:: cmake
 
   get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
@@ -59,3 +53,9 @@ left as a full path.  If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
 any command-line arguments present in the ``<FileName>`` string are split
 from the program name and stored in ``<arg_var>``.  This is used to
 separate a program name from its arguments in a command line string.
+
+.. note::
+
+  This command been superseded by :command:`cmake_path` command, except
+  ``REALPATH`` now offered by :ref:`file(REAL_PATH) <REAL_PATH>` command and
+  ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command.
diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst
index ab3d5c1..3c094aa 100644
--- a/Help/command/separate_arguments.rst
+++ b/Help/command/separate_arguments.rst
@@ -5,7 +5,7 @@ Parse command-line arguments into a semicolon-separated list.
 
 .. code-block:: cmake
 
-  separate_arguments(<variable> <mode> <args>)
+  separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
 
 Parses a space-separated string ``<args>`` into a list of items,
 and stores this list in semicolon-separated standard form in ``<variable>``.
@@ -35,6 +35,36 @@ be one of the following keywords:
   Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows.
   Otherwise proceeds as in ``UNIX_COMMAND`` mode.
 
+``PROGRAM``
+  The first item in ``<args>`` is assumed to be an executable and will be
+  search in the system search path or left as a full path. If not found,
+  ``<variable>`` will be empty. Otherwise, ``<variable>`` is a list of 2
+  elements:
+
+    0. Absolute path of the program
+    1. Any command-line arguments present in ``<args>`` as a string
+
+  For example:
+
+  .. code-block:: cmake
+
+    separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
+
+  * First element of the list: ``/path/to/cc``
+  * Second element of the list: ``" -c main.c"``
+
+``SEPARATE_ARGS``
+  When this sub-option of ``PROGRAM`` option is specified, command-line
+  arguments will be split as well and stored in ``<variable>``.
+
+  For example:
+
+  .. code-block:: cmake
+
+    separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
+
+  The contents of ``out`` will be: ``/path/to/cc;-c;main.c``
+
 .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
 
 .. code-block:: cmake
diff --git a/Help/release/dev/separate_arguments-PROGRAM.rst b/Help/release/dev/separate_arguments-PROGRAM.rst
new file mode 100644
index 0000000..428bfda
--- /dev/null
+++ b/Help/release/dev/separate_arguments-PROGRAM.rst
@@ -0,0 +1,5 @@
+separate_arguments-PROGRAM
+--------------------------
+
+* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
+  search program.