DOCS/mpv: clarify the location of cache/state files

1 files changed, 31 insertions, 7 deletions

diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index fc7122cb5b..c7c11fd2cb 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -1539,6 +1539,7 @@ input command can take an exit code: in this case, that exit code is returned.
 FILES
 =====
 
+Note that this section assumes Linux/BSD. On other platforms the paths may be different.
 For Windows-specifics, see `FILES ON WINDOWS`_ section.
 
 ``/usr/local/etc/mpv/mpv.conf``
@@ -1546,6 +1547,18 @@ For Windows-specifics, see `FILES ON WINDOWS`_ section.
     in default configuration will use ``/usr/local/etc/mpv/`` as config
     directory, while most Linux distributions will set it to ``/etc/mpv/``).
 
+``~/.cache/mpv``
+    The standard cache directory. Certain options within mpv may cause it to write
+    cache files to disk. This can be overridden by environment variables, in
+    ascending order:
+
+    :1: If ``$XDG_CACHE_HOME`` is set, then the derived cache directory
+        will be ``$XDG_CACHE_HOME/mpv``.
+    :2: If ``$MPV_HOME`` is set, then the derived cache directory will be
+       ``$MPV_HOME``.
+
+    If the directory does not exist, mpv will try to create it automatically.
+
 ``~/.config/mpv``
     The standard configuration directory. This can be overridden by environment
     variables, in ascending order:
@@ -1560,7 +1573,9 @@ For Windows-specifics, see `FILES ON WINDOWS`_ section.
 
 ``~/.mpv/``
     The original (pre 0.5.0) configuration directory. It will continue to be
-    read if present.
+    read if present. If this directory is present and the standard configuration
+    directory is not present, then cache files and watch later config files will
+    also be written to this directory.
 
     If both this directory and the standard configuration directory are
     present, configuration will be read from both with the standard
@@ -1601,6 +1616,13 @@ For Windows-specifics, see `FILES ON WINDOWS`_ section.
     the watch later feature. See for example the ``Q`` key binding, or the
     ``quit-watch-later`` input command.
 
+    This can be overridden by environment variables, in ascending order:
+
+    :1: If ``$XDG_STATE_HOME`` is set, then the derived watch later directory
+        will be ``$XDG_STATE_HOME/mpv/watch_later``.
+    :2: If ``$MPV_HOME`` is set, then the derived watch later directory will be
+       ``$MPV_HOME/watch_later``.
+
     Each file is a small config file which is loaded if the corresponding media
     file is loaded. It contains the playback position and some (not necessarily
     all) settings that were changed during playback. The filenames are hashed
@@ -1631,16 +1653,18 @@ You can find the exact path by running ``echo %APPDATA%\mpv\mpv.conf`` in cmd.ex
 Other config files (such as ``input.conf``) are in the same directory. See the
 `FILES`_ section above.
 
+The cache directory is located at ``%LOCALAPPDATA%/mpv``.
+
 The environment variable ``$MPV_HOME`` completely overrides these, like on
 UNIX.
 
 If a directory named ``portable_config`` next to the mpv.exe exists, all
-config will be loaded from this directory only. Watch later config files are
-written to this directory as well. (This exists on Windows only and is redundant
-with ``$MPV_HOME``. However, since Windows is very scripting unfriendly, a
-wrapper script just setting ``$MPV_HOME``, like you could do it on other
-systems, won't work. ``portable_config`` is provided for convenience to get
-around this restriction.)
+config will be loaded from this directory only. Watch later config files and
+cache files are written to this directory as well. (This exists on Windows
+only and is redundant with ``$MPV_HOME``. However, since Windows is very
+scripting unfriendly, a wrapper script just setting ``$MPV_HOME``, like you
+could do it on other systems, won't work. ``portable_config`` is provided for
+convenience to get around this restriction.)
 
 Config files located in the same directory as ``mpv.exe`` are loaded with
 lower priority. Some config files are loaded only once, which means that