PATCH: complist doc, and some small problems

[Peter Stephenson <pws@xxxxxxxxxxxxxxxxx>]

Here's some small changes to the documentation for complist, including
SELECTMIN (which should be ZSELECTMIN, but then so should LISTMAX by
today's rules, so I suppose we have to leave it as it is).

I still have some problems, which by now are rather minor.

1.  Actually, this one isn't minor, but I just discovered it trying to get
    the others to show up with zsh -f.  Any completion (!) with zsh -f
    gives a core dump at the top of printfmt() in zle_tricky.c.  It seems
    the fmt passed is invalid.  Looking back, it seems ilistmatches is
    calling printfmt with `e' which points to a null string.

2.  I finally tracked down my problems with spaces appearing after a
    menu item when selection was used.  It happens if you
    - load new completion
    - setopt menucomplete
    - use menu-select, highlight a directory
    - abort with ^G
    - hit <TAB> again
    - the key point is I'm using _oldlist, so that this sets
      compstate[old_list]=keep to use the existing list.
    - The list items which aren't directories all have a space after them.

      Also with zsh -g it seems to be beeping all the time.  This seems to
      be tied to old_list, too, presumably with LISTBEEP taking effect
      too often.  I've tried this with an old version, and it doesn't
      seem to be related to my feeping changes, nor the other bug I've
      just mentioned.

3.  Also, the documentation advertises that undo works to remove a
    completion.  If this means it's supposed to work invoking undo
    to remove a completion while menu-select is still active, it doesn't.
    It works after you've aborted, of course.

--- Doc/Zsh/mod_complist.yo.doc	Wed Jun 23 09:35:34 1999
+++ Doc/Zsh/mod_complist.yo	Thu Jun 24 10:01:28 1999
@@ -2,18 +2,18 @@
 sect(The complist Module)
 cindex(completion, listing)
 The tt(complist) module offers two extensions to completion listings:
-the possibility to highlight matches in such a list and a different
+the ability to highlight matches in such a list and a different
 style of menu-completion.
 
 subsect(Parameters)
-For both extensions one has to describe how matches are highlighted by 
-setting one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS). The
-format of the value of these parameters is the same as used by the GNU
-version of the tt(ls) command: a colon-separated list of
-specifications of the form `var(name)=var(value)'. The var(name)
-may be one of the following strings, most of which specify file-types
-for which the var(value) will be used. The strings and their default
-values are:
+For both extensions one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS)
+must be set, even if the value is empty (which uses all the default values
+given below). These describe how matches are highlighted. The format of the
+value of these parameters is the same as used by the GNU version of the
+tt(ls) command: a colon-separated list of specifications of the form
+`var(name)=var(value)'. The var(name) may be one of the following strings,
+most of which specify file-types for which the var(value) will be used. The
+strings and their default values are:
 
 startitem()
 item(tt(no 0))(
@@ -77,39 +77,43 @@
 
 subsect(Menu selection)
 The tt(complist) module also offers a different style of selecting
-matches from a list called menu-selection. It can be invoked by using
-the widget tt(menu-select) defined by the module or by setting the
-parameter tt(ZLS_SELECT). In the latter case menu-selection is used
-whenever menu-completion is started (because a widget such as
-tt(menu-complete) was used or because of tt(AUTO_MENU) being set).
+matches from a list called menu-selection. It can be invoked directly by
+the widget tt(menu-select) defined by the module.  Alternatively,
+the parameter tt(SELECTMIN) can be set to an integer giving the minimum
+number of matches which must be present before menu selection is
+automatically turned on.  This second method requires that menu completion
+be started, either directly from a widget such as tt(menu-complete), or due
+to one of the options tt(MENU_COMPLETE) or tt(AUTO_MENU) being set.  If
+tt(SELECTMIN) is set, but is 0, 1 or empty, menu selection will always be
+started during menu completion if the completion is ambiguous.
 
 After menu-selection is started, the matches will be listed. The
 matches to insert into the command line can be selected from this
 list. In the list one match is highlighted using the value for tt(ma)
 from the tt(ZLS_COLORS) or tt(ZLS_COLOURS) parameter. The default
-value for this it `tt(7)' which makes the selected match be
+value for this it `tt(7)' which forces the selected match to be
 highlighted using standout mode on a vt100 compatible terminal.
 
-Selecting matches is done by moving the mark around using the zle
-movement functions. The zle functions tt(send-break) and
-tt(accept-line) can be used to leave menu-selection, leaving the match 
-currently inserted into the line in place. The functions
-tt(accept-and-hold) and tt(accept-and-menu-complete) can be used to
-accept the match currently inserted and continue inserting matches
-after that. Matches inserted this way can be removed by invoking the
-tt(undo) function. Keys bound to one of the completion functions make
-the next (or, in case of tt(reverse-menu-complete), the previous)
-match be inserted and the tt(redisplay) and tt(clear-screen) functions 
-work as usual without leaving menu-selection. Any other zle function
-leaves menu-selection and makes that function be executed.
+Selecting matches is done by moving the mark around using the zle movement
+functions. The zle functions tt(send-break) and tt(accept-line) can be used
+to leave menu-selection, leaving the match currently inserted into the line
+in place. The functions tt(accept-and-hold) and
+tt(accept-and-menu-complete) can be used to accept the match currently
+inserted and continue inserting matches after that. Matches inserted this
+way can be removed by invoking the tt(undo) function. Keys bound to one of
+the completion functions will cycle to the next (or, in case of
+tt(reverse-menu-complete), the previous) match, and the tt(redisplay) and
+tt(clear-screen) functions work as usual without leaving
+menu-selection. Any other zle function leaves menu-selection and executes
+that function.
 
 During this selection the widget uses the keymap tt(menuselect). Any
 key that is not defined in this keymap or that is bound to
 tt(undefined-key) is looked up in the keymap currently selected. This
 is used to ensure that the most important keys used during selection
-have sensible default (namely the cursor keys, return, and TAB). But
-the tt(menuselect) is user-visible and other keys can be defined in it 
-using the tt(bindkey) builtin command (see
+have sensible default (namely the cursor keys, return, and TAB). However,
+keys in the the tt(menuselect) keymap can be modified directly using the
+tt(bindkey) builtin command (see
 ifzman(zmanref(zshmodules))\
 ifnzman(noderef(The zle Module))\
 ).

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