PATCH: compsys.yo

PATCH: compsys.yo

[Sven Wischnowsky]

This is the fix for two more things Peter talked about: at one place
(at least I could only find one place) there was a context name used
without the `:completion' prefix and then there is the documentation
of the default tag.

Bye
 Sven

diff -ru ../z.old/Doc/Zsh/compsys.yo Doc/Zsh/compsys.yo
--- ../z.old/Doc/Zsh/compsys.yo	Thu Dec 16 14:34:12 1999
+++ Doc/Zsh/compsys.yo	Thu Dec 16 14:42:04 1999
@@ -278,11 +278,13 @@
 
 The completion system represents contexts as hierarchical name s
 with components separated by colons. For example, take the context
-`tt(:complete::dvips::-o-1)'.  The tt(:complete) at the
-beginning is the `completer', which is in overall control of how completion
-is to be performed; `tt(complete)' is the basic one for
-ordinary completion, but completers may perform various related tasks
-such as correction, or modify the behaviour of a later completer (see
+`tt(:completion:complete::dvips::-o-1)'.  The tt(:completion) at the
+beginning just says that this context is used in the completion system 
+and the tt(:complete) after it is the `completer', which is in overall
+control of how completion is to be performed; `tt(complete)' is the
+basic one for ordinary completion, but completers may perform various
+related tasks such as correction, or modify the behaviour of a later
+completer (see
 ifzman(the section `Control Functions' below)\
 ifnzman(noderef(Control Functions)) 
 for more information).  Strictly, the completer is `tt(_complete)', but the
@@ -430,6 +432,10 @@
 )
 item(tt(cvs))(
 used only to look up the value of the tt(disable-stat) style
+)
+item(tt(default))(
+used to look up default values for various styles that may also be set 
+for tags that are used when generating matches
 )
 item(tt(descriptions))(
 used when looking up the value of the tt(format) style for

--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

PATCH: compsys.yo

[Peter Stephenson]

Here's an approximate reconstruction of my patch for the completion
documentation.  As always, it may be hopelessly inaccurate.

I altered _argument_sets to _arguments in the examples since the
documentation has changed to remove _argument_sets from everywhere else.

Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.54
diff -u -r1.54 compsys.yo
--- Doc/Zsh/compsys.yo	2000/05/23 15:27:13	1.54
+++ Doc/Zsh/compsys.yo	2000/05/23 19:19:03
@@ -2524,17 +2524,17 @@
 )
 findex(_alternative)
 item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
-This function is useful if you offer multiple tags and building the
-matches for them is easy enough. It basically implements a loop like
-the one described for the tt(_tags) function below.
-
-The tags to use and what to do if the tags are requested are described 
-using the var(specs) which are of the form:
-`var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered
-using tt(_tags) and if the tag is requested, the var(action) is
-executed with the given var(descr) (description). The var(action)s
-supported are those used by the tt(_arguments) function (described
-below), without the `tt(->)var(state)' and `tt(=)var(...)' forms.
+This function is useful in simple cases where multiple tags are available.
+Essentially, it implements a loop like the one described for the tt(_tags)
+function above.
+
+The tags to use and the action to perform if a tag is requested are
+described using the var(specs) which are of the form:
+`var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered using
+tt(_tags) and if the tag is requested, the var(action) is executed with the
+given description var(descr).  The var(action)s supported are those used
+by the tt(_arguments) function (described below), without the
+`tt(->)var(state)' and `tt(=)var(...)' forms.
 
 For example, the var(action) may be a simple function call. With that
 one could do:
