Help: Improve documentation formatting of find_* commands

Use inline reStructuredText markup and add cross-references in more
places.

6 files changed, 114 insertions, 90 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 474127d..966db06 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -33,36 +33,42 @@ and the search will not be repeated unless the variable is cleared.
 If nothing is found, the result will be
 ``<VAR>-NOTFOUND``, and the search will be attempted again the
 next time |FIND_XXX| is invoked with the same variable.
-The name of the |SEARCH_XXX| that
-is searched for is specified by the names listed
-after the NAMES argument.   Additional search locations
-can be specified after the PATHS argument.  If ENV var is
-found in the HINTS or PATHS section the environment variable var
-will be read and converted from a system environment variable to
-a cmake style list of paths.  For example ENV PATH would be a way
-to list the system path variable. The argument
-after DOC will be used for the documentation string in
-the cache.
-PATH_SUFFIXES specifies additional subdirectories to check below
-each search path.
-
-If NO_DEFAULT_PATH is specified, then no additional paths are
+
+Options include:
+
+``NAMES``
+  Specify one or more possible names for the |SEARCH_XXX|.
+
+``HINTS``, ``PATHS``
+  Specify directories to search in addition to the default locations.
+  The ``ENV var`` sub-option reads paths from a system environment
+  variable.
+
+``PATH_SUFFIXES``
+  Specify additional subdirectories to check below each directory
+  location otherwise considered.
+
+``DOC``
+  Specify the documentation string for the ``<VAR>`` cache entry.
+
+If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
 added to the search.
-If NO_DEFAULT_PATH is not specified, the search process is as follows:
+If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 
 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
-   <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH
+   |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
 
 .. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
-   <prefix>/|XXX_SUBDIR| for each <prefix>/[s]bin in PATH, and
-   <entry>/|XXX_SUBDIR| for other entries in PATH
+   |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
+   |entry_XXX_SUBDIR| for other entries in ``PATH``
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
-   <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
+   |prefix_XXX_SUBDIR| for each ``<prefix>`` in
+   :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 
 1. Search paths specified in cmake-specific cache variables.
-   These are intended to be used on the command line with a -DVAR=value.
-   This can be skipped if NO_CMAKE_PATH is passed.
+   These are intended to be used on the command line with a ``-DVAR=value``.
+   This can be skipped if ``NO_CMAKE_PATH`` is passed.
 
    * |CMAKE_PREFIX_PATH_XXX|
    * |CMAKE_XXX_PATH|
@@ -70,24 +76,24 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows:
 
 2. Search paths specified in cmake-specific environment variables.
    These are intended to be set in the user's shell configuration.
-   This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
+   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
 
    * |CMAKE_PREFIX_PATH_XXX|
    * |CMAKE_XXX_PATH|
    * |CMAKE_XXX_MAC_PATH|
 
-3. Search the paths specified by the HINTS option.
+3. Search the paths specified by the ``HINTS`` option.
    These should be paths computed by system introspection, such as a
    hint provided by the location of another item already found.
-   Hard-coded guesses should be specified with the PATHS option.
+   Hard-coded guesses should be specified with the ``PATHS`` option.
 
 4. Search the standard system environment variables.
-   This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
+   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
 
    * |SYSTEM_ENVIRONMENT_PATH_XXX|
 
 5. Search cmake variables defined in the Platform files
-   for the current system.  This can be skipped if NO_CMAKE_SYSTEM_PATH
+   for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
    is passed.
 
    * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt
index b5cab68..fab2303 100644
--- a/Help/command/FIND_XXX_ROOT.txt
+++ b/Help/command/FIND_XXX_ROOT.txt
@@ -16,8 +16,14 @@ search there too.  By default at first the directories listed in
 directory is searched, and then the non-rooted directories will be
 searched.  The default behavior can be adjusted by setting
 |CMAKE_FIND_ROOT_PATH_MODE_XXX|.  This behavior can be manually
-overridden on a per-call basis.  By using CMAKE_FIND_ROOT_PATH_BOTH
-the search order will be as described above.  If
-NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be
-used.  If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched.
+overridden on a per-call basis using options:
+
+``CMAKE_FIND_ROOT_PATH_BOTH``
+  Search in the order described above.
+
+``NO_CMAKE_FIND_ROOT_PATH``
+  Do not use the :variable:`CMAKE_FIND_ROOT_PATH` variable.
+
+``ONLY_CMAKE_FIND_ROOT_PATH``
+  Search only the re-rooted directories and directories below
+  :variable:`CMAKE_STAGING_PREFIX`.
diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst
index be309a5..bf7a919 100644
--- a/Help/command/find_file.rst
+++ b/Help/command/find_file.rst
@@ -5,24 +5,27 @@ find_file
 .. |NAMES| replace:: NAMES name1 [name2 ...]
 .. |SEARCH_XXX| replace:: full path to a file
 .. |SEARCH_XXX_DESC| replace:: full path to named file
