emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@posteo.net>
To: Bruno Barbier <brubar.cs@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
	Jack Kamm <jackkamm@gmail.com>, Matt <matt@excalamus.com>
Subject: Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...))
Date: Sun, 19 May 2024 09:39:18 +0000	[thread overview]
Message-ID: <8734qe5eex.fsf@localhost> (raw)
In-Reply-To: <6640f1aa.df0a0220.9356.9ce8@mx.google.com>

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

> I've pushed the modification to my branch.

Thanks! Let's work further on the top comment.

> ;; To lock a region, you need to do something like this:

I think "something like this" can be just dropped.

> ;;    1. Call the function `org-pending' with the region to lock; use
> ;;       the ON-OUTCOME argument to tell Emacs how to update the
> ;;       region.  Keep the returned REGLOCK (you'll need it to send
> ;;       updates).

It would be nice to provide examples of `org-pending' call right in the
top comment. Ideally, the example should also show how to modify REGLOCK
fields to customize its behaviour.

> ;;    2. Start "something" that computes the new content.  That
> ;;       "something" may be a thread, a timer, a notification, a
> ;;       process, etc.  That "something" must eventually send a
> ;;       :success or :failure message (using
> ;;       `org-pending-send-update'): Emacs will update the pending
> ;;       region (using your ON-OUTCOME) and unlock it; at this point
> ;;       the lock is "dead" (not live-p).

Please also add information about sending updates to the REGLOCK, with
examples. Otherwise, "receiving progress" in the next section is
surprising.

> ... (not live-p)

Please name `org-pending-reglock-live-p' - it is more clear than forcing
the readers search it themselves.

> ;;;; Interface provided to the Emacs user
> ;;
> ;; The library makes locks visible to the user using text properties
> ;; and/or overlays.  It diplays and updates the status while the
> ;; region is locked: the initial status is "scheduled", then, when

It would be nice to name `org-pending-reglock-status' here and use the
actual status values - :scheduled, :pending, :success, :failure.
Ideally, in table/list explaining what happens with buffer text,
overlays, and user interaction, when REGLOCK has each of the listed
status values.

> ;; receiving progress it becomes "pending" (with progress information
> ;; if any).  Emacs allows to diplay a description of the lock.  From
> ;; that description, the user may request to cancel that lock; see the
> ;; field `user-cancel-function' of the REGLOCK object if you need to
> ;; customize what to do on cancel.

It is not very clear how user can interact with "description". Is it a
tooltip? A window? Something else? Please give a bit more details.

Also, when "cancel" is requested, it is a good idea to state that
`user-cancel-function' is called and describe what it does by default.

> ;; When receiving the outcome (success or failure), after unlocking
> ;; the region, the library may leave information about the outcome

"may"?? Or does it always leave the information (by default)?

> ;; (using text properties/overlays).  If that outcome information is
> ;; (still) displayed, Emacs allows to display a description of that
> ;; lock.  From that description, the user may decide to "forget" that
> ;; lock; "forgetting the lock" removes the outcome visual marks, and,

Is "forgetting" customizeable like `user-cancel-function'?

> ;; it allows Emacs to discard any information related to this lock.

What does it mean?

> ;; The description of a lock (live or dead) provides information like
> ;; the schedule time, the duration, the outcome time, the result (in
> ;; case of success), the error (in case of failure), etc.  Customize
> ;; the field `insert-details-function' of REGLOCK object to add your
> ;; own information.

Please show an example how to do it here.

> ;; If the user kills a buffer, or, kills Emacs, some locks may have to
> ;; be killed too be killed too.  The library will ask the user to
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
typo

> ;; confirm if an operation requires to kill some locks.  See the field
> ;; `before-kill-function' of REGLOCK object, if you need to do
> ;; something before a lock is really killed.

Again, an example would be helpful.

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


  reply	other threads:[~2024-05-19  9:38 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 [this message]
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                                                                   ` Pending contents in org documents Bruno Barbier
2024-06-03 11:04                                                                     ` 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=8734qe5eex.fsf@localhost \
    --to=yantar92@posteo.net \
    --cc=brubar.cs@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=jackkamm@gmail.com \
    --cc=matt@excalamus.com \
    /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).