@@ -2557,16 +2557,16 @@
 findex(_arguments)
 item(tt(_arguments) var(specs) ...)(
 This function can be used to complete words on the line by simply
-describing the arguments the command on the line gets. The description 
-is given as arguments to this function, with each var(spec) describing
-one option or normal argument of the command. The descriptions
-understood are:
+describing the arguments which may be passed to the command for which
+completion is being performed.  The description is given as arguments to
+this function, with each var(spec) describing one option or normal argument
+of the command.  The descriptions understood are:
 
 startitem()
 item(var(n)tt(:)var(message)tt(:)var(action))(
-This describes the var(n)'th normal argument. The var(message) will be 
+This describes the var(n)'th normal argument.  The var(message) will be 
 printed above the matches generated and the var(action) says what can
-be completed in this position (see below). If there are two colons
+be completed in this position (see below).  If there are two colons
 before the var(message), this describes an optional argument.
 )
 item(tt(:)var(message)tt(:)var(action))(
@@ -2768,17 +2768,17 @@
 the tt(curcontext) parameter will be changed by appending the same
 string that is stored in the tt(context) parameter.
 
-The aruments also allows to specify multiple sets of options and
-arguments separated by single hyphens. The specifications before
-the first hyphen are shared by all sets given after the first
-hyphen. The first word in every other set gives the name of the
+It is also possible to specify multiple sets of options and
+arguments with the sets separated by single hyphens.  The specifications
+before the first hyphen are shared by all sets given after the first
+hyphen.  The first word in every other set gives the name of the
 set. This name may appear in exclusion lists in the specifications,
 either alone or before one of the possible values described above
 (with a `tt(-)' between the name and the rest).
 
 For example:
 
-example(_argument_sets \ 
+example(_arguments \ 
     -a \ 
   - set1 \ 
     -c \ 
@@ -2800,7 +2800,7 @@
 useful for defining multiple sets of options which are mutually
 exclusive and in which the options are aliases for each other. E.g.:
 
-example(_argument_sets \ 
+example(_arguments \ 
     -a -b \ 
   - '(compress)' \ 
     {-c,--compress}'[compress]' \ 
@@ -2933,37 +2933,36 @@
 )
 findex(_call)
 item(tt(_call) var(tag) var(string) ...)(
-This function is used in places where a command is called and the user 
-should have the possibility to override the default for calling this
-command. It looks up the tt(command) style with the supplied
-var(tag). If the style is set, its value is used as the command to
-execute.
+This function is used in places where a command is called, making it
+possible for the user to override the default command call.  It looks up
+the tt(command) style with the supplied var(tag).  If the style is set, its
+value is used as the command to execute.
 
-In any case, the var(strings) from the call to tt(_call) or from the
+In any case, the var(string)s from the call to tt(_call) or from the
 style are concatenated with spaces between them and the resulting
-string is evaluated. The return value is the return value of the
+string is evaluated.  The return value is the return value of the
 command called.
 )
 findex(_combination)
 item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(specs) ... var(field) var(opts) ...)(
 This function is used to complete combinations of values such as pairs 
-of hostnames and usernames. The possible values will be taken from the 
-var(style) whose name is given as the second argument. The first argument
+of hostnames and usernames.  The possible values will be taken from the 
+var(style) whose name is given as the second argument.  The first argument
 is the var(tag) to use to do the lookup.
 
 The style name should consist of multiple parts separated by
-hyphens which are then used as fieldnames. Known values for such
+hyphens which are then used as field names.  Known values for such
 fields can be given after the second argument in arguments of the form 
-`var(field)tt(=)var(pattern)'. The first argument without a equal sign 
+`var(field)tt(=)var(pattern)'.  The first argument without a equal sign 
 is taken as the name of the field for which completions should be
 generated.
 
-The matches generated will be taken from the value of the style. These 
+The matches generated will be taken from the value of the style.  These 
 values should contain the possible values for the combinations where
 the values for the different fields are separated by colons or
 characters matching the pattern given after the tt(-s) option to
-tt(_combination) (normally this is used to define character classes
-like the `tt(-s "[:@]")' used for the tt(users-hosts) style).
+tt(_combination); normally this is used to define character classes
+like the `tt(-s "[:@]")' used for the tt(users-hosts) style.
 
 Only the values for the requested fields for which the patterns given
 in the `var(field)tt(=)var(pattern)' match the respective fields in
@@ -2972,7 +2971,7 @@
 If no style with the given name is defined for the given tag but a
 function named with the name of the requested field preceded by an
 underscore is defined, that function will be called to generate the
-matches. This is also done if none of the strings in the value of the
+matches.  This is also done if none of the strings in the value of the
 style match all the patterns given as arguments.
 
 If the same name is used for more than one field, in both the
@@ -2980,80 +2979,86 @@
 name to complete for, the number of the field (starting with one) may
 be given after the fieldname, separated from it by a colon.
 
-All arguments after the requested fieldname are given to the
-tt(compadd) used (when generating matches from the style value) and to 
+All arguments after the requested field name are passed to
+tt(compadd) when generating matches from the style value, or to 
 the functions for the fields if they are called.
 )
 findex(_compalso)
 item(tt(_compalso) var(names) ...)(
 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
+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.
 )
 findex(_describe)
 item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
-This function can be used to add options or values with descriptions
-as matches. The var(descr) is taken as a string to display above
-the matches if the tt(format) style for the tt(descriptions) tag is set.
-
-After this one or two names of arrays followed by options to give
-to tt(compadd) must be given. The first array contains the possible
-completions with their descriptions (with the description separated
-by a colon from the completion string). If the second array is given,
-it should have the same number of elements as the first one and these
-elements are added as possible completions instead of the strings from 
-the first array. In any case, however, the completion list will contain
-the strings from the first array.
-
-Any number of array/option sequences may be given separated by
-`tt(-)tt(-)'. This allows one to display matches together that need
-to be added with different options for tt(compadd).
-
-Before the first argument, the option `tt(-o)' may be given. It says
-that the matches added are option names. This will make tt(_describe)
-use the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles
-to find out if the strings should be added at all and if the
-descriptions should be shown. Without the `tt(-o)' option, only the
-tt(verbose) style is used.
+This function is useful for preparing a list of command options or
+arguments, together with their descriptions var(descr), as matches.
+Multiple groups separated by tt(-)tt(-) can be supplied, potentially with
+different completion options var(opts).
+
+The var(descr) is taken as a string to display above the matches if the
+tt(format) style for the tt(descriptions) tag is set.  After this come one
+or two names of arrays followed by options to pass to tt(compadd).  The
+first array contains the possible completions with their descriptions in
+the form `var(completion)tt(:)var(description)'.  If a second array is
+given, it should have the same number of elements as the first one and the
+corresponding elements are added as possible completions instead of the
+var(completion) strings from the first array.  The completion list will
+retain the descriptions from the first array.  Finally, a set of completion
+options can appear.
+
+If the option `tt(-o)' appears before the first argument, the matches added
+will be treated as option names (typically following a `tt(-)',
+`tt(-)tt(-)' or `tt(+)' on the command line).  This makes tt(_describe) use
+the tt(prefix-hidden), tt(prefix-needed) and tt(verbose) styles to find out
+if the strings should be added at all and if the descriptions should be
+shown.  Without the `tt(-o)' option, only the tt(verbose) style is used.
 
 tt(_describe) uses the tt(_all_labels) function to generate the matches, so
-that one doesn't need to put it into a loop over the tag labels.
+it does not need to appear inside a loop over tag labels.
 )
 findex(_description)
 item(tt(_description) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
-This function tests some styles for the var(tag) and and stores
-options usable for tt(compadd) in the array with the given var(name)
-which guarantee that the matches are generated as requested by the
-user. The styles tested are: tt(format) (which is first tested for the
-given tag and then for the tt(descriptions) tag if that isn't
-defined), tt(hidden), tt(matcher), tt(ignored-patterns) and
-tt(group-name) (the last are tested only for the tag given as the
-first argument). This function also calls the tt(_setup) function
-which tests some more styles.
-
-The format string from the style (if any) will be modified so that the 
-sequence `tt(%d)' is replaced by the var(descr) given as the third
-argument. If tt(_description) is called with more than three
-arguments, these var(specs) should be of the form
-`var(char)tt(:)var(str)' and every appearance of `tt(%)var(char)' in
-the format string will be replaced by var(string).
+This function is called before completions are added (typically by a call
+to tt(compadd)); it tests various styles and arranges for any necessary
+options to be passed on to tt(compadd).  The styles are tested in the
+current context using the given var(tag); options are put into the array
+called var(name) for passing on to tt(compadd); the description for the
+current set of matches is passed in var(descr).  The styles tested are:
+tt(format) (which is first tested for the given var(tag) and then for the
+tt(descriptions) tag if that isn't defined), tt(hidden), tt(matcher),
+tt(ignored-patterns) and tt(group-name) (the last are tested only for the
+tag given as the first argument).  This function also calls the tt(_setup)
+function which tests some more styles.
+
+The string returned by the tt(format) style (if any) will be modified so
+that the sequence `tt(%d)' is replaced by the var(descr) given as the third
+argument.  If tt(_description) is called with more than three arguments,
+the additional var(specs) should be of the form `var(char)tt(:)var(str)'
+and every appearance of `tt(%)var(char)' in the format string will be
+replaced by var(string).
 
 The options placed in the array will also make sure that the matches
 are placed in a separate group, depending on the value of the
-tt(group-name) style. Normally a sorted group will be used for this
+tt(group-name) style.  Normally a sorted group will be used for this
 (with the `tt(-J)' option), but if a option starting with `tt(-V)',
 `tt(-J)', `tt(-1)', or `tt(-2)' is given, that option will be included
 in the array, so that it is possible to make the group unsorted by
 giving the option `tt(-V)', `tt(-1V)', or `tt(-2V)'. 
 
-In most cases, this function will be used like this:
+In most cases, the function will be used like this:
 
 example(local expl
 _description files expl file
 compadd "$expl[@]" - "$files[@]")
+
+Note the use of the parameter tt(expl), the hyphen, and the list of
+matches.  Almost all calls to tt(compadd) within the completion system use
+a similar format; this ensures that user-specified styles are correctly
+passed down to the builtins which implement the internals of completion.
 )
 findex(_funcall)
 item(tt(_funcall) var(return) var(name) [ var(args) ... ])(
@@ -3083,29 +3088,30 @@
 )
 findex(_multi_parts)
 item(tt(_multi_parts) var(sep) var(array))(
-This function gets two arguments: a separator character and an
+This function receives two arguments: a separator character and an
 array.  As usual, the var(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
+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
+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
+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.
+tt(_path_files) function, by using `tt(_multi_parts) tt(/)
+var(patharray)'.
 
-If given the tt(-i) option a single match left will be accepted
-immediatly even if that means that additional parts for which no
-separators were on the line are to be inserted. When completing from a 
-fixed set of possible completions which are really words, this is
-often the expected behaviour. But if tt(_multi_parts) should behave
-like completing pathnames, the tt(-i) option should not be used.
+If the tt(-i) option is present, then any time there is a unique match it
+will immediately be inserted even if that requires additional separators to
+be inserted as well.  When completing from a fixed set of possible
+completions which are really words, this is often the expected behaviour;
+however, if tt(_multi_parts) should behave like completing pathnames, the
+tt(-i) option should not be used.
 
 Like other utility functions, this function accepts the `tt(-V)',
-`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)', `tt(-P)',
-`tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes them to
-the tt(compadd) builtin.
+`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)',
+`tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes
+them to the tt(compadd) builtin.
 )
 findex(_next_label)
 item(tt(_next_label) [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])(
@@ -3145,43 +3151,44 @@
 )
 findex(_normal)
 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 and uses the value in the 
-same way it is used after calling the completion function for the
-tt(-first-) context. With this 
-one can write a pattern completion function that keeps other functions 
-from being tried simply by setting this parameter to any value.
+This function is used for normal command completion.  It has two tasks:
+completing the first word on the command line as the name of a command, and
+completing the arguments to this command.  In the second case, the name of
+the command is looked up to see if special completions exists, including
+completions defined for patterns which match the name.  If none is found,
+completion is performed for the context tt(-default-).
+
+The function can also be called by other completion functions which need to
+treat a range of words as a command line.  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 tt(_normal) again, with the effect that `tt(nohup) var(cmd ...)'
+is treated the same way was `var(cmd ...)'.
+
+If the command name matches a pattern, the parameter tt(_compskip) is
+checked after the call to the corresponding completion function.  This has
+the same effect here as in the tt(-first-) context: if it is set, no more
+completion functions are called even if there are no matches so far.
 )
 findex(_parameters)
 item(tt(_parameters))(
-This should be used to complete parameter names. All arguments are
+This should be used to complete parameter names.  All arguments are
 passed unchanged to the tt(compadd) builtin.
 )
 findex(_path_files)
 findex(_files)
 item(tt(_path_files) and tt(_files))(
-The function tt(_path_files) is used throughout the shell code
-to complete filenames. It allows completion of partial paths. For
+The function tt(_path_files) is used throughout the completion system
+to complete filenames.  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 function tt(_files) uses the tt(file-patterns) style and calls
 tt(_path_files) with all the arguments it was passed except for tt(-g) 
-and tt(-/). These two options are used depending on the setting of the 
+and tt(-/).  These two options are used depending on the setting of the 
 tt(file-patterns) style.
 
-Options accepted by both tt(_path_files) and tt(_files) are:
+The options accepted by both tt(_path_files) and tt(_files) are:
 
 startitem()
 item(tt(-f))(
@@ -3191,18 +3198,18 @@
 Specifies that only directories should be completed.
 )
 item(tt(-g) var(pattern))(
-Says that only files matching the var(pattern) should be completed.
+Specifies that only files matching the var(pattern) should be completed.
 )
 item(tt(-W) var(paths))(
 Specifies path prefixes that are to be prepended to the string from the
 line to generate the filenames but that should not be inserted in the line
-or shown in a completion listing. The var(paths) may be the name of an
+or shown in a completion listing.  Here, var(paths) may be the name of an
 array parameter, a literal list of paths enclosed in parentheses or an
 absolute pathname.
 )
 item(tt(-F))(
 This option from the tt(compadd) builtin gives direct control over which
-filenames should be ignored. If no such option is given, the
+filenames should be ignored.  If the option is not present, the
 tt(ignored-patterns) style is used.
 )
 enditem()
@@ -3216,10 +3223,10 @@
 )
 findex(_options)
 item(tt(_options))(
-This can be used to complete option names. It uses a matching
+This can be used to complete option names.  It 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
+allows the user to type upper-case letters which will match their
+lower-case counterparts.  All arguments passed to this function are
 propagated unchanged to the tt(compadd) builtin.
 )
 findex(_regex_arguments)
@@ -3289,33 +3296,33 @@
 )
 findex(_requested)
 item(tt(_requested) [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
-A function that uses tt(_tags) to register tags and then calls it to
-loop over the requested sets of tags should call this function to
-check if a certain tag is currently requested. This normally has to be 
-done in a loop such as:
+This function is called to decide whether a tag already registered by a
+call to tt(_tags) (see below) is requested and hence completion should be
+performed for it; it returns status zero if the tags is requested and
+non-zero otherwise.  This will usually be done in a loop such as the
+following:
 
 example(_tags foo bar baz
 while _tags; do
   if _requested foo; then
-    ...
+    ... # perform completion for foo
   fi
-  ... # test other tags
+  ... # test the tags bar and baz in the same way
   ... # exit loop if matches were generated
 done)
 
-So, the first argument for tt(_requested) is used as the name of a tag 
-and if that tag is currently requested, the return value is zero (and
-non-zero otherwise).
+Note that the test for whether matches were generated is not performed
+until the end of the tt(_tags) loop.  This is so that the user can specify
+a set of tags to be tested at the same time in the tt(tag-order)
+parameter.
 
 If the var(name) and the var(descr) are given, tt(_requested) calls the
 tt(_description) function with these arguments, including the options.
 
 If the var(command) is given, the tt(_all_labels) function will be called
-immediately with the same arguments.
-
-This is often useful to do both the testing of the tag,
-getting the description for the matches and adding the matches at
-once. E.g.:
+immediately with the same arguments.  This is often useful to do both the
+testing of the tag, getting the description for the matches and adding the
+matches at once.  For example:
 
 example(local expl ret=1
 _tags foo bar baz
@@ -3328,10 +3335,10 @@
 )
 findex(_sep_parts)
 item(tt(_sep_parts))(
-This function gets as arguments alternating arrays and separators.
+This function is passed alternating arrays and separators as arguments.
 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
+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)'.
@@ -3348,9 +3355,10 @@
 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
+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.
+widget locally sets the options it needs.  Hence these options are not
+generally used by the completion system.
 )
 findex(_setup)
 item(tt(_setup) var(tag))(
@@ -3363,11 +3371,12 @@
 )
 findex(_sort_tags)
 item(tt(_sort_tags) var(tag) ...)(
-As described above for the tt(tag-order) style, this is only provided
-to show how functions that sort tags can be implemented.
+No such function is actually used by the completion system; as mentioned
+above for the tt(tag-order) style, it is only provided to show how
+functions that sort tags can be implemented.
 
 Inside such functions the name of the current context can
-be accessed using the tt(curcontext) parameter. For example, the
+be accessed using the tt(curcontext) parameter.  For example, the
 function used in command position (called tt(_command_names)) in the
 completion can generate names of external and builtin commands, names
 of shell functions, aliases and parameters and reserved words.
@@ -3388,13 +3397,13 @@
 })
 
 Every call to the tt(comptry) builtin command gives a
-set of tags to use; as soon as completion system produces
-some matches for one set, subsequent sets have no effect.  Hence in
+set of tags to use; as soon as the completion system produces
+matches for one set, subsequent sets have no effect.  Hence in
 the example this means that in command position on the first attempt
 only names of external commands and shell functions will be generated
-(first call to tt(comptry)). If none of those names match the string
+(the first call to tt(comptry)).  If none of those names match the string
 from the command line the completion function will generate names of
-builtin commands and aliases as possible matches (second call to
+builtin commands and aliases as possible matches (the second call to
 tt(comptry)).
 
 For all other context names the second case-pattern matches, so that
@@ -3403,15 +3412,15 @@
 all offered tags as a default, so in the first case names or
 parameters and reserved words will never be completed.
 
-In every context the function may call tt(comptry) as often as it
-wants. Also, every string may be given as argument, even if no tag
-with such a name was offered by the completion function. This allows
+In any context the function may call tt(comptry) as often as necessary.
+Also, any string may be given as an argument, even if no tag
+with that name was offered by the completion function.  This allows
 one to give a preferred ordering for some common tag sets without
-having to worry about sensible patterns for context names. For
+having to worry about sensible patterns for context names.  For
 example, many completion functions can generate both arguments and
-option names for commands. These functions normally use the tags
+option names for commands.  These functions normally use the tags
 like tt(argument-)var(num), tt(option-)var(name)tt(-)var(num) and
-tt(options). Depending on your preference you may write in your
+tt(options).  Depending on your preference you may write in your
 sorting function:
 
 example(_sort_tags() {
@@ -3431,13 +3440,12 @@
   esac
 })
 
-The former always adds both the matches for the argument and the
-option names as possible matches. The latter forces matches for the
-arguments to be preferred. In this case option names are only generated
-as matches if the string on the line matches no possible completion
-for the argument, which normally means that you have to type the
-hyphen the option names start with yourself to see the list of option
-names that can be completed.
+The former always adds both the matches for the argument and the option
+names as possible matches.  The latter forces matches for the arguments to
+be preferred.  In this case option names are only generated as matches if
+the string on the line produces no possible completion for arguments;
+normally you would have to type the hyphen the option names start with
+yourself in order to see the list of option names that can be completed.
 
 With the tt(-s) option, each tag given to tt(comptry) will be put in a 
 separate set. With the tt(-m) option, the arguments are treated in the 
@@ -3448,10 +3456,10 @@
 item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])(
 If called with arguments, these are taken as the names of the tags for 
 the types of matches the calling completion function can generate in
-the current context. These tags are stored internally and sorted by
-using the tt(tag-order) style. Following calls to this function
+the current context.  These tags are stored internally and sorted by
+using the tt(tag-order) style.  Following calls to this function
 without arguments from the same function will then select the first,
-second, etc. set of tags requested by the user. To test if a certain
+second, etc. set of tags requested by the user.  To test if a certain
 tag should be tried, the tt(_requested) function has to be called (see 
 above).
 
@@ -3467,22 +3475,24 @@
 )
 findex(_wanted)
 item(tt(_wanted) [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
-In many contexts only one type of matches can be generated but even
-then it should be tested if the tag representing those matches is
-requested by the user. This function makes that easier.
-
-Like tt(_requested) it gets arguments as for tt(_description).
-With the var(tag) it calls tt(_tags) and if that returns zero 
-(i.e. the var(tag) is requested by the user) it calls tt(_description). So, 
-if you want to offer only one tag and immediatly want to use the
-description built, you can just do:
+In many contexts, completion will one generate one particular set of
+matches (usually corresponding to a single tag); however, it is
+still necessary to decide whether the user requires matches of this type.
+This function is useful in such a case.
+
+Like tt(_requested), it should be passed arguments as for tt(_description).
+It calls tt(_tags) with the given var(tag) and if that returns zero 
+(so that the var(tag) is requested by the user) it calls
+tt(_description).  Hence to offer only one tag and immediately
+use the description generated:
 
 example(_wanted tag expl 'description' \ 
     compadd matches...)
 
-Unlike tt(_requested), however, tt(_wanted) can not be called without
-the var(command). That's because tt(_wanted) also implements the loop
-over the tags, not only the one for the labels.
+Unlike tt(_requested), however, tt(_wanted) cannot be called without
+the var(command).  This is because tt(_wanted) also implements the loop
+over the tags, not just the one for the labels; conversely, it should not
+be called in the middle of a tt(_tags) loop.
 
 Like tt(_tags) this function supports the tt(-C) option to give a
 different name for the argument context field.
@@ -3490,16 +3500,18 @@
 findex(_values)
 item(tt(_values) var(specs) ...)(
 This is used to complete values (strings) and their arguments or
-lists of such values.
+lists of such values.  It can be used in two ways.
 
-If the first argument is the option `tt(-O) var(name)', this will be
-used in the same way as by the tt(_arguments) function. I.e. the
+If the first argument is the option `tt(-O) var(name)', this will be used
+in the same way as by the tt(_arguments) function, in other words the
 elements of the var(name) array will be given to calls to tt(compadd)
 and when executing an action.
 
 Otherwise, if the first argument (or the first argument after the
 `tt(-O) var(name)' option if that is used) is the option `tt(-s)', the
 next argument is used as the character that separates multiple values.
+Thus the values completed appear in the same word on the command line,
+unlike completion using tt(_arguments).
 
 The first argument (after the options and separator character if they
 are given) is used as a string to print as a description before
@@ -3507,8 +3519,8 @@
 
 All other arguments describe the possible values and their
 arguments in the same format used for the description of options by
-the tt(_arguments) function (see above). The only difference is that
-there is no required minus or plus sign at the beginning and that
+the tt(_arguments) function (see above).  The only differences are that
+no minus or plus sign is required at the beginning and that
 values can have only one argument.
 
 Example:
@@ -3519,43 +3531,43 @@
         'two[another number]::second count:(1 2 3)')
 
 This describes three possible values: `tt(foo)', `tt(one)', and
-`tt(two)'. The first one is described as `tt(bar)', gets no argument 
-and may appear more than once. The second one is described as
-`tt(number)', may appear more than once, and gets one mandatory
+`tt(two)'.  The first is described as `tt(bar)', takes no argument 
+and may appear more than once.  The second is described as
+`tt(number)', may appear more than once, and takes one mandatory
 argument described as `tt(first count)' for which no action is
-specified so that it will not be completed automatically. The
+specified so that it will not be completed automatically.  The
 `tt((two))' at the beginning says that if the value `tt(one)' is on
-the line, the value `tt(two)' will not be  considered to be a possible
-completion anymore. Finally, the last value (`tt(two)') is described
-as `tt(another number)' and gets an optional argument described as
+the line, the value `tt(two)' will not be considered to be a possible
+completion anymore.  Finally, the last value (`tt(two)') is described
+as `tt(another number)' and takes an optional argument described as
 `tt(second count)' which will be completed from the strings `tt(1)',
 `tt(2)', and `tt(3)'. The tt(_values) function will complete lists of
 these values separated by commas.
 
 Like tt(_arguments) this function temporarily adds another context
 name component to the current context name while executing the
-var(action). Here this name is just the name of the value for which
+var(action).  Here this name is just the name of the value for which
 the argument is completed.
 
 To decide if the descriptions for the values (not those for the
-arguments) should be printed, the tt(verbose) is used.
+arguments) should be printed, the style tt(verbose) is used.
 
-One last difference to tt(_arguments) is that this function uses the
+One last difference from tt(_arguments) is that this function uses the
 associative array
-tt(val_args) to report values and their arguments (but otherwise this
+tt(val_args) to report values and their arguments, although otherwise this
 is the same as the tt(opt_args) association used by
-tt(_arguments)). This also means that the function calling tt(_values) 
+tt(_arguments).  This also means that the function calling tt(_values) 
 should declare the tt(state), tt(line), tt(context) and tt(val_args)
 parameters as in:
 
 example(local context state line
 typeset -A val_args)
 
-when using an action of the form `tt(->)var(string)'. With this
+when using an action of the form `tt(->)var(string)'.  With this
 function the tt(context) parameter will be set to the name of the
 value whose argument is to be completed.
 
-Like tt(_arguments), tt(_values) also supports the tt(-C) option in
+Like tt(_arguments), tt(_values) supports the tt(-C) option in
 which case you have to make the parameter tt(curcontext) local instead 
 of tt(context) (as described above).
 )
@@ -3585,12 +3597,17 @@
 )
 item(tt(Builtins))(
 Functions for completing arguments of shell builtin commands and
-utility functions for this (which are also used by functions from the
-tt(User) directory).
+utility functions for this.  Some of these are also used by functions from
+the tt(User) directory.
 )
 item(tt(User))(
 Functions for completing arguments of external commands and suites of
-commands.  They may need modifying for your system.
+commands.  They may need modifying for your system, although in many cases
+some attempt is made to decide which version of a command is present.  For
+example, completion for the tt(mount) command tries to determine the system
+it is running on, while completion for many other utilities try to decide
+whether the GNU version of the command is in use, and hence whether the
+tt(--help) option is supported..
 )
 item(tt(Commands))(
 Functions which implement special types of completion to be bound to

-- 
Peter Stephenson <pws@pwstephenson.fsnet.co.uk>
Work: pws@CambridgeSiliconRadio.com
Web: http://www.pwstephenson.fsnet.co.uk

Re: PATCH: compsys.yo

[Sven Wischnowsky]

Peter Stephenson wrote:

> > -Other functions will you will almost certainly want if you are going to use
> > +Other functions you will almost certainly want if you are going to use
> 
> With my English quarreling you are?  Or like this speaking never have you?
> Unlearn you must.

:-) Stupity on my side, I just so the double `will'. Ahem. Sorry. May the...

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

RE: PATCH: compsys.yo

[Andrej Borsenkow]

>
> And then I saw that... Andrej: have I missed something, or did you
> forget to document your changes to `_long_options'?
>

