Documentation work

docs/cmd_automap.rst

@@ -19,10 +19,19 @@ episodes are considered candidates. Otherwise, only those episodes specified
 are considered.
 
 If no title numbers are specified, all titles on the disc are considered
-candidates. Otherwise, only the titles specified are considered. If title
-mapping fails, chapter-based mapping is attempted instead.
+candidates. Otherwise, only the titles specified are considered.
+
+The algorithm relies on the :doc:`var_duration` being correctly set. It
+attempts to match unripped titles on the disc which fit within the duration
+range to unripped episodes in the current season. If this "title mapping"
+fails, "chapter mapping" is attempted instead. This finds the longest title on
+the disc, and attempts to find sequences of chapters within that title which
+match the specified duration range for the given episodes (all episodes by
+default). This often results in an ambiguous set of solutions, in which case
+you will be prompted to play certain chapters and answer if they correspond to
+the start of an episode.
 
 The current episode mapping can be viewed in the output of the :doc:`cmd_map`
 command.
 
-See also :doc:`cmd_map`, :doc:`cmd_unmap`
+See also :doc:`cmd_map`, :doc:`cmd_unmap`, :doc:`cmd_season`, :doc:`var_duration`

docs/cmd_map.rst

@@ -23,6 +23,17 @@ For example::
     (tvrip) map 7 4
     (tvrip) map 5 2.1-12
 
-If no arguments are specified, the current episode map will be displayed.
+If no arguments are specified, the current episode map will be displayed. For
+example::
+
+    (tvrip) map
+    Episode Mapping for The Boys season 2:
+
+    ╭───────┬──────────┬────────┬─────────┬───────────────────────────────────╮
+    │ Title │ Duration │ Ripped │ Episode │ Name                              │
+    ├───────┼──────────┼────────┼─────────┼───────────────────────────────────┤
+    │ 1     │  0:52:05 │        │       7 │ Butcher, Baker, Candlestick Maker │
+    │ 2     │  1:04:30 │        │       8 │ What I Know                       │
+    ╰───────┴──────────┴────────┴─────────┴───────────────────────────────────╯
 
 See also :doc:`cmd_automap`, :doc:`cmd_unmap`

docs/cmd_rip.rst

@@ -14,14 +14,12 @@ rip
 
 The ``rip`` command begins ripping the mapped titles from the current source
 device, converting them according to the current preferences, and storing the
-results in the target path. Only previously unripped episodes will be ripped.
-If you wish to re-rip an episode, use the :doc:`cmd_unrip` command to set it to
-unripped first.
-
-You can specify a list of episodes to rip only a subset of the map. This is
-useful to adjust ripping configurations between episodes. Note that already
-ripped episodes will not be re-ripped even if manually specified. Use
-:doc:`cmd_unrip` first.
+results in the target path.
+
+You can specify a list of episodes to rip a subset of the map. This is useful
+to adjust ripping configurations between episodes. Note that already ripped
+episodes will not be re-ripped even if manually specified. Use :doc:`cmd_unrip`
+first.
 
 If no episodes are specified, all unripped episodes in the map will be ripped.
 Examples::

docs/var_api_key.rst

@@ -16,7 +16,7 @@ Sets the API key for use with the service specified by :doc:`var_api`. This is
 used by tvrip to look up episode information for new programs and seasons. By
 default this is blank (represented by a single dash "-") meaning the default
 key for the service (if any) is used. If no default key is available, all entry
-or program, season, and episode information is manual.
+of program, season, and episode information is manual.
 
 If a default key is available, or this is set to a valid value, starting a new
 program or season (with :doc:`cmd_program` or :doc:`cmd_season`) will query the