ENH: Clarify documentation of find_package command.

1 files changed, 20 insertions, 8 deletions

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index 24d8c17..bbdf087 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -125,13 +125,25 @@ cmFindPackageCommand::cmFindPackageCommand()
     "a configuration file a fatal error is always generated because user "
     "intervention is required."
     "\n"
+    "Config mode provides an elaborate interface and search procedure.  "
+    "Much of the interface is provided for completeness and for use "
+    "internally by find-modules loaded by Module mode.  "
+    "Most user code should simply call\n"
+    "  find_package(<package> [REQUIRED|QUIET])\n"
+    "in order to find a package.  Package maintainers providing CMake "
+    "package configuration files are encouraged to name and install "
+    "them such that the procedure outlined below will find them "
+    "without requiring use of additional options."
+    "\n"
     "CMake constructs a set of possible installation prefixes for the "
-    "package.  Under each prefix the following directories are searched "
-    "for a configuration file:\n"
+    "package.  Under each prefix several directories are searched for a "
+    "configuration file.  The tables below show the directories searched.  "
+    "Each entry is meant for installation trees following Windows (W), "
+    "UNIX (U), or Apple (A) conventions.\n"
     "  <prefix>/                                               (W)\n"
     "  <prefix>/(cmake|CMake)/                                 (W)\n"
-    "  <prefix>/(share|lib)/<name>*/                           (P)\n"
-    "  <prefix>/(share|lib)/<name>*/(cmake|CMake)/             (P)\n"
+    "  <prefix>/(share|lib)/<name>*/                           (U)\n"
+    "  <prefix>/(share|lib)/<name>*/(cmake|CMake)/             (U)\n"
     "On systems supporting OS X Frameworks and Application Bundles "
     "the following directories are searched for frameworks or bundles "
     "containing a configuration file:\n"
@@ -144,14 +156,14 @@ cmFindPackageCommand::cmFindPackageCommand()
     "In all cases the <name> is treated as case-insensitive and corresponds "
     "to any of the names specified (<package> or names given by NAMES).  "
     "If PATH_SUFFIXES is specified the suffixes are appended to each "
-    "(W) or (P) directory entry one-by-one.\n"
+    "(W) or (U) directory entry one-by-one.\n"
     "This set of directories is intended to work in cooperation with "
     "projects that provide configuration files in their installation trees.  "
     "Directories above marked with (W) are intended for installations on "
     "Windows where the prefix may point at the top of an application's "
-    "installation directory.  Those marked with (P) are intended for "
-    "installations on POSIX platforms where the prefix is shared by "
-    "multiple packages.  This is merely a convention, so all (W) and (P) "
+    "installation directory.  Those marked with (U) are intended for "
+    "installations on UNIX platforms where the prefix is shared by "
+    "multiple packages.  This is merely a convention, so all (W) and (U) "
     "directories are still searched on all platforms.  "
     "Directories marked with (A) are intended for installations on "
     "Apple platforms.  The cmake variables CMAKE_FIND_FRAMEWORK and "