Help: Document warning about multiple source paths

Although passing multiple source paths was never documented, it was not
diagnosed by CMake 3.22 and below.  In CMake 3.23 we now diagnose extra
paths and warn.  Document this change and add a release note.

Issue: #23334

2 files changed, 13 insertions, 0 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 9a2b2ef..18bdc5f 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -171,6 +171,13 @@ is used for the other.  For example:
  ``cmake -B build -S src``      ``src``      ``build``
 ============================== ============ ===========
 
+.. versionchanged:: 3.23
+
+  CMake warns when multiple source paths are specified.  This has never
+  been officially documented or supported, but older versions accidentally
+  accepted multiple source paths and used the last path specified.
+  Avoid passing multiple source path arguments.
+
 After generating a buildsystem one may use the corresponding native
 build tool to build the project.  For example, after using the
 :generator:`Unix Makefiles` generator one may run ``make`` directly:
diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst
index c3bee02..69b935d 100644
--- a/Help/release/3.23.rst
+++ b/Help/release/3.23.rst
@@ -225,6 +225,12 @@ CPack
 Deprecated and Removed Features
 ===============================
 
+* :manual:`cmake(1)` now warns when multiple source paths are specified,
+  as in ``cmake -S src1 src2``.  This has never been officially documented
+  or supported, but older versions accidentally accepted multiple source
+  paths and used the last path specified.  Update scripts to avoid
+  passing multiple source path arguments.
+
 * The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed.
 
 Other Changes