adjust doc to mycommands and new section installation

README.md

@@ -16,25 +16,12 @@ Most complete [UTF-8 support for bashbot](doc/4_expert.md#Bashbot-UTF-8-Support)
 
 Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are availible on www.github.com
 
-## Install bashbot
-1. Go to the directory you want to install bashbot, e.g.
-    * your $HOME directory (install and run with your user-ID)
-    * /usr/local if you want to run as service
-2. [Download latest release zip from github](https://github.com/topkecleon/telegram-bot-bash/releases) and extract all files. 
-
-    As an alternative you can clone the github repository to get the latest improvements/fixes,
-    run bashbot test suite ``All-tests.sh`` afterwards to see if code looks OK.
-    ```
-    git clone https://github.com/topkecleon/telegram-bot-bash; test/ALL-tests.sh
-    ```
-3. Go to directory ```telegram-bot-bash```, run ```./bashbot.sh init``` and follow the instructions. At this point you are asked for your Bots token given by botfather.
-
-## Update bashbot
-1. [Download latest update zip from github](https://github.com/topkecleon/telegram-bot-bash/releases)
-2. Extract all files and copy them to your bashbot dir
-3. Run ```sudo ./bashbot.sh init``` to setup your environment after the update
-
 ## Documentation
+* [Install Bashbot](doc/0_install.md)
+    * Install release
+    * Install from githup
+    * Update Bashbot
+    * Notes on Updates
 * [Create a new Telegram Bot with botfather](doc/1_firstbot.md)
 * [Getting Started](doc/2_usage.md)
     * Managing your Bot
@@ -58,21 +45,6 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
 * [Notes for bashbot developers](doc/7_develop.md)
 * [Customize bashbot environment](doc/8_customize.md)
 
-## Note on Keyboards
-From Version 0.60 on keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed.
-Keybords are now defined in JSON Array notation e.g. "[ \\"yes\\" , \\"no\\" ]".
-This has the advantage that you can create any type of keyboard supported by Telegram.
-The old format is supported for backward compatibility, but may fail for corner cases.
-
-*Example Keyboards*:
-
-- yes no in two rows:
-    - OLD format: 'yes' 'no' (two strings)
-    - NEW format: '[ "yes" ] , [ "no" ]' (two arrays with a string)
-- new layouts made easy with NEW format:
-    - Yes No in one row: '[ "yes" , "no" ]'
-    - Yes No plus Maybe in 2.row: '[ "yes" , "no" ] , [ "maybe" ]' 
-    - numpad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
 
 ## Security Considerations
 Running a Telegram Bot means it is connected to the public and you never know whats send to your Bot.
@@ -104,4 +76,4 @@ Bashbot is not more (in)secure as any other Bot written in any other language, w
 
 If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

bashbot.sh

@@ -12,7 +12,7 @@
 # This file is public domain in the USA and all free countries.
 # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
 #
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 #
 # Exit Codes:
 # - 0 sucess (hopefully)
@@ -666,7 +666,7 @@ if [ "$1" != "source" ]; then
 		echo "Sending the broadcast $* to $NUMCOUNT users."
 		[ "$NUMCOUNT" -gt "300" ] && sleep="sleep 0.5"
 		shift
-		while read -r f; do send__markdown_message "${f//COUNT}" "$*"; $sleep; done <"${COUNTFILE}"
+		while read -r f; do send_markdown_message "${f//COUNT}" "$*"; $sleep; done <"${COUNTFILE}"
 		;;
 	"start")
 		${CLEAR}

doc/0_install.md

@@ -0,0 +1,65 @@
+#### [Home](../README.md)
+
+## Install bashbot
+
+1. Go to the directory you want to install bashbot, e.g.
+    * your $HOME directory (install and run with your user-ID)
+    * /usr/local if you want to run as service
+2. [Download latest release zip from github](https://github.com/topkecleon/telegram-bot-bash/releases) and extract all files. 
+3. Change into the directory ```telegram-bot-bash```
+4. Create default commands with ```cp commands.sh.dist commands.sh; cp mycommands.sh.dist mycommands.sh```
+5. Run ```./bashbot.sh init``` to setup the environment and enter your Bots token given by botfather.
+
+Now your Bot is ready to start ...
+
+### Install from Github
+
+As an alternative to donwload the zip files, you can clone the github repository to get the latest improvements/fixes.
+
+1. Go to the directory you want to install bashbot, e.g.
+    * your $HOME directory (install and run with your user-ID)
+    * /usr/local if you want to run as service
+
+2. Run ```git clone https://github.com/topkecleon/telegram-bot-bash;```
+3. Change into the directory ```telegram-bot-bash```
+4. Run ``` test/ALL-tests.sh``` and if everthing finish OK ...
+5. Run ```./bashbot.sh init``` to setup the environment and enter your Bots token given by botfather.
+
+###  Update bashbot
+
+1. Go to the directory where you had installed bashbot, e.g.
+    * your $HOME directory
+    * /usr/local
+2. [Download latest release zip from github](https://github.com/topkecleon/telegram-bot-bash/releases)
+3. Extract all files to you existing bashbot dir **Note** all files execpt 'mycommands.sh' and 'commands.sh' may overwritten!**
+4. Run ```sudo ./bashbot.sh init``` to setup your environment after the update
+
+### Notes on Updates
+
+#### Location of tmp / data dir
+From version 0.70 on the tmp dir is renamed to 'data-bot-bash' to refelect the fact that not only temporyry files are stored. an existing 'tmp-bot-bash' will be automatically after update renamed.
+
+From version 0.50 on the temporary files are no more placed in '/tmp'. instead a dedicatet tmp dir is used.
+
+#### Changes to send_keyboard in v0.6
+From Version 0.60 on keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed.
+Keybords are now defined in JSON Array notation e.g. "[ \\"yes\\" , \\"no\\" ]".
+This has the advantage that you can create any type of keyboard supported by Telegram.
+The old format is supported for backward compatibility, but may fail for corner cases.
+
+*Example Keyboards*:
+
+- yes no in two rows:
+    - OLD format: 'yes' 'no' (two strings)
+    - NEW format: '[ "yes" ] , [ "no" ]' (two arrays with a string)
+- new layouts made easy with NEW format:
+    - Yes No in one row: '[ "yes" , "no" ]'
+    - Yes No plus Maybe in 2.row: '[ "yes" , "no" ] , [ "maybe" ]' 
+    - numpad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
+
+
+
+#### [Next Create Bot](1_firstbot.md)
+
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
+

doc/1_firstbot.md

@@ -59,7 +59,8 @@ group. This step is up to you actually.
 13. @botfather replies with `Success! The new status is: DISABLED. /help`
 
 
+#### [Prev Installation](0_install.md)
 #### [Next Getting started](2_usage.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/2_usage.md

@@ -1,9 +1,9 @@
 #### [Home](../README.md)
 ## Gettting Started
 
-All Commands for the Bot are in the ```commands.sh``` file (this should ease upgrades of the bot core). Here you find some examples how to process messages and send out text.
+THe Bots standard commands are in the ```commands.sh``` file. Vou must not add your commands to 'commands.sh' instead place them in ```mycommands.sh```,  there you also find examples how to process messages and send out text.
 
-Once you're done editing start the Bot with ```./bashbot.sh start```. 
+Once you're done with editing 'mycommands.sh' start the Bot with ```./bashbot.sh start```. 
 If some thing doesn't work as it should, debug with ```bash -x bashbot.sh```. To stop the Bot run ```./bashbot.sh kill```
 
 To use the functions provided in this script in other scripts simply source bashbot: ```source bashbot.sh```
@@ -166,5 +166,5 @@ send_action "${CHAT[ID]}" "action"
 #### [Prev Create Bot](1_firstbot.md)
 #### [Next Advanced Usage](3_advanced.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/3_advanced.md

@@ -156,5 +156,5 @@ answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
 #### [Prev Advanced Usage](3_advanced.md)
 #### [Next Expert Use](4_expert.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/4_expert.md

@@ -104,5 +104,5 @@ An example crontab is provided in ```examples/bashbot.cron```.
 #### [Prev Expert Use](4_expert.md)
 #### [Next Best Practice](5_practice.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/5_practice.md

@@ -1,49 +1,81 @@
 #### [Home](../README.md)
 ## Best Practices
 
-### Customize commands.sh only
+### Add commands to mycommands.sh only
-
+To ease Updates never change ```bashbot.sh```, instead your commands and functions must go to  ```mycommands.sh``` .  Insert your Bot commands in the ```case ... esac``` block of the 'mycommands()' function:
-To ease Updates never change ```bashbot.sh```, instead individual commands should go to  ```commands.sh``` .  Insert your Bot commands in the ```case ... esac``` block:
 ```bash
-	case "$MESSAGE" in
+# file: mycommands.sh
-		'/echo') # my first own command, echo MESSAGE
+# your additional bahsbot commands
-			send_normal_message "${CHAT[ID]}" "${MESSAGE}"
-			;;
 
+# uncomment the following lines to overwrite info and help messages
+ bashbot_info='This is *MY* variant of _bashbot_, the Telegram bot written entirely in bash.
+'
+
+ bashbot_help='*Available commands*:
+/echo message - _echo the given messsage_
+'
+
+mycommands() {
+
+	case "$MESSAGE" in
+		'/echo'*) # example echo command
+			send_normal_message "${CHAT[ID]}" "$MESSAGE"
+			;;
+		# .....
+	esac
+}
+```
+
+### Reuse or disable standard commands
+If you want to disable or reuse a standard bashbot command comment it out in 'commands.sh' by placing a '#' in front of
+every line from ```'/command')``` to ```;;```. 
+
+**Note: Never disable the catchall command ``*)```` in 'commands.sh'!!**
+```bash
+#!/bin/bash
+# file: commands.sh
+
+	case "$MESSAGE" in
 		################################################
-		# DEFAULT commands start here, do not edit below this!
+		# DEFAULT commands start here, edit messages only
-		'/info')
+
-			bashbot_info "${CHAT[ID]}"
+		#'/start')
+		#	send_action "${CHAT[ID]}" "typing"
+		#	_is_botadmin && _markdown_message "You are *BOTADMIN*."
+		#	if _is_allowed "start" ; then
+		#		_markdown_message "${bot_help}"
+		#	else
+		#		_message "You are not allowed to start Bot."
+		#	fi
+		#	;;
+
+		*)	# forward other messages to optional dispatcher
+			_is_function startproc && if tmux ls | grep -v send | grep -q "$copname"; then inproc; fi # interactive running
+			_is_function mycommands && mycommands
 			;;
 	esac
 ```
 
+
 ### Seperate logic from commands
 
-If a command need more than 2-3 lines of code, you should use a function to seperate logic from command. Place your functions in a seperate file, e.g. ```mycommands.inc.sh``` and source it from bashbot.sh. Example:
+If a command need more than 2-3 lines of code, you should use a function to seperate logic from command. Place your functions in ```mycommands.sh``` and call the from you commands. Example:
 ```bash
-	source "mycommands.inc.sh"
+#!/bin/bash
+# file: mycommands.sh
+
+mycommands() {
 
 	case "$MESSAGE" in
 		'/process') # logic for /process is done in process_message 
 			result="$(process_message "$MESSAGE")"
 			send_normal_message "${CHAT[ID]}" "$result" 
 			;;
-
-		################################################
-		# DEFAULT commands start here, do not edit below this!
-		'/info')
-			bashbot_info "${CHAT[ID]}"
-			;;
-		'/start')
-			send_action "${CHAT[ID]}" "typing"
-			bashbot_help "${CHAT[ID]}"
-			;;
 	esac
-```
+
-```bash
+}
-#!/bin/bash
+
-# file: mycommands.inc.sh
+# place your functions here
 
 process_message() {
    local ARGS="${1#/* }"	# remove command 
@@ -53,7 +85,6 @@ process_message() {
    set -f
    for WORD in $ARGS
    do
-	set +f
 	# process links 
 	if [[ "$WORD" == "https://"* ]]; then
 		REPORT="$(dosomething_with_link "$WORD")"
@@ -68,7 +99,6 @@ process_message() {
    done
 
    # return result, reset globbing in case we had no ARGS
-   set +f
    echo "${OUTPUT}${TEXT}"
 }
 
@@ -112,5 +142,5 @@ The second warning is about an unused variable, this is true because in our exam
 #### [Prev Best Practice](5_practice.md)
 #### [Next Functions Reference](6_reference.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/6_reference.md

@@ -445,5 +445,5 @@ Send Input from Telegram to waiting Interactive Chat.
 #### [Prev Best Practice](5_practice.md)
 #### [Next Notes for Developers](7_develop.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/7_develop.md

@@ -71,5 +71,5 @@ fi
 #### [Prev Function Reference](6_function.md)
 #### [Next Bashbot Environment](8_custom.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
 

doc/8_custom.md

@@ -131,5 +131,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
 
 #### [Prev Notes for Developers](7_develop.md)
 
-#### $$VERSION$$ v0.70-dev2-18-g097a841
+#### $$VERSION$$ v0.70-dev2-20-ga3b82f7