[BUG] org-insert-link should use DEFAULT in read-string when asking for description

[BUG] org-insert-link should use DEFAULT in read-string when asking for description

[Visuwesh]

Currently, when asking the user for the description of link,
`org-insert-link' calls `read-string' with a non-nil INITIAL-INPUT but
this argument is discouraged and deprecated; moreover, it is unfriendly.

`org-insert-link' should, ideally, use the DEFAULT argument.  If the
user decides that the suggested description is okay, they can type M-n.

Regards

Emacs  : GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, X toolkit, cairo version 1.16.0, Xaw scroll bars)
Package: Org mode version 9.5.2 (release_9.5.2-9-g7ba24c @ /nix/store/0m0yw7b3zly74ljs3qmkblb780xg03id-emacs-git-20220130.0/share/emacs/29.0.50/lisp/org/)

Re: [BUG] org-insert-link should use DEFAULT in read-string when asking for description

[Max Nikulin]

On 25/02/2022 21:19, Visuwesh wrote:
> 
> Currently, when asking the user for the description of link,
> `org-insert-link' calls `read-string' with a non-nil INITIAL-INPUT but
> this argument is discouraged and deprecated; moreover, it is unfriendly.
> 
> `org-insert-link' should, ideally, use the DEFAULT argument.  If the
> user decides that the suggested description is okay, they can type M-n.

Due to lack of experience with emacs I can miss something. If so, 
please, correct me.

Are you suggesting replacing
     (read-string "rs-initial: " "Some initial")
by
     (read-string "rs-default: " nil nil "Some default")
? Is it possible to override provided default description by empty 
string in the latter variant? Currently it is possible to erase 
description using just backspace or C-S-backspace.

P.S. Many GUI applications pre-select whole value when some input field 
is focused, so it is possible to overwrite current value by typing 
anything. It may be convenient but is not consistent with emacs 
behavior. Moreover it makes uncertain if visually selected text 
overwrites X PRIMARY selection.

Re: [BUG] org-insert-link should use DEFAULT in read-string when asking for description

[Visuwesh]

[சனி, பிப்ரவரி 26 2022] Max Nikulin wrote:

> On 25/02/2022 21:19, Visuwesh wrote:
>> Currently, when asking the user for the description of link,
>> `org-insert-link' calls `read-string' with a non-nil INITIAL-INPUT but
>> this argument is discouraged and deprecated; moreover, it is unfriendly.
>> `org-insert-link' should, ideally, use the DEFAULT argument.  If the
>> user decides that the suggested description is okay, they can type M-n.
>
> Due to lack of experience with emacs I can miss something. If so,
> please, correct me.
>
> Are you suggesting replacing
>     (read-string "rs-initial: " "Some initial")
> by
>     (read-string "rs-default: " nil nil "Some default")
> ?

Yes, exactly.

> Is it possible to override provided default description by empty
> string in the latter variant? Currently it is possible to erase
> description using just backspace or C-S-backspace.
>

I admit that I forgot about this but Emacs can be made to not translate
empty string to the default argument if you DTRT when calling
`read-from-minibuffer' (and `read-shell-command' does this).  If writing
a new function just to get this functionality is too much, then I guess
I can live with the current behaviour, but this inconsistency is an
annoyance since I end up with garbled link names, which I only notice
_afterwards_.

> P.S. Many GUI applications pre-select whole value when some input
> field is focused, so it is possible to overwrite current value by
> typing anything. It may be convenient but is not consistent with emacs
> behavior. Moreover it makes uncertain if visually selected text
> overwrites X PRIMARY selection.

I would rather not go there.  You seem to describe
`delete-selection-mode' which, IMO, is also a nuisance given how
mark+point is not the same as "regular selections" (even with
`transient-mark-mode' turned on).

Re: [BUG] org-insert-link should use DEFAULT in read-string when asking for description

[Max Nikulin]

