options: add -remove action to list options

Actually I wanted this for key/value lists only, but add it to the
others for consistency too. (For vf/af it barely makes even sense, but
anyway.)

3 files changed, 24 insertions, 5 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 08edf618b1..8f8a5681cc 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -725,6 +725,10 @@ Input Commands that are Possibly Subject to Change
 ``vf <operation> <value>``
     Change video filter chain.
 
+    The semantics are exactly the same as with option parsing (see
+    `VIDEO FILTERS`_). As such the text below is a redundant and incomplete
+    summary.
+
     The first argument decides what happens:
 
     <set>
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 9ff62ae4f0..a96dd1149e 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -496,6 +496,7 @@ Suffix        Meaning
 -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)
+-remove       Delete item if present (does not interpret escapes)
 -del          Delete 1 or more items by integer index
 -toggle       Append an item, or remove if if it already exists (no escapes)
 ============= ===============================================
@@ -518,6 +519,7 @@ 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)
+-remove       Delete item by key if present (does not interpret escapes)
 ============= ===============================================
 
 Keys are unique within the list. If an already present key is set, the existing
@@ -538,6 +540,7 @@ Suffix        Meaning
 -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)
+-remove       Delete filter if present
 -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
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index a9288d7a93..7f0b0f9bc9 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -96,12 +96,24 @@ filter list.
     Prepends the filters given as arguments to the filter list. (Passing
     multiple filters is currently still possible, but deprecated.)
 
+``--vf-remove=filter``
+    Deletes the filter from the list. The filter can be either given the way it
+    was added (filter name and its full argument list), or by label (prefixed
+    with ``@``). Matching of filters works as follows: if either of the compared
+    filters has a label set, only the labels are compared. If none of the
+    filters have a label, the filter name, arguments, and argument order are
+    compared.
+
+``-vf-toggle=filter``
+    Add the given filter to the list if it was not present yet, or remove it
+    from the list if it was present. Matching of filters works as described in
+    ``--vf-remove``.
+
 ``--vf-del=filter``
-    Deletes the filter. The filter can even given the way it was added (filter
-    name and its full argument list), by label (prefixed with ``@``), or as
-    index number. Index numbers start at 0, negative numbers address the end of
-    the list (-1 is the last). (Passing multiple filters is currently still
-    possible, but deprecated.)
+    Sort of like ``--vf-remove``, but also accepts an index number. Index
+    numbers start at 0, negative numbers address the end of the list (-1 is the
+    last). (Passing multiple filters is currently still possible, but
+    deprecated.)
 
 ``--vf-clr``
     Completely empties the filter list.