Help: Improve grammar and wording for cmake_parse_arguments
diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst
index 70dbeeb..746e1f1 100644
--- a/Help/command/cmake_parse_arguments.rst
+++ b/Help/command/cmake_parse_arguments.rst
@@ -20,48 +20,49 @@
and defines a set of variables which hold the values of the
respective options.
-The first signature reads processes arguments passed in the ``<args>...``.
+The first signature reads arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`.
.. versionadded:: 3.7
The ``PARSE_ARGV`` signature is only for use in a :command:`function`
- body. In this case the arguments that are parsed come from the
+ body. In this case, the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with
the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
This allows for the values to have special characters like ``;`` in them.
-The ``<options>`` argument contains all options for the respective macro,
-i.e. keywords which can be used when calling the macro without any value
-following, like e.g. the ``OPTIONAL`` keyword of the :command:`install`
-command.
+The ``<options>`` argument contains all options for the respective function
+or macro. These are keywords that have no value following them, like the
+``OPTIONAL`` keyword of the :command:`install` command.
-The ``<one_value_keywords>`` argument contains all keywords for this macro
-which are followed by one value, like e.g. ``DESTINATION`` keyword of the
-:command:`install` command.
+The ``<one_value_keywords>`` argument contains all keywords for this function
+or macro which are followed by one value, like the ``DESTINATION`` keyword of
+the :command:`install` command.
The ``<multi_value_keywords>`` argument contains all keywords for this
-macro which can be followed by more than one value, like e.g. the
+function or macro which can be followed by more than one value, like the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
.. versionchanged:: 3.5
- All keywords shall be unique. I.e. every keyword shall only be specified
- once in either ``<options>``, ``<one_value_keywords>`` or
+ All keywords must be unique. Each keyword can only be specified
+ once in any of the ``<options>``, ``<one_value_keywords>``, or
``<multi_value_keywords>``. A warning will be emitted if uniqueness is
violated.
When done, ``cmake_parse_arguments`` will consider for each of the
-keywords listed in ``<options>``, ``<one_value_keywords>`` and
-``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
-followed by ``"_"`` and the name of the respective keyword. These
-variables will then hold the respective value from the argument list
-or be undefined if the associated option could not be found.
-For the ``<options>`` keywords, these will always be defined,
-to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
+keywords listed in ``<options>``, ``<one_value_keywords>``, and
+``<multi_value_keywords>``, a variable composed of the given ``<prefix>``
+followed by ``"_"`` and the name of the respective keyword. For
+``<one_value_keywords>`` and ``<multi_value_keywords>``, these variables
+will then hold the respective value(s) from the argument list, or be undefined
+if the associated keyword was not given (policy :policy:`CMP0174` can also
+affect the behavior for ``<one_value_keywords>``). For the ``<options>``
+keywords, these variables will always be defined, and they will be set to
+``TRUE`` if the keyword is present, or ``FALSE`` if it is not.
All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see
-whether your macro was called with unrecognized parameters.
+whether your macro or function was called with unrecognized parameters.
.. versionadded:: 3.15
``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
@@ -96,7 +97,7 @@
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
-After the ``cmake_parse_arguments`` call the macro will have set or undefined
+After the ``cmake_parse_arguments`` call, the macro will have set or undefined
the following variables::
MY_INSTALL_OPTIONAL = TRUE
@@ -111,14 +112,14 @@
You can then continue and process these variables.
-Keywords terminate lists of values, e.g. if directly after a
-``one_value_keyword`` another recognized keyword follows, this is
-interpreted as the beginning of the new option. E.g.
+Keywords terminate lists of values. If a keyword is given directly after a
+``<one_value_keyword>``, that preceding ``<one_value_keyword>`` receives no
+value and the keyword is added to the ``<prefix>_KEYWORDS_MISSING_VALUES``
+variable. For the above example, the call
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
-``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
-is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
-to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
-therefore be set to ``TRUE``.
+``MY_INSTALL_OPTIONAL`` being set to ``TRUE`` and ``MY_INSTALL_DESTINATION``
+being unset. The ``MY_INSTALL_KEYWORDS_MISSING_VALUES`` variable would hold
+the value ``DESTINATION``.
See Also
^^^^^^^^
