18859: Allow the sort style to override sorting by setting explicitly to false.

1 files changed, 16 insertions, 6 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index e48a057f7..6b77fb8f8 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -2162,12 +2162,22 @@ is started, making it easy to select either of them.
 )
 kindex(sort, completion style)
 item(tt(sort))(
-If set to `true', completing words from the command
-history sorts the words alphabetically instead of
-keeping them in the order in which they appear in the history (from
-youngest to oldest).
-
-This is also used by the tt(_expand) completer. If it is set to
+Many completion widgets call tt(_description) at some point which
+decides whether the matches are added sorted or unsorted (often
+indirectly via tt(_wanted) or tt(_requested)).  This style can be set
+explicitly to one of the usual true or false values as an override.
+If it is not set for the context, the standard behaviour of the
+calling widget is used.
+
+The style is tested first against the full context including the tag, and
+if that fails to produce a value against the context without the tag.
+
+If the calling widget explicitly requests unsorted matches, this is usually
+honoured.  However, the default (unsorted) behaviour of completion
+for the command history may be overridden by setting the style to
+tt(true).
+
+In the tt(_expand) completer, if it is set to
 `true', the expansions generated will always be sorted.  If it is set
 to `tt(menu)', then the expansions are only sorted when they are offered 
 as single strings but not in the string containing all possible