[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/tmr df9c3000cc 2/3: Rewrite and expand the docs
From: |
ELPA Syncer |
Subject: |
[elpa] externals/tmr df9c3000cc 2/3: Rewrite and expand the docs |
Date: |
Sun, 15 May 2022 05:57:51 -0400 (EDT) |
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: