Doc of deprecated INITIAL-INPUT arg of completing-read

Doc of deprecated INITIAL-INPUT arg of completing-read

[Michael Heerdegen]

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

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?


[-- 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: 1577 bytes --]

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


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


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.

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

[Drew Adams]

> 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?

FWIW, for my part I disagree that any "warning"
is warranted.  There's nothing dangerous to warn
about.

I disagree with this (as I also disagree with the
deprecation):

  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.

There's zero reason to discourage its use in any
blanket way, let alone "strongly" discourage.

INIT and DEF are different in behavior, and thus
in use cases.  Telling users to use one of them
_instead of_ the other is misguided, IMO.

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

But the confusion over their different uses is
related to a missing feature, IMO, which is the
ability for users to automatically insert the
DEF value (not INIT) into the minibuffer, as an
alternative to using `M-n' to insert it.

Neither alternative is absolutely "better" than
the other - this is naturally a user preference.

The mistakes made in deciding to deprecate (or
discourage) INIT-INPUT are two: (1) confusing
it with a default value - DEF is no substitute
for INIT, and (2) thinking that it's never a
good UI to insert default values (DEF) in the
minibuffer.

#1 should be fixed by removing the deprecation
and explaining the difference between the two
(not by warning not to use INIT).

#2 should be fixed by letting _users_ decide
which DEF-inserting behavior they prefer: (1)
automatic or (2) manual (`M-n').

