From a23e31d1b688b48defd3a50ce9c9cce0e2fded34 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Mon, 28 Nov 2022 16:16:08 +0100 Subject: [PATCH 1/2] Improve playlist plugin docs --- docs/plugins/playlist.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/plugins/playlist.rst b/docs/plugins/playlist.rst index 81fc60beb..ebff72da5 100644 --- a/docs/plugins/playlist.rst +++ b/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. Since `playlist:` submits a regular beets query like any +other query syntax (eg. `artist:`, `year:`, ...), the sorting order of either +the configuartion setting `sort_item` or any sorting patterns submitted with +the query command will be used:: + + $ beet ls playlist:/path/to/someplaylist.m3u artist+ year+ + +Currently retaining the original sort order of the playlist is not supported. + 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. From 6b0634466228c534510efc6500af57b69ac9b690 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Tue, 29 Nov 2022 08:27:32 +0100 Subject: [PATCH 2/2] Further improve playlist plugin docs Incorporate wording suggestions and add links to query sections. --- docs/plugins/playlist.rst | 10 +++++----- docs/reference/query.rst | 4 ++++ 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/plugins/playlist.rst b/docs/plugins/playlist.rst index ebff72da5..9737874b0 100644 --- a/docs/plugins/playlist.rst +++ b/docs/plugins/playlist.rst @@ -25,14 +25,14 @@ name:: $ beet ls playlist:anotherplaylist A playlist query will use the paths found in the playlist file to match items -in the beets library. Since `playlist:` submits a regular beets query like any -other query syntax (eg. `artist:`, `year:`, ...), the sorting order of either -the configuartion setting `sort_item` or any sorting patterns submitted with -the query command will be used:: +in the beets library. ``playlist:`` submits a regular beets +:ref:`query` similar to a :ref:`specific fields query`. +If you want the list in any particular order, you can use the standard beets +query syntax for :ref:`sorting`:: $ beet ls playlist:/path/to/someplaylist.m3u artist+ year+ -Currently retaining the original sort order of the playlist is not supported. +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`` diff --git a/docs/reference/query.rst b/docs/reference/query.rst index 955bdf57d..a3d7944bf 100644 --- a/docs/reference/query.rst +++ b/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 ---------------