Re: Pending contents in org documents

[Bruno Barbier]

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