[elpa] externals/tmr 80673d9eb5 1/2: Update docs for Damien Cassou's contributions

[ELPA Syncer]

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

    Update docs for Damien Cassou's contributions
    
    This pertains to commits cbf80ec, cd19c02.  Thanks to Damien for the
    patches!
---
 README.org | 21 +++++++++++++++++----
 tmr.el     | 21 +++++++++++++++++----
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/README.org b/README.org
index 8b805dc4d7..000a2b7362 100644
--- a/README.org
+++ b/README.org
@@ -85,6 +85,11 @@ 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.
 
+#+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
@@ -103,6 +108,9 @@ 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.
+
 #+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
@@ -169,14 +177,18 @@ Everything is in place to set up the package.
 ;; Load the `tmr' library
 (require 'tmr)
 
+;; set to nil to disable the sound
+(setq tmr-sound-file
+      "/usr/share/sounds/freedesktop/stereo/alarm-clock-elapsed.oga")
+
 ;; OPTIONALLY set global key bindings:
 (let ((map global-map))
-  (define-key map (kbd "C-c t t") #'tmr)
+  (define-key map (kbd "C-c t t") #'tmr) ; or use the command 
`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 c") #'tmr-cancel))
 
-;; Also check the user options `tmr-sound-file',
-;; `tmr-notification-urgency' `tmr-descriptions-list'.
+;; Also check the user options `tmr-notification-urgency'
+;; `tmr-descriptions-list'.
 #+end_src
 
 * Acknowledgements
@@ -189,7 +201,8 @@ TMR is meant to be a collective effort.  Every bit of help 
matters.
 
 + Author/maintainer :: Protesilaos Stavrou.
 
-+ Contributions to the code or manual :: Christian Tietze.
++ Contributions to the code or manual :: Christian Tietze, Damien
+  Cassou.
 
 * GNU Free Documentation License
 :PROPERTIES:
diff --git a/tmr.el b/tmr.el
index db06fd45b8..134f377ba7 100644
--- a/tmr.el
+++ b/tmr.el
@@ -44,6 +44,10 @@
 ;; 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
@@ -59,6 +63,9 @@
 ;; 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' command).  If there is only one timer, it cancels it outright.  If
 ;; there are multiple timers, it produces a minibuffer completion prompt
@@ -95,7 +102,10 @@ such notifications."
   :group 'tmr)
 
 (defcustom tmr-descriptions-list (list "Boil water" "Prepare tea" "Bake bread")
-  "Optional description candidates for the current `tmr'."
+  "Optional description candidates for the current `tmr'.
+These are provided as completion candidates when `tmr' is called
+with a DESCRIPTION argument or when `tmr-with-description' is
+used."
   :type '(repeat string)
   :group 'tmr)
 
@@ -267,9 +277,12 @@ With optional DESCRIPTION as a prefix 
(\\[universal-argument]),
 prompt for a description among `tmr-descriptions-list', though
 allow for any string to serve as valid input.
 
-This command also plays back `tmr-sound-file'.
+This command also plays back `tmr-sound-file' if it is available.
+
+To cancel the timer, use the `tmr-cancel' command.
 
-To cancel the timer, use the `tmr-cancel' command."
+To always prompt for a DESCRIPTION when setting a timer, use the
+command `tmr-with-description' instead of this one."
   (interactive
    (list
     (read-string "N minutes for timer (append `h' or `s' for other units): ")
@@ -292,7 +305,7 @@ To cancel the timer, use the `tmr-cancel' command."
 (defun tmr-with-description (time description)
   "Set timer to TIME duration and notify with DESCRIPTION after it elapses.
 
-See `tmr' for a description of the arguments. The difference
+See `tmr' for a description of the arguments.  The difference
 between the two commands is that `tmr-with-description' always
 asks for a description whereas `tmr' only asks for it when the
 user uses a prefix argument (\\[universal-argument])."