From ecf677ae4148f1eb4e47b468cda81a33cc9a816a Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Fri, 14 Aug 2015 20:50:29 -0700
Subject: [PATCH] Reorganize up some badfiles documentation

---
 beetsplug/badfiles.py     | 10 +++-----
 docs/plugins/badfiles.rst | 52 +++++++++++++++++++--------------------
 2 files changed, 29 insertions(+), 33 deletions(-)

diff --git a/beetsplug/badfiles.py b/beetsplug/badfiles.py
index 5d0954b8a..e072d82a3 100644
--- a/beetsplug/badfiles.py
+++ b/beetsplug/badfiles.py
@@ -30,7 +30,6 @@ import sys
 
 
 class BadFiles(BeetsPlugin):
-
     def run_command(self, cmd):
         self._log.debug("running command: {}",
                         displayable_path(list2cmdline(cmd)))
@@ -41,8 +40,7 @@ class BadFiles(BeetsPlugin):
             return 1, [line for line in e.output.split("\n") if line]
         except OSError as e:
             if e.errno == errno.ENOENT:
-                ui.print_("command not found: {}",
-                          cmd[0])
+                ui.print_("command not found: {}".format(cmd[0]))
                 sys.exit(1)
             else:
                 raise
@@ -77,12 +75,12 @@ class BadFiles(BeetsPlugin):
     def check_bad(self, lib, opts, args):
         for item in lib.items(args):
 
-            # First check if the path exists. If not, should run 'beets update'
-            # to cleanup your library.
+            # First, check whether the path exists. If not, the user
+            # should probably run `beet update` to cleanup your library.
             dpath = displayable_path(item.path)
             self._log.debug("checking path: {}", dpath)
             if not os.path.exists(item.path):
-                ui.print_("{}: file does not exist", dpath)
+                ui.print_("{}: file does not exist".format(dpath))
 
             # Run the checker against the file if one is found
             ext = os.path.splitext(item.path)[1][1:]
diff --git a/docs/plugins/badfiles.rst b/docs/plugins/badfiles.rst
index d11eefe77..d084dca82 100644
--- a/docs/plugins/badfiles.rst
+++ b/docs/plugins/badfiles.rst
@@ -1,41 +1,35 @@
 Bad Files Plugin
 ================
 
-Adds a `beet bad` command to check for missing, and optionally corrupt files.
+The ``badfiles`` plugin adds a ``beet bad`` command to check for missing and
+corrupt files.
 
-Configuration
--------------
+Configuring
+-----------
 
-Here is a very basic configuration that uses the default commands for MP3 and
-FLAC files, requiring the `mp3val`_ and
-packages to be installed::
+First, enable the ``badfiles`` plugin (see :ref:`using-plugins`). Then, add a
+``badfiles:`` section to your configuration file, like so::
 
     badfiles:
-      commands: {}
-    plugins: ... badfiles
+        commands: {}
 
-Note that the *mp3val* checker is a bit verbose and can output a lot of "stream
-error" messages, even for files that play perfectly well. Generally if more
-than one stream error happens, or if a stream error happens in the middle of a
-file, this is a bad sign.
+This uses two default checkers: `mp3val`_ for MP3s and the ordinary `FLAC`_
+command-line tools for those files. (You will need to install these yourself.)
+You can also add custom commands for a specific extension, like this::
+
+    badfiles:
+        commands:
+            ogg: myoggchecker --opt1 --opt2
+            flac: flac --test --warnings-as-errors --silent
 
 .. _mp3val: http://mp3val.sourceforge.net/
 .. _flac: https://xiph.org/flac/
 
-You can also add custom commands for a specific extension, e.g.::
+Using
+-----
 
-    badfiles:
-      commands:
-        ogg: myoggchecker --opt1 --opt2
-        flac: flac --test --warnings-as-errors --silent
-    plugins: ... badfiles
-
-Running
--------
-
-To run Badfiles, just use the ``beet bad`` command with Beets' usual query syntax.
-
-For instance, this will run a check on all songs containing the word "wolf"::
+Type ``beet bad`` with a query according to beets' usual query syntax. For
+instance, this will run a check on all songs containing the word "wolf"::
 
     beet bad wolf
 
@@ -43,11 +37,15 @@ This one will run checks on a specific album::
 
     beet bad album_id:1234
 
-Here is an example from my library where the FLAC decoder was signaling a
-corrupt file::
+Here is an example where the FLAC decoder was signals a corrupt file::
 
     beet bad title::^$
     /tank/Music/__/00.flac: command exited with status 1
       00.flac: *** Got error code 2:FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
       00.flac: ERROR while decoding data
                  state = FLAC__STREAM_DECODER_READ_FRAME
+
+Note that the default `mp3val` checker is a bit verbose and can output a lot
+of "stream error" messages, even for files that play perfectly well.
+Generally, if more than one stream error happens, or if a stream error happens
+in the middle of a file, this is a bad sign.