Documentation update.

CHANGELOG.md

@@ -163,6 +163,7 @@ v1.2 maintenance release.
 * Added a new pcwindows platform for scraping PC (Windows) games
 * Changed the platform to pcwindows for the epic system
 * Enabled screensaver controls when running in Kid UI mode
+* Added a --create-systemdirs command line option to generate the game system directories
 * Added an Xbox Kinect controller badge icon
 * (macOS) Categorized the application as a game so it shows up in the Launchpad games section
 * Replaced the explicit shell commands in es_systems.xml with %EMULATOR_OS-SHELL% find rules
@@ -170,6 +171,7 @@ v1.2 maintenance release.
 * (Windows) Set %RUNINBACKGROUND% when launching MAME standalone as this emulator may otherwise hang on exit
 * (Windows) Added an %ESCAPESPECIALS% variable that escapes the special characters &()^=;,
 * (Windows) Added %ESCAPESPECIALS% to the desktop, epic, kodi, ports and steam systems
+* Added experimental support for folder flattening
 * Updated the StringUtil::replace function as the old function was dangerous and could run into an endless loop
 
 ### Bug fixes

INSTALL-DEV.md

@@ -1059,6 +1059,7 @@ You can use **--help** or **-h** to view the list of command line options, as sh
 --force-kiosk                   Force the UI mode to Kiosk
 --force-kid                     Force the UI mode to Kid
 --force-input-config            Force configuration of input device
+--create-systemdirs             Create game system directories
 --home [path]                   Directory to use as home path
 --debug                         Print debug information
 --version, -v                   Display version information
@@ -1069,6 +1070,8 @@ As you can see above, you can override the home directory path using the `--home
 
 Setting the resolution to a lower or higher value than the display resolution will add a border to the application window.
 
+Running with the --create-systemdirs option will generate all the game system directories in the ROMs folder. This is equivalent to starting ES-DE with no game ROMs present and pressing the _Create directories_ button. Detailed output for the directory creation will be available in es_log.txt and the application will quit immediately after the directories have been created.
+
 For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter:
 ```
 --display

INSTALL.md

@@ -1355,6 +1355,7 @@ You can use **--help** or **-h** to view the list of command line options, as sh
 --force-kiosk                   Force the UI mode to Kiosk
 --force-kid                     Force the UI mode to Kid
 --force-input-config            Force configuration of input device
+--create-systemdirs             Create game system directories
 --home [path]                   Directory to use as home path
 --debug                         Print debug information
 --version, -v                   Display version information
@@ -1365,6 +1366,8 @@ As you can see above, you can override the home directory path using the `--home
 
 Setting the resolution to a lower or higher value than the display resolution will add a border to the application window.
 
+Running with the --create-systemdirs option will generate all the game system directories in the ROMs folder. This is equivalent to starting ES-DE with no game ROMs present and pressing the _Create directories_ button. Detailed output for the directory creation will be available in es_log.txt and the application will quit immediately after the directories have been created.
+
 For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter:
 ```
 --display

USERGUIDE-DEV.md

@@ -757,6 +757,47 @@ It's also possible to combine these types of special directories with normal dir
 
 Also in this case the directory will be displayed as a regular game file inside ES-DE and when launching the game the directory is passed as the game ROM argument to RPCS3.
 
+### Folder flattening
+
+**This functionality is unsupported and experimental and may cause all sorts of issues including corrupting your gamelist.xml files, so make sure to have backups of your data prior to attempting to use this.**
+
+ES-DE works according to the filesystem paradigm used on most operating systems, meaning the file and directory structure of your ROMs directory is reflected inside the application. So if you create a directory on the filesystem and place some games in there, it will be reflected inside ES-DE as a folder that you can enter and launch games from.
+
+A slight exception to this is the _Directories interpreted as files_ functionality where you can display a folder as a single entry. But even then, the basic directory structure is retained.
+
+However, some users have a setup where they have separated games inside their systems into folders but would still want to see these as a flat structure in ES-DE. While this is possible to accomplish, it's strongly discouraged as it will cause multiple issues:
+* It completely disables folder support for the system
+* Any identically named files will be added only once in a semi-random fashion, meaning you could miss a lot of games
+* If there is metadata available for multiple games with the same filename (which could happen if scraping was done prior to flattening the folders) then the behavior is undefined and metadata from the wrong game may get used
+* Some systems like MS-DOS and ScummVM may be completely broken
+* The setup may cause confusion when reorganizing your collection and similar as what you'll see inside ES-DE will not reflect what you see if navigating the ROM directory in your operating system's file manager
+
+Again, it's not recommended to flatten the folder structure, only enable this functionality if you know exactly what you're doing and understand the adverse side effects mentioned above. If you have any name collisions in your directory structure then make sure to rename each file to have a unique name. Also delete your gamelist.xml file and rescrape the entire system after fixing any collisions as it's otherwise random which metadata will be used for those games.
+
+If you still want to go ahead and enable folder flattening, then place an empty file named `flatten.txt` in the root of each system where you would like to have this applied.
+
+Here's an example setup:
+```
+~/ROMs/nes/EU/Kid Icarus.zip
+~/ROMs/nes/EU/Metal Gear (EU).zip
+~/ROMs/nes/USA/Kid Icarus.zip
+~/ROMs/nes/USA/Metal Gear (USA).zip
+~/ROMs/nes/Contra.zip
+~/ROMs/nes/Recca.zip
+~/ROMs/nes/flatten.txt
+```
+
+For this example the following entries will show up inside ES-DE:
+```
+Contra
+Kid Icarus
+Metal Gear (EU)
+Metal Gear (USA)
+Recca
+```
+
+Note that _Kid Icarus_ will only show up once since there is a name collision present and in this case only the first file processed will be added and any other identically named files will be ignored. Also note that in this case it's random whether metadata from _EU/Kid Icarus_ or _USA/Kid Icarus_ will be used.
+
 ### Special game installation considerations
 
 Not all systems are as simple as described above, or there may be multiple ways to do the configuration. Specifics for such systems will be covered here. Consider this a work in progress as there are many platforms supported by ES-DE.