diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 64de51d112c13..60ac00927dcf2 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -499,32 +499,53 @@ console controls. (Which makes it suitable for playing data piped to stdin.)
 The special argument ``--`` can be used to stop mpv from interpreting the
 following arguments as options.
 
-When using the client API, you should strictly avoid using ``mpv_command_string``
+For paths passed to mpv CLI options, the situation is further complicated by the
+need to escape special characters. To work around this, the path can instead be
+wrapped in the "fixed-length" syntax, e.g. ``%n%string_of_length_n`` (see above).
+
+When using the libmpv API, you should strictly avoid using ``mpv_command_string``
 for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command``
 to avoid the need for filename escaping.
 
-For paths passed to suboptions, the situation is further complicated by the
-need to escape special characters. To work this around, the path can be
-additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n``
-(see above).
+The same applies when you're using the scripting API, where you should avoid using
+``mp.command``, and instead prefer using the "separate parameters" variants (such
+as ``mp.commandv`` or ``mp.command_native``), so that the filenames will always be
+correctly interpreted.
+
+Some mpv options will interpret special meanings for paths starting with ``~``,
+making it easy to dynamically find special directories, such as referring to the
+current user's home directory or the mpv configuration directory.
+
+When using the special ``~`` prefix, there must always be a trailing ``/`` after
+the special path prefix. In other words, ``~`` doesn't work, but ``~/`` will work.
+
+The following special paths/keywords are currently recognized:
+
+.. warning::
+
+    Beware that if ``--no-config`` is used, all of the "config directory"-based
+    paths (``~~/``, ``~~home/`` and ``~~global/``) will resolve to empty strings.
+
+    This means that commands such as ``expand-path "~~home/"`` will return an
+    empty string, and ``expand-path "~~home/foo/bar"`` will only return ``foo/bar``
+    (without any path prefix), which might not be what you expected.
+
+    Furthermore, certain commands such as ``mp.find_config_file("mpv.conf")``
+    won't have any config paths to search in, and would always return ``nil``,
+    which means "not found".
 
-Some mpv options interpret paths starting with ``~``.
-Currently, the prefix ``~~home/`` expands to the mpv configuration directory
-(usually ``~/.config/mpv/``).
-``~/`` expands to the user's home directory. (The trailing ``/`` is always
-required.) The following paths are currently recognized:
+    Be sure that your scripts can handle the "no config" scenarios.
 
 ================ ===============================================================
 Name             Meaning
 ================ ===============================================================
-``~~/``          If the subpath exists in any of the mpv's config directories
+``~~/``          If the subpath exists in any of mpv's config directories, then
                  the path of the existing file/dir is returned. Otherwise this
                  is equivalent to ``~~home/``.
-                 Note that if --no-config is used ``~~/foobar`` will resolve to
-                 ``foobar`` which can be unexpected.
-``~/``           user home directory root (similar to shell, ``$HOME``)
+``~/``           user home directory root (similar to a shell's ``$HOME``)
 ``~~home/``      mpv config dir (for example ``~/.config/mpv/``)
-``~~global/``    the global config path, if available (not on win32)
+``~~global/``    the global config path (such as ``/etc/mpv``), if available
+                 (not on win32)
 ``~~osxbundle/`` the macOS bundle resource path (macOS only)
 ``~~desktop/``   the path to the desktop (win32, macOS)
 ``~~exe_dir/``   win32 only: the path to the directory containing the exe (for