Consider removing newlines from org-insert-link help message

Consider removing newlines from org-insert-link help message

[Salih Muhammed]

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/ol.el#n1856

	(insert "Insert a link.
Use TAB to complete link prefixes, then RET for type-specific completion support\n")

This causes a stretch in the message buffer, which sometimes is being a
little bit annoying, I'm advising org-link-insert personally because of
it.

Maybe merging it into one line:

	(insert "Insert a link. Use TAB to complete link prefixes, then RET for type-specific completion support\n")

Will make it better.

--
Regards,
Salih

Re: Consider removing newlines from org-insert-link help message

[Ihor Radchenko]

Salih Muhammed <lr0@gmx.com> writes:

> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/lisp/ol.el#n1856
>
> 	(insert "Insert a link.
> Use TAB to complete link prefixes, then RET for type-specific completion support\n")
>
> This causes a stretch in the message buffer, which sometimes is being a
> little bit annoying, I'm advising org-link-insert personally because of
> it.
>
> Maybe merging it into one line:
>
> 	(insert "Insert a link. Use TAB to complete link prefixes, then RET for type-specific completion support\n")
>
> Will make it better.

I am not sure. Your variant will be worse  on smaller screens
or terminals, when the line wrap may look more ugly for longer line.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Consider removing newlines from org-insert-link help message

[Salih Muhammed]

> I am not sure. Your variant will be worse  on smaller screens
> or terminals, when the line wrap may look more ugly for longer line.

What about replacing it with shorter description?

"Insert a link. Use TAB for prefixes completion, RET for type-specific completion"

This is only 80 characters, should be suitable for small terminals.


--
Regards,
Salih

Re: Consider removing newlines from org-insert-link help message

[Ihor Radchenko]

Salih Muhammed <lr0@gmx.com> writes:

>> I am not sure. Your variant will be worse  on smaller screens
>> or terminals, when the line wrap may look more ugly for longer line.
>
> What about replacing it with shorter description?

 (Insert a link. Use TAB to complete link prefixes, then RET for type-specific completion support)

> "Insert a link. Use TAB for prefixes completion, RET for type-specific completion"
>
> This is only 80 characters, should be suitable for small terminals.

"then" was important in the original formulation.

I personally do not mind having a shorter variant, but we should not
make it obfuscated just for the sake of being short.

Also, if you really want to save screen space, you may consider hiding
the whole *Org Links* window by customizing `display-buffer-alist'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Consider removing newlines from org-insert-link help message

[Rudolf Adamkovič]

Salih Muhammed <lr0@gmx.com> writes:

> What about replacing it with shorter description?

+1 for making the message shorter,

... and while on it, perhaps also a bit clearer.

Also,

- the key bindings are not propertized, and
- the entire buffer is writable.

> Insert a link.

How about we say "Insert link:" in the minibuffer and drop this sentence
altogether?  Grammatically, the minibuffer prompt would be similar to
'C-x b', which says "Switch to buffer".

> Use TAB to complete link prefixes, then RET for type-specific
> completion support.

How about:

  Type TAB to complete link types, then RET to complete destinations.

> Stored links are available with <up>/<down> or M-p/n (most recent with
> RET):

Could we show the default value in the minibuffer, as

  Insert link (default [...]):

and then drop the "(most recent with RET)" comment?

As for the rest of the message, ... actually let me stop here and zoom
out a bit.  The optimal solution here would be to remove this entire UI
and leverage standard Emacs completions.  Org could simply ask

  Insert link (default [...]):

in the minibuffer and then provide intelligent completions based on the
current input.  If that can be done, then Emacs can handle the rest.  It
can show completion candidates, handle past/future history, and more.

Rudy
-- 
"We shall not cease from exploration
 And the end of all our exploring
 Will be to arrive where we started
 And know the place for the first time"
--- T. S. Eliot, Little Gidding, Four Quarters, 1943

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Consider removing newlines from org-insert-link help message

[Ihor Radchenko]

Rudolf Adamkovič <salutis@me.com> writes:

>> What about replacing it with shorter description?
>
> +1 for making the message shorter,
>
> ... and while on it, perhaps also a bit clearer.

Patches welcome.

> - the key bindings are not propertized, and
> - the entire buffer is writable.

I see no obvious downsides. May as well.

>> Insert a link.
>
> How about we say "Insert link:" in the minibuffer and drop this sentence
> altogether?  Grammatically, the minibuffer prompt would be similar to
> 'C-x b', which says "Switch to buffer".

Currently, the minibuffer message is simply "Link: ". "Insert link:" is
also ok.

>> Use TAB to complete link prefixes, then RET for type-specific
>> completion support.
>
> How about:
>
>   Type TAB to complete link types, then RET to complete destinations.

Maybe "Press" rather than "Type".

>> Stored links are available with <up>/<down> or M-p/n (most recent with
>> RET):
>
> Could we show the default value in the minibuffer, as
>
>   Insert link (default [...]):
>
> and then drop the "(most recent with RET)" comment?

We may, but the default link might sometimes be long. Not sure how it
will look like.

> As for the rest of the message, ... actually let me stop here and zoom
> out a bit.  The optimal solution here would be to remove this entire UI
> and leverage standard Emacs completions.  Org could simply ask
>
>   Insert link (default [...]):
>
> in the minibuffer and then provide intelligent completions based on the
> current input.  If that can be done, then Emacs can handle the rest.  It
> can show completion candidates, handle past/future history, and more.

AFAIK, this is already done. We already use `completing-read'. The UI is
there historically and in addition to the normal Emacs completion.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Consider removing newlines from org-insert-link help message

[Rudolf Adamkovič]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> Patches welcome.

Please, see the attached patch.

> I see no obvious downsides. May as well.

Done.

> Currently, the minibuffer message is simply "Link: ". "Insert link:"
> is also ok.

Done.

> Maybe "Press" rather than "Type".

I went with "Type" to match other Emacs commands.

> We may, but the default link might sometimes be long. Not sure how it
> will look like.

All right, you be the judge.

Personally, I find this UI less disorienting, as opposed to the unclear
comment about RET in the *Org Links* buffer.  And it makes sense, given
I see the "VERB NOUN [default CANDIDATE]: " constantly, all throughout
in Emacs.

> AFAIK, this is already done. We already use `completing-read'. The UI
> is there historically and in addition to the normal Emacs completion.

Gotcha!

(It is quite confusing when using e.g. Vertico, but if we are optimizing
for the default Emacs completion system, then it makes sense.)

Rudy


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-link-Prettify-org-insert-link.patch --]
[-- Type: text/x-patch, Size: 3410 bytes --]

From 7bc8e913af0972f0d6119e45d4ecaf80835f2277 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <salutis@me.com>
Date: Sun, 10 Dec 2023 00:51:31 +0100
Subject: [PATCH] org-link: Prettify 'org-insert-link'

* lisp/ol.el (org-insert-link): Update the UI with text that is (1)
shorter, to avoid line breaks, (2) more standard, to match other Emacs
commands, and (3) more readable, with propertized key bindings.  Also,
show the default link in the minibuffer, as seen elsewhere in Emacs.
---
 lisp/ol.el | 44 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/lisp/ol.el b/lisp/ol.el
index e684b9504..49499e932 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1866,16 +1866,34 @@ non-interactively, don't allow to edit the default description."
       (org-link--fontify-links-to-this-file)
       (org-switch-to-buffer-other-window "*Org Links*")
       (with-current-buffer "*Org Links*"
-	(erase-buffer)
-	(insert "Insert a link.
-Use TAB to complete link prefixes, then RET for type-specific completion support\n")
-	(when org-stored-links
-	  (insert "\nStored links are available with <up>/<down> or M-p/n \
-\(most recent with RET):\n\n")
-	  (insert (mapconcat #'org-link--prettify
-			     (reverse org-stored-links)
-			     "\n")))
-	(goto-char (point-min)))
+        (read-only-mode 1)
+        (let ((inhibit-read-only t)
+              ;; FIXME Duplicate: Also in 'ox.el'.
+              (propertize-help-key
+               (lambda (key)
+                 ;; Add `face' *and* `font-lock-face' to "work
+                 ;; reliably in any buffer", per a comment in
+                 ;; `help--key-description-fontified'.
+                 (propertize key
+                             'font-lock-face 'help-key-binding
+                             'face 'help-key-binding))))
+          (erase-buffer)
+          (insert
+           (apply 'format
+                  (cons "Type %s to complete link type, then %s to complete destination.\n"
+                        (mapcar propertize-help-key
+                                (list "TAB" "RET")))))
+	  (when org-stored-links
+            (insert (apply 'format
+                           (cons "\nStored links accessible with %s/%s or %s/%s are:\n\n"
+                                 (mapcar propertize-help-key
+                                         (list "<up>" "<down>"
+                                               "M-p" "M-n"
+                                               "RET")))))
+	    (insert (mapconcat #'org-link--prettify
+			       (reverse org-stored-links)
+			       "\n"))))
+        (goto-char (point-min)))
       (when (get-buffer-window "*Org Links*" 'visible)
         (let ((cw (selected-window)))
 	  (select-window (get-buffer-window "*Org Links*" 'visible))
@@ -1890,7 +1908,11 @@ Use TAB to complete link prefixes, then RET for type-specific completion support
 			 org-link--insert-history)))
 	    (setq link
 		  (org-completing-read
-		   "Link: "
+                   (concat "Insert link"
+                           (if-let ((default (caar org-stored-links)))
+                               (format " [default %s]" default)
+                             "")
+                           ": ")
 		   (append
 		    (mapcar (lambda (x) (concat x ":")) all-prefixes)
 		    (mapcar #'car org-stored-links)
-- 
2.39.3 (Apple Git-145)


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

-- 
"Music is the mathematics of the sense, mathematics is the music of the
reason."  -- James Joseph Sylvester, 1814-1897

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Consider removing newlines from org-insert-link help message

[Ihor Radchenko]

Rudolf Adamkovič <salutis@me.com> writes:

> From 7bc8e913af0972f0d6119e45d4ecaf80835f2277 Mon Sep 17 00:00:00 2001
> From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <salutis@me.com>
> Date: Sun, 10 Dec 2023 00:51:31 +0100
> Subject: [PATCH] org-link: Prettify 'org-insert-link'
>
> * lisp/ol.el (org-insert-link): Update the UI with text that is (1)
> shorter, to avoid line breaks, (2) more standard, to match other Emacs
> commands, and (3) more readable, with propertized key bindings.  Also,
> show the default link in the minibuffer, as seen elsewhere in Emacs.

Thanks for the update!

> +                   (concat "Insert link"
> +                           (if-let ((default (caar org-stored-links)))
> +                               (format " [default %s]" default)
> +                             "")
> +                           ": ")

You can just use `org-format-prompt'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Consider removing newlines from org-insert-link help message

[Rudolf Adamkovič]

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

Ihor Radchenko <yantar92@posteo.net> writes:

> You can just use `org-format-prompt'.

TIL!  Updated.

Thank you!

P.S. I have also updated the commit message.

Rudy

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-link-Improve-UX-of-org-insert-link.patch --]
[-- Type: text/x-patch, Size: 3299 bytes --]

From aa947b42186fca813d3fcc702f7f5daa554980f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rudolf=20Adamkovi=C4=8D?= <salutis@me.com>
Date: Sun, 10 Dec 2023 00:51:31 +0100
Subject: [PATCH] org-link: Improve UX of 'org-insert-link'

* lisp/ol.el (org-insert-link): Shorten the text in the *Org Links*
buffer to avoid unnecessary line breaks, reword it to better align
with the rest of Emacs, and propertize its key bindings to improve
readability.  Further, move the default link to the minibuffer, as
seen elsewhere in Emacs, and make the *Org Links* buffer read-only.
---
 lisp/ol.el | 40 +++++++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/lisp/ol.el b/lisp/ol.el
index c38a30378..bd89415e8 100644
--- a/lisp/ol.el
+++ b/lisp/ol.el
@@ -1868,16 +1868,34 @@ non-interactively, don't allow to edit the default description."
       (org-link--fontify-links-to-this-file)
       (org-switch-to-buffer-other-window "*Org Links*")
       (with-current-buffer "*Org Links*"
-	(erase-buffer)
-	(insert "Insert a link.
-Use TAB to complete link prefixes, then RET for type-specific completion support\n")
-	(when org-stored-links
-	  (insert "\nStored links are available with <up>/<down> or M-p/n \
-\(most recent with RET):\n\n")
-	  (insert (mapconcat #'org-link--prettify
-			     (reverse org-stored-links)
-			     "\n")))
-	(goto-char (point-min)))
+        (read-only-mode 1)
+        (let ((inhibit-read-only t)
+              ;; FIXME Duplicate: Also in 'ox.el'.
+              (propertize-help-key
+               (lambda (key)
+                 ;; Add `face' *and* `font-lock-face' to "work
+                 ;; reliably in any buffer", per a comment in
+                 ;; `help--key-description-fontified'.
+                 (propertize key
+                             'font-lock-face 'help-key-binding
+                             'face 'help-key-binding))))
+          (erase-buffer)
+          (insert
+           (apply 'format
+                  (cons "Type %s to complete link type, then %s to complete destination.\n"
+                        (mapcar propertize-help-key
+                                (list "TAB" "RET")))))
+	  (when org-stored-links
+            (insert (apply 'format
+                           (cons "\nStored links accessible with %s/%s or %s/%s are:\n\n"
+                                 (mapcar propertize-help-key
+                                         (list "<up>" "<down>"
+                                               "M-p" "M-n"
+                                               "RET")))))
+	    (insert (mapconcat #'org-link--prettify
+			       (reverse org-stored-links)
+			       "\n"))))
+        (goto-char (point-min)))
       (when (get-buffer-window "*Org Links*" 'visible)
         (let ((cw (selected-window)))
 	  (select-window (get-buffer-window "*Org Links*" 'visible))
@@ -1892,7 +1910,7 @@ Use TAB to complete link prefixes, then RET for type-specific completion support
 			 org-link--insert-history)))
 	    (setq link
 		  (org-completing-read
-		   "Link: "
+                   (org-format-prompt "Insert link" (caar org-stored-links))
 		   (append
 		    (mapcar (lambda (x) (concat x ":")) all-prefixes)
 		    (mapcar #'car org-stored-links)
-- 
2.39.3 (Apple Git-145)


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

-- 
"Mathematics takes us still further from what is human into the region
of absolute necessity, to which not only the actual world, but every
possible world, must conform."  --- Bertrand Russell, 1902

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Consider removing newlines from org-insert-link help message

[Ihor Radchenko]

Rudolf Adamkovič <salutis@me.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> You can just use `org-format-prompt'.
>
> TIL!  Updated.
>
> Thank you!
>
> P.S. I have also updated the commit message.

Thanks!
Applied, onto main, with minor amendments.
I have removed redundant `cons' call in the `apply' and added proper
function quoting: #'format.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=664ffde14

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Consider removing newlines from org-insert-link help message

[Rudolf Adamkovič]

Ihor Radchenko <yantar92@posteo.net> writes:

> Thanks! [...] Applied, onto main, with minor amendments.

Thank you, Ihor.

> I have removed redundant `cons' call in the `apply' and added proper
> function quoting: #'format.
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=664ffde14

Eagle eyes; one always learns something new!

Rudy
-- 
“I do not fear death.  I had been dead for billions and billions of years
before I was born, and had not suffered the slightest inconvenience from it.”
--- Mark Twain, paraphrased

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Consider removing newlines from org-insert-link help message

[Salih Muhammed]

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


I see that the text has been updated after updating org at my end,
however, the issue of the stretch persists (see attachment).

My version of org is at 571186631a09262abb58ca395f75b837bbb28888

Org version gives: 9.7-??-5711866


[-- Attachment #2: 2024-01-18_07-06.png --]
[-- Type: image/png, Size: 21068 bytes --]

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

--
Regards,
Salih

Re: Consider removing newlines from org-insert-link help message

[Ihor Radchenko]

Salih Muhammed <lr0@gmx.com> writes:

> I see that the text has been updated after updating org at my end,
> however, the issue of the stretch persists (see attachment).
>
> My version of org is at 571186631a09262abb58ca395f75b837bbb28888
>
> Org version gives: 9.7-??-5711866

Org does not add any extra newlines there. It is likely something about
window size.

From the screenshot, it looks like you use some window management
package or customized your `display-buffer-alist'. This customization is
likely overriding Org mode's call to `fit-window-to-buffer', making the
window appear larger than the containing buffer text.

I may be wrong though. It would help if you try to reproduce the problem
starting from emacs without customization. See
https://orgmode.org/manual/Feedback.html#Feedback

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>