From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id CJDGAFjNF2bQMAAAqHPOHw:P1 (envelope-from ) for ; Thu, 11 Apr 2024 13:45:28 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id CJDGAFjNF2bQMAAAqHPOHw (envelope-from ) for ; Thu, 11 Apr 2024 13:45:28 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=WF6uZKPa; 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=1712835927; a=rsa-sha256; cv=none; b=X3m8VpVSeLLkdzgznkTi2xE8pvWPVfrAvZ+hoGUgk1adbT6v1T3m99ZD7fIo5FXbJW9nfR MxZ/9WYnSVHkQWBPNdmKVXN4hvSJ8LqQ0068RFOgnEBXqknTDDOg04pZMw8C60kax08sZV 8k5ElqQQtoFWpDIpy/CmiZ41wTrxbCALJBL7MSPl50KAAFzyjOMgtqRnnEjzNDBHpjHaOa /wQyOoUSidUUcflLPnCyJYvLQV7j3gMKdTL5SPOBFh6nrjwLQhNRnuw+dyt1Ouc0LHPKqN kBoFrWiP7AGhJUHCaHoGvLiDyL9RUbqw+2HwFCzFj+gRigf4D/ZarcrWo9Y09g== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=WF6uZKPa; 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=1712835927; 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=yp5ymV1qJwbOFoSSirRq2IlCMvAT+cku+HItsRSa5+M=; b=Wd6EUXQO6Lmuj3CIP9SWfzyNedNoxaLP6qR/56cAiieX7HIPqVf1hSIH4zkmzh9SKcrJbC rxJPfRNtC/3Ag1nsJkRLKpE4rKsZZxUVZJ+fmpPq/VWMD5/OHJ39NnY5JUESFqZgN1U16y sCeBsav5BCD1M8OfAMYI1pR6xWy8naIIbUCJL+Aiq5RhweH8noUNt7O/+DS07MbbjllEqo gX7SK+ZqATZR96Uc5HgPhfAAw+am/sRajgsM0KbUb/HDIBU/eGXwGCAnldgXYis8U3ORHv WIsd7QZLzWbWGQJGknbB6ldV/Dl2Mmx+FQfdU2Vy5JQVBYDzuQy3KGfKMCpMzg== 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 7A0E57452E for ; Thu, 11 Apr 2024 13:45:27 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rusr2-0004yA-26; Thu, 11 Apr 2024 07:44:32 -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 1rusr0-0004xw-06 for emacs-orgmode@gnu.org; Thu, 11 Apr 2024 07:44:30 -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 1rusqu-00086H-HD for emacs-orgmode@gnu.org; Thu, 11 Apr 2024 07:44:29 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id C2DB1240103 for ; Thu, 11 Apr 2024 13:44:21 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1712835861; bh=rtR18IWyTpP2snnTj6AYL2HUENbKQbCtSat87nzqRhs=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: From; b=WF6uZKPayeAOU0+ZgWVV7C3e0IpeIhTy2GXivk5aIgvBWarLwUSUM6xxpUbBSeQiK wWyv+4X7yVfOCym2ek9MfLpqOzVvqbz7i/UdcpIeKHry+1jbYArZyRrHxQRkzYVEPE VCIzDNhrulTO9toWAd74nosUcs56LgUGk5U3Oz29hEoN1Y2aZFMJtY66ZJqq3eFKws 2O7beprkI4XBpJRHiwrdV9mRkt5Jf9xnBtgw8atEePC/1XOuphAAqWCXA5xE62MlHz wRTqGVBkTlg5kNj2HPTmVXUSSpoDwe9Uue8xf1e5vB/+XiIuPKLk5jgHmMsYzzJa/h lXtnGXXrYbJ5w== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VFdC85K4qz6txP; Thu, 11 Apr 2024 13:44:20 +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: <660ed63d.050a0220.36fdd.af23@mx.google.com> References: <87o7d0mm54.fsf@localhost> <87o7cv9e80.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> Date: Thu, 11 Apr 2024 11:44:47 +0000 Message-ID: <87cyqwyvgw.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_H4=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-Spam-Score: -8.08 X-Migadu-Queue-Id: 7A0E57452E X-Migadu-Spam-Score: -8.08 X-Migadu-Scanner: mx10.migadu.com X-TUID: u3HEVbUgybc5 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. >> In particular, I'd like to see some way to >> >> 1. Create penreg object without locking the region, so that scheduled-at >> time is not set immediately and status overlay is not displayed. >> Then, `org-pending-send-update' could send :schedule signal to >> perform actual lock. > > Using the term "region" was confusing, sorry. That's why I switched > to region "lock". I don't think there is a use to create a lock that > doesn't lock. > > Also, that might be tricky to implement: `org-pending-send-update' is > called asynchronously, from the user point of view. Having regions > that suddenly become locked, independently of what the user is > currently doing (if we implement the :schedule message), might be > difficult. > > What use do you have in mind ? I was mostly confused about linkage between "visual hints" in buffer and how they are connected with reglock object. You may discard this comment of mine. >> 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. >> 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. 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. 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. >> Also, the top-level commentary is getting incomplete and out-of-sync at >> this point. May you work towards more detailed top-level description of >> the library? > > Sorry. I tried hard to keep it in sync with all the modifications. > > I found it too much work, and, possibly overwhelming for the reader, > to explain everything in the top-level "Commentary" section. > > That's why I deleted everything that wasn't mandatory to understand > the core features. > > Everything should be documented as elisp documentation strings, > following the documentation of `org-pending' and > `org-pending-send-update', and, from code comments. I agree, but I'd like to see the core concepts explained on top: 1. How to create region lock (done) 2. What the region lock does (prohibit modifications, done) 3. How the lock is presented to the user and how to control the presentation (not done) 4. What can user do with the lock and how it is reflected in Elisp level (not done) 5. What can Elisp do with the lock (done) > I tried to improve the overall documentation. I hope it's going to be > easier for you, and others. Yes! Thanks! >> 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. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at