New patches attached. >> -** 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. Done. > 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. Done. >> +*** 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.) This is the new organization: --8<---------------cut here---------------start------------->8--- * Images and link previews [Explanation of link previews and org-link-preview] ** Images [Image-preview-specific options] --8<---------------cut here---------------end--------------->8--- The section "External link previews" is gone, moved up into the parent. >> +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. Used active voice. >> + 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. Improved both in the manual and in the command documentation in ol.el. > 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. Okay. I've added `org-startup-with-link-previews' and the "linkpreview", "nolinkpreview" STARTUP options. `org-startup-with-inline-images' is an alias to the new variable, and the "inlineimages" and "noinlineimages" options are still respected. There are two other changes. In org-cycle, I've renamed `org-cycle-inline-images-display' and `org-cycle-display-inline-images' to `org-cycle-link-previews-display' and `org-cycle-display-link-previews'. The older user option and function are aliased to the new ones. There are new entries in ORG-NEWS documenting these renames. None of the above have been obsoleted. Let me know if I should make them all obsolete aliases instead. >> +- {{{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. Done. >> +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. Done. >> #+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. Done. >> +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 Done. >> + 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. Done. >> --- 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 > when ~org-cycle-inline-images-display~ is non-nil and there is a link at > point. I haven't added this. I think it's better not to do this, since cycling is expected to only involve hiding/showing buffer contents. Generating a preview might cause new external processes to be started. I can add it if you think we should. >> +*** New option ~org-link-preview-batch-size~ >> + >> +Org link previews are generated a few at a time, in batches. This > > asynchronously Done, both in the manual and in the variable docstring. Karthik