From 342636377513e0f1fb4010b366fee44fcf0300df Mon Sep 17 00:00:00 2001
From: Pierre Rust <pierre.rust@gmail.com>
Date: Thu, 12 Jun 2014 09:14:05 +0200
Subject: [PATCH] Add documentation about sort specification.

---
 docs/reference/cli.rst   |  5 +++--
 docs/reference/query.rst | 22 ++++++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index 4ff0346a6..317dbd00d 100644
--- a/docs/reference/cli.rst
+++ b/docs/reference/cli.rst
@@ -169,8 +169,9 @@ list
 
 Want to search for "Gronlandic Edit" by of Montreal? Try ``beet list
 gronlandic``.  Maybe you want to see everything released in 2009 with
-"vegetables" in the title? Try ``beet list year:2009 title:vegetables``. (Read
-more in :doc:`query`.)
+"vegetables" in the title? Try ``beet list year:2009 title:vegetables``. You 
+can also specify the order used when outputting the results (Read more in 
+:doc:`query`.)
 
 You can use the ``-a`` switch to search for albums instead of individual items.
 In this case, the queries you use are restricted to album-level fields: for
diff --git a/docs/reference/query.rst b/docs/reference/query.rst
index cf981bed2..a224c8dc9 100644
--- a/docs/reference/query.rst
+++ b/docs/reference/query.rst
@@ -183,3 +183,25 @@ equivalent::
 Note that this only matches items that are *already in your library*, so a path
 query won't necessarily find *all* the audio files in a directory---just the
 ones you've already added to your beets library.
+
+
+Sort Order
+----------
+
+You can also specify the order used when outputting the results. Of course, this
+is only useful when displaying the result, for example with the ``list``
+command, and is useless when the query is used as a filter for an command. Use
+the name of the `field` you want to sort on, followed by a ``+`` or ``-`` sign
+if you want ascending or descending sort. For example this command::
+
+    $ beet list -a year+
+
+will list all albums in chronological order.
+
+You can also specify several sort orders, which will be used in the same order at
+which they appear in your query::
+
+    $ beet list -a genre+ year+
+ 
+This command will sort all albums by genre and, in each genre, in chronological
+order.