Help: clarify "LINKER:" prefix usage

Fixes: #18503

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.

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

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

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``.