_arguments docs: Bring all option descriptions to one place

1 files changed, 85 insertions, 54 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index af906bf29..2052acc13 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3530,37 +3530,105 @@ xitem(SPACES()[ tt(:) ] var(spec) ...)
 item(tt(_arguments) [ var(opt) ... ] tt(-)tt(-) [ tt(-i) var(pats) ] [ tt(-s) var(pair) ] [ var(helpspec) ... ])(
 This function can be used to give a complete specification for completion
 for a command whose arguments follow standard UNIX option and argument
-conventions.  Options to tt(_arguments) itself must be in separate words,
-i.e. tt(-s -w), not tt(-sw).
+conventions.
 
-When calling tt(_arguments), all var(spec)s that describe options of the
-analyzed command line must precede all var(spec)s that describe non-option
-(aka "normal") arguments of the analyzed line.  To avoid ambiguity, all
+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")
+arguments of the analyzed line.  To avoid ambiguity, all
 options to tt(_arguments) itself may be separated from the var(spec) forms
 by a single colon.
 
-The tt(-s -w -W -A) and tt(-S) options describe how parsing of the command
-line should proceed, and are discussed in context below.  The `tt(-)tt(-)'
+The `tt(-)tt(-)'
 form is used to intuit var(spec) forms from the help output of the command
 being analyzed, and is described in detail below.  The var(opts) for the
 `tt(-)tt(-)' form are otherwise the same options as the first form.  Note
 that `tt(-s)' following `tt(-)tt(-)' has a distinct meaning from `tt(-s)'
 preceding `tt(-)tt(-)', and both may appear.
 
-With the option tt(-n), tt(_arguments) sets the parameter tt(NORMARG)
+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:
+
+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
 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.
+)
+item(tt(-s))(
+Enable em(option stacking) for single-letter options, whereby multiple
+single-letter options may be combined into a single word.  For example,
+the two options `tt(-)var(x)' and `tt(-)var(y)' may be combined into
+a single word `tt(-)var(xy)'.  By default, every word corresponds to a single
+option name (the `tt(-xy)' option).
 
-The option `tt(-M) var(matchspec)' sets a match specification to use to
-completion option names and values.  The default var(matchspec) is:
+Options beginning with a single hyphen or plus sign are eligible for stacking;
+words beginning with two hyphens are not.
 
-example(tt(r:|[_-]=* r:|=*))
+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
+even if one or more of the options take
+arguments.  For example, if tt(-x) takes an argument, with no
+tt(-s), `tt(-xy)' is considered as a single (unhandled) option; with
+tt(-s), tt(-xy) is an option with the argument `tt(y)'; with both tt(-s)
+and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with
+arguments still to come.
+)
+item(tt(-W))(
+This option takes tt(-w) a stage further:  it is possible to
+complete single-letter options even after an argument that occurs in the
+same word.  However, it depends on the action performed whether options
+will really be completed at this point.  For more control, use a
+utility function like tt(_guard) as part of the action.
+)
+item(tt(-C))(
+Modify the tt(curcontext) parameter for an action of the form `tt(->)var(state)'.
+This is discussed in detail below.
+)
+item(tt(-R))(
+Return status 300 instead of zero when a tt($state) is to
+be handled, in the `tt(->)var(string)' syntax.
+)
+item(tt(-S))(
+Do not complete options after a `tt(-)tt(-)' appearing on the line,
+and ignore the `tt(-)tt(-)'.  For example, with tt(-S), in the line
+
+example(foobar -x -- -y)
 
-This allows partial word completion after `tt(_)' and `tt(-)', for example
-`tt(-f-b)' can be completed to `tt(-foo-bar)'.
+the `tt(-x)' is considered an option, the `tt(-y)' is considered an
+argument, and the `tt(-)tt(-)' is considered to be neither.
+)
+item(tt(-A) var(pat))(
+Do not complete options after the first non-option
+argument on the line.  var(pat) is a pattern matching
+all strings which are not to be taken as arguments.  For example, to make
+tt(_arguments) stop completing options after the first normal argument, but
+ignoring all strings starting with a hyphen even if they are not described
+by one of the var(optspec)s, the form is `tt(-A "-*")'.
+)
+item(tt(-O) var(name))(
+Pass the elements of the array var(name) as arguments to functions called to
+execute var(action)s.
+This is discussed in detail below.
+)
+item(tt(-M) var(matchspec))(
+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:|=*))
+)
+enditem()
 
 Each of the following forms is a var(spec) describing individual sets of
 options or arguments on the command line being analyzed.
@@ -3601,26 +3669,6 @@ This describes an option.  The colon indicates handling for one or more
 arguments to the option; if it is not present, the option is assumed to
 take no arguments.
 
-By default, options are multi-character name, one `tt(-)var(word)' per
-option.  With tt(-s), options may be single characters, with more than
-one option per word, although words starting with two hyphens, such as
-`tt(-)tt(-prefix)', are still considered complete option names.  This is
-suitable for standard GNU options.
-
-The combination of tt(-s) with tt(-w) allows single-letter options to be
-combined in a single word even if one or more of the options take
-arguments.  For example, if tt(-x) takes an argument, with no
-tt(-s) `tt(-xy)' is considered as a single (unhandled) option; with
-tt(-s) tt(-xy) is an option with the argument `tt(y)'; with both tt(-s)
-and tt(-w), tt(-xy) may be the option tt(-x) and the option tt(-y) with
-arguments still to come.
-
-The option tt(-W) takes this a stage further:  it is possible to
-complete single-letter options even after an argument that occurs in the
-same word.  However, it depends on the action performed whether options
-will really be completed at this point.  For more control, use a
-utility function like tt(_guard) as part of the action.
-
 The following forms are available for the initial var(optspec), whether
 or not the option has arguments.
 
@@ -3682,23 +3730,6 @@ enditem()
 It is possible for options with a literal `tt(PLUS())' or `tt(=)' to
 appear, but that character must be quoted, for example `tt(-\+)'.
 
-The options tt(-S) and tt(-A) are available to simplify the specifications
-for commands with standard option parsing.  With tt(-S), no option will be
-completed after a `tt(-)tt(-)' appearing on its own on the line; this
-argument will otherwise be ignored; hence in the line
-
-example(foobar -x -- -y)
-
-the `tt(-x)' is considered an option but the `tt(-y)' is considered an
-argument, while the `tt(-)tt(-)' is considered to be neither.
-
-With tt(-A), no options will be completed after the first non-option
-argument on the line.  The tt(-A) must be followed by a pattern matching
-all strings which are not to be taken as arguments.  For example, to make
-tt(_arguments) stop completing options after the first normal argument, but
-ignoring all strings starting with a hyphen even if they are not described
-by one of the var(optspec)s, the form is `tt(-A "-*")'.
-
 Each var(optarg) following an var(optspec) must take one of the
 following forms:
 
@@ -3719,7 +3750,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).
@@ -3772,9 +3803,9 @@ form below, the var(action) will be executed by calling the
 tt(_all_labels) function to process all tag labels.  No special handling
 of tags is needed unless a function call introduces a new one.
 
-The option `tt(-O) var(name)' specifies the name of an array whose elements
-will be passed as arguments to functions called to execute var(action)s.
-For example, this can be used to pass the same set of options for the
+The functions called to execute var(action)s will be called with the the
+elements of the array named by the `tt(-O) var(name)' option as arguments.
+This can be used, for example, to pass the same set of options for the
 tt(compadd) builtin to all var(action)s.
 
 The forms for var(action) are as follows.