Merge topic 'doc-list-semicolons' into release-3.23

8abd714176 Help: Clarify that ENVIRONMENT test properties take ;-separated lists
02cf404ace Help: Add advice for dealing with semicolons in lists
c4117d9116 ExternalProject: Document that LIST_SEPARATOR works for CMAKE_ARGS too

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !7066

4 files changed, 56 insertions, 13 deletions

diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst
index b7f0861..e7d2694 100644
--- a/Help/manual/cmake-language.7.rst
+++ b/Help/manual/cmake-language.7.rst
@@ -627,3 +627,45 @@ in list elements, thus flattening nested lists:
 .. code-block:: cmake
 
  set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
+
+In general, lists do not support elements containing ``;`` characters.
+To avoid problems, consider the following advice:
+
+* The interfaces of many CMake commands, variables, and properties accept
+  semicolon-separated lists.  Avoid passing lists with elements containing
+  semicolons to these interfaces unless they document either direct support
+  or some way to escape or encode semicolons.
+
+* When constructing a list, substitute an otherwise-unused placeholder
+  for ``;`` in elements when.  Then substitute ``;`` for the placeholder
+  when processing list elements.
+  For example, the following code uses ``|`` in place of ``;`` characters:
+
+  .. code-block:: cmake
+
+    set(mylist a "b|c")
+    foreach(entry IN LISTS mylist)
+      string(REPLACE "|" ";" entry "${entry}")
+      # use "${entry}" normally
+    endforeach()
+
+  The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an
+  example of an interface built using this approach.
+
+* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`,
+  use the :genex:`$<SEMICOLON>` generator expression.
+
+* In command calls, use `Quoted Argument`_ syntax whenever possible.
+  The called command will receive the content of the argument with
+  semicolons preserved.  An `Unquoted Argument`_ will be split on
+  semicolons.
+
+* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``,
+  which do not distinguish semicolons in values from those separating values.
+  Instead, prefer using named positional arguments and the ``ARGC`` and
+  ``ARGV#`` variables.
+  When using :command:`cmake_parse_arguments` to parse arguments, prefer
+  its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables.
+
+  Note that this approach does not apply to :command:`macro` implementations
+  because they reference arguments using placeholders, not real variables.
diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst
index 43bcdbe..07b96bb 100644
--- a/Help/prop_test/ENVIRONMENT.rst
+++ b/Help/prop_test/ENVIRONMENT.rst
@@ -3,7 +3,7 @@ ENVIRONMENT
 
 Specify environment variables that should be defined for running a test.
 
-If set to a list of environment variables and values of the form
-``MYVAR=value`` those environment variables will be defined while running
-the test.  The environment changes from this property do not affect other
-tests.
+Set to a :ref:`semicolon-separated list <CMake Language Lists>` list
+of environment variables and values of the form ``MYVAR=value``.
+Those environment variables will be defined while running the test.
+The environment changes from this property do not affect other tests.
diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst
index 1e17329..a80651a 100644
--- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst
+++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst
@@ -7,10 +7,11 @@ Specify environment variables that should be modified for running a test. Note
 that the operations performed by this property are performed after the
 :prop_test:`ENVIRONMENT` property is already applied.
 
-If set to a list of environment variables and values of the form
-``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an
-environment variable to be modified. Entries are considered in the
-order specified in the property's value. The ``OP`` may be one of:
+Set to a :ref:`semicolon-separated list <CMake Language Lists>` of
+environment variables and values of the form ``MYVAR=OP:VALUE``,
+where ``MYVAR`` is the case-sensitive name of an environment variable
+to be modified.  Entries are considered in the order specified in the
+property's value.  The ``OP`` may be one of:
 
   - ``reset``: Reset to the unmodified value, ignoring all modifications to
     ``MYVAR`` prior to this entry. Note that this will reset the variable to
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 14864d5..7f16fdc 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -807,11 +807,11 @@ External Project Definition
 
   **Miscellaneous Options:**
     ``LIST_SEPARATOR <sep>``
-      For any of the various ``..._COMMAND`` options, 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).
+      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).
 
     ``COMMAND <cmd>...``
       Any of the other ``..._COMMAND`` options can have additional commands