convert: changelog thanks & doc enhancements

docs/changelog.rst

@@ -4,8 +4,8 @@ Changelog
 1.0b16 (in development)
 -----------------------
 
-* New plugin: :doc:`/plugins/convert` lets you convert parts of your collection
-  to an external directory using flac and lame.
+* New plugin: :doc:`/plugins/convert` transcodes music and embeds album art
+  while copying to a separate directory. Thanks to Jakob Schnitzer.
 * New plugin: :doc:`/plugins/fuzzy_search` lets you find albums and tracks using
   fuzzy string matching so you don't have to type (or even remember) their exact
   names. Thanks to Philippe Mongeau.
@@ -20,7 +20,7 @@ Changelog
   rather than just one. For example, if your FLAC file has both ordinary FLAC
   tags and ID3 tags, the ID3 tags are now also removed.
 * :ref:`stats-cmd` command: New ``--exact`` switch to make the file size
-  calculation more accurate (thanks to yagebu).
+  calculation more accurate (thanks to Jakob Schnitzer).
 * :ref:`list-cmd` command: Templates given with ``-f`` can now show items' paths
   (using ``$path``).
 * Fix album queries for ``artpath`` and other non-item fields.
@@ -30,7 +30,7 @@ Changelog
 * :doc:`/plugins/lastgenre`: Use the albums' existing genre tags if they pass
   the whitelist (thanks to Fabrice Laporte).
 * :doc:`/plugins/lastgenre`: Add a ``lastgenre`` command for fetching genres
-  post facto (thanks to yagebu).
+  post facto (thanks to Jakob Schnitzer).
 * :doc:`/plugins/fetchart`: Fix a bug where cover art filenames could lack
   a ``.jpg`` extension.
 * :doc:`/plugins/lyrics`: Fix an exception with non-ASCII lyrics.

docs/plugins/convert.rst

@@ -3,25 +3,26 @@ Convert Plugin
 
 The ``convert`` plugin lets you convert parts of your collection to a directory
 of your choice. Currently only converting from MP3 or FLAC to MP3 is supported.
-It will skip files that are already present in the target directory. It uses
-the same directory structure as your library.
+It will skip files that are already present in the target directory. Converted
+files follow the same path formats as your library.
 
 Installation
 ------------
 
-This plugin requires ``flac`` and ``lame``. If thoses executables are in your
-path, they will be found automatically by the plugin, otherwise you have to set
-their respective config options. Of course you will have to enable the plugin
-as well (see :doc:`/plugins/index`)::
+First, enable the ``convert`` plugin (see :doc:`/plugins/index`).
+
+To transcode music, this plugin requires the ``flac`` and ``lame`` command-line
+tools. If those executables are in your path, they will be found automatically
+by the plugin. Otherwise, configure the plugin to locate the executables::
 
     [convert]
-    flac:/usr/bin/flac
-    lame:/usr/bin/lame
+    flac: /usr/bin/flac
+    lame: /usr/bin/lame
 
 Usage
 -----
 
-To convert a part of your collection simply run ``beet convert QUERY``. This
+To convert a part of your collection, run ``beet convert QUERY``. This
 will display all items matching ``QUERY`` and ask you for confirmation before
 starting the conversion. The ``-a`` (or ``--album``) option causes the command
 to match albums instead of tracks.
@@ -32,24 +33,29 @@ or overwrite the respective configuration options.
 Configuration
 -------------
 
-This plugin offers a couple of configuration options: If you want to disable
-that album art is embedded in your converted items (enabled by default), you
-will have to set the ``embed`` option to false. If you set ``max_bitrate``, all
-MP3 files with a higher bitrate will be converted and thoses with a lower
-bitrate will simply be copied. Be aware that this doesn't mean that your
-converted files will have a lower bitrate since that depends on the specified
-encoding options. By default only FLAC files will be converted (and all MP3s
-will be copied). ``opts`` are the encoding options that are passed to ``lame``
-(defaults to "-V2"). Please refer to the ``lame`` docs for possible options.
+The plugin offers several configuration options, all of which live under the
+``[convert]`` section:
 
-The ``dest`` sets the directory the files will be converted (or copied) to.
-This is a required setting and has to be set either in ``.beetsconfig`` or on
-the commandline. Finally ``threads`` lets you determine the number of threads
-to use for encoding (default: 2). An example configuration::
+* ``dest`` sets the directory the files will be converted (or copied) to.
+  A destination is required---you either have to provide it in the config file
+  or on the command line using the ``-d`` flag.
+* ``embed`` indicates whether or not to embed album art in converted items.
+  Default: true.
+* If you set ``max_bitrate``, all MP3 files with a higher bitrate will be
+  transcoded and those with a lower bitrate will simply be copied. Note that
+  this does not guarantee that all converted files will have a lower
+  bitrate---that depends on the encoder and its configuration. By default, FLAC
+  files will be converted and all MP3s will be copied without transcoding.
+* ``opts`` are the encoding options that are passed to ``lame``. Default: 
+  "-V2". Please refer to the LAME documentation for possible options.
+* Finally, ``threads`` determines the number of threads to use for parallel
+  encoding. Default: 2.
+
+Here's an example configuration::
 
     [convert]
-    embed:false
-    max_bitrate:200
-    opts:-V4
-    dest:/home/user/MusicForPhone
-    threads:4
+    embed: false
+    max_bitrate: 200
+    opts: -V4
+    dest: /home/user/MusicForPhone
+    threads: 4