Re: [PATCH v4.0] Re: [PATCH] add a function to only refresh inline images under current headline instead of global buffer

[Karthik Chikmagalur]

> This is not a problem.
> It is possible (and also Elispy) to use advices:
>
> (add-function :before-until (org-link-get-parameter "id" :follow) 
> #'my-function)
>
> We may want to document this fact better though.

I've noticed that org-link-parameters that are functions, like the
:follow, :export and :activate-func parameters, are given very specific
arguments.  For example:

`:activate-func'

  Function to run at the end of Font Lock activation.  It must
  accept four arguments:
  - the buffer position at the start of the link,
  - the buffer position at its end,
  - the path, as a string,
  - a boolean, non-nil when the link has brackets.

This is even though these functions can gather any information about the
link using org-element.  This suggests that we have something specific
in mind for what these functions should do.  Along the same lines, my
plan is to add a :preview (or :preview-func) parameter that looks like
this:

`:preview'

  Function to run when generating an in-buffer preview for the
  link.  It must accept two arguments:
  - an overlay placed from the start to the end of the link.
  - the path, as a string.

(I can add more arguments if it proves necessary.)

The idea is that the preview function can specify an image as the
overlay's display property, or add some other overlay property with
suitable content.  For example, for notmuch links you could specify a
before-string that adds relevant metadata from the email that's not part
of the link path, like a date/sender.

My question is: is it okay to assume that preview actions for all link
types should work by placing an overlay over the link?  Or is it too
restrictive to pass an overlay?  A more general version could leave it
to the :preview function to create the overlay, or preview it in some
other way entirely, such as by adding text properties instead of an
overlay.

One reason I would like to restrict it to an overlay is that I think a
:preview feature should not modify the buffer in any way, as adding text
properties will.

Karthik