Doc of deprecated INITIAL-INPUT arg of completing-read

[Michael Heerdegen]

Hello,

there was a long discussion in emacs-help about the INITIAL-INPUT
argument of `completing-read'.  Among other things people complained
about the argument being deprecated.

I agree that it's not good to use it in nearly all cases, but there ARE
a few cases where it hardly can be avoided - we have over 30 uses in
Emacs itself.  So I want to suggest to change the docstring to warn
strongly about the usage of that argument, but stop saying it would be
deprecated.

This is to make the current state of the code more consistent - I don't
plan to work on changes that had been suggested in that discussion.

So would this patch be ok to install for now?

From c6c2fa8b09be579271d274b38fc17a788132076c 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 few special cases.
---
 src/minibuf.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/minibuf.c b/src/minibuf.c
index 85d6ec4434..c0182cb704 100644
--- a/src/minibuf.c
+++ b/src/minibuf.c
@@ -2025,9 +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
+  for POSITION.)  Using this argument is strongly discouraged--it is
+  normally best to pass nil for INITIAL-INPUT and supply the default
+  value DEF except in few special cases like inserting a prefix common
+  to all completions or an initial part of a file name.  The user can
+  yank the default value into the minibuffer easily using
   \\<minibuffer-local-map>\\[next-history-element].

 HIST, if non-nil, specifies a history list and optionally the initial
--
2.30.2

Or should we rather - as Stefan suggested - change every usage of the
argument to use a kind of setup function (which would at the moment mean
use `minibuffer-with-setup-hook' unless someone implements a SETUP-FUN
argument for that function, but I won't do that as I don't speak C)?

TIA,

Michael.