Help: Explain build/install-tree include dirs in more places (#14946)

Explain how to use $<BUILD_INTERFACE> and $<INSTALL_INTERFACE> directly
in the documentation of the target_include_directories command and
INTERFACE_INCLUDE_DIRECTORIES target property.  Otherwise readers need
to notice the link to the cmake-buildsystem(7) manual and find the
example in that to understand the need for these expressions.

Also fix the explanation in cmake-buildsystem(7) to not claim that
relative paths may be used inside a BUILD_INTERFACE expression.

3 files changed, 35 insertions, 3 deletions

diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst
index 75f917d..581bace 100644
--- a/Help/command/target_include_directories.rst
+++ b/Help/command/target_include_directories.rst
@@ -40,3 +40,17 @@ Arguments to ``target_include_directories`` may use "generator expressions"
 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 directories usage requirements commonly differ between the build-tree
+and the install-tree.  The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
+generator expressions can be used to describe separate usage requirements
+based on the usage location.  Relative paths are allowed within the
+``INSTALL_INTERFACE`` expression and are interpreted relative to the
+installation prefix.  For example:
+
+.. code-block:: cmake
+
+  target_include_directories(mylib PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
+    $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
+  )
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 3e1f011..f3a5770 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -578,9 +578,9 @@ expands to the installation prefix when imported by a consuming project.
 Include directories usage requirements commonly differ between the build-tree
 and the install-tree.  The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
 generator expressions can be used to describe separate usage requirements
-based on the usage location.  Relative paths are allowed within these
-expressions, and are interpreted relative to the current source directory
-or the installation prefix, as appropriate:
+based on the usage location.  Relative paths are allowed within the
+``INSTALL_INTERFACE`` expression and are interpreted relative to the
+installation prefix.  For example:
 
 .. code-block:: cmake
 
diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
index bf4ab46..899e821 100644
--- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
+++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
@@ -3,6 +3,10 @@ INTERFACE_INCLUDE_DIRECTORIES
 
 List of public include directories for a library.
 
+The :command:`target_include_directories` command populates this property
+with values given to the ``PUBLIC`` and ``INTERFACE`` keywords.  Projects
+may also get and set the property directly.
+
 Targets may populate this property to publish the include directories
 required to compile against the headers for the target.  Consuming
 targets can add entries to their own :prop_tgt:`INCLUDE_DIRECTORIES`
@@ -13,3 +17,17 @@ Contents of ``INTERFACE_INCLUDE_DIRECTORIES`` may use "generator expressions"
 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 directories usage requirements commonly differ between the build-tree
+and the install-tree.  The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
+generator expressions can be used to describe separate usage requirements
+based on the usage location.  Relative paths are allowed within the
+``INSTALL_INTERFACE`` expression and are interpreted relative to the
+installation prefix.  For example:
+
+.. code-block:: cmake
+
+  set_property(TARGET mylib APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
+    $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
+    )