Initial revision

1 files changed, 119 insertions, 0 deletions

diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
new file mode 100644
index 000000000..460d4a609
--- /dev/null
+++ b/Doc/Zsh/mod_complist.yo
@@ -0,0 +1,119 @@
+texinode(The complist Module)(The deltochar Module)(The compctl Module)(Zsh Modules)
+sect(The complist Module)
+cindex(completion, listing)
+The tt(complist) module offers two extensions to completion listings:
+the ability to highlight matches in such a list and a different
+style of menu-completion.
+
+subsect(Parameters)
+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))(
+for normal text (not the string displayed for a match)
+)
+item(tt(fi 0))(
+for regular files
+)
+item(tt(di 32))(
+for directories
+)
+item(tt(ln 36))(
+for symbolic links
+)
+item(tt(pi 31))(
+for named pipes (FIFOs)
+)
+item(tt(so 33))(
+for sockets
+)
+item(tt(bd 44;37))(
+for block devices
+)
+item(tt(cd 44;37))(
+for character devices
+)
+item(tt(ex 35))(
+for executable files
+)
+item(tt(mi) var(none))(
+for names not naming a file (default is the value defined for tt(fi))
+)
+item(tt(lc \e[))(
+for the left code (see below)
+)
+item(tt(rc m))(
+for the right code
+)
+item(tt(ec) var(none))(
+for the end code
+)
+enditem()
+
+Apart from these strings, the var(name) may also be an asterisk
+(`tt(*)') followed by any string. The var(value) given for such a
+string will be used for all files whose name ends with the string.
+
+When printing a match, the code prints the value of tt(lc), the value
+for the file-type or the last matching specification with a `tt(*)',
+the value of tt(rc), the string to display for the match itself, and
+then the value of tt(ec) if that is defined or the values of tt(lc),
+tt(no), and tt(rc) if tt(ec) is not defined.
+
+The default values are ISO 6429 (ANSI) compliant and can be used on
+vt100 compatible terminals such as tt(xterm)s. On monochrome terminals
+the default values will have no visual effect.
+
+Whenever one of the parameters tt(ZLS_COLORS) or tt(ZLS_COLOURS) is set 
+and the tt(complist) module is loaded or linked into the shell,
+completion lists will be colored.
+
+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 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 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 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). 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))\
+).