Documentation update.

CHANGELOG.md

@@ -44,6 +44,7 @@ Apart from this, many small improvements and bug fixes are part of the release,
 * Moved the input device configuration tool to the input device settings menu
 * Adjusted the size and position of the various menus to accomodate one additional entry on the screen
 * The quit menu is now disabled by default, instead showing the "Quit EmulationStation" entry unless configured otherwise
+* Removed the "Display game media from ROM directories" setting as it doesn't make sense to support this legacy functionality any longer
 * Removed the menu fade-in effect as it looked terrible
 * Enabled the menu scale-up effect for the OpenGL ES renderer
 * Renamed es_systems.cfg, es_settings.cfg and es_input.cfg to es_systems.xml, es_settings.xml and es_input.xml
@@ -51,6 +52,8 @@ Apart from this, many small improvements and bug fixes are part of the release,
 * Removed the marquee image from rbsimple-DE as it's now baked into the miximages
 * Set the gamelist video scanline rendering option to disabled by default
 * Changed the setting description for the favorites game toggling button
+* The themes and scripts directories are now automatically created during startup
+* Cleaned up some application startup messages
 * The application version is now saved to es_settings.xml, which can be used in the future to notify the user after upgrades to a newer release
 * Added a DebugSkipInputLogging option which is intended primarily for development and needs to be manually set in es_settings.xml
 * Added the CImg library as a Git subtree and created some utility functions for it (used by the miximage generator and the game launch screen)

INSTALL-DEV.md

@@ -1348,7 +1348,7 @@ You can use **--help** or **-h** to view the list of command line options, as sh
 --help, -h                      Summon a sentient, angry tuba
 ```
 
-As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES-DE will use `~/games/emulation/.emulationstation` as its base directory.
+As you can see above, you can override the home directory path using the `--home` flag. So by running for instance the command `emulationstation --home ~/games/emulation`, ES-DE will use `~/games/emulation/.emulationstation` as its application home directory. Be aware that this option completely replaces what is considered the home directory, meaning the default ROM directory ~/ROMs would be resolved to ~/games/emulation/ROMs. The same is true for the emulator core locations if es_find_rules.xml is configured to look for them relative to the home directory. So of course RetroArch and other emulators would also need to be configured to use ~/games/emulation as its base directory in this instance.
 
 For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter:
 ```
@@ -1367,7 +1367,7 @@ The es_systems.xml file contains the system configuration data for ES-DE, writte
 
 ES-DE ships with a comprehensive `es_systems.xml` configuration file and normally you shouldn't need to modify this. However there may be special circumstances such as wanting to use alternative emulators for some game systems or perhaps you need to add additional systems altogether.
 
-To make a customized version of the systems configuration file, it first needs to be copied to `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows.)
+To make a customized version of the systems configuration file, it first needs to be copied to `~/.emulationstation/custom_systems/es_systems.xml`. (The tilde symbol `~` translates to `$HOME` on Unix and macOS, and to `%HOMEPATH%` on Windows unless overridden using the --home command line option.)
 
 The bundled es_systems.xml file is located in the resources directory that is part of the application installation. For example this could be `/usr/share/emulationstation/resources/systems/unix/es_systems.xml` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/resources/systems/macos/es_systems.xml` on macOS and `C:\Program Files\EmulationStation-DE\resources\systems\windows\es_systems.xml` on Windows. The actual location may differ from these examples of course, depending on where ES-DE has been installed.
 
@@ -1591,7 +1591,7 @@ Each rule supports multiple entry tags which are tried in the order that they ar
 
 The %EMUPATH% and %ESPATH% variables can also be used inside the entry tags, making for quite powerful find rules.
 
-The tilde symbol `~` is supported and will expand to the user home directory.
+The tilde symbol `~` is supported and will expand to the user home directory. Be aware that if ES-DE has been started with the --home command line option, the home directory is considered to be whatever path was passed as an argument to this option.
 
 For reference, here are also example es_find_rules.xml files for macOS and Windows:
 

