Merge pull request #894 from estefan3112/master

Major re-write of MAME/MESS Software List page

.gitignore

@@ -1,3 +1,6 @@
 /site
 .DS_Store
 **/.DS_Store
+.DS_Store
+docs/.DS_Store
+.DS_Store

docs/guides/retroarch-cloud-sync.md

@@ -0,0 +1,67 @@
+# What is it?
+
+RetroArch Cloud Sync enables a seamless synchronization of the most important system configuration and save data to a dedicated private webdav server, from where these data can be synchronized across Apple devices. The current functionality is limited to Apple devices (MacOS, iOS, tvOS) because it was developed here. It can be deployed to other RetroArch operating systems, if a developer is interested in this work.
+
+RetroArch Cloud Sync currently syncs all data from the following directories:
+
+/"YourUser"/Documents/RetroArch/saves - original system saves
+/"YourUser"/Documents/RetroArch/states - RetroArch save states
+/"YourUser"/Library/Application Support/RetroArch/config - the global retroarch.cfg and all core-specific configurations, core options and shader configurations
+
+"YourUser" refers to your $HOME user in MacOS
+
+## How to configure it
+
+As with any sync solution, it is recommended to start with one device and ensure a proper functioning. Only then a second device should be added.
+
+### Initial configuration with first device
+
+In order to start with Cloud sync, you need an own webdav account that is accessible by MacOS via Connect to Server -> https://webdav.xxxxxx.xxx/.
+
+!!! Tip
+    It is obviously the best way to start with your leading RetroArch system, as this will bring the most important data into the webdav account first. In this account, create an own folder called RetroArch.
+
+Within RetroArch, go to Settings/Saving/Cloud Sync
+    Enable Cloud Sync -> ON
+    Destructive Cloud Sync -> OFF (keeps a backup in a dedicated subfolder called "deleted", and the file names get a time stamp of deletion)
+    Cloud Sync Backend -> webdav
+    Cloud Storage URL -> https://webdav.xxxxxx.xxx/RetroArch/ (here is the RetroArch subfolder that you created before)
+    Username -> your webdav user
+    Password -> your webdav password
+
+Save this configuration and restart Retroarch. After this restart, the initial sync should start immediately (see progress indicator in the bottom left status line of RetroArch). Depending on your amount of sync data, this can take some time. When this is finished, you could do some testing. For example, launch a game and set a new hiscore, then close the game. Let the sync do its job, then look into the webdav accound, and the new hiscore should be there.
+
+### Configuration of a second device
+
+With the second device, so the identical steps in RetroArch as with the first device. From now on, the two devices should be in sync!
+
+!!! Important Note
+    Be very careful that these directory save settings are also identical on all sync devices:
+    - Sort Saves into Folders by Core Name - ON/OFF
+    - Sort Save States into Folders by Core Name - ON/OFF
+    - Sort Saves into Folders by Content Directory - ON/OFF
+    - Sort Save States into Folders by Content Directory - ON/OFF
+    If these settings are not matching, the sync is likely to fail, as the devices store its data in different directories.
+
+## Further details of the solution
+
+### Sync Status
+
+Syncing is displayed in the bottom left status line of RetroArch.
+
+As soon as the solution is properly configured, Cloud Sync starts immediately at launching RetroArch. This is apparently important if other devices synced new data to the webdav repository. They are then immediately picked up.
+
+Another sync is triggered with every closing of a game.
+
+### .DS_Store files create conflicts
+
+RetroArch Cloud Sync may run in sync problems if .DS_Store files are synced into the cloud repository. It is therefore recommended to delete all .DS_Store files from the synced directories.
+
+For example, you can delete the .DS.Store files from the relevant RetroArch directories from the terminal as follows (easiest way is that you create an .sh file containing these lines and make it executable via chmod 755):
+
+cd /"YourUser"/Documents/RetroArch 
+find . -name '.DS_Store' -type f -delete
+cd /"YourUser"/Library/Application\ Support/RetroArch
+find . -name '.DS_Store' -type f -delete
+
+After deletion, the sync also deletes these .DS_Store files from the cloud repository.

docs/guides/softwarelist-getting-started.md

@@ -1,40 +1,23 @@
-# Getting started with software emulation in Libretro MAME cores
+# Getting started with Non-Acrcade/Software Emulation in Libretro MAME/MESS cores
 
-Multi software emulation requires a different planning approach than arcade emulation. Terminology can also differ from the terms used in other kinds of emulation.
-The terms software and software list are used to define non-arcade machines emulated by MAME.
+In this chapter, the terms 'software' and 'software lists' are used to define non-arcade machines that are emulated by MAME/MESS. This kind of emulation requires a different planning approach than arcade machine emulation - it is more complicated to set up.
 