The choice of whether DEF should be inserted in
the minibuffer should be up to users.  It's not
for Emacs to decide for all and always which UI
behavior (auto or `M-n') is better for everyone.

If a user often wants to use (edit or choose)
the default value then s?he might well want it
to be inserted in the minibuffer.  If a user
rarely uses the default value then s?he might
want to insert it only manually, with `M-n'.

That's really what it comes down to: having to
delete DEF manually, if you don't want it, or
having to insert it manually, if you do.

(This is somewhat akin to the choice of whether
to use `delete-selection-mode'.)

In the help-gnu-emacs discussion you cited, I
detailed what I would propose for #2 - I won't
repeat details here.  I'll just say that users
should have some way to choose whether DEF is
to be automatically inserted in the minibuffer.

(I also said there that they should have a way
to choose whether it's inserted in the prompt.
With my proposal, when DEF's auto-inserted in
the minibuffer it's not inserted in the prompt,
but users can also choose to never insert it
in the prompt.)

In any case, a missing insert-DEF-in-minibuffer
behavior is 100% _independent_ of INIT-INPUT,
which, yes, shouldn't be deprecated.

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

[Christopher Dimech]

> Sent: Tuesday, June 28, 2022 at 4:33 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Michael Heerdegen" <michael_heerdegen@web.de>, "Emacs Development" <emacs-devel@gnu.org>
> Subject: RE: [External] : Doc of deprecated INITIAL-INPUT arg of completing-read
>
> > 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?
>
> FWIW, for my part I disagree that any "warning"
> is warranted.  There's nothing dangerous to warn
> about.
>
> I disagree with this (as I also disagree with the
> deprecation):
>
>   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.
>
> There's zero reason to discourage its use in any
> blanket way, let alone "strongly" discourage.

I agree that there exists no reason to discourage it.
Nothing bad or difficult happens when it is used.


> INIT and DEF are different in behavior, and thus
> in use cases.  Telling users to use one of them
> _instead of_ the other is misguided, IMO.
>
> 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.

Right.  When people start mixing things up or hack their way to
things that creates confusion, the solution in for them to stop
with such approaches.


> But the confusion over their different uses is
> related to a missing feature, IMO, which is the
> ability for users to automatically insert the
> DEF value (not INIT) into the minibuffer, as an
> alternative to using `M-n' to insert it.
>
> Neither alternative is absolutely "better" than
> the other - this is naturally a user preference.
>
> The mistakes made in deciding to deprecate (or
> discourage) INIT-INPUT are two: (1) confusing
> it with a default value - DEF is no substitute
> for INIT, and (2) thinking that it's never a
> good UI to insert default values (DEF) in the
> minibuffer.
>
> #1 should be fixed by removing the deprecation
> and explaining the difference between the two
> (not by warning not to use INIT).
>
> #2 should be fixed by letting _users_ decide
> which DEF-inserting behavior they prefer: (1)
> automatic or (2) manual (`M-n').
>
> The choice of whether DEF should be inserted in
> the minibuffer should be up to users.  It's not
> for Emacs to decide for all and always which UI
> behavior (auto or `M-n') is better for everyone.
>
> If a user often wants to use (edit or choose)
> the default value then s?he might well want it
> to be inserted in the minibuffer.  If a user
> rarely uses the default value then s?he might
> want to insert it only manually, with `M-n'.
>
> That's really what it comes down to: having to
> delete DEF manually, if you don't want it, or
> having to insert it manually, if you do.
>
> (This is somewhat akin to the choice of whether
> to use `delete-selection-mode'.)
>
> In the help-gnu-emacs discussion you cited, I
> detailed what I would propose for #2 - I won't
> repeat details here.  I'll just say that users
> should have some way to choose whether DEF is
> to be automatically inserted in the minibuffer.
>
> (I also said there that they should have a way
> to choose whether it's inserted in the prompt.
> With my proposal, when DEF's auto-inserted in
> the minibuffer it's not inserted in the prompt,
> but users can also choose to never insert it
> in the prompt.)
>
> In any case, a missing insert-DEF-in-minibuffer
> behavior is 100% _independent_ of INIT-INPUT,
> which, yes, shouldn't be deprecated.
>
>

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

[Michael Heerdegen]

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

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:


[-- 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: 1635 bytes --]

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


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


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


Thanks,

Michael.

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

[Drew Adams]

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

  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 M-n.

Mostly agreed. ;-)

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.

1. "default value" instead of "default".
2. INIT is independent of DEF.  Don't say not to use it
   except for XYZ.  Instead, just say not to use it as
   a substitute for providing a default value.  That was
   my point.
3. Give the example of inserting a common prefix as just
   that: an example.  Don't suggest it's the only use case.
4. A filename prefix is just a prefix, no?
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.
___

(The "prefix" insertion case is only particularly
relevant when `completion-styles' favors prefix completion.
With other styles the common text you insert isn't
necessarily a prefix.)

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Jean Louis]

* Michael Heerdegen <michael_heerdegen@web.de> [2022-06-27 18:22]:
> 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.

For anything there must be reason. What is reason to "strongly warn"
programmer not to use it?

It is just an option as any other.

Instead, make better description what it means.

I have many use cases for initial-input, when making calls I need to
make a note, and I like entering new date and time automatically as
initial input, so that I do not need to invoke keys in minibuffer.

From that innocent view point, I see no reason to "strongly warn"
programmers not to use a useful function.


-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

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

[Jean Louis]

* Drew Adams <drew.adams@oracle.com> [2022-06-27 19:40]:
> There's zero reason to discourage its use in any
> blanket way, let alone "strongly" discourage.

I did not see your message. You said it better, I agree with that
statement.

> INIT and DEF are different in behavior, and thus
> in use cases.  Telling users to use one of them
> _instead of_ the other is misguided, IMO.

Exactly.

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

That is right, that is where misunderstanding come from.


-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

> For anything there must be reason. What is reason to "strongly warn"
> programmer not to use it?

Because there's a lot of past experience where people want to have the
Windows-style behavior where prompts get prefilled with the (selected)
default, and they don't understand that in order to get that they need
to change `completing-read`.  So instead they abuse `initial-content` in
their code (even though it doesn't give quite the same behavior either
but gets the closer).


        Stefan

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

[Christopher Dimech]

> Sent: Wednesday, June 29, 2022 at 4:19 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: emacs-devel@gnu.org
> Subject: Re: [External] : Doc of deprecated INITIAL-INPUT arg of completing-read
>
> 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:

I approve of it.


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

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Jean Louis]

* Stefan Monnier <monnier@iro.umontreal.ca> [2022-06-29 00:33]:
> > For anything there must be reason. What is reason to "strongly warn"
> > programmer not to use it?
> 
> Because there's a lot of past experience where people want to have the
> Windows-style behavior where prompts get prefilled with the (selected)
> default, and they don't understand that in order to get that they need
> to change `completing-read`.  So instead they abuse `initial-content` in
> their code (even though it doesn't give quite the same behavior either
> but gets the closer).

That would hypothetically mean that for one smaller group of users
using Windows-style behavior every programmer has to be "strongly
warned".

Your explanation above is also not part of docstring and I do not say
it is necessary to be, but when you think there are such reasons than
maybe better is to solve how that understanding will arrive to
users. Understanding will arrive with good communication in the
docstring.

Instead of strongly warning against useful function it is better to
strongly make distinction in the description what that initial input
means as distinguished to the default value.

-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

> Instead of strongly warning against useful function it is better to
> strongly make distinction in the description what that initial input
> means as distinguished to the default value.

AFAIK that's what the docstring does.


        Stefan

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Arash Esbati]

Michael Heerdegen <michael_heerdegen@web.de> writes:

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

Thanks for working on this.  In order to make this change complete, I
think there are other areas to be touched/considered as well:

 • docstrings of `read-string' and `read-from-minibuffer'

 • 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

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

I think it is best to file a bug report with a complete change
suggestion, get it approved by the maintainer team and then turn the
page.

Are you willing to take this?

Best, Arash

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

[Michael Heerdegen]

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

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:


[-- 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: 2175 bytes --]

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


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



Thanks,

Michael.

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Michael Heerdegen]

Arash Esbati <arash@gnu.org> writes:

> In order to make this change complete, I
> think there are other areas to be touched/considered as well:
>
>  • docstrings of `read-string' and `read-from-minibuffer'

Yes indeed - we can continue with these.

>  • 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

I won't touch the manual, getting fluent in texinfo is not on my list
no, and I have lots of other stuff on my list.

> I think it is best to file a bug report with a complete change
> suggestion, get it approved by the maintainer team and then turn the
> page.
>
> Are you willing to take this?

Sorry, no, I'll stop after getting the docstring(s) into a more
consistent state.  Feel free to do it, you would have my support.

Thanks,

Michael.

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

[Drew Adams]

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

Great; thanks.  LGTM, and thanks for doing this.

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Because there's a lot of past experience where people want to have the
  > Windows-style behavior where prompts get prefilled with the (selected)
  > default, and they don't understand that in order to get that they need
  > to change `completing-read`.  So instead they abuse `initial-content` in
  > their code (even though it doesn't give quite the same behavior either
  > but gets the closer).

Would it be possible to tell users the rest of that?
That is, to tell them what to do instead of using INITIAL-CONTENT?
Ideally it should tell them what mode to enable to get that behavior
for Emacs completion generally.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I have many use cases for initial-input, when making calls I need to
  > make a note, and I like entering new date and time automatically as
  > initial input, so that I do not need to invoke keys in minibuffer.

Is there a reason not to handle this the way most commands do?  That
is to use the current or last-used date-time as the default, if the
argument is empty.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Arash Esbati]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Arash Esbati <arash@gnu.org> writes:
>
>> I think it is best to file a bug report with a complete change
>> suggestion, get it approved by the maintainer team and then turn the
>> page.
>>
>> Are you willing to take this?
>
> Sorry, no, I'll stop after getting the docstring(s) into a more
> consistent state.  Feel free to do it, you would have my support.

Then please open a bug report with your changes which can be installed.
The report can be closed when someone steps forward and makes a
suggestion for the rest.

Best, Arash

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

>   > Because there's a lot of past experience where people want to have the
>   > Windows-style behavior where prompts get prefilled with the (selected)
>   > default, and they don't understand that in order to get that they need
>   > to change `completing-read`.  So instead they abuse `initial-content` in
>   > their code (even though it doesn't give quite the same behavior either
>   > but gets the closer).
>
> Would it be possible to tell users the rest of that?
> That is, to tell them what to do instead of using INITIAL-CONTENT?
> Ideally it should tell them what mode to enable to get that behavior
> for Emacs completion generally.

It's mostly waiting for someone to write the code.  Then it's just
a matter of setting a boolean config var.


        Stefan

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Jean Louis]

