From e2a4e843c262416b7b866203a7e636265beb4673 Mon Sep 17 00:00:00 2001 From: Michael Heerdegen Date: Mon, 27 Jun 2022 15:42:58 +0200 Subject: [PATCH] completing-read: Clarify why to avoid INITIAL-INPUT * src/minibuf.c (completing-read): Don't say INITIAL-INPUT is deprecated because it's necessary to use it in some cases. Mention M-n and M-p as well as `minibuffer-with-setup-hook'. Co-authored-by: Drew Adams --- src/minibuf.c | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/minibuf.c b/src/minibuf.c index c2e270a450..2ad74e4d38 100644 --- a/src/minibuf.c +++ b/src/minibuf.c @@ -2026,10 +2026,11 @@ DEFUN ("completing-read", Fcompleting_read, Scompleting_read, 2, 8, 0, initial input is STRING, but point is placed at _zero-indexed_ position POSITION in STRING. (*Note* that this is different from `read-from-minibuffer' and related functions, which use one-indexing - for POSITION.) This feature is deprecated--it is best to pass nil - for INITIAL-INPUT and supply the default value DEF instead. The - user can yank the default value into the minibuffer easily using - \\\\[next-history-element]. + for POSITION.) Don't use this argument to insert a default value -- + use DEF for that. You can use INITIAL-INPUT, for example, to insert + a prefix common to all completion candidates. See + `minibuffer-with-setup-hook' for a general method to prepare the + minibuffer. HIST, if non-nil, specifies a history list and optionally the initial position in the list. It can be a symbol, which is the history list @@ -2044,6 +2045,9 @@ DEFUN ("completing-read", Fcompleting_read, Scompleting_read, 2, 8, 0, of a history list. If HIST is t, history is not recorded. DEF, if non-nil, is the default value or the list of default values. + These can be yanked into the minibuffer using \ +\\\\[next-history-element] and \ +\\[previous-history-element]. If INHERIT-INPUT-METHOD is non-nil, the minibuffer inherits the current input method and the setting of `enable-multibyte-characters'. -- 2.30.2