diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 233 |
1 files changed, 108 insertions, 125 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 7181b86b6..0c38b0b1d 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -167,8 +167,8 @@ tt(menu-expand-or-complete), or tt(reverse-menu-complete). If the tt(complist) module is loaded (see ifzman(zmanref(zshmodules))\ ifnzman(noderef(The complist Module))\ -), the tt(menu-select) widget can be used, too. If the option tt(-n) is -also given, the bindings will not be used if the key is already bound (that +), the tt(menu-select) widget can be used, too. Note that the +bindings will not be used if the key is already bound (that is, is bound to something other than tt(undefined-key)). The widget is then bound to all the var(key-sequences) given, if any: when @@ -202,7 +202,7 @@ completion functions. enditem() Note that the tt(#) is part of the tag name and no white space is allowed -after it. The tt(#compdef) tags use the tt(compdef) function defined +after it. The tt(#compdef) tags use the tt(compdef) function described below; the main difference is that the name of the function is supplied implicitly. @@ -256,7 +256,7 @@ underscore. In each of the forms supporting it the tt(-a) option makes the var(function) autoloadable (exactly equivalent to -tt(autoload )var(function)). +tt(autoload -U )var(function)). ) findex(compstyle) cindex(completion system, configuring) @@ -273,7 +273,7 @@ ifnzman(noderef(Completion System Configuration))\ . In the first form a new var(style) is defined for a certain -var(pattern), setting it the value given by the var(strings). If there +var(pattern), setting it to the value given by the var(strings). If there was already a definition for the same var(pattern)/var(style) pair, only the value is changed. @@ -288,15 +288,6 @@ In the last form (without arguments) all definitions are listed. If the tt(-L) option is given this is done in the form of calls to tt(compstyle). ) -findex(funcall) -item(tt(funcall) var(return) var(name) [ var(args) ... ])( -If a function var(name) exists, it is called with the arguments -var(args). Unless it is the empty string or a single hyphen, -var(return) is taken as the name of a parameter and the return status -from the called function is stored in it. -The return value of tt(funcall) itself is zero if the function -var(name) exists and was called and non-zero otherwise. -) enditem() texinode(Completion System Configuration)(Control Functions)(Initialization)(Completion System) @@ -324,8 +315,8 @@ beginning just says that we are currently trying completion as opposed to, say, correction, which can also be done using the function based completion system (see ifzman(the section `Control Functions' below)\ -ifnzman(noderef(Control Functions))\ - for more information). +ifnzman(noderef(Control Functions)) +for more information). In many of the possible contexts the completion system can generate matches, and often it can generate multiple types of matches. Whenever @@ -333,9 +324,9 @@ a completion function is about to generate such matches it first calls a utility function, telling it what types of matches can be generated. These types are represented as simple names calld `tags'. This utility function in turn calls another function -(tt(_sort_tags)) and gives the list of tags to it as the positional +(tt(_sort_tags)) and gives the list of tags to it as arguments. The function tt(_sort_tags) can then say in which order the -tags are to be used by the completion function. The function will then +tags are to be used by the completion function. The function will only generate those types of matches whose tags were selected by the user's implementation of the tt(_sort_tags) function. And it will try to generate the different types of matches in the order in which @@ -348,8 +339,8 @@ system is often called to generate only filenames matching a given glob pattern and then uses the tags tt(globbed-files), tt(directories), and tt(all-files). This means that the function offers to generate filenames matching the pattern, names of -directories or all filenames as possible matches. Now, the user may -have definition for tt(_sort_tags): +directories or all filenames as possible matches. Now, if the user has +this definition for tt(_sort_tags): example(_sort_tags() { case $curcontext in @@ -367,13 +358,13 @@ example(_sort_tags() { Every call to the tt(comptry) function (well, it's actually a builtin command defined by the tt(computil) module, but never mind) gives a -set of tags to use. So, the first calls says which tags are to be used +set of tags to use. So, the first call says which tags are to be used first. If there are no matches for those tags, the tags from the second call to tt(comptry) will be tried, and so on. In the example this means that for the tt(dvips) command on the first attempt the names of DVI files and directories will be generated (first call to tt(comptry)). If none of those names match the string from the command -line the completion function will then generate all filenames as +line the completion function will generate all filenames as possible matches (second call to tt(comptry)). For all other context names the second case-pattern matches, so that @@ -394,7 +385,6 @@ you may write in your tt(_sort_tags) function: example(_sort_tags() { comptry arguments options - case $curcontext in ... esac @@ -405,7 +395,6 @@ or example(_sort_tags() { comptry arguments comptry options - case $curcontext in ... esac @@ -419,13 +408,13 @@ for the argument, which normally means that you have to type the hyphen the option names start with yourself to see the list of option names that can be completed. -Since the completion function are free to choose the tag names they +Since the completion functions are free to choose the tag names they use, there can't be a complete list. So to make sure that all types of matches are eventually tried as completions, one should use a call to -tt(comptry) with all positional argument at the end of -tt(_sort_tags). For those contexts where one really wants to make sure -that certain tags are never used one can then use a call to tt(return) -to circumvent that last tt(comptry). For example: +tt(comptry) with all arguments at the end of tt(_sort_tags). For those +contexts where one really wants to make sure that certain tags are +never used one can then use a call to tt(return) to circumvent that +last tt(comptry). For example: example(_sort_tags() { ... @@ -449,10 +438,10 @@ not executed. The tt(_complete_help) bindable command described in ifzman(the section `Bindable Commands' below)\ -ifnzman(noderef(Bindable Commands))\ -can be used to find out the context and tag names used by completion +ifnzman(noderef(Bindable Commands)) +can be used to find out the contexts and tag names used by completion functions. If it is invoked, it shows a list of context names and the -tag names used in those contexts if completion were tried in the +tag names used in those contexts if completion were tried at the current cursor position. This allows one to easily find out all the information needed to change the tt(_sort_tags) function when one wants to change the way matches are generated for that context. @@ -506,14 +495,14 @@ As said above, the patterns given to the tt(compstyle) function are tested in the order in which they were given. But that isn't completely true. In fact, this function roughly sorts the patterns so that more specialized patterns are compared before more general -patterns. Due to this, the last two examples could be defined before +patterns. Due to this, the last two examples could be defined after the first one because both `tt(*:kill:*)' and `tt(*:kill*:jobs)' are -considered to be more special then the pattern `tt(*)' from the first -example. When decided how specific a pattern is, the function looks at +considered to be more specific then the pattern `tt(*)' from the first +example. To decide how specific a pattern is, the function looks at the number of colons (corresponding to the number of components) used in the pattern, and if these components are actual patterns (like the `tt(*)') or simple strings (like the `tt(jobs)' in the last -example). Patterns with fewer patterns and fewer simple strings are +example). Patterns with fewer colons and fewer simple strings are considered to be less specific. As for tags, completion functions can use any number of styles, so @@ -597,7 +586,7 @@ item(tt(fonts))( used for X font names ) item(tt(functions))( -names of functions (shell function or other kinds of functions for +names of functions (shell functions or other kinds of functions for some commands) ) item(tt(globbed-files))( @@ -638,7 +627,7 @@ item(tt(maps))( for map names (e.g. YP maps) ) item(tt(matches))( -used to look up the tt(matches) style +used to look up the tt(group) style ) item(tt(messages))( used to look up the tt(format) style for messages @@ -647,7 +636,7 @@ item(tt(modifiers))( for names of X modifiers ) item(tt(modules))( -for zsh modules +for modules (e.g. tt(zsh) modules) ) item(tt(named-directories))( for named directories (you wouldn't have guessed that, would you?) @@ -662,13 +651,13 @@ item(tt(options))( for command options ) item(tt(packages))( -for RPM packages +for packages (e.g. tt(rpm) packages) ) item(tt(parameters))( for names of parameters ) item(tt(paths))( -used to look up the values of the tt(expand) and tt(cursor) style +used to look up the values of the tt(expand) and tt(cursor) styles ) item(tt(pods))( for perl pods @@ -689,7 +678,7 @@ item(tt(regex))( used to look up tt(cache-path) style ) item(tt(sequences))( -for MH sequences +for sequences (e.g. tt(mh) sequences) ) item(tt(sessions))( for sessions in the tt(zftp) function suite @@ -702,7 +691,7 @@ for strings (e.g. the replacement strings for the tt(cd) builtin command) ) item(tt(tags))( -for RPM tags +for tags (e.g. tt(rpm) tags) ) item(tt(targets))( for makefile targets @@ -779,13 +768,12 @@ The value of this style is given to the tt(ps) command by functions that call it when generating process identifiers as matches. ) item(tt(auto-description))( -If set, this string will be used as the description for options which +If set, this style's value will be used as the description for options which are not described by the completion functions, but that have exactly -one argument (note that this may not work for all commands). - -The sequence `tt(%d)' in the value will be replaced by the description -for this argument. Depending on personal preferences, it may be useful -to set this style to something like `tt(specify: %d)'. +one argument. The sequence `tt(%d)' in the value will be replaced by +the description for this argument. Depending on personal preferences, +it may be useful to set this style to something like `tt(specify: %d)'. +Note that this may not work for some commands. ) item(tt(cache-path))( The tt(_regex_arguments) utility function used by some completion @@ -796,7 +784,7 @@ anew when the completion function is used in another shell. ) item(tt(completer))( The strings given as the value of this style give the names of the -completer function to use. The available completer functions are +completer functions to use. The available completer functions are described in ifzman(the section `Control Functions' below)\ ifnzman(noderef(Control Functions))\ @@ -807,9 +795,9 @@ This style is used by the tt(_expand) completer function. If this is set to an non-empty string it should be an expression usable inside a `tt($((...)))' arithmetical expression. The completer -function evaluates this expression and if the result is `tt(1)' no +function evaluates this expression and if the result is `tt(1)', no expansions will be generated, but instead the completions will be -generated as normal and all of them will be inserted in the command +generated as normal and all of them will be inserted into the command line. ) item(tt(condition))( @@ -828,14 +816,14 @@ other than `tt(1)'. ) item(tt(cursor))( This is used together with the tt(paths) tag by the function -generating filenames as matches to say that the cursor will be left +generating filenames as matches to find out if the cursor will be left after the first ambiguous pathname component even when menucompletion is used. ) item(tt(description))( This is used in several contexts to decide if only a simple or a verbose list of matches should be generated. For example some commands -show descriptions for option names if the style is true. +show descriptions for option names if this style is true. ) item(tt(disable-stat))( This is used with the tt(cvs) tag by the function completing for the @@ -843,7 +831,7 @@ tt(cvs) command to decide if the tt(stat) module should be used to generate only names of modified files in the appropriate places. ) item(tt(expand))( -Like tt(cursor) this style is used with the tt(paths) tag. If it is +Like tt(cursor), this style is used with the tt(paths) tag. If it is set to `true', the partially typed path from the line will be expanded as far as possible even if trailing pathname components can not be completed. @@ -855,16 +843,16 @@ string to display above matches in completion lists. The sequence what these matches are. This string may also contain the sequences to specify output attributes, such as `tt(%b)' and `tt(%s)'. -For the tt(messages) tag, this defines a string to display messages -from the completion functions. Here, the `tt(%d)' is replaced with the -message given by the completion function. +For the tt(messages) tag, this defines a string used by some +completion functions to display messages. Here, the `tt(%d)' is +replaced with the message given by the completion function. Finally, for the tt(warnings) tag, it is printed when no matches could be generated at all. In this case the `tt(%d)' is replaced with the descriptions for the matches that were expected. ) item(tt(glob))( -Like tt(complete) this is used by the tt(_expand) completer. +Like tt(complete), this is used by the tt(_expand) completer. The value is used like the one for tt(complete) and if it evaluates to `tt(1)', globbing will be attempted on the words resulting from @@ -923,8 +911,9 @@ matches generated on the first attempt will be used again. The tt(_history_complete_word) bindable command uses this style to decide if the available matches should be shown. -In the tt(incremental-complete-word) widget, if it is `true', then the -matches are listed on every key press. +When using the tt(incremental-complete-word) widget, this style says +if the matches should be listed on every key press (if they fit on the +screen). ) item(tt(list-arguments))( Like the tt(arguments) style, but used when calling the tt(ps) command @@ -1315,7 +1304,7 @@ corrected completions are found, the completer will normally start menucompletion allowing you to cycle through these strings. The exact behavior of this completer can be changed by using the -style tt(accept), tt(original), tt(prompt), and tt(insert), see +styles tt(accept), tt(original), tt(prompt), and tt(insert), see ifzman(the section `Completion System Configuration' above)\ ifnzman(noderef(Completion System Configuration)). @@ -1324,7 +1313,7 @@ undersccore as the top-level context name. Once it has started trying to generate matches, it will add another context name component containing the number of errors accepted in this attempt. So on the first try the context name starts with `tt(:approximate:1)', on the -second try with `tt(:approximate:1)', and so on. +second try with `tt(:approximate:2)', and so on. ) item(tt(_correct))( Generate corrections (but not completions) for the current word; this is @@ -1335,7 +1324,7 @@ For example, with: example(compstyle '*' completer _complete _correct _approximate compstyle ':correct' accept '2n!' -compstyle ':approximate' accept 3n) +compstyle ':approximate' accept '3n') correction will accept up to two errors. If a numeric argument is given, correction will not be performed, but correcting completion @@ -1460,12 +1449,12 @@ standard output. item(tt(_correct_word) (^Xc))( Performs correction of the current argument using the usual contextual completions as possible choices. This uses the top-level context name -`tt(correct-word)' and then calls the tt(_correct) completer. +`tt(:correct-word)' and then calls the tt(_correct) completer. ) item(tt(_expand_word (^Xe)))( Performs expansion on the current word: equivalent to the standard tt(expand-word) command, but using the tt(_expand) completer. Before -calling it, the top-level context name is set to `tt(expand-word)'. +calling it, the top-level context name is set to `tt(:expand-word)'. ) item(tt(_history_complete_word) (\e/))( Complete words from the shell's command history. @@ -1499,9 +1488,9 @@ Once a string has been read, the next call to tt(_read_comp) will use the existing string instead of reading a new one. To force a new string to be read, call tt(_read_comp) with a numeric argument. ) -item(tt(_complete_help))( +item(tt(_complete_help (^Xh)))( This widget displays information about the context names and tags used -when completing for the place where the cursor is on the line. +when completing at the current cursor position. ) enditem() @@ -1518,6 +1507,15 @@ generated completions and non-zero if no matching completions could be added. startitem() +findex(_funcall) +item(tt(_funcall) var(return) var(name) [ var(args) ... ])( +If a function var(name) exists, it is called with the arguments +var(args). Unless it is the empty string or a single hyphen, +var(return) is taken as the name of a parameter and the return status +from the called function is stored in it. +The return value of tt(_funcall) itself is zero if the function +var(name) exists and was called and non-zero otherwise. +) item(tt(_compalso))( This function looks up the definitions for the context and command names given as arguments and calls the handler functions for them if @@ -1575,7 +1573,7 @@ generated. This is useful to display help texts in places where no completions can be generated automatically. This function also uses the tt(format) style for the tt(messages) tag in -preference to tt(format) style for the tt(descriptions) tag. The +preference to the tt(format) style for the tt(descriptions) tag. The latter is used only if the former is unset. ) item(tt(_tags))( @@ -1588,13 +1586,14 @@ second, etc. set of tags requested by the user. To test if a certain tag should be tried, the tt(_requested) function has to be called (see below). -The return value is zero if tags are requested and non-zero otherwise. +The return value is zero if at least one of the tags is requested and +non-zero otherwise. This function also accepts the tt(-C) option followed by a name. This name is temporarily (i.e. not visible outside tt(_tags)) appended (with a colon before it) to the contents of the tt(curcontext) parameter. This allows to make tt(_tags) and tt(_sort_tags) use a -more specific context name without havin to change and reset the +more specific context name without having to change and reset the tt(curcontext) parameter (which would otherwise have the same effect). ) item(tt(_requested))( @@ -1604,7 +1603,6 @@ check if a certain tag is currently requested. This normally has to be done in a loop such as: example(_tags foo bar baz - while _tags; do if _requested foo; then ... @@ -1615,18 +1613,16 @@ done) So, the first argument for tt(_requested) is used as the name of a tag and if that tag is currently requested, the return value is zero (and -non-zero otheriwse). +non-zero otherwise). -If more than one argument is given, tt(_requested) call the +If more than one argument is given, tt(_requested) calls the tt(_description) function with all arguments except the first one. This is often useful to do both the testing of the tag and -getiing the description for the matches one is about to add at +getting the description for the matches one is about to add at once. E.g.: example(local expl ret=1 - _tags foo bar baz - while _tags; do _requested foo expl 'description' && compadd "$expl[@]" foobar foobaz && ret=0 @@ -1657,7 +1653,7 @@ example(_tags tag && _helper) item(tt(_alternative))( This function is useful if you offer multiple tags and building the matches for them is easy enough. It basically implements a loop like -the one described above for the tt(_tags) function. +the one described above. The tags to use and what to do if the tags are requested are described using the arguments which are of the form: @@ -1677,7 +1673,7 @@ example(_alternative \ to offer usernames and hostnames as possible matches (which are generated by the tt(_users) and tt(_hosts) functions respectively). -Like tt(_tags) this function supports the tt(-C) option to give a +Like tt(_tags) this function supports the tt(-C) option to give an additional context name component. ) item(tt(_style))( @@ -1687,20 +1683,22 @@ a style-name. The tag (if non-empty) is temporarily appended to the current context name (preceded by a colon) and the patterns defined by the user with the tt(compstyle) function will be compared to that combined name. If any of those pattern matches the name and the given -style is defined for it and its boolean value is `true', tt(_style) +style is defined for it and its boolean value is `true' (i.e. its +value is one of `tt(true)', `tt(on)', `tt(yes)', and `tt(1)'), tt(_style) returns zero and non-zero otherwise. If you want to test the style not only for a boolean value, you can give a third argument which is then used as a pattern and tt(_style) returns zero if the pattern matches the value defined for the style. -If you want to retireve the value defined for the style, you can use +If you want to retrieve the value defined for the style, you can use one of the options tt(-b) (to retrieve it as a boolean value, i.e. one of tt(yes) or tt(no)), tt(-s) (to get it as a scalar, i.e. a string concatenated from the value strings defined by the user, separated by spaces), tt(-a) (to get it as an array), and tt(-h) (to get it as an -associative array). In each of this cases the arguments after the -option are the tag, the style-name and the name of the parameter into -which the result will be stored. +associative array; in this case the first, third, etc. strings from the +value are used as the keys and the others as their values). In each of +these cases the arguments after the option are the tag, the style-name +and the name of the parameter into which the result will be stored. For example, to test if the tt(description) style is set to `true' for the current context and the tag tt(foo): @@ -1719,19 +1717,6 @@ In any case, the return value of this function is zero, if a definition for the style was found and non-zero if no definition was found. ) -item(tt(_display))( -This function generates a display list usable for the `tt(-d)' option -of tt(compadd). For this it takes its arguments except the first one -as possible matches with descriptions. The strings should contain the -match, optionally followed by a colon and the description for this -match. From this tt(_display) builds an array with elements containing -the matches and their descriptions, where the descriptions are aligned. -After that, the first argument is taken as a parameter name and the -array built is stored in it. - -The return value of tt(_display) is zero if there was at least one -match with a description non-zero otherwise. -) item(tt(_describe))( This function can be used to add options or values with descriptions as matches. The first argument is taken as a string to display above @@ -1886,7 +1871,7 @@ If there are two colons before the var(message) (as in `tt(*::)var(message)tt(:)var(action)') the tt(words) special array and the tt(CURRENT) special parameter will be restricted to only the normal arguments when the var(action) is executed or evaluated. With -three colons before the var(message) they will be restructed to only +three colons before the var(message) they will be restricted to only the normal arguments covered by this description. ) item(var(opt-spec)[var(description) ...])( @@ -1942,7 +1927,7 @@ should not be used if the option described is on the line. Finally, the var(opt-spec) may contain a explanation string. This is given in brackets at the end, as in `tt(-q[query operation])'. The -style tt(description) for the tt(options) tag is used to decide if these +tt(description) style for the tt(options) tag is used to decide if these explanation strings should be printed when options are listed. If no explanation string is given but the tt(auto-describe) style is set and only one argument is described for this var(opt-spec), the @@ -1959,7 +1944,7 @@ a list in parentheses, as in `tt(:foo:(foo bar baz))'. Such a list in doubled parentheses, as in `tt(:foo:((a\:bar b\:baz)))' should contain strings consisting of the string to complete followed by a colon (which needs to be preceded by a backslash) and a description. The -matches will be listed together with their descriptions the +matches will be listed together with their descriptions if the tt(description) style for the tt(values) tag is set. An var(action) of the form `tt(->)var(string)' is used by functions @@ -1985,7 +1970,7 @@ braces will be evaluated to generate the matches and if the var(action) does not begin with an opening parentheses or brace, 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 +otherwise it will be invoked with some extra strings placed after the first word which can be given as arguments to the tt(compadd) builtin command and which make sure that the var(message) given in the description will be shown above the matches. These arguments @@ -2015,19 +2000,14 @@ will be set to the automatically created context name. This is either a string of the form `var(-opt)tt(-)var(n)' for the var(n)'th argument of the option var(-opt), or a string of the form `tt(argument-)var(n)' for the var(n)'th argument (for rest arguments the var(n) is the -string `tt(rest)'). - -Also, during the evaluation of the var(action), the context name will -be changed by adding another component describing the option or -argument for which the action is executed. For arguments of options, -the name is build from the name of the option followed by a hyphen and -the number of the argument (starting with `tt(1)'). For arguments the -name added is the string tt(argument-) followed by the number of the -argument or the string tt(rest) if this is for a `tt(*:...)' -definition. For example, when completing the argument of the tt(-o) +string `tt(rest)'). For example, when completing the argument of the tt(-o) option, the name is `tt(-o-1)' and for the second normal (non-option-) argument it is `tt(argument-2)'. +Also, during the evaluation of the var(action), the context name in +the tt(curcontext) parameter will be changed by appending the same +string that is stored in the tt(context) parameter. + Normally the option names are taken as multi-character names and a word from the line is considered to contain only one option (or none). By giving the tt(-s) option to this function (before the first @@ -2042,7 +2022,7 @@ Another option supported is `tt(-O) var(name)'. The var(name) will be taken as the name of an array and its elements will be given to functions called to generate matches when executing the var(actions). For example, this allows one to give options for the -tt(compadd) builtin that should be used. +tt(compadd) builtin that should be used for all var(action)s. Also, the tt(-M) option followed by a string may be given before the first description. The string will be used as the match specification @@ -2069,7 +2049,8 @@ possible option names. Note that this means that you should be careful to make sure that this feature is not used for a command that does not support this option. -For options that get an argument after a `tt(=)', the function also tries +For such automatically found 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 after the `tt(-)tt(-)' (which are not used as described @@ -2112,18 +2093,19 @@ replacement. E.g. some tt(configure)-scripts describe options only as completion of the second form, one would use `tt(-s "LPAR()#-)tt(-enable- -)tt(-disable-RPAR()")'. -Finally, this function uses the styles tt(prefix-hidden) and -tt(prefix-needed). +Finally, this function uses the styles tt(description), +tt(prefix-hidden) and tt(prefix-needed) with the tt(options) tag when +generating option names as matches. Example: -example(_arguments '-l+:left border:' \ - '-format:paper size:(letter A4)' \ - '*-copy:output file:_files::resolution:(300 600)' \ - ':postscript file:_files -g *.(ps|eps)' \ +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 +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 @@ -2154,7 +2136,7 @@ and when executing an action. Otherwise, if the first argument (or the first argument after the `tt(-O) var(name)' option if that is used) is the option `tt(-s)', the -second argument is used as the character that separates multiple values. +next argument is used as the character that separates multiple values. The first argument (after the options and separator character if they are given) is used as a string to print as a description before @@ -2168,9 +2150,9 @@ values can have only one argument. Example: -example(_values -s , '...' \ +example(_values -s , 'description' \ '*foo[bar]' \ - '(two)*one[number]:first count:' \ + '(two)*one[number]:first count:' \ 'two[another number]::second count:(1 2 3)') This describes three possible values: `tt(foo)', `tt(one)', and @@ -2179,7 +2161,7 @@ and may appear more than once. The second one is described as `tt(number)', may appear more than once, and gets one mandatory argument described as `tt(first count)' for which no action is specified so that it will not be completed automatically. The -`tt((one))' at the beginning says that if the value `tt(one)' is on +`tt((two))' at the beginning says that if the value `tt(one)' is on the line, the value `tt(two)' will not be considered to be a possible completion any more. Finally, the last value (`tt(two)') is described as `tt(another number)' and gets an optional argument decribed as @@ -2196,7 +2178,8 @@ To decide if the descriptions for the values (not those for the arguments) should be printed, the style tt(description) for the tt(values) tag is used. -One last difference is that this function uses the associative array +One last difference to tt(_arguments) is that this function uses the +associative array tt(val_args) to report values and their arguments (but otherwise this is the same as the tt(opt_args) association used by tt(_arguments)). This also means that the function calling tt(_values) |