Merge pull request #4563 from JOJ0/playlist_docs

Improve playlist plugin docs

docs/plugins/playlist.rst

@@ -24,6 +24,16 @@ name::
 
     $ beet ls playlist:anotherplaylist
 
+A playlist query will use the paths found in the playlist file to match items
+in the beets library. ``playlist:`` submits a regular beets
+:ref:`query<queries>` similar to a :ref:`specific fields query<fieldsquery>`.
+If you want the list in any particular order, you can use the standard beets
+query syntax for :ref:`sorting<query-sort>`::
+
+    $ beet ls playlist:/path/to/someplaylist.m3u artist+ year+
+
+Playlist queries do not reflect the original order in the m3u file.
+
 The plugin can also update playlists in the playlist directory automatically
 every time an item is moved or deleted. This can be controlled by the ``auto``
 configuration option.

docs/reference/query.rst

@@ -1,3 +1,5 @@
+.. _queries:
+
 Queries
 =======
 
@@ -50,6 +52,8 @@ will match both "The House of Tomorrow" by the Magnetic Fields, as well as
 "Yesterday" by The Beatles. Note that the comma has to be followed by a space
 (e.g., ``foo,bar`` will be treated as a single keyword, *not* as an OR-query).
 
+.. _fieldsquery:
+
 Specific Fields
 ---------------