[documentation] Add deprecated options and aliases in readme

README.md

@@ -47,6 +47,7 @@ # YT-DLP
     * [Sorting Formats](#sorting-formats)
     * [Format Selection examples](#format-selection-examples)
 * [PLUGINS](#plugins)
+* [DEPRECATED OPTIONS](#deprecated-options)
 * [MORE](#more)
 
 
@@ -471,7 +472,8 @@ ## Verbosity and Simulation Options:
     --no-warnings                    Ignore warnings
     -s, --simulate                   Do not download the video and do not write
                                      anything to disk
-    --skip-download                  Do not download the video
+    --skip-download                  Do not download the video but write all
+                                     related files (Alias: --no-download)
     -g, --get-url                    Simulate, quiet but print URL
     -e, --get-title                  Simulate, quiet but print title
     --get-id                         Simulate, quiet but print id
@@ -508,7 +510,7 @@ ## Workarounds:
     --encoding ENCODING              Force the specified encoding (experimental)
     --no-check-certificate           Suppress HTTPS certificate validation
     --prefer-insecure                Use an unencrypted connection to retrieve
-                                     information about the video. (Currently
+                                     information about the video (Currently
                                      supported only for YouTube)
     --user-agent UA                  Specify a custom user agent
     --referer URL                    Specify a custom referer, use if the video
@@ -522,15 +524,11 @@ ## Workarounds:
     --sleep-requests SECONDS         Number of seconds to sleep between requests
                                      during data extraction
     --sleep-interval SECONDS         Number of seconds to sleep before each
-                                     download when used alone or a lower bound
+                                     download. This is the minimum time to sleep
-                                     of a range for randomized sleep before each
+                                     when used along with --max-sleep-interval
-                                     download (minimum possible number of
+                                     (Alias: --min-sleep-interval)
-                                     seconds to sleep) when used along with
+    --max-sleep-interval SECONDS     Maximum number of seconds to sleep. Can
-                                     --max-sleep-interval
+                                     only be used along with --min-sleep-interval
-    --max-sleep-interval SECONDS     Upper bound of a range for randomized sleep
-                                     before each download (maximum possible
-                                     number of seconds to sleep). Must only be
-                                     used along with --min-sleep-interval
     --sleep-subtitles SECONDS        Number of seconds to sleep before each
                                      subtitle download
 
@@ -580,16 +578,16 @@ ## Subtitle Options:
     --write-subs                     Write subtitle file
     --no-write-subs                  Do not write subtitle file (default)
     --write-auto-subs                Write automatically generated subtitle file
-                                     (YouTube only)
+                                     (Alias: --write-automatic-subs)
-    --no-write-auto-subs             Do not write automatically generated
+    --no-write-auto-subs             Do not write auto-generated subtitles
-                                     subtitle file (default)
+                                     (default) (Alias: --no-write-automatic-subs)
     --all-subs                       Download all the available subtitles of the
                                      video
     --list-subs                      List all available subtitles for the video
     --sub-format FORMAT              Subtitle format, accepts formats
                                      preference, for example: "srt" or
                                      "ass/srt/best"
-    --sub-lang LANGS                 Languages of the subtitles to download
+    --sub-langs LANGS                Languages of the subtitles to download
                                      (optional) separated by commas, use --list-
                                      subs for available language tags
 
@@ -699,8 +697,9 @@ ## Post-Processing Options:
                                      downloading and post-processing, similar to
                                      find's -exec syntax. Example: --exec 'adb
                                      push {} /sdcard/Music/ && rm {}'
-    --convert-subs FORMAT            Convert the subtitles to other format
+    --convert-subs FORMAT            Convert the subtitles to another format
                                      (currently supported: srt|ass|vtt|lrc)
+                                     (Alias: --convert-subtitles)
     --split-chapters                 Split video into multiple files based on
                                      internal chapters. The "chapter:" prefix
                                      can be used with "--paths" and "--output"
@@ -1203,5 +1202,39 @@ # PLUGINS
 
 **Note**: `<root-dir>` is the directory of the binary (`<root-dir>/yt-dlp`), or the root directory of the module if you are running directly from source-code (`<root dir>/yt_dlp/__main__.py`)
 
+# DEPRECATED OPTIONS
+
+These are all the deprecated options and the current alternative to achieve the same effect
+
+    --cn-verification-proxy URL      --geo-verification-proxy URL
+    --id                             -o "%(id)s.%(ext)s"
+    -A, --auto-number                -o "%(autonumber)s-%(id)s.%(ext)s"
+    -t, --title                      -o "%(title)s-%(id)s.%(ext)s"
+    -l, --literal                    -o accepts literal names
+    --autonumber-size NUMBER         Use string formatting. Eg: %(autonumber)03d
+    --metadata-from-title FORMAT     --parse-metadata "title:FORMAT"
+    --prefer-avconv                  avconv is no longer officially supported (Alias: --no-prefer-ffmpeg)
+    --prefer-ffmpeg                  Default (Alias: --no-prefer-avconv)
+    --avconv-location                avconv is no longer officially supported
+    -C, --call-home                  Not implemented
+    --no-call-home                   Default
+    --write-srt                      --write-subs
+    --no-write-srt                   --no-write-subs
+    --srt-lang LANGS                 --sub-langs LANGS
+    --prefer-unsecure                --prefer-insecure
+    --rate-limit RATE                --limit-rate RATE
+    --force-write-download-archive   --force-write-archive
+    --dump-intermediate-pages        --dump-pages
+    --dump-headers                   --print-traffic
+    --youtube-print-sig-code         No longer supported
+    --trim-file-names LENGTH         --trim-filenames LENGTH
+    --yes-overwrites                 --force-overwrites
+    --load-info                      --load-info-json
+    --split-tracks                   --split-chapters
+    --no-split-tracks                --no-split-chapters
+    --sponskrub-args ARGS            --ppa "sponskrub:ARGS"
+    --test                           Only used for testing extractors
+
+
 # MORE
 For FAQ, Developer Instructions etc., see the [original README](https://github.com/ytdl-org/youtube-dl#faq)

yt_dlp/extractor/common.py

@@ -252,8 +252,8 @@ class InfoExtractor(object):
                         * "data": The subtitles file contents
                         * "url": A URL pointing to the subtitles file
                     "ext" will be calculated from URL if missing
-    automatic_captions: Like 'subtitles', used by the YoutubeIE for
+    automatic_captions: Like 'subtitles'; contains automatically generated
-                    automatically generated captions
+                    captions instead of normal subtitles
     duration:       Length of the video in seconds, as an integer or float.
     view_count:     How many users have watched the video on the platform.
     like_count:     Number of positive ratings of the video

yt_dlp/options.py

@@ -533,11 +533,11 @@ def _dict_from_multiple_values_options_callback(
     subtitles.add_option(
         '--write-auto-subs', '--write-automatic-subs',
         action='store_true', dest='writeautomaticsub', default=False,
-        help='Write automatically generated subtitle file (YouTube only)')
+        help='Write automatically generated subtitle file (Alias: --write-automatic-subs)')
     subtitles.add_option(
         '--no-write-auto-subs', '--no-write-automatic-subs',
         action='store_false', dest='writeautomaticsub', default=False,
-        help='Do not write automatically generated subtitle file (default)')
+        help='Do not write auto-generated subtitles (default) (Alias: --no-write-automatic-subs)')
     subtitles.add_option(
         '--all-subs',
         action='store_true', dest='allsubtitles', default=False,
@@ -551,7 +551,7 @@ def _dict_from_multiple_values_options_callback(
         action='store', dest='subtitlesformat', metavar='FORMAT', default='best',
         help='Subtitle format, accepts formats preference, for example: "srt" or "ass/srt/best"')
     subtitles.add_option(
-        '--sub-lang', '--sub-langs', '--srt-lang',
+        '--sub-langs', '--srt-langs',
         action='callback', dest='subtitleslangs', metavar='LANGS', type='str',
         default=[], callback=_comma_separated_values_options_callback,
         help='Languages of the subtitles to download (optional) separated by commas, use --list-subs for available language tags')
@@ -679,7 +679,7 @@ def _dict_from_multiple_values_options_callback(
     workarounds.add_option(
         '--prefer-insecure', '--prefer-unsecure',
         action='store_true', dest='prefer_insecure',
-        help='Use an unencrypted connection to retrieve information about the video. (Currently supported only for YouTube)')
+        help='Use an unencrypted connection to retrieve information about the video (Currently supported only for YouTube)')
     workarounds.add_option(
         '--user-agent',
         metavar='UA', dest='user_agent',
@@ -707,17 +707,13 @@ def _dict_from_multiple_values_options_callback(
         '--sleep-interval', '--min-sleep-interval', metavar='SECONDS',
         dest='sleep_interval', type=float,
         help=(
-            'Number of seconds to sleep before each download when used alone '
+            'Number of seconds to sleep before each download. '
-            'or a lower bound of a range for randomized sleep before each download '
+            'This is the minimum time to sleep when used along with --max-sleep-interval '
-            '(minimum possible number of seconds to sleep) when used along with '
+            '(Alias: --min-sleep-interval)'))
-            '--max-sleep-interval'))
     workarounds.add_option(
         '--max-sleep-interval', metavar='SECONDS',
         dest='max_sleep_interval', type=float,
-        help=(
+        help='Maximum number of seconds to sleep. Can only be used along with --min-sleep-interval')
-            'Upper bound of a range for randomized sleep before each download '
-            '(maximum possible number of seconds to sleep). Must only be used '
-            'along with --min-sleep-interval'))
     workarounds.add_option(
         '--sleep-subtitles', metavar='SECONDS',
         dest='sleep_interval_subtitles', default=0, type=int,
@@ -739,7 +735,7 @@ def _dict_from_multiple_values_options_callback(
     verbosity.add_option(
         '--skip-download', '--no-download',
         action='store_true', dest='skip_download', default=False,
-        help='Do not download the video')
+        help='Do not download the video but write all related files (Alias: --no-download)')
     verbosity.add_option(
         '-g', '--get-url',
         action='store_true', dest='geturl', default=False,
@@ -982,9 +978,7 @@ def _dict_from_multiple_values_options_callback(
     filesystem.add_option(
         '--no-write-playlist-metafiles',
         action='store_false', dest='allow_playlist_files',
-        help=(
+        help='Do not write playlist metadata when using --write-info-json, --write-description etc.')
-            'Do not write playlist metadata when using '
-            '--write-info-json, --write-description etc.'))
     filesystem.add_option(
         '--clean-infojson',
         action='store_true', dest='clean_infojson', default=True,
@@ -1189,9 +1183,9 @@ def _dict_from_multiple_values_options_callback(
         metavar='CMD', dest='exec_cmd',
         help='Execute a command on the file after downloading and post-processing, similar to find\'s -exec syntax. Example: --exec \'adb push {} /sdcard/Music/ && rm {}\'')
     postproc.add_option(
-        '--convert-subs', '--convert-subtitles',
+        '--convert-subs', '--convert-sub', '--convert-subtitles',
         metavar='FORMAT', dest='convertsubtitles', default=None,
-        help='Convert the subtitles to other format (currently supported: srt|ass|vtt|lrc)')
+        help='Convert the subtitles to another format (currently supported: srt|ass|vtt|lrc) (Alias: --convert-subtitles)')
     postproc.add_option(
         '--split-chapters', '--split-tracks',
         dest='split_chapters', action='store_true', default=False,