Help: Add explicit <PackageName>_ROOT variable documentation

Add documentation for both the CMake variable and environment variable
of this name pattern.  Update references to these names to link to their
documents.  Clarify the pattern used to construct their names.

1 files changed, 15 insertions, 0 deletions

diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst
new file mode 100644
index 0000000..e01009b
--- /dev/null
+++ b/Help/envvar/PackageName_ROOT.rst
@@ -0,0 +1,15 @@
+<PackageName>_ROOT
+------------------
+
+Calls to :command:`find_package(<PackageName>)` will search in prefixes
+specified by the ``<PackageName>_ROOT`` environment variable, where
+``<PackageName>`` is the name given to the ``find_package`` call
+and ``_ROOT`` is literal.  For example, ``find_package(Foo)`` will search
+prefixes specified in the ``Foo_ROOT`` environment variable (if set).
+See policy :policy:`CMP0074`.
+
+This variable may hold a single prefix or a list of prefixes separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`<PackageName>_ROOT` CMake variable.