Help: Convert signatures of list and set commands

Convert documentation of the `list` and `set` commands to use new
`signature` directive. Use new `cref` role in the `list` introduction so
that the subcommands there are links rather than just text. Turn
references into `string` subcommands into actual links. Reformat some
prose as definition lists.

2 files changed, 248 insertions, 277 deletions

diff --git a/Help/command/list.rst b/Help/command/list.rst
index 33c4f80d24..191003a700 100644
--- a/Help/command/list.rst
+++ b/Help/command/list.rst
@@ -36,23 +36,25 @@ Synopsis
 Introduction
 ^^^^^^^^^^^^
 
-The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``,
-``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
-``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
-new values for the list within the current CMake variable scope.  Similar to
-the :command:`set` command, the LIST command creates new variable values in
-the current scope, even if the list itself is actually defined in a parent
-scope.  To propagate the results of these operations upwards, use
-:command:`set` with ``PARENT_SCOPE``, :command:`set` with
-``CACHE INTERNAL``, or some other means of value propagation.
+The list subcommands :cref:`APPEND`, :cref:`INSERT`, :cref:`FILTER`,
+:cref:`PREPEND`, :cref:`POP_BACK`, :cref:`POP_FRONT`, :cref:`REMOVE_AT`,
+:cref:`REMOVE_ITEM`, :cref:`REMOVE_DUPLICATES`, :cref:`REVERSE` and
+:cref:`SORT` may create new values for the list within the current CMake
+variable scope.  Similar to the :command:`set` command, the ``list`` command
+creates new variable values in the current scope, even if the list itself is
+actually defined in a parent scope.  To propagate the results of these
+operations upwards, use :command:`set` with ``PARENT_SCOPE``,
+:command:`set` with ``CACHE INTERNAL``, or some other means of value
+propagation.
 
 .. note::
 
   A list in cmake is a ``;`` separated group of strings.  To create a
-  list the set command can be used.  For example, ``set(var a b c d e)``
-  creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a
-  string or a list with one item in it.   (Note macro arguments are not
-  variables, and therefore cannot be used in LIST commands.)
+  list, the :command:`set` command can be used.  For example,
+  ``set(var a b c d e)`` creates a list with ``a;b;c;d;e``, and
+  ``set(var "a b c d e")`` creates a string or a list with one item in it.
+  (Note that macro arguments are not variables, and therefore cannot be used
+  in ``LIST`` commands.)
 
 .. note::
 
@@ -66,76 +68,54 @@ scope.  To propagate the results of these operations upwards, use
 Reading
 ^^^^^^^
 
-.. _LENGTH:
-
-.. code-block:: cmake
-
+.. signature::
   list(LENGTH <list> <output variable>)
 
-Returns the list's length.
-
-.. _GET:
-
-.. code-block:: cmake
+  Returns the list's length.
 
+.. signature::
   list(GET <list> <element index> [<element index> ...] <output variable>)
 
-Returns the list of elements specified by indices from the list.
-
-.. _JOIN:
+  Returns the list of elements specified by indices from the list.
 
-.. code-block:: cmake
+.. signature:: list(JOIN <list> <glue> <output variable>)
 
-  list(JOIN <list> <glue> <output variable>)
+  .. versionadded:: 3.12
 
-.. versionadded:: 3.12
-
-Returns a string joining all list's elements using the glue string.
-To join multiple strings, which are not part of a list, use ``JOIN`` operator
-from :command:`string` command.
-
-.. _SUBLIST:
-
-.. code-block:: cmake
+  Returns a string joining all list's elements using the glue string.
+  To join multiple strings, which are not part of a list,
+  use :command:`string(JOIN)`.
 
+.. signature::
   list(SUBLIST <list> <begin> <length> <output variable>)
 
-.. versionadded:: 3.12
+  .. versionadded:: 3.12
 
-Returns a sublist of the given list.
-If ``<length>`` is 0, an empty list will be returned.
-If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
-the remaining elements of the list starting at ``<begin>`` will be returned.
+  Returns a sublist of the given list.
+  If ``<length>`` is 0, an empty list will be returned.
+  If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then
+  the remaining elements of the list starting at ``<begin>`` will be returned.
 
 Search
 ^^^^^^
 
-.. _FIND:
-
-.. code-block:: cmake
-
+.. signature::
   list(FIND <list> <value> <output variable>)
 
-Returns the index of the element specified in the list or -1
-if it wasn't found.
+  Returns the index of the element specified in the list
+  or ``-1`` if it wasn't found.
 
 Modification
 ^^^^^^^^^^^^
 
