emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Bruno Barbier <brubar.cs@gmail.com>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
	Jack Kamm <jackkamm@gmail.com>, Matt <matt@excalamus.com>
Subject: Re: Pending contents in org documents
Date: Sat, 01 Jun 2024 08:28:45 +0200	[thread overview]
Message-ID: <665abf9f.050a0220.d2a6e.ef6b@mx.google.com> (raw)
In-Reply-To: <87jzja71n7.fsf@localhost>


Ihor Radchenko <yantar92@posteo.net> writes:

> Bruno Barbier <brubar.cs@gmail.com> writes:
>
>>>> ;;        (org-pending-send-update my-rlock  (list :progress "Not ready yet."))
>>>> ;;        (org-pending-send-update my-rlock  (list :progress "Coming soon."))
>>>
>>> Should the progress message always be a string?
>>
>> No.  It may currently be any data.  org-pending will format it as a
>> string that fits on one line.
>
> Please say this in the docstring of `org-pending-send-update'.

Done.



>>>> ;;        (org-pending-send-update my-rlock (list :success 1))
>>>
>>> What will org-pending do with :success 1? Will it replace region with
>>> "1" or will it do something else?
>>
>> That's the job on ON-OUTCOME to convert/format/append/prepend/replace
>> some content if needed, on :success and/or on :failure.
>
> 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.

I don't know any safe way to replace some text, but, I hope that will
be a good enough default.



>>> It would be nice to have an example that will also send a signal to
>>> process, as it is probably the most commonly used way to utilize
>>> org-pending.
>>
>> For my many use cases, that would always be a mistake to kill the
>> process: an OS process is always in charge of many locks.
>>
>> More importantly, to find a self-contained working readable example
>> might be a challenge.
>>
>> We could add a function 'org-pending-shell-command-on-region' in
>> org-pending, that could be used as an implementation example, like
>> `org-pending-user-edit', `org-babel-execute-src-block', etc.
>
> Yes, having pre-cooked wrappers for `org-pending' or pre-defined values
> for :on-outcome/:befire-kill-function/:user-cancel-function/etc would be useful.

:on-outcome now has a better default: `org-pending-on-outcome-replace'
(see above).

The predefined values for :before-kill-function and
:user-cancel-function seem OK to me.  We will see, when using
org-pending, if some patterns need to be included in org-pending.

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" ?

I've added 'org-pending-shell-command-on-region' to my todo list.


