CLI: Revise CLI help.

Fixes a number of typos. Better formatting in some cases. Clarifies optional parameter usage (fixes #300).

1 files changed, 303 insertions, 240 deletions

diff --git a/test/test.c b/test/test.c
index b7c755447..e1044faf5 100644
--- a/test/test.c
+++ b/test/test.c
@@ -978,8 +978,7 @@ void SigHandler( int i_signal )
 static void showFilterPresets(FILE* const out, int filter_id)
 {
     char ** names = hb_filter_get_presets_short_name(filter_id);
-    char  * slash = "", * newline;
-    int     ii, count = 0, linelen = 0;
+    int     ii, count = 0;
 
     // Count number of entries we want to display
     for (ii = 0; names[ii] != NULL; ii++)
@@ -996,32 +995,54 @@ static void showFilterPresets(FILE* const out, int filter_id)
     {
         return;
     }
-    fprintf(out, "                           Presets:\n"
-                 "                             <");
+    fprintf(out, "                           Presets:\n");
     for (ii = 0; names[ii] != NULL; ii++)
     {
         if (!strcasecmp(names[ii], "custom") || // skip custom
             !strcasecmp(names[ii], "off")    || // skip off
             !strcasecmp(names[ii], "default"))  // skip default
             continue;
-        int len = strlen(names[ii]) + 1;
-        if (linelen + len > 48)
-        {
-            newline = "\n                              ";
-            linelen = 0;
-        }
-        else
-        {
-            newline = "";
-        }
-        fprintf(out, "%s%s%s", slash, newline, names[ii]);
-        linelen += len;
-        slash = "/";
+        fprintf(out, "                               %s\n", names[ii]);
     }
 
-    fprintf(out, ">\n");
     hb_str_vfree(names);
 }
+static void showFilterTunes(FILE* const out, int filter_id)
+{
+    char ** tunes = hb_filter_get_tunes_short_name(filter_id);
+    int     ii, count = 0;
+
+    // Count number of entries we want to display
+    for (ii = 0; tunes[ii] != NULL; ii++)
+    {
+        /*
+        if (!strcasecmp(tunes[ii], "custom") || // skip custom
+            !strcasecmp(tunes[ii], "off")    || // skip off
+            !strcasecmp(tunes[ii], "default"))  // skip default
+            continue;
+        */
+        count++;
+    }
+
+    // If there are no entries, display nothing.
+    if (count == 0)
+    {
+        return;
+    }
+    fprintf(out, "                           Tunes:\n");
+    for (ii = 0; tunes[ii] != NULL; ii++)
+    {
+        /*
+        if (!strcasecmp(tunes[ii], "custom") || // skip custom
+            !strcasecmp(tunes[ii], "off")    || // skip off
+            !strcasecmp(tunes[ii], "default"))  // skip default
+            continue;
+        */
+        fprintf(out, "                               %s\n", tunes[ii]);
+    }
+
+    hb_str_vfree(tunes);
+}
 
 static void showFilterKeys(FILE* const out, int filter_id)
 {
@@ -1030,14 +1051,14 @@ static void showFilterKeys(FILE* const out, int filter_id)
     int     ii, linelen = 0;
 
     fprintf(out, "                           Custom Format:\n"
-                 "                             <");
+                 "                               ");
     for (ii = 0; keys[ii] != NULL; ii++)
     {
         int c = tolower(keys[ii][0]);
         int len = strlen(keys[ii]) + 3;
         if (linelen + len > 48)
         {
-            newline = "\n                              ";
+            newline = "\n                               ";
             linelen = 0;
         }
         else
@@ -1048,7 +1069,7 @@ static void showFilterKeys(FILE* const out, int filter_id)
         linelen += len;
         colon = ":";
     }
-    fprintf(out, ">\n");
+    fprintf(out, "\n");
     hb_str_vfree(keys);
 }
 
@@ -1057,7 +1078,7 @@ static void showFilterDefault(FILE* const out, int filter_id)
     const char * preset = "default";
 
     fprintf(out, "                           Default:\n"
-                 "                             <");
+                 "                               ");
     switch (filter_id)
     {
         case HB_FILTER_NLMEANS:
@@ -1105,7 +1126,7 @@ static void showFilterDefault(FILE* const out, int filter_id)
                 int len = strlen(split[ii]) + 1;
                 if (linelen + len > 48)
                 {
-                    newline = "\n                              ";
+                    newline = "\n                               ";
                     linelen = 0;
                 }
                 else
@@ -1128,7 +1149,7 @@ static void showFilterDefault(FILE* const out, int filter_id)
         default:
             break;
     }
-    fprintf(out, ">\n");
+    fprintf(out, "\n");
 }
 
 static void ShowHelp()
