manual/7448

2 files changed, 152 insertions, 14 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 025003675..4f1b70c6e 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -151,6 +151,10 @@ called when completing for a command whose name matches the given
 var(pattern) (a standard globbing pattern).  Note that only one
 var(pattern) may be given.
 )
+item(tt(#compdef -P) var(pattern))(
+Like the previous one, but the function will be called only if no
+completion function for the command on the line could be found.
+)
 item(tt(#compdef -k) var(style key-sequences...))(
 This can be used to bind special completion functions to the
 var(key-sequences).  It creates a widget behaving like the builtin widget
@@ -195,6 +199,7 @@ startitem()
 xitem(tt(compdef) [ tt(-an) ] var(function names...))
 xitem(tt(compdef -d) var(names...))
 xitem(tt(compdef -p) [ tt(-a) ] var(function pattern))
+xitem(tt(compdef -P) [ tt(-a) ] var(function pattern))
 item(tt(compdef -k) [ tt(-a) ] var(function style key-sequences...))(
 The first form tells the completion system to call the given
 var(function) when completing for the contexts or commands
@@ -207,7 +212,12 @@ The third form is similar to the first, but var(function) will be called
 for all commands whose name matches the var(pattern); this is like the
 tt(#compdef -p) function tag.
 
-The fourth form defines a widget with the same name as the var(function)
+The fourth form is like the third, but the var(function) will be
+called only if no function for the command itself was found or if one
+was found and it set the tt(_compskip) parameter to a value em(not)
+containing the sub-string `tt(patterns)'.
+
+The fifth form defines a widget with the same name as the var(function)
 which will be called for each of the var(key-sequences); this is like the
 tt(#compdef -k) tag.  The function should generate the completions needed
 and will otherwise behave like the builtin widget whose name is given as
@@ -694,6 +704,37 @@ tt(-first-) context. With this
 one can write a pattern completion function that keeps other functions 
 from being tried simply by setting this parameter to any value.
 )
+item(tt(_description))(
+This function gets two arguments: the name of an array and a
+string. It tests if the configuration key tt(description_format) is
+set and if it is, it stores some options in the array that can then be 
+given to the tt(compadd) and tt(compgen) builtin commands to make the
+value of the tt(description_format) key (with the sequence `tt(%d)'
+replaced by the string given as the second argument) be displayed
+above the matches added. These options also will make sure that the
+matches are placed in a separate group (the second argument is used as 
+the name of the group) if the configuration key tt(group_matches) is
+set to a non-empty string. Normally a sorted group will be used for this
+(with the `tt(-J)' option), but if the option `tt(-V)' is given, a
+unsorted group will be used instead.
+
+In most cases, this function will be used like this:
+
+example(local expl
+_description expl file
+compadd "$expl[@]" - "$files[@]")
+)
+item(tt(_message))(
+This function takes one argument which is used like the second
+argument to the tt(_description) function. However, the resulting
+string will always be shown, not only if some matches were
+generated. This is useful to display help texts in places where no
+completions can be generated automatically.
+
+This function also uses the configuration key tt(message_format) in
+preference to tt(description_format). The latter is used only if the
+former is unset or set to the empty string.
+)
 item(tt(_multi_parts))(
 This function gets two arguments: a separator character and an
 array.  As usual, the array may be either the
@@ -791,19 +832,21 @@ names. Note that this means that you should be careful to make sure
 that this function is not called for a command that does not support
 this option.
 
-For options that get an argument after a `tt(=)', the function also
-automatically tries to find out what should be completed as the argument.
+For options that get an argument after a `tt(=)', the function also tries
+to automatically find out what should be completed as the argument.
 The possible completions for option-arguments can be described with
-the arguments to this function. This is done by giving pairs of
-patterns and actions as consecutive arguments. The actions specify
-what should be done to complete arguments of those options whose
-description match the pattern. The action may be a list of words in
-brackets or in parentheses, separated by spaces. A list in square brackets
-denotes possible values for an optional argument, a list in parentheses
+the arguments to this function. Each argument contains one description
+of the form <pattern>:<message>:<action>. The message will be printed 
+above the possible completion if the `description_format' configuration
+key is set (see above). The actions specify what
+should be done to complete arguments of those options that match 
+the pattern. The action may be a list of words in brackets or in
+parentheses, separated by spaces. A list in brackets denotes
+possible values for an optional argument, a list in parentheses
 gives words to complete for mandatory arguments. If the action does
-not start with a square bracket or parenthesis, it should be the name of a
+not start with a bracket or parentheses, it should be the name of a
 command (probably with arguments) that should be invoked to complete 
-after the equal sign. Example:
+after the equal sign. E.g.:
 
 example(_long_options '*\*'     '(yes no)' \ 
               '*=FILE*' '_files' \ 
@@ -818,8 +861,7 @@ for option descriptions containing `tt(=FILE)' and paths for option
 descriptions that contain `tt(=DIR)' or `tt(=PATH)'. These builtin
 patterns can be overridden by patterns given as arguments, however.
 
-This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)'
-options which are passed unchanged to `tt(compadd)'. If the
+If the
 option `tt(-t)' is given, completion is only done on words starting
 with two hyphens. The option `tt(-i) var(patterns)' can be used to
 give patterns for options which should not be completed. The patterns
@@ -833,6 +875,102 @@ replacement. E.g. some tt(configure)-scripts describe options only as
 completion of the second form, one would use
 `tt(-s "(#--enable- --disable-)")'.
 )
+item(tt(_arguments))(
+Like tt(_long_options), this function is in the tt(Base) subdirectory.
+
+This function can be used to complete words on the line by simply
+describing the arguments the command on the line gets. The description 
+is given as arguments to this function, with each argument describing
+one option or normal argument of the command. The descriptions
+understood are:
+
+startitem()
+item(var(n)tt(:)var(message)tt(:)var(action))(
+This describes the var(n)'th normal argument. The var(message) will be 
+printed above the matches generated and the var(action) says what can
+be completed in this position (see below).
+)
+item(tt(:)var(message)tt(:)var(action))(
+Like the previous one, but describing the em(next) argument. I.e. if
+you want to describe all arguments a command can get, you can leave
+out the numbers in the description and just use this form to describe
+them one after another in the order they have to appear on the line.
+)
+item(tt(*:)var(message)tt(:)var(action))(
+This describes how arguments are to be completed for which no
+description with one of the first two forms was given. This also means 
+that any number of arguments can be completed.
+)
+item(var(opt-spec)[var(description) ...])(
+This describes an option and (if at least one var(description) is
+given) the arguments that have to come after the option. If no
+var(description) is given, this will only be used to offer the option
+name as a possible completion in the right places. Each
+var(description) has to be of the form
+`tt(:)var(message)tt(:)var(action)' or
+`tt(::)var(message)tt(:)var(action)', where the second form describes
+an optional argument and the first one describes a mandatory argument.
+
+In the simplest form the var(opt-spec) is just the option name
+beginning with a minus or a plus sign, such as `tt(-foo)'. In this
+case, the first argument for the option (if any) has to come as a
+separate word directly after the option and the option may appear only 
+once on the line (and if it is already on the line, the option name
+will not be offered as a possible completion again). If the first
+argument for the option has to come directly after the option name
+em(in the same word), a minus sign should be added to the end of the
+var(opt-spec), as in `tt(-foo-)'. If the first argument may be given
+in one string with the option name, but may also be given as a
+separate argument after the option, a plus sign should be used
+instead. Finally, if the option may be given more than once, a star
+(`tt(*)') should be added in front of the var(opt-spec).
+enditem()
+
+In each of the cases above, the var(action) says how the possible
+completions should be generated. In cases where only one of a fixed
+set of strings can be completed, these string can directly be given as 
+a list in parentheses, as in `tt(:foo:(foo bar baz))'. If the
+var(action) does not begin with an opening parentheses, it will be
+split into separate words and executed. If the var(action) starts with 
+a space, this list of words will be invoked unchanged, otherwise it
+will be invoked with some extra string placed after the first word
+which can be given as arguments to the tt(compadd) and tt(compgen)
+builtins and which make sure that the var(message) given in the
+description will be shown above the matches.
+
+Finally, this function can be made to automatically call the
+tt(_long_options) function where appropriate by giving it the string
+`tt(--)' as an argument. All arguments after this will be given
+unchanged to the tt(_long_options) function.
+
+Example:
+
+example(_arguments '-l+:left border:' \
+           '-format:paper size:(letter A4)' \
+	   '*-copy:output file:_files::resolution:(300 600)' \
+	   ':postscript file:_files -g *.(ps|eps)' \
+	   '*:page number:')
+
+This describes three options `tt(-l)', `tt(-format)', and
+`tt(-copy)'. The first one gets one argument described as `var(left
+border)' for which no completion will be offered because of the empty
+action. The argument may come directly after the `tt(-l)' or it may be 
+given as the next word on the line. The `tt(-format)' option gets one
+argument (in the next word) described as `var(paper size)' for which
+only the strings `tt(letter)' and `tt(A4)' will be completed. The
+`tt(-copy)' option differs from the first two in that it may appear
+more than once on the command line and in that it accepts two
+arguments. The first one is mandatory and will be completed as a
+filename. The second one is optional (because of the second colon
+before the description `var(resolution)') and will be completed from
+the strings `tt(300)' and `tt(600)'.
+
+The last two descriptions say what should be completed as
+arguments. The first one describes the first argument as a
+`var(postscript file)' and makes files ending in `tt(ps)' or `tt(eps)' 
+be completed. The last description says that all other arguments are
+`var(page numbers)' but does not give possible completions.
+)
 enditem()
 
 texinode(Completion Directories)(Bindable Commands)(Completion Functions)(Completion System)
diff --git a/Doc/Zsh/mod_parameter.yo b/Doc/Zsh/mod_parameter.yo
index 4fe537c6d..3640e39d8 100644
--- a/Doc/Zsh/mod_parameter.yo
+++ b/Doc/Zsh/mod_parameter.yo
@@ -16,7 +16,7 @@ the option, respectively. Unsetting a key in this array is like
 setting it to the value tt(off).
 )
 vindex(commands)
-item(tt(command))(
+item(tt(commands))(
 This array gives access to the command hash table. The keys are the
 names of external commands, the values are the pathnames of the files
 that would be executed when the command would be invoked. Setting a