PATCH: manual for example completion

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

This puts a description of the example completion system into the
docs. I've put it into its own file because I think it's already big
enough for that. In the manual this comes after the modules-section,
at the very end.

Most of the text is taken from the `README' file and the comments in
the helper functions. In some cases I added some more comments and in
at least one place I had to correct what I took from `README'.

I don't think that I'll support `README' any longer.

Bye
 Sven

diff -u Doc/Zsh/compsys.yo Doc/Zsh/compsys.yo
--- Doc/Zsh/compsys.yo	Tue Mar 30 11:25:31 1999
+++ Doc/Zsh/compsys.yo	Tue Mar 30 11:20:26 1999
@@ -0,0 +1,701 @@
+texinode(Completion System)()(Zsh Modules)(Top)
+chapter(Completion System)
+cindex(completion, system)
+cindex(completion, programmable)
+cindex(completion, controlling)
+sect(Description)
+
+This describes the example implementation for the new completion
+system. It consists of two scripts and a couple of other files that
+define shell functions, residing in the tt(Completion) directory and
+its sub-directories of the main distribution directory.
+
+The intended use is to copy all the files you need into a directory
+of your account and then start the intialisation process. Which files
+are always needed and which files are optional is described in the
+following sections.
+
+startmenu()
+menu(Initialisation)
+menu(Control Functions)
+menu(Completion Functions)
+endmenu()
+
+texinode(Initialisation)(Control Functions)()(Completion System)
+sect(Initialisation)
+
+The script tt(compinit), when sourced with `tt(source .../compinit)'
+or `tt(. .../compinit)', will define a few utility functions, make all 
+files defining shell functions for completion automatically loaded,
+and will then re-bind all keys that do completion to use the new system.
+
+subsect(Arguments)
+
+Since finding out which files should be made automatically autoloaded
+can be quite expensive, it is recommended to create a file containing
+executable shell code doing everything tt(compinit) would
+normally do automatically. To simplify this, the second script,
+tt(compdump)' is provided. Whenever this is sourced, a file,
+called `var(dumpfile)' is created containing the shell code needed to
+set up everything needed for the completion system. To simplify this
+even further, the tt(compinit) file accepts the option
+`tt(-d)'. If this is given, tt(compdump) is automatically called
+after everything is set up. On later invocations of tt(compinit)
+with the option given, it will only search the files that have to be
+made autoloaded if something has changed and will otherwise just
+source the var(dumpfile). The name of the var(dumpfile) can be given
+to tt(compinit) as an argument. If this is not given, a default
+name will be chosen.
+
+Whenever the setup for the completion system changes, the script
+tt(compdump) can be source by hand, but if tt(compinit) is
+sourced with the `tt(-d)' option this will only be needed if one of
+the files for completion has been renamed. If only the number of files 
+to use for completion has changed, this will be detected by
+tt(compinit) and it will then automatically create a new
+var(dumpfile).
+
+subsect(Autoloaded files)
+
+To have the files used for completion automatically autoloaded the
+tt(fpath/FPATH) parameter has to contain the directory in which they
+are stored. As a convention the names of these files start with an
+underscore. When tt(compinit) is sourced, it searches all such
+files accessible via tt(fpath/FPATH) and reads the first line of each
+of them. This line has to describe what to do with the file by
+starting with one of the tags described below. Files whose first line
+does not start with one of these tags are not considered to be part of 
+the completion system and will not be treated specially.
+
+The tags looked for are:
+
+startitem()
+item(tt(#compdef) var(names...))(
+In this case the file will be made autoloaded and the function defined 
+in it will be called when completing for one of the contexts or
+commands whose var(names) are given. Internally this uses the function 
+tt(compdef) described below.
+)
+item(tt(#compdef -p) var(pattern))(
+This will make the file be made autoloaded and the function will be
+called when completing for a command whose name matches the given
+var(pattern). Not that only one var(pattern) may be given.
+)
+item(tt(#compdef -k) var(style key-sequences...))(
+This can be used bind special completion functions to the
+var(key-sequences). The var(style) given has to be the name of one of
+the builtin widgets that do completion, namely tt(complete-word),
+tt(delete-char-or-list), tt(expand-or-complete),
+tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
+tt(menu-expand-or-complete), or tt(reverse-menu-complete).
+
+Such a tag line will create a widget behaving like the builtin widget
+given by var(style) and bind it to all var(key-sequences) given. If
+one of the var(key-sequences) is typed, the function in the file will
+be invoked to generate the matches. The widget created has the same
+name as the file and can also be bound to other keys using tt(bindkey) 
+as usual.
+)
+item(tt(#autoload))(
+This is used for files defining utility function that are not to be
+used as completion functions directly but should be loaded
+automatically when invoked.
+)
+enditem()
+
+In each of these cases, no white space is allowed between the `tt(#)'
+and the name of the tag.
+
+subsect(Functions)
+
+The tt(compinit) file defines the follwing functions that may
+also be used directly by the user.
+
+startitem()
+xitem(tt(compdef) [ tt(-an) ] var(function names...))
+xitem(tt(compdef -d) var(names...))
+xitem(tt(compdef -p) [ tt(-a) ] var(function pattern))
+item(tt(compdef -k) [ tt(-a) ] var(function style key-sequences...))(
+In the first form makes the completion system call the given
+var(function) be called when completing for the contexts or commands
+whose var(names) are given. If the tt(-n) option is given, the
+var(function) will only be called for contexts or commands for which
+there was no previous definition. These definitions can be deleted
+by giving the tt(-d) option as in the second form.
+
+The third form makes the var(function) be called for all commands
+whose name matches the var(pattern).
+
+The fourth form defines a widget with the same name as the
+var(function) and makes it be called for each of the
+var(key-sequences). The function should generate the completions
+needed and will otherwise behave like the builtin widget whose name is 
+given as the var(style) argument. The widgets usable for this are:
+tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
+tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
+tt(menu-expand-or-complete), and tt(reverse-menu-complete).
+
+In each of the forms supporting it the tt(-a) option makes the
+var(function) autoloaded.
+)
+xitem(tt(compconf) var(definitions...))
+xitem(tt(compconf))
+item(tt(compconf) [ tt(-l) ] var(keys...))(
+Several aspects of the completion system can be configured by the
+user. The configuration values are stored under the keys described
+below in the associative array `tt(compconfig)'. To set configuration
+values, one can either set directly as in
+`tt(compconfig[completer]=_complete)' after sourcing
+tt(compinit), or by calling this utility function.
+
+Each var(definition) may be either a simple `var(key)', which sets this
+key in the tt(compconfig) array to an empty string, or of the form
+`var(key=value)' which stores the `var(value)' under key `var(key)'.
+
+Since the completion system also uses the array for internal purposes
+one should not set all values at once by doing `tt(compconfig=(...))'.
+
+In the second form (without arguments), this function lists all keys
+and their values. If given the tt(-l) option as its first argument, as 
+in the last form, the other arguments are taken as names of keys and
+the values of these keys are printed one per line.
+)
+enditem()
+
+texinode(Control Functions)(Completion Functions)(Initialisation)(Completion System)
+sect(Control Functions)
+
+The initialisation script tt(compinit) re-binds all keys doing
+completion to newly created widgets that all cal the supplied widget
+function tt(_main_complete). This function acts as a wrapper calling
+the so-called completer functions that generate the matches. If it is
+called with arguments, these are taken as the names of completer
+functions that should be called. If no arguments are given, the set of 
+functions to try is taken from the configuration key
+tt(completer). For example if you want to use normal completion and
+correction if that doesn't generate any matches, you can do
+
+indent(nofill(
+tt(compconf completer=_complete:_correct)))
+
+after sourcing tt(compinit). The default value for this
+configuration key set up in tt(compinit) is `tt(_complete)',
+i.e. normally only completion is tried. The tt(_main_complete)
+function uses the return value of the completer functions to decide if 
+other completers should be called. If the return value is zero, no
+other completers are tried and the tt(_main_complete) function
+returns.
+
+The following example completer functions are contained in the
+distribution:
+
+startitem()
+item(tt(_complete))(
+This completer generates all possible completions for the current
+settings of the special completion parameters and the completion
+functions defined using the tt(compdef) function explained above.
+
+To complete arguments of commands it uses the utility function
+tt(_normal), for other contexts it directly looks up the definition
+(given by calls to tt(compdef) or implicitly by automatically
+autoloaded files with `tt(#compdef)' tags).
+
+The names of the special contexts supported are:
+
+startitem()
+item(tt(-equal-))(
+for completion after an equal sign
+)
+item(tt(-tilde-))(
+for completion after a tilde (`tt(~)') character
+)
+item(tt(-redirect-))(
+for completion after a redirection operator
+)
+item(tt(-math-))(
+for completion inside mathematical contexts, such as
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())'
+)
+item(tt(-subscript-))(
+for completion inside subscripts
+)
+item(tt(-value-))(
+for completion on the right hand side of an assignment
+)
+item(tt(-array-value-))(
+for completion on the right hand side of an array-assignment
+(`tt(foo=LPAR()...RPAR())')
+)
+item(tt(-condition-))(
+for completion inside conditions (`tt([[...]])')
+)
+item(tt(-parameter-))(
+for completing the name of a parameter expansion (`tt($...)')
+)
+item(tt(-brace-parameter-))(
+for completing the name of a parameter expansion with braces
+(`tt(${...})')
+)
+enditem()
+
+The example system has a default implementation for each of these
+contexts, in most cases named after the context itself
+(e.g. completion for the `tt(-tilde-)' context is done by the function 
+named `tt(_tilde)').
+)
+item(tt(_approximate))(
+This completer function uses the tt(_complete) completer to generate
+a list of strings for the context the cursor is currently in, allowing 
+a number of errors. The resulting list of corrected and completed
+strings is then presented to the user. The intended use of this
+completer function is to try it after the normal tt(_complete)
+completer by setting:
+
+indent(nofill(
+tt(compconf completer=_complete:_approximate)))
+
+This will give you normal completion and correcting completion if
+normal completion doesn't yield any possible completions. When
+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
+supported configuration keys:
+
+startitem()
+item(tt(approximate_accept))(
+This should be set to the number of errors the correction code should
+accept. The completer will consecutively try to generate completions
+by allowing one error, two errors, and so on, until the maximum number 
+of errors given by this key has been tried or possible completions
+were generated.
+
+If the value for this key contains a lower- or upper-case `tt(n)', the 
+completer function will preferably use the numeric argument as the
+maximum number of errors allowed. For example, with
+
+indent(nofill(
+tt(compconf approximate_accept=2n)))
+
+two errors will be allowed if no numeric argument is given. However,
+with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
+errors are accepted. Also, with a value of `tt(0n)', no correcting
+completion will be attempted, unless a numeric argument is given.
+But if the value contains `tt(n)' or `tt(N)' and a exclamation mark
+(`tt(!)'), this completer will var(not) try to generate corrected
+completions when given a numeric argument.
+)
+item(tt(approximate_original))(
+This key is used to specify if the original string on which correcting 
+completion was attempted should be included in the list of possible
+corrections. If it is set to any non-empty string, the original string 
+will be offered when cycling through the completions. Normally it will 
+appear as the first string, so that the command line does not change
+immediatly, but conecutive completion attempts will cycle through the
+corrected strings. If the value for this key contains the sub-string
+`tt(last)', the original string will be the last one in the list, so
+that it appears just before wrapping around to the first corrected
+string again. Also, if the value contains the sub-string `tt(always)',
+the original string will always be included, whereas normally it is
+included only if more than one possible correction was generated.
+)
+item(tt(approximate_prompt))(
+This can be set to a string that should be displayed on top of the
+corrected strings generated when cycling through them. This string
+may contain the control sequences `tt(%n)', `tt(%B)', etc. known from
+the `tt(-X)' option of tt(compctl). Also, the sequence `tt(%e)' will
+be replaced by the number of errors accepted to generate the corrected 
+strings.
+)
+item(tt(approximate_insert))(
+If this is set to a string starting with `tt(unambig)', the code will try
+to insert a usable unambiguous string in the command line instead of
+always cycling through the corrected strings. If such a unambiguous
+string could be found, the original string is not used, independent of
+the setting of tt(approximate_original). If no sensible string could be
+found, one can cycle through the corrected strings as usual.
+)
+enditem()
+
+If any of these keys is not set, but the the same key with the prefix
+`tt(correct)' instead of `tt(approximate)' is set, that value will be
+used. The forms beginning with `tt(correct)' are also used by the
+tt(_correct) completer function.
+
+The keys with the `tt(approximate)' prefix have no default values, but 
+tt(compinit) defines default values for tt(correct_accept) (which 
+is set to `tt(2n)'), and tt(correct_prompt).
+)
+item(tt(_correct))(
+This completer function uses tt(_approximate), but makes it generate
+only corrected strings, var(not) completed and corrected strings. The
+fact that this completer uses only the configuration keys with the
+`tt(correct)' prefix allows one to give different values to be used
+with correction and correcting completion. For example, with:
+
+indent(nofill(tt(
+  compconf completer=_complete:_correct:_approximate
+  compconf correct_accept='2n!' approximate_accept=3n)))
+
+correction will accept up to two errors. If a numeric argument is
+given, correction will not be used, but correcting completion will
+and it will accept as many errors as given by the numeric argument.
+Without a numeric argument first correction and then correcting
+completion will be tried, with the first one accepting two errors 
+and the second one accepting three errors.
+
+This completer function is intended to be used without the
+tt(_approximate) completer or, as in the example, just before
+it. Using it after the tt(_approximate) completer is useless since
+tt(_approximate) will at least generate the corrected strings
+generated by the tt(_correct) completer -- and probably more.
+)
+item(tt(_match))(
+This completer is intended to be used after the tt(_complete)
+completer. It allows one to give patterns one the command line and
+complete all strings metching these patterns from the set of possible
+completions for the context the cursor is in, without having to set
+the tt(GLOB_COMPLETE) options.
+
+Normally this will be done by taking the pattern from the line,
+inserting a `tt(*)' at the cursor position and comparing the resulting
+pattern with the possible completions generated. However, if the
+configuration key tt(match_original) has a value of `tt(only)', no
+`tt(*)' will be inserted. If the key has any other non-empty string as 
+its value, this completer will first try to generate matches without
+inserted a `tt(*)', and then with the `tt(*)' inserted at the cursor
+position.
+)
+item(tt(_expand))(
+This completer function does not really do completion, but instead
+checks if the word on the command line is eligible for expansion and,
+if it is, gives detailed control over how this expansion is done. When 
+using this, one should not use the tt(expand-or-complete) widget, but
+instead use tt(complete-word), as otherwise tt(expand-or-complete)
+will expand the string on the line before the completion widget is
+called. Also, this completer should be called before the tt(_complete) 
+completer function.
+
+Control over how the expanded string will be treated is given with the 
+following configuration keys:
+
+startitem()
+item(tt(expand_substitute))(
+If this is unset or set to the empty string, the code will first try
+to expand all substitutions in the string (such as
+`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an
+non-empty string it should be an expression usable inside a `tt($[...])'
+arithmetical expression. In this case, expansion of substitutions will
+be done if the expression evaluates to `tt(1)'. For example, with
+
+indent(nofill(
+tt(compconf expand_substitute='NUMERIC != 1')))
+
+substitution will be performed only if given an explicit numeric
+argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'.
+)
+item(tt(expand_glob))(
+If this is unset or set to an empty string, globbing will be attempted
+on the word resulting from substitution or the original string. The
+values accepted for this key are the same as for expand_substitute.
+)
+item(tt(expand_menu))(
+If this is unset or set to the empty string, the words resulting from
+expansion (if any) will simply be inserted in the ommand line,
+replacing the original string. However, if this key is set to an
+non-empty string, the user can cycle through the expansion as in a
+menucompletion. Unless the value contains the sub-string `tt(only)',
+the user will still be offered all expansions at once as one of the
+strings to insert in the command line. Also, if the value contains the
+sub-string `tt(last)', the string with all expansion will be offered
+last, whereas normally it is offered as the first string to
+insert. Finally, if the value contains the sub-string `tt(sort)', the
+expansions will be sorted alphabetically, normally they are kept in
+the order the expansion produced them in.
+)
+item(tt(expand_original))(
+If this is set to an non-empty string, the original string from the
+line will be included in the list of strings the user can cycle
+through as in a menucompletion. If the value contains the sub-string
+`tt(last)', the original string will appear as the last string, with
+other values it is inserted as the first one (so that the command line
+does not change immediatly).
+)
+item(tt(expand_prompt))(
+This may be set to a string that should be displayed before the
+possible expansions. This is given to the `tt(-X)' option of
+tt(compadd) and thus may contain the control sequences `tt(%n)',
+`tt(%B)', etc. Also, the sequence `tt(%o)' in this string will be
+replaced by the original string.
+)
+enditem()
+
+None of these configuration keys has a default value.
+)
+item(tt(_list))(
+This completer allows one to delay the insertion of matches until
+completion is attempted a second time without the word on the line
+being changed. On the first attempt, only the list of matches will be
+shown. Configuration keys understood are:
+
+startitem()
+item(tt(list_condition))(
+If this key is unset or set to the empty string, the insertion of
+matches will be delayed unconditionally. If this value is set, it
+should be set to an expression usable inside a `tt($[...])'
+arithmetical expression. In this case, delaying will be done if the
+expression evaluates to `tt(1)'. For example, with
+
+indent(nofill(
+tt(compconf list_condition='NUMERIC != 1')))
+
+delaying will be done only if given an explicit numeric argument
+other than `tt(1)'.
+)
+item(tt(list_word))(
+To find out if only listing should be done, the code normally compares
+the contents of the line with the contents the line had at the time of
+the last invocation. If this key is set to an non-empty string,
+comparison is done using only the current word. So if it is set,
+attempting completion on a word equal to the one completion was called
+on the last time will not delay the generation of matches.
+)
+enditem()
+)
+item(tt(_menu))(
+This completer is a simple example function implemented to show how
+menucompletion can be done in shell code. It should be used as the
+first completer and has the effect of making the code use
+menucompletion. Note that this is independent of the setting of the
+tt(MENU_COMPLETE) option and does not work with the other
+menucompletion widgets such as tt(reverse-menu-complete), or
+tt(accept-and-menu-complete).
+)
+enditem()
+
+texinode(Completion Functions)()(Control Functions)(Completion System)
+sect(Utility Functions)
+
+The tt(Core) directory contains several utility functions that may be
+interesting to use when writing completion functions. Like the example 
+functions for commands in the distribution, the utility functions
+generating matches all follow the convention to return zero if they
+generated completions and non-zero if no matching completions could be 
+added.
+
+startitem()
+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
+there is a definition (given with the tt(compdef) function). For
+example, the function completing inside subscripts might use
+`tt(_compalso -math-)' to include the completions generated for
+mathematical environments.
+)
+item(tt(_normal))(
+This function is used to complete for normal commands, i.e. if
+completion is attempted on the first word, command names are
+completed. Otherwise, the arguments are completed by calling the
+functions defined for this command, including those functions defined
+for patterns matching the command name. This function can also be
+called by other completion functions if they have to complete a range
+of words as a separate command. The function to complete after the
+pre-command specifiers such as tt(nohup), for example calls this
+function after removing the first word from the tt(words) array and
+decrementing the tt(CURRENT) parameter.
+
+When calling a function defined for a pattern, this function also
+checks if the parameter tt(_compskip) is set. If it was set by the
+function called, no further completion functions are called. With this 
+one can write a pattern completion function that keeps other functions 
+from being tried by simple setting this parameter to any value.
+)
+item(tt(_multi_parts))(
+This functions gets two arguments: a separator character and an
+array. As usual for the completion code, the array may be given as the 
+name of an array parameter or as a literal array in the form
+`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white 
+space in parentheses). With these arguments, this function will
+complete te strings from the array where the parts separated by the
+separator character are completed independently. For example, the
+tt(_tar) function from the distribution caches the pathnames from the
+tar file in an array and then calls this function to complete these
+names in the way, normal filenames are completed by the
+tt(_path_files) function.
+
+Like other utility functions, this function accepts the `tt(-V)',
+`tt(-J)', and `tt(-X)' options with an argument and gives them to the
+tt(compadd) builtin.
+)
+item(tt(_sep_parts))(
+This function gets alternatingly arrays and separators as
+arguments. With this, it completes the strings consisting of different 
+parts, separated by the separator characters. Before and after these
+separators the strings from the arrays are completed. The arrays may
+be given as the names of array parameters or literally as a list of
+words in parentheses. For example, with the array `tt(hosts=(ftp news))'
+the call `tt(_sep_parts '(foo bar)' @ hosts)' will complete the string 
+`tt(f)' to `tt(foo)' and the string `tt(b@n)' to `tt(bar@news)'.
+
+This function gives the `tt(-V)', `tt(-J)', and `tt(-X)' options and
+their arguments to the tt(compadd) builtin used to add the matches.
+)
+item(tt(_path_files) and tt(_files))(
+The function tt(_path_files) is used throughout the example completion 
+system to complete filenames. The advantage over the builtin
+completion functions is that it allows to complete partial paths. For
+example, the string `tt(/u/i/s/sig)' may be completed to
+`tt(/usr/include/sys/signal.h)'. To be able to use this for all cases
+where the completion of filenames is needed it supports the options
+`tt(-/)', `tt(-f)', `tt(-g)', and `tt(-W)' known from the tt(compctl)
+and tt(compgen) builtins. Additionally, the `tt(-F)' option from the
+tt(compadd) builtin is supported, giving direct control over which
+filenames should normally be ignored as done by the tt(fignore)
+parameter for normal completion.
+
+The function tt(_files) calls tt(_path_files) with all arguments it
+got and, if that generated no matches, call tt(_path_files) again
+without any tt(-g) or tt(-/) option, thus generating all filenames.
+
+These functions also accept the `tt(-J)', `tt(-V)', `tt(-X)', `tt(-P)',
+`tt(-S)', `tt(-q)', `tt(-r)', and `tt(-R)' options from the
+tt(compadd) builtin.
+
+Finally, the tt(_path_files) function supports one configuration key:
+tt(path_expand). If this is set to any non-empty string, the partially
+typed path from the line will be expanded as far as possible even if
+trailing pathname components can not be completed.
+)
+item(tt(_parameters))(
+This should be used to complete parameter names if you need some of the
+extra options of tt(compadd). It first tries to complete only non-local
+parameters. All arguments are given unchanged to the tt(compadd) builtin.
+)
+item(tt(_options))(
+This can be used to complete option names. The difference to the
+`tt(-o)' option of tt(compgen) is that this function uses a matching
+specification that ignores a leading `tt(no)', ignores underscores and 
+allows the user to type upper-case letters, making them match their
+lower-case counterparts. All arguments given to this function are
+propagated unchanged to the tt(compgen) builtin.
+)
+item(tt(_set_options) and tt(_unset_options))(
+These functions complete only set or unset options, with the same
+matching specification used in the tt(_options) functions.
+
+Note that you need to uncomment a few lines in the tt(_main_complete)
+function for these functions to work properly. The lines in question
+are used to store the option settings in effect before the completion
+widget locally sets the options it needs.
+)
+item(tt(_long_options))(
+Unlike the other utility functions, this function resides in the
+tt(Base) directory of the example completion system because it is not
+used by the core of the system itself.
+
+This function is used to complete long options for commands that
+support the `tt(--help)' option as, for example, most of the GNU
+commands do. For this it invokes the command from the line with the
+`tt(--help)' option and then parses the output to find possible option
+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 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 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 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:
+
+indent(nofill(
+tt(_long_options '*\*'     '(yes no)' \)
+tt(              '*=FILE*' '_files' \)
+tt(              '*=DIR*'  '_files -/')))
+
+This makes `tt(yes)' and `tt(no)' be completed as the argument of
+options whose description ends in a star, file names for options that
+contain the substring `tt(=FILE)' in the description, and paths for
+options whose description contains `tt(=DIR)'. Note that the last two
+patterns are not needed since this function always completes files
+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, though.
+
+This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)'
+options which are given unchanged to `tt(compadd)'. Finally, it
+accepts the option `tt(-t)'. If this is given, completion is only done
+on words starting with two hyphens.
+)
+item(tt(_match_test))(
+This function is called at the beginning of functions that do matching in
+shell code with one argument: the name of the calling function. It
+should test the value of `tt($compstate[matcher])' and return non-zero
+if the calling function should try to generate matches for the global
+match specification in use.
+
+If you have a global match specification with more than one set of patterns
+you may want to modify this function to return non-zero for all of your
+match specifications and modify the function tt(_match_pattern) to build the
+pattern to use in the calling function.
+)
+item(tt(_match_pattern))(
+This function is called from functions that do matching whenever they
+need to build a pattern that is used to match possible completions.
+It gets the name of the calling function and two names of parameters
+as arguments. The first one is used in the calling function to build
+the pattern used for matching possible completions. The content of this
+parameter on entry to this function is the string taken from the line.
+Here it should be changed to a pattern that matches words as the match
+specifications currently in use do.
+
+In the calling function this pattern may be changed again or used only 
+in parts. The second parameter whose name is given as the third argument
+allows to give pattern flags like `tt(LPAR()#l)tt(RPAR())' that are to
+be used whenever matching is done.
+
+As an example, if you have global match specifications like:
+
+indent(nofill(
+tt(compctl -M 'm:{a-z}={A-Z}' 'm:{a-z}={A-Z} r:|[.-]=* r:|=*')))
+
+This function should look like:
+
+indent(nofill(
+tt(eval "${3}='(#l)'")
+tt([[ compstate[matcher] -eq 2 ]] && eval "$2='${(P)2:gs/./*./:gs/-/*-/}'")))
+
+The first line makes sure that matching is done case-insensitively as
+specified by `tt(m:{a-z}={A-Z})'. The second line replaces dots and hyphens
+in the given string by patterns matching any characters before them,
+like the `tt(r:|[.-]=* r:|=*)'. To make this work, the function `_match_test'
+would have to be changed to `tt(LPAR()LPAR() compstate[matcher] <= 2 RPAR()RPAR())'.
+
+When correction is used (see above), you probably don't want to set
+matching flags here as that may make the results slightly
+unpredictable. For this, change the line above to:
+
+indent(nofill(
+tt([[ compstate[matcher] -lt 0 ]] && eval "${3}='(#l)'")))
+
+The default implementation of this function is empty.
+)
+enditem()
+
+Apart from the functions explained, the tt(Base) sub-directory
+contains functions to complete for the special contexts listed
+above. Normally users may want to use all of these function, probably
+editing some of them.
+
+Also, the tt(Builtins) sub-directory contains completion functions for
+all shell builtin commands, the tt(User) sub-directory contains
+example functions for several standard Unix commands, and the
+tt(Commands) sub-sirectory contains examples for specialised
+completion functions bound to keys.
diff -u od/Zsh/compwid.yo Doc/Zsh/compwid.yo
--- od/Zsh/compwid.yo	Mon Mar 29 11:49:11 1999
+++ Doc/Zsh/compwid.yo	Mon Mar 29 13:30:58 1999
@@ -664,3 +664,9 @@
 
 In this the function will complete words from the history matching the 
 current word.
+
+For a description of the example completion system from the
+distributions, see
+ifzman(zmanref(zshcompsys))\
+ifnzman(noderef(Completion System))\
+.
diff -u od/Zsh/guide.yo Doc/Zsh/guide.yo
--- od/Zsh/guide.yo	Mon Mar 29 11:49:11 1999
+++ Doc/Zsh/guide.yo	Mon Mar 29 15:10:20 1999
@@ -31,6 +31,7 @@
 menu(Programmable Completion)
 menu(Completion Widgets)
 menu(Zsh Modules)
+menu(Completion System)
 
  --- Indices ---
 
diff -u od/Zsh/intro.yo Doc/Zsh/intro.yo
--- od/Zsh/intro.yo	Mon Mar 29 11:49:12 1999
+++ Doc/Zsh/intro.yo	Mon Mar 29 13:28:38 1999
@@ -23,6 +23,7 @@
 list(em(zshcompctl)   Zsh completion control)
 list(em(zshcompwid)   Zsh completion widgets)
 list(em(zshmodules)   Zsh loadable modules)
+list(em(zshcompsys)   Zsh completion system)
 ifzshone(\
 list(em(zshall)       Meta-man page containing all of the above)
 )\
diff -u od/Zsh/modules.yo Doc/Zsh/modules.yo
--- od/Zsh/modules.yo	Mon Mar 29 11:49:13 1999
+++ Doc/Zsh/modules.yo	Mon Mar 29 13:36:20 1999
@@ -1,4 +1,4 @@
-texinode(Zsh Modules)()(Completion Widgets)(Top)
+texinode(Zsh Modules)(Completion System)(Completion Widgets)(Top)
 chapter(Zsh Modules)
 cindex(modules)
 sect(Description)
diff -u od/Zsh/seealso.yo Doc/Zsh/seealso.yo
--- od/Zsh/seealso.yo	Mon Mar 29 11:49:13 1999
+++ Doc/Zsh/seealso.yo	Mon Mar 29 13:29:06 1999
@@ -11,6 +11,7 @@
 zmanref(zshbuiltins),
 zmanref(zshcompctl),
 zmanref(zshcompwid),
+zmanref(zshcompsys),
 zmanref(zshexpn),
 zmanref(zshmisc),
 zmanref(zshmodules),
diff -u od/Makefile.in Doc/Makefile.in
--- od/Makefile.in	Tue Mar 30 11:26:10 1999
+++ Doc/Makefile.in	Tue Mar 30 11:29:22 1999
@@ -38,7 +38,7 @@
 .SUFFIXES: .yo .1
 
 # man pages to install
-MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 \
+MAN = zsh.1 zshbuiltins.1 zshcompctl.1 zshcompwid.1 zshcompsys.1 \
 zshexpn.1 zshmisc.1 zshmodules.1 \
 zshoptions.1 zshparam.1 zshzle.1 zshall.1
 
@@ -48,7 +48,7 @@
 Zsh/compat.yo Zsh/compctl.yo Zsh/cond.yo Zsh/exec.yo Zsh/expn.yo \
 Zsh/filelist.yo Zsh/files.yo Zsh/func.yo Zsh/grammar.yo Zsh/guide.yo \
 Zsh/index.yo Zsh/intro.yo Zsh/invoke.yo Zsh/jobs.yo Zsh/metafaq.yo \
-Zsh/modules.yo Zsh/mod_cap.yo Zsh/compwid.yo \
+Zsh/modules.yo Zsh/mod_cap.yo Zsh/compwid.yo Zsh/compsys.yo \
 Zsh/mod_clone.yo Zsh/mod_comp1.yo Zsh/mod_compctl.yo Zsh/mod_deltochar.yo \
 Zsh/mod_example.yo Zsh/mod_files.yo Zsh/mod_stat.yo \
 Zsh/mod_zle.yo Zsh/options.yo \
@@ -114,6 +114,8 @@
 zshcompctl.1: Zsh/compctl.yo
 
 zshcompwid.1: Zsh/compwid.yo
+
+zshcompsys.1: Zsh/compsys.yo
 
 zshexpn.1: Zsh/expn.yo
 
diff -u od/zsh.yo Doc/zsh.yo
--- od/zsh.yo	Tue Mar 30 11:26:11 1999
+++ Doc/zsh.yo	Mon Mar 29 13:27:18 1999
@@ -66,6 +66,7 @@
 ifnzman(includefile(Zsh/compctl.yo))

 ifnzman(includefile(Zsh/compwid.yo))

 ifnzman(includefile(Zsh/modules.yo))

+ifnzman(includefile(Zsh/compsys.yo))

 ifzshall(\
 def(source)(1)(NOTRANS(.so )man1/ARG1NOTRANS(.)1)\
 CMT()
@@ -78,6 +79,7 @@
 source(zshcompctl)
 source(zshcompwid)
 source(zshmodules)
+source(zshcompsys)
 manpage(ZSHALL)(1)(date())(zsh version())
 )\
 ifzman(includefile(Zsh/filelist.yo))

diff -u Doc/zshcompsys.yo Doc/zshcompsys.yo
--- Doc/zshcompsys.yo	Tue Mar 30 11:26:36 1999
+++ Doc/zshcompsys.yo	Mon Mar 29 13:28:07 1999
@@ -0,0 +1,3 @@
+manpage(ZSHCOMPSYS)(1)(date())(zsh version())
+manpagename(zshcompsys)(zsh completion system)
+includefile(Zsh/compsys.yo)


--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx