Initial revision

1 files changed, 691 insertions, 0 deletions

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()