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