Merge topic 'doc-installed-file-property'

89bb34d3 Help: Add 3.1 release notes for INSTALL property scope
07254a81 Help: Document installed file property API
a1aceb25 Help: Format set_property and get_property command docs

3 files changed, 69 insertions, 28 deletions

diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index c2937be..632ece6 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -10,6 +10,7 @@ Get a property.
                 DIRECTORY [dir]    |
                 TARGET    <target> |
                 SOURCE    <source> |
+                INSTALL   <file>   |
                 TEST      <test>   |
                 CACHE     <entry>  |
                 VARIABLE>
@@ -21,29 +22,40 @@ specifies the variable in which to store the result.  The second
 argument determines the scope from which to get the property.  It must
 be one of the following:
 
-GLOBAL scope is unique and does not accept a name.
+``GLOBAL``
+  Scope is unique and does not accept a name.
 
-DIRECTORY scope defaults to the current directory but another
-directory (already processed by CMake) may be named by full or
-relative path.
+``DIRECTORY``
+  Scope defaults to the current directory but another
+  directory (already processed by CMake) may be named by full or
+  relative path.
 
-TARGET scope must name one existing target.
+``TARGET``
+  Scope must name one existing target.
 
-SOURCE scope must name one source file.
+``SOURCE``
+  Scope must name one source file.
 
-TEST scope must name one existing test.
+``INSTALL``
+  Scope must name one installed file path.
 
-CACHE scope must name one cache entry.
+``TEST``
+  Scope must name one existing test.
 
-VARIABLE scope is unique and does not accept a name.
+``CACHE``
+  Scope must name one cache entry.
 
-The required PROPERTY option is immediately followed by the name of
+``VARIABLE``
+  Scope is unique and does not accept a name.
+
+The required ``PROPERTY`` option is immediately followed by the name of
 the property to get.  If the property is not set an empty value is
-returned.  If the SET option is given the variable is set to a boolean
-value indicating whether the property has been set.  If the DEFINED
+returned.  If the ``SET`` option is given the variable is set to a boolean
+value indicating whether the property has been set.  If the ``DEFINED``
 option is given the variable is set to a boolean value indicating
-whether the property has been defined such as with define_property.
-If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
+whether the property has been defined such as with the
+:command:`define_property` command.
+If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
 string containing documentation for the requested property.  If
 documentation is requested for a property that has not been defined
-NOTFOUND is returned.
+``NOTFOUND`` is returned.
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index 8cb963e..6200230 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -9,6 +9,7 @@ Set a named property in a given scope.
                 DIRECTORY [dir]                   |
                 TARGET    [target1 [target2 ...]] |
                 SOURCE    [src1 [src2 ...]]       |
+                INSTALL   [file1 [file2 ...]]     |
                 TEST      [test1 [test2 ...]]     |
                 CACHE     [entry1 [entry2 ...]]>
                [APPEND] [APPEND_STRING]
@@ -18,26 +19,48 @@ Set one property on zero or more objects of a scope.  The first
 argument determines the scope in which the property is set.  It must
 be one of the following:
 
-GLOBAL scope is unique and does not accept a name.
+``GLOBAL``
+  Scope is unique and does not accept a name.
 
-DIRECTORY scope defaults to the current directory but another
-directory (already processed by CMake) may be named by full or
-relative path.
+``DIRECTORY``
+  Scope defaults to the current directory but another
+  directory (already processed by CMake) may be named by full or
+  relative path.
 
-TARGET scope may name zero or more existing targets.
+``TARGET``
+  Scope may name zero or more existing targets.
 
-SOURCE scope may name zero or more source files.  Note that source
-file properties are visible only to targets added in the same
-directory (CMakeLists.txt).
+``SOURCE``
+  Scope may name zero or more source files.  Note that source
+  file properties are visible only to targets added in the same
+  directory (CMakeLists.txt).
 
-TEST scope may name zero or more existing tests.
+``INSTALL``
+  Scope may name zero or more installed file paths.
+  These are made available to CPack to influence deployment.
 
-CACHE scope must name zero or more cache existing entries.
+  Both the property key and value may use generator expressions.
+  Specific properties may apply to installed files and/or directories.
 
-The required PROPERTY option is immediately followed by the name of
+  Path components have to be separated by forward slashes,
+  must be normalized and are case sensitive.
+
+  To reference the installation prefix itself with a relative path use ".".
+
+  Currently installed file properties are only defined for
+  the WIX generator where the given paths are relative
+  to the installation prefix.
+
+``TEST``
+  Scope may name zero or more existing tests.
+
+``CACHE``
+  Scope must name zero or more cache existing entries.
+
+The required ``PROPERTY`` option is immediately followed by the name of
 the property to set.  Remaining arguments are used to compose the
 property value in the form of a semicolon-separated list.  If the
-APPEND option is given the list is appended to any existing property
-value.If the APPEND_STRING option is given the string is append to any
+``APPEND`` option is given the list is appended to any existing property
+value.  If the ``APPEND_STRING`` option is given the string is append to any
 existing property value as string, i.e.  it results in a longer string
 and not a list of strings.
diff --git a/Help/release/3.1.0.rst b/Help/release/3.1.0.rst
index 101c29d..d6921c4 100644
--- a/Help/release/3.1.0.rst
+++ b/Help/release/3.1.0.rst
@@ -69,9 +69,15 @@ Commands
   :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`
   variables to skip searching the package registries.
 
+* The :command:`get_property` command learned a new ``INSTALL`` scope
+  for properties.
+
 * The :command:`install` command learned a ``MESSAGE_NEVER`` option
   to avoid output during installation.
 
+* The :command:`set_property` command learned a new ``INSTALL`` scope
+  for properties.
+
 * The :command:`string` command learned a new ``GENEX_STRIP`` subcommand
   which removes
   :manual:`generator expression <cmake-generator-expressions(7)>`.