Add docs about commands

Signed-off-by: Joas Schilling <coding@schilljs.com>

docs/commands.md

@@ -0,0 +1,72 @@
+# Chat commands
+
+
+## Admin defined commands
+
+For security reasons commands can only be added via the command line. `./occ  talk:command:add --help` gives you a short overview of the required arguments, but they are explained here in more depth:
+
+### "Add command" arguments
+
+Argument | Allowed chars | Description
+---|---|---
+`cmd` | [a-z0-9] | The keyword the user has to type to run this command (min. 1, max. 64 characters)
+`name` | * | The author name of the response that is posted by the command (min. 1, max. 64 characters)
+`script` | * | Actual command that is being ran. The script must be executable by the user of your webserver. See the parameter table below for options. The script is invoked with `--help` as argument on set up, to check if it can be executed correctly.
+`response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone
+`enabled` | 0-3 |  Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone
+
+### Script parameter
+
+Parameter | Description
+---|---
+`{ROOM}` | The token of the room the command was used in
+`{USER}` | ID of the user that called the command
+`{ARGUMENTS}` | Everything the user write after the actual command
+`{ARGUMENTS_DOUBLEQUOTE_ESCAPED}` | … but with double quotes `"` escaped.
+
+### Example
+
+* `/path/to/calc.sh`:
+
+    ```
+    while test $# -gt 0; do
+      case "$1" in
+        --help)
+          echo "/calc - A Nextcloud Talk chat wrapper for gnome-calculator"
+          echo " "
+          echo "Simple equations: /calc 3 + 4 * 5"
+          echo "Complex equations: /calc sin(3) + 3^3 * sqrt(5)"
+          exit 0
+          ;;
+        *)
+          break
+          ;;
+     esac
+    done
+    
+    set -f
+    echo "$@ ="
+    echo $(gnome-calculator --solve="$@")
+    ```
+    
+    Please note, that your command should also understand the argument `--help`.
+It should return a useful description, the first line is also displayed in a list of all commands when the user just types `/help`.
+
+* `./occ` command used to add the command:
+
+    ```
+    ./occ talk:command:add calc calculater "/path/to/calc.sh \"{ARGUMENTS_DOUBLEQUOTE_ESCAPED}\" {ROOM} {USER}" 1 3
+    ```
+    
+* User input by user `my user id` in the chat of room `index.php/call/4tf349j`:
+    
+    ```
+    /calc 1 + 2 + 3 + "hello"
+    ```
+
+    
+* Executed shell command:
+
+    ```
+    /path/to/calc.sh "1 + 2 + 3 + \"hello\"" '4tf349j' 'my user id'
+    ```