completion list scrolling cleanup; *STATUS renamed to *PROMPT, styles for new used parameters, use local keymap when waiting at list-prompt (10801)

3 files changed, 65 insertions, 15 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 5e698a9ae..84d301e5a 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -1267,6 +1267,19 @@ for a tag, the matches added for it will be listed as if the
 tt(LIST_PACKED) option were set for them. If it is set to `false',
 they are listed normally.
 )
+kindex(list-prompt, completion style)
+item(tt(list-prompt))(
+If this style is set to a non-empty value for the tt(default) tag,
+completion lists that don't fit on the screen can be scrolled (see
+ifzman(the description of the tt(zsh/complist) module in zmanref(zshmodules))\
+ifnzman(noderef(The zsh/complist Module))\
+). The value will be displayed after every screenful, prompting for a
+key and may contain the escape `tt(%l)' which will be replaced by the
+number of the last line displayed and the total number of lines. As
+usual, the `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)', `tt(%u)',
+and `tt(%{)...tt(%})' escapes for the terminal display modes are
+understood, too.
+)
 kindex(list-rows-first, completion style)
 item(tt(list-rows-first))(
 This style is tested like the tt(list-packed) style and determines if
@@ -1559,6 +1572,28 @@ The tt(_history_complete_word) bindable command uses this to decide if
 all duplicate matches should be removed, rather than just consecutive
 duplicates.
 )
+kindex(select-prompt, completion style)
+item(tt(select-prompt))(
+If this is set to a non-empty string for the tt(default) tag, its
+value will be displayed during menu-selection (see the tt(menu) style
+above) when the completion list does not fit on the screen as a
+whole. The same escapes as for the tt(list-prompt) style are
+understood, plus `tt(%m)' which is replaced by the number of the
+currently selected match and the total number of matches and `tt(%p)'
+which is replaced by `tt(Top)' when the mark is on the first line,
+`tt(Bottom)' when it is on the last line and the relative position of
+the mark in the list given as a percentage.
+)
+kindex(select-scroll, completion style)
+item(tt(select-scroll))(
+This style is tested for the tt(default) tag and determines how a
+completion list is scrolled during a menu-selection (see the tt(menu)
+style above) when the completion list does not fit on the screen as a
+whole. Its value should be `tt(0)' (zero) to scroll by
+half-screenfuls, a positive integer to scroll by that many lines and a
+negative number to scroll by the number of lines of the screen minus
+that number (or plus the number, since it is negative).
+)
 kindex(single-ignored, completion style)
 item(tt(single-ignored))(
 This is used by the tt(_ignored) completer. It specifies what
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 340dc0752..f2280df77 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -247,7 +247,7 @@ there.
 vindex(list_max, compstate)
 item(tt(list_max))(
 Initially this is set to the value of the tt(LISTMAX) parameter.
-It may be set to any other numeric value; when the widget exits this value
+It may be set to any other value; when the widget exits this value
 will be used in the same way as the value of tt(LISTMAX).
 )
 vindex(list_lines, compstate)
diff --git a/Doc/Zsh/mod_complist.yo b/Doc/Zsh/mod_complist.yo
index 920df5fc1..e5484c941 100644
--- a/Doc/Zsh/mod_complist.yo
+++ b/Doc/Zsh/mod_complist.yo
@@ -133,26 +133,30 @@ To be able to scroll through a completion list, the tt(LISTMAX)
 parameter has to be set to the string `tt(scroll)'. If it has this
 value, the completion code will not ask if the list should be
 shown. Instead it immediately starts displaying the list, stopping
-after the first screenful, showing a simple prompt at the bottom,
-waiting for a keypress. The following keys have a special meaning:
+after the first screenful, showing a prompt at the bottom,
+waiting for a keypress after temporarily switching to the
+tt(listscroll) keymap. Some of the zle functions have special meaning:
 
 startitem()
-item(tt(Space), tt(Tab))(
-scroll forward one screenful
+item(tt(send-break))(
+stops listing discarding the key pressed
 )
-item(tt(Return), tt(Newline))(
-scroll forward one line
+xitem(tt(accept-line), tt(down-history), tt(down-line-or-history))
+item(tt(down-line-or-search), tt(vi-down-line-or-history))(
+scrolls forward one line
 )
-item(tt(q))(
-stops listing and redisplays the command line without inserting the
-`tt(q)'
+item(tt(complete-word), tt(menu-complete), tt(expand-or-complete))(
+item(tt(expand-or-complete-prefix), tt(menu-complete-or-expand))(
+scrolls forward one screenful
 )
 enditem()
 
 Every other character stops listing and immediately processes the key
-as usual.
+as usual. Any key that is not bound in the tt(listscroll) keymap or
+that is bound to tt(undefined-key) is looked up in the keymap
+currently selected.
 
-If the parameter tt(LISTSTATUS) is set, its value will be used as the
+If the parameter tt(LISTPROMPT) is set, its value will be used as the
 prompt.  The value may contain escapes of the form `tt(%x)'. It
 supports the escapes `tt(%B)', `tt(%b)', `tt(%S)', `tt(%s)', `tt(%U)',
 `tt(%u)' and `tt(%{...%})' known from the shell prompts and the
@@ -160,6 +164,11 @@ additional sequence `tt(%l)' which is replaced by the number of the
 last line shown and the total number of lines in the form
 `var(number)tt(/)var(total)'.
 
+As for the tt(ZLS_COLORS) and tt(ZLS_COLOURS) parameters,
+tt(LISTPROMPT) should not be set directly when using the shell
+function based completion system. Instead, the tt(list-prompt) style
+should be used.
+
 subsect(Menu selection)
 cindex(completion, selecting by cursor)
 vindex(SELECTMIN)
@@ -197,9 +206,9 @@ neither tt(ZLS_COLORS) nor tt(ZLS_COLOURS) is set, the same terminal
 control sequence as for the `tt(%S)' escape in prompts is used.
 
 If there are more matches than fit on the screen and the parameter
-tt(SELECTSTATUS) is set, its value will be shown below the
+tt(SELECTPROMPT) is set, its value will be shown below the
 matches. Next to the escape sequences understood for the
-tt(LISTSTATUS) parameter, a `tt(%m)' will be replaced by a string
+tt(LISTPROMPT) parameter, a `tt(%m)' will be replaced by a string
 containing the number of the match the mark is on and the total number 
 of matches in the form `var(number)tt(/)var(total)' and the sequence
 `tt(%p)' will be replaced with `tt(Top)', `tt(Bottom)' or the position
@@ -210,9 +219,15 @@ The tt(SELECTSCROLL) parameter can be used to specify how the list is
 scrolled. If the parameter is unset, this is done line by line, if it
 is set to `tt(0)' (zero), the list will scrolled half the number of
 lines of the screen. If the value is positive, it gives the number of
-lines to scroll and if it is negative, the list will be scrolled one
+lines to scroll and if it is negative, the list will be scrolled
 the number of lines of the screen minus the (absolute) value.
 
+As for the tt(ZLS_COLORS), tt(ZLS_COLOURS) and tt(LISTPROMPT)
+parameters, neither tt(SELECTPROMPT) nor tt(SELECTSCROLL) should be
+set directly when using the shell function based completion
+system. Instead, the tt(select-prompt) and tt(select-scroll) styles
+should be used.
+
 The completion code sometimes decides not to show all of the matches
 in the list. These hidden matches are either matches for which the
 completion function which added them explicitly requested that they