THEMES.md

@@ -595,7 +595,7 @@ or to specify only a portion of the value of a theme property:
 
 * NORMALIZED_PAIR - two decimals, in the range [0..1], delimited by a space.  For example, `0.25 0.5`.  Most commonly used for position (x and y coordinates) and size (width and height).
 * NORMALIZED_RECT - four decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5 0.10 0.30`.  Most commonly used for padding to store top, left, bottom and right coordinates.
-* PATH - a path.  If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` for Linux or `%HOMEPATH%` for Windows).  If the first character is a `.`, it will be expanded to the theme file's directory, allowing you to specify resources relative to the theme file, like so: `./../general_art/myfont.ttf`.
+* PATH - a path.  If the first character is a `~`, it will be expanded into the environment variable for the home path (`$HOME` for Linux or `%HOMEPATH%` for Windows) unless overridden using the --home command line option.  If the first character is a `.`, it will be expanded to the theme file's directory, allowing you to specify resources relative to the theme file, like so: `./../general_art/myfont.ttf`.
 * BOOLEAN - `true`/`1` or `false`/`0`.
 * COLOR - a hexidecimal RGB or RGBA color (6 or 8 digits).  If 6 digits, will assume the alpha channel is `FF` (not transparent).
 * FLOAT - a decimal.

USERGUIDE-DEV.md

@@ -76,10 +76,12 @@ There's not really much to say about these operating systems, just install ES-DE
 
 **On first application startup**
 
-Upon first startup, ES-DE will create its home directory, by default the location is ~/.emulationstation.
+Upon first startup, ES-DE will create its `~/.emulationstation` home directory.
 
 On Unix this means /home/\<username\>/.emulationstation/, on macOS /Users/\<username\>/.emulationstation/ and on Windows C:\Users\\<username\>\\.emulationstation\
 
+It's also possible to override the home directory path using the --home command line option, but this is normally required only for very special situations so we can safely ignore that option for now.
+
 **Note:** As of ES-DE v1.1 there is no internationalization support, so you would always need to supply the English directory name for your home directory, which is by the way always the real physical name on the file system. For instance on macOS, /Users/myusername will be required instead of /Användare/myusername which is what's shown inside the operating system for a Swedish localized installation. But using the tilde home symbol '~' is a workaround for this, and it's recommended to always use it for any ES-DE configuration settings that require a path to your home directory as it removes any confusion regarding localized home directory paths.
 
 On first startup the configuration file `es_settings.xml` will be generated in the ES-DE home directory, containing all the default settings. A file named `es_systems.xml` will be loaded from the resources directory (which is part of the ES-DE installation). This file contains the game ROM paths and emulator settings and it can be customized if needed. The customized version needs to be placed in the `custom_systems` folder in the ES-DE home directory, for example `~/.emulationstation/custom_systems/es_systems.xml`. For more information on how to do this, refer to the [INSTALL-DEV.md](INSTALL-DEV.md#es_systemsxml) document.
@@ -310,7 +312,7 @@ It's required that the ROM files are in one of the supported file extensions, or
 
 It's highly recommended to use filenames that are corresponding to the full name of the game, otherwise you will need to manually feed the scraper the game name when scraping which is very tedious.
 
-The default game directory folder is ~/ROMs. On Unix this defaults to /home/\<username\>/ROMs, on macOS /Users/\<username\>/ROMs and on Windows C:\Users\\<username\>\ROMs\.
+The default game directory folder is ~/ROMs. On Unix this defaults to /home/\<username\>/ROMs, on macOS /Users/\<username\>/ROMs and on Windows C:\Users\\<username\>\ROMs\. Be aware that if the --home command line option was used to start ES-DE, the tilde `~` symbol will resolve to whatever directory was passed as an argument to this option.
 
 If ES-DE can't find any game files during startup, an error message will be displayed with the option to change the ROM directory path.
 
@@ -693,8 +695,6 @@ JPG and PNG file formats and file extensions are supported for images, and AVI,
 
 Remember that on Unix files are case sensitive, and as well the file extensions must be in lower case, such as .png instead of .PNG or .Png or the file won't be found.
 
-As an alternative, you can also locate your game media in the ROM directory. This is explained below when covering the option **Display game media from ROM directories**. This is however not recommended and the built-in scraper will never save any game media to this folder structure.
-
 It's possible to change the game media directory from within ES-DE, for this see the option **Game media directory**.
 
 
@@ -1211,10 +1211,6 @@ It's possible to trigger custom scripts for a number of actions in ES-DE, as is
 
 If enabled, only ROMs that have metadata saved to the gamelist.xml files will be shown in ES-DE. This option is intended primarily for testing and debugging purposes so it should normally not be enabled.
 
-**Display game media from ROM directories**
-
-Using this option, you can place game images and videos in the ROM directory tree. The media files are searched inside the directory _\<ROM directory\>/\<system name\>/images/_ and _\<ROM directory\>/\<system name\>/videos/_ and the filenames must match the ROM names, followed by a dash and the media type. For example _~/ROMs/nes/images/Contra-screenshot.jpg, ~/ROMs/nes/images/Contra-marquee.jpg_ and _~/ROMs/nes/videos/Contra-video.jpg_. This option is mostly intended for legacy purposes, if you have an existing game collection with this media setup that you would like to open in ES-DE. The scraper will never save files to this directory structure and will instead use the standard media directory logic. It's recommended to keep this option disabled unless you really need it since it slows down the application somewhat.
-
 **Disable desktop composition (requires restart)** _(Unix only)_
 
 The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphic cards and when running in 4K resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphic drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option).
