PATCH: compsys.yo

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>]

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@xxxxxxxxxxxxxxxxx>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy