[elpa] externals/tmr df9c3000cc 2/3: Rewrite and expand the docs

[ELPA Syncer]

branch: externals/tmr
commit df9c3000cc466f449450022f84f43e9bed1133ce
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Rewrite and expand the docs
    
    This should cover all the recent changes we made.
---
 README.org          | 151 ++++++++++++++++++++++++++++++++++++++--------------
 tmr-notification.el |   9 +++-
 tmr-sound.el        |   5 +-
 tmr-tabulated.el    |   3 ++
 tmr.el              |  81 ++--------------------------
 5 files changed, 128 insertions(+), 121 deletions(-)

diff --git a/README.org b/README.org
index 12b2c38b46..ad122a8a9f 100644
--- a/README.org
+++ b/README.org
@@ -70,7 +70,8 @@ TMR is an Emacs package that provides facilities for setting 
timers
 using a convenient notation.  The first point of entry is the ~tmr~
 command.  It prompts for a unit of time, which is represented as a
 string that consists of a number and, optionally, a single character
-suffix which specifies the unit of time.  Valid input formats:
+suffix which specifies the unit of time.  Without a suffix, the number
+is interpreted as a count in minutes.  Valid input formats:
 
 | Input | Meaning   |
 |-------+-----------|
@@ -79,53 +80,59 @@ suffix which specifies the unit of time.  Valid input 
formats:
 | 5s    | 5 seconds |
 | 5h    | 5 hours   |
 
+The input can be a floating point:
+
+| Input | Meaning                  |
+|-------+--------------------------|
+| 1.5   | 1.5 minutes (90 seconds) |
+| 1.5h  | 1.5 hours (90 minuts)    |
+
 #+vindex: tmr-descriptions-list
-If ~tmr~ is called with an optional prefix argument (=C-u=), it also
-asks for a description which accompanies the given timer.  Preconfigured
-candidates are specified in the user option ~tmr-descriptions-list~,
-though any arbitrary input is acceptable at the minibuffer prompt.
+If ~tmr~ is called with an optional prefix argument (=C-u=), it asks for
+a description to accompany the given timer.  Preconfigured candidates
+are specified in the user option ~tmr-descriptions-list~, though any
+arbitrary input is acceptable at the minibuffer prompt.
 
 #+findex: tmr-with-description
 An alternative to the ~tmr~ command is ~tmr-with-description~.  The
 difference between the two is that the latter always prompts for a
 description.
 
-#+findex: tmr-view-echo-area-messages
 When the timer is set, a message is sent to the echo area recording the
 current time and the point in the future when the timer elapses.  Echo
 area messages can be reviewed with the ~view-echo-area-messages~ which
 is bound to =C-h e= by default.  To check all timers, use the command
-~tmr-tabulated-view~, which is described further below.
+~tmr-tabulated-view~ ([[#h:51fe78e0-d614-492b-b7a3-fb6d5bd52a9a][About 
tmr-tabulated]]).
 
-#+vindex: tmr-sound-file
-#+vindex: tmr-notification-urgency
-Once the timer runs its course, it produces a desktop notification and
-plays an alarm sound.  The notification's message is practically the
-same as that which is sent to the echo area.  The sound file for the
-alarm is defined in ~tmr-sound-file~, while the urgency of the
-notification can be set through the ~tmr-notification-urgency~ option.
-Note that it is up to the desktop environment or notification daemon to
-decide how to handle the urgency value.
-
-If the ~tmr-sound-file~ is nil, or the file is not found, no sound will
-be played.
+[ The following are part of {{{development-version}}}. ]
 
 #+findex: tmr-cancel
 The ~tmr-cancel~ command is used to cancel running timers (as set by the
 ~tmr~ or ~tmr-with-description~ commands).  If there is only one timer,
-it cancels it outright.  If there are multiple timers, it produces a
-minibuffer completion prompt which asks for one among them.  Timers at
-the completion prompt are described by the exact time they were set and
-the input that was used to create them, including the optional
-description that ~tmr~ and ~tmr-with-description~ accept.
-
-[ The following information is part of {{{development-version}}}.  Some
-  things may still change. ]
+it cancels it outright.  If there are multiple running timers, it
+produces a minibuffer completion prompt which asks for one among them.
+Timers at the completion prompt are described by the exact time they
+were set and the input that was used to create them, including the
+optional description that ~tmr~ and ~tmr-with-description~ accept.
 
 #+findex: tmr-clone
-An existing timer can be cloned with the ~tmr-clone~ command.  It copies
-the duration and optional description of an existing timer into a new
-one.
+A timer can be cloned with the ~tmr-clone~ command.  It directly copies
+the duration and optional description of a timer into a new one.  With
+an optional prefix argument, this command prompts for a duration and, if
+the underlying timer had a description, for a description as well.  The
+default values of such prompts as those of the original timer.
+
+Timers have hooks associated with their creation, cancellation, or
+completion ([[#h:c908f440-da08-462e-be4e-a61fb274ecbc][Hooks]]).  TMR can also 
integrate with the desktop environment
+to send notifications ([[#h:56bbbd6f-5b63-4375-9c86-e1eb231be356][Sound and 
desktop notifications]]).
+
+** About tmr-tabulated
+:PROPERTIES:
+:CUSTOM_ID: h:51fe78e0-d614-492b-b7a3-fb6d5bd52a9a
+:END:
+#+cindex: About tmr-tabulated and relevant commands
+
+[ Part of {{{development-version}}}. ]
 
 #+findex: tmr-tabulated-view
 Active timers can be viewed in a grid with ~tmr-tabulated-view~ (part of
@@ -139,29 +146,93 @@ Start      End        Finished?  Description
 12:26:26   12:36:26              Prepare tea
 #+end_example
 
-If a timer has elapsed, it has a check mark, otherwise the =Finished?=
-column is empty.  A =Description= is shown only if it is provided while
-setting the timer, otherwise the field is left blank.
+If a timer has elapsed, it has a check mark associated with it,
+otherwise the =Finished?= column is empty.  A =Description= is shown
+only if it is provided while setting the timer, otherwise the field is
+left blank.
 
 The ~tmr-tabulated-view~ command relies on Emacs' ~tabulated-list-mode~.
 From the =*tmr-tabulated-view*= buffer, invoke the command
-~describe-mode~ to learn about the applicable key bindings, such as how
-to expand/contract columns and toggle their sort.
+~describe-mode~ to learn about the generic applicable key bindings, such
+as how to expand/contract columns and toggle their sort.
 
-While in this grid view:
+While in this grid view, one can perform several operations on timers:
 
 + The =+= key creates a new timer by calling the standard ~tmr~ command.
   As always, use a prefix argument to also prompt for a description.
 
-#+findex: tmr-tabulated-cancel
-+ The =c= key invokes the ~tmr-tabulated-cancel~ command.  It is the
-  same as the aforementioned ~tmr-cancel~ plus some tweaks for the grid
-  view.
+#+findex: tmr-tabulated-clone
++ The =c= key invokes the ~tmr-tabulated-clone~ command.  It is the same
+  as ~tmr-clone~ plus some tweaks for the grid view.
 
 #+findex: tmr-tabulated-cancel
 + The =k= key runs the ~tmr-tabulated-cancel~ command.  It immediately
   cancels the timer at point.
 
+#+findex: tmr-tabulated-reschedule
++ The =s= key runs the ~tmr-tabulated-reschedule~ command.  It
+  effectively replaces the timer at point with a new one, using the
+  aforementioned "cancel" and "clone" operations.  If the timer being
+  rescheduled has a description, this command will also prompt for a
+  description while creating the new timer, otherwise it will just ask
+  for a duration.
+
+#+findex: tmr-tabulated-rewrite-description
++ The =w= key invokes the ~tmr-tabulated-rewrite-description~ command.
+  It prompts for user input and uses it to rewrite the description of
+  the timer at point.
+
+** Hooks
+:PROPERTIES:
+:CUSTOM_ID: h:c908f440-da08-462e-be4e-a61fb274ecbc
+:END:
+#+cindex: Hooks triggered by timer operations
+
+TMR provides the following hooks:
+
+#+vindex: tmr-timer-created-functions
++ ~tmr-timer-created-functions~ :: This is triggered by the ~tmr~
+  command.  By default, it will print a message in the echo area showing
+  the newly created timer's start and end time as well as its optional
+  description (if provided).
+
+#+vindex: tmr-timer-completed-functions
++ ~tmr-timer-completed-functions~ :: This runs when a timer elapses.  By
+  default, it will (i) produce a desktop notification which describes
+  the timers start/end time and optional description (if available),
+  (ii) play an alarm sound ([[#h:56bbbd6f-5b63-4375-9c86-e1eb231be356][Sound 
and desktop notifications]]), and (iii)
+  print a message in the echo area which is basically the same as the
+  desktop notification.
+
+#+vindex: tmr-timer-cancelled-functions
++ ~tmr-timer-cancelled-functions~ :: This is called by ~tmr-cancel~.  By
+  default, it will print a message in the echo area describing the timer
+  that was cancelled.
+
+** Sound and desktop notifications
+:PROPERTIES:
+:CUSTOM_ID: h:56bbbd6f-5b63-4375-9c86-e1eb231be356
+:END:
+#+cindex: Alarm sound and settings for desktop notifications
+
+#+vindex: tmr-sound-file
+#+vindex: tmr-notification-urgency
+Once the timer runs its course, it produces a desktop notification and
+plays an alarm sound.  The notification's message is practically the
+same as that which is sent to the echo area.
+
+The sound file for the alarm is defined in ~tmr-sound-file~, while the
+urgency of the notification can be set through the user option
+~tmr-notification-urgency~.  Note that it is up to the desktop
+environment or notification daemon to decide how to handle the urgency
+value.
+
+If the ~tmr-sound-file~ is nil, or the file is not found, no sound will
+be played.
+
+Sound playback depends on the =ffplay= executable which is part of
+=ffmpeg=.
+
 * Installation
 :PROPERTIES:
 :CUSTOM_ID: h:46378bdf-f6cc-469e-b0b0-1b90dd9aa595
diff --git a/tmr-notification.el b/tmr-notification.el
index 0420be643b..1764007f52 100644
--- a/tmr-notification.el
+++ b/tmr-notification.el
@@ -28,8 +28,13 @@
 ;;; Commentary:
 ;;
 ;; Provides a function to display a desktop notification.  This is
-;; useful to get a passive popup when a timer completes.  Read
-;; (info "(elisp) Desktop Notifications") for details.
+;; useful to get a passive popup when a timer completes.
+;;
+;; Please read the manual for all the technicalities.  Either evaluate
+;; (info "(tmr) Top") or visit <https://protesilaos.com/emacs/tmr>.
+;;
+;; Developers can also read (info "(elisp) Desktop Notifications") for
+;; details.
 
 ;;; Code:
 (require 'tmr)
diff --git a/tmr-sound.el b/tmr-sound.el
index be279e02d1..53c99559b9 100644
--- a/tmr-sound.el
+++ b/tmr-sound.el
@@ -30,9 +30,12 @@
 ;; Provides a function to play a configurable sound file.  This is
 ;; useful to get an audio notification when a timer completes.  This
 ;; feature requires "ffplay" (part of ffmpeg) to be in the path.
-
+;;
 ;; Choose the sound file through the `tmr-sound-file' option: if its
 ;; value is nil or if the file is not found, no sound will be played.
+;;
+;; Please read the manual for all the technicalities.  Either evaluate
+;; (info "(tmr) Top") or visit <https://protesilaos.com/emacs/tmr>.
 
 ;;; Code:
 (require 'tmr)
diff --git a/tmr-tabulated.el b/tmr-tabulated.el
index 5ff122fb4d..e99fb9d526 100644
--- a/tmr-tabulated.el
+++ b/tmr-tabulated.el
@@ -31,6 +31,9 @@
 ;; one by line with sortable columns.  Columns show the creation date,
 ;; the end date, a check mark if the timer is finished and the timer's
 ;; optional description.
+;;
+;; Please read the manual for all the technicalities.  Either evaluate
+;; (info "(tmr) Top") or visit <https://protesilaos.com/emacs/tmr>.
 
 ;;; Code:
 
diff --git a/tmr.el b/tmr.el
index 8c90918eba..0a3b10c3c5 100644
--- a/tmr.el
+++ b/tmr.el
@@ -29,85 +29,10 @@
 ;;; Commentary:
 ;;
 ;; TMR is an Emacs package that provides facilities for setting timers
-;; using a convenient notation.  The first point of entry is the `tmr'
-;; command.  It prompts for a unit of time, which is represented as a
-;; string that consists of a number and, optionally, a single character
-;; suffix which specifies the unit of time.  Valid input formats:
+;; using a convenient notation.
 ;;
-;; | Input | Meaning   |
-;; |-------+-----------|
-;; | 5     | 5 minutes |
-;; | 5m    | 5 minutes |
-;; | 5s    | 5 seconds |
-;; | 5h    | 5 hours   |
-;;
-;; If `tmr' is called with an optional prefix argument (`C-u'), it also
-;; asks for a description which accompanies the given timer.  Preconfigured
-;; candidates are specified in the user option `tmr-descriptions-list',
-;; though any arbitrary input is acceptable at the minibuffer prompt.
-;;
-;; An alternative to the `tmr' command is `tmr-with-description'.  The
-;; difference between the two is that the latter always prompts for a
-;; description.
-;;
-;; When the timer is set, a message is sent to the echo area recording the
-;; current time and the point in the future when the timer elapses.  Echo
-;; area messages can be reviewed with the `view-echo-area-messages' which
-;; is bound to `C-h e' by default.  To check all timers, use the command
-;; `tmr-tabulated-view', which is described further below.
-;;
-;; Once the timer runs its course, it produces a desktop notification and
-;; plays an alarm sound.  The notification's message is practically the
-;; same as that which is sent to the echo area.  The sound file for the
-;; alarm is defined in `tmr-sound-file', while the urgency of the
-;; notification can be set through the `tmr-notification-urgency' option.
-;; Note that it is up to the desktop environment or notification daemon to
-;; decide how to handle the urgency value.
-;;
-;; If the `tmr-sound-file' is nil, or the file is not found, no sound will
-;; be played.
-;;
-;; The `tmr-cancel' command is used to cancel running timers (as set by the
-;; `tmr' or `tmr-with-description' commands).  If there is only one timer,
-;; it cancels it outright.  If there are multiple timers, it produces a
-;; minibuffer completion prompt which asks for one among them.  Timers at
-;; the completion prompt are described by the exact time they were set and
-;; the input that was used to create them, including the optional
-;; description that `tmr' and `tmr-with-description' accept.
-;;
-;; An existing timer can be cloned with the `tmr-clone' command.  It copies
-;; the duration and optional description of an existing timer into a new
-;; one.
-;;
-;; Active timers can be viewed in a grid with `tmr-tabulated-view' (part of
-;; the `tmr-tabulated.el' file).  The grid is placed in the
-;; `*tmr-tabulated-view*' buffer and looks like this:
-;;
-;; Start      End        Finished?  Description
-;; 12:26:50   12:51:50   ✔         Update tmr manual
-;; 12:26:35   12:56:35              Bake bread
-;; 12:26:26   12:36:26              Prepare tea
-;;
-;; If a timer has elapsed, it has a check mark, otherwise the `Finished?'
-;; column is empty.  A `Description' is shown only if it is provided while
-;; setting the timer, otherwise the field is left blank.
-;;
-;; The `tmr-tabulated-view' command relies on Emacs' `tabulated-list-mode'.
-;; From the `*tmr-tabulated-view*' buffer, invoke the command
-;; `describe-mode' to learn about the applicable key bindings, such as how
-;; to expand/contract columns and toggle their sort.
-;;
-;; While in this grid view:
-;;
-;; + The `+' key creates a new timer by calling the standard `tmr' command.
-;;   As always, use a prefix argument to also prompt for a description.
-;;
-;; + The `c' key invokes the `tmr-tabulated-cancel' command.  It is the
-;;   same as the aforementioned `tmr-cancel' plus some tweaks for the grid
-;;   view.
-;;
-;; + The `k' key runs the `tmr-tabulated-cancel' command.  It immediately
-;;   cancels the timer at point.
+;; Please read the manual for all the technicalities.  Either evaluate
+;; (info "(tmr) Top") or visit <https://protesilaos.com/emacs/tmr>.
 
 ;;; Code: