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

[Michael Heerdegen]

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

> All that's needed is to make clear that INIT
> isn't intended as a _substitute_ for a default
> value - and vice versa.  That's really the point
> (IMO).  The use cases of INIT are different from
> those of DEF.  That's what should be made clear.
> Then leave it up to coders to use each as they
> see fit.

Mostly agreed.  But as I said, I only intend to describe the current
coding recommendations better, and these don't regard INITIAL-INPUT and
DEF as equivalent alternatives.

As a compromise, here is a reworded version:

>From cb7b80385f74e11d2061e5c5ca31df58711f7665 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 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/minibuf.c b/src/minibuf.c
index 85d6ec4434..9808875752 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--pass
+  nil for INITIAL-INPUT and supply the default value DEF except in
+  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
   position in the list.  It can be a symbol, which is the history list
-- 
2.30.2

For wishes, discussions and feature requests maybe use another
(sub-)thread or bug report.


Thanks,

Michael.