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 ms1.migadu.com with LMTPS id EL1MBNrxQGbnVwAAe85BDQ:P1 (envelope-from ) for ; Sun, 12 May 2024 18:44:10 +0200 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 EL1MBNrxQGbnVwAAe85BDQ (envelope-from ) for ; Sun, 12 May 2024 18:44:10 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=kEk3K9PH; 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=1715532250; a=rsa-sha256; cv=none; b=uX9qosZaKmXozt3KH2NHUdoYAtTsaINk5QDs7Hz9eSB1tFO6Yn6M96RBb94+jWZDFXFij+ 3y2yuHRIfhtfT01JyVRvEvTlnSg/pMKSt8Qatb8BbHnr/4E/m3P3ezPOL2R1EAFgLffxgq xm661/tFIRyjIwJ1FMzHzfxX/4f0qie/mNMmCikuOGtwlZ3akapK7Av5PZNbFegGsX5H5a C09N5qudsG+2/wM2TAjYghg6vCTW0BJk1x36DFmiR+0XOHuOH7uq8HOwIa6df2aK7gHXgs KYCHXPeng+gjh/C9Y7/KtjMKL7EcyHvY3GkT/SHbuJ7u6CrqYfnchvkEsJ/GVA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=kEk3K9PH; 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=1715532250; 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=TSNOGX43RhJ++RdO6AP2qaklIu1PvMagKLvrcU9LMEo=; b=MbUfxynSLpqrotmQb2Hw8oz+YImRndBxt0A3j28AbvD2kpuPXEmso7hbCmKNWcx0jwcjma 7j/OkVwWd47wG181j8yiIA7le+i7O4xprG7hZ3lY+o5eZUpqvkUNHxhBEf7HolkW060NQD KonS/lhJgrzU7DkLPXjxgM0t7jSlxYef4TO/SHjbIbpRvS2k8uLueVHvU2om5HJJaisL7a 0uOuze7CyHTMHzDy7cKQJEh0I4tOfejyWUCnwcQZXtz8Y98+YjdVJ6KGJpO9NTWM7sNfXU 3PMkSR5Wn21K2t0tl6YqkDRb6v1MjSDf9GFZxknPXY32HrOAge8m621P+G9YOg== 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 B6B863618B for ; Sun, 12 May 2024 18:44:09 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s6CIL-0001Ax-Dw; Sun, 12 May 2024 12:43:29 -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 1s6CIJ-0001Ao-CL for emacs-orgmode@gnu.org; Sun, 12 May 2024 12:43:27 -0400 Received: from mail-wm1-x332.google.com ([2a00:1450:4864:20::332]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1s6CIH-000301-P0 for emacs-orgmode@gnu.org; Sun, 12 May 2024 12:43:27 -0400 Received: by mail-wm1-x332.google.com with SMTP id 5b1f17b1804b1-42011507a54so4858455e9.0 for ; Sun, 12 May 2024 09:43:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1715532203; x=1716137003; darn=gnu.org; h=mime-version:date:references:in-reply-to:subject:cc:to:from :message-id:from:to:cc:subject:date:message-id:reply-to; bh=TSNOGX43RhJ++RdO6AP2qaklIu1PvMagKLvrcU9LMEo=; b=kEk3K9PHrz+l3B4uBgCj/E/lSsgh8fq1L1gahE10+0WNAVpTQ1ltUe10KZOEY5297j I2VUMArQemeo9sGdnfnlGgLaZ6uSO9m20MgaRX8rQUeVFkK6p9MITVP+nU7XeoMbdqtF d20edykwZE7vA9mnZDNz/dEq+NdDnZdJ1W39EYx210piFn95bFFmYwGdxE1+eWCY38ZK ScB3+vZeMuiH4attXthI86ErmkSIta2iuwY6impPes05qksUbxxAFQkmueMZX+lE3ISh xj72SsaFWquUt01TyIvCxrcsWuxpgKMB/1BfV61+Q/V8KKMsyOQT+FBc3Hh6gjwvdsDn 0Fvg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1715532203; x=1716137003; h=mime-version:date:references:in-reply-to:subject:cc:to:from :message-id:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=TSNOGX43RhJ++RdO6AP2qaklIu1PvMagKLvrcU9LMEo=; b=BHqdaOjTihDqXL+C5+SXeOP2iplFLLQyquef81kZjyEeNTtRSrmp4EtNXMm/48dmKl vsEFVueHyM/mtvDBmGhWmcHTW6RDS/mKXdTED9pW0SfFfKINaiKKsxGcYGkih3b0y7Tt jxL2O3xIqEO/qb/sXBGHgBuTr4D/WppnWnbUSbAQSxh3e9O2rOXAc4ZlA9FvNFrhKaCa vsOB/hICDZnVMcDwFMA4VQkUe/ivlrotFJcCa15yINxJZNPmIJfUgN1VmaEwsDLFgAuq q+DLcafC9JYhgvbAuPH2xXoW4EWlow1frNCGfYzliGYFDloz/soWxE1s35Nda3SMoZ1X ORpA== X-Gm-Message-State: AOJu0YyhGMPismhlXvXZnHK22WIyPQTYm8tEQ9gXk2YdR3rQyxa/kkBk u6+w1lcvenhrz4YAqZjkbsg0LNAwr76apqL7JMaAtFdyrQZJSN+b X-Google-Smtp-Source: AGHT+IEOjVjnLLaX8DiI2FDHYs4xJSZXe6ZPlvtPFj4sHIlLNX5u6eYlwfgODhOCZhX6T0WzcLJ2Zg== X-Received: by 2002:a05:600c:468e:b0:418:2ab6:7123 with SMTP id 5b1f17b1804b1-41feaa41489mr70582555e9.10.1715532203123; Sun, 12 May 2024 09:43:23 -0700 (PDT) Received: from keynux ([2a01:e0a:505:3460:1c18:688d:ece4:372e]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-3502bbbc35asm9128488f8f.109.2024.05.12.09.43.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 May 2024 09:43:22 -0700 (PDT) Message-ID: <6640f1aa.df0a0220.9356.9ce8@mx.google.com> Received: by keynux (sSMTP sendmail emulation); Sun, 12 May 2024 18:43:21 +0200 From: Bruno Barbier To: Ihor Radchenko Cc: emacs-orgmode , Jack Kamm , Matt Subject: Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...)) In-Reply-To: <87r0f02vq2.fsf@localhost> References: <87o7d0mm54.fsf@localhost> <65cfa0d8.050a0220.cb569.ce34@mx.google.com> <18dbe11968a.12c0800a31425096.5114791462107560324@excalamus.com> <65df0895.df0a0220.a68c8.0966@mx.google.com> <87edct0x2w.fsf@localhost> <65e30609.050a0220.89c06.1798@mx.google.com> <87a5ng7uoq.fsf@localhost> <65e9f49b.df0a0220.11103.1c10@mx.google.com> <87ttlhki9e.fsf@localhost> <65eb1e60.050a0220.337b2.a0f4@mx.google.com> <87frwuxy1b.fsf@localhost> <65f95bf2.050a0220.6d051.c8b1@mx.google.com> <87plvpjj76.fsf@localhost> <65fc06c1.5d0a0220.0d53.efdc@mx.google.com> <87frwjlr1a.fsf@localhost> <6601b872.050a0220.31a67.5a55@mx.google.com> <87le63c3qy.fsf@localhost> <660ed63d.050a0220.36fdd.af23@mx.google.com> <87cyqwyvgw.fsf@localhost> <66225435.5d0a0220.f60e4.c590@mx.google.com> <87r0f02vq2.fsf@localhost> Date: Sun, 12 May 2024 18:43:20 +0200 MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2a00:1450:4864:20::332; envelope-from=brubar.cs@gmail.com; helo=mail-wm1-x332.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, MSGID_FROM_MTA_HEADER=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-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Queue-Id: B6B863618B X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -9.70 X-Spam-Score: -9.70 X-TUID: smy5QXV5VMj2 Thanks for the review Ihor! >> Thanks. I've improved the documentation of `org-pending' to mention >> that one may want to customize the following fields of a reglock: >> before-kill-function, user-cancel-function and >> insert-details-function. And, also, I added that one can attach >> custom properties using the "properties" field. > > Thanks, but I still feel confused. > May you: > > 1. Explain what does "kill" and "cancel" mean in the context of the > REGLOCK. I tried to document that as part of the function `org-pending. That is: | - Emacs may have to kill your locks; see the field | `before-kill-function' if you wish to do something before your | lock is killed. In other words, Emacs has to kill the locks, because the user decided to kill Emacs or some buffers. The user has no say about this. This is when org-pending calls the private function `org-pending--forced-kill'. | - The user may ask Emacs to cancel your lock; see the field | `user-cancel-function' to override the default cancel function. The user is not interested anymore by the lock. He makes a polite request to the library that locked the region to unlock it, the sooner the better. I added some documentation about them to the top level commentary. > 2. Add information about visual hints, "kill", and "cancel" to the > top-level commentary. > > For now, when reading the top commentary: > > ;; This library contains an API to lock a region while it is "being > ;; updated"; the content of the region is "pending" and cannot be > ;; modified. It will be updated, later, when the new content is > ;; available. > > I have an impression that the only side effect of "locking" is that the > region becomes read-only. It is not clear at all that any other > visual indication will be provided. I added a description of the user interface at top-level. [...] > Yes, I do think that top commentary should explain this. > The very idea that lock may be "canceled" or "killed" is important when > designing Elisp code that uses the org-pending library. > Both "killed" and "canceled" are now described in the user interface top-level section. [...] > > I hope that the above clarifies what I am looking for. I think it did. And I even hope the improved top-level documentation shows it :) I've pushed the modification to my branch. Thanks again for the review, your time and useful comments, Bruno