* Richard Stallman <rms@gnu.org> [2022-06-30 06:08]:
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
>   > I have many use cases for initial-input, when making calls I need to
>   > make a note, and I like entering new date and time automatically as
>   > initial input, so that I do not need to invoke keys in minibuffer.
> 
> Is there a reason not to handle this the way most commands do?  That
> is to use the current or last-used date-time as the default, if the
> argument is empty.

There are good reasons. I am using read-from-minibuffer and
completing-read many times per day as that is one of the way how I
enter new notes about assigned tasks.

In general INITIAL-INPUT is helpful to easier enter some value, and
DEFAULT is what is chosen if no value is entered.

Those are two different meanings not related to each other. 

If some people choose to make them same, it does not make their
underlying functionality same. That is matter of docstring to explain
it well for users.

The DEFAULT I use for those cases where there is nothing written in
the prompt in minibuffer, so just by pressing RET I would get the
default. 

DEFAULT may be inserted also with M-n however, when there are many
entries in completing that is rather for me "unsafe" way to choose the
default as I may not have assurance that I have pressed M-n once or
more times, and more often I use M-p to go back in history to choose
some previous value.

INITIAL-INPUT I use to help myself to enter some information quickly
in the minibuffer. It is often, in my case more than often, different
then the default.

Practical examples:
===================

