Help: Improve grammar and wording for cmake_parse_arguments

Help/command/cmake_parse_arguments.rst

@@ -20,48 +20,49 @@ It processes the arguments given to that macro or function,
 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 @@ Assume ``my_install()`` has been called like this:
 
    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 @@ the following variables::
 
 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
 ^^^^^^^^