bug#56380: 29.0.50; completing-read: INITIAL-INPUT arg

bug#56380: 29.0.50; completing-read: INITIAL-INPUT arg

[Michael Heerdegen]

[-- Attachment #1: Type: text/plain, Size: 354 bytes --]


Hello,

The docstring of `completing-read' says the argument INITIAL-INPUT is
deprecated - yet there are over 30 nontrivial uses in Emacs' own Elisp
sources.  So, although we currently don't want that this argument is
used just to insert a default input, it's sometimes not possible to
avoid using it.

Here is an attempt to improve the documentation:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-completing-read-Clarify-why-to-avoid-INITIAL-INPUT.patch --]
[-- Type: text/x-diff, Size: 2218 bytes --]

From e2a4e843c262416b7b866203a7e636265beb4673 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 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
-  \\<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
@@ -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 \
+\\<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


[-- Attachment #3: Type: text/plain, Size: 2096 bytes --]


This patch is the result of a discussion in emacs dev:

  https://yhetil.org/emacs-devel/87v8smt9lp.fsf@web.de/

Further things mentioned in that discussion:

1.  Likewise we want to improve the docstrings of `read-string' and
`read-from-minibuffer'.  And as well (Arash Esbati):

  Emacs Lisp reference the text/descriptions in

   @node Text from Minibuffer
   @section Reading Text Strings with the Minibuffer

   @node Initial Input
   @section Initial Input

   @node Minibuffer Completion
   @subsection Completion and the Minibuffer

2.  Add a minor mode that automatically inserts a DEF into the
minibuffer, and add a defcustom to allow users to enable that mode in
their configuration.  Some people simply prefer that behavior.  This
would allow people to avoid using INITIAL-INPUT to get what they want.

3. Stefan Monnier:

  [...] the `initial-input` arg should be changed into `setup-function`
  (so we don't have to use the hideous `minibuffer-with-setup-function`
  hack) and using a string there should be deprecated (the rare places
  where inserting an initial string makes sense can use a setup-function
  instead).

  Also the prompt handling should be changed so that it automatically
  inserts the default into the prompt.  Doing that in a reliable and
  backward compatible way is not completely straightforward, tho, so maybe
  a simpler solution is to introduce a whole new function instead.

  Then a user-customization could also be used to choose between the
  current default (where the default is added to the prompt) or the other
  option of always inserting the default as initial value (pre-selected
  so it can be deleted with a quick DEL).


TIA,

Michael.


In GNU Emacs 29.0.50 (build 13, x86_64-pc-linux-gnu, GTK+ Version 3.24.24, cairo version 1.16.0)
 of 2022-07-03 built on drachen
Repository revision: 0de355d8ee729ed6fec3ea379258d4a1f1d49021
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Debian GNU/Linux 11 (bullseye)

bug#56380: 29.0.50; completing-read: INITIAL-INPUT arg

[Lars Ingebrigtsen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> The docstring of `completing-read' says the argument INITIAL-INPUT is
> deprecated - yet there are over 30 nontrivial uses in Emacs' own Elisp
> sources.  So, although we currently don't want that this argument is
> used just to insert a default input, it's sometimes not possible to
> avoid using it.

[...]

> +  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.

It's an improvement on the original text, but this makes it sound like
inserting a common prefix is something callers are expected to do.  (But
instead it's a super rare special case that virtually nobody would
actually do in practice.)  So I'd rather just remove that sentence about
what you can use INITIAL-INPUT for.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#56380: 29.0.50; completing-read: INITIAL-INPUT arg

[Arash Esbati]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Michael Heerdegen <michael_heerdegen@web.de> writes:
>
>> The docstring of `completing-read' says the argument INITIAL-INPUT is
>> deprecated - yet there are over 30 nontrivial uses in Emacs' own Elisp
>> sources.  So, although we currently don't want that this argument is
>> used just to insert a default input, it's sometimes not possible to
>> avoid using it.
>
> [...]
>
>> +  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.
>
> It's an improvement on the original text, but this makes it sound like
> inserting a common prefix is something callers are expected to do.  (But
> instead it's a super rare special case that virtually nobody would
> actually do in practice.)  So I'd rather just remove that sentence about
> what you can use INITIAL-INPUT for.

Or say that it should be used in rare cases like a common prefix or a
cons cell for the history argument.  The docstring would be then more in
line with the reference manual (the common prefix part has be to be
added to the reference manual, but that is doable.)

https://www.gnu.org/software/emacs/manual/html_node/elisp/Initial-Input.html

Best, Arash

bug#56380: 29.0.50; completing-read: INITIAL-INPUT arg

[Drew Adams]

> >> The docstring of `completing-read' says the argument INITIAL-INPUT
> >> is deprecated - yet there are over 30 nontrivial uses in Emacs'
> >> own Elisp sources.  So, although we currently don't want that this
> >> argument is used just to insert a default input, it's sometimes
> >> not possible to avoid using it.
> >
> >> +  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.
> >
> > It's an improvement on the original text, but this makes it sound like
> > inserting a common prefix is something callers are expected to do

No, it doesn't.  Or rather, why do you think so?

> > (But instead it's a super rare special case that virtually nobody
> > would actually do in practice.)

No, it isn't.  Or rather, why do you think so?

> > So I'd rather just remove that sentence about what you can
> > use INITIAL-INPUT for.

Uh, the point of the bug report is to document better
what INITIAL-INPUT does, in such a way that users can
understand what it's for.

> Or say that it should be used in rare cases like a common prefix or a
> cons cell for the history argument.  The docstring would be then more
> in line with the reference manual (the common prefix part has be to be
> added to the reference manual, but that is doable.)

I disagree that you should be claiming that its
use is or should be rare.  Just leave it alone,
please.

I disagree that it's only about a common prefix.

And I disagree that, even for just that particular
use case, the case is only about a common _prefix_.
And I disagree that it's even about _any_ common
bit of literal text.

What that use case is about is text that _can be
useful as initial input_.  That's all.

Text that users can edit easily, to put to use in
the current _completion context_ (which includes
use it by completing it).

With _prefix_ completion, yes, insertion of a prefix
is useful.  But even then, the most useful position
of point isn't necessarily _after_ that prefix.

With other kinds of completion, other "common" text
can be appropriate - a common substring, for example.

It's not that the text to be inserted is necessarily,
literally "common" to all or many of the candidates.
It can be that its _completion_, in the current
context, is common to some or all candidates.

And even that's not necessary.  It's only about some
usefulness of having the particular text inserted.

In general, that means usefulness in _editing_ it,
in the broadest sense -- doing <whatever> with it --
to some advantage.

The uses of `completing-read' are many - it contains
multitudes.

The text suggested is fine.  It doesn't go into all
of this.  It just says "for example", and the example
of common-prefix insertion is sufficient.

But if you can't see why/when/how what it does can
be useful then just say what the INIT arg _does_.

And make clear that it's _not_ about INIT being a
substitute for DEF.  The two are different and
independent, though they can also cooperate -- be
used together to advantage.

Please don't spread a prejudice that INIT is only
for some bizarre, "rare" use.  Plenty of optional
args in Emacs are _truly_ used only rarely, but
their doc rightfully doesn't try to steer users
away from using them.

There's nothing bad or dangerous about using an
INIT arg with `completing-read'.  It's high time
for Emacs to relax and get over it.