From 90fb79f40834d219323dcf07284c3177bfae38e6 Mon Sep 17 00:00:00 2001
From: Cole Miller <git@cole-miller.net>
Date: Tue, 17 Dec 2019 16:54:56 -0500
Subject: [PATCH] Document `index_tracks' option

---
 docs/plugins/discogs.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/plugins/discogs.rst b/docs/plugins/discogs.rst
index 6c16083ee..80be4c8bb 100644
--- a/docs/plugins/discogs.rst
+++ b/docs/plugins/discogs.rst
@@ -48,6 +48,33 @@ Configuration
 
 This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
 
+There is one additional option in the ``discogs:`` section, ``index_tracks``.
+Index tracks (see the `Discogs guidelines
+<https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#12.13>`_),
+along with headers, mark divisions between distinct works on the same release
+or within works. When ``index_tracks`` is enabled,::
+
+    discogs:
+        index_tracks: yes
+
+beets will incorporate the names of the divisions containing each track into
+the imported track's title. For example, importing
+`this album
+<https://www.discogs.com/Handel-Sutherland-Kirkby-Kwella-Nelson-Watkinson-Bowman-Rolfe-Johnson-Elliott-Partridge-Thomas-The-A/release/2026070>`_
+would result in track names like::
+
+    Messiah, Part I: No.1: Sinfony
+    Messiah, Part II: No.22: Chorus- Behold The Lamb Of God
+    Athalia, Act I, Scene I: Sinfonia
+
+whereas with ``index_track`` disabled you'd get::
+
+    No.1: Sinfony
+    No.22: Chorus- Behold The Lamb Of God
+    Sinfonia
+
+This option is useful when importing classical music.
+
 Troubleshooting
 ---------------