@@ -1542,13 +1538,13 @@ Somewhat confusingly the terms _theme_ and _theme set_ are used to refer to the
 
 Note that this Desktop Edition fork adds additional features to the themes and more still will be added in future versions. This means that you may not get the full benefits of the application if you're using a different theme set. But effort is spent trying to make ES-DE backwards compatible with the available themes used by other EmulationStation versions. The exception to this are some themes made for the Recalbox and Batocera forks of EmulationStation as they have added a lot of additional theme functionality that ES-DE has no intention to replicate.
 
-Themes are most easily installed in your ES-DE home directory, i.e. `~/.emulationstation/themes`. By just adding the theme sets there, one folder each, they will be found by ES-DE during startup and you can then choose between them via UI Settings on the main menu.
+Themes are most easily installed to your ES-DE home directory, i.e. `~/.emulationstation/themes`. By just adding the theme sets there, one folder each, they will be found during startup and you can then choose between them via the UI Settings menu on the main menu.
 
 Note that although you can put additional themes in your ES-DE home directory, the default rbsimple-DE theme is located in your installation folder. For example this could be `/usr/share/emulationstation/themes` or `/usr/local/share/emulationstation/themes` on Unix, `/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes` on macOS or `C:\Program Files\EmulationStation-DE\themes` on Windows.
 
 If you would like to customize the rbsimple-DE theme, simply make a copy of the complete rbsimple-DE directory to ~/.emulationstation/themes and then that copy of the theme will take precedence over the one in the application installation directory.
 
-In this example, we've downloaded the [Carbon](https://github.com/RetroPie/es-theme-carbon) and [Fundamental](https://github.com/G-rila/es-theme-fundamental) themes and uncompressed them to the ES-DE home folder:
+In this example, we've downloaded the [Carbon](https://github.com/RetroPie/es-theme-carbon) and [Fundamental](https://github.com/G-rila/es-theme-fundamental) themes and uncompressed them to the ES-DE home directory:
 
 ```
 ~/.emulationstation/themes/es-theme-carbon