Help: Reorganize and refine discussion of relocatable packages

Re-organize the content added to the cmake-packages(7) manual by

* commit v3.0.0-rc1~184^2 (Help: Document export(EXPORT) in the
  cmake-packages manual, 2013-12-23),

* commit v3.0.0-rc1~154^2~1 (Help: Add notes about relocatability
  of config-file packages, 2014-01-07), and

* commit v3.2.0-rc1~345^2 (Help: Warn that paths should not be used
  in INTERFACE_ build properties, 2014-11-22).

These commits broke the natural flow of the original manual and made
wording after the new content make less sense.  Move the content into
new subsections to restore the flow of the original manual and to
make explicitly the purpose of the new content.

Shorten the relocatable usage requirement "warnings".  Refer to the
new cmake-packages(7) manual subsection to reduce duplication.  Also
clarify the distinction between paths to library dependencies and
paths to their header files.

2 files changed, 19 insertions, 44 deletions

diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
index 33f71837e5..a54d7280db 100644
--- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
+++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
@@ -1,30 +1,18 @@
 
 Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
-|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
-That would hard-code into installed packages the include directory paths
-for dependencies **as found on the machine the package was made on**.
+|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
+directories of dependencies.  That would hard-code into installed packages
+the include directory paths for dependencies
+**as found on the machine the package was made on**.
 
 The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
-suitable for specifying the required include directories of the target itself,
-not its dependencies.
+suitable for specifying the required include directories for headers
+provided with the target itself, not those provided by the transitive
+dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
+property.  Those dependencies should themselves be targets that specify
+their own header locations in |INTERFACE_PROPERTY_LINK|.
 
-That is, code like this is incorrect for targets which will be used to
-generate :manual:`cmake-packages(7)`:
-
-.. code-block:: cmake
-
-  target_include_directories(mylib INTERFACE
-    $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
-  )
-
-Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
-which have their own |INTERFACE_PROPERTY_LINK| populated
-appropriately.  Those :ref:`IMPORTED targets <Imported Targets>` may then be
-used with the :command:`target_link_libraries` command for ``mylib``.
-
-That way, when a consumer uses the installed package, the
-consumer will run the appropriate :command:`find_package` command to find
-the dependencies on their own machine and populate the
-:ref:`IMPORTED targets <Imported Targets>` with appropriate paths.  See
-:ref:`Creating Packages` for more.  Note that many modules currently shipped
-with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.
+See the :ref:`Creating Relocatable Packages` section of the
+:manual:`cmake-packages(7)` manual for discussion of additional care
+that must be taken when specifying usage requirements while creating
+packages for redistribution.
diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
index ceefa4d2bb..46e84ac227 100644
--- a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
+++ b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt
@@ -1,23 +1,10 @@
 
 Note that it is not advisable to populate the
-|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
-That would hard-code into installed packages the include directory paths
+|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies.
+That would hard-code into installed packages the library file paths
 for dependencies **as found on the machine the package was made on**.
 
-That is, code like this is incorrect for targets which will be used to
-generate :manual:`cmake-packages(7)`:
-
-.. code-block:: cmake
-
-  target_link_libraries(mylib INTERFACE
-    ${Boost_LIBRARIES};${OtherDep_LIBRARIES}
-  )
-
-Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
-which have their own :prop_tgt:`IMPORTED_LOCATION` populated
-appropriately.  That way, when a consumer uses the installed package, the
-consumer will run the appropriate :command:`find_package` command to find
-the dependencies on their own machine and populate the
-:ref:`IMPORTED targets <Imported Targets>` with appropriate paths.  See
-:ref:`Creating Packages` for more.  Note that many modules currently shipped
-with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.
+See the :ref:`Creating Relocatable Packages` section of the
+:manual:`cmake-packages(7)` manual for discussion of additional care
+that must be taken when specifying usage requirements while creating
+packages for redistribution.