Merge topic 'install-messages'

d19b64d6 install(DIRECTORY): Add MESSAGE_NEVER option to avoid output (#13761)
c9568de5 install: Add CMAKE_INSTALL_MESSAGE variable (#13761)
ec7cf7ea install: Thread message level setting through internal API
abebcd23 file(INSTALL): Add undocumented options to control output verbosity
464567a5 file(INSTALL): Report existing DIRECTORY as Up-to-date
f701b0b7 file(INSTALL): Do not pre-create DESTINATION for DIRECTORY
f0a01962 cmInstallTargetGenerator: Drop default constructor arguments
67815894 Help: Add install() command document section headers

2 files changed, 26 insertions, 7 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 869350a..58e3a26 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -298,6 +298,7 @@ See the :command:`install(DIRECTORY)` command for documentation of
 permissions, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options.
 
 The ``INSTALL`` signature differs slightly from ``COPY``: it prints
-status messages, and ``NO_SOURCE_PERMISSIONS`` is default.
+status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
+and ``NO_SOURCE_PERMISSIONS`` is default.
 Installation scripts generated by the :command:`install` command
 use this signature (with some undocumented options for internal use).
diff --git a/Help/command/install.rst b/Help/command/install.rst
index 47108f0..4c52abf 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -1,8 +1,15 @@
 install
 -------
 
+.. only:: html
+
+   .. contents::
+
 Specify rules to run at install time.
 
+Introduction
+^^^^^^^^^^^^
+
 This command generates installation rules for a project.  Rules
 specified by calls to this command within a source directory are
 executed in order during installation.  The order across directories
@@ -52,7 +59,12 @@ signatures that specify them.  The common options are:
   Specify that it is not an error if the file to be installed does
   not exist.
 
-------------------------------------------------------------------------------
+Command signatures that install files may print messages during
+installation.  Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
+to control which messages are printed.
+
+Installing Targets
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -147,7 +159,8 @@ file itself, call ``install(EXPORT)``, documented below.
 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 set to ``TRUE`` has undefined behavior.
 
-------------------------------------------------------------------------------
+Installing Files
+^^^^^^^^^^^^^^^^
 
 ::
 
@@ -175,14 +188,15 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
 However, if any item begins in a generator expression it must evaluate
 to a full path.
 
-------------------------------------------------------------------------------
+Installing Directories
+^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
   install(DIRECTORY dirs... DESTINATION <dir>
           [FILE_PERMISSIONS permissions...]
           [DIRECTORY_PERMISSIONS permissions...]
-          [USE_SOURCE_PERMISSIONS] [OPTIONAL]
+          [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
           [CONFIGURATIONS [Debug|Release|...]]
           [COMPONENT <component>] [FILES_MATCHING]
           [[PATTERN <pattern> | REGEX <regex>]
@@ -205,6 +219,8 @@ permissions specified in the ``FILES`` form of the command, and the
 directories will be given the default permissions specified in the
 ``PROGRAMS`` form of the command.
 
+The ``MESSAGE_NEVER`` option disables file installation status output.
+
 Installation of directories may be controlled with fine granularity
 using the ``PATTERN`` or ``REGEX`` options.  These "match" options specify a
 globbing pattern or regular expression to match directories or files
@@ -247,7 +263,8 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the
 file permissions, the scripts will be given specific permissions, and any
 ``CVS`` directories will be excluded.
 
-------------------------------------------------------------------------------
+Custom Installation Logic
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -266,7 +283,8 @@ example, the code
 
 will print a message during installation.
 
-------------------------------------------------------------------------------
+Installing Exports
+^^^^^^^^^^^^^^^^^^
 
 ::