Re: [External] : Doc of deprecated INITIAL-INPUT arg of completing-read

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> Suggestion:
>
>   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.

Ok, thanks - I went with your version.

> 5. The doc already says that users can yank DEF with `M-n'.
>    (Or if it doesn't then that should be said where DEF
>    is described, not where INIT is described.

It didn't, so I added that, along with a hint mentioning
`minibuffer-with-setup-hook'.

Updated patch:

>From 60a2579134d33975e6739651a06e79f0cf944533 Mon Sep 17 00:00:00 2001
From: Michael Heerdegen <michael_heerdegen@web.de>
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 <drew.adams@oracle.com>
---
 src/minibuf.c | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/minibuf.c b/src/minibuf.c
index 85d6ec4434..9b84bc49da 100644
--- a/src/minibuf.c
+++ b/src/minibuf.c
@@ -2025,10 +2025,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
-  \\<minibuffer-local-map>\\[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
@@ -2043,6 +2044,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 \
+\\<minibuffer-local-map>\\[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


Thanks,

Michael.