runtime(doc): Improve doc for cmdline-autocompletion

- Address vim/vim#18219 (comment)
- Make the cmdline-autocompletion help more user friendly

closes: #18245

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

Author: girishji

runtime/doc/builtin.txt

@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2025 Sep 06
+*builtin.txt*	For Vim version 9.1.  Last change: 2025 Sep 08
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -12407,31 +12407,22 @@ wildmenumode()					*wildmenumode()*
 wildtrigger()						*wildtrigger()*
 		Start wildcard expansion in the command-line, using the
 		behavior defined by the 'wildmode' and 'wildoptions' settings.
-		See |cmdline-completion|.
 
 		This function also enables completion in search patterns such
 		as |/|, |?|, |:s|, |:g|, |:v| and |:vimgrep|.
 
 		Unlike pressing 'wildchar' manually, this function does not
 		produce a beep when no matches are found and generally
 		operates more quietly.  This makes it suitable for triggering
-		completion automatically, such as from an |:autocmd|.
+		completion automatically.
+
+		Note: After navigating command-line history, the first call to
+		wildtrigger() is a no-op; a second call is needed to start
+		expansion.  This is to support history navigation in
+		command-line autocompletion.
+
+		See |cmdline-autocompletion|.
 
-						*cmdline-autocompletion*
-		Example: To make the completion menu pop up automatically
-		while typing on the command line: >
-			autocmd CmdlineChanged [:/\?] call wildtrigger()
-			set wildmode=noselect:lastused,full wildoptions=pum
-<
-		To retain normal history navigation with the up/down keys: >
-			cnoremap <expr> <Up>   wildmenumode() ? "\<C-E>\<Up>"   : "\<Up>"
-			cnoremap <expr> <Down> wildmenumode() ? "\<C-E>\<Down>" : "\<Down>"
-<
-		To apply an option only during a search, for example to set
-		'pumheight': >
-			autocmd CmdlineEnter [/\?] set pumheight=8
-			autocmd CmdlineLeave [/\?] set pumheight&
-<
 		Return value is always 0.
 
 		Return type: |Number|

runtime/doc/cmdline.txt

@@ -1,4 +1,4 @@
-*cmdline.txt*   For Vim version 9.1.  Last change: 2025 Aug 08
+*cmdline.txt*   For Vim version 9.1.  Last change: 2025 Sep 08
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -20,6 +20,7 @@ Basic command line editing is explained in chapter 20 of the user manual
 5. Ex command-line flags	|ex-flags|
 6. Ex special characters	|cmdline-special|
 7. Command-line window		|cmdline-window|
+8. Command-line autocompletion	|cmdline-autocompletion|
 
 ==============================================================================
 1. Command-line editing					*cmdline-editing*
@@ -406,6 +407,9 @@ word before the cursor.  This is available for:
 The number of help item matches is limited (currently to 300) to avoid a long
 delay when there are very many matches.
 
+For automatic completion as you type (without pressing a key like <Tab>),
+see |cmdline-autocompletion|.
+
 These are the commands that can be used:
 
 							*c_CTRL-D*
@@ -479,8 +483,6 @@ When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually
 ending up back to what was typed.  If the first match is not what you wanted,
 you can use <S-Tab> or CTRL-P to go straight back to what you typed.
 
-See also |wildtrigger()|.
-
 The 'wildmenu' option can be set to show the matches just above the command
 line.
 
@@ -1340,4 +1342,83 @@ The character used for the pattern indicates the type of command-line:
 	@	string for |input()|
 	-	text for |:insert| or |:append|
 
