mbsubmit: document new prompt choices

beetbox · Oct 28, 2023 · 7d51f25 · 7d51f25
1 parent 82cb430
commit 7d51f25
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 6 deletions.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -17,6 +17,7 @@ Major new features:
 
 New features:
 
+* :doc:`plugins/mbsubmit`: add new prompt choices helping further to submit unmatched tracks to MusicBrainz faster.
 * :doc:`plugins/discogs`: supply a value for the `cover_art_url` attribute, for use by `fetchart`.
   :bug:`429`
 * :ref:`update-cmd`: added ```-e``` flag for excluding fields from being updated.

diff --git a/docs/plugins/mbsubmit.rst b/docs/plugins/mbsubmit.rst
@@ -1,23 +1,36 @@
 MusicBrainz Submit Plugin
 =========================
 
-The ``mbsubmit`` plugin provides an extra prompt choice during an import
-session and a ``mbsubmit`` command that prints the tracks of the current
-album in a format that is parseable by MusicBrainz's `track parser`_.
+The ``mbsubmit`` plugin provides extra prompt choices when an import session
+fails to find a good enough match for a release. Additionally, it provides an
+``mbsubmit`` command that prints the tracks of the current album in a format
+that is parseable by MusicBrainz's `track parser`_. The prompt choices are:
+
+- Print the tracks to stdout in a format suitable for MusicBrainz's `track
+  parser`_.
+
+- Print the tracks into a ``beets-unmatched`` file in the same format as in the
+  above.
+
+- Open the program `Picard`_ with the unmatched folder as an input, allowing
+  you to start submitting the unmatched release to MusicBrainz with many input
+  fields already filled in.
 
 .. _track parser: https://wiki.musicbrainz.org/History:How_To_Parse_Track_Listings
+.. _Picard: https://picard.musicbrainz.org/
 
 Usage
 -----
 
 Enable the ``mbsubmit`` plugin in your configuration (see :ref:`using-plugins`)
-and select the ``Print tracks`` choice which is by default displayed when no
-strong recommendations are found for the album::
+and select one of the options mentioned above. Here the option ``Print tracks``
+choice is demonstrated::
 
     No matching release found for 3 tracks.
     For help, see: https://beets.readthedocs.org/en/latest/faq.html#nomatch
     [U]se as-is, as Tracks, Group albums, Skip, Enter search, enter Id, aBort,
-    Print tracks? p
+    Print tracks, print tracks into a "beets-unmatched" File,
+    Open Picard with the relevent files? p
     01. An Obscure Track - An Obscure Artist (3:37)
     02. Another Obscure Track - An Obscure Artist (2:05)
     03. The Third Track - Another Obscure Artist (3:02)