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.

1 files changed, 7 insertions, 2 deletions

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.