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.

1 files changed, 14 insertions, 0 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
+  )