>From 6ff7fb935d437b55c2bc94d8338332b80460a3a4 Mon Sep 17 00:00:00 2001 From: Daniel Shahaf Date: Wed, 15 Jul 2015 18:12:47 +0000 Subject: [PATCH 2/2] _arguments docs: Divide into subsections --- Doc/Zsh/compsys.yo | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 5fd8e24..a53de8b 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -3532,6 +3532,8 @@ This function can be used to give a complete specification for completion for a command whose arguments follow standard UNIX option and argument conventions. +em(Options overview) + 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 @@ -3632,6 +3634,8 @@ which allows partial word completion after `tt(_)' and `tt(-)', for example ) enditem() +em(var(spec)s: overview) + Each of the following forms is a var(spec) describing individual sets of options or arguments on the command line being analyzed. @@ -3799,6 +3803,8 @@ given by an array, and tt(_arguments) is called repeatedly for more specific contexts: on the first call `tt(_arguments $global_options)' is used, and on subsequent calls `tt(_arguments !$^global_options)'. +em(var(spec)s: actions) + In each of the forms above the var(action) determines how completions should be generated. Except for the `tt(->)var(string)' form below, the var(action) will be executed by calling the @@ -3951,6 +3957,8 @@ example(local curcontext="$curcontext") This is useful where it is not possible for multiple states to be valid together. +em(Specifying multiple sets of options) + It is possible to specify multiple sets of options and arguments with the sets separated by single hyphens. The specifications before the first hyphen (if any) are shared by all the remaining sets. @@ -3997,6 +4005,8 @@ 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) + 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 GNU commands. The command word is called with the argument @@ -4069,6 +4079,8 @@ as `tt(-)tt(-enable-foo)', but the script also accepts the negated form example(_arguments -- -s "LPAR()(#s)--enable- --disable-RPAR()") +em(Miscellaneous notes) + Finally, note that tt(_arguments) generally expects to be the primary function handling any completion for which it is used. It may have side effects which change the treatment of any matches added by other functions -- 1.9.1