[elpa] externals/tmr 2938857a93 2/3: Update docs, especially for tmr-tabulated-view

[ELPA Syncer]

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

    Update docs, especially for tmr-tabulated-view
    
    Thanks again to Damien Cassou for all the contributions thus far.
---
 README.org | 64 +++++++++++++++++++++++++++++++++++++++++++++++---------------
 tmr.el     | 44 +++++++++++++++++++++++++++++++-----------
 2 files changed, 82 insertions(+), 26 deletions(-)

diff --git a/README.org b/README.org
index 13918f4fff..ee517c3777 100644
--- a/README.org
+++ b/README.org
@@ -24,8 +24,8 @@
 #+texinfo_header: @set MAINTAINERCONTACT 
@uref{mailto:info@protesilaos.com,contact the maintainer}
 
 This manual, written by Protesilaos Stavrou, describes the customization
-options for =tmr= (or =tmr.el=, tmr, TMR, ...), and provides every other
-piece of information pertinent to it.
+options for =tmr= (or =tmr.el=, tmr, TMR, TMR May Ring, ...), and
+provides every other piece of information pertinent to it.
 
 The documentation furnished herein corresponds to stable version
 {{{stable-version}}}, released on {{{release-date}}}.  Any reference to
@@ -38,6 +38,9 @@ Current development target is {{{development-version}}}.
 + Git repository: https://git.sr.ht/~protesilaos/tmr.
 + Mailing list: https://lists.sr.ht/~protesilaos/tmr.
 
+TMR has benefited from major contributions by Damien Cassou, to whom I
+am most thankful.
+
 #+toc: headlines 8 insert TOC here, with eight headline levels
 
 * COPYING
@@ -67,10 +70,10 @@ modify this GNU manual.”
 
 #+findex: tmr
 TMR is an Emacs package that provides facilities for setting timers
-using a convenient notation.  The 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.  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:
 
 | Input | Meaning   |
 |-------+-----------|
@@ -113,11 +116,40 @@ be played.
 
 #+findex: tmr-cancel
 The ~tmr-cancel~ command is used to cancel running timers (as set by the
-~tmr~ command).  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~ accepts.
+~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 about the grid view is part of
+  {{{development-version}}} ]
+
+#+findex: tmr-tabulated-view
+Active timers can be viewed in a grid with ~tmr-tabulated-view~ (part of
+the =tmr-tabulated.el= file, whose main author is Damien Cassou).  The
+grid is placed in the =*tmr-tabulated-view*= buffer and looks like this:
+
+#+begin_example
+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
+#+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.
+
+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.
+
+#+findex: tmr-tabulated-cancel
+While in this grid view, the =k= key runs the ~tmr-tabulated-cancel~
+command.  It immediately cancels the timer at point.
 
 * Installation
 :PROPERTIES:
@@ -181,14 +213,16 @@ Everything is in place to set up the package.
 (setq tmr-sound-file
       "/usr/share/sounds/freedesktop/stereo/alarm-clock-elapsed.oga")
 
+(setq tmr-notification-urgency 'normal)
+(setq tmr-descriptions-list (list "Boil water" "Prepare tea" "Bake bread"))
+
 ;; OPTIONALLY set global key bindings:
 (let ((map global-map))
-  (define-key map (kbd "C-c t t") #'tmr) ; or use the command 
`tmr-with-description'
+  (define-key map (kbd "C-c t t") #'tmr)
+  (define-key map (kbd "C-c t T") #'tmr-with-description)
   (define-key map (kbd "C-c t e") #'tmr-view-echo-area-messages) ; "e" to 
remind of C-h e
+  (define-key map (kbd "C-c t l") #'tmr-tabulated-view) ; "list timers" 
mnemonic
   (define-key map (kbd "C-c t c") #'tmr-cancel))
-
-;; Also check the user options `tmr-notification-urgency'
-;; `tmr-descriptions-list'.
 #+end_src
 
 * Acknowledgements
diff --git a/tmr.el b/tmr.el
index 39b8705af2..f43b791ea0 100644
--- a/tmr.el
+++ b/tmr.el
@@ -28,10 +28,10 @@
 ;;; Commentary:
 ;;
 ;; TMR is an Emacs package that provides facilities for setting timers
-;; using a convenient notation.  The 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.  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:
 ;;
 ;; | Input | Meaning   |
 ;; |-------+-----------|
@@ -52,8 +52,8 @@
 ;; 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.  Though TMR provides its own buffer for
-;; reviewing its log: it is named =*tmr-messages*= and can be accessed with
+;; bound to `C-h e' by default.  Though TMR provides its own buffer for
+;; reviewing its log: it is named `*tmr-messages*' and can be accessed with
 ;; the command `tmr-view-echo-area-messages'.
 ;;
 ;; Once the timer runs its course, it produces a desktop notification and
@@ -68,11 +68,33 @@
 ;; be played.
 ;;
 ;; The `tmr-cancel' command is used to cancel running timers (as set by the
-;; `tmr' command).  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' accepts.
+;; `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.
+;;
+;; Active timers can be viewed in a grid with `tmr-tabulated-view' (part of
+;; the `tmr-tabulated.el' file, whose main author is Damien Cassou).  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 `k' key runs the `tmr-tabulated-cancel'
+;; command.  It immediately cancels the timer at point.
 
 ;;; Code: