GNUInstallDirs: Improve documentation formatting

Also consolidate the description of each variable.

1 files changed, 32 insertions, 27 deletions

diff --git a/Modules/GNUInstallDirs.cmake b/Modules/GNUInstallDirs.cmake
index c61e7e9a1a..82258d1dbe 100644
--- a/Modules/GNUInstallDirs.cmake
+++ b/Modules/GNUInstallDirs.cmake
@@ -4,57 +4,62 @@
 #
 # Define GNU standard installation directories
 #
-# Provides install directory variables as defined for GNU software:
+# Provides install directory variables as defined by the
+# `GNU Coding Standards`_.
 #
-#   http://www.gnu.org/prep/standards/html_node/Directory-Variables.html
+# .. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
 #
 # Inclusion of this module defines the following variables:
 #
 # ``CMAKE_INSTALL_<dir>``
-#   destination for files of a given type
+#
+#   Destination for files of a given type.  This value may be passed to
+#   the ``DESTINATION`` options of :command:`install` commands for the
+#   corresponding file type.
+#
 # ``CMAKE_INSTALL_FULL_<dir>``
-#   corresponding absolute path
 #
-# where <dir> is one of:
+#   The absolute path generated from the corresponding ``CMAKE_INSTALL_<dir>``
+#   value.  If the value is not already an absolute path, an absolute path
+#   is constructed typically by prepending the value of the
+#   :variable:`CMAKE_INSTALL_PREFIX` variable.
+#
+# where ``<dir>`` is one of:
 #
 # ``BINDIR``
-#   user executables (bin)
+#   user executables (``bin``)
 # ``SBINDIR``
-#   system admin executables (sbin)
+#   system admin executables (``sbin``)
 # ``LIBEXECDIR``
-#   program executables (libexec)
+#   program executables (``libexec``)
 # ``SYSCONFDIR``
-#   read-only single-machine data (etc)
+#   read-only single-machine data (``etc``)
 # ``SHAREDSTATEDIR``
-#   modifiable architecture-independent data (com)
+#   modifiable architecture-independent data (``com``)
 # ``LOCALSTATEDIR``
-#   modifiable single-machine data (var)
+#   modifiable single-machine data (``var``)
 # ``LIBDIR``
-#   object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian)
+#   object code libraries (``lib`` or ``lib64``
+#   or ``lib/<multiarch-tuple>`` on Debian)
 # ``INCLUDEDIR``
-#   C header files (include)
+#   C header files (``include``)
 # ``OLDINCLUDEDIR``
-#   C header files for non-gcc (/usr/include)
+#   C header files for non-gcc (``/usr/include``)
 # ``DATAROOTDIR``
-#   read-only architecture-independent data root (share)
+#   read-only architecture-independent data root (``share``)
 # ``DATADIR``
-#   read-only architecture-independent data (DATAROOTDIR)
+#   read-only architecture-independent data (``DATAROOTDIR``)
 # ``INFODIR``
-#   info documentation (DATAROOTDIR/info)
+#   info documentation (``DATAROOTDIR/info``)
 # ``LOCALEDIR``
-#   locale-dependent data (DATAROOTDIR/locale)
+#   locale-dependent data (``DATAROOTDIR/locale``)
 # ``MANDIR``
-#   man documentation (DATAROOTDIR/man)
+#   man documentation (``DATAROOTDIR/man``)
 # ``DOCDIR``
-#   documentation root (DATAROOTDIR/doc/PROJECT_NAME)
+#   documentation root (``DATAROOTDIR/doc/PROJECT_NAME``)
 #
-# Each CMAKE_INSTALL_<dir> value may be passed to the DESTINATION
-# options of install() commands for the corresponding file type.  If the
-# includer does not define a value the above-shown default will be used
-# and the value will appear in the cache for editing by the user.  Each
-# CMAKE_INSTALL_FULL_<dir> value contains an absolute path constructed
-# from the corresponding destination by prepending (if necessary) the
-# value of CMAKE_INSTALL_PREFIX.
+# If the includer does not define a value the above-shown default will be
+# used and the value will appear in the cache for editing by the user.
 
 #=============================================================================
 # Copyright 2011 Nikita Krupen'ko <krnekit@gmail.com>