@@ -1142,36 +1163,42 @@ static void ShowHelp()
     FILE* const out = stdout;
 
     fprintf( out,
-"Syntax: HandBrakeCLI [options] -i <device> -o <file>\n"
+"Usage: HandBrakeCLI [options] -i <source> -o <destination>\n"
+"\n"
+"General Options --------------------------------------------------------------\n"
 "\n"
-"### General Handbrake Options---------------------------------------------\n\n"
 "   -h, --help              Print help\n"
-"   -v, --verbose <#>       Be verbose (optional argument: logging level)\n"
-"   -Z. --preset <string>   Use a built-in preset. Capitalization matters,\n"
-"                           and if the preset name has spaces, surround it\n"
-"                           with double quotation marks\n"
-"   -z, --preset-list       See a list of available built-in presets\n"
-"   --preset-import-file    Import presets from a json preset file.\n"
-"       <filespec>          'filespec' may be a list of files separated\n"
+"   -v, --verbose[=number]  Be verbose (optional argument: logging level)\n"
+"   -Z. --preset <string>   Select preset by name (case-sensitive)\n"
+"                           Enclose names containing spaces in double quotation\n"
+"                           marks (e.g. \"Preset Name\")\n"
+"   -z, --preset-list       List available presets\n"
+"   --preset-import-file <filespec>\n"
+"                           Import presets from a json preset file.\n"
+"                           'filespec' may be a list of files separated\n"
 "                           by spaces, or it may use shell wildcards.\n"
 "   --preset-import-gui     Import presets from GUI config preset file.\n"
-"   --preset-export         Create a new preset from command line options and\n"
-"       <name>              write a json representation of the preset to the\n"
+"   --preset-export <string>\n"
+"                           Create a new preset from command line options and\n"
+"                           write a json representation of the preset to the\n"
 "                           console or a file if '--preset-export-file' is\n"
-"                           specified. The required 'name' argument will be\n"
-"                           the new preset's name.\n"
-"   --preset-export-file    Write new preset generated by '--preset-export'\n"
-"       <filename>          to file 'filename'.\n"
-"   --preset-export-description\n"
-"       <description>       Add a description to the new preset created with\n"
+"                           specified. The required argument will be the name\n"
+"                           of the new preset.\n"
+"   --preset-export-file <filename>\n"
+"                           Write new preset generated by '--preset-export'\n"
+"                           to file 'filename'.\n"
+"   --preset-export-description <string>\n"
+"                           Add a description to the new preset created with\n"
 "                           '--preset-export'\n"
-"   --queue-import-file     Import an encode queue file created by the GUI\n"
-"       <filename>\n"
+"   --queue-import-file <filename>\n"
+"                           Import an encode queue file created by the GUI\n"
 "       --no-dvdnav         Do not use dvdnav for reading DVDs\n"
 "       --no-opencl         Disable use of OpenCL\n"
 "\n"
-"### Source Options--------------------------------------------------------\n\n"
-"   -i, --input <string>    Set input device\n"
+"\n"
+"Source Options ---------------------------------------------------------------\n"
+"\n"
+"   -i, --input <string>    Set input file or device (\"source\")\n"
 "   -t, --title <number>    Select a title to encode (0 to scan all titles\n"
 "                           only, default: 1)\n"
 "       --min-duration      Set the minimum title duration (in seconds).\n"
@@ -1179,101 +1206,113 @@ static void ShowHelp()
 "       --scan              Scan selected title only.\n"
 "       --main-feature      Detect and select the main feature title.\n"
 "   -c, --chapters <string> Select chapters (e.g. \"1-3\" for chapters\n"
-"                           1 to 3, or \"3\" for chapter 3 only,\n"
+"                           1 to 3 or \"3\" for chapter 3 only,\n"
 "                           default: all chapters)\n"
 "       --angle <number>    Select the video angle (DVD or Blu-ray only)\n"
-"       --previews <#:B>    Select how many preview images are generated,\n"
+"       --previews <number:boolean>\n"
+"                           Select how many preview images are generated,\n"
 "                           and whether to store to disk (0 or 1).\n"
 "                           (default: 10:0)\n"
-"   --start-at-preview <#>  Start encoding at a given preview.\n"
-"   --start-at    <unit:#>  Start encoding at a given frame, duration\n"
-"                           (in seconds), or pts (on a 90kHz clock)\n"
-"   --stop-at     <unit:#>  Stop encoding at a given frame, duration\n"
-"                           (in seconds), or pts (on a 90kHz clock)"
+"   --start-at-preview <number>\n"
+"                           Start encoding at a given preview.\n"
+"   --start-at <string:number>\n"
+"                           Start encoding at a given duration (in seconds),\n"
+"                           frame, or pts (on a 90kHz clock)\n"
+"                           (e.g. duration:10, frame:300, pts:900000)\n"
+"   --stop-at  <string:number>\n"
+"                           Stop encoding at a given duration (in seconds),\n"
+"                           frame, or pts (on a 90kHz clock)\n"
+"                           (e.g. duration:10, frame:300, pts:900000)\n"
+"\n"
+"\n"
+"Destination Options ----------------------------------------------------------\n"
 "\n"
-"### Destination Options---------------------------------------------------\n\n"
-"   -o, --output <string>   Set output file name\n"
-"   -f, --format <string>   Set output container format (");
+"   -o, --output <filename> Set destination file name\n"
+"   -f, --format <string>   Select container format:\n");
     container = NULL;
     while ((container = hb_container_get_next(container)) != NULL)
     {
-        fprintf(out, "%s", container->short_name);
-        if (hb_container_get_next(container) != NULL)
-        {
-            fprintf(out, "/");
-        }
-        else
-        {
-            fprintf(out, ")\n");
-        }
+        fprintf(out, "                               %s\n", container->short_name);
     }
     fprintf(out,
-"                           (default: autodetected from file name)\n"
+"                           default: auto-detected from destination file name)\n"
 "   -m, --markers           Add chapter markers\n"
 "       --no-markers        Disable preset chapter markers\n"
-"   -O, --optimize          Optimize mp4 files for HTTP streaming\n"
-"                           (\"fast start\")\n"
+"   -O, --optimize          Optimize MP4 files for HTTP streaming (fast start,\n"
+"                           s.s. rewrite file to place MOOV atom at beginning)\n"
 "       --no-optimize       Disable preset 'optimize'\n"
-"   -I, --ipod-atom         Mark mp4 files so 5.5G iPods will accept them\n"
-"       --no-ipod-atom      Disable 5.5G iPod tag\n"
+"   -I, --ipod-atom         Add iPod 5G compatibility atom to MP4 container\n"
+"       --no-ipod-atom      Disable iPod 5G atom\n"
 "   -P, --use-opencl        Use OpenCL where applicable\n"
 "\n"
-
-
-"### Video Options------------------------------------------------------------\n\n"
-"   -e, --encoder <string>  Set video library encoder\n"
-"                           Options: " );
+"\n"
+"Video Options ----------------------------------------------------------------\n"
+"\n"
+"   -e, --encoder <string>  Select video encoder:\n");
     encoder = NULL;
     while ((encoder = hb_video_encoder_get_next(encoder)) != NULL)
     {
-        fprintf(out, "%s", encoder->short_name);
-        if (hb_video_encoder_get_next(encoder) != NULL)
-        {
-            fprintf(out, "/");
-        }
-        else
-        {
-            fprintf(out, "\n");
-        }
+        fprintf(out, "                               %s\n", encoder->short_name);
     }
     fprintf(out,
-"       --encoder-preset    Adjust video encoding settings for a particular\n"
-"         <string>          speed/efficiency tradeoff (encoder-specific)\n"
-"   --encoder-preset-list   List supported --encoder-preset values for the\n"
-"         <string>          specified video encoder\n"
-"       --encoder-tune      Adjust video encoding settings for a particular\n"
-"         <string>          type of souce or situation (encoder-specific)\n"
-"   --encoder-tune-list     List supported --encoder-tune values for the\n"
-"         <string>          specified video encoder\n"
+"       --encoder-preset <string>\n"
+"                           Adjust video encoding settings for a particular\n"
+"                           speed/efficiency tradeoff (encoder-specific)\n"
+"   --encoder-preset-list <string>\n"
+"                           List supported --encoder-preset values for the\n"
+"                           specified video encoder\n"
+"       --encoder-tune <string>\n"
+"                           Adjust video encoding settings for a particular\n"
+"                           type of souce or situation (encoder-specific)\n"
+"   --encoder-tune-list <string>\n"
+"                           List supported --encoder-tune values for the\n"
+"                           specified video encoder\n"
 "   -x, --encopts <string>  Specify advanced encoding options in the same\n"
 "                           style as mencoder (all encoders except theora):\n"
 "                           option1=value1:option2=value2\n"
-"       --encoder-profile   Ensures compliance with the requested codec\n"
-"         <string>          profile (encoder-specific)\n"
-"   --encoder-profile-list  List supported --encoder-profile values for the\n"
-"         <string>          specified video encoder\n"
-"       --encoder-level     Ensures compliance with the requested codec\n"
-"         <string>          level (encoder-specific)\n"
-"   --encoder-level-list    List supported --encoder-level values for the\n"
-"         <string>          specified video encoder\n"
-"   -q, --quality <number>  Set video quality\n"
-"   -b, --vb <kb/s>         Set video bitrate (default: 1000)\n"
+"       --encoder-profile <string>\n"
+"                           Ensure compliance with the requested codec\n"
+"                           profile (encoder-specific)\n"
+"   --encoder-profile-list <string>\n"
+"                           List supported --encoder-profile values for the\n"
+"                           specified video encoder\n"
+"       --encoder-level <string>\n"
+"                           Ensures compliance with the requested codec\n"
+"                           level (encoder-specific)\n"
+"   --encoder-level-list <string>\n"
+"                           List supported --encoder-level values for the\n"
+"                           specified video encoder\n"
+"   -q, --quality <float>   Set video quality (e.g. 22.0)\n"
+"   -b, --vb <number>       Set video bitrate in kbit/s (default: 1000)\n"
 "   -2, --two-pass          Use two-pass mode\n"
 "       --no-two-pass       Disable two-pass mode\n"
 "   -T, --turbo             When using 2-pass use \"turbo\" options on the\n"
-"                           1st pass to improve speed\n"
+"                           first pass to improve speed\n"
 "                           (works with x264 and x265)\n"
-"       --no-turbo          Disable 2-pass mode's \"turbo\" 1st pass\n"
-"   -r, --rate              Set video framerate\n"
+"       --no-turbo          Disable 2-pass mode's \"turbo\" first pass\n"
+"   -r, --rate <float>      Set video framerate\n"
 "                           (" );