-### Process
-  1. **Understand the core variants**
-  2. **Use the correct version romsets for that emulator**
-
-The libretro core ecosystem currently includes many multi software emulators, that support software emulation. Arcade (MAME), Arcade (MAME 2016) will be the main focus of this guide but the MULTI (MESS 2015) and MULTI (UME 2015) cores have this ability. Each requiring its own distinct version of "romsets" which the emulator supports.
-
-!!! tip
-    Matching emulator and game versions is advised for maximum compatibility but you may find mis-matched combinations also work.
-
----
-
-## Step 1: Understand the core variants
-
-There are three families of multi-system software emulators available as libretro cores: MAME, MESS and UME. These emulators are in turn available in multiple versions to allow users to best match a core to their preference.
+## Understand the core variants
 
+The libretro core ecosystem currently includes many multi software emulators that support software emulation. Three families exist: MAME, MESS and UME. These emulators are in turn available in multiple versions to allow users to best match a core to their preference.
 
 #### MAME
-Arcade (MAME) & Arcade (MAME 2016) are currently the only MAME cores that support the emulation of software & arcade system. The Arcade (MAME) core is updated regularly and most inline with the official MAME project release. Arcade (MAME 2016) is an archived snapshot of MAME from the 0.174 release.
+Arcade (MAME) & Arcade (MAME 2016) are currently the only MAME cores that support the emulation of both software & arcade systems. The Arcade (MAME) core is updated regularly and most inline with the official MAME project release. Arcade (MAME 2016) is an archived snapshot of MAME from the 0.174 release.
 
 #### MESS
-Multi (MESS 2015) is a snapshot of the MESS project from v0.160. The MESS project later merged with the MAME project in MAME v0.162
+Multi (MESS 2015) is a snapshot of the MESS project from v0.160. The MESS project later merged with the MAME project in MAME v0.162, i.e. in May 2015.
 
 #### UME
-Multi (UME 2015) is a snapshot of the Universal Machine Emulator. This was a precursor to the MAME/MESS merger, released by David Haywood (haze). The MAME and MESS project codebases co-existed in the MESS SVN development tree before they officially merged. This allowed haze to build and release the emulator with unmodified code from both projects under the name UME
-
----
-
-## Step 2: Use the correct version romsets for that emulator
-**For best results, start with a full software list ROM collection with a version that matches the emulator you're using.**
-
-In general, you will only get good results with a full collection of software list romsets for your chosen emulator.Individual romset zip files may not include BIOS ROMs, "Parent" romsets, necessary audio sample files, etc.
+Multi (UME 2015) is a snapshot of the Universal Machine Emulator. This was a precursor to the MAME/MESS merger, released by David Haywood (haze). The MAME and MESS project codebases co-existed in the MESS SVN development tree before they officially merged. This allowed haze to build and release the emulator with unmodified code from both projects under the name UME.
 
+## Use the correct version of romset for the desired emulator
+
+Arcade (MAME), Arcade (MAME 2016) will be the main focus of this guide but also the MULTI (MESS 2015) and MULTI (UME 2015) cores have this ability. As in MAME arcade emulation, each core requires its own distinct version of software list "romsets", which the emulator supports.
 
 | Emulator | Required ROM Version |
 | :---: | :---: |
@@ -43,78 +26,76 @@ In general, you will only get good results with a full collection of software li
 | MESS 2015 | - |
 | UME 2015 | - |
 
+!!! tip
+    For best results, start with a full software list ROM collection with a version that matches the emulator you are using. Individual romset zip files may not include BIOS ROMs, "Parent" romsets, necessary audio sample files, etc.
+    Matching emulator and game versions is advised for maximum compatibility, but you may find mis-matched combinations also work.
+
 ---
 
 ## Running software list machines
-There are two common methods of configuring Retroarch to launch software list machines and games with MAME cores.
-
-  1. **MAME Frontend direct**
-  2. **Libretro CMD file**
-
-**Method 1** uses the inbuilt MAME logic and hash files to launch your games.
-**Method 2** uses an extra Libretro feature to pass command line functions to the core. This replicates sending command line functions directly to MAME like you would on a PC.
-
-### MAME Frontend direct
+There are two ways of configuring Retroarch to launch software list machines and games with MAME cores.
 
+  1. **Method 1 - MAME Frontend direct launch:** uses the inbuilt MAME logic and hash files to launch your games
+  2. **Method - RetroArch fontend friendly via Libretro CMD file launch:** uses an extra libretro feature to pass command line functions to the core 
 
-NOTES:-
-Method 1:- Authentic MAME
-Using the internal Software List functions of MAME.
+### Method 1: MAME Frontend direct launch
 