Task has been assigned, and report is written on the task. DEFAULT is
"2022-07-01 Customer informed." but INITIAL-INPUT may be exact date
and time with space waiting for me as user to enter the actual note
about it, like this: "2022-07-01 14:22 ". If I however, delete it, and
press RET, I would get default "2022-07-01 Customer informed."

Further, I do not use those functions directly, they are wrapped in my
functions and what is DEFAULT is usually database backed entry, while
what is INITIAL-INPUT is usually dynamically generated string to help
me as user spare writing.

This may not mean much to people who rarely use completing-read or
read-from-minibuffer -- it means to me and team members who use it way
too often and where INITIAL-INPUT becomes helpful string placed in
mini buffer to help the with editing. It does not represent the
DEFAULT. 

Also note that in database backed editing there may be different
users, and one user could turn off INITIAL-INPUT, while other could
have it, while third one could customize it. 

In general INITIAL-INPUT shall not be considered neither similar nor
equivalent to any DEFAULT, it should be considered as helpful way to
put initial string in minibuffer, whatever it may be such, and initial
input is on my side rather editable, while DEFAULT is not necessarily
considered editable.

Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Michael Heerdegen]

Arash Esbati <arash@gnu.org> writes:

> Then please open a bug report with your changes which can be installed.
> The report can be closed when someone steps forward and makes a
> suggestion for the rest.

Done - see Bug#56380.

I tried to summarize suggestions that were made.  If you think something
important is missing - or you want to add something different - please
just add it to that bug report.


Thanks,

Michael.

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Tim Landscheidt]

Stefan Monnier <monnier@iro.umontreal.ca> wrote some time ago:

>> For anything there must be reason. What is reason to "strongly warn"
>> programmer not to use it?

> Because there's a lot of past experience where people want to have the
> Windows-style behavior where prompts get prefilled with the (selected)
> default, and they don't understand that in order to get that they need
> to change `completing-read`.  So instead they abuse `initial-content` in
> their code (even though it doesn't give quite the same behavior either
> but gets the closer).

I have not found a clear answer for my use case, so I post
it here:

In Gnus, I want to set a group parameter ("to-list") when I
encounter an article in a Gmane group if that article has an
"List-Post" header.  In most cases, I want to set the para-
meter to the header's value.  Sometimes the header's value
is "encrypted" in which case I want to set it to another
value (which I researched out-of-prompt).

So I want to display the value, if it is "correct", one
should have to press (just) RET, otherwise one should be
able to amend the input.