On 26/02/2022 21:16, Visuwesh wrote:
> [சனி, பிப்ரவரி 26 2022] Max Nikulin wrote:
> 
>> Are you suggesting replacing
>>      (read-string "rs-initial: " "Some initial")
>> by
>>      (read-string "rs-default: " nil nil "Some default")
>> ?
> 
> Yes, exactly.

However you agreed that it would be regression since empty description 
use case would be impossible.

> I admit that I forgot about this but Emacs can be made to not translate
> empty string to the default argument if you DTRT when calling
> `read-from-minibuffer' (and `read-shell-command' does this).  If writing
> a new function just to get this functionality is too much, then I guess

`read-shell-command' still has INITIAL argument and it is used by 
various callers (vc, grep). In addition, unlike for link description, I 
do not see any point in empty shell command (e.g. in vim :! allows to 
see output of previous shell command). So `read-shell-command' may 
behave quite differently.

Current way to ask for link description has the following properties:
- Almost no action (just RET) if the user happy with suggested 
description. Default description is provided with hope that it is the 
most convenient option.
- It is possible to erase everything and to get a link with no description.
- The user is free to replace default description with arbitrary 
alternative text.

It is unclear for me how to tame `read-from-minibuffer' to get equally 
convenient behavior using DEFAULT argument instead of formally 
deprecated INITIAL one.

> I can live with the current behaviour, but this inconsistency is an
> annoyance since I end up with garbled link names, which I only notice
> _afterwards_.

Sorry, but I have not figured out what particular problem you met.

Re: [BUG] org-insert-link should use DEFAULT in read-string when asking for description

[Visuwesh]

[ Please keep me in the CCs since I don't follow the list.  ]

[ஞாயிறு, பிப்ரவரி 27 2022] Max Nikulin wrote:

> On 26/02/2022 21:16, Visuwesh wrote:
>> [சனி, பிப்ரவரி 26 2022] Max Nikulin wrote:
>> 
>>> Are you suggesting replacing
>>>      (read-string "rs-initial: " "Some initial")
>>> by
>>>      (read-string "rs-default: " nil nil "Some default")
>>> ?
>> Yes, exactly.
>
> However you agreed that it would be regression since empty description
> use case would be impossible.
>

No.  It is impossible to do it using read-string, but it is possible to
do it by writing a function that calls read-from-minibuffer (and I gave
an example of a function that does this).

>> I admit that I forgot about this but Emacs can be made to not translate
>> empty string to the default argument if you DTRT when calling
>> `read-from-minibuffer' (and `read-shell-command' does this).  If writing
>> a new function just to get this functionality is too much, then I guess
>
> `read-shell-command' still has INITIAL argument and it is used by
> various callers (vc, grep). In addition, unlike for link description,
> I do not see any point in empty shell command (e.g. in vim :! allows
> to see output of previous shell command). So `read-shell-command' may
> behave quite differently.
>

Two things:

    1. I dislike grep's behaviour.  However, I understand why grep
       behaves the way it does.  It makes far more sense to use the
       INITIAL argument in grep, but I don't see the same for
       org-insert-link.

       [ In grep, you rarely ever need to change the initial input.  ]

    2. The reason why I cited read-shell-command does not have anything
       to do with the usefulness of empty string (or shell command).  I
       merely wanted to point out that you can have BOTH the DEFAULT
       argument (and no INITIAL), and can make the empty string a valid
       output from the function (i.e., without getting substituted by
       the DEFAULT argument).

I hope (2) makes sense.  I'm struggling to word it.

> Current way to ask for link description has the following properties:
> - Almost no action (just RET) if the user happy with suggested
>   description. Default description is provided with hope that it is
>   the most convenient option.
> - It is possible to erase everything and to get a link with no description.
> - The user is free to replace default description with arbitrary
>   alternative text.
>
> It is unclear for me how to tame `read-from-minibuffer' to get equally
> convenient behavior using DEFAULT argument instead of formally
> deprecated INITIAL one.
>

Please read the docstring of read-from-minibuffer.  You would be better
served by reading it than me replicating it here.  And I gave
read-shell-command as an example so others could study the function.

In essence, you can get the old behaviour (1) but you need to type M-n
beforehand.  Its one more key but it is far better than the current
behaviour since it is consistent with rest of the Emacs ecosystem (see
below also).

>> I can live with the current behaviour, but this inconsistency is an
>> annoyance since I end up with garbled link names, which I only notice
>> _afterwards_.
>
> Sorry, but I have not figured out what particular problem you met.

Inconsistency is the problem.  org-insert-link breaks my muscle memory.
I am not sure if you use the default completion system, but if you do,
org-insert-link sticks out by being intrusive.

With every command I use, when I know that the DEFAULT argument will be
of no use, I simply start typing.  However, with org-insert-link I have
to clear the input _first_ then start typing.  This never happens
elsewhere, even in grep (which you cite as an example)!

Re: [BUG] org-insert-link should use DEFAULT in read-string when asking for description

[Max Nikulin]

On 27/02/2022 23:16, Visuwesh wrote:
> [ஞாயிறு, பிப்ரவரி 27 2022] Max Nikulin wrote:
>> On 26/02/2022 21:16, Visuwesh wrote:
>>> [சனி, பிப்ரவரி 26 2022] Max Nikulin wrote:
>>>
>>>> Are you suggesting replacing
>>>>       (read-string "rs-initial: " "Some initial")
>>>> by
>>>>       (read-string "rs-default: " nil nil "Some default")
>>>> ?
>>> Yes, exactly.
>>
>> However you agreed that it would be regression since empty description
>> use case would be impossible.
> 
> No.  It is impossible to do it using read-string, but it is possible to
> do it by writing a function that calls read-from-minibuffer (and I gave
> an example of a function that does this).
> 
>>> I admit that I forgot about this but Emacs can be made to not translate
>>> empty string to the default argument if you DTRT when calling
>>> `read-from-minibuffer' (and `read-shell-command' does this).  If writing
>>> a new function just to get this functionality is too much, then I guess
>>
>      2. The reason why I cited read-shell-command does not have anything
>         to do with the usefulness of empty string (or shell command).  I
>         merely wanted to point out that you can have BOTH the DEFAULT
>         argument (and no INITIAL), and can make the empty string a valid
>         output from the function (i.e., without getting substituted by
>         the DEFAULT argument).

In my opinion deprecation of the INITIAL argument without some descent 
replacement was a mistake. I suspect that such statement appeared 
without realizing of the problem with discriminating default vs. empty 
value. `read-string' oversimplify it by assumption that users do not 
need empty values at all. Your first argument was that INITIAL is 
deprecated but in the next message you pointed to a function that still 
uses the INITIAL argument. On the other hand `read-shell-command' 
belongs to command for which empty return value is hardly meaningful 
despite it is possible. That is why I disputed that `read-shell-command' 
is a good example of `read-from-minibuffer' usage in the context of 
`org-insert-link'.

> Please read the docstring of read-from-minibuffer.  You would be better
> served by reading it than me replicating it here.  And I gave
> read-shell-command as an example so others could study the function.
> 
> In essence, you can get the old behaviour (1) but you need to type M-n
> beforehand.  Its one more key but it is far better than the current
> behaviour since it is consistent with rest of the Emacs ecosystem (see
> below also).

I do not think it is a good idea to require extra M-n to keep the 
*current* description when a user hit C-c C-l to edit the link target 
with no intention to touch its description.

> With every command I use, when I know that the DEFAULT argument will be
> of no use, I simply start typing.  However, with org-insert-link I have
> to clear the input _first_ then start typing.  This never happens
> elsewhere, even in grep (which you cite as an example)!

I agree that it is great to be able to just start typing to replace 
default description. Unfortunately similar to significant fraction of 
interfaces, `org-insert-link' behavior is a result of trade-offs and 
compromises. If you see a way to improve it, please, submit a patch or 
at least post a code that can be tried from a src block or from the 
*scratch* buffer to evaluate possible regressions and unaddressed use cases.