lastgenre: Docs for genre normalization (aliases)

Author: JOJ0

docs/plugins/lastgenre.rst

@@ -212,6 +212,55 @@ plain ``metal`` will not match ``heavy metal`` unless you write a regex like
       double-escape backslashes in unquoted or single-quoted strings (e.g., use
       ``\w``, not ``\\w``).
 
+Genre Normalization (Aliases)
+-----------------------------
+
+Last.fm tags often contain variant spellings, abbreviations, or inconsistent
+formatting (e.g., "hip-hop", "hiphop", and "hip hop"). The normalization feature
+uses an ordered list of regular expression aliases to map these variants to a
+single canonical name *before* any other filtering or canonicalization takes
+place.
+
+This feature is enabled by default (``aliases: yes``) and uses a bundled
+``aliases.yaml`` file which covers many common cases, such as mapping "dnb" to
+"drum and bass" or "r&b" to "rhythm and blues".
+
+You can extend or override these aliases in your configuration. The keys are the
+canonical genre names (which support ``\g<1>`` back-references to regex capture
+groups) and the values are lists of regex patterns:
+
+::
+
+    lastgenre:
+        aliases:
+            drum and bass:
+                - d(rum)?[ &n/]*b(ass)?
+            \g<1> hop:
+                - (glitch|hip|jazz|trip)y?[ /-]*hop
+
+.. note::
+
+    The same formatting and quoting rules regarding YAML special characters and
+    backslashes apply here as well. See the **Attention** box in the **Genre
+    Ignorelist** section above for details.
+
+Choosing the Right Tool
+-----------------------
+
+With multiple ways to filter and map genres, here is a quick guide on when to
+use what:
+
+- **Aliases**: Use these first to fix spelling variants and abbreviations (e.g.,
+  ``dnb`` → ``drum and bass``).
+- **Ignorelist**: Use this for error correction when Last.fm results are not
+  accurate, or for precise per-artist or global exclusions (e.g., rejecting
+  ``Metal`` for specific electronic artists).
+- **Whitelist**: Use this to strictly limit your library to a predefined set of
+  genres. When combined with canonicalization, the plugin will try to map a
+  sub-genre to its closest whitelisted parent. Anything else is dropped.
+- **Canonicalization**: Use this to automatically map specific sub-genres to
+  broader categories (e.g., ``Grindcore`` → ``Metal``).
+
 Configuration
 -------------