-For this you will need some supporting files from the mainline MAME emulator. Download the windows MAME emulator here(link). Making sure to get the correct version you require.
+For using the internal software list functions of MAME, you will need the right supporting files from the mainline MAME standalone emulator, i.e. the **hash files**. E.g. for the MAME (current) core, download the newest version of the Windows MAME emulator [here](https://www.mamedev.org/release.html). For earlier versions, make sure to get the correct version you require: The version of the hash files must match with the Libretro Core version.
 
-Extract the contents and remove the “hash” folder and it’s contents. If your device has limited storage just take the files relating to the system you want to emulate.
-
-Folder structure:-
-Folder structure/naming is very important for this use of the MAME Cores. The naming will depend on the machine you are trying to emulate but the folder structure will be the same. The example below is for the Atari 5200.
-
-“YourPath” is the location of your Retroarch and games folders.
+!!! tip
+    In RetroArch, launch the desired core standalone, and on the bottom left, you find the correct MAME version that you want to download.
 
-Create the following folders in your Retroarch installation or your specified “system” folder
+Extract the contents and take the “hash” folder. Move this folder into the RetroArch folder structure. If your device has limited storage, just copy the hash files relating to the system you want to emulate.
 
-YourPath/Retroarch/System/mame
+**RetroArch MAME system folder structure:**
+Folder structure/naming is very important here. The naming will depend on the machine you are trying to emulate but the folder structure will be the same. The example below is for the Atari 7800 system in MAME current.
 
-Copy the hash folder acquired earlier to the above location.
+“YourPath” is the location of your Retroarch system folders. It varies depending on your operating system.
+!!! tip
+    In RetroArch, head for Settings/Directory - the System/BIOS entry identifies the correct "system" folder.
 
-YourPath/Retroarch/system/mame/hash
+If not already existent, create the following folder in your RetroArch “system” folder:
+"YourPath"/Retroarch/System/mame
 
-So for Atari 5200 you would have
+Copy the hash folder acquired earlier into the RetroArch system folder:
+"YourPath"/Retroarch/system/mame/hash
 
-YourPath/Retroarch/system/mame/hash/a5200.xml
+So for Atari 7800 you would have the following hash file:
+YourPath/Retroarch/system/mame/hash/a7800.xml
 
-(Check about .hsi file or use another example)
+(To do: check about .hsi file or use another example)
 
-Create the following folders in your games directory (these will be mame naming dependent)
+**RetroArch MAME games folder structure:**
+Create the following folders in your games directory of your choice (these will be mame naming dependent)
+"YourPath"/Games/Atari 7800/a7800
+(The last folder MUST be named as MAME requires, in this case “a7800”)
 
-YourPath/Games/Atari 5200/a5200
+Place any .zip games and .zip bios files required here:
+"YourPath"/Games/Atari 7800/a7800.zip
+"YourPath"/Games/Atari 7800/a7800/asteroid.zip
 
-(The last folder MUST be named as MAME requires, in this case “a5200”)
+!!! note
+    To place the bios file above a7800 is the way that official MAME stores the data and thus also recommended here. You could also put the bios into the a7800 folder, but that's not how official MAME does it. 
 
-Place any .zip games and .zip bios files required here
+You may also put or even extract the bios file to their own folder within the games directory
+"YourPath"/Games/Atari 7800/a7800/a7800/7800.rom
 
-YourPath/Games/Atari 5200/a5200/a5200.zip
-YourPath/Games/Atari 5200/a5200/boogie.zip
+Now launch the game: In RetroArch, choose "Load Content" and browse to asteroid.zip and launch with MAME current.
 
-(You May also extract the bios file to their own folder within the games directory)
-YourPath/Games/Atari 5200/a5200/a5200/5200.rom)
+(To Do: Add note about SoftList xml specifying the game names and crc and only supporting only those specific file names.)
 
-Now Load Content and browse to the game files and launch with a compatible core.
-————————————————
-Need to do a fresh install and confirm minimum files needed
+### Method 2: RetroArch frontend friendly via Libretro CMD file launching  
 
-Add note about SoftList xml specifying the game names and crc and only supporting only those specific file names.
-————————————————
+This method follows the same folder structure as above, but you can use custom naming outside of the hash file included with MAME. It utilises some custom additions to the Libretro MAME Cores. Specifically the use of text files (.cmd) to replicate sending command line actions as you can with mainline MAME.
 
-Method2: Frontend Friendly
+**Creating a .cmd file**
+Let's follow the above example and create a dedicated asteroid.cmd file for the Atari 7800 game. It needs this line:
 
-CMD or command line file launching.
+a7800 -cart asteroid -rp "/"YourPath"/mame/roms/a7800"
 
-This method follows the same folder structure as above but you can use custom naming outside of the hash file included with MAME.
-It utilises some custom additions to the Libretro MAME Cores. Specifically the use of text files (.cmd) to replicate sending command line actions as you can with mainline MAME.
+To do: Other path definitions, e.g. under Windows?
 
-To do
-Deciding on contents of the cmd file
+Now launch the game: In RetroArch, choose "Load Content" and browse to asteroid.cmd, and it should launch with MAME current.
 
-Cmd file example
+To do: Cmd file example
 
-Test on clean install

mkdocs.yml

@@ -71,6 +71,7 @@ nav:
       - 'Video Recording and Streaming': 'guides/recording-and-streaming.md'
       - 'Troubleshooting': 'guides/troubleshooting-retroarch.md'
       - 'Generating Logs': 'guides/generating-retroarch-logs.md'
+      - 'RetroArch Cloud Sync (Apple Devices)': 'guides/retroarch-cloud-sync.md'
     - 'Appearance & Customization':
       - 'Creating a Theme': 'guides/themes.md'
       - 'Playlists and Thumbnails': 'guides/roms-playlists-thumbnails.md'