From 3fb7dcff71e0786770230c69cea8550270412ecc Mon Sep 17 00:00:00 2001 From: Karthik Chikmagalur Date: Sun, 24 Nov 2024 19:14:28 -0800 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 | 291 ++++++++++++++++++++++++++++++--------------- etc/ORG-NEWS | 93 +++++++++++++-- 2 files changed, 279 insertions(+), 105 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 451fd72cd..e904b27db 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -11778,7 +11778,75 @@ ** 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 +:PROPERTIES: +:DESCRIPTION: Preview links in the buffer. +:END: + +Org mode can display previews of [[*Hyperlinks][hyperlinks]] inside Org buffers. By +default, only image links[fn::Image links are =file:= and +=attachment:= links to existing image files; Emacs should be able to +display the linked images (see ~image-types~ variable)] can be +previewed inline, where the images are displayed in place of the link +path. + +You can customize the previews as described in the [[*Adding Hyperlink +preview]] section. Link previews do not have to display images -- any +kind of [[info:elisp#Overlay Properties][display decoration]] can be used. + +You can preview the supported link types in the whole buffer, in the +current section, active region or at point 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 links without descriptions are previewed. You + can force displaying previews for all supported links (including + links with descriptions) using a numeric argument of ~1~. This + will toggle all previews in the active region, the link at point + or the current section. A numeric prefix argument of ~11~ will + toggle previews in the whole buffer instead. + + #+vindex: org-startup-with-link-previews + Org mode can display link previews automatically when opening + buffers. Either customize ~org-startup-with-link-previews~ or use + the =#+STARTUP: linkpreviews= keyword to enable previews for that + specific buffer when opening it. =#+STARTUP: nolinkpreviews= will + disable previews on startup in the buffer. + +- {{{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 whole 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. + +#+vindex: org-cycle-inline-images-display +Link previews can also be displayed when cycling the folding state. +When the custom option ~org-cycle-link-previews-display~ is set, +supported link types under the subtree (including images) will be +displayed automatically. + +*** Images :PROPERTIES: :DESCRIPTION: Display an image. :END: @@ -11803,102 +11871,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: +When [[*Images and link previews][link previews]] are displayed as images, the image size and +alignment can be further customized. + +#+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. - - 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.) + 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. -#+vindex: org-cycle-inline-images-display -Inline images can also be displayed when cycling the folding state. -When custom option ~org-cycle-inline-images-display~ is set, the -visible inline images under subtree will be displayed automatically. +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.) ** Captions :PROPERTIES: @@ -21837,6 +21879,67 @@ ** 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 syntax node for the link. + It must return a non-nil value to indicate preview success. A + value of =nil= implies that the preview failed, and the overlay + placed on the link will be removed. + + 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 syntax node of 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 92bfe3501..08857962b 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 @@ -120,6 +142,17 @@ See the new [[info:org#Repeating commands]["Repeating commands"]] section in Org # adding new customizations, or changing the interpretation of the # existing customizations. +*** New option ~org-link-preview-batch-size~ + +Org link previews are generated asynchronously and 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 @@ -162,6 +195,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. @@ -204,6 +257,24 @@ leave extra prompts after evaluation, and skipping the prompt filtering can be more robust for such languages (as this avoids removing false positive prompts). +** Removed or renamed functions and variables + +*** ~org-cycle-display-inline-images~ is renamed to ~org-cycle-display-link-previews~ + +Inline image previews in Org mode are now provided by the more general +link previews feature. The behavior with regards to image links is +unchanged. + +*** ~org-cycle-inline-images-display~ is renamed to ~org-cycle-link-previews-display~ + +The behavior is unchanged, except in that the new variable now affects +previews of supported link types besides image links. + +*** ~org-startup-with-inline-images~ is renamed to ~org-startup-with-link-previews~ + +The behavior is unchanged, except in that the new variable now affects +previews of supported link types besides image links. + ** Miscellaneous *** Org mode no longer prevents =flyspell= from spell-checking inside =LOGBOOK= drawers -- 2.46.1