Documentation update.

CHANGELOG.md

@@ -136,8 +136,17 @@ Many bugs have been fixed, and numerous features that were only partially implem
 
 ### Known issues
 
+**The issues below are relevant for ES-DE v1.0.0.**
+
+* On Linux, running games or emulators that switch the screen resolution may cause problems if ES-DE is run in Normal fullscreen mode, most likely due to driver bugs or possibly issues in SDL. Only a white screen will be shown when returning from the game and although the application is still running, attempting to navigate blindly will lead to a crash. Using the Borderless mode resolves the issue but removes the ability to switch windows using Alt-tab. Running ES-DE with the --window flag is another workaround, but that leaves the window border intact around the application window. Hopefully this issue will be worked around in ES-DE v1.1 as improving the fullscreen mode is planned for that release.
+
+* On Ubuntu 20.10, the included VLC version 3.0.11.1-2 is broken so ES-DE will crash when attempting to play videos. This can be fixed by manually replacing the file /lib/x86_64-linux-gnu/libvlccore.so.9.0.0 with the corresponding file from version 3.0.9.2-1 from Ubuntu 20.04. Make sure that the /lib/x86_64-linux-gnu/libvlccore.so.9 symlink points to this file as well. Hopefully this issue will soon be patched in libVLC so that this manual workaround will not be required.
+
 * The input configuration can be a bit glitchy on some devices, most notably the setup of trigger buttons for Xbox and PlayStation controllers. Once configured everything should work fine though. This configuration issue will hopefully be resolved in ES-DE v1.1 with the move to the SDL2 GameController API.
-* Some artifacts can be present with the gaussian blur shader, and screen tearing can be seen when using the slide transitions with certain graphics drivers and resolutions. Both of these issues only affect the upper part of the screen. The second issue is apparently more prevalent when running ES-DE at a lower resolution on 4K displays by using the --resolution command line option. These problems will hopefully be resolved in ES-DE v1.2 when moving to the GLM library.
+* Some artifacts can be present with the gaussian blur shader, and screen tearing can be seen when using the slide transitions with certain graphics drivers and resolutions. Both of these issues mostly affect the upper part of the screen. The second issue is apparently more prevalent when running ES-DE at a lower resolution on 4K displays by using the --resolution command line option (which is only available on Unix). These problems will hopefully be resolved in ES-DE v1.2 when moving to the GLM library.
-* The launching of games can freeze ES-DE on some Windows installations. It probably only occurs on Windows 8.1 and older but that's not confirmed. The setting 'Run in background (while game is launched)' can be enabled to get around this problem, but this causes some other issues so it should only be used as a last resort. It's unclear if this problem can or will be resolved. If it's confirmed to only affect older Windows versions, then it's probably not worthwhile fixing it.
+
+* The launching of games can freeze ES-DE on some Windows installations. It probably only occurs on Windows 8.1 but that's not confirmed. The setting 'Run in background (while game is launched)' can be enabled to get around this problem, but this causes some other issues so it should only be used as a last resort. It's unclear if this problem can or will be resolved. If it's confirmed to only affect older Windows versions, then it's probably not worthwhile fixing it.
+
 * On Windows, if not running ES-DE on the primary display and the display where it runs does not have the same scaling percentage as the primary display, then the ES-DE resolution will not be properly set. The application will still work and if running in fullscreen mode it may not even be noticeable. This issue is caused by a bug in SDL where the primary display scaling is always used for calculating the display bounds and as such it needs to be fixed in that library. If using the same scaling percentage across all monitors, or if not using high DPI monitors at all, then this issue will not occur.
+
 * Scraping using ScreenScraper could lead to errors when exceeding the allowed requests per minute. This will cause a popup window to be displayed in ES-DE with the option available to retry the scraping for the current game (you should first wait a minute or so though or the error will immediately reoccur). This is not really a fault in the application per-se but rather a restriction of ScreenScraper. A request per minute limiter is planned for ES-DE v1.4, which should help with avoiding this problem.

README.md

