Documentation tweaks for bucket (#747)

beetsplug/bucket.py

@@ -12,7 +12,7 @@
 # The above copyright notice and this permission notice shall be
 # included in all copies or substantial portions of the Software.
 
-"""Provides %bucket_alpha and %bucket_year functions for path formatting.
+"""Provides the %bucket{} function for path formatting.
 """
 
 from datetime import datetime

docs/changelog.rst

@@ -9,9 +9,9 @@ Changelog
 * :doc:`/plugins/ftintitle`: A new option lets you remove featured artists
   entirely instead of moving them to the title. Thanks to SUTJael.
 * Item and album queries are much faster.
-* The new :doc:`/plugins/bucket` provides a ``bucket()`` function for path 
-  formatting to generate folder names representing alphabetic/years ranges.
-  Thanks to Fabrice Laporte.
+* The new :doc:`/plugins/bucket` provides a ``%bucket{}`` function for path
+  formatting to generate folder names representing ranges of years or initial
+  letter. Thanks to Fabrice Laporte.
 
 Fixes:
 

docs/plugins/bucket.rst

@@ -1,33 +1,32 @@
 Bucket Plugin
 ==============
 
-The ``bucket`` plugin helps you keep a balanced files tree for your library
-by grouping your files into buckets folders representing ranges.
-This kind of files organization is usually used to classify your music by
-periods (eg *1960s*, *1970s* etc), or to divide bloated folders into smaller
-subfolders by grouping albums/artists alphabetically (eg *A-F*, *G-M*, *N-Z*).
+The ``bucket`` plugin groups your files into buckets folders representing
+*ranges*. This kind of organization can classify your music by periods of time
+(e.g,. *1960s*, *1970s*, etc.), or to divide overwhelmingly large folders into
+smaller subfolders by grouping albums or artists alphabetically (e.g., *A-F*,
+*G-M*, *N-Z*).
 
-To use this plugin, enable it by including ``bucket`` into ``plugins`` line of your
-beets config. The plugin provides a template function called ``%bucket`` for
-use in path format expressions::
+To use the plugin, enable ``bucket`` in your configuration file (see
+:ref:`using-plugins`). The plugin provides a :ref:`template function
+<template-functions>` called ``%bucket`` for use in path format expressions::
 
     paths:
-        default: /%bucket($year)/%bucket($artist)/$albumartist-$album-$year
+        default: /%bucket{$year}/%bucket{$artist}/$albumartist-$album-$year
 
-You must then define what ranges representations you allow in the ``bucket:``
-section of the config file::
+Then, define your ranges in the ``bucket:`` section of the config file::
 
     bucket:
         bucket_alpha: ['A-F', 'G-M', 'N-Z']
         bucket_year:  ['1980s', '1990s', '2000s']
 
 The ``bucket_year`` parameter is used for all substitutions occuring on the
-``$year`` field, while ``bucket_alpha`` takes care of the others textual fields.
+``$year`` field, while ``bucket_alpha`` takes care of textual fields.
 
-The definition of a range is somewhat loose, and multiple formats are allowed :
+The definition of a range is somewhat loose, and multiple formats are allowed:
 
-- for alpha ranges: the range is defined by the lowest and highest (ascii-wise) alphanumeric characters. eg *'ABCD'*, *'A-D'*, *'A->D'*, *[AD]* are equivalent.
-- for year ranges: digits characters are extracted and the two extremes years define the range. eg *'1975-77'*, *'1975,76,77'* and *'1975-1977'* are equivalent. If no upper bound is given, the range is extended to current year (unless a later range is defined). eg *'1975'* encompasses all years from 1975 until now.
+- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise) alphanumeric characters in the string you provide. For example, *ABCD*, *A-D*, *A->D*, and *[AD]* are all equivalent.
+- For year ranges: digits characters are extracted and the two extreme years define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are equivalent. If no upper bound is given, the range is extended to current year (unless a later range is defined). For example, *1975* encompasses all years from 1975 until now.
 
 If you want to group your files into multiple year ranges, you don't have to
 enumerate them all in `bucket_year` parameter but can activate the ``extrapolate``
@@ -38,6 +37,4 @@ of declared buckets::
         bucket_year: ['2000-05']
         extrapolate: true
 
-is enough to make the plugin return an enclosing five years range for any input year.
-
-
+The above configuration creates five-year ranges for any input year.