sub: mess with styling defaults, change --ass-use-margins behavior

Now --ass-use-margins doesn't apply to normal subtitles anymore. This is
probably the inverse from the mpv behavior users expected so far, and
thus a breaking change, so rename the option, that the user at least has
a chance to lookup the option and decide whether the new behavior is
wanted or not.

The basic idea here is:
- plain text subtitles should have a certain useful defalt behavior,
  like actually using margins
- ASS subtitles should never be broken by default
- ASS subtitles should look and behave like plaintext subtitles if
  the --ass-style-override=force option is used

This also subtly changes --sub-scale-with-window and adds the --ass-
scale-with-window option. Since this one isn't so important, don't
bother with compatibility.

3 files changed, 32 insertions, 7 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 36486bedac..80b4b253e9 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -1381,8 +1381,11 @@ Property list
 ``sub-scale`` (RW)
     Subtitle font size multiplier.
 
-``ass-use-margins`` (RW)
-    See ``--ass-use-margins``.
+``ass-force-margins`` (RW)
+    See ``--ass-force-margins``.
+
+``sub-use-margins`` (RW)
+    See ``--sub-use-margins``.
 
 ``ass-vsfilter-aspect-compat`` (RW)
     See ``--ass-vsfilter-aspect-compat``.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index a50bd09e27..7ba22949cd 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -438,7 +438,8 @@ Program Behavior
     Enable the youtube-dl hook-script. It will look at the input URL, and will
     play the video located on the website. This works with many streaming sites,
     not just the one that the script is named after. This requires a recent
-    version of youtube-dl to be installed on the system. (Enabled by default.)
+    version of youtube-dl to be installed on the system. (Enabled by default,
+    except when the client API / libmpv is used.)
 
     If the script can't do anything with an URL, it will do nothing.
 
@@ -1155,13 +1156,22 @@ Subtitles
     doesn't covert the window fully, e.g. because screen aspect and window
     aspect mismatch (and the player adds black bars).
 
+    Default: yes.
+
     This option is misnamed. The difference to the confusingly similar sounding
     option ``--sub-scale-by-window`` is that ``--sub-scale-with-window`` still
     scales with the approximate window size, while the other option disables
     this scaling.
 
+    Affects plain text subtitles only (or ASS if ``--ass-style-override`` is
+    set high enough).
+
+``--ass-scale-with-window=<yes|no>``
+    Like ``--sub-scale-with-window``, but affects subtitles in ASS format only.
     Like ``--sub-scale``, this can break ASS subtitles.
 
+    Default: no.
+
 ``--embeddedfonts``, ``--no-embeddedfonts``
     Use fonts embedded in Matroska container files and ASS scripts (default:
     enabled). These fonts can be used for SSA/ASS subtitle rendering.
@@ -1245,9 +1255,21 @@ Subtitles
             options. Requires a modified libass, can break rendering easily.
             Probably more reliable than ``force``.
 
-``--ass-use-margins``
+``--ass-force-margins``
+    Enables placing toptitles and subtitles in black borders when they are
+    available, if the subtitles are in the ASS format.
+
+    Default: no.
+
+``--sub-use-margins``
     Enables placing toptitles and subtitles in black borders when they are
-    available.
+    available, if the subtitles are in a plain text format  (or ASS if
+    ``--ass-style-override`` is set high enough).
+
+    Default: yes.
+
+    Renamed from ``--ass-use-margins``. To place ASS subtitles in the borders
+    too (like the old option did), also add ``--ass-force-margins``.
 
 ``--ass-vsfilter-aspect-compat=<yes|no>``
     Stretch SSA/ASS subtitles when playing anamorphic videos for compatibility
diff --git a/DOCS/man/vf.rst b/DOCS/man/vf.rst
index bfc6e5d53d..7c31e4d6d5 100644
--- a/DOCS/man/vf.rst
+++ b/DOCS/man/vf.rst
@@ -445,9 +445,9 @@ Available filters are:
 
     ``<bottom-margin>``
         Adds a black band at the bottom of the frame. The SSA/ASS renderer can
-        place subtitles there (with ``--ass-use-margins``).
+        place subtitles there (with ``--sub-use-margins``).
     ``<top-margin>``
-        Black band on the top for toptitles  (with ``--ass-use-margins``).
+        Black band on the top for toptitles  (with ``--sub-use-margins``).
 
     .. admonition:: Examples