Plugin docs overhaul tweaks through "duplicates"

Moving alphabetically through the docs. Got a long way to go...

docs/Makefile

@@ -17,7 +17,7 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest auto
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -38,6 +38,10 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
+# My magical rebuilding, Safari-reloading auto target.
+auto:
+	watchmedo shell-command --patterns='*.rst' --ignore-pattern='_build/*' --recursive --command='make html ; osascript -l JavaScript refresh_safari.js' --wait
+
 clean:
 	-rm -rf $(BUILDDIR)/*
 

docs/plugins/bpd.rst

@@ -70,16 +70,17 @@ on your headless server box. Rad!
 Configuration
 -------------
 
-Available options are pretty self-explanatory:
+To configure the plugin, make a ``bpd:`` section in your configuration file.
+The available options are:
 
-- ``host``
-  Default: ``u''``
-- ``port``
-  Default: ``6600``
-- ``password``
-  Default: ``u''``
-- ``volume``: initial volume in percent
-  Default: ``100``
+- ``host``:
+  Default: Bind to all interfaces.
+- ``port``:
+  Default: 6600
+- ``password``:
+  Default: No password.
+- ``volume``: Initial volume, as a percentage.
+  Default: 100
 
 Here's an example::
 

docs/plugins/bucket.rst

@@ -1,5 +1,5 @@
 Bucket Plugin
-==============
+=============
 
 The ``bucket`` plugin groups your files into buckets folders representing
 *ranges*. This kind of organization can classify your music by periods of time
@@ -38,19 +38,20 @@ The definition of a range is somewhat loose, and multiple formats are allowed:
 Configuration
 -------------
 
-Available options:
+To configure the plugin, make a ``bucket:`` section in your configuration file.
+The available options are:
 
-- ``bucket_alpha``: ranges to use for all substitutions occuring on textual
+- ``bucket_alpha``: Ranges to use for all substitutions occurring on textual
   fields.
-  Default: ``[]``
-- ``bucket_alpha_regex``: list of ``key: value`` (one per line) with 'key'
-  being one of the `bucket_alpha` range and 'value' a regex that override
-  original range definition.
-  Default: ``{}``
-- ``bucket_year``: ranges to use for all substitutions occuring on the
+  Default: none.
+- ``bucket_alpha_regex``: A ``range: regex`` mapping (one per line) where
+  ``range`` is one of the `bucket_alpha` range and ``value`` is  a regex that
+  override original range definition.
+  Default: none.
+- ``bucket_year``: Ranges to use for all substitutions occurring on the
   `$year` field.
-  Default: ``[]``
-- ``extrapolate`` : activate it when you want to group your files into multiple
+  Default: none.
+- ``extrapolate``: Enable this if you want to group your files into multiple
   year ranges without enumerating them all. This option will generate year
   bucket names by reproducing characteristics of declared buckets.
   Default: ``no``
@@ -64,6 +65,6 @@ Here's an example::
          bucket_alpha_regex:
            'A - D': ^[0-9a-dA-D…äÄ]
 
-The above configuration creates five-year ranges for any input year.
+THis configuration creates five-year ranges for any input year.
 The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9
-and … (three dots). The other alpha buckets work as ranges.
+and … (ellipsis). The other alpha buckets work as ranges.

docs/plugins/chroma.rst

@@ -105,8 +105,12 @@ written to files' metadata.
 Configuration
 -------------
 
-The only option is **auto**, set it to 'no' to disable fingerprinting on
-import.
+There is one configuration option in the ``chroma:`` section, ``auto``, which
+controls whether to fingerprint files during the import process. To disable
+fingerprint-based autotagging, set it to ``no``, like so::
+
+    chroma:
+        auto: no
 
 Submitting Fingerprints
 -----------------------

docs/plugins/convert.rst

@@ -50,35 +50,38 @@ them.
 Configuration
 -------------
 
-Available options:
+To configure the plugin, make a ``convert:`` section in your configuration
+file. The available options are:
 
-- ``auto``: set it to ``yes`` to import transcoded versions of your files
-  automatically during the ``import`` command. With this option enabled, the
-  importer will transcode all non-MP3 files over the maximum bitrate before
-  adding them to your library.
+- ``auto``: Import transcoded versions of your files automatically during
+  imports. With this option enabled, the importer will transcode all (in the
+  default configuration) non-MP3 files over the maximum bitrate before adding
+  them to your library.
   Default: ``no``.
-- ``dest``: the directory where the files will be converted (or copied) to.
-  Default: ``None``
-- ``embed`` indicates whether or not to embed album art in converted items.
-  Default: ``yes``.
-- ``max_bitrate``: all lossy files with a higher bitrate will be
+- ``dest``: The directory where the files will be converted (or copied) to.
+  Default: none.
+- ``embed`` Embed album art in converted items. Default: ``yes``.
+- ``max_bitrate``: All lossy 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.
-- ``never_convert_lossy_files``: cross-conversions between lossy codecs---such
+  Default: none.
+- ``never_convert_lossy_files``: Cross-conversions between lossy codecs---such
   as mp3, ogg vorbis, etc,---makes little sense as they will decrease quality
   even further. If set to ``yes``, lossy files are always copied.
-  Default: ``no``
-- ``paths``: lets you specify the directory structure and naming scheme for the
+  Default: ``no``.
+- ``paths``: Lets you specify the directory structure and naming scheme for the
   converted files. Use the same format as the top-level ``paths`` section (see
   :ref:`path-format-config`).
   By default, the plugin reuses your top-level path format settings.
-- ``quiet``: prevents the plugin from announcing every file it processes.
+- ``quiet``: Prevent the plugin from announcing every file it processes.
   Default: ``false``.
-- ``threads``: number of threads to use for parallel encoding.
+- ``threads``: The number of threads to use for parallel encoding.
   By default, the plugin will detect the number of processors available and use
   them all.
 
+You can also configure the format to use for transcoding.
+
 .. _convert-format-config:
 
 Configuring the transcoding command

docs/plugins/duplicates.rst

@@ -36,46 +36,48 @@ duplicates themselves via command-line switches ::
 Configuration
 -------------
 
-Available options (mirroring the CLI ones):
+To configure the plugin, make a ``duplicates:`` section in your configuration
+file. The available options mirror the command-line options:
 
-- ``album``: lists duplicate albums instead of tracks.
+- ``album``: List duplicate albums instead of tracks.
   Default: ``no``.
-- ``checksum``: enables the use of any arbitrary command to compute a checksum
-  of items. It overrides the ``keys`` option the first time it is run; however,
-  because it caches the resulting checksum as ``flexattrs`` in the database,
-  you can use ``--keys=name_of_the_checksumming_program any_other_keys`` (or
-  set configuration ``keys``option) the second time around.
+- ``checksum``: Use an arbitrary command to compute a checksum
+  of items. This overrides the ``keys`` option the first time it is run;
+  however, because it caches the resulting checksum as ``flexattrs`` in the
+  database, you can use ``--keys=name_of_the_checksumming_program
+  any_other_keys`` (or set configuration ``keys`` option) the second time
+  around.
   Default: ``ffmpeg -i {file} -f crc -``.
-- ``copy``: takes a destination base directory into which it will copy matched
+- ``copy``: A destination base directory into which to copy matched
   items.
+  Default: none (disabled).
+- ``count``: Print a count of duplicate tracks or albums in the format
+  ``$albumartist - $album - $title: $count`` (for tracks) or ``$albumartist -
+  $album: $count`` (for albums).
   Default: ``no``.
-- ``count``: prints a count of duplicate tracks or albums, with ``format``
-  hard-coded to ``$albumartist - $album - $title: $count`` or ``$albumartist -
-  $album: $count`` (for the ``-a`` option).
-  Default: ``no``.
-- ``delete``: removes matched items from the library and from the disk.
+- ``delete``: Removes matched items from the library and from the disk.
   Default: ``no``
-- ``format``: lets you specify a specific format with which to print every track
-  or album. This uses the same template syntax as beets
-  ’:doc:`path formats</reference/pathformat>`.  The usage is inspired by, and
+- ``format``: A specific format with which to print every track
+  or album. This uses the same template syntax as beets'
+  :doc:`path formats</reference/pathformat>`.  The usage is inspired by, and
   therefore similar to, the :ref:`list <list-cmd>` command.
   Default: :ref:`list_format_item`
-- ``full``:lists every track or album that has duplicates, not just the
+- ``full``: List every track or album that has duplicates, not just the
   duplicates themselves.
   Default: ``no``.
-- ``keys``: defines in which track or album fields duplicates are to be
+- ``keys``: Define in which track or album fields duplicates are to be
   searched. By default, the plugin uses the musicbrainz track and album IDs for
   this purpose. Using the ``keys`` option (as a YAML list in the configuration
   file, or as space-delimited strings in the command-line), you can extend this
   behavior to consider other attributes.
   Default: ``[mb_trackid, mb_albumid]``
-- ``move``: takes a destination base directory into which it will move matched
+- ``move``: A destination base directory into which it will move matched
   items.
+  Default: none (disabled).
+- ``path``: Output the path instead of metadata when listing duplicates.
   Default: ``no``.
-- ``path``: convenience wrapper for ``-f \$path``.
-  Default: ``no``.
-- ``tag``: takes a ``key=value`` string, and adds a new ``key`` attribute with
-  ``value`` value as a flexattr to the database.
+- ``tag``: A ``key=value`` pair. The plugin will add a new ``key`` attribute
+  with ``value`` value as a flexattr to the database for duplicate items.
   Default: ``no``.
 
 Examples

docs/refresh_safari.js

@@ -0,0 +1,21 @@
+var safari = Application('com.apple.Safari');
+safari.strictPropertyScope = true;
+safari.strictCommandScope = true;
+
+for (var i = 0; i < safari.windows.length; ++i) {
+  var win = safari.windows[i];
+  var tabs = win.tabs;
+  if (Object.keys(tabs).length) {
+    for (var j = 0; j < win.tabs.length; ++j) {
+      var tab = win.tabs[j];
+      var url = tab.url();
+      if (url.indexOf("file:") == 0) {
+        // A local file URL.
+        console.log(url);
+        tab.url = url;  // Refresh.
+      }
+    }
+  }
+}
+
+'done';