Re: [PATCH v8] Inline image display as part of a new org-link-preview system

[Ihor Radchenko <yantar92@posteo.net>]

Karthik Chikmagalur <karthikchikmagalur@gmail.com> writes:

> 1. Patch 0001 is the code patch from before, with the warnings from make
> addressed.
>
> 2. Patch 0002 is the documentation patch, which adds to ORG-NEWS and the
> manual.  There are two new sections -- one is in the appendix under
> "Hacking", and shows how to add a preview function for a link type
> (along with a code example).

Thanks!
See my comments on the documentation patch below.

> -** Images
> +** Images and link previews
> +
> +Org mode can preview hyperlinks in the buffer as images or with other
> +decorations.

May put a link to [*Hyperlinks] here.

Also, this reads awkward. Maybe something like

    Org mode can display previews of [[*Hyperlinks][hyperlinks]] inside
    Org buffers.  By default, only image links[fn::previews are
    available =file:= and =attachment:= links to image files; Emacs
    should be able to display the linked images (see ~image-types~
    variable)] can be previewed - the images are displayed in place of
    the link path.

    You can customize the previews as described in [*Adding Hyperlink
    preview] section.  The custom previews do not have to display images
    - any kind of [[info:elisp#Overlay Properties][display decoration]]
    can be used.

> +*** External link previews
> +:PROPERTIES:
> +:DESCRIPTION: Preview links in the buffer.
> +:END:
> +
> +Org mode can preview [[* External links][External links]] as inline
> +images or with other decorations.  This requires support for the
> +corresponding link types to be available[fn:: To add support for or to
> +modify how links of a certain type are previewed, see .].  By default
                                                     ^^^^^
> +Org mode includes support for previewing file and attachment links for
> +image files (see [[* Images][Images]]).

The first sentence in the parent section and the first sentence here are
basically identical. As I suggested above, let's move these things
up. (Feel free to modify my version as you see fit.)

> +Supported link types can be previewed within the buffer with the
> +following commands:

If possible, try to use active voice. We are talking to users in the
manual:

   You can preview the supported link types in the whole buffer, in
   current section, region, or at point.

> +  By default, only image links without a description are displayed.
> +  You can force displaying previews for all supported links using
> +  numeric argument to toggle all the images in current section (~1~
> +  argument) or the whole buffer (~11~ argument).

This is not accurate. C-1 argument will act just as no argument: display
links at point/region/section depending on the context.

Looks like the docstring wrt C-1/C-11 args should be improved.

> +  #+vindex: org-startup-with-inline-images
> +  You can ask for inline link previews to be displayed at startup by
> +  configuring the variable ~org-startup-with-inline-images~[fn:: The
> +  variable ~org-startup-with-inline-images~ can be set within a buffer
> +  with the =STARTUP= options =inlineimages= and =noinlineimages=.].

     Org mode can display link previews automatically when opening
     buffers.  Either customize ~org-startup-with-inline-images~ or use
     in-buffer =#+STARTUP: inlineimages= keyword to enable the previews.
     =#+STARTUP: noinlineimages= will disable the previews in specific
     buffer.

Also, since we are generalizing things away from images, maybe we should
introduce some aliases to ~org-startup-with-inline-images~ and to the
startup option values. Something like ~org-startup-with-link-previews~
and similar to startup option.

> +- {{{kbd(C-c C-x C-M-v)}}} (~org-link-preview-refresh~) ::
> +
> +  #+kindex: C-c C-x C-M-v
> +  #+findex: org-link-preview-refresh
> +  Assure inline display of external link previews in the buffer and
> +  refresh them.

"the whole buffer" maybe.

> +Such images can be displayed within the buffer with the
> +~org-link-preview~ and associated command, see [[*External link previews]].

This sentence reads awkwardly after the previous section that already
talked about previews and ~org-link-preview~ command.

We can write

  When [[*External link previews][link previews]] are displayed as
  images, the image size and alignment can be further customized.

>  #+vindex: org-cycle-inline-images-display
>  Inline images can also be displayed when cycling the folding state.
> @@ -21794,6 +21833,65 @@ ** Adding Hyperlink Types
>     topic.  It also provides a default description.  The function
>     ~org-insert-link~ can insert it back into an Org buffer later on.

I suspect that it belongs to the previous section - cycling should work
for all the link previews, not just images.
  
> +2. The value of the =:preview= parameter must be a function that
> +   accepts three arguments:
> +   - an overlay placed from the start to the end of the link,
> +   - the link path, as a string, and
> +   - the link element.

element -> syntax node

> +   It must return a non-nil value to indicate preview success.

... and your example can sometimes return nil, which is confusing.
We should explain what nil means as a return value as well.

> --- a/etc/ORG-NEWS
> +++ b/etc/ORG-NEWS
> @@ -24,26 +24,38 @@ Previously, =C-c C-x C-v= always toggled image display in the whole
>  buffer (or narrowed part of the buffer).  With prefix argument, it
>  also forced displaying image links with description.
> ...
> +2. Otherwise, if there is an image at point, it is toggled.  If there
> +   is no image at point, images in the current entry are previewed

Aside: I am wondering if we should also attach preview toggle to <TAB>
when ~org-cycle-inline-images-display~ is non-nil and there is a link at
point.

> +*** New option ~org-link-preview-batch-size~
> +
> +Org link previews are generated a few at a time, in batches.  This

asynchronously

> +option controls the number of links that are previewed in each batch.
> +
> +*** New option ~org-link-preview-delay~
> +
> +Org link previews are generated asynchronously.  This option controls
> +the minimum idle time in seconds between previews of batches of links.

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