From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id UFbTDfCTI2aLUgEAqHPOHw:P1 (envelope-from ) for ; Sat, 20 Apr 2024 12:07:44 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id UFbTDfCTI2aLUgEAqHPOHw (envelope-from ) for ; Sat, 20 Apr 2024 12:07:44 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=egcj6I4A; 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=1713607664; 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=cJ1n1VYbEdOq6JJ37d1bxGpEeHBKlf092uT++eok46E=; b=hPARx0Qi8w2i7I0GmduGR/eXK7nYQV65K+akG1NyAH+hxMcm+Qn7IPhAShwMMXBP4yJH3/ Pq3Zk+jRSZci6CA8SHRaigD4a9f6QUyEug8ECzRYXhhSl4Qn8Of5PtiRTSvnYsCxWpY41i 2UyoXqXEFiVRGDPaiHPnGGacfu072NlnNabCxtSZ0IKXOzGQpsE3FxPHo6VqblLSEnbYwN +Udh+XZOH26Cj/ydFBkqVf/z1Z8crXwEGqgLG/jz9CpgvVSZ901wtTL8y9RwcXO8YNGJTb wWgcIGFhTAqdqdNaHmE6xmtUBehiimGqOV/JSRt91AZvAzzIkJ/8DU0mSpvvQQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=egcj6I4A; 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=1713607664; a=rsa-sha256; cv=none; b=nBPd4b27uqrA7RxAETbk/BF0M5cEnPsaWBesWcvTl+lWvgnekEEyruqYo1IbcMGVGeW0EM zImFXxJWxD+HYW60EPoHA5FBjj8fhP7Xbod5ScsbsJLh8ac8zbVuZYJ39mu4jGKJ0pc6kI A5gxH2h5qJqgsKO6oriJDYvzo9+mEXkFYAw3vqWCXdSlf36OCQdpzCJ58AqAMdSCstAJY9 yG6BEB11+Wz/yKSqthhIVPee5yhgFS9BPd64u+flRECFywFwY4VyDd8oJeY0YiFm9Xvpjb RaBvi8Bgyh6CkomasEAZzDOpX32oeFJvzk31od9IFs1WFcUcAN9oIgIabbAWZQ== 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 4FD5261807 for ; Sat, 20 Apr 2024 12:07:43 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ry7cW-0001sI-Ko; Sat, 20 Apr 2024 06:06:56 -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 1ry7cU-0001rv-Sd for emacs-orgmode@gnu.org; Sat, 20 Apr 2024 06:06:54 -0400 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ry7cR-0008Pc-VD for emacs-orgmode@gnu.org; Sat, 20 Apr 2024 06:06:54 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 7968D240027 for ; Sat, 20 Apr 2024 12:06:49 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1713607609; bh=U35a74VP1mssBhKL/1cEkdj0vBCDLlij5cWF7Wq3iWc=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: From; b=egcj6I4ADnLE5jhnzDNrQX6DxfDKQ+SrAdc51fej7xuOmPOOLcpPGlN1FpxglIjRh iR+KlH2FGQPbnceA5cGQsNSh5xIG+BTsNk2b5gQ2lQxLX7SdJoR/7IkE+UUOwkEckG CP9FyFeFWc+qB7nvpfqWMZ9N1J3KwPBkryD/jL+zQuAr06Ot4S7K1eRe+Lb6XTgt4T n3tWzrnxVY6NzGsjuw1VtBRjt0jb4mNgyL+L/fKyr3PFnmkr98VtBrnm+g/IydsjKn Cj4FUvP55foqMpHeRYcv5dlUS6iDX57DVDy9IMBHdd5OS4Fltg6wvQMT8HZAcS3Dl3 LpTPPmqBvAweg== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VM6cS400vz9rxG; Sat, 20 Apr 2024 12:06:48 +0200 (CEST) From: Ihor Radchenko To: Bruno Barbier Cc: emacs-orgmode , Jack Kamm , Matt Subject: Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...)) In-Reply-To: <66225435.5d0a0220.f60e4.c590@mx.google.com> References: <87o7d0mm54.fsf@localhost> <18dae5cab1d.bf1c7563863897.4896289306902277373@excalamus.com> <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> Date: Sat, 20 Apr 2024 10:07:33 +0000 Message-ID: <87r0f02vq2.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.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, 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: -6.59 X-Migadu-Scanner: mx11.migadu.com X-Spam-Score: -6.59 X-Migadu-Queue-Id: 4FD5261807 X-TUID: wO0zDmTBTJCZ Bruno Barbier writes: > Thanks for the review. > > I've pushed a new version, hoping to decrease the number of dislikes > ;-) Thanks! >>> Cancel is handled by sending a failure message (see >>> `org-pending-cancel'). It's customizable using the reglock field >>> ~org-pending-reglock-user-cancel-function~, which can decide what to >>> do (like kill a process) and which can send a better outcome. >>> Standard 'cancel' leaves a failure outcome mark. >> >> Note that this function is not documented anywhere other than in reglock >> class documentation. > > 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. 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. >> In general, I am confused about your overall design >> of the user interaction with the locks. >> The updated top commentary explains well how Elisp programs can send >> data to the locks, but it does not say anything about how Elisp programs >> can receive the data. > > An elisp program, that uses org-pending, must update the locks using > `org-pending-send-update'. That program does not receive any data > from the lock; it may customize Emacs behavior using the reglock > fields mentioned above: before-kill-function, user-cancel-function and > insert-details-function. > > Hopefully, it's clearer now with the improved documentation of the > org-pending function. > > Just let me know if you still think that the top commentary should > explain this. Thanks. 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. >> Also, I'd like to see more information in the top commentary about what >> are the "visual hints" displayed to the user and how to configure them. > > If you think the current "visual hints" are good enough and could be > shipped as-is, in a first version (indirect buffers, etc.); I could > work on documenting them better. What kind of configuration are you > thinking about ? just the faces ? or more advanced configurations ? I am not thinking about details yet. I just want insert-details-function to be described in the top commentary. At high level. Something like * Visual indication of the "pending" regions While the region is locked, it is visually highlighted in the buffer, providing information about the lock status as an overlay. The status can be: 1. :scheduled - the region is "being updated", but the computation has not yet started. 2. :progress - the computation is in progress After unlocking the region, the visual indication is not necessarily removed. Instead, the outcome is indicated in an overlay. The outcome may be: 1. :success - the computation has been successful and the region text has been updated 2. :failure - the computation failed The lock status is updated according to the data submitted to REGLOCK object via `org-pending-send-update'. * User interaction with pending regions For any pending region, users may request detailed description to be displayed. The description includes the pending region status, creation time, outcome, duration, results, errors, etc. Elisp code using this library may also supply additional details about any given reglock, via `insert-details-function' field of REGLOCK object. For example, process logs can be displayed this way. -------- I hope that the above clarifies what I am looking for. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at