+==============================================================================
+8. Command-line autocompletion			 *cmdline-autocompletion*
+
+Autocompletion makes the command-line more efficient and easier to navigate by
+automatically showing a popup menu of suggestions as you type, whether
+searching (/ or ?) or entering commands (:).
+
+A basic setup is: >
+	autocmd CmdlineChanged [:/\?] call wildtrigger()
+	set wildmode=noselect:lastused,full
+	set wildoptions=pum
+
+With this configuration, suggestions appear immediately, and you can
+move through them with <Tab> or the arrow keys.
+
+To retain normal command-line history navigation with <Up>/<Down>: >
+	cnoremap <expr> <Up>   wildmenumode() ? "\<C-E>\<Up>"   : "\<Up>"
+	cnoremap <expr> <Down> wildmenumode() ? "\<C-E>\<Down>" : "\<Down>"
+
+Options can also be applied only for specific command-lines.  For
+example, to use a shorter popup menu height only during search: >
+	autocmd CmdlineEnter [/\?] set pumheight=8
+	autocmd CmdlineLeave [/\?] set pumheight&
+
+EXTRAS					*fuzzy-file-picker* *live-grep*
+
+Command-line autocompletion can also be extended for advanced uses.
+For example, you can turn the native |:find| command into a fuzzy, interactive
+file picker: >
+
+	set findfunc=Find
+	func Find(arg, _)
+	  if get(s:, 'filescache', []) == []
+	    let s:filescache = systemlist(
+		\ 'find . -path "*/.git" -prune -o -type f -print')
+	  endif
+	  return a:arg == '' ? s:filescache : matchfuzzy(s:filescache, a:arg)
+	endfunc
+	autocmd CmdlineEnter : let s:filescache = []
+
+The `:Grep` command searches for lines matching a pattern and updates the
+results dynamically as you type (triggered after two characters; note: needs
+the `CmdlineLeavePre` autocmd from the next section): >
+
+	command! -nargs=+ -complete=customlist,<SID>Grep
+		\ Grep call <SID>VisitFile()
+
+	func s:Grep(arglead, cmdline, cursorpos)
+	  let cmd = $'grep -REIHns "{a:arglead}" --exclude-dir=.git
+		\ --exclude=".*"'
+	  return len(a:arglead) > 1 ? systemlist(cmd) : []
+	endfunc
+
+	func s:VisitFile()
+	  let item = getqflist(#{lines: [s:selected]}).items[0]
+	  let pos  = '[0,\ item.lnum,\ item.col,\ 0]'
+	  exe $':b +call\ setpos(".",\ {pos}) {item.bufnr}'
+	  call setbufvar(item.bufnr, '&buflisted', 1)
+	endfunc
+
+Automatically select the first item in the completion list when leaving the
+command-line, and for `:Grep`, add the typed pattern to the command-line
+history: >
+
+	autocmd CmdlineLeavePre :
+	      \ if get(cmdcomplete_info(), 'matches', []) != [] |
+	      \   let s:info = cmdcomplete_info() |
+	      \   if getcmdline() =~ '^\s*fin\%[d]\s' && s:info.selected == -1 |
+	      \     call setcmdline($'find {s:info.matches[0]}') |
+	      \   endif |
+	      \   if getcmdline() =~ '^\s*Grep\s' |
+	      \     let s:selected = s:info.selected != -1
+	      \         ? s:info.matches[s:info.selected] : s:info.matches[0] |
+	      \     call setcmdline(s:info.cmdline_orig) |
+	      \   endif |
+	      \ endif
+
+For autocompletion in insert mode, see |ins-autocompletion|.
+
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/tags

@@ -6673,7 +6673,7 @@ cmdarg-variable	eval.txt	/*cmdarg-variable*
 cmdbang-variable	eval.txt	/*cmdbang-variable*
 cmdcomplete_info()	builtin.txt	/*cmdcomplete_info()*
 cmdline-arguments	vi_diff.txt	/*cmdline-arguments*
-cmdline-autocompletion	builtin.txt	/*cmdline-autocompletion*
+cmdline-autocompletion	cmdline.txt	/*cmdline-autocompletion*
 cmdline-changed	version5.txt	/*cmdline-changed*
 cmdline-completion	cmdline.txt	/*cmdline-completion*
 cmdline-editing	cmdline.txt	/*cmdline-editing*
@@ -7680,6 +7680,7 @@ function-range-example	userfunc.txt	/*function-range-example*
 function-search-undo	userfunc.txt	/*function-search-undo*
 function_key	intro.txt	/*function_key*
 functions	eval.txt	/*functions*
+fuzzy-file-picker	cmdline.txt	/*fuzzy-file-picker*
 fuzzy-matching	pattern.txt	/*fuzzy-matching*
 fvwm.vim	syntax.txt	/*fvwm.vim*
 fvwm2rc	syntax.txt	/*fvwm2rc*
@@ -8829,6 +8830,7 @@ listener_remove()	builtin.txt	/*listener_remove()*
 lite.vim	syntax.txt	/*lite.vim*
 literal-Dict	eval.txt	/*literal-Dict*
 literal-string	eval.txt	/*literal-string*
+live-grep	cmdline.txt	/*live-grep*
 lnum-variable	eval.txt	/*lnum-variable*
 load-plugins	starting.txt	/*load-plugins*
 load-vim-script	repeat.txt	/*load-vim-script*