[doc, cleanup] Re-indent "Usage and Options" section

yt_dlp/options.py

@@ -134,10 +134,8 @@ class _YoutubeDLHelpFormatter(optparse.IndentedHelpFormatter):
     def __init__(self):
         # No need to wrap help messages if we're on a wide console
         max_width = compat_get_terminal_size().columns or 80
-        # 47% is chosen because that is how README.md is currently formatted
+        # The % is chosen to get a pretty output in README.md
-        # and moving help text even further to the right is undesirable.
+        super().__init__(width=max_width, max_help_position=int(0.45 * max_width))
-        # This can be reduced in the future to get a prettier output
-        super().__init__(width=max_width, max_help_position=int(0.47 * max_width))
 
     @staticmethod
     def format_option_strings(option):
@@ -345,7 +343,12 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
     general.add_option(
         '--default-search',
         dest='default_search', metavar='PREFIX',
-        help='Use this prefix for unqualified URLs. For example "gvsearch2:" downloads two videos from google videos for the search term "large apple". Use the value "auto" to let yt-dlp guess ("auto_warning" to emit a warning when guessing). "error" just throws an error. The default value "fixup_error" repairs broken URLs, but emits an error if this is not possible instead of searching')
+        help=(
+            'Use this prefix for unqualified URLs. '
+            'Eg: "gvsearch2:python" downloads two videos from google videos for the search term "python". '
+            'Use the value "auto" to let yt-dlp guess ("auto_warning" to emit a warning when guessing). '
+            '"error" just throws an error. The default value "fixup_error" repairs broken URLs, '
+            'but emits an error if this is not possible instead of searching'))
     general.add_option(
         '--ignore-config', '--no-config',
         action='store_true', dest='ignoreconfig',
@@ -439,10 +442,8 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
         '--proxy', dest='proxy',
         default=None, metavar='URL',
         help=(
-            'Use the specified HTTP/HTTPS/SOCKS proxy. To enable '
+            'Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS proxy, specify a proper scheme. '
-            'SOCKS proxy, specify a proper scheme. For example '
+            'Eg: socks5://user:pass@127.0.0.1:1080/. Pass in an empty string (--proxy "") for direct connection'))
-            'socks5://user:pass@127.0.0.1:1080/. Pass in an empty string (--proxy "") '
-            'for direct connection'))
     network.add_option(
         '--socket-timeout',
         dest='socket_timeout', type=float, default=None, metavar='SECONDS',
@@ -550,7 +551,7 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
         '--match-filters',
         metavar='FILTER', dest='match_filter', action='append',
         help=(
-            'Generic video filter. Any field (see "OUTPUT TEMPLATE") can be compared with a '
+            'Generic video filter. Any "OUTPUT TEMPLATE" field can be compared with a '
             'number or a string using the operators defined in "Filtering formats". '
             'You can also simply specify a field to match if the field is present, '
             'use "!field" to check if the field is not present, and "&" to check multiple conditions. '
@@ -559,7 +560,7 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
             '!is_live --match-filter "like_count>?100 & description~=\'(?i)\\bcats \\& dogs\\b\'" '
             'matches only videos that are not live OR those that have a like count more than 100 '
             '(or the like field is not available) and also has a description '
-            'that contains the phrase "cats & dogs" (ignoring case). '
+            'that contains the phrase "cats & dogs" (caseless). '
             'Use "--match-filter -" to interactively ask whether to download each video'))
     selection.add_option(
         '--no-match-filter',
@@ -671,7 +672,7 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
         '--client-certificate-password',
         dest='client_certificate_password', metavar='PASSWORD',
         help='Password for client certificate private key, if encrypted. '
-             'If not provided and the key is encrypted, yt-dlp will ask interactively')
+             'If not provided, and the key is encrypted, yt-dlp will ask interactively')
 
     video_format = optparse.OptionGroup(parser, 'Video Format Options')
     video_format.add_option(
@@ -688,13 +689,11 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
         action='store_true', dest='format_sort_force', metavar='FORMAT', default=False,
         help=(
             'Force user specified sort order to have precedence over all fields, '
-            'see "Sorting Formats" for more details'))
+            'see "Sorting Formats" for more details (Alias: --S-force)'))
     video_format.add_option(
         '--no-format-sort-force',
         action='store_false', dest='format_sort_force', metavar='FORMAT', default=False,
-        help=(
+        help='Some fields have precedence over the user specified sort order (default)')
-            'Some fields have precedence over the user specified sort order (default), '
-            'see "Sorting Formats" for more details'))
     video_format.add_option(
         '--video-multistreams',
         action='store_true', dest='allow_multiple_video_streams', default=None,
@@ -793,14 +792,14 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
     subtitles.add_option(
         '--sub-format',
         action='store', dest='subtitlesformat', metavar='FORMAT', default='best',
-        help='Subtitle format, accepts formats preference, for example: "srt" or "ass/srt/best"')
+        help='Subtitle format; accepts formats preference, Eg: "srt" or "ass/srt/best"')
     subtitles.add_option(
         '--sub-langs', '--srt-langs',
         action='callback', dest='subtitleslangs', metavar='LANGS', type='str',
         default=[], callback=_list_from_options_callback,
         help=(
             'Languages of the subtitles to download (can be regex) or "all" separated by commas. (Eg: --sub-langs "en.*,ja") '
-            'You can prefix the language code with a "-" to exempt it from the requested languages. (Eg: --sub-langs all,-live_chat) '
+            'You can prefix the language code with a "-" to exclude it from the requested languages. (Eg: --sub-langs all,-live_chat) '
             'Use --list-subs for a list of available language tags'))
 
     downloader = optparse.OptionGroup(parser, 'Download Options')
