command: change "edition" property behavior

See manpage/changelog changes.

The purpose of this change is to removes another case of inconsistent
property behavior. At first I wanted to make this go through deprecation
before making a technically incompatible change, but then I considered
this feature too obscure as that anyone would care.

2 files changed, 17 insertions, 5 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 59e00130c4..e3f197ab33 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -62,6 +62,11 @@ Interface changes
     - remove old Apple Remote support, including --input-appleremote
     - add MediaPlayer support and remove the old Media Key event tap on macOS.
       this possibly also re-adds the Apple Remote support
+    - the "edition" property now strictly returns the value of the option,
+      instead of the runtime value. The new "current-edition" property needs to
+      be queried to read the runtime-chosen edition. This is a breaking change
+      for any users which expected "edition" to return the runtime-chosen
+      edition at default settings (--edition=auto).
  --- mpv 0.30.0 ---
     - add `--d3d11-output-format` to enable explicit selection of a D3D11
       swap chain format.
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 3d9263ee3f..fbfede5869 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -1525,6 +1525,18 @@ Property list
     Current MKV edition number. Setting this property to a different value will
     restart playback. The number of the first edition is 0.
 
+    Before mpv 0.31.0, this showed the actual edition selected at runtime, if
+    you didn't set the option or property manually. With mpv 0.31.0 and later,
+    this strictly returns the user-set option or property value, and the
+    ``current-edition`` property was added to return the runtime selected
+    edition (this matters with ``--edition=auto``, the default).
+
+``current-edition``
+    Currently selected edition. This property is unavailable if no file is
+    loaded, or the file has no editions. (Matroska files make a difference
+    between having no editions and a single edition, which will be reflected by
+    the property, although in practice it does not matter.)
+
 ``chapters``
     Number of chapters.
 
@@ -2714,11 +2726,6 @@ caveats with some properties (due to historical reasons):
     *iff* video (for ``vf``) or audio (for ``af``) was active. If playback was
     not active, the behavior was the same as the current behavior.
 
-``edition``
-    While a file is loaded, the property will always return the effective
-    edition, and setting the ``auto`` value will show somewhat strange behavior
-    (the property eventually switching to whatever is the default edition).
-
 ``playlist``
     The property is read-only and returns the current internal playlist. The
     option is for loading playlist during command line parsing. For client API