From 62b6b618d5a11999998b83e5d22a3daf55ed9552 Mon Sep 17 00:00:00 2001
From: "Kay Marquardt (Gnadelwartz)" <kay@rrr.de>
Date: Sun, 7 Feb 2021 19:32:36 +0100
Subject: [PATCH] doc: add send_dice, sendMessage: optimze send_dice emoji
 selection

---
 bin/send_dice.sh       |  4 ++--
 doc/6_reference.md     | 18 ++++++++++++++++--
 modules/sendMessage.sh |  8 +++-----
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/bin/send_dice.sh b/bin/send_dice.sh
index d5406e5..dc81c4a 100755
--- a/bin/send_dice.sh
+++ b/bin/send_dice.sh
@@ -10,7 +10,7 @@ USAGE='send_dice.sh [-h|--help] "CHAT[ID]" "emoji" [debug]'
 # 
 #       OPTIONS: CHAT[ID] - ID number of CHAT or BOTADMIN to send to yourself
 #                emoji - must be one of: “🎲”, “🎯”, “🏀”, “⚽”, or “🎰”
-#                       ":text: ":game_die:" ":dart:" ":basketball:" ":soccer:" :slot_machine:"
+#                        ":game_die:" ":dart:" ":basketball:" ":soccer:" :slot_machine:"
 #
 #                -h - display short help
 #                --help -  this help
@@ -21,7 +21,7 @@ USAGE='send_dice.sh [-h|--help] "CHAT[ID]" "emoji" [debug]'
 #        AUTHOR: KayM (gnadelwartz), kay@rrr.de
 #       CREATED: 07.02.2021 18:45
 #
-#### $$VERSION$$ v1.45-dev-7-ga9ed559
+#### $$VERSION$$ v1.45-dev-8-g069570e
 #===============================================================================
 
 ####
diff --git a/doc/6_reference.md b/doc/6_reference.md
index 758036c..fbb7b55 100644
--- a/doc/6_reference.md
+++ b/doc/6_reference.md
@@ -176,8 +176,22 @@ send_album "$(getConfigKey "botadmin")" "http://www.rrr.de/slider/main-image1.jp
 ##### send_sticker
 `send_sticker` sends a sticker using a `file_id` to send a sticker that exists on the Telegram servers.
 
-*usage:*  send_sticker "$CHAT[ID]" "file_id"
+*usage:*  send_sticker "CHAT[ID]" "file_id"
 
+##### send_dice
+`send_dice` send an animated emoji and returns a value (_e.g. points shown on die_).
+
+*usage:* send_dice "CHAT[ID]" "emoji"
+
+Emoji must be one of '🎲', '🎯', '🏀', '⚽', '🎰' or ":game_die:" ":dart:" ":basketball:" ":soccer:" :slot_machine:".
+Dice can have values 1-6 for '🎲' and '🎯', values 1-5 for '🏀' and '⚽', and values 1-64 for '🎰'. Defaults to '🎲' 
+
+*example:*
+```bash
+# send die and output points
+send_dice "${CHAT[ID]}" ":game_die:"
+[ "$BOTSENT[ok]" = "true ] && send_markdownv2_message "*Congratulation* you got *${BOTSENT[RESULT]} Points*."
+```
 
 ----
 
@@ -1627,5 +1641,5 @@ The name of your bot is available as bash variable "$ME", there is no need to ca
 #### [Prev Best Practice](5_practice.md)
 #### [Next Notes for Developers](7_develop.md)
 
-#### $$VERSION$$ v1.41-0-gad1b91f
+#### $$VERSION$$ v1.45-dev-8-g069570e
 
diff --git a/modules/sendMessage.sh b/modules/sendMessage.sh
index 9994bfc..52afdfe 100644
--- a/modules/sendMessage.sh
+++ b/modules/sendMessage.sh
@@ -6,7 +6,7 @@
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 #
 # shellcheck disable=SC1117
-#### $$VERSION$$ v1.45-dev-7-ga9ed559
+#### $$VERSION$$ v1.45-dev-8-g069570e
 
 # will be automatically sourced from bashbot
 
@@ -321,16 +321,14 @@ send_action() {
 # text: ":game_die:" ":dart:" ":basketball:" ":soccer:" :slot_machine:"
 # $3 reply_to_id
 send_dice() {
-	local emoji reply
+	local reply emoji='\ud83c\udfb2'	# default "🎲"
 	[[ "$3" =~ ^[${o9o9o9}-]+$ ]] && reply=',"reply_to_message_id":'"$3"',"allow_sending_without_reply": true'
 	case "$2" in # convert input to single character emoji
-		*🎲*|*game*  |*'dfb2'*|*'DFB2'*)	emoji='\ud83c\udfb2' ;;
+		*🎲*|*game*|*dice*|*'dfb2'*|*'DFB2'*)	: ;;
 		*🎯*|*dart*  |*'dfaf'*|*'DFAF'*)	emoji='\ud83c\udfaf' ;;
 		*🏀*|*basket*|*'dfc0'*|*'DFC0'*)	emoji='\ud83c\udfc0' ;;
 		*⚽*|*soccer*|*'26bd'*|*'26BD'*)	emoji='\u26bd' ;;
 		*🎰*|*slot*  |*'dfb0'*|*'DFB0'*)	emoji='\ud83c\udfb0' ;;
-		*) # default emoji "🎲"
-				emoji='\ud83c\udfb2' ;;
 	esac
 	sendJson "$1" '"emoji": "'"${emoji}"'"'"${reply}" "${URL}/sendDice"
 	if [ "${BOTSENT[OK]}" = "true" ]; then