DeployQt4: Sync documentation

- Added note that this module is for Qt version 4 and newer version
  should be used.
- Added intro code block showing how to include this module.
- Used word "commands" instead of "functions".
- Added descriptions to commands.
- Used lowercase names of commands.

Modules/DeployQt4.cmake

@@ -5,13 +5,24 @@
 DeployQt4
 ---------
 
-This module provides a collection of CMake utility functions useful for
+.. note::
+
+  This module is for Qt version 4.  New code should follow the
+  :manual:`cmake-qt(7)` instead of using this module.
+
+This module provides a collection of CMake utility commands useful for
 assembling and deploying standalone Qt4 executables.
 
-Functions
+Load this module in a CMake project with:
-^^^^^^^^^
 
-This module defines the following functions:
+.. code-block:: cmake
+
+  include(DeployQt4)
+
+Commands
+^^^^^^^^
+
+This module provides the following commands:
 
 * :command:`write_qt4_conf`
 * :command:`resolve_qt4_paths`
@@ -22,36 +33,42 @@ This module defines the following functions:
 
 .. command:: write_qt4_conf
 
+  Creates a Qt configuration file:
+
   .. code-block:: cmake
 
-    write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
+    write_qt4_conf(<qt-conf-dir> <qt-conf-contents>)
 
-  Writes a ``qt.conf`` file with the ``<qt_conf_contents>`` into the
+  This command writes a ``qt.conf`` file with the ``<qt-conf-contents>`` into
-  ``<qt_conf_dir>`` directory.
+  the ``<qt-conf-dir>`` directory.
 
 .. command:: resolve_qt4_paths
 
+  Resolves relative paths to absolute:
+
   .. code-block:: cmake
 
-    resolve_qt4_paths(<paths_var> [<executable_path>])
+    resolve_qt4_paths(<paths-var> [<executable-path>])
 
-  Loops through the ``<paths_var>`` list and if any path doesn't exist, it
+  This command loops through the ``<paths-var>`` list and if any path doesn't
-  resolves them relative to the ``<executable_path>`` (if supplied) or the
+  exist, it resolves them relative to the ``<executable-path>`` (if supplied)
-  :variable:`CMAKE_INSTALL_PREFIX`.
+  or the :variable:`CMAKE_INSTALL_PREFIX`.
 
 .. command:: fixup_qt4_executable
 
+  Fixes up a Qt4 executable:
+
   .. code-block:: cmake
 
     fixup_qt4_executable(
       <executable>
-      [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>]
+      [<qtplugins> <libs> <dirs> <plugins-dir> <request-qt-conf>]
     )
 
-  Copies Qt plugins, writes a Qt configuration file (if needed) and fixes up a
+  This command copies Qt plugins, writes a Qt configuration file (if needed)
-  Qt4 executable using the :module:`BundleUtilities` module so it is standalone
+  and fixes up a Qt4 executable using the :module:`BundleUtilities` module
-  and can be drag-and-drop copied to another machine as long as all of the
+  so it is standalone and can be drag-and-drop copied to another machine as
-  system libraries are compatible.
+  long as all of the system libraries are compatible.
 
   ``<executable>`` should point to the executable to be fixed-up.
 
@@ -65,26 +82,28 @@ This module defines the following functions:
   ``<dirs>`` will be passed to the :module:`BundleUtilities` module and should
   contain directories to be searched to find library dependencies.
 
-  ``<plugins_dir>`` allows a custom plugins directory to be used.
+  ``<plugins-dir>`` allows a custom plugins directory to be used.
 
-  ``<request_qt_conf>`` will force a ``qt.conf`` file to be written even if not
+  ``<request-qt-conf>`` will force a ``qt.conf`` file to be written even if not
   needed.
 
 .. command:: install_qt4_plugin_path
 
