From d4faed2f7ffa1267b52e0cce9c0c32d8f88b6abc Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Tue, 10 May 2016 09:35:48 -0400
Subject: [PATCH] Help: Document `cmake --find-package` as a separate command
 mode

---
 Help/manual/cmake.1.rst | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 3ae2bafc5..12b401244 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -82,12 +82,7 @@ Options
  done before the -P argument.
 
 ``--find-package``
- Run in pkg-config like mode.
-
- Search a package using find_package() and print the resulting flags
- to stdout.  This can be used to use cmake instead of pkg-config to
- find installed libraries in plain Makefile-based projects or in
- autoconf-based projects (via share/aclocal/cmake.m4).
+ See `Find-Package Tool Mode`_.
 
 ``--graphviz=[file]``
  Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more.
@@ -278,6 +273,24 @@ The following ``cmake -E`` commands are available only on Windows:
 ``write_regv <key> <value>``
   Write Windows registry value.
 
+Find-Package Tool Mode
+======================
+
+CMake provides a helper for Makefile-based projects with the signature::
+
+  cmake --find-package <options>...
+
+This runs in a pkg-config like mode.
+
+Search a package using :command:`find_package()` and print the resulting flags
+to stdout.  This can be used to use cmake instead of pkg-config to find
+installed libraries in plain Makefile-based projects or in autoconf-based
+projects (via ``share/aclocal/cmake.m4``).
+
+.. note::
+  This mode is not well-supported due to some technical limitations.
+  It is kept for compatibility but should not be used in new projects.
+
 See Also
 ========