From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:1008:1e59::1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id 2IUEDDakXWamVAAAA41jLg (envelope-from ) for ; Mon, 03 Jun 2024 13:08:38 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id qOcTBzakXWZPzgAA62LTzQ (envelope-from ) for ; Mon, 03 Jun 2024 13:08:38 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=NPJinGn8; 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=posteo.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1717412918; 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=Z6NYTXC+OG2dpX13/UdBTKpWwsCzIssn8ldRte6hAyE=; b=iM1d8DlvC4vEFxN5aek1btgzBJtNC1Nq99Fv+R8oSPYyYJuu9njQJ6Ncg4eI4Nb51DC09d ac9BmiYv7eJWT4rpJq9INQRV+BcyGZ58VDZJiutTwm8lIlZxAzwCsOO7pCRl6NUhZi51xK Xk3mTQmztzOjXrtWbKS+3p89sz06oikeCUeVCLrLaLUYkc1jMxRsw9jJiTwM30GYYAaF47 a20H6G5SN/vhsw3pQjUTWi2Bv1DkP+8hxGSpuLU0nju4ojhwoyoE3lv3tNGXTcAWj5f8d2 CE7QiSh8wmFy4b6kGNNFc4fJ9hhjdD3wmm32bzfLbcTNiyOIaAoR4uIzVzcLAg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=NPJinGn8; 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=posteo.net ARC-Seal: i=1; s=key1; d=yhetil.org; t=1717412918; a=rsa-sha256; cv=none; b=hzERSVP9lbz60J1wzsMn5891mhI8VfIEbWJwoqisJftoTs+xgsjIN0E+P2CZ2dRzbOo2yC S0zH4S1Z6MqjqrZ20kZvd/dj2yq9uylLD2zZU+btfBpaAn1sPGEmJxNTOTtWoIPk+Thlab a2sYGV4LaAngw0r4oMO+nQ1bHsDN/CtmXdGuC7tO4GoUUYqbOdht0vc6cdZVjd8GVxrEKt cagrKYfPr1JhPvFEJn5vFi4LlSmHLNKTUJi+Stcdmu01FeVMTMSzXy/uOHX1rwMW9zDgqs Vin3r3e3rYFXNtGcLuGXdEzIphJBhkrOPmkLda/cOXkGMNAhnGDKIQrvLB5rSA== 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 859ECC7E2 for ; Mon, 3 Jun 2024 13:08:37 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sE5Sb-0007CU-Dr; Mon, 03 Jun 2024 07:02:41 -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 1sE5SZ-0007C7-9U for emacs-orgmode@gnu.org; Mon, 03 Jun 2024 07:02:39 -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 1sE5SV-0002o1-Af for emacs-orgmode@gnu.org; Mon, 03 Jun 2024 07:02:39 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id D6009240027 for ; Mon, 3 Jun 2024 13:02:29 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1717412549; bh=Wrx0ZiPOhPTeb26fxE6W2HHGAkwYXOLZ/mLy0gtb2c0=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: From; b=NPJinGn80J9M/MI1sHL97/JOjU3HKphIk0Qa6+5iC6KfgD7tKquCgZipeGa3EM2uj OdL2gX90ehiGIhYv9fjj/J/qV5KxmPQghIvO2TSL3zGMTr5/5UlLURNcDZDxb4NNKN yDPcXusJoHhNkZet49sOhKSGEHXiuVGPucMBTrM2y5gz1/Uj5nRe/aUZCicG6SwiuO FENQCOo5ixQOUZwIFa9hLoag5u75qmAp2m3tB/WmOMwKNLyETcHQKJgnO0aKBLxpMB /tuKaZAh6hopN4+vBIxff7NmBzYTEF+VdLCnVueOyyiNu+8cRFq3ZLEYbXE6CLXwHo 6px4z82OsnTlQ== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Vt9mN6thQz6tw2; Mon, 3 Jun 2024 13:02:28 +0200 (CEST) From: Ihor Radchenko To: Bruno Barbier Cc: emacs-orgmode , Jack Kamm , Matt Subject: Re: Pending contents in org documents In-Reply-To: <665abf9f.050a0220.d2a6e.ef6b@mx.google.com> References: <87o7d0mm54.fsf@localhost> <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> <664f6f54.050a0220.10342.b002@mx.google.com> <87o78vwnds.fsf@localhost> <6658cd1f.050a0220.f6605.de1a@mx.google.com> <87jzja71n7.fsf@localhost> <665abf9f.050a0220.d2a6e.ef6b@mx.google.com> Date: Mon, 03 Jun 2024 11:04:12 +0000 Message-ID: <87plsyz3rn.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.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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-Spam-Score: -8.06 X-Migadu-Queue-Id: 859ECC7E2 X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -8.06 X-TUID: jYbf+7JE/UGH Bruno Barbier writes: >> Fair. Although, it feels like a common use case to replace the region >> with :success value. Maybe the library should provide some ready-to-use >> functions that can be used as the value of :on-outcome. > > I've recycled the old function used by `org-pending-user-edit', > improved it and made it the default :on-outcome handler: see > `org-pending-on-outcome-replace'. I've simplified the example > accordingly, removing the custom :on-outcome. Thanks! I have one suggestion though. You now do Use the function ON-OUTCOME to update the region with the outcome; if it is nil, set it to the function `org-pending-on-outcome-replace'. However, `org-pending' is defined via `cl-defun', so you can instead just put the default value for :on-outcome key and mention that it is the default in the docstring. Then, you do not need to do any additional checks in the function body; `cl-defun' will take care about assigning the default value. > From the many examples provided in the branch, do you see any that > should be included in the library as an other precooked-wrapper, that > should be included in the section "Basic use of locks" ? Not sure (I did not look deep into the implementation yet to keep my perspective closer to end user who first encountered the library) As a general rule, we should (1) provide simple examples that are easy to understand and copy/paste; (2) not-so-simple, but useful examples that are ready to use in practice. These examples should not be complex either, with all the complexity hidden behind library API (API should be modified if complexity is unavoidable). I tried to run your example and have several observations: 1. On failure, it is not obvious that failure happened: - The failure overlay disappear very quickly, and is not visible at all if I happen to look elsewhere in the buffer. Maybe we can simply keep it and remove the overlay on click - After failure, the "!" fringe indicator is visible, but it is not obvious at all that user can click to get details I first tried to click on the fringe itself to no avail. Then, I randomly clicked on the text and got the description buffer; but that was unexpected - the text I clicked did not have any indication of its "clickability" - neither some kind of underline face, nor an overlay or a mouse hint. 2. I tried to do M-x undo while the reglock was active, and got an error. I'd expect that undo would work, skipping the region. 3. I tried M-x undo _after_ reglock was unlocked, and I got "TO REPLACE" word highlighted. I did not expect it to be highlighted. 4. If I try to cancel the reglock, it does get canceled, but *Region Lock* buffer is not updated - Live? still displays "yes Cancel". >> What is the difference between "canceling" and "killing" the reglock? >> Do they need to be separate? > > If you cut out, from the example, the part where they differ, they do > look the same indeed :) > > I'm apparently failing to explain and document this correctly, as it > looks like a recurring topic, sorry. > > Yes, they need to be separate as they are two different operations. > > - cancel: The *user* may request a *cancel*; it's a polite way to > tell org-pending that the user doesn't care anymore about the > outcome. A valid implementation is to ignore the user request. > The default implementation is to unlock the region (sending a > cancel :failure using 'org-pending-send-update'): it unlocks the > region, ignoring why it was locked.. > > - kill: *Emacs* may have to *kill* some locks, because Emacs is > killed, or the lock buffer is killed. org-pending will intercept > the operations of this kind, ask the user to confirm the > destruction, and, if confirmed, it will give a chance to the lock > to do some cleanup by calling the 'before-kill-function'. Does it mean that clicking "cancel" does not guarantee that the region will not be updated by the running process/timer? In my eyes, there is no difference between user request and "kill". If users asks things to stop, no modifications should be allowed to the region. > I modified the example to rely on the reglock when possible (as > opposed to values kept from the creation time). I tried to simplify your example as the following: (cl-defstruct my/counter (state 0) timer) (defun my/counter-update (counter reglock &optional force-landing) "Increase COUNTER and send update to REGLOCK. At the end of sequence, cancel COUNTER timer. When FORCE-LANDING is symbol `land', report :success \"Landed early\" and cancel the timer." (org-pending-send-update reglock (pcase (my/counter-state counter) ((guard (eq force-landing 'land)) (when (timerp (my/counter-timer counter)) (cancel-timer (my/counter-timer counter))) '(:success "Landed early")) ((guard (eq force-landing 'crashed)) (when (timerp (my/counter-timer counter)) (cancel-timer (my/counter-timer counter))) '(:failure "Crashed")) (0 '(:progress "Taking off...")) (1 '(:progress "Flying...")) (2 '(:progress "Landing...")) (_ (when (timerp (my/counter-timer counter)) (cancel-timer (my/counter-timer counter))) (if (= 0 (random 2)) '(:success "Landed successfully") '(:failure "Landing malfunction"))))) (cl-incf (my/counter-state counter))) (let ((lock-buffer (generate-new-buffer "*Pending region example*")) reglock state) (with-current-buffer lock-buffer (insert " Buffer displaying pending content. OUTPUT>>> TO REPLACE <<. Support Org development at , or support my work at