#390: Add troubleshooting info for GUI not appearing

README.md

@@ -74,6 +74,7 @@ Note:
 <a name="redirects"></a>
 <a name="roots"></a>
 <a name="selective-scanning"></a>
+<a name="troubleshooting"></a>
 
 Detailed help documentation is available for several topics.
 
@@ -99,6 +100,9 @@ Detailed help documentation is available for several topics.
 * [Environment variables](/docs/help/environment-variables.md)
 * [Logging](/docs/help/logging.md)
 
+### Other
+* [Troubleshooting](/docs/help/troubleshooting.md)
+
 ## Community
 
 The community has created some additional resources you may find useful.
@@ -142,25 +146,5 @@ cross-platform and cross-store solution:
   * Database is not actively updated. As of 2022-11-16, the last update was 2018-06-05.
   * No command line interface.
 
-## Troubleshooting
-* The window content is way too big and goes off screen.
-  * Try setting the `WINIT_X11_SCALE_FACTOR` environment variable to `1`.
-    Flatpak installs will have this set automatically.
-* The file/folder picker doesn't work.
-  * **Linux:** Make sure that you have Zenity or kdialog installed and available on the `PATH`.
-    The `DISPLAY` environment variable must also be set.
-  * **Steam Deck:** Use desktop mode instead of game mode.
-  * **Flatpak:** The `DISPLAY` environment variable may not be getting passed through to the container.
-    This has been observed on GNOME systems.
-    Try running `flatpak run --nosocket=fallback-x11 --socket=x11 com.github.mtkennerly.ludusavi`.
-* On Windows 11, when I open the GUI, a console window also stays open.
-  * This is a limitation of the new Windows Terminal app (https://github.com/microsoft/terminal/issues/14416).
-    It should be fixed once Windows Terminal v1.17 is released.
-    In the meantime, you can work around it by opening Windows Terminal from the Start Menu,
-    opening its settings, and changing the "default terminal application" to "Windows Console Host".
-* The GUI won't launch.
-  * There may be an issue with your graphics drivers/support.
-    Try using the software renderer instead by setting the `ICED_BACKEND` environment variable to  `tiny-skia`.
-
 ## Development
 Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).

docs/help/troubleshooting.md

@@ -0,0 +1,36 @@
+# Troubleshooting
+* The window content is way too big and goes off screen.
+  * Try setting the `WINIT_X11_SCALE_FACTOR` environment variable to `1`.
+    Flatpak installs will have this set automatically.
+* The file/folder picker doesn't work.
+  * **Linux:** Make sure that you have Zenity or kdialog installed and available on the `PATH`.
+    The `DISPLAY` environment variable must also be set.
+  * **Steam Deck:** Use desktop mode instead of game mode.
+  * **Flatpak:** The `DISPLAY` environment variable may not be getting passed through to the container.
+    This has been observed on GNOME systems.
+    Try running `flatpak run --nosocket=fallback-x11 --socket=x11 com.github.mtkennerly.ludusavi`.
+* On Windows 11, when I open the GUI, a console window also stays open.
+  * This is a limitation of the new Windows Terminal app (https://github.com/microsoft/terminal/issues/14416).
+    It should be fixed once Windows Terminal v1.17 is released.
+    In the meantime, you can work around it by opening Windows Terminal from the Start Menu,
+    opening its settings, and changing the "default terminal application" to "Windows Console Host".
+* The GUI won't launch.
+  * There may be an issue with your graphics drivers/support.
+    Try using the software renderer instead by setting the `ICED_BACKEND` environment variable to `tiny-skia`.
+  * You can try prioritizing different hardware renderers
+    by setting the `WGPU_BACKEND` environment variable to `dx12`, `vulkan`, or `metal`.
+  * **Flatpak:** You can try forcing X11 instead of Wayland:
+    `flatpak run --nosocket=wayland --socket=x11 com.github.mtkennerly.ludusavi`
+
+## Environment variables on Windows
+Some of the instructions above mention setting environment variables.
+If you're using Windows and not familiar with how to do this,
+you can follow these instructions:
+
+* Open the Start Menu,
+  search for `edit the system environment variables`,
+  and select the matching result.
+* In the new window, click the `environment variables...` button.
+* In the upper `user variables` section, click the `new...` button,
+  then enter the variable name and value.
+  If the variable already exists, select it and click `edit...`.