@@ -20,7 +20,7 @@ The current version 1.0 has been tested on the following operating systems (all
 * Windows 10
 * Windows 8.1
 
-***)** For Ubuntu 20.10, the included VLC version 3.0.11.1-2 is broken so ES-DE will crash when attempting to play videos. This can be fixed by manually replacing the file /lib/x86_64-linux-gnu/libvlccore.so.9.0.0 with the corresponding file from version 3.0.9.2-1 from Ubuntu 20.04. Make sure that the /lib/x86_64-linux-gnu/libvlccore.so.9 symlink points to this file as well. Hopefully this issue will soon be patched so that this manual workaround is not required.
+***)** On Ubuntu 20.10, attempting to play videos crashes ES-DE due to a libVLC bug, refer to the Known issues section in [CHANGELOG.md](CHANGELOG.md#known-issues) for a workaround.
 
 At the moment Raspberry Pi is not supported, but this is planned for future releases. It may still be possible to compile and run ES-DE on this device, but as of v1.0 it's not actively used during development and therefore not tested.
 

USERGUIDE.md

@@ -42,7 +42,7 @@ The following operating systems have been tested (all for the x86 architecture):
 * Windows 10
 * Windows 8.1
 
-***)** For Ubuntu 20.10, the included VLC version 3.0.11.1-2 is broken so ES-DE will crash when attempting to play videos. This can be fixed by manually replacing the file /lib/x86_64-linux-gnu/libvlccore.so.9.0.0 with the corresponding file from version 3.0.9.2-1 from Ubuntu 20.04. Make sure that the /lib/x86_64-linux-gnu/libvlccore.so.9 symlink points to this file as well. Hopefully this issue will soon be patched so that this manual workaround is not required.
+***)** On Ubuntu 20.10, attempting to play videos crashes ES-DE due to a libVLC bug, refer to the Known issues section in [CHANGELOG.md](CHANGELOG.md#known-issues) for a workaround.
 
 The installation procedure is just covered briefly here and may differ a bit for your specific operating system, so in case of problems refer to your system documentation.
 
@@ -371,6 +371,8 @@ Apart from this, DOS games should work the same as any other system. The game fo
 
 #### Ports
 
+**Note: On Unix/Linux, if you get a white screen in ES-DE after returning from a game that switches screen resolution then refer to the Known issues section in [CHANGELOG.md](CHANGELOG.md#known-issues) for a workaround.**
+
 Ports are not really executed using emulators, but are rather applications running natively in the operating system. The easiest way to handle these is to add a simple shell script or batch file where you can customize the exact launch parameters for the game.
 
 It's of course possible to add these as single files to the root folder, but normally it's recommended to setup a separate folder per game as there may be more than a single file available per game. You very often want to have easy access to the game setup utility for instance.
@@ -421,6 +423,8 @@ You don't need to set execution permissions for these scripts, ES-DE will run th
 
 #### Lutris
 
+**Note: If you get a white screen in ES-DE after returning from a game that switches screen resolution then refer to the Known issues section in [CHANGELOG.md](CHANGELOG.md#known-issues) for a workaround.**
+
 Lutris runs only on Unix so it's only present as a placeholder in the es_systems.cfg templates for macOS and Windows.
 
 These games are executed via the Lutris binary (well it's actually a Python script), and you simply create a shell script per game using the syntax `lutris lutris:rungame/<game name>`
@@ -455,6 +459,8 @@ As an alternative, you can add the Lutris games to the Ports game system, if you
 
 #### Steam
 
+**Note: As of ES-DE v1.0, launching Steam games doesn't work reliably so it's recommended to avoid it for the time being. Future versions will hopefully improve Steam support.**
+
 For steam, it's recommended to put shell scripts/batch files directly in the root folder, where the file names of these scripts correspond to the game names.
 
 Add the game information to each file using the syntax `steam steam://rungameid/<game ID>`
@@ -533,7 +539,7 @@ Here is an overview of what's supported by ES-DE and these scrapers:
 
 The category **Other game metadata** includes Description, Release date, Developer, Publisher, Genre and Players.
 
-The **Multi-language** support includes translated game genre names and game descriptions for a number of languages.
+The **Multi-language** support includes translated game genres and game descriptions for a number of languages.
 
 There are two approaches to scraping, either for a single game from the metadata editor, or for many games and systems using the multi-scraper.
 
@@ -706,7 +712,7 @@ The region to scrape for. This affects game names, game media and release dates.
 
 **Preferred language** _(ScreenScraper only)_
 
-Multiple languages are supported, and this affects game genre names and game descriptions. As the option name implies this is the preferred language only, as not all games on ScreenScraper have had their metadata translated to all supported languages. If the preferred language is not available for a game, ES-DE will fall back to scraping the English metadata.
+Multiple languages are supported by ScreenScraper, and this affects translations of game genres and game descriptions. As the option name implies this is the preferred language only as not all games have had their metadata translated. Unfortunately some less used languages have quite few games translated to them but hopefully this will improve over time as there's an ongoing community effort to make more translations. If the preferred language is not available for a game, ES-DE will fall back to scraping the English metadata.
 
 **Overwrite files and data**
 
@@ -746,7 +752,7 @@ Enabling this option causes folders themselves to be included by the scraper. Th
 
 Various settings that affects the user interface.
 
-**Gamelist to show on startup**
+**Gamelist on startup**
 
 If set to _None_, the system view will be showed. Any other value will jump to that game system automatically on startup.