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 a2f5f1f..9fab3f4 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -9638,55 +9638,65 @@
*'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.
+ 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.
- 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.
+ 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.
- 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).
+ 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'*