From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.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 YJm1LfPUH2cXwwAAe85BDQ:P1 (envelope-from ) for ; Mon, 28 Oct 2024 18:16:19 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id YJm1LfPUH2cXwwAAe85BDQ (envelope-from ) for ; Mon, 28 Oct 2024 19:16:19 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=Dm7KPhgE; dmarc=pass (policy=none) header.from=posteo.net; 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=1730139379; a=rsa-sha256; cv=none; b=fAx/5c4WMPnXv/gENMJulceC75h5RMRGzokCIhHmXMhM7FAUXPzGbElBteC0XLLz/o7m1z 2nPSRxIhW008SM4v7noHeh9ewKEfM0J+0j6JQ4BO3rgFxvtyStYvq37M89FT9cxjCgJcKe mKqtrDf9/4FrOrHUbXUSUem6suQFXOke6Vs/MfxnKE32vwNeTEjpdNqtp5bXtX26C6WAfx ho1J5PCRjtT3qx9XTmgUYjes7rXulG3VgaXTxW9XJTWYY+A51++ykmLhIUycOpJVqpw1H9 TWxAIe/MxUlYgWDdWCfpHFGQWkA103nAS5XKofiLdgTOSPi1QTCPP8b8OxxYMQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=Dm7KPhgE; dmarc=pass (policy=none) header.from=posteo.net; 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=1730139379; 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=MS3/v5JjBkYLUZrCaUfd4hLieufx+Xi9shA1z1oWCBY=; b=LQoVIeISYOFZl5fijUc8wM8doAub5Dwalq5cK+Wc0atlBTDkY1Ss/54t1Vn3gIe/Vlsxzt kDu9/9XAoRguPEAI72KTz5yug/Cg77uTWxujvZ0KFmJHS986CQXsSSZ6LGKd2Cd8eUuRld c8O8s2aiYLYLODLgf0E8tngTz1rPxuSBmJE7PVoNp4qXE4yn6D9aN31L0Hp2p/n7eRjh1T UO5jZngD7yhRuNqRpyMBXFfEIBCsQioMI7dkXYvcjmizXo8XjbfBGXcrxj+Q942vIdlafy L7myFrQ5f+07y3CUSnLeuQzdmJ5CQNOLj8qyR5W9kXV3qEraru7QRtEGllWqHQ== 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 245911BB8C for ; Mon, 28 Oct 2024 19:16:18 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1t5UH4-0005pv-0n; Mon, 28 Oct 2024 14:15:30 -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 1t5UGq-0005jh-MX for emacs-orgmode@gnu.org; Mon, 28 Oct 2024 14:15:18 -0400 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1t5UGn-0002s7-Rq for emacs-orgmode@gnu.org; Mon, 28 Oct 2024 14:15:16 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 1D125240101 for ; Mon, 28 Oct 2024 19:15:09 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1730139311; bh=LFFXfWwRE0cnSBSfpZsnFu3LXb/8HMSPpzIjdpGdlL0=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: From; b=Dm7KPhgErIMKWy6+6WjvjeERZYwNhB/zg0wvnfyg/x4f/76TfluZBepEnfHv05Nnk u3XRzSCGwXECs3eK4cJEqHjKIUjgs82Zhpo9t/XGu7iQXsQRXCMAZu2wmQMOyLPRNC A2G0xZlv6Mxc6as8Sa5Wk99Ei+z0X91Vl7X6z/3mfB0yStc9706fbeODdkXJdO6zjb rEPDFOV/BoX2538FetHVgR8l50HVdwHxL6xAIX4/BzDLpBlWq+vhoXhvZNgV+TQXWB kaRZ0lhz0FzcDCPWDFjEM76jxu/wL8R9mkZK3mhRDIw4X7fJjUUxDtYpyVgtdD9cfW v5tvhNvXviOEw== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4XchPm6cRTz6tvs; Mon, 28 Oct 2024 19:15:08 +0100 (CET) From: Ihor Radchenko To: Karthik Chikmagalur Cc: stardiviner , Org mode Subject: Re: [PATCH v8] Inline image display as part of a new org-link-preview system In-Reply-To: <87h68weovw.fsf@gmail.com> References: <6461a84b.a70a0220.b6d36.5d00@mx.google.com> <874j70n559.fsf@localhost> <87msksabld.fsf@gmail.com> <87jzfwljkq.fsf@localhost> <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> Date: Mon, 28 Oct 2024 18:16:53 +0000 Message-ID: <875xpcks8a.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, 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.06 X-Spam-Score: -1.06 X-Migadu-Queue-Id: 245911BB8C X-Migadu-Scanner: mx12.migadu.com X-TUID: T1g1I1N3DnFA Karthik Chikmagalur writes: > 1. Patch 0001 is the code patch from before, with the warnings from make > addressed. > > 2. Patch 0002 is the documentation patch, which adds to ORG-NEWS and the > manual. There are two new sections -- one is in the appendix under > "Hacking", and shows how to add a preview function for a link type > (along with a code example). Thanks! See my comments on the documentation patch below. > -** Images > +** Images and link previews > + > +Org mode can preview hyperlinks in the buffer as images or with other > +decorations. May put a link to [*Hyperlinks] here. Also, this reads awkward. Maybe something like Org mode can display previews of [[*Hyperlinks][hyperlinks]] inside Org buffers. By default, only image links[fn::previews are available =file:= and =attachment:= links to image files; Emacs should be able to display the linked images (see ~image-types~ variable)] can be previewed - the images are displayed in place of the link path. You can customize the previews as described in [*Adding Hyperlink preview] section. The custom previews do not have to display images - any kind of [[info:elisp#Overlay Properties][display decoration]] can be used. > +*** External link previews > +:PROPERTIES: > +:DESCRIPTION: Preview links in the buffer. > +:END: > + > +Org mode can preview [[* External links][External links]] as inline > +images or with other decorations. This requires support for the > +corresponding link types to be available[fn:: To add support for or to > +modify how links of a certain type are previewed, see .]. By default ^^^^^ > +Org mode includes support for previewing file and attachment links for > +image files (see [[* Images][Images]]). The first sentence in the parent section and the first sentence here are basically identical. As I suggested above, let's move these things up. (Feel free to modify my version as you see fit.) > +Supported link types can be previewed within the buffer with the > +following commands: If possible, try to use active voice. We are talking to users in the manual: You can preview the supported link types in the whole buffer, in current section, region, or at point. > + By default, only image links without a description are displayed. > + You can force displaying previews for all supported links using > + numeric argument to toggle all the images in current section (~1~ > + argument) or the whole buffer (~11~ argument). This is not accurate. C-1 argument will act just as no argument: display links at point/region/section depending on the context. Looks like the docstring wrt C-1/C-11 args should be improved. > + #+vindex: org-startup-with-inline-images > + You can ask for inline link previews to be displayed at startup by > + configuring the variable ~org-startup-with-inline-images~[fn:: The > + variable ~org-startup-with-inline-images~ can be set within a buffer > + with the =STARTUP= options =inlineimages= and =noinlineimages=.]. Org mode can display link previews automatically when opening buffers. Either customize ~org-startup-with-inline-images~ or use in-buffer =#+STARTUP: inlineimages= keyword to enable the previews. =#+STARTUP: noinlineimages= will disable the previews in specific buffer. Also, since we are generalizing things away from images, maybe we should introduce some aliases to ~org-startup-with-inline-images~ and to the startup option values. Something like ~org-startup-with-link-previews~ and similar to startup option. > +- {{{kbd(C-c C-x C-M-v)}}} (~org-link-preview-refresh~) :: > + > + #+kindex: C-c C-x C-M-v > + #+findex: org-link-preview-refresh > + Assure inline display of external link previews in the buffer and > + refresh them. "the whole buffer" maybe. > +Such images can be displayed within the buffer with the > +~org-link-preview~ and associated command, see [[*External link previews]]. This sentence reads awkwardly after the previous section that already talked about previews and ~org-link-preview~ command. We can write When [[*External link previews][link previews]] are displayed as images, the image size and alignment can be further customized. > #+vindex: org-cycle-inline-images-display > Inline images can also be displayed when cycling the folding state. > @@ -21794,6 +21833,65 @@ ** Adding Hyperlink Types > topic. It also provides a default description. The function > ~org-insert-link~ can insert it back into an Org buffer later on. I suspect that it belongs to the previous section - cycling should work for all the link previews, not just images. > +2. The value of the =:preview= parameter must be a function that > + accepts three arguments: > + - an overlay placed from the start to the end of the link, > + - the link path, as a string, and > + - the link element. element -> syntax node > + It must return a non-nil value to indicate preview success. ... and your example can sometimes return nil, which is confusing. We should explain what nil means as a return value as well. > --- 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. > ... > +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 Aside: I am wondering if we should also attach preview toggle to when ~org-cycle-inline-images-display~ is non-nil and there is a link at point. > +*** New option ~org-link-preview-batch-size~ > + > +Org link previews are generated a few at a time, in batches. This asynchronously > +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. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at