Doc updates and --hint option (#93)

README.md

@@ -69,8 +69,8 @@ Follow the steps below to install the latest version of Skyscraper. Lines beginn
 
 NOTE! If you are using the RetroPie distribution, you have the option to install Skyscraper directly from the RetroPie-Setup script (*you need to update the script before installing it!*). Read more about all of that [here](https://retropie.org.uk/docs/Scraper/#skyscraper). If not, read on.
 
-### Installation of Skyscraper Enhanced on RetroPie
-This goes in the usual RetroPie stanza: Either run `sudo RetroPie-Setup/retropie_setup.sh` and folow the menus (_Manage packages_ -> _Manage optional packages_ -> then look for _Skyscraper_) or run `sudo RetroPie-Setup/retropie_packages.sh skyscraper`. This will also automagically install programmable completion (aka. bash completion) for the Skyscraper command line.
+### Installation of Skyscraper on RetroPie and Programmable Completion
+This goes in the usual RetroPie stanza: Either run `sudo RetroPie-Setup/retropie_setup.sh` and folow the menus (_Manage packages_ -> _Manage optional packages_ -> then look for _Skyscraper_) or run `sudo RetroPie-Setup/retropie_packages.sh skyscraper`. This will also automagically install programmable completion (aka. bash completion) for the Skyscraper command line (see also [here](https://gemba.github.io/skyscraper/CLIHELP#programmable-completion)).
 
 ### Installation Prerequisites on Other Systems or Architectures
 #### Linux
@@ -197,14 +197,14 @@ To read more about any of the features described above, please check out all of
 ### Artwork look and effects
 Check the full artwork documentation [here](https://gemba.github.io/skyscraper/ARTWORK/)
 
-## Skyscraper Configurable Platforms Enhancement
-The main goal of this fork is to allow users to easily configurate and add platforms without having the needs to edit the code source directly.
+## Skyscraper Configurable Platforms
+You can easily configurate and add platforms without having the needs to edit the code source directly.
 
 This feature is achieved by adding new config files:
 - [peas.json](peas.json): Describes now the supported platforms by Skyscraper. See all details [here](https://gemba.github.io/skyscraper/PLATFORMS/).
 - [platforms_idmap.csv](platforms_idmap.csv): Maps the local platform name to the platform ID of screenscraper.fr, Mobygames or The Games DB web API.
 
-These files are copied in the folder `/home/pi/.skyscraper` on RetroPie (or `/usr/local/etc/skyscraper/` in general) at the first run of the program if you want to edit them after an installation.  
+These files are copied into the folder `/home/pi/.skyscraper` on RetroPie (or `/usr/local/etc/skyscraper/` in general) at the first run of the program if you want to edit them after an installation.
 
 ## Previous Release Notes
 Release notes for older releases which this fork builds on can be found [here](docs/OLDERRELEASES.md).

docs/CHANGELOG.md

@@ -7,6 +7,15 @@ humans](https://keepachangelog.com).
 
 - Added: Support for [XDG Base Directories](XDG.md), thanks for the suggestion
   @ASHGOLDOFFICIAL. 
+- Added: Option `--hint`, shows a random Tip of the Day
+- Updated: Skyscraper's hardcoded `/home/<USER>` replaced with the actual user's
+  home directory screen messages, thanks for highlighting it on the Mac,
+  @cdaters 
+- Updated: A downloaded `whdload.xml` file for platform Amiga will be not
+  downloaded again until the server indicates. Manually removing
+  `/home/<USER>/.skyscraper/whdload_cached_etag.txt` will force a new download.
+- Fixed: Performing Ctrl-C in `--cache edit` mode will now dismiss any changes
+  made instead of persisting them
 
 ### Version 3.13.0 (2024-11-06)
 

docs/CLIHELP.md

@@ -30,7 +30,8 @@ you will information about the other options here too.
 
 ### -a <FILENAME>
 
-Sets a non-default XML file to use when setting up the artwork compositing. By default Skyscraper uses the file `/home/<USER>/.skyscraper/artwork.xml`. Read more about the artwork.xml format and customization options [here](ARTWORK.md). Consider setting this in [`config.ini`](CONFIGINI.md#artworkxml) instead.
+Sets a non-default XML file to use when setting up the artwork compositing. By default Skyscraper uses the file `/home/<USER>/.skyscraper/artwork.xml`. If you provide a relative filepath it will be expanded relative to the current working directory. Consider setting this in [`config.ini`](CONFIGINI.md#artworkxml) instead.  
+Read more about the artwork.xml format and customization options [here](ARTWORK.md).
 
 **Example(s)**
 
@@ -40,21 +41,21 @@ Skyscraper -p snes -a "/path/to/artwork.xml"
 
 ### -c &lt;FILENAME&gt;
 
-Sets a non-default config file. By default Skyscraper uses the file `/home/<USER>/.skyscraper/config.ini`.
+Sets a non-default config file. By default Skyscraper uses the file `/home/<USER>/.skyscraper/config.ini`. A relative filepath will be prepended with the current working directory. If you provide a config file that does not exist, Skyscraper will print a warning and will continue by using built-in default values for the configuration.
 
 **Example(s)**
 
 ```
 Skyscraper -p snes -c "/path/to/config.ini"
 ```
 
-### -d &lt;FOLDER&gt;
+### -d &lt;PATH&gt;
 
-Sets a non-default location for the storing and loading of cached game resources. This is what is referred to in the docs as the _resource cache_. By default this folder is set to `/home/<USER>/.skyscraper/cache/<PLATFORM>`. Don't change this unless you have a good reason to (for instance if you want your cache to reside on a USB drive). The folder pointed to should be a folder with a Skyscraper `db.xml` file and its required subfolders inside of it (`covers`, `screenshots` etc.).
+Sets a non-default location for the storing and loading of cached game resources. This is what is referred to in the docs as the _resource cache_. By default this folder is set to `/home/<USER>/.skyscraper/cache/<PLATFORM>`. Don't change this unless you have a good reason to. The folder pointed to should be a folder with a Skyscraper `db.xml` file and its required subfolders inside of it (`covers`, `screenshots` etc.).
 
 !!! note
 
-    If you wish to always use a certain location as base folder for your resource cache (for instance a folder on a USB drive), it is _strongly_ recommended to set this in the `config.ini` file instead. Read more about the relevant `config.ini` option [here](CONFIGINI.md#cachefolder).
+    If you wish to _always_ use a certain location as base folder for your resource cache ((for instance if you want your cache to reside on a USB drive), it is _strongly_ recommended to set this in the `config.ini` file instead. Read more about the relevant `config.ini` option [here](CONFIGINI.md#cachefolder).
 
 **Example(s)**
 
@@ -114,6 +115,10 @@ Skyscraper --help
 Skyscraper -h
 ```
 
+### --hint
+
+Displays one of Skyscrapers's 'Did you know?' tips and exits.
+
 ### -i &lt;PATH&gt;
 
 Sets the rom input folder. By default Skyscraper will look for roms in the `/home/<user>/RetroPie/roms/<PLATFORM>` folder. If your roms are located in a non-default location, you can set the input path using this option. Consider setting this in [`config.ini`](CONFIGINI.md#inputfolder) instead.
@@ -257,9 +262,9 @@ Skyscraper -p snes --cache edit --includefrom "/home/pi/.skyscraper/reports/repo
 Skyscraper -p snes --cache edit:new=ages --includefrom "/home/pi/.skyscraper/reports/report-snes-missing_ages-20190708.txt"
 ```
 
-#### --cache merge:&lt;FOLDER&gt;
+#### --cache merge:&lt;PATH&gt;
 
-This option allows you to merge two resource caches together. It will merge the cache located at the `<FOLDER>` location into the default cache for the chosen platform. The path specified must be a path containing the `db.xml` file. You can also set a non-default destination to merge to with the `-d` option.
+This option allows you to merge two resource caches together. It will merge the cache located at the `<PATH>` location into the default cache for the chosen platform. The path specified must be a path containing the `db.xml` file. You can also set a non-default destination to merge to with the `-d` option.
 
 **Example(s)**
 

docs/CONFIGINI.md

@@ -555,7 +555,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 useful when scripting Skyscraper to avoid the need for user input.
+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.
 
 Default value: `false`  
 Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`, `[<SCRAPER>]`
@@ -564,7 +564,7 @@ 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 is useful when scripting Skyscraper to avoid the need for user input.
+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.
 
 Default value: `false`  
 Allowed in sections: `[main]`, `[<PLATFORM>]`, `[<FRONTEND>]`, `[<SCRAPER>]`
@@ -726,7 +726,8 @@ langPrios="it,en"
 
 #### artworkXml
 
-Sets a non-default xml file to use when setting up the artwork compositing. By default Skyscraper uses the file `/home/<USER>/.skyscraper/artwork.xml`. Read more about the artwork.xml format and customization options [here](ARTWORK.md).
+Sets a non-default xml file to use when setting up the artwork compositing. By default Skyscraper uses the file `/home/<USER>/.skyscraper/artwork.xml`. If you provide a relative filepath it will be expanded to `/home/<USER>/.skyscraper/<artworkXml>`, respective to `$XDG_CONFIG_HOME/skyscraper/<artworkXml>`, if you use Skyscraper in [XDG](XDG.md) mode.  
+Read more about the artwork.xml format and customization options [here](ARTWORK.md).
 
 !!! tip
 

docs/PLATFORMS.md

@@ -101,7 +101,7 @@ Outline:
 There is also a an verbatim example, you may skip the next section initially and
 can continue with the [hands-on example](PLATFORMS.md#sample-usecase-adding-platform-satellaview).
 
-### Updating `peas.json` and `platforms_idmap.csv`
+### Updating `peas.json` (or `peas_local.json`) and `platforms_idmap.csv`
 
 These two files are ment to be locally edited and extended for additional
 platforms. Whenever you add a new platform block to the `peas.json` do also

hints.xml

@@ -11,7 +11,7 @@
   <hint>You can turn off these hints using the '--flags nohints' command line flag.</hint>
   <hint>You can force Skyscraper to never apply any bracket notes (such as '(Europe)' or '[aga]') to the game names by using the '--flags nobrackets' command line flag.</hint>
   <hint>If you don't like the returned titles of your games, you can either import your own with the '-s import' module or force it to use the filenames with the '--flags forcefilename' command line flag.</hint>
-  <hint>You can scrape a single game by adding it to the command line either with partial or full path. You can also scrape a span of games with the '--startat' and '--endat' command line options.</hint>
+  <hint>You can scrape a single game by adding it to the command line either with relative or absolute path. You can also scrape a span of games with the '--startat' and '--endat' command line options.</hint>
   <hint>With the '--cache show' command line option, you can check the status of the resources that are cached for the platform you are scraping.</hint>
   <hint>You can use the '--help' command line option to view all available options. Most of these can also be set in the '/home/USER/.skyscraper/config.ini'. Check the '/home/USER/.skyscraper/config.ini.example' file for all available options.</hint>
   <hint>You can set custom input/rom, game list and media folders using the '-i', '-g' and '-o' command line options.</hint>
@@ -26,5 +26,10 @@
   <hint>You can create reports for all files missing certain resources in the cache using the '--cache report:missing=&lt;GROUP or RESOURCE1,RESOURCE2,...&gt; option. Great ways to add missing resources that the online sources are having trouble providing are the '--cache edit' option or the '-s import' module.</hint>
   <hint>Using the '--flags theinfront' flag you can force Skyscraper to always move 'The' to the front of the game titles, regardless of how it was returned from the scraping sources.</hint>
   <hint>When importing ratings ("-s import") you can use either 5-star like scale (0.5, 1, 1.5, ... , 5) or decimal numbers scale (0.0 to 1.0) for the rating value.</hint>
-  <hint>You can pinpoint a game with the Mobygames scraper with "-s mobygames --query &lt;gameid&gt;"", where the &lt;gameid&gt; is the ID listed on the mobygames site in a game's detail view.</hint>
+  <hint>You can pinpoint a game with the Mobygames scraper with "-s mobygames --query &lt;gameid&gt;", where the &lt;gameid&gt; is the ID listed on the mobygames site in a game's detail view.</hint>
+  <hint>Skyscraper on Linux supports bash-completion (programmable completion): Check the documentation how to enable it. Afterwards press TAB twice to display options or values for options.</hint>
+  <hint>You can scrape game manuals with Skyscraper and display them if your frontend supports this. Use manuals=true in config.ini.</hint>
+  <hint>You can make Skyscraper use the XDG Base Directories on Linux systems. See the XDG.md documentation.</hint>
+  <hint>Skyscraper supports ES-DE frontend format.</hint>
+  <hint>You can add new platforms (i.e., systems to scrape) by configuration file edits. See PLATFORMS.md.</hint>
 </hints>

src/cli.cpp

@@ -25,9 +25,14 @@
 #include "strtools.h"
 
 #include <QCommandLineOption>
+#include <QDomDocument>
 #include <QMapIterator>
 #include <QStringBuilder>
 
+#if QT_VERSION >= 0x050a00
+#include <QRandomGenerator>
+#endif
+
 void Cli::createParser(QCommandLineParser *parser, QString platforms) {
 
     QString h =
@@ -230,6 +235,8 @@ void Cli::createParser(QCommandLineParser *parser, QString platforms) {
         "CODE", "en");
     QCommandLineOption verbosityOption(
         "verbosity", "Print more info while scraping. Default: 0", "0-3", "0");
+    QCommandLineOption hintOption("hint",
+                                  "Show a random 'Tip of the Day' and quit.");
 
     parser->addOption(addextOption);
     parser->addOption(aOption);
@@ -244,6 +251,7 @@ void Cli::createParser(QCommandLineParser *parser, QString platforms) {
     parser->addOption(fOption);
     parser->addOption(gOption);
     parser->addHelpOption();
+    parser->addOption(hintOption);
     parser->addOption(includefromOption);
     parser->addOption(includepatternOption);
     parser->addOption(iOption);
@@ -475,3 +483,26 @@ QMap<QString, QString> Cli::getSubCommandOpts(const QString subCmd) {
 void Cli::cacheReportMissingUsage() {
     subCommandUsage("cache report:missing=");
 }
+
+void Cli::showHint() {
+    QFile hintsFile("hints.xml");
+    QDomDocument hintsXml;
+    if (!hintsFile.open(QIODevice::ReadOnly) ||
+        !hintsXml.setContent(&hintsFile)) {
+        return;
+    }
+    hintsFile.close();
+    QDomNodeList hintNodes = hintsXml.elementsByTagName("hint");
+    printf("\033[1;33mDID YOU KNOW:\033[0m %s\n\n",
+           hintsXml
+               .elementsByTagName("hint")
+#if QT_VERSION >= 0x050a00
+               .at(QRandomGenerator::global()->generate() % hintNodes.length())
+#else
+               .at(qrand() % hintNodes.length())
+#endif
+               .toElement()
+               .text()
+               .toStdString()
+               .c_str());
+}

src/cli.h

@@ -28,6 +28,7 @@ namespace Cli {
     void subCommandUsage(const QString subCmd);
     QMap<QString, QString> getSubCommandOpts(const QString subCmd);
     void cacheReportMissingUsage();
+    void showHint();
 } // namespace Cli
 
 #endif // CLI_H

src/settings.cpp

@@ -55,8 +55,8 @@ void RuntimeCfg::applyConfigIni(CfgType type, QSettings *settings,
     if (config->platform.isEmpty()) {
         QStringList plafs = Platform::get().getPlatforms();
         if (parser->isSet("p") &&
-            // '_' is seen as a subcategory of the selected platform
             plafs.contains(parser->value("p").split('_').first())) {
+            /* '_' is seen as a subcategory of the selected platform */
             config->platform = parser->value("p");
         } else if (type == CfgType::MAIN && settings->contains("platform") &&
                    plafs.contains(settings->value("platform").toString())) {
@@ -67,7 +67,8 @@ void RuntimeCfg::applyConfigIni(CfgType type, QSettings *settings,
                              (parser->value("cache") == "help" ||
                               parser->value("cache") == "report:missing=help");
             QStringList flags = parseFlags();
-            if (!cacheHelp && !flags.contains("help")) {
+            if (!cacheHelp && !flags.contains("help") &&
+                !parser->isSet("hint")) {
                 if (parser->isSet("p")) {
                     printf("\033[1;31mUnknown platform '%s' provided. \033[0m",
                            parser->value("p").toUtf8().constData());
@@ -589,6 +590,10 @@ void RuntimeCfg::applyCli(bool &inputFolderSet, bool &gameListFolderSet,
     if (parser->isSet("refresh")) {
         config->refresh = true;
     }
+    if (parser->isSet("hint")) {
+        Cli::showHint();
+        exit(0);
+    }
     if (parser->isSet("cache")) {
         config->cacheOptions = parser->value("cache");
         if (config->cacheOptions == "refresh") {