From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id wNLWIoyHimYv6wAAe85BDQ:P1 (envelope-from ) for ; Sun, 07 Jul 2024 12:18:20 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id wNLWIoyHimYv6wAAe85BDQ (envelope-from ) for ; Sun, 07 Jul 2024 14:18:20 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=RL5K9OVi; 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=1720354404; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=LndzO+nxEusts6nB2ejSJhKlOs3fQR37+sfErA1/bfE=; b=RO0IY1ZP5oAHwAl5tz9gODHPUcbZv6EWJgS6gvGpaKhhj1bNWJ2QQ4Tp8+Bjd8RB+XwEjt VI/wWUvjU3yeiF4/XIMDS3J68DO/nOzJ5GtQN3eAscE4myJe0bEaKp0fCshBbDUn2SluPQ yg9ZnKeWyoLtYUvkTRgaTIlYyt0lnzx/gGiKoSIl66NgaKquqRRqhnAIICkFqnFEkCGbmp NtxctxP/M+j6ZlcFdC1C0eWmOISIcp1WKqR5+Hb5yBD2rgO0XOxXB3QLdN1svZTOR82rdY u8QmlerjAXVxfDOw5EfJZkhpwH2tHARrzB+i3uMY689bCvnVr6QCP76idVhXTg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=RL5K9OVi; 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=1720354404; a=rsa-sha256; cv=none; b=gRs5sfmrfKIZ+atK4sDFwIG/5Us1uR4OxWneNNditX4l4DFUpexX1DVVtZbFrfWEaSkh1N GBbU/fWWbEnX3UN0HhKTZRtZLJC3+1JQRjyTlNJoDDQOuOpMbRNjIulYJ8R6ZVeJGGZmqe fWfXBwkzEJltEPa3th4efaxh0NtbfH29vsbph38o6ScyG1xeb8EfCopSEmykNfyN2Lb8nc lb+VgFuPj7cBQ5zZeKiHHa+B7pX24NgNyic/sFAB0+BCiEVTySty2XyyO+PnpmaZyv7o71 ouVrmgxoL9z80CNKi7o/exBzoqBiyQjQ/4W7UNXDQDXhT5RPJcEoe2nGqNBnEw== 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 A88D97A4E8 for ; Sun, 7 Jul 2024 14:13:23 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sQQkZ-0004Ug-9u; Sun, 07 Jul 2024 08:12:15 -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 1sQQkW-0004TF-RJ for emacs-orgmode@gnu.org; Sun, 07 Jul 2024 08:12:12 -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 1sQQkS-0007bx-03 for emacs-orgmode@gnu.org; Sun, 07 Jul 2024 08:12:12 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 16111240104 for ; Sun, 7 Jul 2024 14:12:02 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1720354323; bh=rIDHfCvnDXaz3JsPx1r/jirfYM3qZs1fxTcfVKnRVts=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: Content-Transfer-Encoding:From; b=RL5K9OVizQ6awokB1ze+JyiFSNANtLrcK6WSmMptIG20+ixcZQwC5bij/XfVun4xS neMmTvSsgLSVOshc9bNZ96fSXVkfjkESWfdg/6Bb0zifh4wDtBD2vhV33+YqkULhUV cZe8ki9/vU2HJj3WGZxQfjEl54VTrvjvSLj/iXiC9WV+j/JPgPLaa6kP1B2iyZjkcC p8rfxft1TFBXtBn5wYcVh+eqJSVoG2ZOEyMpGr5+OPBCFNwOSfrXhgSl/DT/Y7qQTE cTNNkl5iNL6bwbIkMVeDaS78YO0+5hR6W3enWtGFzZkjsKZsdWOe5qncFLY3Swmhvm dFmQE1bZtraiA== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4WH5hx4LcTz6tvh; Sun, 7 Jul 2024 14:12:01 +0200 (CEST) From: Ihor Radchenko To: Bruno Barbier Cc: emacs-orgmode , Jack Kamm , Matt Subject: Re: Pending contents in org documents In-Reply-To: <668a5cc4.df0a0220.11fdd.05c1@mx.google.com> References: <87o7d0mm54.fsf@localhost> <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> <87plsyz3rn.fsf@localhost> <666d4779.050a0220.13efd.8a2d@mx.google.com> <87ed8xi688.fsf@localhost> <668a5cc4.df0a0220.11fdd.05c1@mx.google.com> Date: Sun, 07 Jul 2024 12:13:37 +0000 Message-ID: <87msmtflhq.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.posteo.de 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, 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-Country: US X-Migadu-Flow: FLOW_IN X-Spam-Score: -8.11 X-Migadu-Queue-Id: A88D97A4E8 X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -8.11 X-TUID: ZmbrQXLej5vZ Bruno Barbier writes: > I've just pushed a new version. Thanks! > I added a function 'org-pending-unlock-NOW!' which unlock the region > immediately. The uppercase "NOW!" emphasizes that it's not the > "safe" way to unlock a region. I expect to see this function called by some kind of button in the details buffer, so that users can actually call it. Also, a few more small comments on the commentary section: > ;; The library makes locks visible to the user using text properties > ;; and/or overlays. It diplays and updates the status while the * displays > ;; If the user kills a buffer, or, kills Emacs, some locks may have to > ;; be destroyed. The library will ask the user to confirm if an > ;; operation requires to destroy some locks. See the field > ;; `before-destroy-function' of REGLOCK object, if you need to do > ;; something before a lock is destroyed. We should provide a user option to suppress the query. Something like what `confirm-kill-processes' does. Maybe even support something akin `process-query-on-exit-flag', but for reglocks. > ... feel free to look at the docstrings of the > ;; cl-defstruct `org-pending-reglock' for the full documentation. Maybe better refer to M-x cl-describe-type org-pending-reglock. It will look nicer. --- I have no other comments on your replies, so I am proceeding with the code review. Next step is focusing on the core API functions :) > (cl-defun org-pending (region > ... > On receiving the outcome (a :success or :failure message, sent with > `org-pending-send-update'), remove the region protection. Call > ON-OUTCOME with the reglock and the outcome, from the position from > where the REGLOCK was created. If ON-OUTCOME returns a region (a > pair (start position . end position)), use it to report the > success/failure using visual hints on that region. If ON-OUTCOME > returns nothing, don't display outcome marks. Please describe what the default value of ON-OUTCOME (when ON-OUTCOME is not explicitly provided) does right in the docstring. > You may set/update the following fields of your reglock to customize its > behavior: > - Emacs may have to destroy your locks; see the field > `before-destroy-function' if you wish to do something before your > lock is destroyed. > - The user may ask Emacs to cancel your lock; see the field > `user-cancel-function' to override the default cancel function. > - The user may request a description of the lock; see the the field > `insert-details-function' to add custom information when your > lock is displayed to the user. >=20 > You may add/update your own properties to your reglock using the field > `properties', which is an association list. Here, we may also refer to cl-describe-type for more details about the fiel= ds. > ( user-cancel-function nil > :documentation > "Function called when the user wish to cancel this REGLOCK, > with the REGLOCK as argument. This function must return immediately; it > may, asynchronously, stop some processing and release resources; and, > once this is done, it should send the outcome to the REGLOCK (using > `org-pending-send-update', so that the region is unlocked and the > REGLOCK destroyed). The default value is > `org-pending--user-cancel-default'" ) How come the default value is `org-pending--user-cancel-default' when it is nil? > (cl-defstruct (org-pending-reglock > ... It would be nice to define slot types for each slot. > insert-details-function nil > When non-nil, function called to insert custom details at the end of > =E2=80=98org-pending-describe-reglock=E2=80=99. The function is call= ed with a REGLOCK, > a START position and an END position, it must insert details at > point. Assuming B is a (virtual) buffer containing all detailed human > readable information, insert at point details from START to END. Han= dle > cases where START, END are nil or out of bounds without raising an > error. The function may use text properties, overlays, etc. See > =E2=80=98org-pending-describe-reglock=E2=80=99 >From this description, my understanding is that the existing text between START and END must be replaced? Or is it something else? It is also not clear what the custom function is supposed to do when START/END are nil. I looked up the docstring of `org-pending-describe-reglock', but it does not contain anything useful wrt setting insert-details-function slot. --=20 Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at