options: deprecate --loop

Also "announce" the plans to undeprecate it with changed semantics
later. The deprecation period is needed to warn script authors and
client API users (etc.) of the change.

This is done because everyone seems to expect --loop to loop the current
file, not the playlist. Even in cases when only 1 file is on the
playlist, the --loop-file semantics seem to be preferred.

5 files changed, 26 insertions, 10 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 0584409eb9..f3605016a8 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -41,6 +41,8 @@ Interface changes
       support for lavfi filters still has some differences, such as how strings
       are escaped.) If this happens, the non-deprecated builtin filters might be
       moved to "somewhere else" syntax-wise.
+    - deprecate --loop - after a deprecation period, it will be undeprecated,
+      but changed to alias --loop-file
  --- mpv 0.24.0 ---
     - deprecate --hwdec-api and replace it with --opengl-hwdec-interop.
       The new option accepts both --hwdec values, as well as named backends.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 1a5bd637b7..ecf8d8ada3 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -134,17 +134,22 @@ Playback Control
     speed higher than normal automatically inserts the ``scaletempo`` audio
     filter.
 
-``--loop=<N|inf|force|no>``, ``--loop``
+``--loop-playlist=<N|inf|force|no>``, ``--loop-playlist``
     Loops playback ``N`` times. A value of ``1`` plays it one time (default),
     ``2`` two times, etc. ``inf`` means forever. ``no`` is the same as ``1`` and
     disables looping. If several files are specified on command line, the
-    entire playlist is looped. ``--loop`` is the same as ``--loop=inf``.
+    entire playlist is looped. ``--loop-playlist`` is the same as
+    ``--loop-playlist=inf``.
 
     The ``force`` mode is like ``inf``, but does not skip playlist entries
     which have been marked as failing. This means the player might waste CPU
     time trying to loop a file that doesn't exist. But it might be useful for
     playing webradios under very bad network conditions.
 
+``--loop``
+    Currently a deprecated alias to ``--loop-playlist``. After a deprecation
+    period, it will be undeprecated, but changed to alias ``--loop-file``.
+
 ``--pause``
     Start the player in paused state.
 
diff --git a/options/m_config.c b/options/m_config.c
index 14aa56da51..16a0b38eb1 100644
--- a/options/m_config.c
+++ b/options/m_config.c
@@ -624,12 +624,16 @@ struct m_config_option *m_config_get_co(const struct m_config *config,
     const char *prefix = config->is_toplevel ? "--" : "";
     if (co->opt->type == &m_option_type_alias) {
         const char *alias = (const char *)co->opt->priv;
-        // deprecation_message is not used, but decides whether it's a
-        // proper or deprecated alias.
         if (co->opt->deprecation_message && !co->warning_was_printed) {
-            MP_WARN(config, "Warning: option %s%s was replaced with "
-                    "%s%s and might be removed in the future.\n",
-                    prefix, co->name, prefix, alias);
+            if (co->opt->deprecation_message[0]) {
+                MP_WARN(config, "Warning: option %s%s was replaced with "
+                        "%s%s: %s\n", prefix, co->name, prefix, alias,
+                        co->opt->deprecation_message);
+            } else {
+                MP_WARN(config, "Warning: option %s%s was replaced with "
+                        "%s%s and might be removed in the future.\n",
+                        prefix, co->name, prefix, alias);
+            }
             co->warning_was_printed = true;
         }
         return m_config_get_co(config, bstr0(alias));
diff --git a/options/m_option.h b/options/m_option.h
index f3a4e7bc1e..064b7f83b1 100644
--- a/options/m_option.h
+++ b/options/m_option.h
@@ -715,9 +715,12 @@ extern const char m_option_path_separator;
 
 // If "--optname" was removed, but "--newname" has the same semantics.
 // It will be redirected, and a warning will be printed on first use.
-#define OPT_REPLACED(optname, newname) \
+#define OPT_REPLACED_MSG(optname, newname, msg) \
     {.name = optname, .type = &m_option_type_alias, .priv = newname, \
-     .deprecation_message = "", .offset = -1}
+     .deprecation_message = (msg), .offset = -1}
+
+// Same, with a generic deprecation message.
+#define OPT_REPLACED(optname, newname) OPT_REPLACED_MSG(optname, newname, "")
 
 // "--optname" doesn't exist, but inform the user about a replacement with msg.
 #define OPT_REMOVED(optname, msg) \
diff --git a/options/options.c b/options/options.c
index 5333cf406c..c595964121 100644
--- a/options/options.c
+++ b/options/options.c
@@ -607,7 +607,7 @@ const m_option_t mp_opts[] = {
 
     OPT_FLAG("stop-playback-on-init-failure", stop_playback_on_init_failure, 0),
 
-    OPT_CHOICE_OR_INT("loop", loop_times, 0, 1, 10000,
+    OPT_CHOICE_OR_INT("loop-playlist", loop_times, 0, 1, 10000,
                       ({"no", 1},
                        {"inf", -1}, {"yes", -1},
                        {"force", -2})),
@@ -832,6 +832,8 @@ const m_option_t mp_opts[] = {
     OPT_REPLACED("ass-style-override", "sub-ass-style-override"),
     OPT_REPLACED("ass-scale-with-window", "sub-ass-scale-with-window"),
     OPT_REMOVED("fs-black-out-screens", NULL),
+    OPT_REPLACED_MSG("loop", "loop-playlist", "--loop will be changed to map to"
+        " --loop-file in future releases."),
 
     {0}
 };