Re: org-insert-link completion by description (Re: what is the purpose of "This link has already been stored"?)

[Ihor Radchenko]

Samuel Wales <samologist@gmail.com> writes:

>>> this buffer contains nothing useful and shortens the above buffer.
>>
>> This is fine. I assume that you can simply hide it away using
>> `display-buffer-alist'.
>
> i have struggled with this in a wider context and gotten nowhere for years.

(add-to-list
 'display-buffer-alist
 `("*Org Links*" display-buffer-no-window (allow-no-window . t)))

You may also find
https://www.masteringemacs.org/article/demystifying-emacs-window-manager
and
https://www.gnu.org/software/emacs/manual/html_node/elisp/The-Zen-of-Buffer-Display.html
useful.

>> Org shows link prefixes, stored links, and link description in the
>> completion. The relevant code in `org-insert-link' is:
>
> what is the purpose of the prefixes?

When inserting a link, you do not always need to insert a stored link.
Various link types can have completion function specific to a link type.
For example, I arranged my id: links to use org-ql for completion. That
way I can insert id: links searching across all the agenda files via
org-ql.

> where is the description in this case?  was it a bare link?  that is
> unusual for an id link.

>> (org-completing-read
>>                 "Link: "
>>                 (append
>>                  (mapcar (lambda (x) (concat x ":")) all-prefixes)

The above corresponds to link prefixes.

>>                  (mapcar #'car org-stored-links)

Each element of `org-stored-links' is (path description).
car in org-stored-links elements are bare links (link path).

>>                     ;; Allow description completion.  Avoid "nil" option
>>                     ;; in the case of `completing-read-default' and
>>                     ;; an error in `ido-completing-read' when some links
>>                     ;; have no description.
>>                     (delq nil (mapcar 'cadr org-stored-links)))

cadr in org-stored-links elements are descriptions.

So, the completion should offer (1) all the link types; (2) all the link
paths; (3) all the link descriptions.

You can try to run this code manually to see.
You can also remove different parts in the (append ...) to experiment.

>> Completing descriptions feature has been added by Max 10 months ago - it
>> is a fairly recent addition:
>
> please note that it is of course not my intention to criticize anybody
> or anybody's code.  merely saying what i need.  max is trying to be
> helpful.  iu am not even sure how we got on this topic as my original
> report was the already stored bug.

That's not a problem. We already changed the subject of this spin-off
thread. The original bug report is separate.

> in the context of mindless store/insert, which is what i do most
> frequently, if the most recently stored is set to the completion
> default, this topic is moot as presumably others agree this is
> desirable.  in the context of choosing a different link from the
> default, the short url-like prefixes being there in front of specific
> links confuses me.

So, your suggestion is to move link descriptions and paths before the
link types in the completion list?

> then there is the more fancy question of grabbing random links from
> all over your org files in order to paste them all in one place which
> i will not cover here.

I hope that M-x org-insert-all-links caters this need.

>> This commit is a part of Org 9.6.
>> May it be that you are using older Org version?
>
> 9.6.7, most recent bugfix.  comments apply to vanilla.

May you please elaborate what you mean by "comments apply to vanilla"?

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