client API: deprecate some events

Following the discussion in #1253.

The events won't be removed for a while, though. (Or maybe never, unless
we run out of bits for the uint64_t event mask.)

This is not a real change (the events still work, and the alternative
mechanisms were established a few API revisions earlier), but for the
sake of notifying API users, update DOCS/client-api-changes.rst.

DOCS/client-api-changes.rst

@@ -31,6 +31,15 @@ API changes
         - add --stop-playback-on-init-failure option, and make it the default
           behavior for libmpv only
         - add qthelper.hpp set_option_variant()
+        - mark the following events as deprecated:
+            MPV_EVENT_TRACKS_CHANGED
+            MPV_EVENT_TRACK_SWITCHED
+            MPV_EVENT_PAUSE
+            MPV_EVENT_UNPAUSE
+            MPV_EVENT_METADATA_UPDATE
+            MPV_EVENT_CHAPTER_CHANGE
+          They are handled better with mpv_observe_property() as mentioned in
+          the documentation comments. They are not removed and still work.
  1.8    - add qthelper.hpp
  1.7    - add mpv_command_node(), mpv_command_node_async()
  1.6    - modify "core-idle" property behavior

DOCS/man/lua.rst

@@ -648,28 +648,11 @@ List of events
 ``playback-restart``
     Start of playback after seek or after file was loaded.
 
-``tracks-changed``
-    The list of video/audio/sub tracks was updated. (This happens on playback
-    start, and very rarely during playback.)
-
-``track-switched``
-    A video/audio/subtitle track was switched on or off. This usually happens
-    when the user (or a script) changes the subtitle track and so on.
-
 ``idle``
     Idle mode is entered. This happens when playback ended, and the player was
     started with ``--idle`` or ``--force-window``. This mode is implicitly ended
     when the ``start-file`` or ``shutdown`` events happen.
 
-``pause``
-    Playback was paused. This also happens when for example the player is
-    paused on low network cache. Then the event type indicates the pause state
-    (like the property "pause" as opposed to the "core-idle" property), and you
-    might receive multiple ``pause`` events in a row.
-
-``unpause``
-    Playback was unpaused. See above for details.
-
 ``tick``
     Called after a video frame was displayed. This is a hack, and you should
     avoid using it. Use timers instead and maybe watch pausing/unpausing events
@@ -729,11 +712,9 @@ List of events
 ``audio-reconfig``
     Happens on audio output or filter reconfig.
 
-``metadata-update``
-    Metadata (like file tags) was updated.
-
-``chapter-change``
-    The current chapter possibly changed.
+The following events also happen, but are deprecated: ``tracks-changed``,
+``track-switched``, ``pause``, ``unpause``, ``metadata-update``,
+``chapter-change``. Use ``mp.observe_property()`` instead.
 
 Extras
 ------