CMakePackageConfigHelpers: Document PACKAGE_PREFIX_DIR for public use

This variable has long been provided by `configure_package_config_file`
in the `@PACKAGE_INIT@` part of the package configuration file it
generates.  Although not publicly documented, projects have come to
use it.  Now that we preserve the value across nested `find_package`
calls, it has a stable meaning.

Issue: #25827

Modules/CMakePackageConfigHelpers.cmake

@@ -76,6 +76,23 @@ always relative to the installed location of the package.  This works both for
 relative and also for absolute locations.  For absolute locations, it works
 only if the absolute location is a subdirectory of ``INSTALL_PREFIX``.
 
+.. versionadded:: 3.30
+  The variable ``PACKAGE_PREFIX_DIR`` will always be defined after the
+  ``@PACKAGE_INIT@`` line.  It will hold the value of the base install
+  location.  In general, variables defined via the ``PATH_VARS`` mechanism
+  should be used instead, but ``PACKAGE_PREFIX_DIR`` can be used for those
+  cases not easily handled by ``PATH_VARS``, such as for files installed
+  directly to the base install location rather than a subdirectory of it.
+
+  .. note::
+    When consumers of the generated file use CMake 3.29 or older, the value
+    of ``PACKAGE_PREFIX_DIR`` can be changed by a call to
+    :command:`find_dependency` or :command:`find_package`.
+    If a project relies on ``PACKAGE_PREFIX_DIR``, it is the project's
+    responsibility to ensure that the value of ``PACKAGE_PREFIX_DIR`` is
+    preserved across any such calls, or any other calls which might include
+    another file generated by ``configure_package_config_file()``.
+
 .. versionadded:: 3.1
   If the ``INSTALL_PREFIX`` argument is passed, this is used as the base path to
   calculate all the relative paths.  The ``<path>`` argument must be an absolute