From e663979206e002a79a46b1a0162d00179df1a3af Mon Sep 17 00:00:00 2001
From: "Kay Marquardt (Gnadelwartz)" <kay@rrr.de>
Date: Thu, 11 Jun 2020 12:17:07 +0200
Subject: [PATCH] improve doc

---
 README.html       |  3 ++-
 README.md         |  3 ++-
 README.txt        |  3 ++-
 doc/3_advanced.md | 26 +++++++++++++++-----------
 doc/7_develop.md  | 16 +++++++++-------
 5 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/README.html b/README.html
index 703421c..504bf27 100644
--- a/README.html
+++ b/README.html
@@ -118,6 +118,7 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
 <li>Interactive Chats</li>
 <li>Background Jobs</li>
 <li>Inline queries</li>
+<li>Send message errors</li>
 </ul></li>
 <li><a href="doc/4_expert.md">Expert Use</a>
 <ul>
@@ -245,6 +246,6 @@ It features background tasks and interactive chats, and can serve as an interfac
 <p>@Gnadelwartz</p>
 <h2>That's it!</h2>
 <p>If you feel that there's something missing or if you found a bug, feel free to submit a pull request!</p>
-<h4>$$VERSION$$ v0.96-pre-13-ga71d68e</h4>
+<h4>$$VERSION$$ v0.96-pre-39-gb6e9f9e</h4>
 </body>
 </html>
diff --git a/README.md b/README.md
index 4f481a4..4bd8192 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
     * Interactive Chats
     * Background Jobs
     * Inline queries
+    * Send message errors
 * [Expert Use](doc/4_expert.md)
     * Handling UTF-8 character sets
     * Run as other user or system service
@@ -218,4 +219,4 @@ This may happen if to many wrong requests are sent to api.telegram.org, e.g. usi
 
 If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
 
-#### $$VERSION$$ v0.96-pre-13-ga71d68e
+#### $$VERSION$$ v0.96-pre-39-gb6e9f9e
diff --git a/README.txt b/README.txt
index c3b5a90..50bf470 100644
--- a/README.txt
+++ b/README.txt
@@ -50,6 +50,7 @@ availible on www.github.com
     * Interactive Chats
     * Background Jobs
     * Inline queries
+    * Send message errors
 * [Expert Use](doc/4_expert.md)
     * Handling UTF-8 character sets
     * Run as other user or system service
@@ -304,4 +305,4 @@ in 'mycommands.sh' as example.
 If you feel that there's something missing or if you found a bug, feel free to 
 submit a pull request!
 
