PATHC: config description

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

This only collects the configuration descriptions and puts it into the 
README file. And it fixes a typo in `_match'.

Bye
 Sven

--- oc/README	Tue Mar 23 11:56:58 1999
+++ Completion/README	Tue Mar 23 14:28:32 1999
@@ -14,8 +14,7 @@
 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 comment at the top of Core/_main_complete and the completer
-functions.
+see the section below.
 
 The subdirectories contain:
 
@@ -140,3 +139,112 @@
   _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 get 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.
+
+For more information about what the completers do, see the files
+containing them (_complete, _correct, _approximate, and _match in the
+Core directory).
--- oc/Core/_match	Tue Mar 23 11:56:57 1999
+++ Completion/Core/_match	Tue Mar 23 14:27:18 1999
@@ -1,9 +1,9 @@
 #autoload
 
-# This is inteded to be used as a completer function after the normal
+# This is intended to be used as a completer function after the normal
 # completer as in: `compconf completer=_complete:_match'.
-# It temporarily switches on pattern matching, allowing you to
-# try completion on patterns without having to setopt glob_complete.
+# It temporarily switches on pattern matching, allowing you to try 
+# completion on patterns without having to setopt glob_complete.
 #
 # Note, however, that this is only really useful if you don't use the
 # expand-or-complete function because otherwise the pattern will

--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx