Help: Update install() docs to better reflect preference for file sets

Previously, headers would typically be installed as bare files or
as whole directories. File sets offer a better abstraction and
associate headers with a target, installing them as part of the
target. Add notes and update examples to draw the reader's
attention to the advantages of file sets for headers.

1 files changed, 39 insertions, 21 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 8216a69445..14f7ff7917 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -207,11 +207,13 @@ that may be installed:
 ``FILE_SET <set>``
   .. versionadded:: 3.23
 
+  File sets are defined by the :command:`target_sources(FILE_SET)` command.
   If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any
-  files added to the file set ``<set>`` created by
-  :command:`target_sources(FILE_SET)` are installed in the specified
-  destination, preserving their directory structure relative to the file set's
-  base directories.
+  files in the set are installed under the destination (see below).
+  The directory structure relative to the file set's base directories is
+  preserved. For example, a file added to the file set as
+  ``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
+  would be installed to ``myproj/here.h`` below the destination.
 
 For each of these arguments given, the arguments following them only apply
 to the target or file type specified in the argument. If none is given, the
@@ -223,13 +225,13 @@ For regular executables, static libraries and shared libraries, the
 ``DESTINATION`` argument is not required.  For these target types, when
 ``DESTINATION`` is omitted, a default destination will be taken from the
 appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
-default value if that variable is not defined.  The same is true for the
-public and private headers associated with the installed targets through the
-:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
-A destination must always be provided for module libraries, Apple bundles and
-frameworks.  A destination can be omitted for interface and object libraries,
-but they are handled differently (see the discussion of this topic toward the
-end of this section).
+default value if that variable is not defined.  The same is true for file
+sets, and the public and private headers associated with the installed
+targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER`
+target properties. A destination must always be provided for module libraries,
+Apple bundles and frameworks.  A destination can be omitted for interface and
+object libraries, but they are handled differently (see the discussion of this
+topic toward the end of this section).
 
 The following table shows the target types with their associated variables and
 built-in defaults that apply when no destination is given:
@@ -246,8 +248,9 @@ built-in defaults that apply when no destination is given:
 =============================== =============================== ======================
 
 Projects wishing to follow the common practice of installing headers into a
-project-specific subdirectory will need to provide a destination rather than
-rely on the above.
+project-specific subdirectory may prefer using file sets with appropriate
+paths and base directories. Otherwise, they must provide a ``DESTINATION``
+instead of being able to rely on the above (see next example below).
 
 To make packages compliant with distribution filesystem layout policies, if
 projects must specify a ``DESTINATION``, it is recommended that they use a
@@ -256,7 +259,7 @@ This allows package maintainers to control the install destination by setting
 the appropriate cache variables.  The following example shows a static library
 being installed to the default destination provided by
 :module:`GNUInstallDirs`, but with its headers installed to a project-specific
-subdirectory that follows the above recommendation:
+subdirectory without using file sets:
 
 .. code-block:: cmake
 
@@ -493,6 +496,12 @@ Installing Files
 .. _FILES:
 .. _PROGRAMS:
 
+.. note::
+
+  If installing header files, consider using file sets defined by
+  :command:`target_sources(FILE_SET)` instead. File sets associate
+  headers with a target and they install as part of the target.
+
 .. code-block:: cmake
 
   install(<FILES|PROGRAMS> files...
@@ -549,7 +558,8 @@ file type if they wish to explicitly define the install destination.
 
 Projects wishing to follow the common practice of installing headers into a
 project-specific subdirectory will need to provide a destination rather than
-rely on the above.
+rely on the above. Using file sets for headers instead of ``install(FILES)``
+would be even better (see :command:`target_sources(FILE_SET)`).
 
 Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
 a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
@@ -562,13 +572,14 @@ projects must specify a ``DESTINATION``, it is recommended that they use a
 path that begins with the appropriate :module:`GNUInstallDirs` variable.
 This allows package maintainers to control the install destination by setting
 the appropriate cache variables.  The following example shows how to follow
-this advice while installing headers to a project-specific subdirectory:
+this advice while installing an image to a project-specific documentation
+subdirectory:
 
 .. code-block:: cmake
 
   include(GNUInstallDirs)
-  install(FILES mylib.h
-          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
+  install(FILES logo.png
+          DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
   )
 
 .. versionadded:: 3.4
@@ -587,6 +598,13 @@ Installing Directories
 .. _`install(DIRECTORY)`:
 .. _DIRECTORY:
 
+.. note::
+
+  To install a directory sub-tree of headers, consider using file sets
+  defined by :command:`target_sources(FILE_SET)` instead. File sets not only
+  preserve directory structure, they also associate headers with a target
+  and install as part of the target.
+
 .. code-block:: cmake
 
   install(DIRECTORY dirs...
@@ -638,10 +656,10 @@ any expression.  For example, the code
 
 .. code-block:: cmake
 
-  install(DIRECTORY src/ DESTINATION include/myproj
-          FILES_MATCHING PATTERN "*.h")
+  install(DIRECTORY src/ DESTINATION doc/myproj
+          FILES_MATCHING PATTERN "*.png")
 
-will extract and install header files from a source tree.
+will extract and install images from a source tree.
 
 Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
 under :ref:`string(REGEX) <Regex Specification>` and are applied