From 71d6dc354453c04bee50fcfd30c79c63d969e217 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Tue, 13 Jun 2017 09:27:42 -0400
Subject: [PATCH] Docs refinements for #2581

---
 docs/changelog.rst        |  8 ++++----
 docs/reference/cli.rst    | 11 ++++-------
 docs/reference/config.rst | 11 ++++-------
 3 files changed, 12 insertions(+), 18 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 5b42be08da..fb4f0837a7 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -6,10 +6,10 @@ Changelog
 
 Features:
 
-* It is now possible to set fields to certain values during import, using
-  either the `importer.set_fields` dictionary in the config file, or by
-  passing one or more `--set field=value` options on the command-line.
-  :bug: `1881`
+* You can now set fields to certain values during :ref:`import-cmd`, using
+  either a ``--set field=value`` command-line flag or a new :ref:`set_fields`
+  configuration option under the `importer` section.
+  Thanks to :user:`bartkl`. :bug: `1881` :bug:`2581`
 * :ref:`Date queries <datequery>` can now include times, so you can filter
   your music down to the second. Thanks to :user:`discopatrick`. :bug:`2506`
   :bug:`2528`
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index c5ea5b3493..3e668f013d 100644
--- a/docs/reference/cli.rst
+++ b/docs/reference/cli.rst
@@ -138,16 +138,13 @@ Optional command flags:
   searching for other candidates by using the ``--search-id SEARCH_ID`` option.
   Multiple IDs can be specified by simply repeating the option several times.
 
-* You can supply ``--set`` options with ``field=value`` pairs to assign to
-  those fields the specified values on import, in addition to such field/value
-  pairs defined in the ``importer.set_fields`` dictionary in the configuration
-  file. Make sure to use an option per field/value pair, like so::
+* You can supply ``--set field=value`` to assign `field` to `value` on import.
+  These assignments will merge with (and possibly override) the
+  :ref:`set_fields` configuration dictionary. You can use the option multiple
+  times on the command line, like so::
 
     beet import --set genre="Alternative Rock" --set mood="emotional"
 
-  Note that values for the fields specified on the command-line override the
-  ones defined for those fields in the configuration file.
-
 .. _rarfile: https://pypi.python.org/pypi/rarfile/2.2
 
 .. only:: html
diff --git a/docs/reference/config.rst b/docs/reference/config.rst
index bcd30169bd..9faddd2d24 100644
--- a/docs/reference/config.rst
+++ b/docs/reference/config.rst
@@ -591,18 +591,15 @@ Default: ``no``.
 set_fields
 ~~~~~~~~~~
 
-A dictionary of field/value pairs, each one used to set a field to the
-corresponding value during import.
-
-Example: ::
+A dictionary indicating fields to set to values for newly imported music.
+Here's an example::
 
     set_fields:
         genre: 'To Listen'
         collection: 'Unordered'
 
-Note that field/value pairs supplied via ``--set`` options on the
-command-line are processed in addition to those specified here. Those values
-override the ones defined here in the case of fields with the same name.
+Other field/value pairs supplied via the ``--set`` option on the command-line
+override any settings here for fields with the same name.
 
 Default: ``{}`` (empty).