For me (with list-post-in-article being the header's value):

| (read-string "to-list value: " list-post-in-article)

works just perfectly then.

So what is the proposed Emacs way to get this behaviour if
INITIAL-INPUT is not to be used?

Tim

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

> In Gnus, I want to set a group parameter ("to-list") when I
> encounter an article in a Gmane group if that article has an
> "List-Post" header.  In most cases, I want to set the para-
> meter to the header's value.  Sometimes the header's value
> is "encrypted" in which case I want to set it to another
> value (which I researched out-of-prompt).

That's a very usual use-case.
That should use

    (read-string (format-prompt "to-list value (default %s): "
                                default)
                 nil nil default)

And if you're perplexed by the complexity of this code compared to the
one you proposed, I totally agree: we should rework our API so that The
Right Way™ is also the easiest way.


        Stefan

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Tim Landscheidt]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> In Gnus, I want to set a group parameter ("to-list") when I
>> encounter an article in a Gmane group if that article has an
>> "List-Post" header.  In most cases, I want to set the para-
>> meter to the header's value.  Sometimes the header's value
>> is "encrypted" in which case I want to set it to another
>> value (which I researched out-of-prompt).

> That's a very usual use-case.
> That should use

>     (read-string (format-prompt "to-list value (default %s): "
>                                 default)
>                  nil nil default)

> And if you're perplexed by the complexity of this code compared to the
> one you proposed, I totally agree: we should rework our API so that The
> Right Way™ is also the easiest way.

I'm not perplexed :-).  What I find confusing is:

a) The solution for this "very usual" use case is not men-
   tioned anywhere in the documentation.  Instead, the doc-
   string (for completing-read) suggests a different work-
   flow.

b) With this solution, if the user needs to change the de-
   fault/initial value, he has to use one more keystroke
   (M-n) than if INITIAL-INPUT had been used.  The only ar-
   gument given in the documentation for requiring that ad-
   ditional keystroke is "initial input is an intrusive in-
   terface" (RMS in
   70c750c0e8e54947399245af6c8b49f908c8939c).  I have no
   idea what an "intrusive interface" is, and why
   INITIAL-INPUT is, but the solution above is not.

Tim

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

> I'm not perplexed :-).  What I find confusing is:
>
> a) The solution for this "very usual" use case is not men-
>    tioned anywhere in the documentation.  Instead, the doc-
>    string (for completing-read) suggests a different work-
>    flow.

The documentation probably needs to be improved in this respect,
admittedly, but I can't see where the docstring suggests a different
workflow (or more specifically, I suspect that it only does so if you
have a particular workflow in mind to start with).

> b) With this solution, if the user needs to change the de-
>    fault/initial value, he has to use one more keystroke
>    (M-n) than if INITIAL-INPUT had been used.

But with your solution, the users that want not just to modify the
default but to enter a different value need to first delete the initial
value, (e.g. `C-a C-k`).
You win some, you lose some.


        Stefan

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Tim Landscheidt]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> I'm not perplexed :-).  What I find confusing is:

>> a) The solution for this "very usual" use case is not men-
>>    tioned anywhere in the documentation.  Instead, the doc-
>>    string (for completing-read) suggests a different work-
>>    flow.

> The documentation probably needs to be improved in this respect,
> admittedly, but I can't see where the docstring suggests a different
> workflow (or more specifically, I suspect that it only does so if you
> have a particular workflow in mind to start with).

The docstring for completing-read (GNU Emacs 28.3) says re-
garding INITIAL-INPUT:

| If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
|   with point positioned at the end.  If it is (STRING . POSITION), the
|   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
|   M-n.

If one follows this recommendation (setting INITIAL-INPUT to
nil and passing the original value as DEF), the user is not
made aware of the original INITIAL-INPUT value until he
presses M-n.

>> b) With this solution, if the user needs to change the de-
>>    fault/initial value, he has to use one more keystroke
>>    (M-n) than if INITIAL-INPUT had been used.

> But with your solution, the users that want not just to modify the
> default but to enter a different value need to first delete the initial
> value, (e.g. `C-a C-k`).
> You win some, you lose some.