@@ -837,17 +836,18 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
             'default_key': 'http',
         }, help=(
             'An expression for the time to sleep between retries in seconds (optionally) prefixed '
-            'by the type of retry (http (default), fragment, file_access) to apply the sleep to. '
+            'by the type of retry (file_access, fragment, http (default)) to apply the sleep to. '
-            'EXPR can be a number, or of the forms linear=START[:END[:STEP=1]] or exp=START[:END[:BASE=2]]. '
+            'EXPR can be a number, linear=START[:END[:STEP=1]] or exp=START[:END[:BASE=2]]. '
+            'This option can be used multiple times to set the sleep for the different retry types. '
             'Eg: --retry-sleep linear=1::2 --retry-sleep fragment:exp=1:20'))
     downloader.add_option(
         '--skip-unavailable-fragments', '--no-abort-on-unavailable-fragment',
         action='store_true', dest='skip_unavailable_fragments', default=True,
-        help='Skip unavailable fragments for DASH, hlsnative and ISM (default) (Alias: --no-abort-on-unavailable-fragment)')
+        help='Skip unavailable fragments for DASH, hlsnative and ISM downloads (default) (Alias: --no-abort-on-unavailable-fragment)')
     downloader.add_option(
         '--abort-on-unavailable-fragment', '--no-skip-unavailable-fragments',
         action='store_false', dest='skip_unavailable_fragments',
-        help='Abort downloading if a fragment is unavailable (Alias: --no-skip-unavailable-fragments)')
+        help='Abort download if a fragment is unavailable (Alias: --no-skip-unavailable-fragments)')
     downloader.add_option(
         '--keep-fragments',
         action='store_true', dest='keep_fragments', default=False,
@@ -1213,7 +1213,7 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
     filesystem.add_option(
         '--output-na-placeholder',
         dest='outtmpl_na_placeholder', metavar='TEXT', default='NA',
-        help=('Placeholder value for unavailable meta fields in output filename template (default: "%default")'))
+        help=('Placeholder for unavailable fields in "OUTPUT TEMPLATE" (default: "%default")'))
     filesystem.add_option(
         '--autonumber-size',
         dest='autonumber_size', metavar='NUMBER', type=int,
@@ -1436,9 +1436,7 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
     postproc.add_option(
         '--recode-video',
         metavar='FORMAT', dest='recodevideo', default=None,
-        help=(
+        help='Re-encode the video into another format if necessary. The syntax and supported formats are the same as --remux-video')
-            'Re-encode the video into another format if re-encoding is necessary. '
-            'The syntax and supported formats are the same as --remux-video'))
     postproc.add_option(
         '--postprocessor-args', '--ppa',
         metavar='NAME:ARGS', dest='postprocessor_args', default={}, type='str',
@@ -1635,9 +1633,9 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
         '--force-keyframes-at-cuts',
         action='store_true', dest='force_keyframes_at_cuts', default=False,
         help=(
-            'Force keyframes around the chapters before removing/splitting them. '
+            'Force keyframes around chapters when removing/splitting them. '
-            'Requires a re-encode and thus is very slow, but the resulting video '
+            'The resulting video may have fewer artifacts around the cuts, '
-            'may have fewer artifacts around the cuts'))
+            'but is very slow due to needing a re-encode'))
     postproc.add_option(
         '--no-force-keyframes-at-cuts',
         action='store_false', dest='force_keyframes_at_cuts',
@@ -1675,8 +1673,8 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
             'aliases': {'default': ['all']}
         }, help=(
             'SponsorBlock categories to create chapters for, separated by commas. '
-            f'Available categories are all, default(=all), {", ".join(SponsorBlockPP.CATEGORIES.keys())}. '
+            f'Available categories are {", ".join(SponsorBlockPP.CATEGORIES.keys())}, all and default (=all). '
-            'You can prefix the category with a "-" to exempt it. See [1] for description of the categories. '
+            'You can prefix the category with a "-" to exclude it. See [1] for description of the categories. '
             'Eg: --sponsorblock-mark all,-preview [1] https://wiki.sponsor.ajay.app/w/Segment_Categories'))
     sponsorblock.add_option(
         '--sponsorblock-remove', metavar='CATS',
@@ -1697,9 +1695,9 @@ def _alias_callback(option, opt_str, value, parser, opts, nargs):
         '--sponsorblock-chapter-title', metavar='TEMPLATE',
         default=DEFAULT_SPONSORBLOCK_CHAPTER_TITLE, dest='sponsorblock_chapter_title',
         help=(
-            'The title template for SponsorBlock chapters created by --sponsorblock-mark. '
+            'An output template for the title of the SponsorBlock chapters created by --sponsorblock-mark. '
-            'The same syntax as the output template is used, but the only available fields are '
+            'The only available fields are start_time, end_time, category, categories, name, category_names. '
-            'start_time, end_time, category, categories, name, category_names. Defaults to "%default"'))
+            'Defaults to "%default"'))
     sponsorblock.add_option(
         '--no-sponsorblock', default=False,
         action='store_true', dest='no_sponsorblock',