From 6715b431e6e4f4d419be6f180a6ac2937fa2bd46 Mon Sep 17 00:00:00 2001 From: Karthik Chikmagalur Date: Sun, 27 Oct 2024 20:22:59 -0700 Subject: [PATCH 2/2] Org: Document preview API for arbitrary link types * etc/ORG-NEWS: Mention new commands and options for link preview. * doc/org-manual.org: Add sections on - previewing external links (Images and link previews), and - adding the link preview feature to other link types (Adding Hyperlink preview). --- doc/org-manual.org | 276 ++++++++++++++++++++++++++++++--------------- etc/ORG-NEWS | 74 ++++++++++-- 2 files changed, 250 insertions(+), 100 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 94fabde3b..84e1619a0 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -11778,7 +11778,67 @@ ** Literal Examples the end of the current line. Then the label is stored as a link =(label)=, for retrieval with {{{kbd(C-c C-l)}}}. -** Images +** Images and link previews + +Org mode can preview hyperlinks in the buffer as images or with other +decorations. + +*** 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]]). + +Supported link types can be previewed within the buffer with the +following commands: + +- {{{kbd(C-c C-x C-v)}}} (~org-link-preview~) :: + + #+kindex: C-c C-x C-v + #+findex: org-link-preview + Create inline previews for external links in the active region, the + link at point or in the current section. With a prefix argument, + clear link previews at point or in the current entry. With a double + prefix argument, preview all links in the buffer. With triple + prefix argument, hide previews for all links in the buffer. + + 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). + + #+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=.]. + +- {{{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. + +- (~org-link-preview-region~) :: + + #+findex: org-link-preview-region + Create inline previews for external links in the active region, or + the buffer. With a prefix argument, also preview links with a text + description part. + +- (~org-link-preview-clear~) :: + + #+findex: org-link-preview-clear + Clear external link previews in the active region, or the buffer. + +*** Images :PROPERTIES: :DESCRIPTION: Display an image. :END: @@ -11803,97 +11863,76 @@ ** Images [[./img/a.jpg]] #+end_example -Such images can be displayed within the buffer with the following -command: - -- {{{kbd(C-c C-x C-v)}}} (~org-toggle-inline-images-command~) :: - - #+kindex: C-c C-x C-v - #+findex: org-toggle-inline-images-command - Toggle the inline display of linked images in current section or at - point. With a prefix argument, toggle inline images in the whole - buffer. With double prefix argument, hide all the images in buffer. - - By default, only the image links without description are displayed. - You can force displaying all the images using numeric argument to - toggle all the images in current section (~1~ argument) or the whole - buffer (~11~ argument). - - #+vindex: org-startup-with-inline-images - You can ask for inline images 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=.]. - - - #+vindex: org-image-actual-width - #+vindex: org-image-max-width - #+cindex: @samp{ORG-IMAGE-ACTUAL-WIDTH}, property - By default, Org mode displays inline images according to their - actual width, but no wider than ~fill-column~ characters. - - You can customize the displayed image width using - ~org-image-actual-width~ variable (globally) or - =ORG-IMAGE-ACTUAL-WIDTH= property (subtree-level)[fn:: The width can - be customized in Emacs >= 24.1, built with ImageMagick support.]. - Their value can be the following: - - (default) Non-~nil~, use the actual width of images when inlining - them. If the actual width is too wide, limit it according to - ~org-image-max-width~. - - When set to a number, use ImageMagick (when available) to set the - image's width to this value. - - When set to a number in a list, try to get the width from any - =#+ATTR.*= keyword if it matches a width specification like: - #+begin_example - ,#+ATTR_HTML: :width 300px - #+end_example - and fall back on that number if none is found. - - When set to ~nil~, try to get the width from an =#+ATTR.*= keyword - and fall back on the original width or ~org-image-max-width~ if - none is found. - - ~org-image-max-width~ limits the maximum displayed image width, but - only when the image width is not set explicitly. Possible maximum - width can be set to: - - (default) ~fill-column~, limit width to ~fill-column~ number of - characters. - - ~window~, limit width to current window width. - - integer number, limit width to that specified number of pixels. - - ~nil~, do not limit the width. - - #+vindex: org-image-align - Org mode can left-align, center or right-align the display of inline - images. This setting is controlled (globally) by ~org-image-align~. - Only standalone images are affected, corresponding to links with no - surrounding text in their paragraph except for whitespace. Its - value can be the following: - - (default) The symbol ~left~, which inserts the image where the - link appears in the buffer. - - The symbol ~center~, which will preview links centered in the - Emacs window. - - The symbol ~right~, which will preview links right-aligned in the - Emacs window. - - Inline image alignment can be specified for each link using the - =#+ATTR.*= keyword if it matches an alignment specification like: +Such images can be displayed within the buffer with the +~org-link-preview~ and associated command, see [[*External link previews]]. + +#+vindex: org-image-actual-width +#+vindex: org-image-max-width +#+cindex: @samp{ORG-IMAGE-ACTUAL-WIDTH}, property +By default, Org mode displays inline images according to their +actual width, but no wider than ~fill-column~ characters. + +You can customize the displayed image width using +~org-image-actual-width~ variable (globally) or +=ORG-IMAGE-ACTUAL-WIDTH= property (subtree-level)[fn:: The width can +be customized in Emacs >= 24.1, built with ImageMagick support.]. +Their value can be the following: +- (default) Non-~nil~, use the actual width of images when inlining + them. If the actual width is too wide, limit it according to + ~org-image-max-width~. +- When set to a number, use ImageMagick (when available) to set the + image's width to this value. +- When set to a number in a list, try to get the width from any + =#+ATTR.*= keyword if it matches a width specification like: #+begin_example - ,#+ATTR_HTML: :align center + ,#+ATTR_HTML: :width 300px #+end_example - Org will use the alignment specification from any =#+ATTR.*= - keyword, such as =#+ATTR_HTML= or =#+ATTR_LATEX=, but =#+ATTR_ORG= - (if present) will override the others. For instance, this link - #+begin_example - ,#+ATTR_HTML: :align right - ,#+ATTR_ORG: :align center - [[/path/to/image/file.png]] - #+end_example - will be displayed centered in Emacs but exported right-aligned to - HTML. + and fall back on that number if none is found. +- When set to ~nil~, try to get the width from an =#+ATTR.*= keyword + and fall back on the original width or ~org-image-max-width~ if + none is found. + +~org-image-max-width~ limits the maximum displayed image width, but +only when the image width is not set explicitly. Possible maximum +width can be set to: +- (default) ~fill-column~, limit width to ~fill-column~ number of + characters. +- ~window~, limit width to current window width. +- integer number, limit width to that specified number of pixels. +- ~nil~, do not limit the width. + +#+vindex: org-image-align +Org mode can left-align, center or right-align the display of inline +images. This setting is controlled (globally) by ~org-image-align~. +Only standalone images are affected, corresponding to links with no +surrounding text in their paragraph except for whitespace. Its +value can be the following: +- (default) The symbol ~left~, which inserts the image where the + link appears in the buffer. +- The symbol ~center~, which will preview links centered in the + Emacs window. +- The symbol ~right~, which will preview links right-aligned in the + Emacs window. + +Inline image alignment can be specified for each link using the +=#+ATTR.*= keyword if it matches an alignment specification like: +#+begin_example +,#+ATTR_HTML: :align center +#+end_example +Org will use the alignment specification from any =#+ATTR.*= +keyword, such as =#+ATTR_HTML= or =#+ATTR_LATEX=, but =#+ATTR_ORG= +(if present) will override the others. For instance, this link +#+begin_example +,#+ATTR_HTML: :align right +,#+ATTR_ORG: :align center +[[/path/to/image/file.png]] +#+end_example +will be displayed centered in Emacs but exported right-aligned to +HTML. - When =#+ATTR_ORG= is not set, inline image alignment is also read - from the =:center= attribute supported by some export backends (like - HTML, LaTeX and Beamer.) +When =#+ATTR_ORG= is not set, inline image alignment is also read from +the =:center= attribute supported by some export backends (like HTML, +LaTeX and Beamer.) #+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. +** Adding Hyperlink preview +:PROPERTIES: +:DESCRIPTION: Preview behavior for new hyperlink types. +:END: +#+cindex: hyperlinks, adding preview behavior + +By default, Org supports previewing external links for links ot type +=file= and =attachment= that point to image files. (See [[*Images]].) + +Support for previewing other link types inline can be added to Org in +the following way: + +1. Add a =:preview= link parameter to the link type using + ~org-link-set-parameters~. As an example, here we add previews for + the =docview= link type. + + #+begin_src emacs-lisp +(org-link-set-parameters + "docview" :preview #'org-link-docview-preview) + #+end_src + +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. + It must return a non-nil value to indicate preview success. + + In our example, we use the =convert= program (part of the + =imagemagick= suite of tools) to create the thumbnail that is + displayed inline. + + #+begin_src emacs-lisp +(defun org-link-docview-preview (ov path _elem) + "Preview file at PATH in overlay OV. + +_ELEM is the link element." + (when (executable-find "convert") + (let* ((path (expand-file-name (substitute-in-file-name path))) + (output-file (expand-file-name (concat "org-docview-preview-" + (substring (sha1 path) 0 10) + ".png") + temporary-file-directory))) + ;; Create or find preview for path + (when (or (file-readable-p output-file) + (= 0 (call-process + "convert" + nil (get-buffer-create "*Org Docview Preview Output*") nil + "-thumbnail" "x320" "-colorspace" "rgb" + "-background" "white" "-alpha" "remove" "-strip" + (concat path "[0]") output-file))) + ;; If preview image is available, display it via the overlay + (overlay-put ov 'display (create-image output-file)))))) + #+end_src + +3. Now previews of docview links for supported document types (PDF, + djvu) are generated (along with image file previews) when calling + ~org-link-preview~. + ** Adding Export Backends :PROPERTIES: :DESCRIPTION: How to write new export backends. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index d8018690f..f03043518 100644 --- 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. -Now, =C-c C-x C-v= is bound to a new command -~org-toggle-inline-images-command~, which uses different defaults: +Now, =C-c C-x C-v= is bound to a new command ~org-link-preview~, which +uses different defaults: -1. By default, it toggles image at point or, if there is no image at - point, images in current entry +1. When the region is active, images in the region are previewed -2. When region is active, it is honored +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 -3. =C-u= argument changed its meaning. Now, it forces toggling images - in the whole buffer +3. With the =C-u= argument, image previews in the active region or at + point are cleared instead -4. =C-u C-u= argument unconditionally hides all the images in buffer +4. The =C-u C-u= argument unconditionally shows all images in the + accessible portion of the buffer -5. Displaying images over links with description can be forced using +5. The =C-u C-u C-u= argument unconditionally clears all images in the + accessible portion of the buffer + +6. Displaying images over links with description can be forced using numeric argument: - ~C-u 1~ for toggling all images at point/current entry - ~C-u 11~ for toggling all images in buffer -The old ~org-toggle-inline-images~ command is still available. You -can bind it back to =C-c C-x C-v= by adding the following to you config: +(The first five of these prefix arg behaviors are the same as that of +the ~org-latex-preview~ command.) + +In addition to images, ~org-link-preview~ can also be used to preview +Org links of all types for which preview behavior is defined, see +[[#link-preview][previews for arbitrary link types]]. + +The old ~org-toggle-inline-images~ command is obsolete but still +available. You can bind it back to =C-c C-x C-v= by adding the +following to your config: #+begin_src emacs-lisp (eval-after-load 'org-keys (org-defkey org-mode-map (kbd "C-c C-x C-v") #'org-toggle-inline-images)) @@ -76,6 +88,16 @@ now have diary timestamps included as well. # We list the most important features, and the features that may # require user action to be used. +*** All Org link types can be previewed +:PROPERTIES: +:CUSTOM_ID: link-preview +:END: + +Org links support a new parameter =:preview= that can be used to +preview arbitrary link types. The value of this parameter should be a +function that is called to preview links of the corresponding type +(see ~org-link-parameters~). + *** Alignment of image previews can be customized This is not a new feature. It has been added in Org 9.7, but not @@ -97,6 +119,16 @@ or newer. # adding new customizations, or changing the interpretation of the # existing customizations. +*** New option ~org-link-preview-batch-size~ + +Org link previews are generated a few at a time, in batches. This +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. + *** Allow disabling macro replacement during export New custom option ~org-export-replace-macros~ controls whether Org @@ -139,6 +171,26 @@ bibliography format requires them to be written in title-case. # This also includes changes in function behavior from Elisp perspective. +*** New command ~org-link-preview~ to preview Org links + +This command replaces ~org-toggle-inline-images~, which is now +obsolete. + +*** New command ~org-link-preview-region~ to preview Org links in a region or the buffer + +This command replaces ~org-display-inline-images~, which is now +obsolete. + +*** New command ~org-link-preview-clear~ to clear Org link previews in a region or the buffer + +This command replaces ~org-remove-inline-images~, which is now +obsolete. + +*** New command ~org-link-preview-refresh~ to refresh Org link previews in the buffer + +This command replaces ~org-redisplay-inline-images~, which is now +obsolete. + *** ob-sqlite: Added ability to open a database in readonly mode Added option :readonly to ob-sqlite. -- 2.46.1