Update troubleshooting doc.

end-4 · Feb 28, 2025 · ee8e1df · ee8e1df
1 parent 5492136
commit ee8e1df
Showing 1 changed file with 35 additions and 28 deletions.
diff --git a/src/content/docs/en/i-i/04.troubleshooting.md b/src/content/docs/en/i-i/04.troubleshooting.md
@@ -8,7 +8,8 @@ lastUpdated: 2024-02-24
 On this page, press `Ctrl`+`F` to search or see the right sidebar to find your problem
 :::
 
-# Prerequisite for environment variable
+# Must read
+## Prerequisite for environment variable
 :::note
 We've already given you related notice in `install.sh` but some users ignored it when submitting issues.
 :::
@@ -47,16 +48,19 @@ env = ILLOGICAL_IMPULSE_VIRTUAL_ENV, /home/myself/.local/state/ags/.venv
 ```
 And remember to replace `myself` with actual username.
 
-# Hints
+## Actions you should try at least once
+- Restart Hyprland, or reboot your system. Necessary to apply environment variable changes.
+- If things related to AGS (i.e. the "bars") have problem, switch a wallpaper by pressing `Super+Ctrl+T` and choosing a picture in prompted window. It's not 100% useful though, especially when your installation or environment variable has problem in the first place.
+- The script `install.sh` is idempotent. You may run it again anytime as you like.
 
-- If there's a problem with something, the first thing to do is to fire up a terminal (`Super`+`T`) and run it. Look for errors/warnings that could be problematic.
-- The bar, sidebars, cheatsheet, etc. are powered by AGS. Open a terminal and run `pkill agsv1; agsv1`.
-- The script `install.sh` is idempotent, so you may run it again anytime.
+## How to get logs
+- If there's a problem with something, fire up a terminal (`Super`+`T`) and run it in shell. Look for errors/warnings that could be problematic.
+- The bar, sidebars, cheatsheet, etc. are powered by AGS. (Tip: It's not waybar.) Open a terminal and run `pkill agsv1; agsv1`.
 
-> Use some common sense. If you can't figure out, [open a discussion](https://github.com/end-4/dots-hyprland/discussions) for help.
-
-# Some problems
+## Misc information
+- Use some common sense. If you can't figure out, [open a discussion](https://github.com/end-4/dots-hyprland/discussions) for help.
 
+# Some problems & solutions/workarounds
 ## AGS / bars theme/icons/CSS breaks/not working
 > Reference: [end-4/dots-hyprland#1010](https://github.com/end-4/dots-hyprland/issues/1010)
 
@@ -79,7 +83,7 @@ gsettings set org.gnome.desktop.interface icon-theme Papirus
 ```
 Of course you must install it first, for Arch Linux use `sudo pacman -S papirus-icon-theme`.
 
-### Use `gsettings` to set icon theme
+### Set substitutions in AGS `user_options.js`
 :::note
 This is suitable for the following situation:
 - The application has more than one kinds of window class name (e.g. `foot` and `footclient`), but only one of them (e.g. `foot`) has exact matching icon in current icon theme.
@@ -132,25 +136,6 @@ consider the following steps:
 - Note that it's Material <u>**Symbols**</u>, not Material <u>**Icons**</u>!
 - Remember to `fc-cache -fv` to refresh font cache. A reboot will also work.
 
-## AGS installation failed
-### `PermissionError: [Errno 13] Permission denied: '/usr/local/lib/libgvc.so'`
-Run this to check whether this file belongs to any package (very likely not, because it's inside `/usr/local`)
-```bash
-pacman -Qo /usr/local/lib/libgvc.so
-```
-If not, then it's probably safe to just remove it. To do so, run this:
-```bash
-sudo mv /usr/local/lib/libgvc.so /tmp/
-```
-
-### Other errors
-Delete `./cache/ags` and install it again.
-
-## Hyprland installation failed
-Sometimes the AUR package doesn't install all the dependencies for you. Hyprland is always evolving and this happens when something new is added
-- Check the logs and see if it tells you to install something, then attempt to build it again
-- Note: You might have to clear `~/.cache/yay`
-
 ## `loginctl lock-session` does nothing
 > Reference: [end-4/dots-hyprland#278](https://github.com/end-4/dots-hyprland/issues/278)
 
@@ -175,3 +160,25 @@ This is not related to illogical-impulse technically.
 :::
 See https://github.com/end-4/dots-hyprland/issues/746 .
 
+# Deprecated problems solutions&workarounds
+The content below are not useful anymore cuz things has changed.
+
+Still keep them here in case we need them again in future.
+## AGS installation failed
+### `PermissionError: [Errno 13] Permission denied: '/usr/local/lib/libgvc.so'`
+Run this to check whether this file belongs to any package (very likely not, because it's inside `/usr/local`)
+```bash
+pacman -Qo /usr/local/lib/libgvc.so
+```
+If not, then it's probably safe to just remove it. To do so, run this:
+```bash
+sudo mv /usr/local/lib/libgvc.so /tmp/
+```
+
+### Other errors
+Delete `./cache/ags` and install it again.
+
+## Hyprland installation failed
+Sometimes the AUR package doesn't install all the dependencies for you. Hyprland is always evolving and this happens when something new is added
+- Check the logs and see if it tells you to install something, then attempt to build it again
+- Note: You might have to clear `~/.cache/yay`