11542: Doc/Zsh/compsys.yo: more wording `improvements'

1 files changed, 217 insertions, 200 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 518974014..11a859ebb 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -2524,17 +2524,17 @@ those generated by tt(_all_labels).
 )
 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 @@ different name for the argument context field.
 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 @@ Also, during the evaluation of the var(action), the context name in
 the tt(curcontext) parameter will be changed by appending the same
 string that is stored in the tt(context) parameter.
 
-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 @@ exclusive with all other specifications in the same set. This is
 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 @@ be completed. The last description says that all other arguments are
 )
 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 @@ the strings from the style value are generated as possible matches.
 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 @@ If the same name is used for more than one field, in both the
 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 @@ containing an expanded description.
 )
 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 @@ return ret
 )
 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 @@ item(tt(-/))(
 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 @@ tt(ambiguous) and tt(special-dirs) and tt(file-sort).
 )
 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 @@ enditem()
 )
 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 @@ done)
 )
 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 @@ 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
+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 @@ so that one normally doesn't have to call it explicitly.
 )
 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 @@ example(_sort_tags() {
 })
 
 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 @@ return value means that the calling function, tt(_tags), will not use
 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 @@ example(_sort_tags() {
   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 @@ findex(_tags)
 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 @@ tt(curcontext) parameter (which would otherwise have the same effect).
 )
 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.
+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 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:
+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 @@ different name for the argument context field.
 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 @@ listing the values.
 
 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 @@ example(_values -s , 'description' \
         '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 @@ these files.
 )
 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