Help: Clarify and update SYSTEM-related docs

5 files changed, 50 insertions, 36 deletions

diff --git a/Help/prop_tgt/EXPORT_NO_SYSTEM.rst b/Help/prop_tgt/EXPORT_NO_SYSTEM.rst
index 61f0a8d..f86abd3 100644
--- a/Help/prop_tgt/EXPORT_NO_SYSTEM.rst
+++ b/Help/prop_tgt/EXPORT_NO_SYSTEM.rst
@@ -3,8 +3,10 @@ EXPORT_NO_SYSTEM
 
 .. versionadded:: 3.25
 
-Specifies that :command:`install(EXPORT)` and :command:`export` commands will
-generate an imported target with :prop_tgt:`SYSTEM` property `OFF`.
+This property affects the behavior of the :command:`install(EXPORT)` and
+:command:`export` commands when they install or export the target respectively.
+When ``EXPORT_NO_SYSTEM`` is set to true, those commands generate an imported
+target with :prop_tgt:`SYSTEM` property set to false.
 
 See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this
 behavior on the target *consuming* the include directories rather than the
diff --git a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
index 913d9f2..c8ec8b5 100644
--- a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
+++ b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
@@ -5,27 +5,31 @@ IMPORTED_NO_SYSTEM
 
 .. deprecated:: 3.25
 
-  ``IMPORTED_NO_SYSTEM`` is deprecated. Set :prop_tgt:`SYSTEM` to `OFF`
-  instead if you don't want target's include directories to be ``SYSTEM``
-  when compiling consumers. Set :prop_tgt:`EXPORT_NO_SYSTEM` to `ON` instead
-  if you don't want the include directories of the imported target generated
-  by :command:`install(EXPORT)` and :command:`export` commands to be
-  ``SYSTEM`` when compiling consumers.
+  ``IMPORTED_NO_SYSTEM`` is deprecated. Please use the following alternatives
+  instead:
 
-Specifies that an :ref:`Imported Target <Imported Targets>` is not
-a ``SYSTEM`` library.  This has the following effects:
+  * Set :prop_tgt:`SYSTEM` to false if you don't want a target's include
+    directories to be treated as system directories when compiling consumers.
+  * Set :prop_tgt:`EXPORT_NO_SYSTEM` to true if you don't want the include
+    directories of the imported target generated by :command:`install(EXPORT)`
+    and :command:`export` commands to be treated as system directories when
+    compiling consumers.
+
+Setting ``IMPORTED_NO_SYSTEM`` to true on an
+:ref:`imported target <Imported Targets>` specifies that it is not a
+system target.  This has the following effects:
 
 * Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated
-  as ``SYSTEM`` include directories when compiling consumers (regardless of
+  as system include directories when compiling consumers (regardless of
   the value of the consumed target's :prop_tgt:`SYSTEM` property), as they
   would be by default.   Entries of
   :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
-  and will always be treated as ``SYSTEM`` include directories.
+  and will always be treated as system include directories.
 
 This property can also be enabled on a non-imported target.  Doing so does
 not affect the build system, but does tell the :command:`install(EXPORT)` and
 :command:`export` commands to enable it on the imported targets they generate.
 
 See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this
-behavior on the target consuming the include directories rather than
-providing them.
+behavior on the target *consuming* the include directories rather than
+the one *providing* them.
diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
index b37bb0c..2ded46f 100644
--- a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
+++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
@@ -8,17 +8,17 @@ which contain system headers, and therefore should not result in
 compiler warnings.  Additionally, system include directories are searched
 after normal include directories regardless of the order specified.
 
-The :command:`target_include_directories(SYSTEM)` command signature
-populates this property with values given to the ``PUBLIC`` and
-``INTERFACE`` keywords.
+When the :command:`target_include_directories` command is given the
+``SYSTEM`` keyword, it populates this property with values provided after the
+``PUBLIC`` and ``INTERFACE`` keywords.
 
 Projects may also get and set the property directly, but must be aware that
 adding directories to this property does not make those directories used
 during compilation.  Adding directories to this property marks directories
-as ``SYSTEM`` which otherwise would be used in a non-``SYSTEM`` manner.  This
-can appear similar to 'duplication', so prefer the
-high-level :command:`target_include_directories(SYSTEM)` command and avoid
-setting the property by low-level means.
+as system directories which otherwise would be used in a non-system manner.
+This can appear similar to duplication, so prefer the high-level
+:command:`target_include_directories` command with the ``SYSTEM`` keyword
+and avoid setting the property directly.
 
 When target dependencies are specified using :command:`target_link_libraries`,
 CMake will read this property from all target dependencies to mark the
diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
index 39a13ee..a4c9b9f 100644
--- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
+++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
@@ -2,19 +2,27 @@ NO_SYSTEM_FROM_IMPORTED
 -----------------------
 
 Do not treat include directories from the interfaces of consumed
-:ref:`imported targets` as ``SYSTEM``.
+:ref:`imported targets` as system directories.
 
 The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property
-of imported targets are treated as ``SYSTEM`` includes by default.  If this
-property is enabled on a target, compilation of sources in that target will
-not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed
-imported targets as system includes.  Either way, entries of
-:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
-and will always be treated as ``SYSTEM`` include directories.
+are treated as system includes when the consumed target's :prop_tgt:`SYSTEM`
+property is set to true.  By default, :prop_tgt:`SYSTEM` is true for imported
+targets and false for other target types.  If the ``NO_SYSTEM_FROM_IMPORTED``
+property is set to true on a *consuming* target, compilation of sources in that
+consuming target will not treat the contents of the
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of consumed imported targets as
+system includes, even if that imported target's :prop_tgt:`SYSTEM` property
+is false.
+
+Directories listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`
+property of consumed targets are not affected by ``NO_SYSTEM_FROM_IMPORTED``.
+Those directories will always be treated as system include directories by
+consumers.
 
 This property is initialized by the value of the
 :variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target
 is created.
 
-See the :prop_tgt:`IMPORTED_NO_SYSTEM` target property to set this behavior
-on the target providing the include directories rather than consuming them.
+See the :prop_tgt:`EXPORT_NO_SYSTEM` target property to set this behavior
+on the target providing the include directories rather than the target
+consuming them.
diff --git a/Help/prop_tgt/SYSTEM.rst b/Help/prop_tgt/SYSTEM.rst
index 6399d24..c7ae27e 100644
--- a/Help/prop_tgt/SYSTEM.rst
+++ b/Help/prop_tgt/SYSTEM.rst
@@ -3,20 +3,20 @@ SYSTEM
 
 .. versionadded:: 3.25
 
-Specifies that a target is a ``SYSTEM`` library.  This has the following
+Specifies that a target is a system target.  This has the following
 effects:
 
 * Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are treated as
-  ``SYSTEM`` include directories when compiling consumers.
+  system include directories when compiling consumers.
   Entries of :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not
-  affected, and will always be treated as ``SYSTEM`` include directories.
+  affected, and will always be treated as system include directories.
 
 For imported targets, this property defaults to true, which means
 that their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are treated
-as ``SYSTEM`` by default. If their ``SYSTEM`` property is false,
+as system directories by default.  If their ``SYSTEM`` property is false,
 then their :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` will not be
-treated as ``SYSTEM``, regardless of the value of the
-:prop_tgt:`IMPORTED_NO_SYSTEM` property.
+treated as system.  Use the :prop_tgt:`EXPORT_NO_SYSTEM` property to change
+how a target's ``SYSTEM`` property is set when it is installed.
 
 For non-imported targets, this target property is initialized from
 the :prop_dir:`SYSTEM` directory property when the target is created.