Help: Rework $<LINK_LIBRARY>, $<LINK_GROUP> and related docs

These changes restructure the docs to improve readability and flow,
correct grammar and typos, and fix errors and inconsistencies in
some of the examples.

Fixes: #23684

1 files changed, 28 insertions, 22 deletions

diff --git a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
index 112f6142ee..4d3dd4f64a 100644
--- a/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
+++ b/Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
@@ -3,43 +3,49 @@ LINK_LIBRARY_OVERRIDE_<LIBRARY>
 
 .. versionadded:: 3.24
 
-To resolve incompatible features introduced by :genex:`LINK_LIBRARY` generator
-expression, this property offers the possibility to override, for a
-``link-item`` (``CMake`` target or external library) involved in the link step,
-any defined features with a new one.
+Override the library feature associated with ``<LIBRARY>`` from
+:genex:`LINK_LIBRARY` generator expressions.  This can be used to resolve
+incompatible library features that result from specifying different features
+for ``<LIBRARY>`` in different :genex:`LINK_LIBRARY` generator expressions.
 
-This property takes a ``feature`` name which will be applied to the
-``link-item`` specified by ``<LIBRARY>`` suffix property. For example:
+When set on a target, this property holds a single library feature name, which
+will be applied to ``<LIBRARY>`` when linking that target.
 
 .. code-block:: cmake
 
   add_library(lib1 ...)
-  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
-
   add_library(lib2 ...)
-  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
-
   add_library(lib3 ...)
+
+  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
+  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
   target_link_libraries(lib3 PRIVATE lib1 lib2)
-  # Here, lib1 has two different features which prevents to link lib3
-  # So, define LINK_LIBRARY_OVERRIDE_lib1 property to ensure correct link
+
+  # lib1 is associated with both feature2 and no feature. Without any override,
+  # this would result in a fatal error at generation time for lib3.
+  # Define an override to resolve the incompatible feature associations.
   set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
-  # The lib1 will be used with feature2 to link lib3
 
-It is also possible to override any feature with the pre-defined feature
-``DEFAULT`` to get the standard behavior (i.e. no feature):
+  # lib1 will now be associated with feature2 instead when linking lib3
+
+It is also possible to override any feature with the pre-defined ``DEFAULT``
+library feature.  This effectively discards any feature for that link item,
+for that target only (``lib3`` in this example):
 
 .. code-block:: cmake
 
+  # When linking lib3, discard any library feature for lib1
   set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
-  # The lib1 will be used without any feature to link lib3
+
+See the :prop_tgt:`LINK_LIBRARY_OVERRIDE` target property for an alternative
+way of overriding library features for multiple libraries at once.  If both
+properties are defined and specify an override for the same link item,
+``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` takes precedence over
+:prop_tgt:`LINK_LIBRARY_OVERRIDE`.
 
 Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
-This property takes precedence over :prop_tgt:`LINK_LIBRARY_OVERRIDE`
-target property.
-
-For more information about features, see
-:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`
-and :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
+For more information about library features, see the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.