Overhaul SuperWeapon Sidebar docs

Author: Metadorius

docs/User-Interface.md

@@ -679,21 +679,34 @@ In `RA2MD.INI`:
 ToolTipBlur=false  ; boolean, whether the blur effect of tooltips will be enabled.
 ```
 
-### Exclusive SuperWeapon Sidebar
+### SuperWeapon Sidebar
 
-![image](_static/images/sw_sidebar-01-on.png)
-![image](_static/images/sw_sidebar-02-on.png)
+![image](_static/images/sw_sidebar.png)
+*SuperWeapon Sidebar used with vanilla-like assets for from [Phobos supplementaries](https://github.com/Phobos-developers/PhobosSupplementaries)*
 
-- It is possible to put sw cameos on the left of screen like C&C3 when `SuperWeaponSidebar` is true. Cameos arranged in a pyramid shape. In theory, it should be compatible with Ares.
+- It is possible to put superweapon cameos on the left of screen like C&C3 when `SuperWeaponSidebar` is true. Cameos are arranged in a pyramid shape.
+  - Superweapon Sidebar is compatible with Ares superweapons.
   - `SuperWeaponSidebar.Interval` controls the distance between two column cameos (excluding the background). When you need to make a background, the width of the background should be (`SuperWeaponSidebar.Interval` + cameo fixed width 60).
-  - `SuperWeaponSidebar.LeftOffset` controls the distance between the left side of cameo and the left side of its column (background). This will not be greater than `SuperWeaponSidebar.Interval`.
-  - `SuperWeaponSidebar.CameoHeight` controls the distance from the top of the previous cameo to the top of the next cameo. That is, the space between the upper and lower cameos is (`SuperWeaponSidebar.CameoHeight` - cameo fixed height 48). This will not be less than 48. When you need to make a background, this is the height of the background.
+  - `SuperWeaponSidebar.LeftOffset` controls the distance between the left side of cameo and the left side of its column (background). This should not be greater than `SuperWeaponSidebar.Interval`.
+  - `SuperWeaponSidebar.CameoHeight` controls the distance from the top of the previous cameo to the top of the next cameo. That is, the space between the upper and lower cameos is (`SuperWeaponSidebar.CameoHeight` - cameo fixed height 48). This should not be less than 48. When you need to make a background, this is the height of the background.
   - `SuperWeaponSidebar.Max` controls the maximum number of cameos on the leftmost column, which also depends on the current game resolution.
   - `SuperWeaponSidebar.MaxColumns` controls that maximum count of columns.
-  - Only sw with `SuperWeaponSidebar.Significance` not lower than `SuperWeaponSidebar.RequiredSignificance` are allowed to be added to the sw sidebar.
-- `SuperWeaponSidebarKeysEnabled` should be true that you can use hotkeys about superweapon sidebar.
-- You can also launch first 10 SW by hotkey in INTERFACE category.
-  - For localization of hotkey, add `TXT_FIRE_TACTICAL_SW_XX`, `TXT_FIRE_TACTICAL_SW_XX_DESC`, `TXT_TOGGLE_SW_SIDEBAR` and `TXT_TOGGLE_SW_SIDEBAR_DESC` into your `.csf` file.
+  - `SuperWeaponSidebar.Significance` is needed for user to control which superweapons appear on the sidebar. Only superweapons with `SuperWeaponSidebar.Significance` not lower than user-defined `SuperWeaponSidebar.RequiredSignificance` are shown on the superweapon sidebar.
+
+```{warning}
+While a mod maker can "ban" certain superweapons from appearing on a sidebar completely using `SuperWeaponSidebar.Allow=false` and `SuperWeaponSidebar.AllowByDefault=false`, it is not recommended to use those keys outside of removing "technical" superweapons (like subfaction choosers). Instead, opt for `SuperWeaponSidebar.Significance` and `SuperWeaponSidebar.RequiredSignificance` to control which superweapons appear on the sidebar. This way users with different preferences and different display resolutions could control how many superweapons they would like to see on the sidebar (via client settings) without having to edit the mod files, and you would be able to specify your exact vision through the default significance value.
+```
+
+  - There is a hotkey to toggle the sidebar on/off, which can be bound to a key in the hotkey settings.
+    - `TXT_TOGGLE_SW_SIDEBAR` and `TXT_TOGGLE_SW_SIDEBAR_DESC` are used for localization of the hotkey.
+  - `SuperWeaponSidebarKeysEnabled` enables users to use hotkeys for superweapons displayed on the sidebar.
+    - The hotkeys are positional and are only provided for the first 10 superweapons.
+    - If assigned, a hotkey will be displayed on a superweapon instead of the `Ready` (or its alternative) text.
+    - For localization of those hotkeys, add `TXT_FIRE_TACTICAL_SW_XX` and `TXT_FIRE_TACTICAL_SW_XX_DESC` into your `.csf` file.
+
+```{warning}
+Positional superweapon hotkeys are an experimental feature and currently the user experience may be not polished enough, due to superweapon positions not being fixed on the sidebar, thus the feature is disabled by default.
+```
 
 In `uimd.ini`:
 ```ini
@@ -733,3 +746,7 @@ In `ra2md.ini`
 [Phobos]
 SuperWeaponSidebar.RequiredSignificance=0   ; integer
 ```
+
+```{hint}
+While the feature is usable without any extra graphics, you can find example assets to use with vanilla graphics on [Phobos supplementaries repo](https://github.com/Phobos-developers/PhobosSupplementaries)).
+```