-.. |XXX_SUBDIR| replace:: include
+.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
+.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
 
 .. |CMAKE_PREFIX_PATH_XXX| replace::
-   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |CMAKE_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
-.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
+.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
-   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
-   and the directories in PATH itself.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``,
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
+   directories in ``PATH`` itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
-   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH
-.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_SYSTEM_XXX_PATH| replace::
+   :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
+.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
+   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
    :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst
index e3dcd2b..5d07574 100644
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@@ -5,33 +5,36 @@ find_library
 .. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
 .. |SEARCH_XXX| replace:: library
 .. |SEARCH_XXX_DESC| replace:: library
-.. |XXX_SUBDIR| replace:: lib
+.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
+.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
 
 .. |CMAKE_PREFIX_PATH_XXX| replace::
-   <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |CMAKE_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH
-.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
+   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+   and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
+.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in LIB,
-   <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
-   and the directories in PATH itself.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``,
+   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+   and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
+   and the directories in ``PATH`` itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
-   <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_LIBRARY_PATH
-.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
+   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+   and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_SYSTEM_XXX_PATH| replace::
+   :variable:`CMAKE_SYSTEM_LIBRARY_PATH`
+.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
+   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
    :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
 
 .. include:: FIND_XXX.txt
 
-When more than one value is given to the NAMES option this command by
+When more than one value is given to the ``NAMES`` option this command by
 default will consider one name at a time and search every directory
-for it.  The NAMES_PER_DIR option tells this command to consider one
+for it.  The ``NAMES_PER_DIR`` option tells this command to consider one
 directory at a time and search for all names in it.
 
 Each library name given to the ``NAMES`` option is first considered
@@ -40,14 +43,14 @@ prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``).  Therefore one
 may specify library file names such as ``libfoo.a`` directly.
 This can be used to locate static libraries on UNIX-like systems.
 
-If the library found is a framework, then VAR will be set to the full
-path to the framework <fullPath>/A.framework.  When a full path to a
-framework is used as a library, CMake will use a -framework A, and a
--F<fullPath> to link the framework to the target.
+If the library found is a framework, then ``<VAR>`` will be set to the full
+path to the framework ``<fullPath>/A.framework``.  When a full path to a
+framework is used as a library, CMake will use a ``-framework A``, and a
+``-F<fullPath>`` to link the framework to the target.
 
-If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all search
-paths will be tested as normal, with "64/" appended, and with all
-matches of "lib/" replaced with "lib64/".  This property is
+If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
+all search paths will be tested as normal, with ``64/`` appended, and
+with all matches of ``lib/`` replaced with ``lib64/``.  This property is
 automatically set for the platforms that are known to need it if at
-least one of the languages supported by the PROJECT command is
-enabled.
+least one of the languages supported by the :command:`project` command
+is enabled.
diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst
index b5a6e37..4403cb5 100644
--- a/Help/command/find_path.rst
+++ b/Help/command/find_path.rst
@@ -5,31 +5,34 @@ find_path
 .. |NAMES| replace:: NAMES name1 [name2 ...]
 .. |SEARCH_XXX| replace:: file in a directory
 .. |SEARCH_XXX_DESC| replace:: directory containing the named file
-.. |XXX_SUBDIR| replace:: include
+.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
+.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
 
 .. |CMAKE_PREFIX_PATH_XXX| replace::
-   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |CMAKE_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
-.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
+.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
-   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
-   and the directories in PATH itself.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``,
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
+   directories in ``PATH`` itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
-   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
-   |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH
-.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_SYSTEM_XXX_PATH| replace::
+   :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
+.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
+   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
    :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
 
 .. include:: FIND_XXX.txt
 
-When searching for frameworks, if the file is specified as A/b.h, then
-the framework search will look for A.framework/Headers/b.h.  If that
+When searching for frameworks, if the file is specified as ``A/b.h``, then
+the framework search will look for ``A.framework/Headers/b.h``.  If that
 is found the path will be set to the path to the framework.  CMake
-will convert this to the correct -F option to include the file.
+will convert this to the correct ``-F`` option to include the file.
diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst
index c62a8a5..2a5ce9a 100644
--- a/Help/command/find_program.rst
+++ b/Help/command/find_program.rst
@@ -5,19 +5,22 @@ find_program
 .. |NAMES| replace:: NAMES name1 [name2 ...]
 .. |SEARCH_XXX| replace:: program
 .. |SEARCH_XXX_DESC| replace:: program
-.. |XXX_SUBDIR| replace:: [s]bin
+.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
+.. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
 
 .. |CMAKE_PREFIX_PATH_XXX| replace::
    |CMAKE_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_XXX_PATH| replace:: CMAKE_PROGRAM_PATH
-.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_APPBUNDLE_PATH
+.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
+.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH``
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
-.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_PROGRAM_PATH
-.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH
+.. |CMAKE_SYSTEM_XXX_PATH| replace::
+   :variable:`CMAKE_SYSTEM_PROGRAM_PATH`
+.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
+   :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
 
 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
    :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`