+    i = 0;
     rate = NULL;
     while ((rate = hb_video_framerate_get_next(rate)) != NULL)
     {
-        fprintf(out, "%s", rate->name);
-        if (hb_video_framerate_get_next(rate) != NULL)
+        if (i > 0)
         {
+            // separate multiple items
+            i++;
             fprintf(out, "/");
         }
+        if (hb_video_framerate_get_next(rate) != NULL)
+        {
+            if (i + strlen(rate->name) > 32)
+            {
+                // break long lines
+                i = 0;
+                fprintf(out, "\n                           ");
+            }
+            i += strlen(rate->name);
+        }
+        fprintf(out, "%s", rate->name);
     }
     fprintf( out, "\n"
 "                           or a number between " );
@@ -1294,13 +1333,16 @@ static void ShowHelp()
 "                           If none of these flags are given, the default\n"
 "                           is --pfr when -r is given and --vfr otherwise\n"
 "\n"
-"### Audio Options---------------------------------------------------------\n\n"
-"       --audio-lang-list   Specifiy a comma separated list of audio\n"
-"         <string>          languages you would like to select from the\n"
+"\n"
+"Audio Options ----------------------------------------------------------------\n"
+"\n"
+"       --audio-lang-list <string>\n"
+"                           Specifiy a comma separated list of audio\n"
+"                           languages you would like to select from the\n"
 "                           source title. By default, the first audio\n"
 "                           matching each language will be added to your\n"
