From e74702b467171dbdafb56dfe354794a212e020d9 Mon Sep 17 00:00:00 2001
From: Tanaka Akira <akr@users.sourceforge.net>
Date: Thu, 15 Apr 1999 18:05:38 +0000
Subject: Initial revision

---
 Doc/Zsh/compsys.yo | 691 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 Doc/Zsh/compwid.yo | 428 +++++++++++++++++++++++++++++++++
 Doc/zshcompsys.yo  |   3 +
 Doc/zshcompwid.yo  |   3 +
 4 files changed, 1125 insertions(+)
 create mode 100644 Doc/Zsh/compsys.yo
 create mode 100644 Doc/Zsh/compwid.yo
 create mode 100644 Doc/zshcompsys.yo
 create mode 100644 Doc/zshcompwid.yo

(limited to 'Doc')

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
new file mode 100644
index 000000000..632cb3195
--- /dev/null
+++ b/Doc/Zsh/compsys.yo
@@ -0,0 +1,691 @@
+texinode(Completion System)()(Zsh Modules)(Top)
+chapter(Completion System)
+cindex(completion, system)
+cindex(completion, programmable)
+cindex(completion, controlling)
+sect(Description)
+
+This describes the shell code for the new completion system.  It consists
+of two scripts and a few other files that define shell functions.
+The shell functions which implement completion behaviour and which may
+be bound to keystrokes, are referred to as `widgets'.  All are contained
+in the following subdirectories of the tt(Completion) directory of the main
+distribution directory.
+
+startitem()
+item(tt(Core))(
+The core scripts and functions.  You will certainly need these, though will
+probably not need to alter them.  The contents of this directory is
+described in more detail below.
+)
+item(tt(Base))(
+Other functions you will almost certainly want if you are going to use
+any of the standard completion functions.  You may want to edit some of
+these files.
+)
+item(tt(Builtins))(
+Functions for completing arguments of shell builtin commands.
+)
+item(tt(User))(
+Functions for completing arguments of external commands and suites of
+commands.  They may need modifying for your system.
+)
+item(tt(Commands))(
+Functions which implement special types of completion to be bound to
+keystrokes rather than called by context.
+)
+enditem()
+
+You should decide which files you will be using and copy them to a
+directory (or multiple directories) of your own which should appear in your
+tt($fpath) variable so that the functions can be autoloaded.
+
+startmenu()
+menu(Initialisation)
+menu(Control Functions)
+menu(Completion Functions)
+endmenu()
+
+texinode(Initialisation)(Control Functions)()(Completion System)
+sect(Initialisation)
+
+To initialise the system, the script tt(compinit) should be sourced with
+`tt(source )var(<path>)tt(/compinit)' or
+`tt(. )var(<path>)tt(/compinit)'. This will define a few utility functions,
+arrange for all the necessary shell functions to be autoloaded, and will
+then re-bind all keys that do completion to use the new system.
+
+subsect(Arguments)
+
+To speed up the running of tt(compinit), it can be made to produce a dumped
+configuration which will be read in on future invocations.  The easiest way
+to do this is by adding the option tt(-d) whenever tt(compinit) is sourced.
+In this case the dumped file will have the same name as the sourced file,
+but with tt(.dump) appended to the end; alternatively, an explicit file
+name can be given following the tt(-d).  On the next call to tt(compinit
+-d), the dumped file will be read instead.
+
+If the number of completion files changes, tt(compinit) will recognise this
+and produce a new dump file.  However, if the name of a function or the
+arguments in the first line of a tt(#compdef) funcion (as described below)
+change, it is easiest to delete the dump file by hand so that the next time
+tt(compinit) will re-create it.
+
+The dumping is actually done by another script, tt(compdump), but you will
+only need to source this yourself if you change the configuration
+(e.g. using tt(compdef)) and then want to dump the new one.  The name of
+the old dumped file will be remembered for this.
+
+subsect(Autoloaded files)
+
+The convention for autoloaded functions used in completion is that they
+start with an underscore; as already mentioned, the tt(fpath/FPATH)
+parameter must contain the directory in which they are stored.  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 should
+contain 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 are:
+
+startitem()
+item(tt(#compdef) var(names...))(
+The file will be made autoloadable and the function defined 
+in it will be called when completing var(names), each of which is
+either the name of a command whose arguments are to be completed or one of
+a number of special contexts in the form tt(-)var(context)tt(-) described
+below for the tt(_complete) function.
+)
+item(tt(#compdef -p) var(pattern))(
+The file will be made autoloadable and the function defined in it will be
+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 -k) var(style key-sequences...))(
+This can be used bind special completion functions to the
+var(key-sequences).  It creates a widget behaving like the builtin widget
+var(style), which must be one of those that perform 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).
+
+The widget is then bound to all the var(key-sequences) given, if any: when
+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
+called directly as completion functions but should be loaded automatically
+when invoked.  Typically they are to be called from within one of the
+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
+below; the main difference is that the name of the function is supplied
+implicitly.
+
+subsect(Functions)
+
+The tt(compinit) file defines the following functions, which may
+also be called 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...))(
+The first form tells the completion system to call the given
+var(function) when completing for the contexts or commands
+whose var(names) are given:  this is like the tt(#compdef) tag.  If the
+tt(-n) option is given, any existing completion behaviour for particular
+contexts or commands will not be altered.  These definitions can be deleted
+by giving the tt(-d) option as in the second form.
+
+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)
+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
+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) autoloadable (exactly equivalent to
+tt(autoload )var(function)).
+)
+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)'.  After sourcing
+tt(compinit), configuration values can either be set directly as in
+`tt(compconfig[completer]=_complete)' 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,
+you 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 the keys which perform
+completion to newly created widgets that all call the supplied widget
+function tt(_main_complete). This function acts as a wrapper calling
+the so-called `completer' functions that generate matches. If
+tt(_main_complete) is
+called with arguments, these are taken as the names of completer
+functions to be called in the order given.  If no arguments are given, the
+set of functions to try is taken from the colon-separated list in the
+configuration key tt(completer). For example, to use normal
+completion and correction if that doesn't generate any matches:
+
+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 ordinary
+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 completer functions are contained in the distribution (users
+may write their own):
+
+startitem()
+item(tt(_complete))(
+This completer generates all possible completions in a context-sensitive
+manner, i.e. using the tt(compdef) function
+explained above and the current settings of all special parameters.
+
+To complete arguments of commands, tt(_complete) uses the utility function
+tt(_normal), which is in turn responsible for finding the particular
+function; it is described below.  Various contexts of the form
+tt(-)var(context)tt(-), as mentioned above for the tt(#compdef) tag, are
+handled specially.  These are:
+
+startitem()
+item(tt(-equal-))(
+for completion after an equal sign, other than one occurring in a
+shell-variable assignment.
+)
+item(tt(-tilde-))(
+for completion after a tilde (`tt(~)') character, but before a slash.
+)
+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 within braces
+(`tt(${...})').
+)
+item(tt(-first-))(
+for adding completions before any other other completion functions are
+tried (similar to the `tt(-T)' flag of tt(compctl)); if this
+function sets the tt(_compskip) parameter to any value, the completion
+system will not call any other function to generate matches.
+)
+item(tt(-default-))(
+for generating completions when no special completion function is used 
+(similar to the `tt(-D)' option of tt(compctl)).
+)
+item(tt(-command-))(
+for completing in a command position (as with the `tt(-C)' option of
+tt(compctl)).
+)
+enditem()
+
+Default implementations are supplied 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 
+you to specify a maximum number of errors:  see the description of
+approximate matching in
+ifzman(\
+zmanref(zshexpn)
+)\
+ifnzman(\
+noderef(Filename Generation)
+)\
+for how errors are
+counted. The resulting list of corrected and completed strings is then
+presented to the user. The intended use of this completer function is to
+try after the normal tt(_complete) completer by setting:
+
+indent(
+nofill(tt(compconf completer=_complete:_approximate))
+)
+
+This will give correcting completion if and only 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
+following configuration keys:
+
+startitem()
+item(tt(approximate_accept))(
+This should be set to the number of errors the correction code should
+accept. The completer will try to generate completions by first allowing
+one error, then two errors, and so on, until either a match
+was found or the maximum number of errors given by this key has
+been reached.
+
+If the value for this key contains a lower- or upper-case `tt(n)', the 
+completer function will take any 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.  Hence with a value of `tt(0n)', no correcting
+completion will be attempted unless a numeric argument is given.
+
+If the value contains `tt(n)' or `tt(N)' and a exclamation mark
+(`tt(!)'), tt(_approximate) will var(not) try to generate corrected
+completions when given a numeric argument, so in this case the number given
+should be greater than zero.  For example, `tt(2n!)' specifies that
+correcting completion with two errors will usually be performed, but if a
+numeric argument is given, correcting completion will not be performed.
+)
+item(tt(approximate_original))(
+This key is used to specify whether the original string on which correcting 
+completion was attempted is to 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
+immediately; consecutive completion attempts will cycle through the
+corrected strings.  If the value for this key contains the substring
+`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 substring `tt(always)',
+the original string will always be included; normally it is
+included only if more than one possible correction was generated.
+)
+item(tt(approximate_prompt))(
+This can be set to a string to 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))(
+Generate corrections (but not completions) for the current word; this is
+similar to spell-checking.  This calls tt(_approximate), but only the
+configuration parameters beginning tt(correct_) are used.
+
+For example, with:
+
+indent(tt(
+nofill(compconf completer=_complete:_correct:_approximate)
+nofill(compconf correct_accept='2n!' approximate_accept=3n))
+)
+
+correction will accept up to two errors. If a numeric argument is
+given, correction will not be performed, but correcting completion will be,
+and 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 on the command line and
+to 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) option.
+
+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 tt(match_original) has any other non-empty
+string as its value, this completer will first try to generate matches
+without, then with a `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 possible 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 tt(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 command line,
+replacing the original string. However, if this key is set to a
+non-empty string, the user can cycle through the expansion as in
+menucompletion. Unless the value contains the substring `tt(only)',
+the user will still be offered all expansions at once as one of the
+strings to insert in the command line; normally, this possibility is
+offered first, but if the value contains the
+substring `tt(last)', it is offered last. Finally, if the value contains
+the substring `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 substring
+`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 immediately).
+)
+item(tt(expand_prompt))(
+This may be set to a string that should be displayed before the
+possible expansions. This is passed 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 listing should be performed on its own, 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 when completion was called
+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 perform
+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)
+
+Descriptions follow for utility functions that may be
+useful when writing completion functions.  Most of these reside in the
+tt(Core) subdirectory except where noted. Like the example 
+functions for commands in the distribution, the utility functions
+generating matches all follow the convention of returning 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 for normal command completion.  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. For example, the function to complete after
+the pre-command specifiers such as tt(nohup) removes the first word from
+the tt(words) array, decrements the tt(CURRENT) parameter, then calls this
+function.
+
+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 simply by setting this parameter to any value.
+)
+item(tt(_multi_parts))(
+This functions gets two arguments: a separator character and an
+array.  As usual, the array may be either the
+name of an array parameter or 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 to 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 passes them to the
+tt(compadd) builtin.
+)
+item(tt(_sep_parts))(
+This function gets as arguments alternating arrays and separators.
+The arrays specify completions for parts of strings to be separated by the
+separators. The arrays may be the names of array parameters or
+a quoted 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 passes 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 shell code
+to complete filenames. The advantage over the builtin
+completion functions is that it allows completion of partial paths. For
+example, the string `tt(/u/i/s/sig)' may be completed to
+`tt(/usr/include/sys/signal.h)'.  The options `tt(-/)', `tt(-f)', `tt(-g)',
+and `tt(-W)' are available as for the tt(compctl)
+and tt(compgen) builtins; tt(-f) is the default. Additionally, the `tt(-F)'
+option from the tt(compadd) builtin is supported, giving direct control
+over which filenames should be ignored as done by the tt(fignore)
+parameter in normal completion.
+
+The function tt(_files) calls tt(_path_files) with all the arguments
+it was passed 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 passed 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 passed 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) function.
+
+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))(
+This function resides in the tt(Base) subdirectory of the example
+completion system because it is not used by the core system.
+
+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
+automatically tries to 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
+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
+command (probably with arguments) that should be invoked to complete 
+after the equal sign. Example:
+
+indent(
+nofill(tt(_long_options '*\*'     '(yes no)' \))
+nofill(tt(              '*=FILE*' '_files' \))
+nofill(tt(              '*=DIR*'  '_files -/'))
+)
+
+Here, `tt(yes)' and `tt(no)' will 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)'. In fact, 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, however.
+
+This function also accepts the `tt(-X)', `tt(-J)', and `tt(-V)'
+options which are passed 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.
+)
+enditem()
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
new file mode 100644
index 000000000..2cb12e2c2
--- /dev/null
+++ b/Doc/Zsh/compwid.yo
@@ -0,0 +1,428 @@
+texinode(Completion Widgets)(Zsh Modules)(Programmable Completion)(Top)
+chapter(Completion Widgets)
+cindex(completion, widgets)
+cindex(completion, programmable)
+cindex(completion, controlling)
+sect(Description)
+Completion widgets are defined using the tt(-C) option to the tt(zle)
+builtin command provided by the tt(zle) module (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(The zle Module))\
+). For example, the invocation:
+
+indent(nofill(
+tt(zle -C complete expand-or-complete completer)))
+
+defines a widget named tt(complete). If this widget is bound to a key
+using the tt(bindkey) builtin command defined in the tt(zle) module
+(see 
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) typing that key will make the completion code call the shell
+function tt(completer). This function is responsible for generating
+the possible matches using the builtins described below. Once the
+function returns, the completion code takes over control again and
+treats the matches the way the builtin widget tt(expand-or-complete)
+would do it. For this second argument, the name of any of the builtin
+widgets that handle completions can be given, i.e. it may be any of
+tt(complete-word), tt(expand-or-complete),
+tt(expand-or-complete-prefix), tt(menu-complete),
+tt(menu-expand-or-complete), tt(reverse-menu-complete),
+tt(list-choices), or tt(delete-char-or-list).
+
+startmenu()
+menu(Special Parameters)
+menu(Builtin Commands)
+menu(Condition Codes)
+menu(Examples)
+endmenu()
+
+texinode(Special Parameters)(Builtin Commands)()(Completion Widgets)
+sect(Special Parameters)
+
+Inside completion widgets some parameters have special meaning. They
+will be used inside the widget function and other shell functions
+called from it. Outside of these function they are not special to the
+shell in any way.
+
+The parameters are used to give information about the internal state
+from the completion code to the completion widget and can be set to
+give information to the completion code from the completion
+widget. Some of the builtin commands and the condition codes use or
+change the current values of these parameters. While the completion
+widget is active, these parameters are reseton each function exit to
+the values they had when the function was entered.
+
+startitem()
+item(tt(argv))(
+The positional parameters are set to the arguments on the command line
+when the widget function is invoked from the completion code.
+)
+item(tt(CURRENT))(
+This is the number of the current word, i.e. the word the cursor is
+currently on in the tt(argv) array.
+)
+item(tt(CONTEXT))(
+This will be set by the completion code to the overall context
+completion is attempted in. Possible values are:
+
+startitem()
+item(tt(command))(
+when completing in a command position, e.g. in the first word on the
+command line
+)
+item(tt(argument))(
+when completing an argument for a command
+)
+item(tt(redirect))(
+when completing after a redirection operator; in this case the
+positional parameters contain not only the arguments but also the
+command name itself as the first element
+)
+item(tt(condition))(
+when completing inside a `tt([[)...tt(]])' conditional expressing; in
+this case the positional parameters are set to the words inside the
+conditional expressions
+)
+item(tt(math))(
+when completing in a mathematical environment such as a
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())' construct
+)
+item(tt(value))(
+when completing the value of a parameter assignment; in case of an
+array value the positional parameters are set to the words in
+parentheses
+)
+item(tt(subscript))(
+when completing inside a parameter expansion subscript
+)
+enditem()
+)
+item(tt(COMMAND))(
+In most cases this is set to name of the command for which completion
+is tried. When completing after a redirection operator it contains the 
+string forming that operator. Also, when completing in the value of a
+parameter assignment or in a parameter subscript it is set to the name
+of the parameter.
+)
+item(tt(PREFIX))(
+This should be set to that part of the current word that should be
+taken as the string every possible match has to begin with. Initially
+this will be set to the part of the current word from the beginning of
+the word up to the position of the cursor. When 
+)
+item(tt(IPREFIX))(
+When a part of the current word should not be considered part of the
+matches, this part should be taken from the tt(PREFIX) parameter and
+appended to this parameter. This will initially be set to the empty
+string when called from the completion code.
+)
+item(tt(SUFFIX))(
+This should be set to that part of the current word that should be
+taken as the string every possible match has to end with. The
+completion code sets this to the part of the current word from the
+cursor position to the end.
+)
+item(tt(NMATCHES))(
+This is always set to the number of matches generated and accepted by
+the completion code so far.
+)
+item(tt(MATCHER))(
+When completion is used with a global match specification (i.e. a
+tt(compctl) with only a tt(-M) option), this parameter is set to the
+number of the specification string which is currently used.
+)
+enditem()
+
+texinode(Builtin Commands)(Condition Codes)(Special Parameters)(Completion Widgets)
+sect(Builtin Commands)
+startitem()
+findex(complist)
+item(tt(complist) var(flags ...))(
+
+Generate matches according to the given var(flags) which can be any of 
+the option flags supported by the tt(compctl) builtin command (see
+ifzman(zmanref(zshcompctl))\
+ifnzman(noderef(Programmable Completion))\
+) except for the tt(-t) and tt(-l) flags. Also, when using the tt(-K)
+flag, the function given as argument to it can not access the command
+line with the tt(read) builtin command.
+
+The matches will be generated in the same way as if the completion code
+generated them directly from a tt(compctl)-definition with the same
+flags. The completion code will consider only those matches as
+possible completions that match the prefix and suffix from the special 
+parameters desribed above. These strings will be compared with the
+generated matches using the normal matching rules and any matching
+specifications given with the tt(-M) flag to tt(complist) and the
+global matching specifications given to the tt(compctl) builtin
+command.
+)
+xitem(tt(compadd) [ tt(-qQfnUam) ] [ tt(-F) var(array) ])
+xitem([ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ])
+xitem([ tt(-p) var(hidden-prefix) ] [ tt(-s) var(hidden-suffix) ])
+xitem([ tt(-i) var(ignored-prefix) ] [ tt(-W) var(file-prefix) ])
+xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ])
+xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
+item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
+
+This builtin command can be used to add matches and directly control
+all the information the completion code stores with each possible
+match.
+
+The supported flags are:
+
+startitem()
+item(tt(-P) var(prefix))(
+The same as for tt(compctl) and tt(complist), it gives a string that
+should be inserted before the given words when they are completed. The
+string given is not considered to be part of the match.
+)
+item(tt(-S) var(suffix))(
+Like tt(-P) but gives a string that has to be inserted after the match.
+)
+item(tt(-p) var(hidden-prefix))(
+This gives a string that should be 
+...
+)
+item(tt(-s) var(hidden-suffix))(
+...
+)
+item(tt(-i) var(ignored-prefix))(
+...
+)
+item(tt(-J) var(name))(
+As for tt(compctl) and tt(complist) this gives the name of the group
+of matches the words should be stored in.
+)
+item(tt(-V) var(name))(
+Like tt(-J) but naming a unsorted group.
+)
+item(tt(-q))(
+This flag has the same meaning as for tt(compctl) and tt(complist),
+too. It makes the suffix given with tt(-S) be automatically removed if 
+the next character typed is a blank or does not insert anything or if
+the suffix consists of only one character and the next character typed 
+is the same character.
+)
+item(tt(-r) var(remove-chars))(
+This makes the suffix given with tt(-S) be automatically removed if
+the next character typed inserts one of the characters given in the
+var(remove-chars). This string is parsed as a characters class with
+the usual backslash-sequences understood, e.g. using `tt(-r "a-z\t")'
+removes the suffix if the next character typed inserts one of the
+lower case letters or a TAB, and `tt(-r "^0-9")' removes the suffix if 
+the next character typed inserts anything but a digit. One extra
+backslash sequence is understood in this string: `tt(\-)' stands for
+all characters that insert nothing. Thus `tt(-S "=" -q)' is the same
+as `tt(-S "=" -r "= \t\n\-")'.
+)
+item(tt(-R) var(remove-func))(
+For the cases where one wants to remove suffix and the tt(-r) option
+does not give enough control, this option can be used. It stores the
+name of the shell function var(remove-func) in the matches. If one of
+the matches is finally accepted and the tt(-S)-suffix inserted, this
+function will be called after the next character typed. It gets the
+length of the suffix as its argument and can use the special
+parameters available in zle widgets (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+) to analyse and modify the command line.
+)
+item(tt(-f))(
+If this flag is given, the matches build are marked as being the names 
+of files. They need not be actual filenames, though. But if they are
+and the option tt(LIST_TYPES) is set, the characters describing the
+types of the files in the completion lists will be shown. This also
+makes a slash automatically be added when the name of a directory is
+completed.
+)
+item(tt(-W) var(file-prefix))(
+This option has the same meaning as for the tt(compctl) and
+tt(complist) builtin commands. Here, however, only one string may be
+given, not an array. This string is used as a pathname that will be
+prepended to the given words and the prefix given with the tt(-p)
+option to perform the file-tests when showing completion
+listings. Hence it is only useful if combined with the tt(-f) flag,
+since the tests will only be performed if that flag is given.
+)
+item(tt(-a))(
+When used by tt(compctl) or tt(complist) the completion code normally
+builds two sets of matches: the normal one where words with one of the 
+suffixes in the array parameter tt(fignore) are not considered
+possible matches, and the alternate set where the words excluded
+from the first set are stored. Normally only the matches in the first
+set are used. But if this set is empty, the words from the alternate
+set are used.
+
+The tt(compadd) builtin does not use tt(fignore) parameter and
+normally stores all words in the first set. With the tt(-a)-flag
+given, however, they are all stored in the alternate set unless this
+flag is overridden by the tt(-F) option.
+)
+item(tt(-F) var(array))(
+This can be used to give an array containing suffixes like the
+tt(fignore) parameter. Words with one of these suffixes are stored in
+the alternate set of matches and words without one of these suffixes
+are stored in the normal set.
+
+The var(array) may be the name of an array parameter or a list of
+literal suffixes enclosed in parentheses as in `tt(-F "(.o .h)")'. If
+the name of an array is given, the elements of the array are taken as
+the suffixes.
+)
+item(tt(-Q))(
+As for tt(compctl) and tt(complist) this flag instructs the completion 
+code not to quote any metacharacters in the words when inserting them
+in the command line.
+)
+item(tt(-m))(
+Normally the matches added by tt(compadd) will not be compared with
+what is already on the line. If this flag is given, this comparison is 
+performed as usual and the match specifications given with the tt(-M)
+option to tt(compadd) and the global match specifications defined with 
+tt(compctl) will be used. This means that probably not all the word
+given will be stored as matches since some of them may not match the
+string on the line.
+)
+item(tt(-M) var(match-spec))(
+This option allows one to give local match specifications with the
+same meaning and format as for the tt(compctl) and tt(complist)
+builtin commands. Note that they will only be used if the tt(-m) is
+given, too.
+)
+item(tt(-n))(
+Words added with tt(compadd) with this flag will be used as possible
+matches as usual but they not appear in the completion listing.
+)
+item(tt(-U))(
+If this flag is given to one of the calls to tt(compadd) and the
+option tt(AUTO_MENU) is set, the completion code will immediatly
+switch to menucompletion.
+)
+item(tt(-), tt(--))(
+This flag ends the list of flags and options. All arguments after it
+will be taken as the words to use as matches even if they begin with
+hyphens.
+)
+enditem()
+)
+item(tt(compcall) [ tt(-TD) ])(
+
+This allows one to use completion definitions given with the
+tt(compctl) builtin from within completion widgets. It makes
+completion code complete the current word according to the
+tt(compctl)s defined. Normally only tt(compctl)s given for specific
+commands are used. To make the code use the completion flags given to
+the tt(-T) option of tt(compctl), one can give the tt(-T) flag to
+tt(compctl). Likewise, the tt(-D) flag to tt(compcall) makes the
+default completion flags given to tt(compctl) with the tt(-D) option
+be used.
+)
+enditem()
+
+texinode(Condition Codes)(Examples)(Builtin Commands)(Completion Widgets)
+sect(Condition Codes)
+
+Inside completion widgets not only the builtin commands described
+above can be used, but also some additional condition codes. These
+work on the special parameters and can be used to easily build
+completion functions that generate different matches depending on the
+strings on the line.
+
+The following condition codes are made available inside completion
+widgets:
+
+startitem()
+item(tt(-prefix) var(string))(
+true if the content of tt(PREFIX) starts with var(string)
+)
+item(tt(-iprefix) var(string))(
+like tt(-prefix), but the var(string) is removed from tt(PREFIX) and
+added to tt(IPREFIX)
+)
+item(tt(-position) var(beg) [ var(end) ])(
+true if tt(CURRENT) is equal to var(beg) or, if var(end) is given,
+equal to or greater than var(beg) and equal to or less than var(end);
+both of var(beg) and var(end) may be arithmetic expressions, if they
+are less than zero the number of words in tt(argv) are added to them
+before comparing them to tt(CURRENT); thus, tt(-1) is the last word,
+tt(-2) is the word before that and so on
+)
+item(tt(-word) var(index) var(string))(
+true if the word number var(index) in tt(argv) is equal to
+var(string); again, var(index) may be negative, counting backwards
+)
+item(tt(-mword) var(index) var(pattern))(
+like tt(-word) but using pattern matching
+)
+item(tt(-current) var(offset) var(string))(
+like tt(-word) but var(offset) is relative to the value of
+tt(CURRENT)
+)
+item(tt(-mcurrent) var(offset) var(pattern))(
+like tt(-current) but using pattern matching
+)
+item(tt(-string) [ var(number) ] var(string))(
+true if the current word contains var(string); anything up to the last 
+occurrence of this string will be ingnored by removing it from
+tt(PREFIX) and adding it to tt(IPREFIX); if var(number) is given,
+anything up to the var(number)'th occurrence of the var(string) will
+be ignored; again, var(nmuber) may be any arithmetic expression and
+negative values count backward
+)
+item(tt(-class) [ var(number) ] var(class))(
+like tt(-string) but the var(class) is used as a character class so
+that anything up to and including the last or the var(number)'th
+occurrence of any character from the string var(class) is ignored
+)
+item(tt(-words) var(min) [ var(max) ])(
+true if the number of words is equal to var(min); if var(max) is
+given, it is true if the number of words is equal to or greater than
+var(min) and equal to or less than var(max)
+)
+item(tt(-after) var(string))(
+true if the cursor is after a word that is equal to var(string)
+)
+item(tt(-mafter) var(pattern))(
+like tt(-after) but using pattern matching
+)
+item(tt(-between) var(string1) var(string2))(
+true if the cursor is after a word that is equal to var(string1), if
+there is also a word that is equal to va(string2), this is true only
+if the cursor is before it
+)
+item(tt(-mbetween) var(pattern1) var(pattern2))(
+like tt(-between) but using pattern matching
+)
+item(tt(-nmatches) var(number))(
+true if the the value of tt(NMATCHES) is equal to var(number)
+)
+item(tt(-matcher) var(number))(
+true if the value of tt(MATCHER) is equal to var(number)
+)
+enditem()
+
+texinode(Examples)()(Condition Codes)(Completion Widgets)
+sect(Examples)
+
+The first step is to define the widget:
+
+indent(nofill(
+tt(zle -C complete complete-word complete-history)))
+
+Then the widget can be bound to a key using the tt(bindkey) builtin
+command:
+
+indent(nofill(
+tt(bindkey '^X\t' complete)))
+
+After that the shell function tt(complete-history) will be invoked
+after typing control-X and TAB. The function should then generte the
+matches, e.g.:
+
+indent(nofill(
+tt(complete-history LPAR()RPAR() { complist -H 0 '' })))
+
+In this the function will complete words from the history matching the 
+current word.
diff --git a/Doc/zshcompsys.yo b/Doc/zshcompsys.yo
new file mode 100644
index 000000000..d640606b6
--- /dev/null
+++ b/Doc/zshcompsys.yo
@@ -0,0 +1,3 @@
+manpage(ZSHCOMPSYS)(1)(date())(zsh version())
+manpagename(zshcompsys)(zsh completion system)
+includefile(Zsh/compsys.yo)

diff --git a/Doc/zshcompwid.yo b/Doc/zshcompwid.yo
new file mode 100644
index 000000000..d876e422d
--- /dev/null
+++ b/Doc/zshcompwid.yo
@@ -0,0 +1,3 @@
+manpage(ZSHCOMPWID)(1)(date())(zsh version())
+manpagename(zshcompwid)(zsh completion widgets)
+includefile(Zsh/compwid.yo)

-- 
cgit 1.4.1