m_option: deprecate OPT_PATHLIST

mpv has always had a separate type, OPT_PATHLIST, for paths/files. It
worked exactly like OPT_STRINGLIST except that it used : (unix) or ;
(windows) as a separator. There is no reason to have this distinction. :
is allowed in filenames on linux and ; is allowed on windows so it is
not even like these characters guarantee no escaping. Instead, we should
be consistent and use one separator (,) for everything. In the option
parsing, add some old compatibility code for the old path-specific
separators with a warning that it is deprecated and , is preferred. It's
not perfect. Someone using paths with , in them would now need to escape
them, but it's about the best we can do realistically. Remove all
references to path lists in the documents and treat it exactly like the
normal string list option.

DOCS/interface-changes/pathlist-options.txt

@@ -0,0 +1 @@
+all list options accept `,` as a separator, any other separator character is considered deprecated

DOCS/man/mpv.rst

@@ -637,12 +637,15 @@ the option also allows you to append a single tag with ``--display-tags-append``
 and the tag name can for example contain a literal ``,`` without the need for
 escaping.
 
-String list and path list options
+String list options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 String lists are separated by ``,``. The strings are not parsed or interpreted
-by the option system itself. However, most path or file list options use ``:``
-(Unix) or ``;`` (Windows) as separator, instead of ``,``.
+by the option system itself.
+
+Some options are path/file list options and these used to use ``:`` Unix or
+``;`` (Windows) as a separator instead of ``,``. The old separators still work,
+but this is deprecated and it is strongly recommended to use ``,`` instead.
 
 They support the following operations:
 

DOCS/man/options.rst

@@ -826,7 +826,7 @@ Program Behavior
     Load a Lua script. The second option allows you to load multiple scripts by
     separating them with the path separator (``:`` on Unix, ``;`` on Windows).
 
-    ``--scripts`` is a path list option. See `List Options`_ for details.
+    ``--scripts`` is a string list option. See `List Options`_ for details.
 
 ``--script-opt=<key=value>``, ``--script-opts=key1=value1,key2=value2,...``
     Set options for scripts. A script can query an option by key. If an
@@ -2268,7 +2268,7 @@ Audio
 ``--audio-files=<files>``
     Play audio from an external file while viewing a video.
 
-    This is a path list option. See `List Options`_ for details.
+    This is a string list option. See `List Options`_ for details.
 
 ``--audio-file=<file>``
     CLI/config file only alias for ``--audio-files-append``. Each use of this
@@ -2350,7 +2350,7 @@ Audio
 ``--audio-file-paths=<path1:path2:...>``
     Equivalent to ``--sub-file-paths`` option, but for auto-loaded audio files.
 
-    This is a path list option. See `List Options`_ for details.
+    This is a string list option. See `List Options`_ for details.
 
 ``--audio-client-name=<name>``
     The application name the player reports to the audio API. Can be useful
@@ -2435,7 +2435,7 @@ Subtitles
     and ``--secondary-sid`` to select the second index. (The index is printed
     on the terminal output after the ``--sid=`` in the list of streams.)
 
-    ``--sub-files`` is a path list option (see `List Options`_  for details), and
+    ``--sub-files`` is a string list option (see `List Options`_  for details), and
     can take multiple file names separated by ``:`` (Unix) or ``;`` (Windows),
     while  ``--sub-file`` takes a single filename, but can be used multiple
     times to add multiple files. Technically, ``--sub-file`` is a CLI/config
@@ -2882,7 +2882,7 @@ Subtitles
         - ``/path/to/video/subtitles/``
         -  the ``sub`` configuration subdirectory (usually ``~/.config/mpv/sub/``)
 
-    This is a path list option. See `List Options`_ for details.
+    This is a string list option. See `List Options`_ for details.
 
 ``--sub-visibility=<yes|no>``
     Can be used to disable display of subtitles, but still select and decode
@@ -6184,7 +6184,7 @@ them.
 
     Each use of the ``--glsl-shader`` option will add another file to the
     internal list of shaders, while ``--glsl-shaders`` takes a list of files,
-    and overwrites the internal list with it. The latter is a path list option
+    and overwrites the internal list with it. The latter is a string list option
     (see `List Options`_ for details).
 
     .. warning::
@@ -7716,7 +7716,7 @@ Miscellaneous
     it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite
     strictly enforced.)
 
-    This is a path list option. See `List Options`_ for details.
+    This is a string list option. See `List Options`_ for details.
 
 ``--external-file=<file>``
     CLI/config file only alias for ``--external-files-append``. Each use of this
@@ -7735,7 +7735,7 @@ Miscellaneous
     pass videos to this option, so this paragraph describes the behavior
     coincidentally resulting from implementation details.)
 
-    This is a path list option. See `List Options`_ for details.
+    This is a string list option. See `List Options`_ for details.
 
 ``--cover-art-file=<file>``
     CLI/config file only alias for ``--cover-art-files-append``. Each use of this

options/m_option.c

@@ -1425,10 +1425,10 @@ static int find_list_bstr(char **list, bstr item)
     return -1;
 }
 
-static char **separate_input_param(const m_option_t *opt, bstr param,
-                                   int *len, int op)
+static char **separate_input_param(struct mp_log *log, const m_option_t *opt,
+                                   bstr param, int *len, int op)
 {
-    char separator = opt->priv ? *(char *)opt->priv : OPTION_LIST_SEPARATOR;
+    char separator = OPTION_LIST_SEPARATOR;
     if (op == OP_APPEND || op == OP_REMOVE)
         separator = 0; // specially handled
     struct bstr str = param;
@@ -1438,6 +1438,21 @@ static char **separate_input_param(const m_option_t *opt, bstr param,
         str = bstr_cut(str, 1);
         n++;
     }
+    // Backwards compatibility for path list options.
+    if (opt->priv && n == 1 && separator != 0) {
+        separator = *(char *)opt->priv;
+        while (str.len) {
+            get_nextsep(&str, separator, 0);
+            str = bstr_cut(str, 1);
+            n++;
+        }
+        if (n) {
+            mp_warn(log, "Using '%c' as a separator is deprecated. "
+                    "Use ',' instead for separating items in lists.\n",
+                    OPTION_PATH_SEPARATOR);
+        }
+    }
+
     if (n == 0 && op != OP_NONE)
         return NULL;
 
@@ -1540,7 +1555,7 @@ static int parse_str_list_impl(struct mp_log *log, const m_option_t *opt,
         return 1;
 
     int n = 0;
-    res = separate_input_param(opt, param, &n, op);
+    res = separate_input_param(log, opt, param, &n, op);
     if (!res)
         return M_OPT_INVALID;
 
@@ -1745,7 +1760,7 @@ static int parse_keyvalue_list(struct mp_log *log, const m_option_t *opt,
         return 0;
     } else if (op == OP_DEL || op == OP_REMOVE) {
         int n = 0;
-        char **res = separate_input_param(opt, param, &n, op);
+        char **res = separate_input_param(log, opt, param, &n, op);
         if (!res)
             return M_OPT_INVALID;
         lst = dst ? VAL(dst) : NULL;