options: increase consistency between list options and document them

Whenever I deal with this, I have to look at the code to make sense of
this. And beyond that, there are some strange inconsistencies. (I think
this code is cursed. It always was, and maybe always will be.)

Although the manpage claimed that using multiple items for -add etc. is
deprecated, string list options didn't warn against it. So add the
warning, and add something in the changelog (even though nobody will
ever read this).

The manpage mentioned --vf-append, but this didn't even exist. So add
it, I guess. We encourage using -append for the other option types, so
for consistency, it should work on filter options. (And I already
tricked me into believing it existed when I mentioned it in the
manpage.)

Make the "operations" table separate for all option types, and mention
the option type on every single of the top-level list options.

1 files changed, 72 insertions, 17 deletions

diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index e41e992072..eaced80082 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -472,37 +472,92 @@ 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``.
+example, the ``--display-tags`` option takes a ``,``-separated list of tags, but
+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.
 
-Options for filenames do not use ``,`` as separator, but ``:`` (Unix) or ``;``
-(Windows).
+String list and path 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 ``,``.
+
+They support the following operations:
 
 ============= ===============================================
 Suffix        Meaning
 ============= ===============================================
--add          Append 1 or more items (may become alias for -append)
--append       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
--toggle       Append an item, or remove if if it already exists
+-set          Set a list of items (using the list separator, interprets escapes)
+-append       Append single item (does not interpret escapes)
+-add          Append 1 or more items (same syntax as -set)
+-pre          Prepend 1 or more items (same syntax as -set)
+-clr          Clear the option (remove all items)
+-del          Delete 1 or more items by integer index
+-toggle       Append an item, or remove if if it already exists (no escapes)
 ============= ===============================================
 
-Although some operations allow specifying multiple ``,``-separated items, using
-this is strongly discouraged and deprecated, except for ``-set``.
+``-append`` is meant as a simple way to append a single item without having
+to escape the argument (you may still need to escape on the shell level).
+
+Key/value list options
+~~~~~~~~~~~~~~~~~~~~~~
+
+A key/value list is a list of key/value string pairs. In programming languages,
+this type of data structure is often called a map or a dictionary. The order
+normally does not matter, although in some cases the order might matter.
+
+They support the following operations:
+
+============= ===============================================
+Suffix        Meaning
+============= ===============================================
+-set          Set a list of items (using ``,`` as separator)
+-append       Append a single item (escapes for the key, no escapes for the value)
+-add          Append 1 or more items (same syntax as -set)
+============= ===============================================
 
-Without suffix, the action taken is normally ``-set``.
+Filter options
+~~~~~~~~~~~~~~
+
+This is a very complex option type for the ``--af`` and ``--vf`` options only.
+They often require complicated escaping. See `VIDEO FILTERS`_ for details. They
+support the following operations:
+
+============= ===============================================
+Suffix        Meaning
+============= ===============================================
+-set          Set a list of filters (using ``,`` as separator)
+-append       Append single filter
+-add          Append 1 or more filters (same syntax as -set)
+-pre          Prepend 1 or more filters (same syntax as -set)
+-clr          Clear the option (remove all filters)
+-del          Delete 1 or more filters by integer index or filter label
+-toggle       Append a filter, or remove if if it already exists
+-help         Pseudo operation that prints a help text to the terminal
+============= ===============================================
+
+General
+~~~~~~~
+
+Without suffix, the operation used is normally ``-set``.
+
+Although some operations allow specifying multiple items, using this is strongly
+discouraged and deprecated, except for ``-set``. There is a chance that
+operations like ``-add`` and ``-pre`` will work like ``-append`` and accept a
+single, unescaped item only (so the ``,`` separator will not be interpreted and
+is passed on as part of the value).
 
 Some options (like ``--sub-file``, ``--audio-file``, ``--glsl-shader``) are
 aliases for the proper option with ``-append`` action. For example,
 ``--sub-file`` is an alias for ``--sub-files-append``.
 
-Some options only support a subset of the above.
-
 Options of this type can be changed at runtime using the ``change-list``
-command, which takes the suffix as separate operation parameter.
+command, which takes the suffix (without the ``-``) as separate operation
+parameter.
 
 CONFIGURATION FILES
 ===================