-.. _APPEND:
-
-.. code-block:: cmake
-
+.. signature::
   list(APPEND <list> [<element> ...])
 
-Appends elements to the list. If no variable named ``<list>`` exists in the
-current scope its value is treated as empty and the elements are appended to
-that empty list.
-
-.. _FILTER:
-
-.. code-block:: cmake
+  Appends elements to the list. If no variable named ``<list>`` exists in the
+  current scope its value is treated as empty and the elements are appended to
+  that empty list.
 
+.. signature::
   list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
 
 .. versionadded:: 3.6
@@ -146,219 +126,205 @@ In ``REGEX`` mode, items will be matched against the given regular expression.
 For more information on regular expressions look under
 :ref:`string(REGEX) <Regex Specification>`.
 
-.. _INSERT:
-
-.. code-block:: cmake
-
+.. signature::
   list(INSERT <list> <element_index> <element> [<element> ...])
 
-Inserts elements to the list to the specified index. It is an
-error to specify an out-of-range index. Valid indexes are 0 to `N`
-where `N` is the length of the list, inclusive. An empty list
-has length 0. If no variable named ``<list>`` exists in the
-current scope its value is treated as empty and the elements are
-inserted in that empty list.
-
-.. _POP_BACK:
-
-.. code-block:: cmake
+  Inserts elements to the list to the specified index. It is an
+  error to specify an out-of-range index. Valid indexes are 0 to `N`
+  where `N` is the length of the list, inclusive. An empty list
+  has length 0. If no variable named ``<list>`` exists in the
+  current scope its value is treated as empty and the elements are
+  inserted in that empty list.
 
+.. signature::
   list(POP_BACK <list> [<out-var>...])
 
-.. versionadded:: 3.15
+  .. versionadded:: 3.15
 
-If no variable name is given, removes exactly one element. Otherwise,
-with `N` variable names provided, assign the last `N` elements' values
-to the given variables and then remove the last `N` values from
-``<list>``.
-
-.. _POP_FRONT:
-
-.. code-block:: cmake
+  If no variable name is given, removes exactly one element. Otherwise,
+  with `N` variable names provided, assign the last `N` elements' values
+  to the given variables and then remove the last `N` values from
+  ``<list>``.
 
+.. signature::
   list(POP_FRONT <list> [<out-var>...])
 
-.. versionadded:: 3.15
-
-If no variable name is given, removes exactly one element. Otherwise,
-with `N` variable names provided, assign the first `N` elements' values
-to the given variables and then remove the first `N` values from
-``<list>``.
+  .. versionadded:: 3.15
 
-.. _PREPEND:
-
-.. code-block:: cmake
+  If no variable name is given, removes exactly one element. Otherwise,
+  with `N` variable names provided, assign the first `N` elements' values
+  to the given variables and then remove the first `N` values from
+  ``<list>``.
 
+.. signature::
   list(PREPEND <list> [<element> ...])
 
-.. versionadded:: 3.15
-
-Insert elements to the 0th position in the list. If no variable named
-``<list>`` exists in the current scope its value is treated as empty and
-the elements are prepended to that empty list.
+  .. versionadded:: 3.15
 
-.. _REMOVE_ITEM:
-
-.. code-block:: cmake
+  Insert elements to the 0th position in the list. If no variable named
+  ``<list>`` exists in the current scope its value is treated as empty and
+  the elements are prepended to that empty list.
 
+.. signature::
   list(REMOVE_ITEM <list> <value> [<value> ...])
 
-Removes all instances of the given items from the list.
-
-.. _REMOVE_AT:
-
-.. code-block:: cmake
+  Removes all instances of the given items from the list.
 
+.. signature::
   list(REMOVE_AT <list> <index> [<index> ...])
 
-Removes items at given indices from the list.
-
-.. _REMOVE_DUPLICATES:
-
-.. code-block:: cmake
+  Removes items at given indices from the list.
 
+.. signature::
   list(REMOVE_DUPLICATES <list>)
 
-Removes duplicated items in the list. The relative order of items is preserved,
-but if duplicates are encountered, only the first instance is preserved.
-
-.. _TRANSFORM:
-
-.. code-block:: cmake
+  Removes duplicated items in the list. The relative order of items
+  is preserved, but if duplicates are encountered,
+  only the first instance is preserved.
 
+.. signature::
   list(TRANSFORM <list> <ACTION> [<SELECTOR>]
-                        [OUTPUT_VARIABLE <output variable>])
+       [OUTPUT_VARIABLE <output variable>])
 
-.. versionadded:: 3.12
+  .. versionadded:: 3.12
 