+  Installs a resolved Qt4 plugin:
+
   .. code-block:: cmake
 
     install_qt4_plugin_path(
       <plugin>
       <executable>
       <copy>
-      <installed_plugin_path_var>
+      <installed-plugin-path-var>
-      [<plugins_dir> <component> <configurations>]
+      [<plugins-dir> <component> <configurations>]
     )
 
-  Installs (or copies) a resolved ``<plugin>`` to the default plugins directory
+  This command installs (or copies) a resolved ``<plugin>`` to the default
-  (or ``<plugins_dir>``) relative to ``<executable>`` and stores the result in
+  plugins directory (or ``<plugins-dir>``) relative to ``<executable>`` and
-  a variable ``<installed_plugin_path_var>``.
+  stores the result in a variable ``<installed-plugin-path-var>``.
 
   If ``<copy>`` is set to ``TRUE`` then the plugins will be copied rather than
   installed.  This is to allow this module to be used at CMake time rather than
@@ -94,36 +113,41 @@ This module defines the following functions:
 
 .. command:: install_qt4_plugin
 
+  Installs an unresolved Qt4 plugin:
+
   .. code-block:: cmake
 
     install_qt4_plugin(
       <plugin>
       <executable>
       <copy>
-      <installed_plugin_path_var>
+      <installed-plugin-path-var>
-      [<plugins_dir> <component>]
+      [<plugins-dir> <component>]
     )
 
-  Installs (or copies) an unresolved ``<plugin>`` to the default plugins
+  This command installs (or copies) an unresolved ``<plugin>`` to the default
-  directory (or ``<plugins_dir>``) relative to ``<executable>`` and stores the
+  plugins directory (or ``<plugins-dir>``) relative to ``<executable>`` and
-  result in a variable ``<installed_plugin_path_var>``.  For other arguments,
+  stores the result in a variable ``<installed-plugin-path-var>``.  For other
-  see also :command:`install_qt4_plugin_path`.
+  arguments, see also :command:`install_qt4_plugin_path`.
 
 .. command:: install_qt4_executable
 
+  Installs Qt plugins, writes a Qt configuration file (if needed) and fixes
+  up a Qt4 executable:
+
   .. code-block:: cmake
 
     install_qt4_executable(
       <executable>
-      [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>]
+      [<qtplugins> <libs> <dirs> <plugins-dir> <request-qt-conf> <component>]
     )
 
-  Installs Qt plugins, writes a Qt configuration file (if needed) and fixes up a
+  This command uses the :module:`BundleUtilities` module so executable is
-  Qt4 executable using the :module:`BundleUtilities` module so it is standalone
+  standalone and can be drag-and-drop copied to another machine as long as
-  and can be drag-and-drop copied to another machine as long as all of the
+  all of the system libraries are compatible.  The executable will be fixed-up
-  system libraries are compatible.  The executable will be fixed-up at install
+  at install time.  The ``<component>`` is the COMPONENT used for bundle fixup
-  time.  ``<component>`` is the COMPONENT used for bundle fixup and plugin
+  and plugin installation.  For other arguments, see also
-  installation.  For other arguments, see also :command:`fixup_qt4_executable`.
+  :command:`fixup_qt4_executable`.
 #]=======================================================================]
 
 # The functions defined in this file depend on the fixup_bundle function
@@ -416,7 +440,7 @@ function(install_qt4_executable executable)
   install(CODE
 "include(\"${CMAKE_CURRENT_FUNCTION_LIST_DIR}/DeployQt4.cmake\")
 set(BU_CHMOD_BUNDLE_ITEMS TRUE)
-FIXUP_QT4_EXECUTABLE(\"\$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/${executable}\" \"\" \"${libs}\" \"${dirs}\" \"${plugins_dir}\" \"${request_qt_conf}\")"
+fixup_qt4_executable(\"\$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/${executable}\" \"\" \"${libs}\" \"${dirs}\" \"${plugins_dir}\" \"${request_qt_conf}\")"
           ${component}
   )
 endfunction()