DOCS/{mpv,options}: document the watch later functionality

This adds a section to the documentation to explain how resuming
playback works, and in particular it explains how it affects which
playlist entry mpv starts playing from, since this feature was only
implied in the --playlist-start documentation.

It also groups the documentation of the watch later options together to
make them easier to find.

3 files changed, 99 insertions, 67 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 05b0c806d3..d5eecbb479 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -672,7 +672,7 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
 ``quit-watch-later [<code>]``
     Exit player, and store current playback position. Playing that file later
     will seek to the previous position on start. The (optional) argument is
-    exactly as in the ``quit`` command.
+    exactly as in the ``quit`` command. See `RESUMING PLAYBACK`_.
 
 ``sub-add <url> [<flags> [<title> [<lang>]]]``
     Load the given subtitle file or stream. By default, it is selected as
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 341f97924a..896c0fda00 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -107,7 +107,8 @@ q
 
 Q
     Like ``q``, but store the current playback position. Playing the same file
-    later will resume at the old playback position if possible.
+    later will resume at the old playback position if possible. See
+    `RESUMING PLAYBACK`_.
 
 / and *
     Decrease/increase volume.
@@ -1088,6 +1089,33 @@ Additional options that can be tried:
 - without audio ``--framedrop=no --speed=1.01`` may help for live sources
   (results can be mixed)
 
+RESUMING PLAYBACK
+=================
+
+mpv is capable of storing the playback position of the currently playing file
+and resume from there the next time that file is played. This is done with the
+commands ``quit-watch-later`` (bound to Shift+Q by default) and
+``write-watch-later-config``, and with the ``--save-position-on-quit`` option.
+
+The difference between always quitting with a key bound to ``quit-watch-later``
+and using ``--save-position-on-quit`` is that the latter will save the playback
+position even when mpv is closed with a method other than a keybinding, for
+example if you shutdown your system without closing mpv beforehand, unless of
+course mpv is terminated abruptly and doesn't have the time to save (e.g. with
+the KILL Unix signal).
+
+mpv also stores options other than the playback position when they have been
+modified after playback began, for example the volume and the fullscreen state,
+and restores their values the next time the file is played. Which options are
+saved can be configured with the ``--watch-later-options`` option.
+
+When playing multiple playlist entries, mpv checks if one them has a resume
+config file associated, and if it finds one it restarts playback from it. For
+example, if you use ``quit-watch-later`` on the 5th episode of a show, and
+later play all the episodes, mpv will automatically resume playback from
+episode 5.
+
+More options to configure this functionality are listed in `Watch Later`_.
 
 PROTOCOLS
 =========
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index f895fe2ecc..f574a20b1d 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -746,23 +746,6 @@ Program Behavior
 
     Note that the ``--no-config`` option takes precedence over this option.
 
-``--save-position-on-quit``
-    Always save the current playback position on quit. When this file is
-    played again later, the player will seek to the old playback position on
-    start. This does not happen if playback of a file is stopped in any other
-    way than quitting. For example, going to the next file in the playlist
-    will not save the position, and start playback at beginning the next time
-    the file is played.
-
-    This behavior is disabled by default, but is always available when quitting
-    the player with Shift+Q.
-
-``--watch-later-directory=<path>``
-    The directory in which to store the "watch later" temporary files.
-
-    The default is a subdirectory named "watch_later" underneath the
-    config directory (usually ``~/.config/mpv/``).
-
 ``--dump-stats=<filename>``
     Write certain statistics to the given file. The file is truncated on
     opening. The file will contain raw samples, each with a timestamp. To
@@ -804,18 +787,6 @@ Program Behavior
     Pretend that all files passed to mpv are concatenated into a single, big
     file. This uses timeline/EDL support internally.
 
-``--no-resume-playback``
-    Do not restore playback position from the ``watch_later`` configuration
-    subdirectory (usually ``~/.config/mpv/watch_later/``).
-    See ``quit-watch-later`` input command.
-
-``--resume-playback-check-mtime``
-    Only restore the playback position from the ``watch_later`` configuration
-    subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's
-    modification time is the same as at the time of saving. This may prevent
-    skipping forward in files with the same name which have different content.
-    (Default: ``no``)
-
 ``--profile=<profile1,profile2,...>``
     Use the given profile(s), ``--profile=help`` displays a list of the
     defined profiles.