Yeah, you are right. I changed it in comments to _long_options.

But I have found one unfortunate problem with configure. It does not play
well together with --with/--without options. That is, if you try to
complete --w-s-f (meaning --with-some-feature), you now inevitably get
both --with and --without. I'll have yet to think, what can be done. One
possibility is to have separate groups for options in help output and one
for "inferred" options.

If Peter decides to include this patch in spite of the above problem, I'll
make a patch for docs.

cheers

/andrej

Re: PATCH: compsys.yo

[Peter Stephenson]

Sven Wischnowsky wrote:
> P.S.: I changed a couple of `#defcomp's to `#compdef's, or will that
>       patch not make it into pws-15?

Thanks, that was just stupidity.

> -Other functions will you will almost certainly want if you are going to use
> +Other functions you will almost certainly want if you are going to use

With my English quarreling you are?  Or like this speaking never have you?
Unlearn you must.

-- 
Peter Stephenson <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy

Re: PATCH: compsys.yo

[Sven Wischnowsky]

Peter Stephenson wrote:

> I've done some work on the zshcompsys manual page.  You may want to quarrel
> with this.

Thanks! (And as long as we don't have users who tried to understand
what's going on I don't expect this to be the final form anyway.)

And then I saw that... Andrej: have I missed something, or did you
forget to document your changes to `_long_options'?

Bye
 Sven

P.S.: I changed a couple of `#defcomp's to `#compdef's, or will that
      patch not make it into pws-15?

