FindPerl: Update documentation

- Added example.
- Docs synced with other similar find modules.
- Perl_FOUND and PERL_FOUND variables are always set as of CMake 3.3 to
  the same value.

Modules/FindCxxTest.cmake

@@ -194,10 +194,10 @@ find_program(CXXTEST_PYTHON_TESTGEN_EXECUTABLE
 find_program(CXXTEST_PERL_TESTGEN_EXECUTABLE cxxtestgen.pl
          PATHS ${CXXTEST_INCLUDE_DIR})
 
-if(PYTHON_FOUND OR PERL_FOUND)
+if(PYTHON_FOUND OR Perl_FOUND)
   include(FindPackageHandleStandardArgs)
 
-  if(PYTHON_FOUND AND (CXXTEST_USE_PYTHON OR NOT PERL_FOUND OR NOT DEFINED CXXTEST_USE_PYTHON))
+  if(PYTHON_FOUND AND (CXXTEST_USE_PYTHON OR NOT Perl_FOUND OR NOT DEFINED CXXTEST_USE_PYTHON))
     set(CXXTEST_TESTGEN_EXECUTABLE ${CXXTEST_PYTHON_TESTGEN_EXECUTABLE})
     execute_process(COMMAND ${CXXTEST_PYTHON_TESTGEN_EXECUTABLE} --version
       OUTPUT_VARIABLE _CXXTEST_OUT ERROR_VARIABLE _CXXTEST_OUT RESULT_VARIABLE _CXXTEST_RESULT)
@@ -209,7 +209,7 @@ if(PYTHON_FOUND OR PERL_FOUND)
     find_package_handle_standard_args(CxxTest DEFAULT_MSG
         CXXTEST_INCLUDE_DIR CXXTEST_PYTHON_TESTGEN_EXECUTABLE)
 
-  elseif(PERL_FOUND)
+  elseif(Perl_FOUND)
     set(CXXTEST_TESTGEN_EXECUTABLE ${CXXTEST_PERL_TESTGEN_EXECUTABLE})
     set(CXXTEST_TESTGEN_INTERPRETER ${PERL_EXECUTABLE})
     find_package_handle_standard_args(CxxTest DEFAULT_MSG

Modules/FindPerl.cmake

@@ -5,20 +5,39 @@
 FindPerl
 --------
 
-Find a Perl interpreter.
+Finds a Perl interpreter.  Perl is a general-purpose, interpreted, dynamic
+programming language.
+
+Result Variables
+^^^^^^^^^^^^^^^^
 
 This module defines the following variables:
 
-``PERL_EXECUTABLE``
-  The full path to Perl.
-
-``PERL_FOUND``
-  True if the Perl executable was found.
+``Perl_FOUND``
+  True if the Perl executable was found.  For backward compatibility, the
+  ``PERL_FOUND`` variable is also set to the same value.
 
 ``PERL_VERSION_STRING``
   .. versionadded:: 2.8.8
 
   The version of Perl found.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``PERL_EXECUTABLE``
+  Full path to the ``perl`` executable.
+
+Examples
+^^^^^^^^
+
+Finding the Perl interpreter:
+
+.. code-block:: cmake
+
+  find_package(Perl)
 #]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/FindCygwin.cmake)