-"                           output. Provide the language's iso639-2 code\n"
-"                           (fre, eng, spa, dut, et cetera)\n"
+"                           output. Provide the language's ISO 639-2 code\n"
+"                           (e.g. fre, eng, spa, dut, et cetera)\n"
 "                           Use code 'und' (Unknown) to match all languages.\n"
 "       --all-audio         Select all audio tracks matching languages in\n"
 "                           the specified language list (--audio-lang-list).\n"
@@ -1310,19 +1352,18 @@ static void ShowHelp()
 "                           Any language if list is not specified.\n"
 "   -a, --audio <string>    Select audio track(s), separated by commas\n"
 "                           (\"none\" for no audio, \"1,2,3\" for multiple\n"
-"                            tracks, default: first one).\n"
+"                           tracks, default: first one).\n"
 "                           Multiple output tracks can be used for one input.\n"
-"   -E, --aencoder <string> Audio encoder(s):\n" );
+"   -E, --aencoder <string> Select audio encoder(s):\n" );
     encoder = NULL;
     while ((encoder = hb_audio_encoder_get_next(encoder)) != NULL)
     {
-        fprintf(out, "                               %s\n",
-                encoder->short_name);
+        fprintf(out, "                               %s\n", encoder->short_name);
     }
     fprintf(out,
-"                           copy:* will passthrough the corresponding\n"
-"                           audio unmodified to the muxer if it is a\n"
-"                           supported passthrough audio type.\n"
+"                           \"copy:<type>\" will pass through the corresponding\n"
+"                           audio track without modification, if pass through\n"
+"                           is supported for the audio type.\n"
 "                           Separate tracks by commas.\n"
 "                           Defaults:\n");
     container = NULL;
@@ -1334,8 +1375,9 @@ static void ShowHelp()
                 hb_audio_encoder_get_short_name(audio_encoder));
     }
     fprintf(out,
-"       --audio-copy-mask   Set audio codecs that are permitted when the\n"
-"               <string>    \"copy\" audio encoder option is specified\n"
+"       --audio-copy-mask <string>\n"
+"                           Set audio codecs that are permitted when the\n"
+"                           \"copy\" audio encoder option is specified\n"
 "                           (" );
     i       = 0;
     encoder = NULL;
@@ -1355,15 +1397,17 @@ static void ShowHelp()
     }
     fprintf(out, ")\n"
 "                           Separated by commas for multiple allowed options.\n"
-"       --audio-fallback    Set audio codec to use when it is not possible\n"
-"               <string>    to copy an audio track without re-encoding.\n"
-"   -B, --ab <kb/s>         Set audio bitrate(s) (default: depends on the\n"
-"                           selected codec, mixdown and samplerate)\n"
+"       --audio-fallback <string>\n"
+"                           Set audio codec to use when it is not possible\n"
+"                           to copy an audio track without re-encoding.\n"
+"   -B, --ab <number>       Set audio track bitrate(s) in kbit/s.\n"
+"                           (default: determined by the selected codec, mixdown,\n"
+"                           and samplerate combination).\n"
 "                           Separate tracks by commas.\n"
-"   -Q, --aq <quality>      Set audio quality metric.\n"
+"   -Q, --aq <float>        Set audio quality metric.\n"
 "                           Separate tracks by commas.\n"
-"   -C, --ac <compression>  Set audio compression metric.\n"
-"                           selected codec)\n"
+"   -C, --ac <float>        Set audio compression metric.\n"
+"                           (available depending on selected codec)\n"
 "                           Separate tracks by commas.\n"
 "   -6, --mixdown <string>  Format(s) for audio downmixing/upmixing:\n");
     // skip HB_AMIXDOWN_NONE