--- od/Zsh/compsys.yo	Wed Apr 14 12:36:24 1999
+++ Doc/Zsh/compsys.yo	Wed Apr 14 13:07:28 1999
@@ -19,7 +19,7 @@
 described in more detail below.
 )
 item(tt(Base))(
-Other functions will you will almost certainly want if you are going to use
+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.
 )
@@ -67,7 +67,7 @@
 
 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(#defcomp) funcion (as described below)
+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.
 
@@ -80,7 +80,7 @@
 
 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 the are stored.  When
+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
@@ -142,18 +142,18 @@
 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(#defcomp) tag.  If the
+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(#defcomp -p) function tag.
+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(#defcomp -k) tag.  The function should generate the completions needed
+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),
@@ -410,7 +410,7 @@
 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) options.
+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
@@ -418,7 +418,7 @@
 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
-first without, then with a `tt(*)' inserted at the cursor position.
+without, then with a `tt(*)' inserted at the cursor position.
 )
 item(tt(_expand))(
 This completer function does not really do completion, but instead
@@ -452,7 +452,7 @@
 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.
+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
@@ -635,7 +635,7 @@
 )
 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.
+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

--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

PATCH: compsys.yo

[Peter Stephenson]

I've done some work on the zshcompsys manual page.  You may want to quarrel
with this.  I still have to look at zshcompwid (probably not before
pws-15).

I've removed references to this as an `example' system.  I think it's
enough to point out which bits users are likely to want to alter.  If they
want to start again from scratch that's up to them.

--- Doc/Zsh/compsys.yo.old	Tue Apr 13 14:36:25 1999
+++ Doc/Zsh/compsys.yo	Wed Apr 14 11:25:11 1999
@@ -5,15 +5,40 @@
 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.
+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 will 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)
@@ -24,73 +49,69 @@
 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.
