Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...))

[Ihor Radchenko <yantar92@posteo.net>]

Bruno Barbier <brubar.cs@gmail.com> writes:

> Thanks for the review.
>
> I've pushed a new version, hoping to decrease the number of dislikes
> ;-)

Thanks!

>>> Cancel is handled by sending a failure message (see
>>>  `org-pending-cancel').  It's customizable using the reglock field
>>>  ~org-pending-reglock-user-cancel-function~, which can decide what to
>>>  do (like kill a process) and which can send a better outcome.
>>>  Standard 'cancel' leaves a failure outcome mark.
>>
>> Note that this function is not documented anywhere other than in reglock
>> class documentation.
>
> Thanks. I've improved the documentation of `org-pending' to mention
> that one may want to customize the following fields of a reglock:
> before-kill-function, user-cancel-function and
> insert-details-function.  And, also, I added that one can attach
> custom properties using the "properties" field.

Thanks, but I still feel confused.
May you:

1. Explain what does "kill" and "cancel" mean in the context of the
   REGLOCK.

2. Add information about visual hints, "kill", and "cancel" to the
   top-level commentary.

For now, when reading the top commentary:

    ;; This library contains an API to lock a region while it is "being
    ;; updated"; the content of the region is "pending" and cannot be
    ;; modified.  It will be updated, later, when the new content is
    ;; available.

I have an impression that the only side effect of "locking" is that the
region becomes read-only. It is not clear at all that any other
visual indication will be provided.

>> In general, I am confused about your overall design
>> of the user interaction with the locks.
>> The updated top commentary explains well how Elisp programs can send
>> data to the locks, but it does not say anything about how Elisp programs
>> can receive the data.
>
> An elisp program, that uses org-pending, must update the locks using
> `org-pending-send-update'.  That program does not receive any data
> from the lock; it may customize Emacs behavior using the reglock
> fields mentioned above: before-kill-function, user-cancel-function and
> insert-details-function.
>
> Hopefully, it's clearer now with the improved documentation of the
> org-pending function.
>
> Just let me know if you still think that the top commentary should
> explain this.  Thanks.

Yes, I do think that top commentary should explain this.
The very idea that lock may be "canceled" or "killed" is important when
designing Elisp code that uses the org-pending library.

>> Also, I'd like to see more information in the top commentary about what
>> are the "visual hints" displayed to the user and how to configure them.
>
> If you think the current "visual hints" are good enough and could be
> shipped as-is, in a first version (indirect buffers, etc.); I could
> work on documenting them better.  What kind of configuration are you
> thinking about ? just the faces ? or more advanced configurations ?

I am not thinking about details yet.
I just want insert-details-function to be described in the top
commentary. At high level. Something like


* Visual indication of the "pending" regions

While the region is locked, it is visually highlighted in the buffer,
providing information about the lock status as an overlay. The status
can be:

1. :scheduled - the region is "being updated", but the computation has
   not yet started.
2. :progress  - the computation is in progress

After unlocking the region, the visual indication is not necessarily
removed. Instead, the outcome is indicated in an overlay. The outcome
may be:

1. :success - the computation has been successful and the region text
   has been updated
2. :failure - the computation failed

The lock status is updated according to the data submitted to REGLOCK
object via `org-pending-send-update'.

* User interaction with pending regions

For any pending region, users may request detailed description to be
displayed. The description includes the pending region status, creation
time, outcome, duration, results, errors, etc.

Elisp code using this library may also supply additional details about
any given reglock, via `insert-details-function' field of REGLOCK
object. For example, process logs can be displayed this way.

--------

I hope that the above clarifies what I am looking for.

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