zsh-3.1.5-pws-15dot-zsh-3.1.5-pws-15-last-snapshot-

1 files changed, 3 insertions, 356 deletions

diff --git a/Completion/README b/Completion/README
index bf677066a..dbfb50534 100644
--- a/Completion/README
+++ b/Completion/README
@@ -1,356 +1,3 @@
-The subdirectories contain code for the new function-based completion
-system.  Broadly speaking, this uses shell functions defined for each
-command to determine how the arguments of a command should be completed.
-
-You should copy all the files you need or want to a directory of your own,
-which should be included in your autoload path as defined by $fpath.  Then
-in your .zshrc you should source the file which appears here in
-Core/compinit.  It is recommnded that you use the -d option, which outputs
-a file containing the necessary variables, bindkeys etc., making later
-loading much faster.  For example,
-  [[ -f ~/completion/compinit ]] && . ~/completion/compinit -d
-The name of the file to use may be given as an extra argument.
-
-This will rebind any keys which do completion to use the new system.
-For more detailed instructions, including how to add new completions, see
-the top of Core/compinit. For information about how to configure the code,
-see the section below.
-
-The subdirectories contain:
-
-Core:
-  The basic functions and files to be sourced.  You will certainly need
-  these, and will most likely not want to alter them --- if you do, it
-  would probably help to give your version a different name.  The files
-  are:
-  compinit
-    As already described, this is not a function, but is sourced once
-    (with the `source' or `.' commands) to set up the completion system.
-  compdump
-    This dumps the completions status for faster initialisation.  The
-    easiest way of doing this is to use the -d option to compinit rather
-    than calling compdump directly.
-  _approximate
-    A completer function that does correcting completion.
-  _compalso
-    Utility for calling a function to add additional completions to an
-    already existing set.
-  _complete
-    The main completer function that generates the completions by calling
-    the context and command specific functions.
-  _correct
-    A completer function that attempts correction on the word from the
-    line. Unlike _approximate this does only correction, not completion.
-  _expand
-    A completer function for expanding the word on the line.
-  _files
-    A frontend to _path_files which will default to any old file if the
-    specified file was not found.
-  _list
-    A completer function that allows showing only a list on the first
-    TAB and insert completions on the second one.
-  _match
-    A completer function that temporarily swicthes on pattern matching
-    when comparing the string from the line with possible completions.
-  _main_complete
-    The main entry point called by the key bindings which compinit sets
-    up (the main `completion widget' in zsh jargon). This mainly calls
-    completer functions like _complete, either those given as arguments
-    or (if it is called without arguments) those from the completer
-    configuration key (see below).
-  _multi_parts
-    Utility for completion parts of words given a separator character and 
-    a list of words.
-  _normal
-    The function called by _main_complete to handle the most common
-    cases, such as completing a command name or its arguments.  This
-    function dispatches to the various other functions for individual
-    commands.  (Actually, the system is fairly context-sensitive, so
-    it is wider than just command+argument.)
-  _options
-    Utility to complete option names, allowing the optional `no' prefix
-    and correctly handling upper case letters and underscores.
-  _parameters
-    This can be used to complete parameter names if you need some of the
-    options of compadd not supported by compgen.
-  _path_files
-    The function usually called to complete filenames and directories.  It
-    replaces the standard -f, -g and -/ options for the basic completion
-    commands:  it can do various extra tricks, such as expanding a whole
-    path at once, e.g. F/C/C/_p<TAB> -> Functions/Completion/Core/_path_files
-  _sep_parts
-    Utility used for completing words with multiple separate parts, such as
-    `<user>@<host>'
-  _set_options
-  _unset_options
-    These can be used to complete only set or unset options. For this to
-    work, you'll have to un-comment a few lines in _main_complete.
-Base:
-  You will almost certainly want these files, too, which handle standard
-  tasks like completing files.  However, you may want to edit them for
-  your own particular setup.  Files are:
-  _command_names
-    This handles completion of the command word, i.e. the first thing
-    on the command line.  You may want to alter this, for example,
-    to complete parameters to assign to.
-  _condition
-    This handles completing inside [[ ... ]] .
-  _default
-    This handles completion of command arguments when no special function
-    exists.  Usually this means completing files, but you can modify this
-    as you wish.
-  _long_options
-    This handles options beginning with `--', as in many GNU commands.
-    The command must accept the --help option to list the possible options.
-    __long_options can also take arguments to help it decide what to
-    complete as the value of the option.  Note that this is potentially
-    dangerous because the command from the line will be called with the
-    --help option and hence could cause damage if used with a command
-    that does not support it.
-  _match_pattern
-  _match_test
-    These are used by Base/_path_files (and hence also Base/_files)
-    and Base/_sep_parts for file completion with control over
-    matching (whether to complete case-insensitively, or to allow
-    insertion before `.', etc.)  See _match_test for instructions.
-    Note _path_files expects these files to be present.
-  _precommand
-    Allows completion when the first word on the line has to be ignored,
-    for example `noglob ...' should ignore the noglob and just complete
-    as if it wasn't there.  Add other such commands to the top line.
-  _redirect
-    Completes after `<' or `>': this version calls _files.
-  _subscript
-    For completion in subscripts of parameters, e.g $foo[...].
-  _vars
-    Completion for commands which need variables (so this could also be in
-    the Builtins directory), but also in math environments such as ((...)).
-  _tilde
-    Completion after `~', defaults to user names and named directories.
-  _equal
-    Completion after `=', normally command and alias names are used.
-  _parameter
-  _brace_parameter
-    For completion inside parameter expansions ($... and ${...).
-Builtins:
-  Define completions for various shell builtins.  The top line of each file
-  says which builtins they apply to; in many cases you can guess from the
-  name.  Note in particular that _zftp defines completions for all commands
-  beginning `zf', not just for the module command zftp.  This is only
-  really useful if you use zftp with the zf* function suite (zfopen, zfget,
-  ...).
-User:
-  This contains a pot pourri of completions for various external commands.
-  Not all will work unmodified on your system.
-Commands:
-  These functions define separate completion commands which do not use
-  the usual context information, and hence have to be bound separately
-  to keys.  As they appear, they have bindings which you can change or
-  delete by altering the top line of the file.  To bind a function
-  (strictly speaking, the corresponding completion widget) yourself
-  after completion is loaded, use `bindkey '<key-string>' <_function_name>'.
-  The files are:
-  _correct_filename, bound to \C-xc
-    Correct the word under the cursor as a filename.  This is significantly
-    more powerful than the standard \e$ (spell-word) binding.
-  _most_recent_file, bound to \C-xm
-    Insert the name of the most recent file matching the pattern
-    so far on the command line.
-
-
-Configuration
-
-You can configure several aspects of the completion functions and the
-overall completion behavior using the compconf shell function defined
-in compinit. This function gets any number of arguments of the form
-`key=value', where `key' is one of the keys described below and `value'
-is any string. Most configuration keys are defined by the completer
-functions.
-
-The completion widget function _main_complete currently understands
-one configuration key:
-
-  completer
-    This should be set to the names of the functions to generate the
-    matches separated by colons. E.g. with
-
-      compconf completer=_complete:_correct:_approximate
-
-    the code will first try normal completion. If that doesn't yield
-    any matches, correction is tried and if that doesn't yield
-    anything either, correcting completion is attempted.
-
-The keys understood by the _approximate completer function are:
-
-  approximate_accept
-    This should be set to a number, specifying the maximum number
-    of errors that should be accepted. If the string also contains
-    a `n' or `N', the code will use the numeric argument as the
-    maximum number of errors if a numeric argument was given. If no
-    numeric argument was given, the number from the value of this
-    key will be used. E.g. with `compconf approximate_accept=2n' two
-    errors will be accepted, but if the user gives another number
-    with the numeric argument, this will be prefered. Also, with
-    `compconf approximate_accept=0n', normally no correction will be
-    tried, but if a numeric argument is given, automatic correction
-    will be used. On the other hand, if the string contains an `!'
-    and a `n' or `N', correction is not attempted if a numeric
-    argument is given. Once the number of errors to accept is
-    determined, the code will repeatedly try to generate matches by
-    allowing one error, two errors, and so on. Independent of the
-    number of errors the user wants to accept, the code will allow
-    only fewer errors than there are characters in the string from
-    the line.
-
-  approximate_original
-    This value is used to determine if the original string should
-    be included in the list (and thus be presented to the user when
-    cycling through the corrections). If it is set to any non-empty
-    value, the original string will be offered. If it contains the
-    sub-string `last', the original string will appear as the last
-    string when cycling through the corrections, otherwise it will
-    appear as the first one (so that the command line does not
-    change immediately). Also, if the value contains the sub-string
-    `always', the original string will always be included, whereas
-    normally it is included only if more than one possible
-    correction was generated.
-
-  approximate_prompt
-    This can be set to a string that should be printed before the
-    list of corrected strings when cycling through them. This string
-    may contain the control sequences `%n', `%B', etc. known from
-    the `-X' option of `compctl'. Also, the sequence `%e' will be
-    replaced by the number of errors accepted to generate the
-    corrected strings.
-
-  approximate_insert
-    If this is set to a string starting with `unambig', the code
-    will try to insert a usable unambiguous string in the command
-    line instead of always cycling through the corrected strings.
-    If such a unambiguous string could be found, the original
-    string is not used, independent of the setting of
-    `approximate_original'. If no sensible string could be found,
-    one can cycle through the corrected strings as usual.
-
-If any of these keys is not set, but the the same key with the
-prefix `correct' instead of `approximate' is set, that value will
-be used. The forms beginning with `correct' are also used by the
-_correct completer function, and this function uses only them, not
-the ones starting with `approximate'. This allows one to give
-different value to be used with correction and correcting
-completion. For example, with:
-
-  compconf completer=_complete:_correct:_approximate
-  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
-completion will be tried, with the first one accepting two errors 
-and the second one accepting three errors.
-
-The _match completer function, which allows to give patterns on the
-command line and complete all strings matching it from the set of
-possible completions, understands the following key:
-
-  match_original
-    If this is set to a `only', pattern matching will only be tried
-    with the string from the line. If it is set to any other non-empty
-    string, the original pattern will be tried first and if that yields
-    no completions, matching will be tried again with a `*' inserted
-    at the cursor position. If this key is not set or set to an empty
-    string, matching will only be attempted with the `*' inserted.
-
-The _expand completer allows one to do expansion on the word from the
-line. Note that you may either want to use the configuration keys or
-not use this completer at all if you also use the _match completer
-because the _expand completer will otherwise expand patterns before
-they are seen by the _match completer.
-Configuration keys supported are:
-
-  expand_substitute
-    If this is unset or set to the empty string, the code will first
-    try to expand all substitutions in the string (such as $(...) and
-    ${...}). If this is set to an non-empty string it should be 
-    an expression usable inside a $[...] arithmetical expression.
-    In this case, expansion of substitutions will be done if the
-    expression evaluates to `1'. For example, with
-
-      compconf expand_substitute='NUMERIC != 1'
-
-    substitution will be performed only if given an explicit numeric
-    argument other than `1', as by typing ESC 2 TAB.
-
-  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.
-
-  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 `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 `last', the string with all expansion will
-    be offered first, whereas normally it is offered as the last string
-    to insert. Finally, if the value contains the sub-string `sort',
-    the expansions will be sorted alphabetically, normally they are
-    kept in the order the expansion produced them in.
-    
-  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
-    `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).
-
-  expand_prompt
-    This may be set to a string that should be displayed before the
-    possible expansions. This is given to the -X option and thus may
-    contain the control sequences `%n', `%B', etc. Also, the sequence
-    `%o' in this string will be replaced by the original string.
-
-The _list completer allows one to delay the insertion of matches until
-completion is attempted a second time without the word on the line 
-being changed. On the first attempt, only the list of matches will
-be shown. Configuration keys understood are:
-
-  list_condition
-    If this key is unset or set to the empty string, this completer
-    will delay the insertion of matches unconditionally. However,
-    if this value is set, it should be set to an expression usable
-    inside a $[...] arithmetical expression. In this case, delaying
-    will be done if the expression evaluates to `1'.
-    For example, with
-
-      compconf list_condition='NUMERIC != 1'
-
-    delaying will be done only if given an explicit numeric argument
-    other than `1'.
-
-  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 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.
-
-For more information about what the completers do, see the files
-containing them (_complete, _correct, _approximate, _match, and
-_expand in the Core directory).
-
-The _path_files function used to complete filenames has one
-configuration key:
-
-  path_expand
-    If this is set to a non-empty string, the partially typed path
-    from the line will be expanded as far as possible even if trailing
-    pathname components can not be completed.
+The subdirectories contain code for a shell-based system of command-line
+completion.  This is considerably more powerful than the old `compctl'
+method.  For details, see the compsys(1) manual page (`man zshcompsys').