From 85ad17d43103e912e65cacd15e27e48adbfff3bc Mon Sep 17 00:00:00 2001
From: Diego Moreda <diego.plan9@gmail.com>
Date: Wed, 30 Dec 2015 20:29:58 +0100
Subject: [PATCH] mbsubmit: add documentation, changelog

---
 docs/changelog.rst        |  3 +++
 docs/plugins/index.rst    |  2 ++
 docs/plugins/mbsubmit.rst | 54 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 docs/plugins/mbsubmit.rst

diff --git a/docs/changelog.rst b/docs/changelog.rst
index dbcd7e399..b69288170 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -9,6 +9,9 @@ New:
 * :doc:`/plugins/fetchart`: The Google Images backend has been restored. It
   now requires an API key from Google. Thanks to :user:`lcharlick`.
   :bug:`1778`
+* A new :doc:`/plugins/mbsubmit` lets you print the tracks of an album in a
+  format parseable by MusicBrainz track parser during an interactive import
+  session. :bug:`1779`
 
 
 1.3.16 (December 28, 2015)
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index 5da5ee0be..d1cc41015 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -59,6 +59,7 @@ Each plugin has its own set of options that can be defined in a section bearing
    lastimport
    lyrics
    mbcollection
+   mbsubmit
    mbsync
    metasync
    missing
@@ -162,6 +163,7 @@ Miscellaneous
 * :doc:`ihate`: Automatically skip albums and tracks during the import process.
 * :doc:`info`: Print music files' tags to the console.
 * :doc:`mbcollection`: Maintain your MusicBrainz collection list.
+* :doc:`mbsubmit`: Print an album's tracks in a MusicBrainz-friendly format.
 * :doc:`missing`: List missing tracks.
 * :doc:`random`: Randomly choose albums and tracks from your library.
 * :doc:`filefilter`: Automatically skip files during the import process based
diff --git a/docs/plugins/mbsubmit.rst b/docs/plugins/mbsubmit.rst
new file mode 100644
index 000000000..9312eb785
--- /dev/null
+++ b/docs/plugins/mbsubmit.rst
@@ -0,0 +1,54 @@
+MusicBrainz Submit Plugin
+=========================
+
+The ``mbsubmit`` plugin provides an extra prompt choice during an import
+session that prints the tracks of the current album in a format that is
+parseable by MusicBrainz's `track parser`_.
+
+.. _track parser: http://wiki.musicbrainz.org/History:How_To_Parse_Track_Listings
+
+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::
+
+    No matching release found for 3 tracks.
+    For help, see: http://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
+    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)
+
+    No matching release found for 3 tracks.
+    For help, see: http://beets.readthedocs.org/en/latest/faq.html#nomatch
+    [U]se as-is, as Tracks, Group albums, Skip, Enter search, enter Id, aBort,
+    Print tracks?
+
+As MusicBrainz currently does not support submitting albums programmatically,
+the recommended workflow is to copy the output of the ``Print tracks`` choice
+and paste it into the parser that can be found by clicking on the
+"`Track Parser`" button on MusicBrainz "`Tracklist`" tab.
+
+Configuration
+-------------
+
+To configure the plugin, make a ``mbsubmit:`` section in your configuration
+file. The following options are available:
+
+- **mb_format**: The format used for printing the tracks, defined using the
+  same template syntax as beets’ :doc:`path formats </reference/pathformat>`.
+  Default: ``$track. $title - $artist ($length)``.
+- **threshold**: The minimum strength of the autotagger recommendation that
+  will cause the ``Print tracks`` choice to be displayed on the prompt.
+  Default: ``medium`` (causing the choice to be displayed for all albums that
+  have a recommendation of medium strength or lower). Valid values: ``none``,
+  ``low``, ``medium``, ``strong``.
+
+Please note that some values of the ``threshold`` configuration option might
+require other ``beets`` command line switches to be enabled in order to work as
+intended. In particular, setting a threshold of ``strong`` will only display
+the prompt if ``timid`` mode is enabled. You can find more information about
+how the recommendation system works on :ref:`match-config`.