@@ -851,42 +822,6 @@ Program Behavior
         - ``--reset-on-next-file=all``
           Try to reset all settings that were changed during playback.
 
-``--watch-later-options=option1,option2,...``
-    The options that are saved in "watch later" files if they have been changed
-    since when mpv started. These values will be restored the next time the
-    files are played. The playback position is always saved as ``start``, so
-    adding ``start`` to this list has no effect.
-
-    When removing options, existing watch later data won't be modified and will
-    still be applied fully, but new watch later data won't contain these
-    options.
-
-    This is a string list option. See `List Options`_ for details.
-
-    .. admonition:: Examples
-
-        - ``--watch-later-options-remove=fullscreen``
-          The fullscreen state won't be saved to watch later files.
-        - ``--watch-later-options-remove=volume``
-          ``--watch-later-options-remove=mute``
-          The volume and mute state won't be saved to watch later files.
-        - ``--watch-later-options-clr``
-          No option will be saved to watch later files except the starting
-          position.
-
-``--write-filename-in-watch-later-config``
-    Prepend the watch later config files with the name of the file they refer
-    to. This is simply written as comment on the top of the file.
-
-    .. warning::
-
-        This option may expose privacy-sensitive information and is thus
-        disabled by default.
-
-``--ignore-path-in-watch-later-config``
-    Ignore path (i.e. use filename only) when using watch later feature.
-    (Default: disabled)
-
 ``--show-profile=<profile>``
     Show the description and content of a profile. Lists all profiles if no
     parameter is provided.
@@ -1062,6 +997,75 @@ Program Behavior
     only by mpv internally, or mpv-provided scripts, config files, or .desktop
     files. See `PSEUDO GUI MODE`_ for details.
 
+Watch Later
+-----------
+
+``--save-position-on-quit``
+    Always save the current playback position on quit. When this file is
+    played again later, the player will seek to the old playback position on
+    start. This does not happen if playback of a file is stopped in any other
+    way than quitting. For example, going to the next file in the playlist
+    will not save the position, and start playback at beginning the next time
+    the file is played.
+
+    This behavior is disabled by default, but is always available when quitting
+    the player with Shift+Q.
+
+    See `RESUMING PLAYBACK`_.
+
+``--watch-later-directory=<path>``
+    The directory in which to store the "watch later" temporary files.
+
+    The default is a subdirectory named "watch_later" underneath the
+    config directory (usually ``~/.config/mpv/``).
+
+``--no-resume-playback``
+    Do not restore playback position from the ``watch_later`` configuration
+    subdirectory (usually ``~/.config/mpv/watch_later/``).
+
+``--resume-playback-check-mtime``
+    Only restore the playback position from the ``watch_later`` configuration
+    subdirectory (usually ``~/.config/mpv/watch_later/``) if the file's
+    modification time is the same as at the time of saving. This may prevent
+    skipping forward in files with the same name which have different content.
+    (Default: ``no``)
+
+``--watch-later-options=option1,option2,...``
+    The options that are saved in "watch later" files if they have been changed
+    since when mpv started. These values will be restored the next time the
+    files are played. The playback position is always saved as ``start``, so
+    adding ``start`` to this list has no effect.
+
+    When removing options, existing watch later data won't be modified and will
+    still be applied fully, but new watch later data won't contain these
+    options.
+
+    This is a string list option. See `List Options`_ for details.
+
+    .. admonition:: Examples
+
+        - ``--watch-later-options-remove=fullscreen``
+          The fullscreen state won't be saved to watch later files.
+        - ``--watch-later-options-remove=volume``
+          ``--watch-later-options-remove=mute``
+          The volume and mute state won't be saved to watch later files.
+        - ``--watch-later-options-clr``
+          No option will be saved to watch later files except the starting
+          position.
+
+``--write-filename-in-watch-later-config``
+    Prepend the watch later config files with the name of the file they refer
+    to. This is simply written as comment on the top of the file.
+
+    .. warning::
+
+        This option may expose privacy-sensitive information and is thus
+        disabled by default.
+
+``--ignore-path-in-watch-later-config``
+    Ignore path (i.e. use filename only) when using watch later feature.
+    (Default: disabled)
+
 Video
 -----