-Transforms the list by applying an action to all or, by specifying a
-``<SELECTOR>``, to the selected elements of the list, storing the result
-in-place or in the specified output variable.
+  Transforms the list by applying an action to all or, by specifying a
+  ``<SELECTOR>``, to the selected elements of the list, storing the result
+  in-place or in the specified output variable.
 
-.. note::
+  .. note::
 
-   The ``TRANSFORM`` sub-command does not change the number of elements in the
-   list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
-   the other ones will remain the same as before the transformation.
+    The ``TRANSFORM`` sub-command does not change the number of elements in the
+    list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
+    the other ones will remain the same as before the transformation.
 
-``<ACTION>`` specifies the action to apply to the elements of the list.
-The actions have exactly the same semantics as sub-commands of the
-:command:`string` command.  ``<ACTION>`` must be one of the following:
+  ``<ACTION>`` specifies the action to apply to the elements of the list.
+  The actions have exactly the same semantics as sub-commands of the
+  :command:`string` command.  ``<ACTION>`` must be one of the following:
 
-``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
-the list.
+    :command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>`
+      Append, prepend specified value to each element of the list.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
+        list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
 
-``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
-characters.
+    :command:`TOUPPER <string(TOUPPER)>`, :command:`TOLOWER <string(TOLOWER)>`
+      Convert each element of the list to upper, lower characters.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
+        list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
 
-``STRIP``: Remove leading and trailing spaces from each element of the
-list.
+    :command:`STRIP <string(STRIP)>`
+      Remove leading and trailing spaces from each element of the list.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> STRIP ...)
+        list(TRANSFORM <list> STRIP ...)
 
-``GENEX_STRIP``: Strip any
-:manual:`generator expressions <cmake-generator-expressions(7)>` from each
-element of the list.
+    :command:`GENEX_STRIP <string(GENEX_STRIP)>`
+      Strip any
+      :manual:`generator expressions <cmake-generator-expressions(7)>`
+      from each element of the list.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> GENEX_STRIP ...)
+        list(TRANSFORM <list> GENEX_STRIP ...)
 
-``REPLACE``: Match the regular expression as many times as possible and
-substitute the replacement expression for the match for each element
-of the list
-(Same semantic as ``REGEX REPLACE`` from :command:`string` command).
+    :command:`REPLACE <string(REGEX REPLACE)>`:
+      Match the regular expression as many times as possible and substitute
+      the replacement expression for the match for each element of the list
+      (same semantic as :command:`string(REGEX REPLACE)`).
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> REPLACE <regular_expression>
-                                  <replace_expression> ...)
+        list(TRANSFORM <list> REPLACE <regular_expression>
+                                      <replace_expression> ...)
 
-``<SELECTOR>`` determines which elements of the list will be transformed.
-Only one type of selector can be specified at a time.  When given,
-``<SELECTOR>`` must be one of the following:
+  ``<SELECTOR>`` determines which elements of the list will be transformed.
+  Only one type of selector can be specified at a time.
+  When given, ``<SELECTOR>`` must be one of the following:
 
-``AT``: Specify a list of indexes.
+    ``AT``
+      Specify a list of indexes.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
+        list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
 
-``FOR``: Specify a range with, optionally, an increment used to iterate over
-the range.
+    ``FOR``
+      Specify a range with, optionally,
+      an increment used to iterate over the range.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
+        list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
 
-``REGEX``: Specify a regular expression. Only elements matching the regular
-expression will be transformed.
+    ``REGEX``
+      Specify a regular expression.
+      Only elements matching the regular expression will be transformed.
 
-  .. code-block:: cmake
+      .. code-block:: cmake
 
-    list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
+        list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
 
 
 Ordering
 ^^^^^^^^
 
-.. _REVERSE:
+.. signature::
+  list(REVERSE <list>)
 
-.. code-block:: cmake
+  Reverses the contents of the list in-place.
 
-  list(REVERSE <list>)
+.. signature::
+  list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
 
-Reverses the contents of the list in-place.
+  Sorts the list in-place alphabetically.
 
-.. _SORT:
+  .. versionadded:: 3.13
+    Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
 
-.. code-block:: cmake
+  .. versionadded:: 3.18
+    Added the ``COMPARE NATURAL`` option.
 
-  list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
+  Use the ``COMPARE`` keyword to select the comparison method for sorting.
+  The ``<compare>`` option should be one of:
 
-Sorts the list in-place alphabetically.
+    ``STRING``
+      Sorts a list of strings alphabetically.
+      This is the default behavior if the ``COMPARE`` option is not given.
 
-.. versionadded:: 3.13
-  Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
+    ``FILE_BASENAME``
+      Sorts a list of pathnames of files by their basenames.
 
-.. versionadded:: 3.18
-  Added the ``COMPARE NATURAL`` option.
+    ``NATURAL``
+      Sorts a list of strings using natural order
+      (see ``strverscmp(3)`` manual), i.e. such that contiguous digits
+      are compared as whole numbers.
+      For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
+      will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
+      comparison is selected where it will be sorted as
+      `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
 
