From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.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 UIk4G8QXRmfVzAAAqHPOHw:P1 (envelope-from ) for ; Tue, 26 Nov 2024 18:47:32 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id UIk4G8QXRmfVzAAAqHPOHw (envelope-from ) for ; Tue, 26 Nov 2024 19:47:32 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=gmail.com header.s=20230601 header.b=lO3RGUjr; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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=1732646852; a=rsa-sha256; cv=none; b=r5WMDErWNabcCqt16D+zqx8WIBHj+dUIupilbXtXrSOilduDJJB75iFNUyXFMKmdjZXi6i ROOqocVYu4ozs0io5bqbmwSYKgFxpx5biS75U8BSuuI7hlZnEKmfcgISQhScJEIjuPVrf/ HTCQfPX+vWU348/mZVtpreMmBaFUUDMhTaztitMU6XnuoouHOXroF4S+92JbhdgPOhwvWq J6+kTkVPrkkMm6/75Ij63bcK33xjaQ5bLfgFWQOLgazcLV9wv0aSii3y1/dol/3eDN37cE xPy+GBa3D3OTGxaLQLU3UQmwVzX7KGkUVG/dFVeuBP+AyCLr2AKE5k3f28p1Rw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=gmail.com header.s=20230601 header.b=lO3RGUjr; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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=1732646852; 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=uGefw2VsVw7nlgwHBz9RFl5PmxEuduEHqNF0ak+/pqk=; b=bS/wWxa+MkvJrPxJAnnH41C8NrSO4WYESVnOKvy+ne8Zu2Uh2n0eqkEWrGPcMVXsnr9TqR LXO5IyVXvozZ4iq5r1vOjYptHatdTSmf6Z705pcM5WfAJ4fvSqz/t4Yb9CKCoKLmZ0PRNN +8zRrlgAHzwXpl1LqiAMrTMqw3p5U3f7DRh/qhDQ/eKJzsYPy2IMBoRBDPVbbk1252YUf0 4vHpQuxaKzvdCYpYA/IT9pBl5avt2m3RRurC7tMKHwyLqOKlEJPBV+bmPL49k8i5/UtsnK 4/yk5mLl/J/0YYuadH93oY9GI8z/qoTiRsLmoERbXlxiK+XO4lDOxzOJZgkyqg== 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 504368B180 for ; Tue, 26 Nov 2024 19:47:30 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tG0Zm-0005hm-5i; Tue, 26 Nov 2024 13:46:18 -0500 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 1tG0Zd-0005gg-OC for emacs-orgmode@gnu.org; Tue, 26 Nov 2024 13:46:10 -0500 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 1tG0ZW-0007mS-JU for emacs-orgmode@gnu.org; Tue, 26 Nov 2024 13:46:09 -0500 Received: by mail-pj1-x1035.google.com with SMTP id 98e67ed59e1d1-2ea1e605193so5046919a91.0 for ; Tue, 26 Nov 2024 10:46:01 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1732646760; x=1733251560; 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=Mee+yevNglUOg2n+Bb0MZxex0mOVimRrm8f0ziRUtzI=; b=lO3RGUjrrvJPSl5WcCkRgx5foP2omDdrjC4VnHZJcyZiGeuCN1v2e36IMmooezorqi bYGm/W7rSVhP4MkLQ9H9pvtMckgyt+Vw9aZ7T+J1AFPbwj5dFiXKyuT5z2kI1+ip1+OA 8HJ6xPgf46y9zSY2FZsd3RJ7cvKss6KonRtVxU6wufzWxZZMYwOnnwQ0XaZ+lMeJjKj9 UcqSYwL5YZzkrEfCkfAW69SMkwQBEHcv7YGOWNK4e/eTdiFskWUVs9Q4UfrqDNFV7o7b bvopyzSOLhNevn+zveuF2Bj+wTvugsUQpWDBhJ20khSnsMTQbMrGpwJXLM1G5Ga/YNMj bKAg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1732646760; x=1733251560; 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=Mee+yevNglUOg2n+Bb0MZxex0mOVimRrm8f0ziRUtzI=; b=T0Vtin/InMiPrmjcrA2JIgg8D47Yn5mq3mRvhswO0Y7E9HeJSLtbUZZIO5BbF23SL6 9qhBb266Q/shCZlzodBJJDhhL5qDdZWjgUGlBv1JhIiR+U4rQ5cHB4oiEhVBu8+MwqcR 4HNWO9NMfOCJMmoMvwBGg/DDBv5kScVBAdEnoH925gTzBRC5vV6BgZxiI4PDclzXcxRQ 4DwomBKQjzbrEmLh36Vu+jNCse+nrYzL0PidZ9R28DnEqSIYO2Dbgk/UshNkIJuEl9pa yZROQQcccvxpD6inJkrIDFuOQoXYZWwpeHbbaNY2MiO1uRemC+sDLx8umI/Y9rtiJAwW V30g== X-Forwarded-Encrypted: i=1; AJvYcCU9xmBSTpHj1tlmCVhGp3JGUKzKgLwsU9I8iTAXQuyooDUCKsVaGMu23TNXKPETJFouYevJxhb66gXhTdGC@gnu.org X-Gm-Message-State: AOJu0YwlZc8aROzJsQ5V6WtAn3aakt2pK/xaTNUBl6WT6G+sksEWDbTT 7csdTvzUyE9j8XdVQeqApGRTaxYghicy/uhjfU0KE6ss0FDndVZr X-Gm-Gg: ASbGnct7mLHozRmK4dTqiYgjxUV2K2rsBBpct2WWJX0SY4r8YeAzFQiNwhhxQCOMmPq TONCf/FzqqXHqbntksMMbr1D03YpgeWzZfGgPLeu12ef0i+es7JxATkLCBYv8Rii4erxeZ2+3K9 BdUkLGCZRoqAOrXgi7ri6+DSxvp9bq00ZXwESBSJ4sX+JArns9O8XosDJEwP1KypuhJT9cekgdF 8xN/J5xQYD7zzQOsxJDSS6f+SDAnm7P/uuImxKfnewNM6crqzNXPAmvf2V5BkY= X-Google-Smtp-Source: AGHT+IGJHGkn+sw0hY96PVDazDUC14ib8grAOtwFm5Y0l0kplxlp2PghWSWEVo3/cIj0UkNUUmK9Mg== X-Received: by 2002:a17:90b:4d0d:b0:2ea:a25d:3baa with SMTP id 98e67ed59e1d1-2ee08e5bad3mr409042a91.5.1732646760151; Tue, 26 Nov 2024 10:46:00 -0800 (PST) Received: from localhost ([2600:8802:5726:2500:7900:ffb8:b27c:275b]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2ead02ea3e9sm12775712a91.4.2024.11.26.10.45.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 26 Nov 2024 10:45:59 -0800 (PST) From: Karthik Chikmagalur To: Ihor Radchenko Cc: stardiviner , Org mode Subject: Re: [PATCH v12] Inline image display as part of a new org-link-preview system In-Reply-To: <87iks9opl9.fsf@localhost> References: <6461a84b.a70a0220.b6d36.5d00@mx.google.com> <874j5jfy8y.fsf@gmail.com> <875xpxu47h.fsf@localhost> <87h68weovw.fsf@gmail.com> <875xpcks8a.fsf@localhost> <87a5enevy5.fsf@gmail.com> <877c9qeohj.fsf@localhost> <87msimtz88.fsf@gmail.com> <87plnh7azl.fsf@localhost> <87v7x9z7y6.fsf@gmail.com> <87cyjgcf48.fsf@localhost> <87iksqmktm.fsf@gmail.com> <87msi1eo07.fsf@localhost> <87frntmpq4.fsf@gmail.com> <87r075ckql.fsf@gmail.com> <87a5dq9bt9.fsf@localhost> <87bjy4c895.fsf@gmail.com> <87jzcri3pe.fsf@localhost> <87r06yvm1g.fsf@gmail.com> <87bjy1q5fz.fsf@localhost> <87iks9opl9.fsf@localhost> Date: Tue, 26 Nov 2024 10:45:58 -0800 Message-ID: <87ldx5vno9.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: -1.04 X-Spam-Score: -1.04 X-Migadu-Queue-Id: 504368B180 X-Migadu-Scanner: mx12.migadu.com X-TUID: habJbRw77Yon --=-=-= Content-Type: text/plain >> Oops. My patch happens to be exactly the opposite of my changes. (I >> chose wrong direction of the diff range) > > Here is the correct diff. Applied diff and rebased onto main. Karthik --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-org-link-Customizable-preview-API-for-arbitrary-link.patch >From eedcba143b72abdaa93e34d1356616012141c7f4 Mon Sep 17 00:00:00 2001 From: Karthik Chikmagalur Date: Fri, 23 Aug 2024 15:46:53 -0700 Subject: [PATCH 1/2] org-link: Customizable preview API for arbitrary link types Add a customizable preview API for arbitrary link types. Make inline image previews a part of the more universal org-link preview feature. Each link type can now be previewed differently based on a new link parameter. * lisp/ol.el (org-link-parameters, org-link-preview-batch-size, org-link-preview-delay, org-link-preview--timer, org-link-preview--queue, org-link-preview-overlays, org-link-preview--get-overlays, org-link-preview--remove-overlay, org-link-preview, org-link-preview-region, org-link-preview--process-queue, org-link-preview-clear, org-link-preview-file, org-display-remote-inline-images, org-image-align, org--create-inline-image, org-display-inline-image--width, org-image--align): Add new commands `org-link-preview', `org-link-preview-region' and `org-link-preview-clear' for creating link previews for any kind of link. Add new org-link parameter `:preview' for specifying how a link type should be previewed. This link parameter is a function called asynchronously to place previes. File links and attachments are previewed using inline image previews as before. Move image handling utilities from lisp/org.el to lisp/ol.el. * testing/lisp/test-org-fold.el: Use `org-link-preview'. * lisp/org.el (org-toggle-inline-images, org-toggle-inline-images-command, org-display-inline-images, org--inline-image-overlays, org-inline-image-overlays, org-redisplay-inline-images, org-image-align, org-display-inline-remove-overlay, org-remove-inline-images, org-startup-with-inline-images, org-startup-with-link-previews, org-startup-options): Obsolete and move `org-toggle-inline-images', `org-display-inline-images' and `org-redisplay-inline-images' to org-compat. These are obsoleted by `org-link-preview' and `org-link-preview-region'. Remove `org-toggle-inline-images-command'. Move the other internal functions to org-link. Rename `org-startup-with-inline-images' to `org-startup-with-link-previews'. Add new STARTUP options for link previews to `org-startup-options': "linkpreviews" and "nolinkpreviews". * lisp/org-plot.el (org-plot/redisplay-img-in-buffer): Modify to use `org-link-preview'. * lisp/org-keys.el: Bind `C-c C-x C-v' to new command `org-link-preview', which has the same prefix arg behaviors as `org-latex-preview'. In addition to these, it supports numeric prefix args 1 and 11 to preview links with descriptions at point/region (with 1) and across the buffer (with 11). * lisp/org-cycle.el (org-cycle-display-inline-images, org-cycle-display-link-previews, org-cycle-inline-images-display, org-cycle-inline-link-previews): Use `org-link-preview' and `org-link-preview-region'. Rename inline-images functions and user options to their link-previews equivalents: - `org-cycle-display-inline-images' to `org-cycle-display-link-previews' - `org-cycle-inline-images-display' to `org-cycle-inline-link-previews' * lisp/org-compat.el (org-display-inline-remove-overlay, org--inline-image-overlays, org-remove-inline-images, org-inline-image-overlays, org-display-inline-images, org-toggle-inline-images): * lisp/org-attach.el (org-attach-preview-file): Add new `:preview' link parameter for links of type "attachment", set to the new function `org-attach-preview-file'. --- lisp/ol.el | 603 +++++++++++++++++++++++++++++++++- lisp/org-attach.el | 11 +- lisp/org-compat.el | 185 +++++++++++ lisp/org-cycle.el | 31 +- lisp/org-keys.el | 7 +- lisp/org-plot.el | 2 +- lisp/org.el | 554 +------------------------------ testing/lisp/test-org-fold.el | 4 +- 8 files changed, 839 insertions(+), 558 deletions(-) diff --git a/lisp/ol.el b/lisp/ol.el index ea01e2254..032610bad 100644 --- a/lisp/ol.el +++ b/lisp/ol.el @@ -82,6 +82,11 @@ (declare-function org-src-source-buffer "org-src" ()) (declare-function org-src-source-type "org-src" ()) (declare-function org-time-stamp-format "org" (&optional long inactive)) (declare-function outline-next-heading "outline" ()) +(declare-function image-flush "image" (spec &optional frame)) +(declare-function org-entry-end-position "org" ()) +(declare-function org-element-contents-begin "org-element" (node)) +(declare-function org-element-contents-end "org-element" (node)) +(declare-function org-property-or-variable-value "org" (var &optional inherit)) ;;; Customization @@ -171,6 +176,18 @@ (defcustom org-link-parameters nil The default face is `org-link'. +`:preview' + + Function to run to generate an in-buffer preview for the link. It + must accept three arguments: + - an overlay placed from the start to the end of the link + - the link path, as a string + - the syntax node for the link + + This function must return a non-nil value to indicate success. + A return value of nil implies that the preview failed, and the + overlay placed on the link will be removed. + `:help-echo' String or function used as a value for the `help-echo' text @@ -521,6 +538,81 @@ (defcustom org-link-keep-stored-after-insertion nil :type 'boolean :safe #'booleanp) +(defcustom org-link-preview-delay 0.05 + "Idle delay in seconds between link previews when using +`org-link-preview'. Links are previewed in batches (see +`org-link-preview-batch-size') spaced out by this delay. Set +this to a small number for more immediate previews, but at the +expense of higher lag." + :group 'org-link + :type 'number) + +(defcustom org-link-preview-batch-size 6 + "Number of links that are previewed at once with +`org-link-preview'. Links are previewed asynchronously, in +batches spaced out in time (see `org-link-preview-delay'). Set +this to a large integer for more immediate previews, but at the +expense of higher lag." + :group 'org-link + :type 'natnum) + +(defcustom org-display-remote-inline-images 'skip + "How to display remote inline images. +Possible values of this option are: + +skip Don't display remote images. +download Always download and display remote images. +t +cache Display remote images, and open them in separate buffers + for caching. Silently update the image buffer when a file + change is detected." + :group 'org-appearance + :package-version '(Org . "9.7") + :type '(choice + (const :tag "Ignore remote images" skip) + (const :tag "Always display remote images" download) + (const :tag "Display and silently update remote images" cache)) + :safe #'symbolp) + +(defcustom org-image-max-width 'fill-column + "When non-nil, limit the displayed image width. +This setting only takes effect when `org-image-actual-width' is set to +t or when #+ATTR* is set to t. + +Possible values: +- `fill-column' :: limit width to `fill-column' +- `window' :: limit width to window width +- integer :: limit width to number in pixels +- float :: limit width to that fraction of window width +- nil :: do not limit image width" + :group 'org-appearance + :package-version '(Org . "9.7") + :type '(choice + (const :tag "Do not limit image width" nil) + (const :tag "Limit to `fill-column'" fill-column) + (const :tag "Limit to window width" window) + (integer :tag "Limit to a number of pixels") + (float :tag "Limit to a fraction of window width"))) + +(defcustom org-image-align 'left + "How to align images previewed using `org-link-preview-region'. + +Only stand-alone image links are affected by this setting. These +are links without surrounding text. + +Possible values of this option are: + +left Insert image at specified position. +center Center image previews. +right Right-align image previews." + :group 'org-appearance + :package-version '(Org . "9.7") + :type '(choice + (const :tag "Left align (or don\\='t align) image previews" left) + (const :tag "Center image previews" center) + (const :tag "Right align image previews" right)) + :safe #'symbolp) + ;;; Public variables (defconst org-target-regexp (let ((border "[^<>\n\r \t]")) @@ -649,6 +741,29 @@ (defvar org-link--insert-history nil (defvar org-link--search-failed nil "Non-nil when last link search failed.") +(defvar-local org-link-preview-overlays nil) +;; Preserve when switching modes or when restarting Org. +;; If we clear the overlay list and later enable Or mode, the existing +;; image overlays will never be cleared by `org-link-preview' +;; and `org-link-preview-clear'. +(put 'org-link-preview-overlays 'permanent-local t) + +(defvar-local org-link-preview--timer nil + "Timer for previewing Org links in buffer. + +This timer creates previews for specs in +`org-link-preview--queue'.") + +(defvar-local org-link-preview--queue nil + "Queue of pending previews for Org links in buffer. + +Each element of this queue is a list of the form + +(PREVIEW-FUNC OVERLAY PATH LINK) + +where PREVIEW-FUNC places a preview of PATH using OVERLAY. LINK +is the Org element being previewed.") + ;;; Internal Functions @@ -881,7 +996,227 @@ (defun org-link--file-link-to-here () (setq desc search-desc)))) (cons link desc))) +(defun org-link-preview--get-overlays (&optional beg end) + "Return link preview overlays between BEG and END." + (let* ((beg (or beg (point-min))) + (end (or end (point-max))) + (overlays (overlays-in beg end)) + result) + (dolist (ov overlays result) + (when (memq ov org-link-preview-overlays) + (push ov result))))) + +(defun org-link-preview--remove-overlay (ov after _beg _end &optional _len) + "Remove link-preview overlay OV if a corresponding region is modified. + +AFTER is true when this function is called post-change." + (when (and ov after) + (setq org-link-preview-overlays (delq ov org-link-preview-overlays)) + ;; Clear image from cache to avoid image not updating upon + ;; changing on disk. See Emacs bug#59902. + (when-let* ((disp (overlay-get ov 'display)) + ((imagep disp))) + (image-flush disp)) + (delete-overlay ov))) + + +;;;; Utilities for image preview display + +;; For without-x builds. +(declare-function image-flush "image" (spec &optional frame)) + +(defun org--create-inline-image (file width) + "Create image located at FILE, or return nil. +WIDTH is the width of the image. The image may not be created +according to the value of `org-display-remote-inline-images'." + (let* ((remote? (file-remote-p file)) + (file-or-data + (pcase org-display-remote-inline-images + ((guard (not remote?)) file) + (`download (with-temp-buffer + (set-buffer-multibyte nil) + (insert-file-contents-literally file) + (buffer-string))) + ((or `cache `t) + (let ((revert-without-query '("."))) + (with-current-buffer (find-file-noselect file) + (buffer-string)))) + (`skip nil) + (other + (message "Invalid value of `org-display-remote-inline-images': %S" + other) + nil)))) + (when file-or-data + (create-image file-or-data + (and (image-type-available-p 'imagemagick) + width + 'imagemagick) + remote? + :width width + :max-width + (pcase org-image-max-width + (`fill-column (* fill-column (frame-char-width (selected-frame)))) + (`window (window-width nil t)) + ((pred integerp) org-image-max-width) + ((pred floatp) (floor (* org-image-max-width (window-width nil t)))) + (`nil nil) + (_ (error "Unsupported value of `org-image-max-width': %S" + org-image-max-width))) + :scale 1)))) + +(declare-function org-export-read-attribute "ox" + (attribute element &optional property)) +(defvar visual-fill-column-width) ; Silence compiler warning +(defun org-display-inline-image--width (link) + "Determine the display width of the image LINK, in pixels. +- When `org-image-actual-width' is t, the image's pixel width is used. +- When `org-image-actual-width' is a number, that value will is used. +- When `org-image-actual-width' is nil or a list, :width attribute of + #+attr_org or the first #+attr_... (if it exists) is used to set the + image width. A width of X% is divided by 100. If the value is a + float between 0 and 2, it interpreted as that proportion of the text + width in the buffer. + + If no :width attribute is given and `org-image-actual-width' is a + list with a number as the car, then that number is used as the + default value." + ;; Apply `org-image-actual-width' specifications. + ;; Support subtree-level property "ORG-IMAGE-ACTUAL-WIDTH" specified + ;; width. + (let ((org-image-actual-width (org-property-or-variable-value 'org-image-actual-width))) + (cond + ((eq org-image-actual-width t) nil) + ((listp org-image-actual-width) + (require 'ox) + (let* ((par (org-element-lineage link 'paragraph)) + ;; Try to find an attribute providing a :width. + ;; #+ATTR_ORG: :width ... + (attr-width (org-export-read-attribute :attr_org par :width)) + (width-unreadable? + (lambda (value) + (or (not (stringp value)) + (unless (string= value "t") + (or (not (string-match + (rx bos (opt "+") + (or + ;; Number of pixels + ;; must be a lone number, not + ;; things like 4in + (seq (1+ (in "0-9")) eos) + ;; Numbers ending with % + (seq (1+ (in "0-9.")) (group-n 1 "%")) + ;; Fractions + (seq (0+ (in "0-9")) "." (1+ (in "0-9"))))) + value)) + (let ((number (string-to-number value))) + (and (floatp number) + (not (match-string 1 value)) ; X% + (not (<= 0.0 number 2.0))))))))) + ;; #+ATTR_BACKEND: :width ... + (attr-other + (catch :found + (org-element-properties-map + (lambda (prop _) + (when (and + (not (eq prop :attr_org)) + (string-match-p "^:attr_" (symbol-name prop)) + (not (funcall width-unreadable? (org-export-read-attribute prop par :width)))) + (throw :found prop))) + par))) + (attr-width + (if (not (funcall width-unreadable? attr-width)) + attr-width + ;; When #+attr_org: does not have readable :width + (and attr-other + (org-export-read-attribute attr-other par :width)))) + (width + (cond + ;; Treat :width t as if `org-image-actual-width' were t. + ((string= attr-width "t") nil) + ;; Fallback to `org-image-actual-width' if no interprable width is given. + ((funcall width-unreadable? attr-width) + (car org-image-actual-width)) + ;; Convert numeric widths to numbers, converting percentages. + ((string-match-p "\\`[[+]?[0-9.]+%" attr-width) + (/ (string-to-number attr-width) 100.0)) + (t (string-to-number attr-width))))) + (if (and (floatp width) (<= 0.0 width 2.0)) + ;; A float in [0,2] should be interpereted as this portion of + ;; the text width in the window. This works well with cases like + ;; #+attr_latex: :width 0.X\{line,page,column,etc.}width, + ;; as the "0.X" is pulled out as a float. We use 2 as the upper + ;; bound as cases such as 1.2\linewidth are feasible. + (round (* width + (window-pixel-width) + (/ (or (and (bound-and-true-p visual-fill-column-mode) + (or visual-fill-column-width auto-fill-function)) + (when auto-fill-function fill-column) + (- (window-text-width) (line-number-display-width))) + (float (window-total-width))))) + width))) + ((numberp org-image-actual-width) + org-image-actual-width) + (t nil)))) + +(defun org-image--align (link) + "Determine the alignment of the image LINK. +LINK is a link object. + +In decreasing order of priority, this is controlled: +- Per image by the value of `:center' or `:align' in the +affiliated keyword `#+attr_org'. +- By the `#+attr_html' or `#+attr_latex` keywords with valid + `:center' or `:align' values. +- Globally by the user option `org-image-align'. + +The result is either nil or one of the strings \"left\", +\"center\" or \"right\". + +\"center\" will cause the image preview to be centered, \"right\" +will cause it to be right-aligned. A value of \"left\" or nil +implies no special alignment." + (let ((par (org-element-lineage link 'paragraph))) + ;; Only align when image is not surrounded by paragraph text: + (when (and par ; when image is not in paragraph, but in table/headline/etc, do not align + (= (org-element-begin link) + (save-excursion + (goto-char (org-element-contents-begin par)) + (skip-chars-forward "\t ") + (point))) ;account for leading space + ;before link + (<= (- (org-element-contents-end par) + (org-element-end link)) + 1)) ;account for trailing newline + ;at end of paragraph + (save-match-data + ;; Look for a valid ":center t" or ":align left|center|right" + ;; attribute. + ;; + ;; An attr_org keyword has the highest priority, with + ;; any attr.* next. Choosing between these is + ;; unspecified. + (let ((center-re ":\\(center\\)[[:space:]]+t\\b") + (align-re ":align[[:space:]]+\\(left\\|center\\|right\\)\\b") + attr-align) + (catch 'exit + (org-element-properties-mapc + (lambda (propname propval) + (when (and propval + (string-match-p ":attr.*" (symbol-name propname))) + (setq propval (car-safe propval)) + (when (or (string-match center-re propval) + (string-match align-re propval)) + (setq attr-align (match-string 1 propval)) + (when (eq propname :attr_org) + (throw 'exit t))))) + par)) + (if attr-align + (when (member attr-align '("center" "right")) attr-align) + ;; No image-specific keyword, check global alignment property + (when (memq org-image-align '(center right)) + (symbol-name org-image-align)))))))) + ;;; Public API (defun org-link-types () @@ -1573,6 +1908,231 @@ (defun org-link-add-angle-brackets (s) (unless (equal (substring s -1) ">") (setq s (concat s ">"))) s) +;;;###autoload +(defun org-link-preview (&optional arg beg end) + "Toggle display of link previews in the buffer. + +When region BEG..END is active, preview links in the +region. + +When point is at a link, display a preview for that link only. +Otherwise, display previews for links in current entry. + +With numeric prefix ARG 1, also preview links with description in +the active region, at point or in the current section. + +With prefix ARG `\\[universal-argument]', clear link previews at +point or in the current entry. + +With prefix ARG `\\[universal-argument] \\[universal-argument]', + display link previews in the accessible portion of the + buffer. With numeric prefix ARG 11, do the same, but include + links with descriptions. + +With prefix ARG `\\[universal-argument] \\[universal-argument] \\[universal-argument]', +hide all link previews in the accessible portion of the buffer. + +This command is designed for interactive use. From Elisp, you can +also use `org-link-preview-region'." + (interactive (cons current-prefix-arg + (when (use-region-p) + (list (region-beginning) (region-end))))) + (let* ((include-linked + (cond + ((member arg '(nil (4) (16)) ) nil) + ((member arg '(1 11)) 'include-linked) + (t 'include-linked))) + (interactive? (called-interactively-p 'any)) + (toggle-previews + (lambda (&optional beg end scope remove) + (let* ((beg (or beg (point-min))) + (end (or end (point-max))) + (old (org-link-preview--get-overlays beg end)) + (scope (or scope (format "%d:%d" beg end)))) + (if remove + (progn + (org-link-preview-clear beg end) + (when interactive? + (message + "[%s] Inline link previews turned off (removed %d images)" + scope (length old)))) + (org-link-preview-region include-linked t beg end) + (when interactive? + (let ((new (org-link-preview--get-overlays beg end))) + (message + (if new + (format "[%s] Displaying %d images inline %s" + scope (length new) + (if include-linked "(including images with description)" + "")) + (format "[%s] No images to display inline" scope)))))))))) + (cond + ;; Region selected :: display previews in region. + ((and beg end) + (funcall toggle-previews beg end "region" + (and (equal arg '(4)) 'remove))) + ;; C-u argument: clear image at point or in entry + ((equal arg '(4)) + (if-let ((ov (cdr (get-char-property-and-overlay + (point) 'org-image-overlay)))) + ;; clear link preview at point + (funcall toggle-previews + (overlay-start ov) (overlay-end ov) + "preview at point" 'remove) + ;; Clear link previews in entry + (funcall toggle-previews + (if (org-before-first-heading-p) (point-min) + (save-excursion + (org-with-limited-levels (org-back-to-heading t) (point)))) + (org-with-limited-levels (org-entry-end-position)) + "current section" 'remove))) + ;; C-u C-u or C-11 argument :: display images in the whole buffer. + ((member arg '(11 (16))) (funcall toggle-previews nil nil "buffer")) + ;; C-u C-u C-u argument :: unconditionally hide images in the buffer. + ((equal arg '(64)) (funcall toggle-previews nil nil "buffer" 'remove)) + ;; Argument nil or 1, no region selected :: display images in + ;; current section or image link at point. + ((and (member arg '(nil 1)) (null beg) (null end)) + (let ((context (org-element-context))) + ;; toggle display of inline image link at point. + (if (org-element-type-p context 'link) + (let* ((ov (cdr-safe (get-char-property-and-overlay + (point) 'org-image-overlay))) + (remove? (and ov (memq ov org-link-preview-overlays) + 'remove))) + (funcall toggle-previews + (org-element-begin context) + (org-element-end context) + "image at point" remove?)) + (let ((beg (if (org-before-first-heading-p) (point-min) + (save-excursion + (org-with-limited-levels (org-back-to-heading t) (point))))) + (end (org-with-limited-levels (org-entry-end-position)))) + (funcall toggle-previews beg end "current section"))))) + ;; Any other non-nil argument. + ((not (null arg)) (funcall toggle-previews beg end "region"))))) + +;;;###autoload +(defun org-link-preview-refresh () + "Assure display of link previews in buffer and refresh them." + (interactive) + (org-link-preview-region nil t (point-min) (point-max))) + +(defun org-link-preview-region (&optional include-linked refresh beg end) + "Display link previews. + +A previewable link type is one that has a `:preview' link +parameter, see `org-link-parameters'. + +By default, a file link or attachment is previewable if it +follows either of these conventions: + + 1. Its path is a file with an extension matching return value + from `image-file-name-regexp' and it has no contents. + + 2. Its description consists in a single link of the previous + type. In this case, that link must be a well-formed plain + or angle link, i.e., it must have an explicit \"file\" or + \"attachment\" type. + +File links are equipped with the keymap `image-map'. + +When optional argument INCLUDE-LINKED is non-nil, links with a +text description part will also be inlined. This can be nice for +a quick look at those images, but it does not reflect what +exported files will look like. + +When optional argument REFRESH is non-nil, refresh existing +images between BEG and END. This will create new image displays +only if necessary. + +BEG and END define the considered part. They default to the +buffer boundaries with possible narrowing." + (interactive "P") + (when refresh (org-link-preview-clear beg end)) + (org-with-point-at (or beg (point-min)) + (let ((case-fold-search t) + preview-queue) + ;; Collect links to preview + (while (re-search-forward org-link-any-re end t) + (forward-char -1) ;ensure we are on the link + (when-let* + ((link (org-element-lineage (org-element-context) 'link t)) + (linktype (org-element-property :type link)) + (preview-func (org-link-get-parameter linktype :preview)) + (path (and (or include-linked + (not (org-element-contents-begin link))) + (org-element-property :path link)))) + ;; Create an overlay to hold the preview + (let ((ov (make-overlay + (org-element-begin link) + (progn + (goto-char + (org-element-end link)) + (unless (eolp) (skip-chars-backward " \t")) + (point))))) + (overlay-put ov 'modification-hooks + (list 'org-link-preview--remove-overlay)) + (push ov org-link-preview-overlays) + (push (list preview-func ov path link) preview-queue)))) + ;; Collect previews in buffer-local LIFO preview queue + (setq org-link-preview--queue + (nconc (nreverse preview-queue) org-link-preview--queue)) + ;; Run preview possibly asynchronously + (when org-link-preview--queue + (org-link-preview--process-queue (current-buffer)))))) + +(defun org-link-preview--process-queue (org-buffer) + "Preview pending Org link previews in ORG-BUFFER. + +Previews are generated from the specs in +`org-link-preview--queue', which see." + (and (buffer-live-p org-buffer) + (with-current-buffer org-buffer + (cl-loop + for spec in org-link-preview--queue + for ov = (cadr spec) ;SPEC is (preview-func ov path link) + for count from org-link-preview-batch-size above 0 + do (pop org-link-preview--queue) + if (overlay-buffer ov) do + (if (apply spec) + (overlay-put ov 'org-image-overlay t) + ;; Preview was unsuccessful, delete overlay + (delete-overlay ov) + (setq org-link-preview-overlays + (delq ov org-link-preview-overlays))) + else do (cl-incf count) end + finally do + (setq org-link-preview--timer + (and org-link-preview--queue + (run-with-idle-timer + (time-add (or (current-idle-time) 0) + org-link-preview-delay) + nil #'org-link-preview--process-queue org-buffer))))))) + +(defun org-link-preview-clear (&optional beg end) + "Clear link previews in region BEG to END." + (interactive (and (use-region-p) (list (region-beginning) (region-end)))) + (let* ((beg (or beg (point-min))) + (end (or end (point-max))) + (overlays (overlays-in beg end))) + (dolist (ov overlays) + (when (memq ov org-link-preview-overlays) + ;; Remove pending preview tasks between BEG and END + (when-let ((spec (cl-find ov org-link-preview--queue + :key #'cadr))) + (setq org-link-preview--queue (delq spec org-link-preview--queue))) + ;; Remove placed overlays between BEG and END + (when-let ((image (overlay-get ov 'display)) + ((imagep image))) + (image-flush image)) + (setq org-link-preview-overlays (delq ov org-link-preview-overlays)) + (delete-overlay ov))) + ;; Clear removed overlays. + (dolist (ov org-link-preview-overlays) + (unless (overlay-buffer ov) + (setq org-link-preview-overlays (delq ov org-link-preview-overlays)))))) + ;;; Built-in link types @@ -1595,7 +2155,48 @@ (defun org-link--open-elisp (path _) (org-link-set-parameters "elisp" :follow #'org-link--open-elisp) ;;;; "file" link type -(org-link-set-parameters "file" :complete #'org-link-complete-file) +(org-link-set-parameters "file" + :complete #'org-link-complete-file + :preview #'org-link-preview-file) + +(defun org-link-preview-file (ov path link) + "Display image file PATH in overlay OV for LINK. + +LINK is the Org element being previewed. + +Equip each image with the keymap `image-map'. + +This is intended to be used as the `:preview' link property of +file links, see `org-link-parameters'." + (if (not (display-graphic-p)) + (prog1 nil + (message "Your Emacs does not support displaying images!")) + (require 'image) + (when-let* ((file-full (expand-file-name path)) + (file (substitute-in-file-name file-full)) + ((string-match-p (image-file-name-regexp) file)) + ((file-exists-p file))) + (let* ((width (org-display-inline-image--width link)) + (align (org-image--align link)) + (image (org--create-inline-image file width))) + (when image ; Add image to overlay + ;; See bug#59902. We cannot rely + ;; on Emacs to update image if the file + ;; has changed. + (image-flush image) + (overlay-put ov 'display image) + (overlay-put ov 'face 'default) + (overlay-put ov 'keymap image-map) + (when align + (overlay-put + ov 'before-string + (propertize + " " 'face 'default + 'display + (pcase align + ("center" `(space :align-to (- center (0.5 . ,image)))) + ("right" `(space :align-to (- right ,image))))))) + t))))) ;;;; "help" link type (defun org-link--open-help (path _) diff --git a/lisp/org-attach.el b/lisp/org-attach.el index d4393324f..4fe06cbf4 100644 --- a/lisp/org-attach.el +++ b/lisp/org-attach.el @@ -797,9 +797,18 @@ (defun org-attach-follow (file arg) See `org-open-file' for details about ARG." (org-link-open-as-file (org-attach-expand file) arg)) +(defun org-attach-preview-file (ov path link) + "Preview attachment with PATH in overlay OV. + +LINK is the Org link element being previewed." + (org-with-point-at (org-element-begin link) + (org-link-preview-file + ov (org-attach-expand path) link))) + (org-link-set-parameters "attachment" :follow #'org-attach-follow - :complete #'org-attach-complete-link) + :complete #'org-attach-complete-link + :preview #'org-attach-preview-file) (defun org-attach-complete-link () "Advise the user with the available files in the attachment directory." diff --git a/lisp/org-compat.el b/lisp/org-compat.el index 05fe13457..20caafb2b 100644 --- a/lisp/org-compat.el +++ b/lisp/org-compat.el @@ -1010,6 +1010,191 @@ (define-obsolete-function-alias 'org-open-link-from-string (define-obsolete-function-alias 'org-add-angle-brackets 'org-link-add-angle-brackets "9.3") +(declare-function org-link-preview--remove-overlay "ol" + (ov after beg end &optional len)) +(declare-function org-link-preview--get-overlays "ol" (&optional beg end)) +(declare-function org-link-preview-clear "ol" (&optional beg end)) +(declare-function org-link-preview--remove-overlay "ol" + (ov after beg end &optional len)) +(declare-function org-attach-expand "org-attach" (file)) +(declare-function org-display-inline-image--width "org" (link)) +(declare-function org-image--align "org" (link)) +(declare-function org--create-inline-image "org" (file width)) + +(define-obsolete-function-alias 'org-display-inline-remove-overlay + 'org-link-preview--remove-overlay "9.8") +(define-obsolete-function-alias 'org--inline-image-overlays + 'org-link-preview--get-overlays "9.8") +(define-obsolete-function-alias 'org-remove-inline-images + 'org-link-preview-clear "9.8") +(define-obsolete-function-alias 'org-redisplay-inline-images + 'org-link-preview-refresh "9.8") +(define-obsolete-variable-alias 'org-inline-image-overlays + 'org-link-preview-overlays "9.8") +(defvar org-link-preview-overlays) +(defvar org-link-abbrev-alist-local) +(defvar org-link-abbrev-alist) +(defvar org-link-angle-re) +(defvar org-link-plain-re) + +(make-obsolete 'org-display-inline-images + 'org-link-preview-region "9.8") +;; FIXME: Unused; obsoleted; to be removed +(defun org-display-inline-images (&optional include-linked refresh beg end) + "Display inline images. + +An inline image is a link which follows either of these +conventions: + + 1. Its path is a file with an extension matching return value + from `image-file-name-regexp' and it has no contents. + + 2. Its description consists in a single link of the previous + type. In this case, that link must be a well-formed plain + or angle link, i.e., it must have an explicit \"file\" or + \"attachment\" type. + +Equip each image with the key-map `image-map'. + +When optional argument INCLUDE-LINKED is non-nil, also links with +a text description part will be inlined. This can be nice for +a quick look at those images, but it does not reflect what +exported files will look like. + +When optional argument REFRESH is non-nil, refresh existing +images between BEG and END. This will create new image displays +only if necessary. + +BEG and END define the considered part. They default to the +buffer boundaries with possible narrowing." + (interactive "P") + (when (display-graphic-p) + (when refresh + (org-link-preview-clear beg end) + (when (fboundp 'clear-image-cache) (clear-image-cache))) + (let ((end (or end (point-max)))) + (org-with-point-at (or beg (point-min)) + (let* ((case-fold-search t) + (file-extension-re (image-file-name-regexp)) + (link-abbrevs (mapcar #'car + (append org-link-abbrev-alist-local + org-link-abbrev-alist))) + ;; Check absolute, relative file names and explicit + ;; "file:" links. Also check link abbreviations since + ;; some might expand to "file" links. + (file-types-re + (format "\\[\\[\\(?:file%s:\\|attachment:\\|[./~]\\)\\|\\]\\[\\(From 43df7292f834644aff1cdc8e0c28eaedacba6fe7 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 | 293 ++++++++++++++++++++++++++++++--------------- etc/ORG-NEWS | 93 ++++++++++++-- 2 files changed, 281 insertions(+), 105 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 451fd72cd..95846b475 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -11778,7 +11778,77 @@ ** 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 (see [[*Hyperlinks]]) +inside Org buffers. By default, only image links[fn::Image links are +=file:= and =attachment:= links to existing image files; Emacs can +only display the linked images listed in ~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 [[*Adding Hyperlink +preview]]. Link previews do not have to display images -- any kind of +display decoration (see [[info:elisp#Overlay Properties]]) 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, if + any; the link at point, if there is such; or in the current section + otherwise. 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. + +- {{{kbd(M-x 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. + +- {{{kbd(M-x 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 +11873,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 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 +21881,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 --=-=-=--