For example, when I use M-x compile RET, I typically do not
want to enter a different value, but amend the existing one
by adding/changing the target or setting an option.  But
even in the basic case of C-x C-f, if I want to find a file
upwards of default-directory, the two extra keystrokes har-
monize well with wanting to do something different, so it
never occured to me that Emacs should protect me from them.

Tim

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

[Drew Adams]

> If one follows this recommendation (setting INITIAL-INPUT to
> nil and passing the original value as DEF), the user is not
> made aware of the original INITIAL-INPUT value until he
> presses M-n.

> For example, when I use M-x compile RET, I typically do not
> want to enter a different value, but amend the existing one
> by adding/changing the target or setting an option.  But
> even in the basic case of C-x C-f, if I want to find a file
> upwards of default-directory, the two extra keystrokes har-
> monize well with wanting to do something different, so it
> never occured to me that Emacs should protect me from them.

Exactly - use the default value as is or edit it.

A user, such as yourself, can prefer having the default
value in the minibuffer by default, i.e., without having
to use `M-n' to insert it.  And how commonly you find
that you use the default value, either as is or by
editing it, can influence your preference.

Stefan's right that the choice is between (1) having it
present by default, and needing to remove it if you don't
want it, and (2) having it absent by default, and needing
to use `M-n' to insert it if you do want it.

The point is that that should be a _user_ choice, not
preordained.  Give users a user option for exactly that
choice.

How helpful a particular use of `completing-read' is in
providing a useful default value can also matter,
obviously.  A poor default value is less likely to be
used (as is or edited).  The vanilla Emacs design of not
inserting the default automatically essentially assumes
(allows and encourages) lazy coding with poor default
values.
___

But this is all about the DEFAULT value, _not_ the
INITIAL-INPUT.  Those are separate things for a reason,
because you can use them differently.

The Emacs policy should be similar to this, which is
the Icicles policy (i.e., if you enable its minor
mode):

1. INITIAL-INPUT should in no way be deprecated.  It's
useful.  It gives a call to `completing-read', e.g.
for a particular command, control over what happens by
default wrt inserting an initial value.

A DEFAULT value doesn't in any way systematically
replace the utility of INITIAL-INPUT.

2. Users should be able to set their preference wrt
whether DEFAULT is inserted automatically (modulo
use of INITIAL-INPUT).  IOW, a user option.
___

Icicles provides option `icicle-default-value' for
this.  Its default value is `t'.

  nil               - Don't insert default value or add it to prompt.
  t                 - Add default value to `completing-read' prompt.
                      Do not insert it.
  `insert-start'    - Insert default value and leave cursor at start.
  `insert-end'      - Insert default value and leave cursor at end.
  `preselect-start' - Insert and preselect default value;
                      leave cursor at beginning.
  `preselect-end'   - Insert and preselect default value;
                      leave cursor at end.

If the default value is inserted automatically you can
easily remove it with `M-k'.  You can use that anytime,
to completely empty the minibuffer, regardless of the
position of the cursor or how much text is there.
(Vanilla Emacs should have a key for this.)

