Link preview generation with new link preview property

Link preview generation with new link preview property

[Björn Bidar]

Hello,

I have a few question regarding the new link preview handler property
added recently. I ported the org-remoteimg package to it which was quite
easy, much cleaner with the new property.

The PR do port the package to this new handler property:
https://github.com/gaoDean/org-remoteimg/pull/4

However it left me with a few questions:
- Who is supposed to take care of the scaling/width of the preview
  image, the handler or the caller of the handler?
- When calling the link preview function for a description with prefix
  argument 1 I noticed that it doesn't get the contents of the
  description.
  Why is that? In this instance the link looked like this:
  [[https://stable.melpa.org/#/rpm-spec-mode][file:https://stable.melpa.org/packages/rpm-spec-mode-badge.svg]]

Thanks have a great day,

Björn

Re: Link preview generation with new link preview property

[Karthik Chikmagalur]

> The PR do port the package to this new handler property:
> https://github.com/gaoDean/org-remoteimg/pull/4
>
> However it left me with a few questions:
> - Who is supposed to take care of the scaling/width of the preview
>   image, the handler or the caller of the handler?

The handler is responsible for sizing the image.  The reason for this is
that the preview does not have to be an image -- it can be any kind of
overlay decoration.

If you decide to use an image file as the preview, you can call
`org-link-preview-file' inside your handler to handle the geometry for
you.  This includes the size and alignment specified by #+attr_*
keywords, `org-image-max-width' and `org-image-align'.

If you are using a preview image from image data, you'll have to copy
some of the code in `org-link-preview-file' to your handler if you want
to respect these user options.

> - When calling the link preview function for a description with prefix
>   argument 1 I noticed that it doesn't get the contents of the
>   description.
>   Why is that? In this instance the link looked like this:
>   [[https://stable.melpa.org/#/rpm-spec-mode][file:https://stable.melpa.org/packages/rpm-spec-mode-badge.svg]]

I don't follow.  What do you mean by "it doesn't get the contents"?  Did
the preview work as expected when you used a prefix arg of 1?

Karthik

Re: Link preview generation with new link preview property

[Björn Bidar]

Karthik Chikmagalur <karthikchikmagalur@gmail.com> writes:

>> The PR do port the package to this new handler property:
>> https://github.com/gaoDean/org-remoteimg/pull/4
>>
>> However it left me with a few questions:
>> - Who is supposed to take care of the scaling/width of the preview
>>   image, the handler or the caller of the handler?
>
> The handler is responsible for sizing the image.  The reason for this is
> that the preview does not have to be an image -- it can be any kind of
> overlay decoration.
>
> If you decide to use an image file as the preview, you can call
> `org-link-preview-file' inside your handler to handle the geometry for
> you.  This includes the size and alignment specified by #+attr_*
> keywords, `org-image-max-width' and `org-image-align'.
>
> If you are using a preview image from image data, you'll have to copy
> some of the code in `org-link-preview-file' to your handler if you want
> to respect these user options.

Would it be possible to also handle image data in the function or
refactor the org-link-preview-file function in a way that the geometry
handling is done in a helper function which can be reused by other
handlers.

In the example I mentioned it should be possible to use the cached file
from the url cache but that might be not so easy in other cases.

>> - When calling the link preview function for a description with prefix
>>   argument 1 I noticed that it doesn't get the contents of the
>>   description.
>>   Why is that? In this instance the link looked like this:
>>   [[https://stable.melpa.org/#/rpm-spec-mode][file:https://stable.melpa.org/packages/rpm-spec-mode-badge.svg]]
>
> I don't follow.  What do you mean by "it doesn't get the contents"?  Did
> the preview work as expected when you used a prefix arg of 1?

The link element passed towards the handler didn't contain the
description e.g. in this case file:https://stable.melpa.org/packages/rpm-spec-mode-badge.svg.

Re: Link preview generation with new link preview property

[Ihor Radchenko]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Would it be possible to also handle image data in the function or
> refactor the org-link-preview-file function in a way that the geometry
> handling is done in a helper function which can be reused by other
> handlers.

There is such function: `org-display-inline-image--width'.
We may consider exposing it as public function.

> The link element passed towards the handler didn't contain the
> description e.g. in this case file:https://stable.melpa.org/packages/rpm-spec-mode-badge.svg.

This is expected. See https://orgmode.org/worg/dev/org-element-api.html#org22c967a
You can access the contents by looking at buffer text between
:contents-begin and :contents-end. Either directly, or by invoking
sub-parser on the text.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: Link preview generation with new link preview property

[Björn Bidar]

Ihor Radchenko <yantar92@posteo.net> writes:

> Björn Bidar <bjorn.bidar@thaodan.de> writes:
>
>> Would it be possible to also handle image data in the function or
>> refactor the org-link-preview-file function in a way that the geometry
>> handling is done in a helper function which can be reused by other
>> handlers.
>
> There is such function: `org-display-inline-image--width'.
> We may consider exposing it as public function.

That would be awesome, the easier it is for other modes to add their own
handlers and them to survive org-mode updates.
Although for this http link handler it could be better a function inside org-mode.

>> The link element passed towards the handler didn't contain the
>> description e.g. in this case file:https://stable.melpa.org/packages/rpm-spec-mode-badge.svg.
>
> This is expected. See https://orgmode.org/worg/dev/org-element-api.html#org22c967a
> You can access the contents by looking at buffer text between
> :contents-begin and :contents-end. Either directly, or by invoking
> sub-parser on the text.

Oh thanks, will look into that. Is there a offline version of the manual
like the org info manual? 
 

Re: Link preview generation with new link preview property

[Karthik Chikmagalur]

>> Would it be possible to also handle image data in the function or
>> refactor the org-link-preview-file function in a way that the geometry
>> handling is done in a helper function which can be reused by other
>> handlers.
>
> There is such function: `org-display-inline-image--width'.
> We may consider exposing it as public function.

This will not be enough, we will also have to expose `org-image--align'
and the alignment code:

(when align
  (overlay-put
   ov 'before-string
   (propertize
    " " 'face 'default
    'display
    (pcase align
      ("center" `(space :align-to (- center (0.5 . ,image))))
      ("right"  `(space :align-to (- right ,image)))))))

I don't think we can expect third party packages to figure out and
reimplement Org's image alignment logic.

Considering this, it might be better to just split
`org-link-preview-file' into two public functions, where the "inside"
function accepts an image instead of a file.

Karthik

Re: Link preview generation with new link preview property

[Ihor Radchenko]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

>> This is expected. See https://orgmode.org/worg/dev/org-element-api.html#org22c967a
>> You can access the contents by looking at buffer text between
>> :contents-begin and :contents-end. Either directly, or by invoking
>> sub-parser on the text.
>
> Oh thanks, will look into that. Is there a offline version of the manual
> like the org info manual? 

Nothing shipped with Org distribution.
But you can always clone WORG - it is mostly a collection of .org files.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: Link preview generation with new link preview property

[Ihor Radchenko]

Karthik Chikmagalur <karthikchikmagalur@gmail.com> writes:

> ...
> Considering this, it might be better to just split
> `org-link-preview-file' into two public functions, where the "inside"
> function accepts an image instead of a file.

Agree.
Would you be interested to create a patch?

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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: Link preview generation with new link preview property

[stardiviner]

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

I don't think so, my package org-link-beautify ported to the new
:preview mechanism. The file preview not always image. Could be text, or
icon etc. So pass in image object is not a good idea. It will limit
preview functionality extensibility.

[stardiviner]           <Hack this world!>      GPG key ID: 47C32433
IRC(freeenode): stardiviner                     Twitter:  @numbchild
Key fingerprint = 9BAA 92BC CDDD B9EF 3B36  CB99 B8C4 B8E5 47C3 2433
Blog: http://stardiviner.github.io/


On Tue, Dec 17, 2024 at 11:43 AM Karthik Chikmagalur <
karthikchikmagalur@gmail.com> wrote:

> >> Would it be possible to also handle image data in the function or
> >> refactor the org-link-preview-file function in a way that the geometry
> >> handling is done in a helper function which can be reused by other
> >> handlers.
> >
> > There is such function: `org-display-inline-image--width'.
> > We may consider exposing it as public function.
>
> This will not be enough, we will also have to expose `org-image--align'
> and the alignment code:
>
> (when align
>   (overlay-put
>    ov 'before-string
>    (propertize
>     " " 'face 'default
>     'display
>     (pcase align
>       ("center" `(space :align-to (- center (0.5 . ,image))))
>       ("right"  `(space :align-to (- right ,image)))))))
>
> I don't think we can expect third party packages to figure out and
> reimplement Org's image alignment logic.
>
> Considering this, it might be better to just split
> `org-link-preview-file' into two public functions, where the "inside"
> function accepts an image instead of a file.
>
> Karthik
>
>

[-- Attachment #2: Type: text/html, Size: 2425 bytes --]

Re: Link preview generation with new link preview property

[Karthik Chikmagalur]

> I don't think so, my package org-link-beautify ported to the new
> :preview mechanism. The file preview not always image. Could be text, or
> icon etc. So pass in image object is not a good idea. It will limit
> preview functionality extensibility.

The API will not be changed.  Org will provide a new
`org-link-preview-image' function that you can use to preview links
using image data.  You'll have to write the adapter to register this as
the :preview handler for a link type yourself.

Karthik