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, 9 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 48a1a71..38c231a 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -62,8 +62,11 @@ added to the search.
 If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 
 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
-   |prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called
-   from within a find module
+   |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
+   :variable:`<PackageName>_ROOT` CMake variable and the
+   :envvar:`<PackageName>_ROOT` environment variable if
+   called from within a find module loaded by
+   :command:`find_package(<PackageName>)`
 
 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
@@ -76,13 +79,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in
    :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 
-1. If called from within a find module, search prefix paths unique to the
-   current package being found.  Specifically look in the ``PackageName_ROOT``
-   CMake and environment variables.  The package root variables are maintained
-   as a stack so if called from nested find modules, root paths from the
-   parent's find module will be searched after paths from the current module,
-   i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``,
-   ``ParentPackage_ROOT``, ``ENV{ParentPackage_ROOT}``, etc.
+1. If called from within a find module loaded by
+   :command:`find_package(<PackageName>)`, search prefixes unique to the
+   current package being found.  Specifically look in the
+   :variable:`<PackageName>_ROOT` CMake variable and the
+   :envvar:`<PackageName>_ROOT` environment variable.
+   The package root variables are maintained as a stack so if called from
+   nested find modules, root paths from the parent's find module will be
+   searched after paths from the current module,
+   i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
+   ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
    This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
    See policy :policy:`CMP0074`.