+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)
 
-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).
+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(#defcomp) 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)
 
-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 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 the 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 looked for are:
+The tags 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.
+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))(
-This will make the file be made autoloaded and the function will be
+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). Not that only one var(pattern) may be 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). 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),
+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).
 
-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
+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) 
@@ -98,62 +119,66 @@
 )
 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.
+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()
 
-In each of these cases, no white space is allowed between the `tt(#)'
-and the name of the tag.
+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 follwing functions that may
-also be used directly by the user.
+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...))(
-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
+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(#defcomp) 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 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:
+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(#defcomp -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(#defcomp -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) autoloaded.
+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)'. 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.
+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
-one should not set all values at once by doing `tt(compconfig=(...))'.
+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 
@@ -165,94 +190,95 @@
 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
+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 the matches. If it is
+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 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.
+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 example completer functions are contained in the
-distribution:
+The following completer functions are contained in the distribution (users
+may write their own):
 
 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:
+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
+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
+for completion after a tilde (`tt(~)') character, but before a slash.
 )
 item(tt(-redirect-))(
-for completion after a redirection operator
+for completion after a redirection operator.
 )
 item(tt(-math-))(
 for completion inside mathematical contexts, such as
-`tt(LPAR()LPAR())...tt(RPAR()RPAR())'
+`tt(LPAR()LPAR())...tt(RPAR()RPAR())'.
 )
 item(tt(-subscript-))(
-for completion inside subscripts
+for completion inside subscripts.
 )
 item(tt(-value-))(
-for completion on the right hand side of an assignment
+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())')
+(`tt(foo=LPAR()...RPAR())').
 )
 item(tt(-condition-))(
-for completion inside conditions (`tt([[...]])')
+for completion inside conditions (`tt([[...]])').
 )
 item(tt(-parameter-))(
-for completing the name of a parameter expansion (`tt($...)')
+for completing the name of a parameter expansion (`tt($...)').
 )
 item(tt(-brace-parameter-))(
-for completing the name of a parameter expansion with braces
-(`tt(${...})')
+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 (comparable to the `tt(-T)' flag of tt(compctl)); if this
+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
+system will not call any other function to generate matches.
 )
 item(tt(-default-))(
 for generating completions when no special completion function is used 
-(comparable to the `tt(-D)' option of tt(compctl))
+(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))
+tt(compctl)).
 )
 enditem()
 
-The example system has a default implementation for each of these
+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)').
@@ -260,61 +286,75 @@
 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:
+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)))
+indent(
+nofill(tt(compconf completer=_complete:_approximate))
+)
 
-This will give you normal completion and correcting completion if
+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
-supported configuration keys:
+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 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.
+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 preferably use the numeric argument as 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)))
+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.
+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 if the original string on which correcting 
-completion was attempted should be included in the list of possible
+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
-immediatly, but conecutive completion attempts will cycle through the
-corrected strings. If the value for this key contains the sub-string
+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 sub-string `tt(always)',
-the original string will always be included, whereas normally it is
+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 that should be displayed on top of the
+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
@@ -341,20 +381,21 @@
 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)))
+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 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
+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.
 
@@ -366,8 +407,8 @@
 )
 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
+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) options.
 
