Re: Pending contents in org documents

[Ihor Radchenko <yantar92@posteo.net>]

Bruno Barbier <brubar.cs@gmail.com> 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

<<<OUTPUT
More text.
")

    (goto-char (point-min))
    (re-search-forward "TO REPLACE")

    ;; We lock the 'region', defining how to update it when the
    ;; outcome is available.
    (setq reglock (org-pending (cons (match-beginning 0) (match-end 0))))

    (pop-to-buffer lock-buffer)

    (setq state (make-my/counter))
    ;; We create a timer to update our state every few seconds.
    (setf (my/counter-timer state)
	  (run-with-timer 2 2 #'my/counter-update state reglock)))

  (setf (org-pending-reglock-user-cancel-function reglock)
        `(lambda (rlock)
           (warn "Initiating emergency landing...")
           (sleep-for 1)
           (my/counter-update ,state rlock 'land)
           (warn "Initiating emergency landing... done")))

  (setf (org-pending-reglock-before-kill-function reglock)
        `(lambda (_rlock)
           (cancel-timer (my/counter-timer ,state))
           (warn "Transponder signal lost")))

  (setf (org-pending-reglock-insert-details-function reglock)
        `(lambda (rlock _start _end)
           (insert (format "State: %s\n"
                           (my/counter-state ,state)))))

  )

In the above, it is not fully clear for me what BEG and END arguments in
`org-pending-reglock-insert-details-function' mean and where the
insertion happens.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>