FindSubversion: Sync documentation

- Added intro code block with find_package() showing how to find the
  package using this module.
- Used "commands" instead of "macros".
- Synced one missed SUBVERSION_FOUND variable in code to
  Subversion_FOUND (available as of CMake 3.3.).
- Synced few descriptions with other similar find modules.

Modules/FindSubversion.cmake

@@ -5,8 +5,12 @@
 FindSubversion
 --------------
 
-This module finds a Subversion command-line client executable (``svn``) and
-provides macros for extracting information from a Subversion working copy.
+Finds a Subversion command-line client executable (``svn``) and provides
+commands for extracting information from a Subversion working copy:
+
+.. code-block:: cmake
+
+  find_package(Subversion [<version>] [...])
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -14,12 +18,12 @@ Result Variables
 This module defines the following variables:
 
 ``Subversion_FOUND``
-  True if the Subversion command-line client was found.  For backward
-  compatibility, the ``SUBVERSION_FOUND`` variable is also set to the same
-  value.
+  Boolean indicating whether (the requested version of) Subversion command-line
+  client is found.  For backward compatibility, the ``SUBVERSION_FOUND``
+  variable is also set to the same value.
 
 ``Subversion_VERSION_SVN``
-  Version of the ``svn`` command-line client.
+  Version of the ``svn`` command-line client found.
 
 Cache Variables
 ^^^^^^^^^^^^^^^
@@ -29,11 +33,11 @@ The following cache variables may also be set:
 ``Subversion_SVN_EXECUTABLE``
   Path to the ``svn`` command-line client.
 
-Macros
-^^^^^^
+Commands
+^^^^^^^^
 
-If the Subversion command-line client is found, the following macros are
-defined:
+This module provides the following commands if the Subversion command-line
+client is found:
 
 .. command:: Subversion_WC_INFO
 
@@ -44,7 +48,7 @@ defined:
 
     Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
 
-  This macro defines the following variables if running Subversion's ``info``
+  This command defines the following variables if running Subversion's ``info``
   subcommand on ``<dir>`` succeeds; otherwise a ``SEND_ERROR`` message is
   generated:
 
@@ -81,7 +85,7 @@ defined:
 
     Subversion_WC_LOG(<dir> <var-prefix>)
 
-  This macro defines the following variable if running Subversion's ``log``
+  This command defines the following variable if running Subversion's ``log``
   subcommand on ``<dir>`` succeeds; otherwise a ``SEND_ERROR`` message is
   generated:
 
@@ -92,7 +96,33 @@ defined:
 Examples
 ^^^^^^^^
 
-Example usage:
+Examples: Finding Subversion
+""""""""""""""""""""""""""""
+
+Finding Subversion:
+
+.. code-block:: cmake
+
+  find_package(Subversion)
+
+Or, finding Subversion and specifying a minimum required version:
+
+.. code-block:: cmake
+
+  find_package(Subversion 1.4)
+
+Or, finding Subversion and making it required (if not found, processing stops
+with an error message):
+
+.. code-block:: cmake
+
+  find_package(Subversion REQUIRED)
+
+Example: Using Subversion
+"""""""""""""""""""""""""
+
+Finding Subversion and retrieving information about the current project's
+working copy:
 
 .. code-block:: cmake
 
@@ -103,13 +133,6 @@ Example usage:
     Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
     message("Last changed log is ${Project_LAST_CHANGED_LOG}")
   endif()
-
-The minimum required version of Subversion can be specified using the standard
-syntax:
-
-.. code-block:: cmake
-
-  find_package(Subversion 1.4)
 #]=======================================================================]
 
 find_program(Subversion_SVN_EXECUTABLE svn
@@ -209,4 +232,4 @@ find_package_handle_standard_args(Subversion REQUIRED_VARS Subversion_SVN_EXECUT
                                              VERSION_VAR Subversion_VERSION_SVN )
 
 # for compatibility
-set(Subversion_SVN_FOUND ${SUBVERSION_FOUND})
+set(Subversion_SVN_FOUND ${Subversion_FOUND})