From d88d422fdd0d0ab2f2e062b3cc8bdd45fe6a51d8 Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Thu, 25 Apr 2019 22:17:24 +0200 Subject: [PATCH] improve documentation --- doc/2_usage.md | 4 ++-- doc/3_advanced.md | 26 ++++++++++++-------- doc/6_reference.md | 60 ++++++++++++++++++++++++---------------------- 3 files changed, 49 insertions(+), 41 deletions(-) diff --git a/doc/2_usage.md b/doc/2_usage.md index e4e211a..670a6c5 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -1,7 +1,7 @@ #### [Home](../README.md) ## Gettting Started -The Bots standard commands are in ```commands.sh``` file. You 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. +The Bots standard commands are in ```commands.sh``` file. You 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. See [Best practices](5_practice.md) for more information. 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``` @@ -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-27-g2da31c1 +#### $$VERSION$$ v0.70-dev3-6-g034274c diff --git a/doc/3_advanced.md b/doc/3_advanced.md index 6ce711d..fda1985 100644 --- a/doc/3_advanced.md +++ b/doc/3_advanced.md @@ -2,7 +2,7 @@ ## Advanced Features ### Access control -Bashbot offers functions to check what Telegram capabilities like chat admin or chat creator the given user has: +Bashbot offers functions to check what Telegram capabilities like 'chat admin' or 'chat creator' the given user has: ```bash # return true if user is admin/owner of the bot @@ -21,7 +21,7 @@ user_is_botadmin "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are * user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *CHATADMIN*." ``` -In addition you can check individual capabilities of users as defined in the ```./botacl``` file: +In addition you can check individual capabilities of users as you must define in the file ```./botacl```: ```bash # file: botacl # a user not listed here, will return false from 'user_is_allowed' @@ -44,7 +44,7 @@ In addition you can check individual capabilities of users as defined in the ``` *:start:* *:*:98979695 ``` -you have to use the function ```user_is_allowed``` to check if a user has the capability to do something. Example check if user has capability to start bot: +You must use the function ```user_is_allowed``` to check if a user has the capability to do something. Example: Check if user has capability to start bot. ```bash case "$MESSAGE" in '/start') @@ -58,8 +58,14 @@ you have to use the function ```user_is_allowed``` to check if a user has the ca ``` ### Interactive Chats -To create interactive chats, write (or edit the exmaples/question.sh script) a normal bash (or C or python) script, chmod +x it and then change the argument of the startproc function to match the command you usually use to start the script. -The text that the script will output will be sent in real time to the user, and all user input will be sent to the script (as long as it's running or until the user kills it with /cancel). +To create interactive chats, write *(or edit the 'exmaples/question.sh' script)* a bash *(or C or python)* script, make it executable +and then use the 'startproc' function to start the script. +The output of the script will be sent to the user and user input will be sent to the script. +To stop the script use the function 'killprog' + +The output of the script will be processed by 'send_messages' to enable you to not only send text, but also keyboards, files, locations and more. +Each newline in the output will start an new message to the user, to have line breaks in your message you can use 'mynewlinestartshere'. + To open up a keyboard in an interactive script, print out the keyboard layout in the following way: ```bash echo "Text that will appear in chat? mykeyboardstartshere [ \"Yep, sure\" , \"No, highly unlikely\" ]" @@ -90,11 +96,11 @@ Note: Interactive Chats run independent from main bot and continue running until ### Background Jobs -A background job is similar to an interactive chat, but runs in the background and does only output massages instead of processing input from the user. In contrast to interactive chats it's possible to run multiple background jobs. To create a background job write a script or edit the examples/notify.sh script and use the funtion ```background``` to start it: +A background job is similar to an interactive chat, but runs in the background and does only output massages and does not get user input. In contrast to interactive chats it's possible to run multiple background jobs. To create a background job write a script or edit 'examples/notify.sh' script and use the funtion ```background``` to start it: ```bash background "examples/notify.sh" "jobname" ``` -All output of the script will be sent to the user or chat. To stop a background job use: +All output of the script will be sent to the user, to stop a background job use: ```bash killback "jobname" ``` @@ -109,7 +115,7 @@ If you want to kill all background jobs permantly run: ./bashbot.sh killback ``` -Note: Background Jobs run independent from main bot and continue running until your script exits or you stop if from your Bot. Backgound Jobs will continue running if your Bot is stoped (kill)!. +Note: Background Jobs run independent from main bot and continue running until your script exits or you stop if from your Bot. Backgound Jobs will continue running if your Bot is stopeda and must be terminated, e.g. by ```bashbot.sh killback``` ### Inline queries The following commands allows users to interact with your bot via *inline queries*. @@ -153,8 +159,8 @@ To send stickers through an *inline query*: ```bash answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker" ``` -#### [Prev Advanced Usage](3_advanced.md) +#### [Prev Getting started](2_usage.md) #### [Next Expert Use](4_expert.md) -#### $$VERSION$$ v0.70-dev2-27-g2da31c1 +#### $$VERSION$$ v0.70-dev3-6-g034274c diff --git a/doc/6_reference.md b/doc/6_reference.md index 220cf88..1288bd9 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -125,23 +125,24 @@ send_keyboard "${CHAT[ID]}" "Enter digit" "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \ ##### remove_keyboard *usage:* remove_keybord "$CHAT[ID]" "message" -#### send_inline_button -*usage:* send_inine_button "chat-id" "message" "Button text" "Buttton URL" +##### send_inline_button +*usage:* send_inine_button "chat-id" "message" "text" "URL" -*alias:* _inline_button "Button text" "Buttton URL" +*alias:* _inline_button "text" "URL" *example:* ```bash send_inline_button "${CHAT[ID]}" "MAKE MONEY FAST!!!" "Visit my Shop" "https://dealz.rrr.de" ``` -#### send_inline_keyboard -An inline keyboard is used to place multiple inline buttons in a row. The inline buttons must specified as a JSON array in the following format. Each button consists of a text for the button and an URL to got to if the button is clicked, button definitions -are sourrounded by a pair of '**{ }**' and seperated by a '**,**'. +##### send_inline_keyboard +This allows to place multiple inline buttons in a row. The inline buttons must specified as a JSON array in the following format: ```[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]``` -*usage:* send_inline_keyboard "chat-id" "message" "[{"text":"text", "url":"url"} ...]" +Each button consists of a pair of text and URL values, sourrounded by '**{ }**', multiple buttons are seperated by '**,**' and everthing is wrapped in '**[ ]**'. + +*usage:* send_inline_keyboard "chat-id" "message" "[ {"text":"text", "url":"url"} ...]" *alias:* _inline_keyboard "[{"text":"text", "url":"url"} ...]" @@ -157,21 +158,21 @@ send_inline_keyboard "${CHAT[ID]}" "" '[{"text":"b 1", url"":"u 1"}, {"text":"b ### Manage users ##### kick_chat_member -If your Bot is Admin of a chat he can kick and ban a user. +If your Bot is a chat admin he can kick and ban a user. *usage:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}" *alias:* _kick_user "${USER[ID]}" ##### unban_chat_member -If your Bot is Admin of a chat he can unban a kicked user. +If your Bot is a chat admine can unban a kicked user. *usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}" *alias:* _unban "${USER[ID]}" ##### leave_chat -Bot will leave given chat. +Your Bot will leave the chat. *usage:* leave_chat "${CHAT[ID]}" @@ -189,8 +190,7 @@ fi ### User Access Control ##### user_is_botadmin -Return true (0) if user is owner / admin of bot. -Name or ID botadmin must be placed in './botadmin' file. +Return true (0) if user is admin of bot, user id if botadmin is read from file './botadmin'. *usage:* user_is_botadmin "${USER[ID]}" @@ -238,21 +238,21 @@ fi ---- ### Aliases - shortcuts for often used funtions -You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to have the following functions availible. +You must not disable ```source modules/aliases.sh``` in 'commands.sh' to have the following functions availible. -#### _is_botadmin +##### _is_botadmin *usage:* _is_botadmin *alias for:* user_is_botadmin "${USER[ID]}" -#### _is_admin +##### _is_admin *usage:* _is_admin *alias for:* user_is_admin "${CHAT[ID]}" "${USER[ID]}" -#### _is_allowed +##### _is_allowed *usage:* _is_allowed "what" @@ -260,19 +260,19 @@ You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to ---- -##### kick_chat_member +##### _kick_user *usage:* _kick_user "${USER[ID]}" *alias for:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}" -##### unban_chat_member +##### _unban *usage:* _unban "${USER[ID]}" *alias for:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}" -##### leave_chat +##### _leave *usage:* _leave @@ -280,25 +280,25 @@ You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to ---- -#### _message +##### _message *usage:* _message "message" *alias for:* send_normal_message "${CHAT[ID]}" "message" -#### _normal_message +##### _normal_message *usage:* _normal_message "message" *alias for:* send_normal_message "${CHAT[ID]}" "message" -#### _html_message +##### _html_message *usage:* _html_message "message" *alias for:* send_html_message "${CHAT[ID]}" "message" -#### _markdown_message +##### _markdown_message *usage:* _markdown_message "message" @@ -307,10 +307,10 @@ You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to ---- ### Interactive and backgound jobs -You must use ```source modules/background.sh``` in commands.sh or mycommands.sh to have the following functions availible. +You must not disable ```source modules/background.sh``` in 'commands.sh' to have the following functions availible. ##### startproc -```startproc``` starts a script (or C or python program etc.) running in parallel to your Bot. The text that the script outputs is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats) +```startproc``` starts a script, the output of the script is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats) *usage:* startproc "script" @@ -320,7 +320,7 @@ startproc 'examples/calc.sh' ``` ##### checkproc -Return true (0) if an interactive script active in the given chat. +Return true (0) if an interactive script is running in the chat. *usage:* checkprog @@ -335,6 +335,8 @@ fi ``` ##### killproc +Kill the interactive script running in the chat + *usage:* killproc *example:* @@ -350,7 +352,7 @@ fi ---- ##### background -```background``` starts a script / programm as a background job and attaches a jobname to it. All output from a background job is sent to the associated chat. +Starts a script as a background job and attaches a jobname to it. All output from a background job is sent to the associated chat. In contrast to interactive chats, background jobs do not recieve user input and can run forever. In addition you can suspend and restart running jobs, e.g. after reboot. @@ -406,7 +408,7 @@ The main use case for send_message is to process the output of interactive chats ### Helper functions -#### _is_function +##### _is_function Returns true if the given function exist, can be used to check if a module is loaded. *usage* _is_function function @@ -471,5 +473,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-dev3-4-g8f4b168 +#### $$VERSION$$ v0.70-dev3-6-g034274c