Help: improve documentation for BUILD_RPATH

Now all properties related to BUILD_RPATH are linked from the
documentation for BUILD_RPATH.
SKIP_BUILD_RPATH now also refers to BUILD_RPATH.

Help/prop_tgt/BUILD_RPATH.rst

@@ -3,13 +3,31 @@ BUILD_RPATH
 
 .. versionadded:: 3.8
 
-A :ref:`semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``)
-entries to add to binaries linked in the build tree (for platforms that
-support it).  The entries will *not* be used for binaries in the install
-tree.  See also the :prop_tgt:`INSTALL_RPATH` target property.
+A :ref:`semicolon-separated list <CMake Language Lists>` specifying
+runtime path (``RPATH``) entries to add to binaries linked in the
+build tree (for platforms that support it).  By default, CMake sets
+the runtime path of binaries in the build tree to contain search
+paths it knows are needed to find the shared libraries they link.
+Projects may set ``BUILD_RPATH`` to specify additional search paths.
+
+The build-tree runtime path will *not* be used for binaries in the
+install tree.  It will be replaced with the install-tree runtime path
+during the installation step.  See also the :prop_tgt:`INSTALL_RPATH`
+target property.
 
 This property is initialized by the value of the variable
 :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created.
 
 This property supports
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+Other settings that affect the build-tree runtime path include:
+
+* The :prop_tgt:`SKIP_BUILD_RPATH` target property disables setting any
+  runtime path in the build tree.
+
+* The :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property causes the
+  automatically-generated runtime path to use entries relative to ``$ORIGIN``.
+
+* The :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property causes binaries
+  in the build tree to be built with the install-tree runtime path.

Help/prop_tgt/SKIP_BUILD_RPATH.rst

@@ -4,6 +4,7 @@ SKIP_BUILD_RPATH
 Should rpaths be used for the build tree.
 
 ``SKIP_BUILD_RPATH`` is a boolean specifying whether to skip automatic
-generation of an rpath allowing the target to run from the build tree.
+generation of an rpath allowing the target to run from the build tree,
+see also the :prop_tgt:`BUILD_RPATH` target property.
 This property is initialized by the value of the variable
 :variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created.