On Thu, 8 Feb 2024, at 1:02 PM, Ihor Radchenko wrote:
> I have some thoughts about rewording your changes to the manual and
> ORG-NEWS. See the attached patch on top of yours.

Thanks, makes sense -- wasn't sure whether to keep this as a separate patch or not, I have squashed into the attached updated version.

> [minor points on commit messages]

Fixed these.

> The new optional argument to a public function should be announced in ORG-NEWS.

Added.

>> +             (new-heading-level (if new-heading-container
>> +                                    (+ 1 (org-element-property :level new-heading-container))
>
> What if new-heading-container is not a heading?
>
>> +                                  1)))
>> +        (goto-char new-heading-position)
>
> This is err when container ends after narrowed region boundary.

Added checks for these.

>> +(defun org-link-precise-link-target ()
>> ...
>> +              (cond
>> +               (name
>> +                (list name
>> +                      name
>> +                      (org-element-begin element)))
>
> It would make sense to use #+caption as default description when available.

Maybe... But I had a little look and it seems complicated, since caption is a parsed property, it's not clear to me how to get a plain string in a simple way. And there could be a long and a short caption, over multiple lines. If the caption is long, it wouldn't make a good link description anyway.

The current behaviour is the same as it was before, so maybe we can leave this as a future enhancement if wanted?