@@ -1416,81 +1460,84 @@ static void ShowHelp()
 "                           in dB.  Negative values attenuate, positive\n"
 "                           values amplify. A 1 dB difference is barely\n"
 "                           audible.\n"
-"       --adither <string>  Apply dithering to the audio before encoding.\n"
-"                           Separate tracks by commas.\n"
-"                           Only supported by some encoders\n"
-"                           (");
-    i       = 0;
-    encoder = NULL;
-    while ((encoder = hb_audio_encoder_get_next(encoder)) != NULL)
-    {
-        if (hb_audio_dither_is_supported(encoder->codec))
-        {
-            if (i)
-            {
-                fprintf(out, "/");
-            }
-            i = 1;
-            fprintf(out, "%s", encoder->short_name);
-        }
-    }
-    fprintf(out, ").\n");
-    fprintf(out,
-    "                            Options:\n");
+"       --adither <string>  Select dithering to apply before encoding audio:\n");
     dither = NULL;
     while ((dither = hb_audio_dither_get_next(dither)) != NULL)
     {
         if (dither->method == hb_audio_dither_get_default())
         {
-            fprintf(out, "                               %s (default)\n",
-                    dither->short_name);
+            fprintf(out, "                               %s (default)\n", dither->short_name);
         }
         else
         {
-            fprintf(out, "                               %s\n",
-                    dither->short_name);
+            fprintf(out, "                               %s\n", dither->short_name);
         }
     }
     fprintf(out,
-"   -A, --aname <string>    Audio track name(s),\n"
 "                           Separate tracks by commas.\n"
+"                           Supported by encoder(s):\n");
+    encoder = NULL;
+    while ((encoder = hb_audio_encoder_get_next(encoder)) != NULL)
+    {
+        if (hb_audio_dither_is_supported(encoder->codec))
+        {
+            fprintf(out, "                               %s\n", encoder->short_name);
+        }
+    }
+    fprintf(out,
+"   -A, --aname <string>    Set audio track name(s).\n"
+"                           Separate tracks by commas.\n"
+"\n"
 "\n"
-"### Picture Settings------------------------------------------------------\n\n"
-"   -w, --width  <number>   Set picture width\n"
-"   -l, --height <number>   Set picture height\n"
-"       --crop  <T:B:L:R>   Set cropping values (default: autocrop)\n"
+"Picture Options --------------------------------------------------------------\n"
+"\n"
+"   -w, --width  <number>   Set storage width in pixels\n"
+"   -l, --height <number>   Set storage height in pixels\n"
+"       --crop   <top:bottom:left:right>\n"
+"                           Set picture cropping in pixels\n"
+"                           (default: automatically remove black bars)\n"
 "       --loose-crop        Always crop to a multiple of the modulus\n"
 "       --no-loose-crop     Disable preset 'loose-crop'\n"
-"   -Y, --maxHeight   <#>   Set maximum height\n"
-"   -X, --maxWidth    <#>   Set maximum width\n"
+"   -Y, --maxHeight <number>\n"
+"                           Set maximum height in pixels\n"
+"   -X, --maxWidth  <number>\n"
+"                           Set maximum width in pixels\n"
 "   --non-anamorphic        Set pixel aspect ratio to 1:1\n"
 "   --strict-anamorphic     Store pixel aspect ratio in video stream\n"
-"   --loose-anamorphic      Store pixel aspect ratio with specified width\n"
+"   --loose-anamorphic      Store pixel aspect ratio with specified display width\n"
 "   --custom-anamorphic     Store pixel aspect ratio in video stream and\n"
 "                           directly control all parameters.\n"
-"   --display-width         Set the width to scale the actual pixels to\n"
-"     <number>              at playback, for custom anamorphic.\n"
+"   --display-width <number>\n"
+"                           Set display width in pixels, for custom anamorphic.\n"
+"                           This determines the display aspect during playback,\n"
+"                           which may differ from the storage aspect.\n"
 "   --keep-display-aspect   Preserve the source's display aspect ratio\n"
 "                           when using custom anamorphic\n"
-"  --no-keep-display-aspect Disable preset 'keep-display-aspect'\n"
-"   --pixel-aspect          Set a custom pixel aspect for custom anamorphic\n"
-"     <PARX:PARY>           (--display-width and --pixel-aspect are mutually\n"
+"   --no-keep-display-aspect\n"
+"                           Disable preset 'keep-display-aspect'\n"
+"   --pixel-aspect <par_x:par_y>\n"
+"                           Set pixel aspect for custom anamorphic\n"
+"                           (--display-width and --pixel-aspect are mutually\n"
 "                           exclusive.\n"
-"   --itu-par               Use wider, ITU pixel aspect values for loose and\n"
-"                           custom anamorphic, useful with underscanned\n"
-"                           sources\n"
+"   --itu-par               Use wider ITU pixel aspect values for loose and\n"
+"                           custom anamorphic, useful with underscanned sources\n"
 "   --no-itu-par            Disable preset 'itu-par'\n"
-"   --modulus               Set the number you want the scaled pixel\n"
-"                           dimensions\n"
-"     <number>              to divide cleanly by. Does not affect strict\n"
-"                           anamorphic mode, which is always mod 2\n"
-"                           (default: 16)\n"
-"   -M, --color-matrix      Set the color space signaled by the output\n"
-"                           Values: 709, pal, ntsc, 601 (same as ntsc)\n"
-"                           (default: detected from source)\n"
+"   --modulus <number>      Set storage width and height modulus\n"
+"                           Dimensions will be made divisible by this number.\n"
+"                           Does not affect strict anamorphic mode (always mod 2)\n"
+"                           (default: set by preset, typically 2)\n"
+"   -M, --color-matrix <string>\n"
+"                           Set the color space signaled by the output:\n"
+"                               709\n"
+"                               601\n"
+"                               ntsc (same as 601)\n"
+"                               pal\n"
+"                           (default: auto-detected from source)\n"
+"\n"
+"\n"
+"Filters Options --------------------------------------------------------------\n"
 "\n"
-"### Filters---------------------------------------------------------------\n\n"
-"   --comb-detect           Detect interlace artifacts in frames.\n"
+"   --comb-detect[=string]  Detect interlace artifacts in frames.\n"
 "                           If not accompanied by the decomb or deinterlace\n"
 "                           filters, this filter only logs the interlaced\n"
 "                           frame count to the activity log.\n"
@@ -1503,20 +1550,22 @@ static void ShowHelp()
     showFilterDefault(out, HB_FILTER_COMB_DETECT);
     fprintf( out,
 "   --no-comb-detect        Disable preset comb-detect filter\n"
-"   -d, --deinterlace       Deinterlaces using libav yadif.\n");
+"   -d, --deinterlace[=string]\n"
+"                           Deinterlace video using libav yadif.\n");
     showFilterPresets(out, HB_FILTER_DEINTERLACE);
     showFilterKeys(out, HB_FILTER_DEINTERLACE);
     showFilterDefault(out, HB_FILTER_DEINTERLACE);
     fprintf( out,
-"   --no-deinterlace        Disable preset deinterlace filter\n"
-"   -5, --decomb            Deinterlaces using a combination of yadif,\n"
+"       --no-deinterlace    Disable preset deinterlace filter\n"
+"   -5, --decomb[=string]   Deinterlace video using a combination of yadif,\n"
 "                           blend, cubic, or EEDI2 interpolation.\n");
     showFilterPresets(out, HB_FILTER_DECOMB);
     showFilterKeys(out, HB_FILTER_DECOMB);
     showFilterDefault(out, HB_FILTER_DECOMB);
     fprintf( out,
 "   --no-decomb             Disable preset decomb filter\n"
-"   -9, --detelecine        Detelecine (ivtc) video with pullup filter\n"
+"   -9, --detelecine[=string]\n"
+"                           Detelecine (ivtc) video with pullup filter\n"
 "                           Note: this filter drops duplicate frames to\n"
 "                           restore the pre-telecine framerate, unless you\n"
 "                           specify a constant framerate\n"
@@ -1526,39 +1575,39 @@ static void ShowHelp()
     showFilterDefault(out, HB_FILTER_DETELECINE);
     fprintf( out,
 "   --no-detelecine         Disable preset detelecine filter\n"
-"   -8, --hqdn3d            Denoise video with hqdn3d filter\n");
+"   -8, --hqdn3d[=string]   Denoise video with hqdn3d filter\n");
     showFilterPresets(out, HB_FILTER_HQDN3D);
     showFilterKeys(out, HB_FILTER_HQDN3D);
     showFilterDefault(out, HB_FILTER_HQDN3D);
     fprintf( out,
 "   --no-hqdn3d             Disable preset hqdn3d filter\n"
-"   --denoise               Legacy alias for '--hqdn3d'\n"
-"   --nlmeans               Denoise video with nlmeans filter\n");
+"   --denoise[=string]      Legacy alias for '--hqdn3d'\n"
+"   --nlmeans[=string]      Denoise video with NLMeans filter\n");
     showFilterPresets(out, HB_FILTER_NLMEANS);
     showFilterKeys(out, HB_FILTER_NLMEANS);
     showFilterDefault(out, HB_FILTER_NLMEANS);
     fprintf( out,
 
-"   --no-nlmeans            Disable preset nlmeans filter\n"
-"   --nlmeans-tune          Tune nlmeans filter to content type\n"
-"                           Note: only works in conjunction with presets\n"
-"                           ultralight/light/medium/strong.\n"
-"                           Tunes:\n"
-"                             <none/film/grain/highmotion/animation>\n"
-"   -7, --deblock           Deblock video with pp7 filter\n");
+"   --no-nlmeans            Disable preset NLMeans filter\n"
+"   --nlmeans-tune <string> Tune NLMeans filter to content type\n");
+    showFilterTunes(out, HB_FILTER_NLMEANS);
+    fprintf( out,
+"                           Applies to NLMeans presets only (does not affect\n"
+"                           custom settings)\n"
+"   -7, --deblock[=string]  Deblock video with pp7 filter\n");
     showFilterKeys(out, HB_FILTER_DEBLOCK);
     showFilterDefault(out, HB_FILTER_DEBLOCK);
     fprintf( out,
 "   --no-deblock            Disable preset deblock filter\n"
-"   --rotate                Rotate image or flip its axes.\n"
+"   --rotate[=string]       Rotate image or flip its axes.\n"
 "                           angle rotates clockwise, can be one of:\n"
-"                              0, 90, 180, 270\n"
-"                           hflip flips the image on the x axis.\n");
+"                               0, 90, 180, 270\n"
+"                           hflip=1 flips the image on the x axis (horizontally).\n");
     showFilterKeys(out, HB_FILTER_ROTATE);
     showFilterDefault(out, HB_FILTER_ROTATE);
     fprintf( out,
-"   --pad                   Add borders to pad image (e.g. letterbox).\n"
-"                           The color of pad may be set (default black).\n"
+"   --pad <string>          Pad image with borders (e.g. letterbox).\n"
+"                           The padding color may be set (default black).\n"
 "                           Color may be an HTML color name or RGB value.\n"
 "                           The position of image in pad may also be set.\n");
     showFilterKeys(out, HB_FILTER_PAD);
