options: rename/deprecate --playlist-pos

Conflicts with the "playlist-pos" property. They're really a bit too
different, and since the --playlist-pos option is relatively new and
obscure, just rename it to get this out of the way.

3 files changed, 7 insertions, 10 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index a5c141d953..339b7ffd9e 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -63,6 +63,7 @@ Interface changes
     - deprecate the ao and vo auto-profiles (they never made any sense)
     - deprecate "--vo=direct3d_shaders" - use "--vo=direct3d" instead.
       Change "--vo=direct3d" to always use shaders by default.
+    - deprecate --playlist-pos option, renamed to --playlist-start
     - incompatible change to cdda:// protocol options: the part after cdda://
       now always sets the device, not the span or speed to be played. No
       separating extra "/" is needed. The hidden --cdda-device options is also
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index c7c7c0d887..e626b1ba81 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -2122,12 +2122,6 @@ caveats with some properties (due to historical reasons):
     option is for loading playlist during command line parsing. For client API
     uses, you should use the ``loadlist`` command instead.
 
-``playlist-pos``
-    The property refuses setting out of range values, restarts playback
-    immediately when writing to it, and does not know the ``no`` value (which
-    the option uses to indicate the default state, that is resuming a file
-    on the playlist and jumping to that instead of entry 0).
-
 ``audio-file``, ``sub-file``, ``external-file``
     These options/properties are actually lists of filenames. To make the
     command-line interface easier, each ``--audio-file=...`` option appends
@@ -2141,7 +2135,7 @@ caveats with some properties (due to historical reasons):
     Strictly speaking, option access via API (e.g. ``mpv_set_option_string()``)
     has the same problem, and it's only a difference between CLI/API.
 
-``demuxer``, ``idle``, ``length``, ``audio-samplerate``, ``audio-channels``, ``audio-format``, ``fps``, ``cache``
+``demuxer``, ``idle``, ``length``, ``audio-samplerate``, ``audio-channels``, ``audio-format``, ``fps``, ``cache``, ``playlist-pos``
     These behave completely different as property, but are deprecated (newer
     aliases which don't conflict have been added). After the deprecation period
     they will be changed to the proper option behavior.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index cefd12eae5..349d948834 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -157,17 +157,19 @@ Playback Control
 
     See also: ``--start``.
 
-``--playlist-pos=<no|index>``
+``--playlist-start=<auto|index>``
     Set which file on the internal playlist to start playback with. The index
-    is an integer, with 0 meaning the first file. The value ``no`` means that
+    is an integer, with 0 meaning the first file. The value ``auto`` means that
     the selection of the entry to play is left to the playback resume mechanism
     (default). If an entry with the given index doesn't exist, the behavior is
     unspecified and might change in future mpv versions. The same applies if
     the playlist contains further playlists (don't expect any reasonable
     behavior). Passing a playlist file to mpv should work with this option,
-    though. E.g. ``mpv playlist.m3u --playlist-pos=123`` will work as expected,
+    though. E.g. ``mpv playlist.m3u --playlist-start=123`` will work as expected,
     as long as ``playlist.m3u`` does not link to further playlists.
 
+    The value ``no`` is a deprecated alias for ``auto``.
+
 ``--playlist=<filename>``
     Play files according to a playlist file (Supports some common formats. If
     no format is detected, it will be treated as list of files, separated by