Merge topic 'ExternalProject-list-separator-docs-example' into release-3.29

5d33f41e23 ExternalProject: reword `LIST_SEPARATOR` to indicate what it *does*
611ffce98c ExternalProject: add an example of `LIST_SEPARATOR` usage

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

1 files changed, 15 insertions, 4 deletions

diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 8b10135..965b25c 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -906,10 +906,21 @@ Miscellaneous Options
 
 ``LIST_SEPARATOR <sep>``
   For any of the various ``..._COMMAND`` options, and ``CMAKE_ARGS``,
-  replace ``;`` with ``<sep>`` in the specified command lines.
-  This can be useful where list variables may be given in commands where
-  they should end up as space-separated arguments (``<sep>`` would be a
-  single space character string in this case).
+  ``ExternalProject`` will replace ``<sep>`` with ``;`` in the specified
+  command lines. This can be used to ensure a command has a literal ``;`` in it
+  where direct usage would otherwise be interpreted as argument separators to
+  CMake APIs instead. Note that the separator should be chosen to avoid being
+  confused for non-list-separator usages of the sequence. For example, using
+  ``LIST_SEPARATOR`` allows for passing list values to CMake cache variables on
+  the command line:
+
+  .. code-block:: cmake
+
+    ExternalProject_Add(example
+      ... # Download options, etc.
+      LIST_SEPARATOR ","
+      CMAKE_ARGS "-DCMAKE_PREFIX_PATH:STRING=${first_prefix},${second_prefix}"
+    )
 
 ``COMMAND <cmd>...``
   Any of the other ``..._COMMAND`` options can have additional commands