@@ -1566,13 +1615,16 @@ static void ShowHelp()
 "   -g, --grayscale         Grayscale encoding\n"
 "   --no-grayscale          Disable preset 'grayscale'\n"
 "\n"
-"### Subtitle Options------------------------------------------------------\n\n"
-"      --subtitle-lang-list Specifiy a comma separated list of subtitle\n"
-"          <string>         languages you would like to select from the\n"
+"\n"
+"Subtitles Options ------------------------------------------------------------\n"
+"\n"
+"  --subtitle-lang-list <string>\n"
+"                           Specifiy a comma separated list of subtitle\n"
+"                           languages you would like to select from the\n"
 "                           source title. By default, the first subtitle\n"
 "                           matching each language will be added to your\n"
-"                           output. Provide the language's iso639-2 code\n"
-"                           (fre, eng, spa, dut, et cetera)\n"
+"                           output. Provide the language's ISO 639-2 code\n"
+"                           (e.g. fre, eng, spa, dut, et cetera)\n"
 "      --all-subtitles      Select all subtitle tracks matching languages in\n"
 "                           the specified language list\n"
 "                           (--subtitle-lang-list).\n"
@@ -1585,7 +1637,7 @@ static void ShowHelp()
 "                           More than one output track can be used for one\n"
 "                           input. \"none\" for no subtitles.\n"
 "                           Example: \"1,2,3\" for multiple tracks.\n"
