From d87a7474776d6f498e952c230a1b4ade96ca9e06 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Mon, 16 Nov 2015 12:43:59 -0800
Subject: [PATCH] Condense edit plugin documentation

Also avoided adding some unused command-line options.
---
 beetsplug/edit.py     |  2 +-
 docs/plugins/edit.rst | 59 +++++++++++++++++--------------------------
 2 files changed, 24 insertions(+), 37 deletions(-)

diff --git a/beetsplug/edit.py b/beetsplug/edit.py
index b31f4c5f5..e444ad3de 100644
--- a/beetsplug/edit.py
+++ b/beetsplug/edit.py
@@ -96,7 +96,7 @@ class EditPlugin(plugins.BeetsPlugin):
             action='store_true', dest='all',
             help='edit all fields',
         )
-        edit_command.parser.add_all_common_options()
+        edit_command.parser.add_album_option()
         edit_command.func = self._edit_command
         return [edit_command]
 
diff --git a/docs/plugins/edit.rst b/docs/plugins/edit.rst
index 28ac21681..5f3083948 100644
--- a/docs/plugins/edit.rst
+++ b/docs/plugins/edit.rst
@@ -1,49 +1,36 @@
 Edit Plugin
-============
-The ``edit`` plugin lets you open the tags, fields from a group of items, edit them in a text-editor and save them back.
-Add the ``edit`` plugin to your ``plugins:`` in your ``config.yaml``. Then
-simply do a query.
-::
+===========
 
-     beet edit beatles
-     beet edit beatles -a
-     beet edit beatles -f '$title $lyrics'
+The ``edit`` plugin lets you modify music metadata using your favorite text
+editor.
 
+Enable the ``edit`` plugin in your configuration (see :ref:`using-plugins`) and
+then type::
 
+     beet edit QUERY
 
-You get a list of hits to edit.``edit`` opens your standard text-editor with a list of your hits and for each hit a bunch of fields.
-Without anything specified in your ``config.yaml`` for ``edit:`` you will see
+Your text editor (i.e., the command in your ``$EDITOR`` environment variable)
+will open with a list of tracks to edit. Make your changes and exit your text
+editor to apply them to your music.
 
-for items
-::
+Command-Line Options
+--------------------
 
-    $track-$title-$artist-$album
+The ``edit`` command has these command-line options:
 
-and for albums
-::
-
-   $album-$albumartist
-
-You can get extra fields from the cmdline by adding
-::
-
-   -e year  -e comments
-
-
-If you add ``--all`` you get all the fields.
-
-After you edit the values in your text-editor - *and you may only edit the values, no deleting fields or adding fields!* - you save the file and you get a summary of your changes. Check em. Apply the changes into your library.
+- ``-a`` or ``--album``: Edit albums instead of individual items.
+- ``-e FIELD`` or ``--extra FIELD``: Specify an additional field to edit
+  (in addition to the defaults set in the configuration).
+- ``--all``: Edit *all* available fields.
 
 Configuration
 -------------
 
-Make a ``edit:`` section in your config.yaml ``(beet config -e)``
-::
+To configure the plugin, make an ``edit:`` section in your configuration
+file. The available options are:
 
-    edit:
-       albumfields: genre album
-       itemfields: track artist
-
-* The ``albumfields:`` and ``itemfields:`` is a list of fields you want to change.
-  ``albumfields:`` gets picked if you put ``-a`` in your search query, else ``itemfields:``. For a list of fields
-  do the ``beet fields`` command. Or put in a faulty one, hit enter and you get a list of available field.
+- **itemfields**: A space-separated list of item fields to include in the
+  editor by default.
+  Default: ``track title artist album``
+- **albumfields**: The same when editing albums (with the ``-a`` option).
+  Default: ``album albumartist``