-Use the ``COMPARE`` keyword to select the comparison method for sorting.
-The ``<compare>`` option should be one of:
+  Use the ``CASE`` keyword to select a case sensitive or case insensitive
+  sort mode.  The ``<case>`` option should be one of:
 
-* ``STRING``: Sorts a list of strings alphabetically.  This is the
-  default behavior if the ``COMPARE`` option is not given.
-* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
-* ``NATURAL``: Sorts a list of strings using natural order
-  (see ``strverscmp(3)`` manual), i.e. such that contiguous digits
-  are compared as whole numbers.
-  For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
-  will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
-  comparison is selected where it will be sorted as
-  `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
+    ``SENSITIVE``
+      List items are sorted in a case-sensitive manner.
+      This is the default behavior if the ``CASE`` option is not given.
 
-Use the ``CASE`` keyword to select a case sensitive or case insensitive
-sort mode.  The ``<case>`` option should be one of:
+    ``INSENSITIVE``
+      List items are sorted case insensitively.  The order of
+      items which differ only by upper/lowercase is not specified.
 
-* ``SENSITIVE``: List items are sorted in a case-sensitive manner.  This is
-  the default behavior if the ``CASE`` option is not given.
-* ``INSENSITIVE``: List items are sorted case insensitively.  The order of
-  items which differ only by upper/lowercase is not specified.
+  To control the sort order, the ``ORDER`` keyword can be given.
+  The ``<order>`` option should be one of:
 
-To control the sort order, the ``ORDER`` keyword can be given.
-The ``<order>`` option should be one of:
+    ``ASCENDING``
+      Sorts the list in ascending order.
+      This is the default behavior when the ``ORDER`` option is not given.
 
-* ``ASCENDING``: Sorts the list in ascending order.  This is the default
-  behavior when the ``ORDER`` option is not given.
-* ``DESCENDING``: Sorts the list in descending order.
+    ``DESCENDING``
+      Sorts the list in descending order.
diff --git a/Help/command/set.rst b/Help/command/set.rst
index c724844813..ee677c991e 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -15,102 +15,107 @@ unset.  See the :command:`unset` command to unset variables explicitly.
 Set Normal Variable
 ^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   set(<variable> <value>... [PARENT_SCOPE])
+  :target: normal
 
-Sets the given ``<variable>`` in the current function or directory scope.
+  Sets the given ``<variable>`` in the current function or directory scope.
 
-If the ``PARENT_SCOPE`` option is given the variable will be set in
-the scope above the current scope.  Each new directory or :command:`function`
-command creates a new scope.  A scope can also be created with the
-:command:`block` command. This command will set the value of a variable into
-the parent directory, calling function or encompassing scope (whichever is
-applicable to the case at hand). The previous state of the variable's value
-stays the same in the current scope (e.g., if it was undefined before, it is
-still undefined and if it had a value, it is still that value).
+  If the ``PARENT_SCOPE`` option is given the variable will be set in
+  the scope above the current scope.  Each new directory or :command:`function`
+  command creates a new scope.  A scope can also be created with the
+  :command:`block` command. This command will set the value of a variable into
+  the parent directory, calling function or encompassing scope (whichever is
+  applicable to the case at hand). The previous state of the variable's value
+  stays the same in the current scope (e.g., if it was undefined before, it is
+  still undefined and if it had a value, it is still that value).
 
-The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
-be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
-:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
+  The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands
+  can be used as an alternate method to the :command:`set(PARENT_SCOPE)`
+  and :command:`unset(PARENT_SCOPE)` commands to update the parent scope.
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   set(<variable> <value>... CACHE <type> <docstring> [FORCE])
-
-Sets the given cache ``<variable>`` (cache entry).  Since cache entries
-are meant to provide user-settable values this does not overwrite
-existing cache entries by default.  Use the ``FORCE`` option to
-overwrite existing entries.
-
-The ``<type>`` must be specified as one of:
-
-``BOOL``
-  Boolean ``ON/OFF`` value.  :manual:`cmake-gui(1)` offers a checkbox.
-
-``FILEPATH``
-  Path to a file on disk.  :manual:`cmake-gui(1)` offers a file dialog.
-
-``PATH``
-  Path to a directory on disk.  :manual:`cmake-gui(1)` offers a file dialog.
-
-``STRING``
-  A line of text.  :manual:`cmake-gui(1)` offers a text field or a
-  drop-down selection if the :prop_cache:`STRINGS` cache entry
-  property is set.
-
-``INTERNAL``
-  A line of text.  :manual:`cmake-gui(1)` does not show internal entries.
-  They may be used to store variables persistently across runs.
-  Use of this type implies ``FORCE``.
-
-The ``<docstring>`` must be specified as a line of text providing
-a quick summary of the option for presentation to :manual:`cmake-gui(1)`
-users.
-
-If the cache entry does not exist prior to the call or the ``FORCE``
-option is given then the cache entry will be set to the given value.
-
-.. note::
-
-  The content of the cache variable will not be directly accessible if a normal
-  variable of the same name already exists (see :ref:`rules of variable
-  evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set
-  to ``OLD``, any normal variable binding in the current scope will be removed.
-
-It is possible for the cache entry to exist prior to the call but
-have no type set if it was created on the :manual:`cmake(1)` command
-line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without
-specifying a type.  In this case the ``set`` command will add the
-type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
-and the ``<value>`` provided on the command line is a relative path,
-then the ``set`` command will treat the path as relative to the
-current working directory and convert it to an absolute path.
+  :target: CACHE
+
+  Sets the given cache ``<variable>`` (cache entry).  Since cache entries
+  are meant to provide user-settable values this does not overwrite
+  existing cache entries by default.  Use the ``FORCE`` option to
+  overwrite existing entries.
+
+  The ``<type>`` must be specified as one of:
+
+    ``BOOL``
+      Boolean ``ON/OFF`` value.
+      :manual:`cmake-gui(1)` offers a checkbox.
+
+    ``FILEPATH``
+      Path to a file on disk.
+      :manual:`cmake-gui(1)` offers a file dialog.
+
+    ``PATH``
+      Path to a directory on disk.
+      :manual:`cmake-gui(1)` offers a file dialog.
+
+    ``STRING``
+      A line of text.
+      :manual:`cmake-gui(1)` offers a text field or a drop-down selection
+      if the :prop_cache:`STRINGS` cache entry property is set.
+
+    ``INTERNAL``
+      A line of text.
+      :manual:`cmake-gui(1)` does not show internal entries.
+      They may be used to store variables persistently across runs.
+      Use of this type implies ``FORCE``.
+
+  The ``<docstring>`` must be specified as a line of text
+  providing a quick summary of the option
+  for presentation to :manual:`cmake-gui(1)` users.
+
+  If the cache entry does not exist prior to the call or the ``FORCE``
+  option is given then the cache entry will be set to the given value.
+
+  .. note::
+
+    The content of the cache variable will not be directly accessible
+    if a normal variable of the same name already exists
+    (see :ref:`rules of variable evaluation <CMake Language Variables>`).
+    If policy :policy:`CMP0126` is set to ``OLD``, any normal variable
+    binding in the current scope will be removed.
+
+  It is possible for the cache entry to exist prior to the call but
+  have no type set if it was created on the :manual:`cmake(1)` command
+  line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option
+  without specifying a type.  In this case the ``set`` command will add the
+  type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
+  and the ``<value>`` provided on the command line is a relative path,
+  then the ``set`` command will treat the path as relative to the
+  current working directory and convert it to an absolute path.
 
 Set Environment Variable
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   set(ENV{<variable>} [<value>])
+  :target: ENV
 
-Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
-to the given value.
-Subsequent calls of ``$ENV{<variable>}`` will return this new value.
+  Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
+  to the given value.
+  Subsequent calls of ``$ENV{<variable>}`` will return this new value.
 
-This command affects only the current CMake process, not the process
-from which CMake was called, nor the system environment at large,
-nor the environment of subsequent build or test processes.
+  This command affects only the current CMake process, not the process
+  from which CMake was called, nor the system environment at large,
+  nor the environment of subsequent build or test processes.
 
-If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
-an empty string, then this command will clear any existing value of the
-environment variable.
+  If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
+  an empty string, then this command will clear any existing value of the
+  environment variable.
 
-Arguments after ``<value>`` are ignored. If extra arguments are found,
-then an author warning is issued.
+  Arguments after ``<value>`` are ignored. If extra arguments are found,
+  then an author warning is issued.
 
 See Also
 ^^^^^^^^