Help: Improve documentation formatting of find_* commands

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

1 files changed, 32 insertions, 26 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|