From 4e8948d7ca138c2f3b3f1c70475e05db4be0ee09 Mon Sep 17 00:00:00 2001
From: J0J0 Todos <jojo@peek-a-boo.at>
Date: Tue, 21 Jan 2025 11:36:41 +0100
Subject: [PATCH] Rework new & refine existing lastgenre docs chapters

and describe according to new defaults: force and keep_existing
DISABLED, ensuring failsafe operation out of the box.
---
 docs/plugins/lastgenre.rst | 68 +++++++++++++++++++++++++++-----------
 1 file changed, 48 insertions(+), 20 deletions(-)

diff --git a/docs/plugins/lastgenre.rst b/docs/plugins/lastgenre.rst
index c54d7b161..54e4de761 100644
--- a/docs/plugins/lastgenre.rst
+++ b/docs/plugins/lastgenre.rst
@@ -25,7 +25,7 @@ tags can be considered genres. This way, tags like "my favorite music" or "seen
 live" won't be considered genres. The plugin ships with a fairly extensive
 `internal whitelist`_, but you can set your own in the config file using the
 ``whitelist`` configuration value or forgo a whitelist altogether by setting
-the option to `false`.
+the option to ``no``.
 
 The genre list file should contain one genre per line. Blank lines are ignored.
 For the curious, the default genre list is generated by a `script that scrapes
@@ -117,21 +117,47 @@ Handling pre-populated tags
 The ``force``, ``keep_existing`` and ``whitelist`` options control how
 pre-existing genres are handled.
 
-By default, the plugin *combines* newly fetched last.fm genres with whitelisted
-pre-existing ones (``force: yes`` and ``keep_existing: yes``).
+As you would assume, setting ``force: no`` **won't touch pre-existing genre
+tags** and will only **fetch new genres for empty tags**. When ``force`` is
+``yes`` the setting of the ``whitelist`` option (as documented in `Usage`_)
+applies to any existing or newly fetched genres.
 
-To write new genres to empty tags only and keep pre-populated tags untouched,
-set ``force: no``.
+The follwing configurations are possible:
 
-To *overwrite* any content of pre-populated tags, set ``force: yes`` and
-``keep_existing: no``.
+**Setup 1** (default)
 
-To *combine* newly fetched last.fm genres with any pre-existing ones, set
-``force: yes``, ``keep_existing: yes`` and ``whitelist: False``.
+Add new last.fm genres when **empty**. Any present tags stay **untouched**.
 
-Combining ``force: no`` and ``keep_existing: yes`` is invalid (since ``force:
+.. code-block:: yaml
+
+    force: no
+    keep_existing: no
+
+**Setup 2**
+
+**Overwrite all**. Only fresh last.fm genres remain.
+
+.. code-block:: yaml
+
+    force: yes
+    keep_existing: no
+
+**Setup 3**
+
+**Combine** genres in present tags with new ones (be aware of that with an
+enabled ``whitelist`` setting, of course some genres might get cleaned up. To
+make sure any exisitng genres remain, set ``whitelist: no``).
+
+.. code-block:: yaml
+
+    force: yes
+    keep_existing: yes
+
+If ``force`` is disabled the ``keep_existing`` option is simply ignored (since ``force:
 no`` means `not touching` existing tags anyway).
 
+
+
 Configuration
 -------------
 
@@ -149,20 +175,22 @@ configuration file. The available options are:
 - **fallback**: A string if to use a fallback genre when no genre is found.
   You can use the empty string ``''`` to reset the genre.
   Default: None.
-- **force**: By default, lastgenre will fetch new genres for empty as well as
-  pre-populated tags. Enable the ``keep_existing`` option to combine existing
-  and new genres. (see `Handling pre-populated tags`_).
+- **force**: By default, lastgenre will fetch new genres for empty tags only.
+  Enable the ``keep_existing`` option to combine existing and new genres. (see
+  `Handling pre-populated tags`_).
+  Default: ``no``.
+- **keep_existing**: This option alters the ``force`` behaviour.
+  If both ``force`` and ``keep_existing`` are enabled, existing genres are
+  combined with new ones. Depending on the ``whitelist`` setting, existing and
+  new genres are filtered accordingly. To ensure only fresh last.fm genres,
+  disable this option. (see `Handling pre-populated tags`_)
   Default: ``no``.
-- **keep_existing**: By default, genres remain in pre-populated tags. Depending
-  on whether or not ``whitelist`` is enabled, existing genres get "a cleanup".
-  Enabling ``keep_existing`` is only valid in combination with an active
-  ``force`` option. To ensure only fresh last.fm genres, disable this option.
-  (see `Handling pre-populated tags`_)
-  Default: ``yes``.
 - **min_weight**: Minimum popularity factor below which genres are discarded.
   Default: 10.
 - **prefer_specific**: Sort genres by the most to least specific, rather than
-  most to least popular. Default: ``no``.
+  most to least popular. Note that this option requires a ``canonical`` tree,
+  and if not configured it will automatically enable and use the built-in tree.
+  Default: ``no``.
 - **source**: Which entity to look up in Last.fm. Can be
   either ``artist``, ``album`` or ``track``.
   Default: ``album``.