options: change path list options, and document list options

The changes to path list options is basically getting rid of the need to
pass multiple paths to a single option. Instead, you can use the option
multiple times. The old behavior can be used by using the -set suffix
with the option.

Change some options to path lists. For example --script is now append by
default, and if you use --script-set, you need to use ":"/";" as
separator instead of ",".

--sub-paths/--audio-file-paths is a deprecated alias now, and will break
if the user tries to pass multiple paths to it. I'm assuming that if
these are used, most users will pass only 1 path anyway.

--opengl-shaders has more compatibility handling, since it's probably
rather common that users pass multiple options to it.

Also document all that in the manpage.

I'll probably regret this later, as it somewhat increases the complexity
of the option parser, rather than increasing it.

1 files changed, 29 insertions, 0 deletions

diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 1da99715dc..9befe435da 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -416,6 +416,35 @@ file stops playing. If option ``--c`` is changed during playback of
 file-local options. The option ``--a`` is never reset here.
 
 
+List Options
+------------
+
+Some options which store lists of option values can have action suffixes. For
+example, you can set a ``,``-separated list of filters with ``--vf``, but the
+option also allows you to append filters with ``--vf-append``.
+
+Options for filenames do not use ``,`` as separator, but ``:`` (Unix) or ``;``
+(Windows).
+
+============= ===============================================
+Suffix        Meaning
+============= ===============================================
+-add          Append 1 or more items
+-add-str      Append single item (avoids need for escaping)
+-clr          Clear the option
+-del          Delete an existing item by integer index
+-pre          Prepend 1 or more items
+-set          Set a list of items
+============= ===============================================
+
+Although some operations allow specifiying multiple ``,``-separated items, using
+this is strongly discouraged and deprecated, except for ``-set``.
+
+Without suffix, the action taken is normally ``-set``.
+
+Some options (like ``--sub-file``, ``--audio-file``, ``--opengl-shader``) append
+one file per option use. Their default action is ``-add-str``.
+
 Playing DVDs
 ------------