doc: clearer explanation of .user.js url support

Author: ACTCD

README.md

@@ -60,8 +60,9 @@ After installing the iOS App, you need two main steps to make the extension work
 
 There are two main ways to install a user script from the iOS version:
 
-- Visit any `.user.js` URL in Safari, then open the extension `popup` and you will see an installation prompt
-- You can also save `.user.js` files directly to the Userscripts directory you set above
+- Visit a `.user.js` URL in Safari, then open the extension `popup` and you will see an installation prompt
+- The URL should ending with `.user.js` in `PATH` part, not the `?QUERY` or `#HASH` parts
+- You could also save files that extension with `.user.js` directly to the Userscripts directory you set above
 
 > [!TIP]
 >
@@ -177,10 +178,13 @@ Userscripts Safari currently supports the following userscript metadata:
   - when paired with `@updateURL`, this will allow the user to update a userscript from a remote source, if the version on their machine is `<` version at the update URL
   - `@version` does nothing by itself, it needs to be paired with` @updateURL` for remote updating to function properly
 - `@updateURL`
-  - the remote url to check version against
+  - the remote url to check version against, the url `PATH` should ending with `.meta.js` and contains the Metadata block
   - if the version of the file located at the update URL is `>` the version on the local machine, the file will be updated
   - `@updateURL` does nothing by itself, it needs to be paired with `@version` for remote updating to function properly