-#### $$VERSION$$ v0.96-pre-13-ga71d68e
+#### $$VERSION$$ v0.96-pre-39-gb6e9f9e
diff --git a/doc/3_advanced.md b/doc/3_advanced.md
index 095018a..6d5213f 100644
--- a/doc/3_advanced.md
+++ b/doc/3_advanced.md
@@ -206,27 +206,30 @@ See also [answer_inline_multi, answer_inline_compose](6_reference.md#answer_inli
 
 ### Handle send message errors
 
-Usually the exmaples do not care if an error happen while sending a message, this is  because bashbot detects if a message is
-not sent and try to recover when possible, e.g. resend on throttling.
+Our examples usually do not care about errors happening while sending a message, this is OK as long your bot does not send an
+massive aoumnt of messages. By default bashbot detects if a message is not sent and try to recover when possible,
+e.g. resend on throttling. In addtion every send error is logged in logs/ERROR.log
 
-In addition on every transmission to telegram the results are provided as bash in bash variables.
 
 #### Trasmission results
 
+On every message send to telgram (transmission) the results are provided in bash variables, like its done when a new message
+is received.
+
 **Note**: the values of the variables contains always the result of the LAST transmission to telegram,
-everey send action will overwrite them!
+every send action will overwrite them!
 
 * ```$BOTSENT```: This array contains the parsed results from the last transmission to telegram.
-    * ```${BOTSENT[OK]}```: contain's the string 'true' after a successful transmission
-    * ```${BOTSENT[ERROR]}```: Error code if OK is not true
+    * ```${BOTSENT[OK]}```: contains the string ```true```: after a successful transmission
+    * ```${BOTSENT[ERROR]}```: Error code if an error occured
     * ```${BOTSENT[DESC]}```: Description text for error
-    * ```${BOTSENT[RETRY]}```: Seconds to wait ifntelegram requests throtteling.
+    * ```${BOTSENT[RETRY]}```: Seconds to wait if telegram requests throtteling.
 * ```$res```: temporary variable containing the full transmission result, may be overwritten by any bashbot function.
 
 By default you don't have to care about retry, as bashbot resend the message after the requested time automatically.
 Only if the retry fails also an error is returned. The downside is that send_message functions will wait until resend is done.
 
-If you want to disbale all automtic error processing  and handle all errors manually (or don't care)
+If you want to disable automtic error processing  and handle all errors manually (or don't care)
 set ```BASHBOT_RETRY``` to any no zero value.
 
 [Telegram API error codes](https://core.telegram.org/api/errors)
@@ -235,12 +238,13 @@ set ```BASHBOT_RETRY``` to any no zero value.
 #### Detect bot blocked
 
 If the we can't connect to telegram, e.g. blocked from telegram server but also any other reason,
-bashbot set ```BOTSENT[ERROR]``` to '999'.
+bashbot set ```BOTSENT[ERROR]``` to ```999```.
 
 To get a notification on every connection problem create a function named ```bashbotBlockRecover``` and handle blocks there.
 If the function returns true (0 or no value) bashbot will retry once and then return to the calling function.
 In case you return any non 0 value bashbot will return to the calling function without retry.
 
+Note: If you disable automatic retry, se above, you disable also connection problem notification.
 
 ```bash
   # somewhere in myfunctions.sh ...
@@ -249,7 +253,7 @@ In case you return any non 0 value bashbot will return to the calling function w
   function bashbotBlockRecover() {
       # ups, we are blocked!
       (( MYBLOCKED++ ))
-      # log what we gotr
+      # log what we got
       printf "%s: Blocked %d times: %s\n" "$(date)" "${MYBLOCKED}" "$*" >>"${ERRORLOG}" 
 
       if [ "${MYBLOCKED}" -gt 10 ]; then
@@ -270,5 +274,5 @@ In case you return any non 0 value bashbot will return to the calling function w
 #### [Prev Getting started](2_usage.md)
 #### [Next Expert Use](4_expert.md)
 
-#### $$VERSION$$ v0.96-pre-37-g6c02bab
+#### $$VERSION$$ v0.96-pre-39-gb6e9f9e
 
diff --git a/doc/7_develop.md b/doc/7_develop.md
index 68de0f3..07ca51c 100644
--- a/doc/7_develop.md
+++ b/doc/7_develop.md
@@ -56,7 +56,7 @@ Note: For the same reason event function MUST return immediately! Time consuming
 
 ##### SEND RECEIVE events
 
-executed when a Message is received, same iQuery / Message variables are avalible as in commands.sh
+An RECEIVE event is executed when a Message is received, same iQuery / Message variables are avalible as in commands.sh
 
 * BASHBOT_EVENT_INLINE		an inline query is received
 
@@ -89,6 +89,8 @@ example_echo() {
 }
 ```
 
+An SEND event is executed when a Message is send tomtelegram.
+
 * BASHBOT_EVENT_SEND	is exceuted if data is send or uploaded to Telegram server
 
 In contrast to other events, BASHBOT_EVENT_SEND is excecuted in a subshell, so there is no need to spawn
@@ -117,7 +119,7 @@ example_log(){
 
 ##### TIMER events
 
-Important: The timer tick is diabled by default and must be enabled by setting BASHBOT_START_TIMER to any value not zero.
+Important: Bashbot timer tick is diabled by default and must be enabled by setting BASHBOT_START_TIMER to any value not zero.
 
 * BAHSBOT_EVENT_TIMER		executed every minute and can be used in 3 variants: oneshot, once a minute, every X minutes.
 
@@ -133,9 +135,9 @@ This means if you register an every 5 minutes callback first execution may < 5 M
     * 0	ignored
     * 1	execute once every minute
     * x	execute every x minutes
-    * -x execute ONCE in (next) x minutes *
+    * -x execute once WHITHIN the next x Minutes (10=between now and 10 Minutes)
 
-*\* if you really want "in x minutes" you must use ```-(EVENT_TIMER+x)```* 
+Note: If you want exact "in x minutes" use "EVENT_TIMER plus x" as time: ```-(EVENT_TIMER + x)```
 
 *Example:*
 ```bash
@@ -151,10 +153,10 @@ example_everymin() {
 # register other callback:
 BAHSBOT_EVENT_TIMER["example_every5","5"]="example_every5min"
 
-# execute once in the next 10 minutes
+# execute once in the next 1 to 10 minutes
 BAHSBOT_EVENT_TIMER["example_10min","-10"]="example_in10min"
 
-# once in 10 minutes
+# once in exact 10 minutes
 BAHSBOT_EVENT_TIMER["example_10min","$(( (EVENT_TIMER+10) * -1 ))"]="example_in10min"
 
 ```
@@ -336,5 +338,5 @@ fi
 
 #### [Prev Function Reference](6_reference.md)
 
-#### $$VERSION$$ v0.96-pre-36-g81c8771
+#### $$VERSION$$ v0.96-pre-39-gb6e9f9e