UsePkgConfig: Update documentation

This module is deprecated yet still documentation output can be improved
a bit to provide relevant info where to go instead and how to "migrate"
to FindPkgConfig. Also in the near future, this can be further extended
or adjusted with `cmake_pkg_config()` built-in command.

Modules/UsePkgConfig.cmake

@@ -6,18 +6,81 @@ UsePkgConfig
 ------------
 
 .. deprecated:: 3.0
-  Use :module:`FindPkgConfig` instead.
+
+  This module should no longer be used.  Instead, use the
+  :module:`FindPkgConfig` module or the :command:`cmake_pkg_config` command.
+
+  This module provided a macro for finding external packages using
+  ``pkg-config`` command-line utility.  It has been replaced by the more
+  convenient ``FindPkgConfig`` module, which is commonly used in
+  :ref:`Find Modules`.
+
+  As of CMake 3.31, the built-in :command:`cmake_pkg_config` command provides
+  even more features to extract package information.
+
+Macros
+^^^^^^
 
 This module defines the following macro:
 
-PKGCONFIG(package includedir libdir linkflags cflags)
+.. command:: pkgconfig
 
-Calling PKGCONFIG will fill the desired information into the 4 given
+  Finds external package using ``pkg-config`` and sets result variables:
-arguments, e.g.  PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
+
-LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
+  .. code-block:: cmake
-found or the specified software package doesn't exist, the variable
+
-will be empty when the function returns, otherwise they will contain
+    pkgconfig(<package> <includedir> <libdir> <linkflags> <cflags>)
-the respective information
+
+  This macro invokes ``pkg-config`` command-line utility to retrieve the package
+  information into specified variables.  If ``pkg-config`` or the specified
+  package ``<package>`` is NOT found, the result variables remain empty.
+
+  The arguments are:
+
+  ``<package>``
+    Name of the package as defined in its PC metadata file (``<package>.pc``).
+
+  ``<includedir>``
+    Variable name to store the package's include directory.
+
+  ``<libdir>``
+    Variable name to store the directory containing the package library.
+
+  ``<linkflags>``
+    Variable name to store the linker flags for the package.
+
+  ``<cflags>``
+    Variable name to store the compiler flags for the package.
+
+Examples
+^^^^^^^^
+
+Using this module fills the desired information into the four given variables:
+
+.. code-block:: cmake
+
+  include(UsePkgConfig)
+  pkgconfig(
+    libart-2.0
+    LIBART_INCLUDEDIR
+    LIBART_LIBDIR
+    LIBART_LDFLAGS
+    LIBART_CFLAGS
+  )
+
+Migrating to the :module:`FindPkgConfig`  would look something like this:
+
+.. code-block:: cmake
+
+  find_package(PkgConfig QUIET)
+  if(PKG_CONFIG_FOUND)
+    pkg_check_modules(LIBART QUIET libart-2.0)
+  endif()
+
+  message(STATUS "LIBART_INCLUDEDIR=${LIBART_INCLUDEDIR}")
+  message(STATUS "LIBART_LIBDIR=${LIBART_LIBDIR}")
+  message(STATUS "LIBART_LDFLAGS=${LIBART_LDFLAGS}")
+  message(STATUS "LIBART_CFLAGS=${LIBART_CFLAGS}")
 #]=======================================================================]
 
 find_program(PKGCONFIG_EXECUTABLE NAMES pkg-config )