>
> ;;     ;; We lock the 'region', defining how to update it when the
> ;;     ;; outcome is available.
> ;;     (setq my-lock (org-pending
> ;;                    region
> ;;                    :on-outcome
> ;;                    (lambda (_rl outcome)
> ;;                      (pcase outcome
> ;;                        (`(:success ,value)
> ;;                         ;; On :success, we replace the region with the
> ;;                         ;; value.
> ;;                         (let ((tmp-end (cdr region)))
> ;;                           (goto-char tmp-end)
> ;;                           (insert (format "%s\n" value))
> ;;                           (setcdr region (point))
> ;;                           (delete-region (car region) tmp-end)))
> ;; ...
>
> This example has a major problem if user edits the buffer text _before_
> locked region before the outcome is available.
> (car region) and (cdr region) will no longer be accurate, and your code
> will replace text in places you do not expect.
> I believe that it will be better to query region-lock object about the
> region location where we need to replace text:
>
> (setq region (org-pending-reglock-region rl))
>
> Same for reglock buffer in other examples.
>
> Then, we will keep the possibility open for org-pending to handle cases
> like killing/yanking text containing reglocks (org-refile) - org-pending
> may in future keep track of them.

I see. Good point!

But note that the region is a "read-only constant" field;
archiving/refiling live locks is forbidden.

I modified the example to rely on the reglock when possible (as
opposed to values kept from the creation time).


>
> ;;     (setf (org-pending-reglock-user-cancel-function my-lock)
> ;;           (let ((this-timer my-timer))
> ;;             (lambda (_rl)
> ;;               (cancel-timer this-timer)
> ;; ...
>
> ;;     (setf (org-pending-reglock-before-kill-function my-lock)
> ;;           (let ((this-timer my-timer))
> ;;             (lambda (_rl)
> ;;               (message "Killing %s" this-timer)
> ;;               (cancel-timer this-timer))))
>
> 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'.


I've made some improvements about the kill behaviour and
documentation.

I've pushed my changes to my public branch.

Bruno


  reply	other threads:[~2024-06-01  6:30 UTC|newest]

Thread overview: 73+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-02-01 11:58 [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)] Ihor Radchenko
2024-02-01 14:56 ` Bruno Barbier
2024-02-03  1:30   ` Jack Kamm
2024-02-04 15:07     ` Ihor Radchenko
2024-02-05  1:37       ` Jack Kamm
2024-02-05 14:29         ` Ihor Radchenko
2024-02-06 19:24           ` Bruno Barbier
2024-02-07 16:19             ` Ihor Radchenko
2024-02-07 17:40               ` Bruno Barbier
2024-02-08  3:21             ` Jack Kamm
2024-02-15 20:02             ` Asynchronous blocks for everything (was Re: [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)]) Matt
2024-02-16 17:52               ` Bruno Barbier
2024-02-18 21:14                 ` Matt
2024-02-19  0:31                   ` Jack Kamm
2024-02-20 10:28                   ` Ihor Radchenko
2024-02-20 10:46                     ` tomas
2024-02-20 11:00                       ` Ihor Radchenko
2024-02-20 11:03                         ` tomas
2024-02-21 15:27                   ` Bruno Barbier
     [not found]                   ` <notmuch-sha1-61e086e33bd1faf1a123c1b0353cf2102c71bdac>
2024-02-28 10:18                     ` Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...)) Bruno Barbier
2024-03-02 10:03                       ` Ihor Radchenko
2024-03-02 10:57                         ` Bruno Barbier
2024-03-02 11:13                           ` Ihor Radchenko
2024-03-02 18:06                             ` Bruno Barbier
     [not found]                             ` <notmuch-sha1-d2799a191385bf51811d7788856a83b4f5a1fe3b>
2024-03-07 17:08                               ` Bruno Barbier
2024-03-07 18:29                                 ` Ihor Radchenko
2024-03-08 14:19                                   ` Bruno Barbier
2024-03-13  9:48                                     ` Ihor Radchenko
2024-03-19  9:33                                       ` Bruno Barbier
2024-03-20 10:23                                         ` Ihor Radchenko
2024-03-21 10:06                                           ` Bruno Barbier
2024-03-21 12:15                                             ` Ihor Radchenko
2024-03-25 17:46                                               ` Bruno Barbier
2024-03-27 11:29                                                 ` Ihor Radchenko
2024-03-30 22:53                                                   ` Rudolf Adamkovič
2024-04-04 16:35                                                     ` Bruno Barbier
2024-04-04 16:33                                                   ` Bruno Barbier
2024-04-11 11:44                                                     ` Ihor Radchenko
2024-04-19 11:23                                                       ` Bruno Barbier
2024-04-20 10:07                                                         ` Ihor Radchenko
2024-05-12 16:43                                                           ` Bruno Barbier
2024-05-19  9:39                                                             ` Ihor Radchenko
2024-05-23 16:31                                                           ` Bruno Barbier
2024-05-24  9:49                                                             ` Ihor Radchenko
2024-05-30 19:01                                                               ` Bruno Barbier
2024-05-31  9:48                                                                 ` Ihor Radchenko
2024-06-01  6:28                                                                   ` Bruno Barbier [this message]
2024-06-03 11:04                                                                     ` Pending contents in org documents Ihor Radchenko
2024-06-15  7:49                                                                       ` Bruno Barbier
2024-06-16  9:31                                                                         ` Ihor Radchenko
2024-07-07  9:15                                                                           ` Bruno Barbier
2024-07-07 12:13                                                                             ` Ihor Radchenko
2024-07-18  8:05                                                                               ` Bruno Barbier
2024-07-19 14:23                                                                                 ` Ihor Radchenko
2024-07-31  8:47                                                                                   ` Bruno Barbier
2024-08-02 16:48                                                                                     ` Ihor Radchenko
2024-08-12  7:14                                                                                       ` Bruno Barbier
2024-08-13  9:49                                                                                         ` Ihor Radchenko
2024-02-19  0:15                 ` Asynchronous blocks for everything (was Re: [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)]) Jack Kamm
2024-02-21 15:43                   ` Bruno Barbier
2024-02-19  9:06                 ` Ihor Radchenko
2024-02-19 19:47                   ` Matt
2024-02-19 20:10                     ` Ihor Radchenko
2024-02-20  8:32                     ` Ihor Radchenko
2024-02-20 17:04                     ` Jack Kamm
2024-02-21 16:03                   ` Bruno Barbier
2024-02-23 12:11                     ` Ihor Radchenko
2024-02-23 13:24                       ` Bruno Barbier
2024-02-24 11:59                         ` Ihor Radchenko
2024-02-24 16:42                           ` Bruno Barbier
2024-02-24 19:54                             ` Matt
2024-02-28 10:21                               ` Bruno Barbier
2024-02-08  3:26           ` [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)] Jack Kamm

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=665abf9f.050a0220.d2a6e.ef6b@mx.google.com \
    --to=brubar.cs@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=jackkamm@gmail.com \
    --cc=matt@excalamus.com \
    --cc=yantar92@posteo.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).