From baa4e14ebc570fae76f773a783ad3bc874b15f6b Mon Sep 17 00:00:00 2001
From: "Kay Marquardt (Gnadelwartz)" <kay@rrr.de>
Date: Sat, 6 Feb 2021 12:08:24 +0100
Subject: [PATCH] doc: adjust user visible changes to URLS and download_file

---
 doc/2_usage.md     | 18 ++++++++++--------
 doc/6_reference.md | 42 +++++++++++++++++++++++++++++++-----------
 2 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/doc/2_usage.md b/doc/2_usage.md
index 4910931..149ae5b 100644
--- a/doc/2_usage.md
+++ b/doc/2_usage.md
@@ -186,13 +186,14 @@ The following variables are set if the message contains optional parts:
     * `${FORWARD[LAST_NAME]}`: Original user's' last name
     * `${FORWARD[USERNAME]}`: Original user's username
 * `$CAPTION`: Picture, Audio, Video, File Captions
-* `$URLS`: This array contains documents, audio files, voice recordings and stickers as URL.
-    * `${URLS[AUDIO]}`: Audio files
-    * `${URLS[VIDEO]}`: Videos
-    * `${URLS[PHOTO]}`: Photos (maximum quality)
-    * `${URLS[VOICE]}`: Voice recordings
-    * `${URLS[STICKER]}`: Stickers
-    * `${URLS[DOCUMENT]}`: Any other file
+* `$URLS`: This array contains `path` to document, audio file, voice recording and sticker for download from telegram server.
+    * `${URLS[AUDIO]}`: Path to audio file
+    * `${URLS[VIDEO]}`: Path to video
+    * `${URLS[PHOTO]}`: Path to photo (maximum quality)
+    * `${URLS[VOICE]}`: Path to voice recording
+    * `${URLS[STICKER]}`: Path to sticker
+    * `${URLS[DOCUMENT]}`: Path to any other file
+**Important:** This is NO MORE a full URL, you must use `download_file` or `${URL}/${URLS[xxx]}` for manual download.
 * `$CONTACT`: This array contains info about contacts sent in a chat.
     * `${CONTACT[ID]}`: User id
     * `${CONTACT[NUMBER]}`: Phone number
@@ -238,6 +239,7 @@ e.g. if a new user joins a chat MESSAGE is set to "/_new_chat_user".
         * `${MESSAGE}`: /_new_chat_title SENDER TEXT
     * `${SERVICE[NEWPHOTO]}`: New Chat Picture 
         * `${MESSAGE}`: /_new_chat_picture SENDER URL
+**Important:** SERVICE[NEWPHOTO] is NOT a full URL, you must use `download_file` or `${URL}/${SERVICE[NEWPHOTO]}` for manual download.
     * `${SERVICE[PINNED]}`: Pinned MESSAGE ID
         * `${MESSAGE}`: /_new_pinned_message SENDER ID
         * `${PINNED[ID]}`: Id of pinned message
@@ -372,5 +374,5 @@ send_action "${CHAT[ID]}" "action"
 #### [Prev Create Bot](1_firstbot.md)
 #### [Next Advanced Usage](3_advanced.md)
 
-#### $$VERSION$$ v1.40-0-gf9dab50
+#### $$VERSION$$ v1.41-dev-3-gbc40a3f
 
diff --git a/doc/6_reference.md b/doc/6_reference.md
index 30be34a..5d0e7ac 100644
--- a/doc/6_reference.md
+++ b/doc/6_reference.md
@@ -1398,18 +1398,40 @@ Do not use them in other files e.g. `bashbot.sh`, modules, addons etc.
 
 ### Helper functions
 
-##### download
-Download the given URL and returns the final filename in TMPDIR. If the given filename exists,the filename is prefixed with a
-random number. Filename is not allowed to contain '/' or '..'.
+##### download_file
+`download_file` download a file to DATADIR and returns the PATH to the file, main use is to download files send to chats.
+I tried to be as compatible as possible with old function `download`.
 
-*usage:* download URL filename
+*usage:* download_file path_to_ile prosed_filename
+
+*alias*: download
+
+*Note:* You must use `download_file` to download  `URLS[...]` or `SERVICE[NEWPHOTO]` URLs from Telegram server.
 
 *example:* 
 ```bash
+########
+# download from Telegram server
+# photo received in a chat
+photo="${URLS[PHOTO]}")"
+echo "$photo" -> photo/file_1234.jpg
+
+# first download
+file="$(download_file "${photo}"
+echo "$file" -> ./data-bot-bash/photo-file_1234.jpg
+
+# second, third etc. download
+file="$(download_file "${photo}"
+echo "$file" -> ./data-bot-bash/jkdfhihsdkf-photo-file_1234.jpg
+
+
+########
+# download from other sources (full URL)
 file="$(download "https://avatars.githubusercontent.com/u/13046303" "avatar.jpg")"
 echo "$file" -> ./data-bot-bash/avatar.jpg
+
 file="$(download "https://avatars.githubusercontent.com/u/13046303" "avatar.jpg")"
-echo "$file" -> ./data-bot-bash/12345-avatar.jpg
+echo "$file" -> ./data-bot-bash/jhsdfjkakshdfkja-avatar.jpg
 ```
 
 ##### _exec_if_function
@@ -1455,6 +1477,9 @@ _is_function "background" && _message "you can run background jobs!"
 ### Bashbot internal functions
 These functions are for internal use only and must not used in your bot commands.
 
+##### get_file
+*usage:* url="$(get_file "CHAT[ID]" "message")"
+
 ##### procname
 Returns PrefixBotname_Postfix
 
@@ -1506,11 +1531,6 @@ killallproc
 
 ----
 
-##### get_file
-*usage:* url="$(get_file "CHAT[ID]" "message")"
-
-----
-
 ##### JsonDecode
 Outputs decoded string to STDOUT
 
@@ -1578,5 +1598,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.40-0-gf9dab50
+#### $$VERSION$$ v1.41-dev-3-gbc40a3f