New version of Patch 0002 (documentation patch) attached. Patch 0001
(code patch) is unchanged.
>> None of the above have been obsoleted. Let me know if I should make
>> them all obsolete aliases instead.
>
> I think that an alias is fine.
> At least, it is the approach I am leaning to recently.
Okay, we can obsolete it later if deemed necessary.
>> 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.
>
> ~org-cycle-inline-images-display~ already invokes link previews.
While that's true, link previews don't start new OS processes right now.
They can for custom :preview types.
> You do not have to implement it though. It is slightly out of scope of
> this particular patchset.
Okay, let's leave it out. This patchset has become reasonably large
already.
>> Subject: [PATCH 2/2] Org: Document preview API for arbitrary link types
>> ...
>> ...
>> + By default, only image links without a description are displayed.
>> + You can force displaying previews for all supported links using a
>> + numeric argument of ~1~ to 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.
>
> It is slightly inaccurate I think. Once new :preview handlers are added
> to non-image link types, the same rule about links with/without
> description will apply to non-image links. So, we may better explain C-1
> and C-11 arguments in more generic terms: "image links without
> description" -> "previews for links without description"
Fixed in the the documentation patch.
I have one more question for you:
The overlay property that is used to check if it corresponds to a link
preview is inconsistent with the rest of Org right now. We are checking
for the non-nil overlay property `org-image-overlay'.
1. Should we rename this property to `org-link-preview-overlay', or
`org-link-preview'?
2. Org's LaTeX previews (both the existing and WIP versions) use a
different system. They set two overlay properties: `category' set to
`org', and `org-overlay-type', set to `org-latex-preview'. Should we
use a consistent set of properties to identify Org-related overlays?
This is an implementation detail and none of it really matters, but I
can unify them if required.
If this is not an issue and there's nothing else, I think we are good to
merge.
Karthik
>From 7d4656c3718e303330c02e0025817851d8761b5b Mon Sep 17 00:00:00 2001
From: Karthik Chikmagalur <karthikchikmaga...@gmail.com>
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 | 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 94fabde3b..c94358779 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:
- #+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
+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 right
- ,#+ATTR_ORG: :align center
- [[/path/to/image/file.png]]
+ ,#+ATTR_HTML: :width 300px
#+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.)
-
-#+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:
@@ -21794,6 +21836,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 d8018690f..a033fafcd 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,17 @@ 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 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
@@ -139,6 +172,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.
@@ -163,6 +216,24 @@ accept the INFO channel and return a string. This makes it possible
to dynamically generate the content of the resulting ~<head>~ tag in
the resulting HTML document.
+** 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