-"                           A special track name \"scan\" adds an extra 1st\n"
+"                           A special track name \"scan\" adds an extra first\n"
 "                           pass. This extra pass scans subtitles matching\n"
 "                           the language of the first audio or the language \n"
 "                           selected by --native-language.\n"
@@ -1593,32 +1645,36 @@ static void ShowHelp()
 "                           or less is selected. This should locate subtitles\n"
 "                           for short foreign language segments. Best used in\n"
 "                           conjunction with --subtitle-forced.\n"
-"  -F, --subtitle-forced    Only display subtitles from the selected stream\n"
-"        <string>           if the subtitle has the forced flag set. The\n"
-"                           values in \"string\" are indexes into the\n"
+"  -F, --subtitle-forced[=string]\n"
+"                           Only display subtitles from the selected stream\n"
+"                           if the subtitle has the forced flag set. The\n"
+"                           values in 'string' are indexes into the\n"
 "                           subtitle list specified with '--subtitle'.\n"
 "                           Separate tracks by commas.\n"
 "                           Example: \"1,2,3\" for multiple tracks.\n"
 "                           If \"string\" is omitted, the first track is\n"
 "                           forced.\n"
-"      --subtitle-burned    \"Burn\" the selected subtitle into the video\n"
-"        <subtitle>         track. If \"subtitle\" is omitted, the first\n"
+"      --subtitle-burned[=number]\n"
+"                           \"Burn\" the selected subtitle into the video\n"
+"                           track. If \"subtitle\" is omitted, the first\n"
 "                           track is burned. \"subtitle\" is an index into\n"
 "                           the subtitle list specified with '--subtitle'\n"
 "                           or \"native\" to burn the subtitle track that may\n"
 "                           be added by the 'native-language' option.\n"
-"      --subtitle-default   Flag the selected subtitle as the default\n"
-"        <number>           subtitle to be displayed upon playback.  Setting\n"
+"      --subtitle-default[=number]\n"
+"                           Flag the selected subtitle as the default\n"
+"                           subtitle to be displayed upon playback.  Setting\n"
 "                           no default means no subtitle will be displayed\n"
