Help: Clarify documentation on SYSTEM include directories

Mention that system include directories are searched after normal
include directories.

Document that `IMPORTED_NO_SYSTEM` and `NO_SYSTEM_FROM_IMPORTED`
do not affect `INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`.

5 files changed, 24 insertions, 12 deletions

diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst
index 3fc7926..9a99a7d 100644
--- a/Help/command/target_include_directories.rst
+++ b/Help/command/target_include_directories.rst
@@ -28,12 +28,15 @@ The following arguments specify include directories.
   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
 
 Repeated calls for the same ``<target>`` append items in the order called.
-If ``SYSTEM`` is specified, the compiler will be told the
-directories are meant as system include directories on some platforms
-(signalling this setting might achieve effects such as the compiler
-skipping warnings, or these fixed-install system files not being
-considered in dependency calculations - see compiler docs).  If ``SYSTEM``
-is used together with ``PUBLIC`` or ``INTERFACE``, the
+
+If ``SYSTEM`` is specified, the compiler will be told the directories
+are meant as system include directories on some platforms.  This may
+have effects such as suppressing warnings or skipping the contained
+headers in dependency calculations (see compiler documentation).
+Additionally, system include directories are searched after normal
+include directories regardless of the order specified.
+
+If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
 :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
 populated with the specified directories.
 
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 2f43070..f48313a 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -675,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the
 dependency. This can result in omission of compiler warnings for headers
 found in those directories.  This behavior for :ref:`imported targets` may
 be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target
-property on the *consumers* of imported targets.
+property on the *consumers* of imported targets, or by setting the
+:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets
+themselves.
 
 If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the
 ``Headers`` directory of the framework is also treated as a usage requirement.
diff --git a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
index cc726d1..f6ad3e5 100644
--- a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
+++ b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst
@@ -6,7 +6,9 @@ a ``SYSTEM`` library.  This has the following effects:
 
 * Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated
   as ``SYSTEM`` include directories when compiling consumers, as they
-  would be by default.
+  would be by default.   Entries of
+  :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
+  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
diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
index a0a97ad..b37bb0c 100644
--- a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
+++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
@@ -5,9 +5,12 @@ List of public system include directories for a library.
 
 Targets may populate this property to publish the include directories
 which contain system headers, and therefore should not result in
-compiler warnings.  The :command:`target_include_directories(SYSTEM)`
-command signature populates this property with values given to the
-``PUBLIC`` and ``INTERFACE`` keywords.
+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.
 
 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
diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
index e5cc09b..39a13ee 100644
--- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
+++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst
@@ -8,7 +8,9 @@ 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.
+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.
 
 This property is initialized by the value of the
 :variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target