From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.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 KH3dLJVvT2YB/gAAe85BDQ:P1 (envelope-from ) for ; Thu, 23 May 2024 18:32:21 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id KH3dLJVvT2YB/gAAe85BDQ (envelope-from ) for ; Thu, 23 May 2024 18:32:21 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=RMfOkzoX; 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=1716481941; 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=ZakQtRnhB2CnURjPSzy3tAuJobEfhdMYgIwi7qhrGCo=; b=nOSknf8EVnTpEypHKueo/WpbMnVkUyWsyF1D9h8/uPkzX321GiN3hCJLcZWmD5fGZy8oOW ACAc5k5FEf/S3JvbY8eS3uZiPs3t2xdpFw8v/LAG+vAGCTOyQdkHgI5BIkajISoHbE0OQy PPn79BYiLUHG9h/OfNPwxZwOQLbVVEAIydebEikK/DJOu04ayMzIz9o6JggzJPN10FJ9CS 7B5NuShUFffVrbSL7DaltTt5lOoN76xdtZXRUsMaKmg1Ga2gaUL+4eBGzSpbESeB4BU5fB qYFbLglHf8+RpgzTKlxvf8K4cSYtjf+Ta6/LGntapHjIZKPT4B+jQXqwAaOLRA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1716481941; a=rsa-sha256; cv=none; b=udVJU3ARK3foj9Flo3D76QfzFyXPBEZAnfLm8nTXoZOAbBSaJtvHQp7NO1qJqtCZWcfXij F5o4vSsQNfAvJKSIACWh/gjYTRaRPNOX0VqHO6d6eanrTTcrpVfjKsMEAgIvIFx2dmX1u9 CPauDDK8jITaQDjuTNN8PCgL3BLxvuWTtWk9dqAPsz+g9ltR2sgOUJiuMvpVNWN9+oQwJN jwgiRRiFco44V0hIE47ea5WkcKvrwGtI6JB/JvK4YJVQEjuVQJMmVmnFzkoKzgJFOfo+N+ 1jBjbqMgukYnpuc5ZI2M3zrQ9tCeNXShkv/SJ2xCshxH4V42cjoeSVmC1wFA8Q== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=RMfOkzoX; 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" 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 7311670BF for ; Thu, 23 May 2024 18:32:21 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sABLi-0000wW-5v; Thu, 23 May 2024 12:31:26 -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 1sABLe-0000w1-LA for emacs-orgmode@gnu.org; Thu, 23 May 2024 12:31:23 -0400 Received: from mail-lj1-x232.google.com ([2a00:1450:4864:20::232]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sABLc-0005Pj-P8 for emacs-orgmode@gnu.org; Thu, 23 May 2024 12:31:22 -0400 Received: by mail-lj1-x232.google.com with SMTP id 38308e7fff4ca-2e576057c06so76326021fa.0 for ; Thu, 23 May 2024 09:31:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1716481877; x=1717086677; 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=ZakQtRnhB2CnURjPSzy3tAuJobEfhdMYgIwi7qhrGCo=; b=RMfOkzoX+Fi16JE2BdYZI19gMZJfgXgirNXlfE1ue+hVkJQSVG+n6u8cv2wTLDE/kq +gUDWjN1yKdXIg40Nd74qsBbem5smg/H8zr+/kx9nXXis/q8vrz2Ie5wpqKqxcHUrRaA HiB9wDLv1zUg4oqPnp6NiyUWCrDR2CiSuAJB4+6ZfJxHayMPFwwjNuDXNnvr7xj7siMl xfWAI56GaWahZQNi2nWRYWLuNqe4LMSGz9Y035TfiEf8ieExwbwDV5sEPwl7rrI9O9Nt qMaznGyH6eXbB4rqwv2Wr6JOGB8CNoVz9vQV+KXnSR7IqbG9FW3eaJ52rZP+cqZUma6j ITzw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1716481877; x=1717086677; 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=ZakQtRnhB2CnURjPSzy3tAuJobEfhdMYgIwi7qhrGCo=; b=DjVqiGV4mxkiEq/SipSSkDZ0u7HtP3lKc13PyoOecUs388UYmstCBlLgsjlTj/d7OT swGkAM0PExFQ8tb9xrlui0IFflh8oGWQid/ppfhvWfS2HFq6y8gD/BjlsdVn02mh9tJl B/Hlg5T6CufLqg13X8yorD9lOa/4KNozEzZoQ13HwrEMHaxgU3F27imi1O1R1nzfEQtn bZbLqw8Lbo1t6BrYcpwtq96Gh+UI+quBLApy7tu1SA7elD/kffuZz8HL1v5PqoMJtpWi gMEbLg3teuLmBB7MXSg1yQiRTlkGdDwgbKVkCzke8ib73TqZKiixfEpngZV7ZWW7fvPF /AQg== X-Gm-Message-State: AOJu0YyMwq73fFWvPALqI2PWHIfLCLp4rowcyhP203nhNLIXDfdtoiui OtxRPJeJG4GBnai/ajPLjyZp+JlaikT8hXxfl0QXrSQVQnp/yw6RfTke7Q== X-Google-Smtp-Source: AGHT+IF3HLx8lcCl6MRo0ECKRvuRtj9WNRjzhVNOdaTa2rJb3mvgEN/wxgVcAOn6kGwzEYA99VbLxA== X-Received: by 2002:a2e:87cf:0:b0:2e5:67a8:2e5a with SMTP id 38308e7fff4ca-2e9494c1bb3mr36398481fa.13.1716481877255; Thu, 23 May 2024 09:31:17 -0700 (PDT) Received: from keynux ([2a01:e0a:505:3460:1c18:688d:ece4:372e]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-42100fad638sm29756605e9.29.2024.05.23.09.31.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 23 May 2024 09:31:16 -0700 (PDT) Message-ID: <664f6f54.050a0220.10342.b002@mx.google.com> Received: by keynux (sSMTP sendmail emulation); Thu, 23 May 2024 18:31:15 +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: Thu, 23 May 2024 18:31:15 +0200 MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2a00:1450:4864:20::232; envelope-from=brubar.cs@gmail.com; helo=mail-lj1-x232.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-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -6.68 X-Spam-Score: -6.68 X-Migadu-Queue-Id: 7311670BF X-Migadu-Scanner: mx11.migadu.com X-TUID: LwcFYxxFC1RK Hi Ihor, Ihor Radchenko writes: > Bruno Barbier writes: > >> I've pushed the modification to my branch. > > Thanks! Let's work further on the top comment. > >> ;; To lock a region, you need to do something like this: > > I think "something like this" can be just dropped. Sorry, I'm failing to find a simpler accurate sentence. >> ;; 1. Call the function `org-pending' with the region to lock; use >> ;; the ON-OUTCOME argument to tell Emacs how to update the >> ;; region. Keep the returned REGLOCK (you'll need it to send >> ;; updates). > > It would be nice to provide examples of `org-pending' call right in the > top comment. Ideally, the example should also show how to modify REGLOCK > fields to customize its behaviour. I added an example below the 2 steps. >> ;; 2. Start "something" that computes the new content. That >> ;; "something" may be a thread, a timer, a notification, a >> ;; process, etc. That "something" must eventually send a >> ;; :success or :failure message (using >> ;; `org-pending-send-update'): Emacs will update the pending >> ;; region (using your ON-OUTCOME) and unlock it; at this point >> ;; the lock is "dead" (not live-p). > > Please also add information about sending updates to the REGLOCK, with > examples. Otherwise, "receiving progress" in the next section is > surprising. Done in the example too. >> ... (not live-p) > > Please name `org-pending-reglock-live-p' - it is more clear than forcing > the readers search it themselves. Done. > >> ;;;; Interface provided to the Emacs user >> ;; >> ;; The library makes locks visible to the user using text properties >> ;; and/or overlays. It diplays and updates the status while the >> ;; region is locked: the initial status is "scheduled", then, when > > It would be nice to name `org-pending-reglock-status' here and use the > actual status values - :scheduled, :pending, :success, :failure. > Ideally, in table/list explaining what happens with buffer text, > overlays, and user interaction, when REGLOCK has each of the listed > status values. I added a table describing the possible status values, the valid updates, etc in the section above. > >> ;; receiving progress it becomes "pending" (with progress information >> ;; if any). Emacs allows to diplay a description of the lock. From >> ;; that description, the user may request to cancel that lock; see the >> ;; field `user-cancel-function' of the REGLOCK object if you need to >> ;; customize what to do on cancel. > > It is not very clear how user can interact with "description". > Is it a tooltip? A window? Something else? Please give a bit more details. I added that it's like the function `describe-package'. > Also, when "cancel" is requested, it is a good idea to state that > `user-cancel-function' is called and describe what it does by default. The function `user-cancel-function' is not always called; Emacs will only call it if the lock is still live (see `org-pending-cancel'). I added a short sentence describing what is done by default (the documentation of the field `user-cancel-function' of the reglock object already fully document `user-cancel-function'). >> ;; When receiving the outcome (success or failure), after unlocking >> ;; the region, the library may leave information about the outcome > > "may"?? Or does it always leave the information (by default)? To mark the outcome, org-pending needs to know where it is. If the ON-OUTCOME function (see `org-pending` documentation) returns the outcome region, org-pending will add a mark, else not. By default, ON-OUTCOME is nil, meaning no outcome region and no outcome marks. I added a sentence about that. >> ;; (using text properties/overlays). If that outcome information is >> ;; (still) displayed, Emacs allows to display a description of that >> ;; lock. From that description, the user may decide to "forget" that >> ;; lock; "forgetting the lock" removes the outcome visual marks, and, > > Is "forgetting" customizeable like `user-cancel-function'? No. >> ;; it allows Emacs to discard any information related to this lock. > > What does it mean? Emacs is free to delete any data related to this lock. This lock will not be available anywhere anymore for the user. Concretely, this lock is remove from the list of known locks, and, eventually, Emacs should hopefully garbage collect the related data. > >> ;; The description of a lock (live or dead) provides information like >> ;; the schedule time, the duration, the outcome time, the result (in >> ;; case of success), the error (in case of failure), etc. Customize >> ;; the field `insert-details-function' of REGLOCK object to add your >> ;; own information. > > Please show an example how to do it here. Done. > >> ;; If the user kills a buffer, or, kills Emacs, some locks may have to >> ;; be killed too be killed too. The library will ask the user to > ^^^^^^^^^^^^^^^^^^^^^^^^^^^ > typo Thanks. >> ;; confirm if an operation requires to kill some locks. See the field >> ;; `before-kill-function' of REGLOCK object, if you need to do >> ;; something before a lock is really killed. > > Again, an example would be helpful. Done. I've pushed the update to my public branch. Thanks, Bruno