From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id QPTBDqVJIWc16wAA62LTzQ:P1 (envelope-from ) for ; Tue, 29 Oct 2024 20:46:29 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id QPTBDqVJIWc16wAA62LTzQ (envelope-from ) for ; Tue, 29 Oct 2024 21:46:29 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="YtOY//L0"; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" ARC-Seal: i=1; s=key1; d=yhetil.org; t=1730234789; a=rsa-sha256; cv=none; b=hIIzdHTKgAfRqwrq7EfJV89j9YxClWWAkwP1wf2tvPHDOFGrDQJEgLtXb3+xH4WEuud5Yo TDhFNtcv4zB2h9/PmaoZLbWCDexmpB6xSPezfTlHsZKErtZwQZZsNzaDCB1sT3nW14VH/S MjPFZxFgCWFpWA5/ZxbXhZ+HrjkQ6NdtYizKRCWjKY6YBP7SzAIadt00OkJCj+nKxWFLOf v3t3ZLcyhVCDu0pE+xp8bD7CdBL19ReVWfLpIeJOMsjlFkvrTj90UeeysZ4ntqGClrHgqG rIagoHwWKTTIsrQQbebpeWbTl09a+tA/2LtYGQQCq06mzjpe1bdlkszJNcj6HA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="YtOY//L0"; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1730234789; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=uS31LF3Uw+bFVlEzjNkSEfFbsDsP2OstUvvOKqZUPz8=; b=o+Pqmc4X499RM9TKaZO0Zd4TT87jH5rO0A4tYWO75hHU4OhwbqrZC+zBhlrulvfT/k5e70 eFy2bY2i9y6M1j15yp4kFtnJApQlMAi4A7y/UA9hQpFReob6XUWgd8cBB7v+XPhfe7rksR laSOK7JRdEi9t8c7zaZ4uczAhDH6eEoQ4aU1u8zCdSfTd+cTCIzq6SMhv8AnbGdKB+LAYs S1wRD8dF0n1ec7d1bbkAHLpGMFrEIioxtqRkP+wQfuWkzfvMVChMMEIfaARvvpYw6YrIRy NbQZZuVlAdtU/2SHOsWIeOKfM/C//nRlTQjuwcIvSgtoUPY81iI5auxoPSbIjA== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 8322444E1 for ; Tue, 29 Oct 2024 21:46:28 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1t5t62-0000TJ-I6; Tue, 29 Oct 2024 16:45:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t5t5s-0000Se-09 for emacs-orgmode@gnu.org; Tue, 29 Oct 2024 16:45:39 -0400 Received: from mail-pj1-x1035.google.com ([2607:f8b0:4864:20::1035]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1t5t5o-0004TW-T3 for emacs-orgmode@gnu.org; Tue, 29 Oct 2024 16:45:35 -0400 Received: by mail-pj1-x1035.google.com with SMTP id 98e67ed59e1d1-2e2bd347124so4560290a91.1 for ; Tue, 29 Oct 2024 13:45:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1730234730; x=1730839530; darn=gnu.org; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc:subject:date:message-id:reply-to; bh=uS31LF3Uw+bFVlEzjNkSEfFbsDsP2OstUvvOKqZUPz8=; b=YtOY//L0RWFydueyKJIFDnWOcKwR4hsX5HfqV2l6DX/vLh1vVvz68AYnS7XnPyXhTu AX0TMmIA9DHnH6Am9r0iKlKxaQbdTjYoNF1Ox7k5DYLKq+xStn1OtGDl/Lu9bFYK5yfL ZPBLGWYhRnfnEOcAEP1ZrHE+QQsloCpHSx9F1yIUpHqdKdsMxneO89ALRH8YbpUWZXdJ yNbmS2w4zChvBaDmxf6WwK4vqNY9SRNNe2U7LBaDp2C7nk7rWzlac3CTxbKPAyW98wT6 YIfKiQjhDPQZUjqzOPMr1tR8nXp95h+uKTibmXXut1iUvaTQ+M/YTWBv/9KkH1Xx1VAt CyiQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1730234730; x=1730839530; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=uS31LF3Uw+bFVlEzjNkSEfFbsDsP2OstUvvOKqZUPz8=; b=W1MPLna13bc7JeuEbKDvxxH6UK767Ju2GtdY2NBciGhCgj1ZCTtQrTUZetafOkYWog lXuqhObS0Wh77zpUfJzOlg2p9lrWQn47mnz+4e+ujnszIJQoXis2unvHUL80rm6+GB5g aaGerzmFnaLmlX4F/0Qj5hUGkn+beG62fzekjpAexZFXdr2p6iidiLmXETNnsTRJWtig rs5647D6fcgZtuszlFX5SVa2+7AtTV3aEmlhalB94jS7KckcO5uF07Wqh0NXihzJXnbn 2Byjh8dOYGwupCSLL3aaoATwZATD9i6zH1pL6yKqtJZSCsCxWWWJL7vZXu98tMj6+f2J aRLg== X-Forwarded-Encrypted: i=1; AJvYcCWyXjmYmHEEmiq2Jw23Wz1yLjgMy+t3ZY+aWjcXTp03civPF+SJIK2+VOrWrB+uNuQek/VLb3EQaErzSCpA@gnu.org X-Gm-Message-State: AOJu0YxJKzTjt3+/1mFdQLqp5972qsYg8umjOgHM5BGd+zD4FP1mKbXZ QggBSnfEkRldf+iBt5oXkjuK85KRQ2lSvODxtWJmjbhZ24x+7Ccg X-Google-Smtp-Source: AGHT+IEuZplhc5PgUea0iDY8uAX7BkuliZBOh2EwgNGYw7CAbtDMfZA9lTMWQA6bC2pcWIFtstneAQ== X-Received: by 2002:a17:90b:3003:b0:2e2:c6a6:84da with SMTP id 98e67ed59e1d1-2e8f11dcd91mr15083004a91.34.1730234729513; Tue, 29 Oct 2024 13:45:29 -0700 (PDT) Received: from localhost (c-73-92-213-61.hsd1.ca.comcast.net. [73.92.213.61]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2e92fc01360sm14619a91.55.2024.10.29.13.45.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 29 Oct 2024 13:45:28 -0700 (PDT) From: Karthik Chikmagalur To: Ihor Radchenko Cc: stardiviner , Org mode Subject: Re: [PATCH v10] Inline image display as part of a new org-link-preview system In-Reply-To: <877c9qeohj.fsf@localhost> References: <6461a84b.a70a0220.b6d36.5d00@mx.google.com> <87h6b09v4o.fsf@gmail.com> <878qwb8qw1.fsf@localhost> <878qw9ak6a.fsf@gmail.com> <87o74ypp3b.fsf@localhost> <87r09rxpjg.fsf@gmail.com> <87h6ah72ui.fsf@localhost> <8734m060ma.fsf@gmail.com> <87o74mjgcy.fsf@localhost> <8734lx4twk.fsf@gmail.com> <87bk0hs4dm.fsf@localhost> <87tte7wdpj.fsf@gmail.com> <87y135ce4g.fsf@localhost> <87cykbfodz.fsf@gmail.com> <87r08nkhfg.fsf@localhost> <874j5jfy8y.fsf@gmail.com> <875xpxu47h.fsf@localhost> <87h68weovw.fsf@gmail.com> <875xpcks8a.fsf@localhost> <87a5enevy5.fsf@gmail.com> <877c9qeohj.fsf@localhost> Date: Tue, 29 Oct 2024 13:45:27 -0700 Message-ID: <87msimtz88.fsf@gmail.com> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=2607:f8b0:4864:20::1035; envelope-from=karthikchikmagalur@gmail.com; helo=mail-pj1-x1035.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -0.01 X-Spam-Score: -0.01 X-Migadu-Queue-Id: 8322444E1 X-Migadu-Scanner: mx12.migadu.com X-TUID: BeU4HABlV/WP --=-=-= Content-Type: text/plain 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 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0002-Org-Document-preview-API-for-arbitrary-link-types.patch >From 7d4656c3718e303330c02e0025817851d8761b5b 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 | 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 ~~ 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 --=-=-=--