Re: [PATCH] _arguments docs: Add options overview and sections

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Daniel Shahaf wrote on Thu, Jul 16, 2015 at 23:20:32 +0000:
> Attached for review.  The first patch conslidates the documentation of
> all of _arguments' options in one place; that patch is 90% moving text
> around and 10% minor text changes.  The second patch divides the long
> help docstring into "subsections".

Here's an additional patch following Oliver's review (thanks!).

Possible further enhancements:

- Clarify terminology throughout: option/flag/argument/switch, as referring to
  _arguments' argv or to the analyzed command line's.

- Clarify documentation of -C

Cheers,

Daniel

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index a53de8b..290c85f 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3534,7 +3534,7 @@ conventions.
 
 em(Options overview)
 
-Options to tt(_arguments) itself must be in separate words, i.e., tt(-s -w),
+Options to tt(_arguments) itself must be in separate words, i.e. tt(-s -w),
 not tt(-sw).  The options are followed by var(spec)s that describe options and
 arguments of the analyzed command.  var(spec)s that describe option flags must
 precede var(spec)s that describe non-option ("positional" or "normal")
@@ -3549,8 +3549,9 @@ being analyzed, and is described in detail below.  The var(opts) for the
 that `tt(-s)' following `tt(-)tt(-)' has a distinct meaning from `tt(-s)'
 preceding `tt(-)tt(-)', and both may appear.
 
-The options tt(-s), tt(-S), tt(-A) affect the parsing of the command line,
-and are useful for commands with standard option parsing.
+The option switches tt(-s), tt(-S), tt(-A), tt(-w), and tt(-W) affect how
+tt(_arguments) parses the analyzed command line's options.  These switches are
+useful for commands with standard argument parsing.
 
 The options of tt(_arguments) have the following meanings:
 
@@ -3558,7 +3559,7 @@ startitem()
 item(tt(-n))(
 With this option, tt(_arguments) sets the parameter tt(NORMARG)
 to the position of the first normal argument in the tt($words) array,
-i.e., the position after the end of the options.  If that argument
+i.e. the position after the end of the options.  If that argument
 has not been reached, tt(NORMARG) is set to tt(-1).  The caller
 should declare `tt(integer NORMARG)' if the tt(-n) option is passed;
 otherwise the parameter is not used.
@@ -3572,10 +3573,9 @@ option name (the `tt(-xy)' option).
 
 Options beginning with a single hyphen or plus sign are eligible for stacking;
 words beginning with two hyphens are not.
-This is suitable for standard GNU options.
 
-Note that tt(-s) after tt(-)tt(-) has a different meaning, and is documented
-below.
+Note that tt(-s) after tt(-)tt(-) has a different meaning, which is documented
+in the segment entitled `Deriving var(spec) forms from the help output'.
 )
 item(tt(-w))(
 In combination with tt(-s), allow option stacking
@@ -3624,13 +3624,11 @@ execute var(action)s.
 This is discussed in detail below.
 )
 item(tt(-M) var(matchspec))(
-Use var(matchspec) as the match specification to use to
-completion option names and values.  The default var(matchspec) is:
-
+Use the match specification var(matchspec) for completing option names and values.
+The default var(matchspec) allows partial word completion after `tt(_)' and
+`tt(-)', such as completing `tt(-f-b)' to `tt(-foo-bar)'.  The default
+var(matchspec) is:
 example(tt(r:|[_-]=* r:|=*))
-
-which allows partial word completion after `tt(_)' and `tt(-)', for example
-`tt(-f-b)' can be completed to `tt(-foo-bar)'.
 )
 enditem()
 
@@ -3756,7 +3754,7 @@ xitem(tt(:*)var(pattern)tt(::)var(message)tt(:)var(action))
 item(tt(:*)var(pattern)tt(:::)var(message)tt(:)var(action))(
 This describes multiple arguments.  Only the last var(optarg) for
 an option taking multiple arguments may be
-given in this form.  If the var(pattern) is empty (i.e., tt(:*:)), all
+given in this form.  If the var(pattern) is empty (i.e. tt(:*:)), all
 the remaining words on the line are to be completed as described by the
 var(action); otherwise, all the words up to and including a word matching
 the var(pattern) are to be completed using the var(action).
@@ -4005,7 +4003,7 @@ A useful alternative is often an option specification with rest-arguments
 (as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all
 remaining arguments as described by the var(optarg) definitions.
 
-em(Intuiting var(spec) forms from the help output)
+em(Deriving var(spec) forms from the help output)
 
 The option `tt(-)tt(-)' allows tt(_arguments) to work out the names of long
 options that support the `tt(-)tt(-help)' option which is standard in many