Help: Reformat install(DIRECTORY) options as a definition list

This makes it easier to find documentation for each option.
Previously they were sprinkled throughout prose.  It also
provides a good place for ``versionadded`` directives.

Help/command/install.rst

@@ -641,7 +641,7 @@ Signatures
 
   .. code-block:: cmake
 
-    install(DIRECTORY dirs...
+    install(DIRECTORY <dir>...
             TYPE <type> | DESTINATION <dir>
             [FILE_PERMISSIONS <permission>...]
             [DIRECTORY_PERMISSIONS <permission>...]
@@ -649,124 +649,164 @@ Signatures
             [CONFIGURATIONS <config>...]
             [COMPONENT <component>] [EXCLUDE_FROM_ALL]
             [FILES_MATCHING]
-            [[PATTERN <pattern> | REGEX <regex>]
-             [EXCLUDE] [PERMISSIONS <permission>...]] [...])
+            [<match-rule> <match-option>...]...
+            )
 
   The ``DIRECTORY`` form installs contents of one or more directories to a
   given destination.  The directory structure is copied verbatim to the
-  destination.  The last component of each directory name is appended to
-  the destination directory but a trailing slash may be used to avoid
-  this because it leaves the last component empty.  Directory names
-  given as relative paths are interpreted with respect to the current
-  source directory.  If no input directory names are given the
-  destination directory will be created but nothing will be installed
-  into it.  The ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` options
-  specify permissions given to files and directories in the destination.
-  If ``USE_SOURCE_PERMISSIONS`` is specified and ``FILE_PERMISSIONS`` is not,
-  file permissions will be copied from the source directory structure.
-  If no permissions are specified files will be given the default
-  permissions specified in the ``FILES`` form of the command, and the
-  directories will be given the default permissions specified in the
-  ``PROGRAMS`` form of the command.
-
-  .. versionadded:: 3.1
-    The ``MESSAGE_NEVER`` option disables file installation status output.
-
-  Installation of directories may be controlled with fine granularity
-  using the ``PATTERN`` or ``REGEX`` options.  These "match" options specify a
-  globbing pattern or regular expression to match directories or files
-  encountered within input directories.  They may be used to apply
-  certain options (see below) to a subset of the files and directories
-  encountered.  The full path to each input file or directory (with
-  forward slashes) is matched against the expression.  A ``PATTERN`` will
-  match only complete file names: the portion of the full path matching
-  the pattern must occur at the end of the file name and be preceded by
-  a slash.  A ``REGEX`` will match any portion of the full path but it may
-  use ``/`` and ``$`` to simulate the ``PATTERN`` behavior.  By default all
-  files and directories are installed whether or not they are matched.
-  The ``FILES_MATCHING`` option may be given before the first match option
-  to disable installation of files (but not directories) not matched by
-  any expression.  For example, the code
+  destination.
 
-  .. code-block:: cmake
+  Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
+  If no permissions is given, files will be given the default permissions
+  specified in the `FILES`_ form of the command, and the directories
+  will be given the default permissions specified in the `PROGRAMS`_
+  form of the command.
+
+  The options are:
+
+  ``<dir>...``
+    The list of directories to be installed.
+
+    The last component of each directory name is appended to the
+    destination directory but a trailing slash may be used to avoid
+    this because it leaves the last component empty.  Directory names
+    given as relative paths are interpreted with respect to the current
+    source directory.  If no input directory names are given the
+    destination directory will be created but nothing will be installed
+    into it.
+
+    .. versionadded:: 3.5
+      The source ``<dir>...`` list may use "generator expressions" with the
+      syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+      manual for available expressions.
+
+  ``TYPE <type>``
+    Specifies the generic file type of the files within the listed
+    directories being installed.  A destination will then be set
+    automatically by taking the corresponding variable from
+    :module:`GNUInstallDirs`, or by using a built-in default if that
+    variable is not defined.  See the table below for the supported
+    file types and their corresponding variables and built-in defaults.
+    Projects can provide a ``DESTINATION`` argument instead of a file
+    type if they wish to explicitly define the install destination.
+
+    ======================= ================================== =========================
+       ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
+    ======================= ================================== =========================
+    ``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
+    ``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
+    ``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
+    ``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
+    ``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
+    ``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
+    ``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
+    ``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
+    ``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
+    ``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
+    ``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
+    ``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
+    ``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+    ``LIBEXEC``             ``${CMAKE_INSTALL_LIBEXECDIR}``    ``libexec``
+    ======================= ================================== =========================
+
+    Note that some of the types' built-in defaults use the ``DATAROOT``
+    directory as a prefix.  The ``DATAROOT`` prefix is calculated similarly
+    to the types, with ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and
+    ``share`` as the built-in default.  You cannot use ``DATAROOT`` as a
+    ``TYPE`` parameter; please use ``DATA`` instead.
+
+    .. versionadded:: 3.31
+      The ``LIBEXEC`` type.
+
+  ``DESTINATION <dir>``
+    The destination directory, as documented among the `common options`_.
+
+    To make packages compliant with distribution filesystem layout
+    policies, if projects must specify a ``DESTINATION``, it is
+    strongly recommended that they use a path that begins with the
+    appropriate relative :module:`GNUInstallDirs` variable.
+    This allows package maintainers to control the install destination
+    by setting the appropriate cache variables.
+
+    .. versionadded:: 3.4
+      The destination ``<dir>`` may use "generator expressions" with the
+      syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+      manual for available expressions.
+
+  ``FILE_PERMISSIONS <permission>...``
+    Specify permissions given to files in the destination, where the
+    ``<permission>`` names are documented among the `common options`_.
+
+  ``DIRECTORY_PERMISSIONS <permission>...``
+    Specify permissions given to directories in the destination, where the
+    ``<permission>`` names are documented among the `common options`_.
+
+  ``USE_SOURCE_PERMISSIONS``
+    If specified, and ``FILE_PERMISSIONS`` is not, file permissions will
+    be copied from the source directory structure.
+
+  ``MESSAGE_NEVER``
+    .. versionadded:: 3.1
+
+    Disable file installation status output.
+
+  ``FILES_MATCHING``
+    This option may be given before the first ``<match-rule>`` to
+    disable installation of files (but not directories) not matched
+    by any expression.  For example, the code
 
-    install(DIRECTORY src/ DESTINATION doc/myproj
-            FILES_MATCHING PATTERN "*.png")
+    .. code-block:: cmake
 
-  will extract and install images from a source tree.
+      install(DIRECTORY src/ DESTINATION doc/myproj
+              FILES_MATCHING PATTERN "*.png")
 
-  Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
-  under :ref:`string(REGEX) <Regex Specification>` and are applied
-  only to files or directories matching them.  The ``EXCLUDE`` option will
-  skip the matched file or directory.  The ``PERMISSIONS`` option overrides
-  the permissions setting for the matched file or directory.  For
-  example the code
+    will extract and install images from a source tree.
 
-  .. code-block:: cmake
+  ``<match-rule> <match-option>...``
+    Installation of directories may be controlled with fine granularity
+    using rules that match directories or files encountered within input
+    directories.  They may be used to apply certain options (see below)
+    to a subset of the files and directories encountered.  All files
+    and directories are installed whether or not they are matched,
+    unless the above ``FILES_MATCHING`` option is given.
 
-    install(DIRECTORY icons scripts/ DESTINATION share/myproj
-            PATTERN "CVS" EXCLUDE
-            PATTERN "scripts/*"
-            PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
-                        GROUP_EXECUTE GROUP_READ)
+    The full path to each input file or directory, with forward slashes,
+    may be matched by a ``<match-rule>``:
 
-  will install the ``icons`` directory to ``share/myproj/icons`` and the
-  ``scripts`` directory to ``share/myproj``.  The icons will get default
-  file permissions, the scripts will be given specific permissions, and any
-  ``CVS`` directories will be excluded.
+    ``PATTERN <pattern>``
+      Match complete file names using a globbing pattern.  The portion of
+      the full path matching the pattern must occur at the end of the file
+      name and be preceded by a slash (which is not part of the pattern).
 
-  Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
-  A ``TYPE`` argument specifies the generic file type of the files within the
-  listed directories being installed.  A destination will then be set
-  automatically by taking the corresponding variable from
-  :module:`GNUInstallDirs`, or by using a built-in default if that variable
-  is not defined.  See the table below for the supported file types and their
-  corresponding variables and built-in defaults.  Projects can provide a
-  ``DESTINATION`` argument instead of a file type if they wish to explicitly
-  define the install destination.
+    ``REGEX <regex>``
+      Match any portion of the full path of a file with a
+      :ref:`regular expression <Regex Specification>`.
+      One may use ``/`` and ``$`` to limit matching to the end of a path.
 
-  ======================= ================================== =========================
-     ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
-  ======================= ================================== =========================
-  ``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
-  ``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
-  ``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
-  ``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
-  ``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
-  ``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
-  ``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
-  ``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
-  ``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
-  ``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
-  ``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
-  ``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
-  ``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
-  ``LIBEXEC``             ``${CMAKE_INSTALL_LIBEXECDIR}``    ``libexec``
-  ======================= ================================== =========================
+    Each ``<match-rule>`` may be followed by ``<match-option>`` arguments.
+    The match options apply to the files or directories matched by the rule.
+    The match options are:
 
-  Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
-  a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
-  ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
-  default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
-  ``DATA`` instead.
+    ``EXCLUDE``
+      Exclude the matched file or directory from installation.
 
-  To make packages compliant with distribution filesystem layout policies, if
-  projects must specify a ``DESTINATION``, it is strongly recommended that they use
-  a path that begins with the appropriate relative :module:`GNUInstallDirs` variable.
-  This allows package maintainers to control the install destination by setting
-  the appropriate cache variables.
+    ``PERMISSIONS <permission>...``
+      Ovrerride the permissions setting for the matched file or directory.
 
-  .. versionadded:: 3.4
-    An install destination given as a ``DESTINATION`` argument may
-    use "generator expressions" with the syntax ``$<...>``.  See the
-    :manual:`cmake-generator-expressions(7)` manual for available expressions.
+    For example, the code
 
-  .. versionadded:: 3.5
-    The list of ``dirs...`` given to ``DIRECTORY`` may use
-    "generator expressions" too.
+    .. code-block:: cmake
 
-  .. versionadded:: 3.31
-    The ``TYPE`` argument now supports type ``LIBEXEC``.
+      install(DIRECTORY icons scripts/ DESTINATION share/myproj
+              PATTERN "CVS" EXCLUDE
+              PATTERN "scripts/*"
+              PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
+                          GROUP_EXECUTE GROUP_READ)
+
+    will install the ``icons`` directory to ``share/myproj/icons`` and the
+    ``scripts`` directory to ``share/myproj``.  The icons will get default
+    file permissions, the scripts will be given specific permissions, and any
+    ``CVS`` directories will be excluded.
 
 .. signature::
   install(SCRIPT <file> [...])