Help: clarify "LINKER:" prefix usage

Fixes: #18503

4 files changed, 19 insertions, 7 deletions

diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt
index 76927be..a723375 100644
--- a/Help/command/LINK_OPTIONS_LINKER.txt
+++ b/Help/command/LINK_OPTIONS_LINKER.txt
@@ -8,3 +8,15 @@ driver option and the rest of the option string defines linker arguments using
 
 For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for
 ``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``.
+
+The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix
+expression.
+
+The ``LINKER:`` prefix supports, as alternate syntax, specification of
+arguments using ``SHELL:`` prefix and space as separator. Previous example
+becomes ``"LINKER:SHELL:-z defs"``.
+
+.. note::
+
+  Specifying ``SHELL:`` prefix elsewhere than at the beginning of the
+  ``LINKER:`` prefix is not supported.
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index 551d440..e5fb878 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -21,6 +21,6 @@ the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
-.. include:: LINK_OPTIONS_LINKER.txt
-
 .. include:: OPTIONS_SHELL.txt
+
+.. include:: LINK_OPTIONS_LINKER.txt
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index 8f47180..0b45a8b 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -37,6 +37,6 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
-.. include:: LINK_OPTIONS_LINKER.txt
-
 .. include:: OPTIONS_SHELL.txt
+
+.. include:: LINK_OPTIONS_LINKER.txt
diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst
index 0e52282..321f97e 100644
--- a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst
+++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst
@@ -17,7 +17,7 @@ For example, for ``Clang`` we have:
 
   set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ")
 
-Specifying ``"LINKER:-z defs"`` will be transformed in
+Specifying ``"LINKER:-z,defs"`` will be transformed in
 ``-Xlinker -z -Xlinker defs``.
 
 For ``GNU GCC``:
@@ -27,7 +27,7 @@ For ``GNU GCC``:
   set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,")
   set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
 
-Specifying ``"LINKER:-z defs"`` will be transformed in ``-Wl,-z,defs``.
+Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Wl,-z,defs``.
 
 And for ``SunPro``:
 
@@ -36,4 +36,4 @@ And for ``SunPro``:
   set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ")
   set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",")
 
-Specifying ``"LINKER:-z defs"`` will be transformed in ``-Qoption ld -z,defs``.
+Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Qoption ld -z,defs``.