Update docs

Author: snejus

docs/dev/paths.rst

@@ -17,8 +17,9 @@ long-path support (Windows) are automatically managed by ``pathlib``.
 When storing paths in the database, however, convert them to bytes with
 ``bytestring_path()``. Paths in Beets are currently stored as bytes, although
 there are plans to eventually store ``pathlib.Path`` objects directly. To access
-media file paths in their stored form, use the ``.path`` property on ``Item``
-and ``Album``.
+media file paths from library objects, use ``.path`` for the absolute path as
+``bytes`` or ``.filepath`` for the absolute path as a ``pathlib.Path``. The
+database still stores these paths relative to the configured library root.
 
 Legacy utilities
 ----------------

docs/reference/query.rst

@@ -386,6 +386,8 @@ Sometimes it's useful to find all the items in your library that are
 ::
 
     $ beet list path:/my/music/directory
+    $ beet list path:Artist/Album
+    $ beet list path:Artist/Album/track.mp3
 
 In fact, beets automatically recognizes any query term containing a path
 separator (``/`` on POSIX systems) as a path query if that path exists, so this
@@ -395,6 +397,9 @@ command is equivalent as long as ``/my/music/directory`` exist:
 
     $ beet list /my/music/directory
 
+The ``path:`` field accepts either an absolute path under the configured music
+directory or a path relative to the library root.
+
 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.