runtime(doc): Improve 'wildmode' setting desciption

closes: #17100

Signed-off-by: Girish Palya <girishji@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index a2f5f1f0979fd2c5238fca540b77d62e2b177811..9fab3f46d8c9e31b8b1259fefc0c9a03eb97fcc9 100644 (file)
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -9638,55 +9638,65 @@ A jump table for the options with a short description can be found at |Q_op|.
                                                *'wildmode'* *'wim'*
 'wildmode' 'wim'       string  (Vim default: "full")
                        global
-       Completion mode that is used for the character specified with
-       'wildchar'.  It is a comma-separated list of up to four parts.  Each
-       part specifies what to do for each consecutive use of 'wildchar'.  The
-       first part specifies the behavior for the first use of 'wildchar',
-       The second part for the second use, etc.
-
-       Each part consists of a colon separated list consisting of the
-       following possible values:
-       ""              Complete only the first match.
-       "full"          Complete the next full match.  After the last match,
-                       the original string is used and then the first match
-                       again.  Will also start 'wildmenu' if it is enabled.
-       "longest"       Complete till longest common string.  If this doesn't
-                       result in a longer string, use the next part.
-       "list"          When more than one match, list all matches.
-       "lastused"      When completing buffer names and more than one buffer
-                       matches, sort buffers by time last used (other than
-                       the current buffer).
-       "noselect"      Do not pre-select first menu item and start 'wildmenu'
-                       if it is enabled.
-       When there is only a single match, it is fully completed in all cases
-       except when "noselect" is present.
-
-       Examples of useful colon-separated values:
-       "longest:full"  Like "longest", but also start 'wildmenu' if it is
-                       enabled.  Will not complete to the next full match.
-       "list:full"     When more than one match, list all matches and
-                       complete first match.
-       "list:longest"  When more than one match, list all matches and
-                       complete till longest common string.
-       "list:lastused" When more than one buffer matches, list all matches
-                       and sort buffers by time last used (other than the
-                       current buffer).
+       Completion mode used for the character specified with 'wildchar'.
+       This option is a comma-separated list of up to four parts,
+       corresponding to the first, second, third, and fourth presses of
+       'wildchar'.  Each part is a colon-separated list of completion
+       behaviors, which are applied simultaneously during that phase.
+
+       The possible behavior values are:
+       ""              Only complete (insert) the first match.  No further
+                       matches are cycled or listed.
+       "full"          Complete the next full match.  Cycles through all
+                       matches, returning to the original input after the
+                       last match.  If 'wildmenu' is enabled, it will be
+                       shown.
+       "longest"       Complete to the longest common substring.  If this
+                       doesn't extend the input, the next 'wildmode' part is
+                       used.
+       "list"          If multiple matches are found, list all of them.
+       "lastused"      When completing buffer names, sort them by most
+                       recently used (excluding the current buffer).  Only
+                       applies to buffer name completion.
+       "noselect"      If 'wildmenu' is enabled, show the menu but do not
+                       preselect the first item.
+       If only one match exists, it is completed fully—unless "noselect" is
+       specified.
+
+       Some useful combinations of colon-separated values:
+       "longest:full"          Start with the longest common string and show
+                               'wildmenu' (if enabled).  Does not cycle
+                               through full matches.
+       "list:full"             List all matches and complete first match.
+       "list:longest"          List all matches and complete till the longest
+                               common prefix.
+       "list:lastused"         List all matches.  When completing buffers,
+                               sort them by most recently used (excluding the
+                               current buffer).
+       "noselect:lastused"     Do not preselect the first item in 'wildmenu'
+                               if it is active.  When completing buffers,
+                               sort them by most recently used (excluding the
+                               current buffer).
 
        Examples: >
                :set wildmode=full
-<      Complete first full match, next match, etc.  (the default) >
+<      Complete full match on every press (default behavior) >
                :set wildmode=longest,full
-<      Complete longest common string, then each full match >
+<      First press: longest common substring
+       Second press: cycle through full matches >
                :set wildmode=list:full
-<      List all matches and complete each full match >
+<      First press: list all matches and complete the first one >
                :set wildmode=list,full
-<      List all matches without completing, then each full match >
+<      First press: list matches only
+       Second press: complete full matches >
                :set wildmode=longest,list
-<      Complete longest common string, then list alternatives >
+<      First press: longest common substring
+       Second press: list all matches >
                :set wildmode=noselect:full
-<      Display 'wildmenu' without completing, then each full match >
+<      Show 'wildmenu' without completing or selecting on first press
+       Cycle full matches on second press >
                :set wildmode=noselect:lastused,full
-<      Same as above, but sort buffers by time last used.
+<      Same as above, but buffer matches are sorted by last used
        More info here: |cmdline-completion|.
 
                                                *'wildoptions'* *'wop'*