From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.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 ADaFEmhUImZHewEA62LTzQ:P1 (envelope-from ) for ; Fri, 19 Apr 2024 13:24:24 +0200 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id ADaFEmhUImZHewEA62LTzQ (envelope-from ) for ; Fri, 19 Apr 2024 13:24:24 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=SFYY87yW; 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"; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1713525864; 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=yF9bQ3ZAxWyw6O+LfcjbLqJVET1ITwMB91usyNArIfU=; b=llgC4ps4SgMOMjCVtDax7RoWI5JbfUggQq+eOK9s0I/vwHIn4V1k/oLQPERkau1pe/zuOi TCktv0Ic9KWeMJWcYMd1sHoQXk+LuVwyW8EBSdMjlAkMz6yQ7fCHzyKvvdm33hToFnNr/G eHB34OyVUKzSeZlqJPy9w4VJOvX2N0Zbpf+tY6hr0YC45MQI2HGE5U88N0TI6JUwZw2EnI LS42V1IHVl+p96RKKe9lTKZbWmqio1hqUuCMzCS3QdO/MM2LtL08OzU2QUsTZ6/KkZ8Q03 JdLKN1nOquywdRPByoeTGonJpx1RCkbhJ8Yumg4U7SP7FN1SZ0NrTeYuK6WLkA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1713525864; a=rsa-sha256; cv=none; b=P7XuMsNO4m/VH3A/Fv9zgxjz+Acr6R33ua3fZpozMupDnsqj3DAKFpU+kQDswPVbVug77D wjs2HimzHWPBz9Vcvod8ej198FBoBX4hr1/x8xZXL2lk9/kuXU6cJkkxLaA4vnBKV7gURV zBDlLpI+fW7N+6UmwmagQAd4bZsPNV2n7snlsxqFS/tIq/cGcDsPm3HL3pXhyoeNvdt6QA 4rRNV1HrvzjBef16ObqB4IRiEazXk4bxYStk4uo9EtsGD53D6SAPupCA5hwrh/Djm1Q58G TMdDZ81f4sG8I3XERgx5VWRV8FZYiHAT2vrILDckBEmgU4WABHJ/e3jccs16ow== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=SFYY87yW; 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"; dmarc=pass (policy=none) header.from=gmail.com 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 E80C21D197 for ; Fri, 19 Apr 2024 13:24:23 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rxmLD-0008Gk-VQ; Fri, 19 Apr 2024 07:23:40 -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 1rxmLB-0008GL-Tm for emacs-orgmode@gnu.org; Fri, 19 Apr 2024 07:23:37 -0400 Received: from mail-wr1-x42a.google.com ([2a00:1450:4864:20::42a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rxmL9-0004qa-UQ for emacs-orgmode@gnu.org; Fri, 19 Apr 2024 07:23:37 -0400 Received: by mail-wr1-x42a.google.com with SMTP id ffacd0b85a97d-3465921600dso1671969f8f.3 for ; Fri, 19 Apr 2024 04:23:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1713525814; x=1714130614; 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=yF9bQ3ZAxWyw6O+LfcjbLqJVET1ITwMB91usyNArIfU=; b=SFYY87yW5kFhZLXUmHABiX/Ydv4gLCTUi+Cm1VZzXKfS2HBogtK5NDZqe5Q6UuJYCL cvQHdd57u1o7vdYBB6m6ASnTErBua612LwySwTs6moOoxfLPZ+y7ascbiZFgRk3ySskY xqyCmuUZwnJ1lEQoyzX/e1TszmBq6xOqY5ichBr7Bm3KfhmYmltE5o/zif1msfd++m05 0K6/WudwQzGvpz35rscPJzMsSyCGBtsYHunTs30f2tKHGAAupOM9Qo1n2bPat7JaG4np 4bxdpxrDE82MlUU/7gNWHJ0Se5D2XlM6jgEODW/BjxEUp8fyU5wmMFlnX7AUMSXawGKn 3rqA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1713525814; x=1714130614; 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=yF9bQ3ZAxWyw6O+LfcjbLqJVET1ITwMB91usyNArIfU=; b=h4ktbCePzc1dac2PVCHJhLlupnS9QYlrVNMrUc4yRJdNaT/4dbQV4VHY5CGnyyROVz UqSzGP0LO9BWFrXMeVUhvY4pvqDC7eqe7dgm4I8AGFln8fc9XMR7G7KNQ8VsB01uji6/ e2AR3wqFyVmIrBv3Er+ctD1NrVpdC3mYhQEPGzhlKVmCpCccCXtNHkrVhWBl7y0cuvQd yvoScG7nSGZjH4vuVnhpuJTB47Th3lmoW3D1ggufiFDXHAhO4BozR2+1SFMfFw+nPy4E PTdL1+HFlEGinriOXqZPzQR2vxyulfRtSOIjBnPBRZ+Z3BrjEe/ZeuezOgLAmWzgyScL 6QRA== X-Gm-Message-State: AOJu0YzEqonLJesvtaEDO0gJt7mv3zKcccEDtI0FNvQaM76gVUAhyFfM RihK1Tzi2J/YFw2NW1Q45ttunBStUce1uDJMbekxb0Vn826S+mz3a3mDOg== X-Google-Smtp-Source: AGHT+IHzxc0GN8IssUw1J1vozo+6cL3ZeACJyGPBCsG5aVilhFr20updiAP6FrYSJZ4AJjyLKp8xMw== X-Received: by 2002:a5d:648a:0:b0:349:c42f:eacf with SMTP id o10-20020a5d648a000000b00349c42feacfmr1356952wri.24.1713525813467; Fri, 19 Apr 2024 04:23:33 -0700 (PDT) Received: from keynux ([2a01:e0a:505:3460:1c18:688d:ece4:372e]) by smtp.gmail.com with ESMTPSA id cg5-20020a5d5cc5000000b00343dc6a0019sm4145436wrb.68.2024.04.19.04.23.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 19 Apr 2024 04:23:33 -0700 (PDT) Message-ID: <66225435.5d0a0220.f60e4.c590@mx.google.com> Received: by keynux (sSMTP sendmail emulation); Fri, 19 Apr 2024 13:23:31 +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: <87cyqwyvgw.fsf@localhost> References: <87o7d0mm54.fsf@localhost> <65c2875f.050a0220.caf6d.8291@mx.google.com> <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> Date: Fri, 19 Apr 2024 13:23:31 +0200 MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2a00:1450:4864:20::42a; envelope-from=brubar.cs@gmail.com; helo=mail-wr1-x42a.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: -9.69 X-Spam-Score: -9.69 X-Migadu-Queue-Id: E80C21D197 X-Migadu-Scanner: mx12.migadu.com X-TUID: GVQhgAArHfsd Hi Ihor, Thanks for the review. I've pushed a new version, hoping to decrease the number of dislikes ;-) Ihor Radchenko writes: > Bruno Barbier writes: > >>> I have a further request on interaction with penreg objects. >>> I feel that it is not ideal that overlays associated with penreg objects >>> cannot be fully controlled by the callers. >> >> I'm trying to limit the public API surface. I don't think we should >> leak that we are currently using a mix of overlays and text >> properties. > > Let me rephrase my concern - I do not like that after reglock is no > longer live (got success/failure signal), there is no way to clean up the > visual hints associated with this particular reglock. [....] For the org-pending library, "live" means "locked". Once the outcome is known, it can't be "live" anymore (it's unlocked); as it's not reusable, it's "dead". As the region is not locked anymore, the lock properties/fields can't be trusted anymore. But see below about removing the visual outcome hints of a given reglock. >>> 2. Act on the outcome overlays - there is currently no way to remove >>> them using penreg object. >> >> I've added a funcion `org-pending-delete-outcome-marks' to manually >> delete outcome marks that are in a given region. >> >> Else, everything is handled automatically. Once the outcome is known, >> the reglock is dead (not live-p). org-pending may leave outcome marks >> about the outcomes (outcome marks are optional). The outcome marks >> automatically disappear if the user remove the section, or, if a new >> lock is created for the same region. > > I do not like this. > I'd like the Elisp program that creates the reglock to be able to > clean up any visual hints associated with it. > A function doing it for a > given region cannot do this AFAIU. ok. I've added the function `org-pending-reglock-delete-outcome-marks, that will delete the outcome visual hints for a given reglock, if there are some. I updated how the lock is described to the user (org-pending-describe-reglock): I added a button "Forget" (if the lock is dead, that removes the outcome marks), and I added a "Cancel" button if the lock is still live. >>> Maybe :cancel signal? Canceled penreg >>> objects can then be garbage-collected from the manager. >> >> 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. > 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. > 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 ? [...] >>> Is there any reason why you hide the extra information behind :-alist >>> filed? Why not directly adding extra fields with proper documentation? >> >> To hide them, indeed :) > >> The API for 'get-status and 'get-live-p are >> `org-pending-reglock-status' and `org-pending-reglock-live-p' (they >> are read-only). The API for the new `useless-p' is >> `org-pending-reglock-useless-p' (it's read-only too). > > We usually "hide" fields by declaring them private. > Hiding them from the type docs is not a good idea because it defeats the > purpose of type documentation in general. > >> The fields anchor-ovl, region-ovl, on-outcome, set-status and >> creation-point are the dump of the closure context, so that >> org-pending doesn't rely anymore on a closure to handle updates; I've >> rewritten that recently. Nobody is supposed to use or change those >> values, except the update process. >> >> IMHO, dumping those as fields in the lock structure would be more >> confusing and fragile than keeping those out of sight. I could add >> comments when they are created/used in the code to help understand how >> they are used. > > I disagree. In particular, I dislike the fact that they are not > documented anywhere and one has to read the internals of the code to > understand their purpose. Done. I hope the minimal documentation is enough. Thanks again for your reviews and your comments, Bruno