-"                           automatically. \"number\" is an index into the\n"
+"                           automatically. 'number' is an index into the\n"
 "                           subtitle list specified with '--subtitle'.\n"
-"  -N, --native-language    Specifiy your language preference. When the first\n"
-"      <string>             audio track does not match your native language\n"
+"  -N, --native-language <string>\n"
+"                           Specifiy your language preference. When the first\n"
+"                           audio track does not match your native language\n"
 "                           then select the first subtitle that does. When\n"
 "                           used in conjunction with --native-dub the audio\n"
 "                           track is changed in preference to subtitles.\n"
-"                           Provide the language's iso639-2 code:\n"
-"                               (fre, eng, spa, dut, et cetera)\n"
+"                           Provide the language's ISO 639-2 code\n"
+"                           (e.g. fre, eng, spa, dut, et cetera)\n"
 "      --native-dub         Used in conjunction with --native-language\n"
 "                           requests that if no audio tracks are selected the\n"
 "                           default selected audio track will be the first\n"
@@ -1626,27 +1682,29 @@ static void ShowHelp()
 "                           are no matching audio tracks then the first\n"
 "                           matching subtitle track is used instead.\n"
 "     --srt-file <string>   SubRip SRT filename(s), separated by commas.\n"
-"     --srt-codeset         Character codeset(s) that the SRT file(s) are\n"
-"       <string>            encoded in, separated by commas.\n"
-"                           Use 'iconv -l' for a list of valid\n"
-"                           codesets. If not specified, 'latin1' is assumed\n"
-"     --srt-offset          Offset (in milliseconds) to apply to the SRT\n"
-"       <string>            file(s), separated by commas. If not specified,\n"
+"     --srt-codeset <string>\n"
+"                           Character codeset(s) that the SRT file(s) are\n"
+"                           encoded as, separated by commas.\n"
+"                           If not specified, 'latin1' is assumed.\n"
+"                           Command 'iconv -l' provides a list of valid codesets.\n"
+"     --srt-offset <string> Offset (in milliseconds) to apply to the SRT\n"
+"                           file(s), separated by commas. If not specified,\n"
 "                           zero is assumed. Offsets may be negative.\n"
-"     --srt-lang <string>   SRT track language as an iso639-2 code:\n"
-"                               (fre, eng, spa, dut, et cetera)\n"
-"                           Separated by commas. If not specified, then 'und'\n"
-"                           is used.\n"
-"     --srt-default         Flag the selected srt as the default subtitle\n"
-"       <number>            to be displayed upon playback. Setting no default\n"
-"                           means no subtitle will be automatically displayed\n"
-"                           If \"number\" is omitted, the first SRT is the\n"
-"                           default. \"number\" is an 1 based index into the\n"
-"                           'srt-file' list\n"
-"     --srt-burn            \"Burn\" the selected SRT subtitle into the\n"
-"       <number>            video track. If \"number\" is omitted, the first\n"
-"                           SRT is burned. \"number\" is an 1 based index\n"
-"                           into the 'srt-file' list\n"
+"     --srt-lang <string>   SRT track language as an ISO 639-2 code\n"
+"                           (e.g. fre, eng, spa, dut, et cetera)\n"
+"                           If not specified, then 'und' is used.\n"
+"                           Separate by commas.\n"
+"     --srt-default[=number]\n"
+"                           Flag the selected SRT as the default subtitle\n"
+"                           to be displayed during playback.\n"
+"                           Setting no default means no subtitle will be\n"
+"                           automatically displayed. If 'number' is omitted,\n"
+"                           the first SRT is the default.\n"
+"                           'number' is a 1-based index into the 'srt-file' list\n"
+"     --srt-burn[=number]   \"Burn\" the selected SRT subtitle into\n"
+"                           the video track.\n"
+"                           If 'number' is omitted, the first SRT is burned.\n"
+"                           'number' is a 1-based index into the 'srt-file' list\n"
 "\n"
     );
 
@@ -1654,13 +1712,18 @@ static void ShowHelp()
 if (hb_qsv_available())
 {
     fprintf( out,
-"### Intel Quick Sync Video------------------------------------------------\n\n"
-"   --disable-qsv-decoding  Force software decoding of the video track.\n"
-"   --enable-qsv-decoding   Allow QSV hardware decoding of the video track.\n"
-"   --qsv-async-depth       Specifies how many asynchronous operations\n"
+"\n"
+"-- Intel Quick Sync Video Options --------------------------------------------\n"
+"\n"
+"   --enable-qsv-decoding   Allow QSV hardware decoding of the video track\n"
+"   --disable-qsv-decoding  Disable QSV hardware decoding of the video track,\n"
+"                           forcing software decoding instead\n"
+"   --qsv-async-depth[=number]\n"
+"                           Set the number of asynchronous operations that\n"
 "                           should be performed before the result is\n"
 "                           explicitly synchronized.\n"
-"                           Default: 4. If zero, the value is not specified.\n"
+"                           Omit 'number' for zero.\n"
+"                           (default: 4)\n"
 "\n"
     );
 }