If the default value isn't inserted automatically,
then you can use `M-n' to insert it (as in vanilla
Emacs).  Overall, the default Icicles behavior
matches that of vanilla Emacs.

I mention all of this not to advertise Icicles but to
(once again) suggest that vanilla Emacs should offer
behavior that's somewhat similar:

1. It shouldn't consider INITIAL-INPUT "deprecated".
2. It should give users an option, to choose whether
   the DEFAULT value gets inserted automatically.
3. It should provide a key to empty the minibuffer.
___


https://www.emacswiki.org/emacs/Icicles_-_Customization_and_General_Tips#icicle-default-value

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

> The docstring for completing-read (GNU Emacs 28.3) says re-
> garding INITIAL-INPUT:
>
> | If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
> |   with point positioned at the end.  If it is (STRING . POSITION), the
> |   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
> |   M-n.
>
> If one follows this recommendation (setting INITIAL-INPUT to
> nil and passing the original value as DEF), the user is not
> made aware of the original INITIAL-INPUT value until he
> presses M-n.

Oh, you mean we should add that the default should be passed to
`format-prompt`?  I guess that would help, indeed.

Of course, even better would be to call `format-prompt` automatically.
I just don't know how to do that conveniently without
breaking compatibility.

Maybe something like

    (unless (memq (aref prompt (- (length prompt) 1)) '(?: ?? ?\s))
      (setq prompt (format-prompt prompt default)))

?

> For example, when I use M-x compile RET, I typically do not
> want to enter a different value, but amend the existing one
> by adding/changing the target or setting an option.

I suspect this depends on the user.

> But even in the basic case of C-x C-f, if I want to find a file
> upwards of default-directory, the two extra keystrokes harmonize
> well with wanting to do something different, so it never occured to me
> that Emacs should protect me from them.

🙂

FWIW, it's almost never necessary in `C-x C-f` since you can type `../`
to "go up", `~/` to go home, and you don't need to type anything at all to
go back to the root.


        Stefan

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Tim Landscheidt]

Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> The docstring for completing-read (GNU Emacs 28.3) says re-
>> garding INITIAL-INPUT:

>> | If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
>> |   with point positioned at the end.  If it is (STRING . POSITION), the
>> |   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
>> |   M-n.

>> If one follows this recommendation (setting INITIAL-INPUT to
>> nil and passing the original value as DEF), the user is not
>> made aware of the original INITIAL-INPUT value until he
>> presses M-n.

> Oh, you mean we should add that the default should be passed to
> `format-prompt`?  I guess that would help, indeed.

Yes.  (I doubt, though, that my brain can ever be trained to
find it convenient that pressing RET at position B will make
Emacs use the text displayed at position A, and this text at
position B will not go away if I tell Emacs that I want to
enter something different so that I can remember that if I
delete all text and press RET, it will use the text at posi-
tion A again.)

> […]

>> But even in the basic case of C-x C-f, if I want to find a file
>> upwards of default-directory, the two extra keystrokes harmonize
>> well with wanting to do something different, so it never occured to me
>> that Emacs should protect me from them.

> 🙂

> FWIW, it's almost never necessary in `C-x C-f` since you can type `../`
> to "go up", `~/` to go home, and you don't need to type anything at all to
> go back to the root.

I wasn't aware of the latter two until now, and I can't say
that the display of "~//etc/passwd" leading to visit
"/etc/passwd", but (find-file "~//etc/passwd") not working
is intuitive to me.

Tim

Re: Doc of deprecated INITIAL-INPUT arg of completing-read

[Stefan Monnier]

>>> The docstring for completing-read (GNU Emacs 28.3) says re-
>>> garding INITIAL-INPUT:
>
>>> | If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
>>> |   with point positioned at the end.  If it is (STRING . POSITION), the
>>> |   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
>>> |   M-n.
>
>>> If one follows this recommendation (setting INITIAL-INPUT to
>>> nil and passing the original value as DEF), the user is not
>>> made aware of the original INITIAL-INPUT value until he
>>> presses M-n.
>
>> Oh, you mean we should add that the default should be passed to
>> `format-prompt`?  I guess that would help, indeed.
>
> Yes.  (I doubt, though, that my brain can ever be trained to
> find it convenient that pressing RET at position B will make
> Emacs use the text displayed at position A, and this text at
> position B will not go away if I tell Emacs that I want to
> enter something different so that I can remember that if I
> delete all text and press RET, it will use the text at posi-
> tion A again.)

But that's a UI issue.  Whereas we're discussing an API issue.
The API's design should allow for several UI choices.

> I wasn't aware of the latter two until now, and I can't say
> that the display of "~//etc/passwd" leading to visit
> "/etc/passwd", but (find-file "~//etc/passwd") not working
> is intuitive to me.

That's been a feature of `C-x C-f` since for ever :-)
At some point the (find-file "~//etc/passwd") also worked.  I think this
was changed around Emacs-21 or maybe even Emacs-19.  Then in Emacs-22 we
added the `file-name-shadow-mode` to give some visual feedback about
the feature.


        Stefan