find_package: Reword <package>_NO_INTERFACES documentation

1 files changed, 17 insertions, 18 deletions

diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index e9b6ab6..6e78bd7 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -376,26 +376,25 @@ void cmFindPackageCommand::GenerateDocumentation()
     "The package configuration file may set <package>_FOUND to false "
     "to tell find_package that component requirements are not satisfied."
     "\n"
-    "Targets exported by the install() command may have additional INTERFACE "
-    "properties set for include directories, compile definitions etc.  As "
-    "these may create a backward compatibility concern for consumers of "
-    "existing projects, it is possible to set the <package>_NO_INTERFACES "
-    "variable to disable populating those interfaces.  It is possible to "
-    "emulate a version-based policy for whether the interfaces should be "
-    "enabled in the config file before including the imported targets file. "
-    "This allows consumers to decide when to enable the new interfaces when "
-    "upgrading.  The upstream project is responsible for adding code similar "
-    "to this in the version which generates the INTERFACE content:\n"
-    "  if(${CMAKE_FIND_PACKAGE_NAME}_FIND_VERSION VERSION_LESS 2.3\n"
-    "      AND NOT ${CMAKE_FIND_PACKAGE_NAME}_INTERFACES)\n"
-    "    set(${CMAKE_FIND_PACKAGE_NAME}_NO_INTERFACES 1)\n"
+    "A package configuration file may include() a <package>Targets.cmake "
+    "file, created by install(EXPORT) in the upstream source, to import "
+    "targets into the downstream consumer.  "
+    "When a new version of the upstream adds INTERFACE properties not "
+    "present in a previous version it can change behavior for existing "
+    "downstreams.  "
+    "In order to remain source compatible the upstream package configuration "
+    "file may set <package>_NO_INTERFACES to disable INTERFACE properties.  "
+    "For example, code of the form:\n"
+    "  if(<package>_FIND_VERSION VERSION_LESS <new-version>\n"
+    "      AND NOT <package>_INTERFACES)\n"
+    "    set(<package>_NO_INTERFACES 1)\n"
     "  endif()\n"
     "  include(\"${CMAKE_CURRENT_LIST_DIR}/<package>Targets.cmake\")\n"
-    "\n"
-    "Downstream users may then choose to use the new interfaces by finding "
-    "the newer version of upstream.  They can also choose to not use the new "
-    "interfaces by setting <package>_INTERFACES to false before finding the "
-    "package.\n"
+    "tells <package>Targets.cmake not to provide the INTERFACE properties "
+    "unless the downstream requests at least <new-version> or sets "
+    "<package>_INTERFACES to explicitly request them.  "
+    "This allows consumers to decide when to enable the new interfaces when "
+    "upgrading."
     "\n"
     "See the cmake_policy() command documentation for discussion of the "
     "NO_POLICY_SCOPE option."