Fix path handling for ES frontend and other edge case fixes

VERSION.ini

@@ -1 +1 @@
-VERSION="3.17.3"
+VERSION="3.17.4"

docs/CLIHELP.md

@@ -572,11 +572,17 @@ Game titles are returned from the scraping sources sometimes as 'The Game' and o
 
 #### unattend
 
-When generating a game list Skyscraper will check if it already exists and ask if you want to overwrite it. And it will also ask if you wish to skip existing game list entries. By using this flag Skyscraper will _always_ overwrite an existing game list and _never_ skip existing entries. This is useful when scripting Skyscraper to avoid the need for user input. Consider setting this in [`config.ini`](CONFIGINI.md#unattend) instead.
+Before a game list creation Skyscraper will check if it already exists and ask if you want to overwrite it, when neither `unattend` nor `unattendskip` are set. By setting this flag or `unattendskip` Skyscraper will overwrite an existing game list without confirmation question. This is useful when scripting Skyscraper to avoid the need for user input. Additionally, if this flag or `unattendskip` is set on the cache operations `purge:all` and `vacuum` you will _not_ get a confirmation question. Consider setting this in [`config.ini`](CONFIGINI.md#unattend) instead.
 
 #### unattendskip
 
-When generating a game list Skyscraper will check if it already exists and ask if you want to overwrite it. And it will also ask if you wish to skip existing game list entries. By using this flag Skyscraper will _always_ overwrite an existing game list and _always_ skip existing entries. This is useful when scripting Skyscraper to avoid the need for user input. Consider setting this in [`config.ini`](CONFIGINI.md#unattendskip) instead.
+Before a game list creation Skyscraper will ask if you want to skip existing game entries (i.e. not recreate from cache) in an existing game list, when neither `unattend` nor `unattendskip` are set. By setting this flag and not having set `unattend` Skyscraper will skip existing entries. This is useful when scripting Skyscraper to avoid the need for user input. This flag has no effect (i.e. an existing game list entry will be always recreated) when either
+
+- `unattend` is set or
+- you use the `--query` parameter or
+- the frontend generator does not support preserving a complete gameentry.
+
+If this flag or `unattend` is set on the cache operations `purge:all` and `vacuum` you will _not_ get a confirmation question. Consider setting this in [`config.ini`](CONFIGINI.md#unattendskip) instead.
 
 #### unpack
 

docs/CONFIGINI.md

@@ -627,7 +627,7 @@ Allowed in sections: `[main]`, `[<PLATFORM>]`
 
 #### unattend
 
-When generating a game list Skyscraper will check if it already exists and ask if you want to overwrite it. And it will also ask if you wish to skip existing game list entries. By enabling this option Skyscraper will _always_ overwrite an existing game list and _never_ skip existing entries, in other words: the game list will be newly created. This is flag useful for example when scripting Skyscraper to avoid the need for user input.
+Before a game list creation Skyscraper will check if it already exists and ask if you want to overwrite it, when neither the `unattend` nor the `unattendskip` option is set true. By setting this option or `unattendskip` to true Skyscraper will overwrite an existing game list without confirmation question. This is useful when scripting Skyscraper to avoid the need for user input. Additionally, if this option or `unattendskip` is set to true, the cache operations `purge:all` and `vacuum` will _not_ prompt you with a confirmation question.
 
 Default value: `false`  
 Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`, `[<SCRAPER>]`
@@ -636,7 +636,13 @@ Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`, `[<SCRAPER>]`
 
 #### unattendSkip
 
-When generating a game list Skyscraper will check if it already exists and ask if you want to overwrite it. And it will also ask if you wish to skip existing game list entries. By enabling this option Skyscraper will _always_ overwrite an existing game list and _always_ skip existing entries, in other words: game list entries are added if not present in the gamelist, existing entries are left untouched. This flag is useful for example when scripting Skyscraper to avoid the need for user input.
+Before a game list creation Skyscraper will ask if you want to skip existing game entries (i.e. not recreate from cache) in an existing game list, when the `unattend` and the `unattendskip` option are set false. By setting this option to true and having `unattend` set to false, Skyscraper will skip existing entries without prompting you. This is useful when scripting Skyscraper to avoid the need for user input. This option has no effect (i.e. an existing game list entry will be always recreated) when either
+
+- `unattend` is set to true or
+- you use the `--query` parameter or
+- the frontend generator does not support preserving a complete gameentry.
+
+If this option or the `unattend` option is true, the cache operations `purge:all` and `vacuum` will _not_ prompt you with a confirmation question.
 
 Default value: `false`  
 Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`, `[<SCRAPER>]`

docs/PATHHANDLING.md

@@ -3,7 +3,7 @@
 This page describes how Skyscraper processes the different paths and especially
 how the absolute path is calculated when a you provide a relative path.
 
-Do not get confused by the lenghty flow diagram below. It covers gamelist folder,
+Do not get confused by the lenghty flow diagram below. It covers game list folder,
 input folder and media folder handling. You wiil notice that input folder and
 media folder are processed in the same manner.
 
@@ -23,87 +23,88 @@ symbolic links are not resolved.
 Remember the precedence of [CLI and configuration
 options](CONFIGINI.md#configini-options) when you read through this document.
 
-!!! tip "In a Nutshell"
-
-    Key takeaway is that a relative input folder and relative media folder are
-    always calculated to an absolute folder in relation to the absolute gamelist
-    folder. When you apply [`relativePaths="true"`](CONFIGINI.md#relativepaths),
-    they will be generated with the relative path in respect to the gamelist-
-    or metadata-output (in Pegasus terms) path.
-
 Now, let's see how Skyscraper handles relative path configuration options.
 
 ### Computing the Absolute Path from ...
 
 a relative path provided. The next subsections are summarizing the absolute path
 calculation of the different path and file options.
 
-#### Current Working Directory
+#### ... Current Working Directory
 
 The current working directory (CWD) is the directory from where you run
-Skyscraper. The absolute path is computed as `<CWD>/<option-value>` for these
-CLI options and their values:
+Skyscraper. The absolute path is computed as `<CWD>/<parameter-value>` for these
+CLI parameters and their values:
 
 `-a <artwork.xml>`  
 `-c <configfile>`  
 `-g <gamelistfolder>`  
 `-d <cachefolder>`
 
-This means the first part of the flow diagram (Gamelist folder) also applies to
-`-a` and `-d` options and their configfile counterparts.
+This means the first part of the flow diagram (resolution of Gamelist folder)
+also applies to `-a` and `-d` options and their configfile counterparts.
 
-In contrast, when you provide these three (`<artwork.xml>`,`<gamelistfolder>`
-and `<cachefolder>`) in a configuration INI-file the absolute path it determined
-from the absolute path of the config file. See
-[below](#an-option-in-a-configuration-ini-file).
+In contrast, when you use one of the three parameters
+(`<artwork.xml>`,`<gamelistfolder>` and `<cachefolder>`) in a configuration
+INI-file the absolute path it determined from the absolute path of the config
+file. See [below](#an-option-in-a-configuration-ini-file).
 
-#### Skyscraper Built-in Config Directory
+#### ... Skyscraper Built-in Config Directory
 
-This is usually `/home/<USER>/.skyscraper/` (base). With [XDG](XDG.md) it is
+This is usually `/home/<USER>/.skyscraper/` (=_base_). With [XDG](XDG.md) it is
 slightly different. The files provided with these options
 
 `--excludeFrom <excludes.txt>`  
 `--includeFrom <includes.txt>`
 
-are searched in that directory by concatenating the base and for example the
-exclude file. If not found, Skyscraper tries to access them with the current
-working directory as base.
+are searched by concatenating the _base_ and for example the exclude file. If
+not found, Skyscraper tries to access it with the current working directory as
+_base_. If it is not found in any of these locations Skyscraper end with an
+error message.
 
-#### the Gamelist Folder
+#### ... the Gamelist Folder
 
 If you define a Gamelist folder either via `-g` or via `gameListFolder=`
-(INI-file) this is the base for the relative paths of
+(INI-file) and are using a frontend for EmulationStation (or any other frontend,
+which is not Pegasus) then the input folder must provided absolute and can not
+be relative. The media folder, if relative, is then assumed to be relative to
+the input folder.
 
-`-i <folder>` or `inputFolder=<folder>`  
-`-o <folder>` or `mediaFolder=<folder>`
+However, if you selected the Pegasus frontend then the input folder may be
+relative. The input folder and media folder, when relative, are then interpreted
+by Skyscraper to be relative to the game list folder.
 
 This is also depicted in the diagram above.
 
-#### Input Folder (ROM-/gamefile-path)
+#### ... Input Folder (ROM-/gamefile-path)
 
 The files provided with these options
 
-`--startAt <game-file-A>`  
-`--endAr <game-file-B>`
+`--startAt <ROM-or-game-file-A>`  
+`--endAt <ROM-or-game-file-B>`
 
-are first searched in the current working directory. If not found,
-Skyscraper tries to access them in the input folder.
+are first searched in the current working directory. If not found, Skyscraper
+tries to access them in the input folder. If they are not found at all
+Skyscraper silently assumes that `--startAt` respective `--endAt` are not set.
 
-#### an Option in a Configuration INI File
+#### ... an Option in a Configuration INI File
 
-When you have set one of the following parameters in the default configuration
-file (`/home/<USER>/.skyscraper/config.ini`) or in a custom config file defined
-with `-c <configfile>` the path is calculated from the absolute path of
-the location of the config INI-file.
+When you have set one of the four following parameters in the default
+configuration file (`/home/<USER>/.skyscraper/config.ini`) or in a custom config
+file defined with `-c <configfile>` the path is calculated from the absolute
+path of the location of the config INI-file.
 
-`artworkXml=<artwork.xml>`  
-`gameListFolder=<gamelistfolder>`  
-`cacheFolder<cachefolder>`
-`importFolder<importfolder>`
+```ini
+artworkXml=<artwork.xml>
+gameListFolder=<gamelistfolder>
+cacheFolder=cachefolder>
+importFolder=<importfolder>
+```
 
-!!! note
+Remember, that the path calculation for the paramters `artworkXml`,
+`gameListFolder` and `cacheFolder` differs when using their CLI
+counterparts, see [CLI options](#current-working-directory) above.
 
-    The `importFolder=` parameter has no counterpart on the command line.
+!!! note
 
-Remember, that this path calculation is different than the logic when using [CLI
-options](#current-working-directory).
+    The `importFolder=` parameter has no counterpart on the command line.