@@ -375,10 +416,9 @@
 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.
+`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
+first without, then with a `tt(*)' inserted at the cursor position.
 )
 item(tt(_expand))(
 This completer function does not really do completion, but instead
@@ -390,7 +430,7 @@
 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 
+Control over how the expanded string will be treated is possible with the 
 following configuration keys:
 
 startitem()
@@ -398,12 +438,13 @@
 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($[...])'
+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')))
+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)'.
@@ -415,29 +456,28 @@
 )
 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)',
+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. 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.
+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 sub-string
+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 immediatly).
+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 given to the `tt(-X)' option of
+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.
@@ -456,30 +496,31 @@
 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($[...])'
+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')))
+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,
+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 completion was called
-on the last time will not delay the generation of matches.
+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 use
+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
@@ -490,10 +531,11 @@
 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 
+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 to return zero if they
+generating matches all follow the convention of returning zero if they
 generated completions and non-zero if no matching completions could be 
 added.
 
@@ -507,68 +549,66 @@
 mathematical environments.
 )
 item(tt(_normal))(
-This function is used to complete for normal commands, i.e. if
+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. 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.
+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 by simple setting this parameter to any value.
+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 for the completion code, the array may be given as the 
-name of an array parameter or as a literal array in the form
+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 te strings from the array where the parts separated by the
+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
+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(-J)', and `tt(-X)' options with an argument and passes 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 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 gives the `tt(-V)', `tt(-J)', and `tt(-X)' options and
+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 example completion 
-system to complete filenames. The advantage over the builtin
-completion functions is that it allows to complete partial paths. For
+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)'. 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.
+`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 arguments it
-got and, if that generated no matches, call tt(_path_files) again
+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)',
@@ -583,14 +623,14 @@
 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.
+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 given to this function are
+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))(
@@ -603,9 +643,8 @@
 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 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
@@ -615,48 +654,38 @@
 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.
+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 brackets
+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 bracket or parentheses, it should be the name of a
+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)' \)
-tt(              '*=FILE*' '_files' \)
-tt(              '*=DIR*'  '_files -/')))
+indent(
+nofill(tt(_long_options '*\*'     '(yes no)' \))
+nofill(tt(              '*=FILE*' '_files' \))
+nofill(tt(              '*=DIR*'  '_files -/'))
+)
 
-This makes `tt(yes)' and `tt(no)' be completed as the argument of
+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)'. Note that the last two
+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, though.
+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 given unchanged to `tt(compadd)'. Finally, it
-accepts the option `tt(-t)'. If this is given, completion is only done
+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()
-
-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.

-- 
Peter Stephenson <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy

PATCH: compsys.yo

[Sven Wischnowsky]

I forgot to mention some of the special contexts...

Bye
 Sven

--- od/Zsh/compsys.yo	Tue Mar 30 16:00:36 1999
+++ Doc/Zsh/compsys.yo	Wed Mar 31 13:14:13 1999
@@ -236,6 +236,20 @@
 for completing the name of a parameter expansion with braces
 (`tt(${...})')
 )
+item(tt(-first-))(
+for adding completions before any other other completion functions are
+tried (comparable 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 
+(comparable 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()
 
 The example system has a default implementation for each of these

--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de