+  - Read this [link](https://stackoverflow.com/questions/38023717/) for more details
+  - _Note: The extension does not correctly implement the entire update process, tracking in issue [#248](https://github.com/quoid/userscripts/issues/248)_
 - `@downloadURL`
+  - the url `PATH` should ending with `.user.js`, that is, it cannot be in `?QUERY` or `#HASH` parts
   - optional download location for a remotely updateable file (\*i.e. a file that has both `@version` and `@updateURL`)
   - when paired with `@version` and `@updateURL`, if the local version is `<` the version of the file that `@updateURL` points to, the extension will attempt to update the file's code with the contents of the file located at the `@downloadURL`
   - `@downloadURL` does nothing by itself, it needs `@version` and `@updateURL` to present in order to function properly

src/app/_locales/en/quick-start-guide-ios.md

@@ -14,8 +14,11 @@
 
 ### How to you install a user script
 
-- Visit any `.user.js` URL in Safari, then open the extension popup and you will see an installation prompt, or it will pop up automatically if you have enhanced prompts turned on.
-- You can also save `.user.js` files directly to the Userscripts directory. The script file must contain a valid metadata block to match the page and be displayed in the extension popup.
+- The mobile extension does not currently have a built-in script editor, but you could still write your own scripts and install them.
+- You could save files that extension with `.user.js` directly to the Userscripts directory.
+  - The script file must contain a valid metadata block to match the web pages and be displayed in the extension popup.
+- When you visit a `.user.js` URL in Safari, open the extension popup and you will see an installation prompt, or it will pop up automatically if you have enhanced prompts turned on.
+  - The URL should ending with `.user.js` in `/PATH` part, not the `?QUERY` or `#HASH` parts, otherwise it will not be considered a valid user script URL by the extension.
 
 ### That’s it, start improving your quality of life now!
 

src/app/_locales/en/quick-start-guide-mac.md

@@ -12,6 +12,14 @@
   - Enable Userscripts in Safari extensions list.
   - For an optimal experience it's recommended that you "Always Allow" Userscripts for "All Websites", but you could also allow only the sites you want, but please don't forget your settings if your script doesn't work.
 
-That’s it, start improving your quality of life now!
+### How to you install a user script
+
+- The preferred method is of course to create your own scripts, open the extension page and click on the plus sign in the editor to create a new JS, write code and save it.
+- You could also save files that extension with `.user.js` directly to the Userscripts directory.
+  - The script file must contain a valid metadata block to match the web pages and be displayed in the extension popup.
+- When you visit a `.user.js` URL in Safari, open the extension popup and you will see an installation prompt, or it will pop up automatically if you have enhanced prompts turned on.
+  - The URL should ending with `.user.js` in `/PATH` part, not the `?QUERY` or `#HASH` parts, otherwise it will not be considered a valid user script URL by the extension.
+
+### That’s it, start improving your quality of life now!
 
 _Hey, don't forget to read our detailed documentation to learn more._

src/app/_locales/zh/quick-start-guide-ios.md

@@ -13,8 +13,11 @@
 
 ### 那么，如何安装用户脚本？
 
-- 在 Safari 中访问任何 `.user.js` 网址，然后打开扩展弹出窗口，您将看到安装提示；如果您启用了增强提示，它会自动弹出。
-- 您还可以将 `.user.js` 文件直接保存到您上面设置的 Userscripts 目录中，脚本文件必须包含有效的元数据块以匹配页面并显示在扩展弹出窗口中。
+- 移动版扩展目前不包含内置的脚本编辑器，但您仍然可以编写您自己的脚本并安装它们。
+- 您可以直接保存扩展名为 `.user.js` 的文件到您上面设置的 Userscripts 目录中。
+  - 您的脚本文件必须包含有效的元数据块以匹配网站页面并正确显示在扩展的弹出窗口中。
+- 当您在 Safari 中访问一个 `.user.js` 网址，然后打开扩展弹出窗口，您将看到安装提示；如果您启用了增强提示，它会自动弹出。
+  - 请注意该网址的 `/路径` 部分应该以 `.user.js` 结尾，而不是 `?查询` 或 `#锚点` 部分，否则该网址将不会被视为有效的用户脚本。
 
 ### 就这样，现在就开始改善您的生活质量吧！
 

src/app/_locales/zh/quick-start-guide-mac.md

@@ -11,6 +11,14 @@
   - 在 Safari 扩展列表中启用 Userscripts 条目。
   - 为了获得最佳体验，建议您“始终允许” Userscripts 为“所有网站”，但您也可以仅允许您想要的网站，但当您的脚本不起作用时，请不要忘记您的设置。
 
-就这样，现在就开始改善您的生活质量吧！
+### 那么，如何安装用户脚本？
+
+- 首选的方法当然是撰写您自己的用户脚本，打开扩展页面点击加号创建新脚本，编辑和保存它。
+- 您还可以直接保存扩展名为 `.user.js` 的文件到您上面设置的 Userscripts 目录中。
+  - 您的脚本文件必须包含有效的元数据块以匹配网站页面并正确显示在扩展的弹出窗口中。
+- 当您在 Safari 中访问一个 `.user.js` 网址，然后打开扩展弹出窗口，您将看到安装提示；如果您启用了增强提示，它会自动弹出。
+  - 请注意该网址的 `/路径` 部分应该以 `.user.js` 结尾，而不是 `?查询` 或 `#锚点` 部分，否则该网址将不会被视为有效的用户脚本。
+
+### 就这样，现在就开始改善您的生活质量吧！
 
 _嘿，不要忘记阅读我们的详细文档以了解更多信息。_

src/app/_locales/zh_Hant/quick-start-guide-ios.md

@@ -13,8 +13,11 @@
 
 ### 那麼，如何安裝使用者腳本？
 
-- 在 Safari 中訪問任何 `.user.js` 網址，然後開啟延伸功能彈出視窗，您將看到安裝提示；如果您啟用了增強提示，它會自動彈出。
-- 您還可以將 `.user.js` 檔案直接儲存到您上面設定的 Userscripts 目錄中，腳本檔案必須包含有效的元資料塊以匹配頁面並顯示在延伸功能彈出視窗中。
+- 移動版延伸功能目前不包含內建的腳本編輯器，但您仍然可以編寫您自己的腳本並安裝它們。
+- 您可以直接儲存副檔名為 `.user.js` 的檔案到您上面設定的 Userscripts 目錄中。
+  - 您的腳本檔案必須包含有效的元資料塊以匹配網站頁面並正確顯示在延伸功能的彈出視窗中。
+- 當您在 Safari 中訪問一個 `.user.js` 網址，然後開啟延伸功能彈出視窗，您將看到安裝提示；如果您啟用了增強提示，它會自動彈出。
+  - 請注意該網址的 `/路徑` 部分應該以 `.user.js` 結尾，而不是 `?查詢` 或 `#錨點` 部分，否則該網址將不會被視為有效的使用者腳本。
 
 ### 就這樣，現在就開始改善您的生活質量吧！
 

src/app/_locales/zh_Hant/quick-start-guide-mac.md

@@ -11,6 +11,14 @@
   - 在 Safari 延伸功能列表中啟用 Userscripts 條目。
   - 為了獲得最佳體驗，建議您“始終允許” Userscripts 為“所有網站”，但您也可以僅允許您想要的網站，但當您的腳本不起作用時，請不要忘記您的設定。
 
-就這樣，現在就開始改善您的生活質量吧！
+### 那麼，如何安裝使用者腳本？
+
+- 首選的方法當然是撰寫您自己的使用者腳本，開啟延伸功能頁面點選加號建立新腳本，編輯和儲存它。
+- 您還可以直接儲存副檔名為 `.user.js` 的檔案到您上面設定的 Userscripts 目錄中。
+  - 您的腳本檔案必須包含有效的元資料塊以匹配網站頁面並正確顯示在延伸功能的彈出視窗中。
+- 當您在 Safari 中訪問一個 `.user.js` 網址，然後開啟延伸功能彈出視窗，您將看到安裝提示；如果您啟用了增強提示，它會自動彈出。
+  - 請注意該網址的 `/路徑` 部分應該以 `.user.js` 結尾，而不是 `?查詢` 或 `#錨點` 部分，否則該網址將不會被視為有效的使用者腳本。
+
+### 就這樣，現在就開始改善您的生活質量吧！
 
 _嘿，不要忘記閱讀我們的詳細文件以瞭解更多資訊。_