cmp, diff, diff3, sdiff: edit and align --help text.

* cmp.c (option_help_msgid, usage),
* diff.c (option_help_msgid, usage),
* diff3.c (option_help_msgid, usage),
* sdiff.c (option_help_msgid, usage): align descriptions in the --help
output and slightly edit content.

4 files changed, 146 insertions, 103 deletions

diff --git a/src/cmp.c b/src/cmp.c
index f78f4f6..92b60bc 100644
--- a/src/cmp.c
+++ b/src/cmp.c
@@ -158,15 +158,15 @@ check_stdout (void)
 }
 
 static char const * const option_help_msgid[] = {
-  N_("-b  --print-bytes  Print differing bytes."),
-  N_("-i SKIP  --ignore-initial=SKIP  Skip the first SKIP bytes of input."),
-  N_("-i SKIP1:SKIP2  --ignore-initial=SKIP1:SKIP2"),
-  N_("  Skip the first SKIP1 bytes of FILE1 and the first SKIP2 bytes of FILE2."),
-  N_("-l  --verbose  Output byte numbers and values of all differing bytes."),
-  N_("-n LIMIT  --bytes=LIMIT  Compare at most LIMIT bytes."),
-  N_("-s  --quiet  --silent  Output nothing; yield exit status only."),
-  N_("-v  --version  Output version info."),
-  N_("--help  Output this help."),
+  N_("-b, --print-bytes          print differing bytes"),
+  N_("-i, --ignore-initial=SKIP         skip first SKIP bytes of both inputs"),
+  N_("-i, --ignore-initial=SKIP1:SKIP2  skip first SKIP1 bytes of FILE1 and\n"
+     "                                      first SKIP2 bytes of FILE2"),
+  N_("-l, --verbose              output byte numbers and differing byte values"),
+  N_("-n, --bytes=LIMIT          compare at most LIMIT bytes"),
+  N_("-s, --quiet, --silent      suppress all normal output"),
+  N_("    --help                 display this help and exit"),
+  N_("-v, --version              output version information and exit"),
   0
 };
 
@@ -177,11 +177,17 @@ usage (void)
 
   printf (_("Usage: %s [OPTION]... FILE1 [FILE2 [SKIP1 [SKIP2]]]\n"),
 	  program_name);
-  printf ("%s\n\n", _("Compare two files byte by byte."));
+  printf ("%s\n", _("Compare two files byte by byte."));
+  printf ("\n%s\n\n",
+_("The optional SKIP1 and SKIP2 specify the number of bytes to skip\n"
+  "at the beginning of each file (zero by default)."));
+
+  fputs (_("\
+Mandatory arguments to long options are mandatory for short options too.\n\
+"), stdout);
   for (p = option_help_msgid;  *p;  p++)
     printf ("  %s\n", _(*p));
-  printf ("\n%s\n%s\n\n%s\n%s\n",
-	  _("SKIP1 and SKIP2 are the number of bytes to skip in each file."),
+  printf ("\n%s\n\n%s\n%s\n",
 	  _("SKIP values may be followed by the following multiplicative suffixes:\n\
 kB 1000, K 1024, MB 1,000,000, M 1,048,576,\n\
 GB 1,000,000,000, G 1,073,741,824, and so on for T, P, E, Z, Y."),
diff --git a/src/diff.c b/src/diff.c
index 0ca2328..0aa09e9 100644
--- a/src/diff.c
+++ b/src/diff.c
@@ -842,41 +842,63 @@ check_stdout (void)
 }
 
 static char const * const option_help_msgid[] = {
-  N_("Compare files line by line."),
+  N_("    --normal                  output a normal diff (the default)"),
+  N_("-q, --brief                   report only when files differ"),
+  N_("-s, --report-identical-files  report when two files are the same"),
+  N_("-c, -C NUM, --context[=NUM]   output NUM (default 3) lines of copied context"),
+  N_("-u, -U NUM, --unified[=NUM]   output NUM (default 3) lines of unified context"),
+  N_("-e, --ed                      output an ed script"),
+  N_("-n, --rcs                     output an RCS format diff"),
+  N_("-y, --side-by-side            output in two columns"),
+  N_("-W, --width=NUM               output at most NUM (default 130) print columns"),
+  N_("    --left-column             output only the left column of common lines"),
+  N_("    --suppress-common-lines   do not output common lines"),
   "",
-  N_("-i  --ignore-case  Ignore case differences in file contents."),
-  N_("--ignore-file-name-case  Ignore case when comparing file names."),
-  N_("--no-ignore-file-name-case  Consider case when comparing file names."),
-  N_("-E  --ignore-tab-expansion  Ignore changes due to tab expansion."),
-  N_("-b  --ignore-space-change  Ignore changes in the amount of white space."),
-  N_("-w  --ignore-all-space  Ignore all white space."),
-  N_("-B  --ignore-blank-lines  Ignore changes whose lines are all blank."),
-  N_("-I RE  --ignore-matching-lines=RE  Ignore changes whose lines all match RE."),
-  N_("--strip-trailing-cr  Strip trailing carriage return on input."),
+  N_("-p, --show-c-function         show which C function each change is in"),
+  N_("-F, --show-function-line=RE   show the most recent line matching RE"),
+  N_("    --label LABEL             use LABEL instead of file name\n"
+     "                                (can be repeated)"),
+  "",
+  N_("-t, --expand-tabs             expand tabs to spaces in output"),
+  N_("-T, --initial-tab             make tabs line up by prepending a tab"),
+  N_("    --tabsize=NUM             tab stops every NUM (default 8) print columns"),
+  N_("    --suppress-blank-empty    suppress space or tab before empty output lines"),
+  N_("-l, --paginate                pass output through `pr' to paginate it"),
+  "",
+  N_("-r, --recursive                 recursively compare any subdirectories found"),
+  N_("-N, --new-file                  treat absent files as empty"),
+  N_("    --unidirectional-new-file   treat absent first files as empty"),
+  N_("    --ignore-file-name-case     ignore case when comparing file names"),
+  N_("    --no-ignore-file-name-case  consider case when comparing file names"),
+  N_("-x, --exclude=PAT               exclude files that match PAT"),
+  N_("-X, --exclude-from=FILE         exclude files that match any pattern in FILE"),
+  N_("-S, --starting-file=FILE        start with FILE when comparing directories"),
+  N_("    --from-file=FILE1           compare FILE1 to all operands;\n"
+     "                                  FILE1 can be a directory"),
+  N_("    --to-file=FILE2             compare all operands to FILE2;\n"
+     "                                  FILE2 can be a directory"),
+  "",
+  N_("-i, --ignore-case               ignore case differences in file contents"),
+  N_("-E, --ignore-tab-expansion      ignore changes due to tab expansion"),
+  N_("-b  --ignore-space-change       ignore changes in the amount of white space"),
+  N_("-w, --ignore-all-space          ignore all white space"),
+  N_("-B, --ignore-blank-lines        ignore changes whose lines are all blank"),
+  N_("-I, --ignore-matching-lines=RE  ignore changes whose lines all match RE"),
+  "",
+  N_("-a, --text                      treat all files as text"),
+  N_("    --strip-trailing-cr         strip trailing carriage return on input"),
 #if O_BINARY
-  N_("--binary  Read and write data in binary mode."),
+  N_("    --binary                    read and write data in binary mode"),
 #endif
-  N_("-a  --text  Treat all files as text."),
   "",
-  N_("-c  -C NUM  --context[=NUM]  Output NUM (default 3) lines of copied context.\n\
--u  -U NUM  --unified[=NUM]  Output NUM (default 3) lines of unified context.\n\
-  -L LABEL  --label=LABEL  Use LABEL instead of file name.\n\
-  -p  --show-c-function  Show which C function each change is in.\n\
-  -F RE  --show-function-line=RE  Show the most recent line matching RE."),
-  N_("-q  --brief  Output only whether files differ."),
-  N_("-e  --ed  Output an ed script."),
-  N_("--normal  Output a normal diff."),
-  N_("-n  --rcs  Output an RCS format diff."),
-  N_("-y  --side-by-side  Output in two columns.\n\
-  -W NUM  --width=NUM  Output at most NUM (default 130) print columns.\n\
-  --left-column  Output only the left column of common lines.\n\
-  --suppress-common-lines  Do not output common lines."),
-  N_("-D NAME  --ifdef=NAME  Output merged file to show `#ifdef NAME' diffs."),
-  N_("--GTYPE-group-format=GFMT  Similar, but format GTYPE input groups with GFMT."),
-  N_("--line-format=LFMT  Similar, but format all input lines with LFMT."),
-  N_("--LTYPE-line-format=LFMT  Similar, but format LTYPE input lines with LFMT."),
+  N_("-D, --ifdef=NAME                output merged file with `#ifdef NAME' diffs"),
+  N_("    --GTYPE-group-format=GFMT   format GTYPE input groups with GFMT"),
+  N_("    --line-format=LFMT          format all input lines with LFMT"),
+  N_("    --LTYPE-line-format=LFMT    format LTYPE input lines with LFMT"),
+  N_("  These format options provide fine-grained control over the output\n"
+     "    of diff, generalizing -D/--ifdef."),
   N_("  LTYPE is `old', `new', or `unchanged'.  GTYPE is LTYPE or `changed'."),
-  N_("  GFMT may contain:\n\
+  N_("  GFMT (only) may contain:\n\
     %<  lines from FILE1\n\
     %>  lines from FILE2\n\
     %=  lines common to FILE1 and FILE2\n\
@@ -886,41 +908,27 @@ static char const * const option_help_msgid[] = {
         L  last line number\n\
         N  number of lines = L-F+1\n\
         E  F-1\n\
-        M  L+1"),
-  N_("  LFMT may contain:\n\
+        M  L+1\n\
+    %(A=B?T:E)  if A equals B then T else E"),
+  N_("  LFMT (only) may contain:\n\
     %L  contents of line\n\
     %l  contents of line, excluding any trailing newline\n\
     %[-][WIDTH][.[PREC]]{doxX}n  printf-style spec for input line number"),
-  N_("  Either GFMT or LFMT may contain:\n\
+  N_("  Both GFMT and LFMT may contain:\n\
     %%  %\n\
     %c'C'  the single character C\n\
-    %c'\\OOO'  the character with octal code OOO"),
+    %c'\\OOO'  the character with octal code OOO\n\
+    C    the character C (other characters represent themselves)"),
   "",
-  N_("-l  --paginate  Pass the output through `pr' to paginate it."),
-  N_("-t  --expand-tabs  Expand tabs to spaces in output."),
-  N_("-T  --initial-tab  Make tabs line up by prepending a tab."),
-  N_("--tabsize=NUM  Tab stops are every NUM (default 8) print columns."),
-  N_("--suppress-blank-empty  Suppress space or tab before empty output lines."),
+  N_("-d, --minimal            try hard to find a smaller set of changes"),
+  N_("    --horizon-lines=NUM  keep NUM lines of the common prefix and suffix"),
+  N_("    --speed-large-files  assume large files and many scattered small changes"),
   "",
-  N_("-r  --recursive  Recursively compare any subdirectories found."),
-  N_("-N  --new-file  Treat absent files as empty."),
-  N_("--unidirectional-new-file  Treat absent first files as empty."),
-  N_("-s  --report-identical-files  Report when two files are the same."),
-  N_("-x PAT  --exclude=PAT  Exclude files that match PAT."),
-  N_("-X FILE  --exclude-from=FILE  Exclude files that match any pattern in FILE."),
-  N_("-S FILE  --starting-file=FILE  Start with FILE when comparing directories."),
-  N_("--from-file=FILE1  Compare FILE1 to all operands.  FILE1 can be a directory."),
-  N_("--to-file=FILE2  Compare all operands to FILE2.  FILE2 can be a directory."),
-  "",
-  N_("--horizon-lines=NUM  Keep NUM lines of the common prefix and suffix."),
-  N_("-d  --minimal  Try hard to find a smaller set of changes."),
-  N_("--speed-large-files  Assume large files and many scattered small changes."),
-  "",
-  N_("-v  --version  Output version info."),
-  N_("--help  Output this help."),
+  N_("    --help               display this help and exit"),
+  N_("-v, --version            output version information and exit"),
   "",
   N_("FILES are `FILE1 FILE2' or `DIR1 DIR2' or `DIR FILE...' or `FILE... DIR'."),
-  N_("If --from-file or --to-file is given, there are no restrictions on FILES."),
+  N_("If --from-file or --to-file is given, there are no restrictions on FILE(s)."),
   N_("If a FILE is `-', read standard input."),
   N_("Exit status is 0 if inputs are the same, 1 if different, 2 if trouble."),
   0
@@ -932,6 +940,11 @@ usage (void)
   char const * const *p;
 
   printf (_("Usage: %s [OPTION]... FILES\n"), program_name);
+  printf ("%s\n\n", _("Compare FILES line by line."));
+
+  fputs (_("\
+Mandatory arguments to long options are mandatory for short options too.\n\
+"), stdout);
 
   for (p = option_help_msgid;  *p;  p++)
     {
diff --git a/src/diff3.c b/src/diff3.c
index b4e1e3a..34e7a8f 100644
--- a/src/diff3.c
+++ b/src/diff3.c
@@ -426,23 +426,28 @@ check_stdout (void)
 }
 
 static char const * const option_help_msgid[] = {
-  N_("-e  --ed  Output unmerged changes from OLDFILE to YOURFILE into MYFILE."),
-  N_("-E  --show-overlap  Output unmerged changes, bracketing conflicts."),
-  N_("-A  --show-all  Output all changes, bracketing conflicts."),
-  N_("-x  --overlap-only  Output overlapping changes."),
-  N_("-X  Output overlapping changes, bracketing them."),
-  N_("-3  --easy-only  Output unmerged nonoverlapping changes."),
+  N_("-A, --show-all              output all changes, bracketing conflicts"),
   "",
-  N_("-m  --merge  Output merged file instead of ed script (default -A)."),
-  N_("-L LABEL  --label=LABEL  Use LABEL instead of file name."),
-  N_("-i  Append `w' and `q' commands to ed scripts."),
-  N_("-a  --text  Treat all files as text."),
-  N_("--strip-trailing-cr  Strip trailing carriage return on input."),
-  N_("-T  --initial-tab  Make tabs line up by prepending a tab."),
-  N_("--diff-program=PROGRAM  Use PROGRAM to compare files."),
+  N_("-e, --ed                    output ed script incorporating changes\n"
+     "                                from OLDFILE to YOURFILE into MYFILE"),
+  N_("-E, --show-overlap          like -e, but bracket conflicts"),
+  N_("-3, --easy-only             like -e, but incorporate only nonoverlapping changes"),
+  N_("-x, --overlap-only          like -e, but incorporate only overlapping changes"),
+  N_("-X                          like -x, but bracket conflicts"),
+  N_("-i                          append `w' and `q' commands to ed scripts"),
   "",
-  N_("-v  --version  Output version info."),
-  N_("--help  Output this help."),
+  N_("-m, --merge                 output actual merged file, according to\n"
+     "                                -A if no other options are given"),
+  "",
+  N_("-a, --text                  treat all files as text"),
+  N_("    --strip-trailing-cr     strip trailing carriage return on input"),
+  N_("-T, --initial-tab           make tabs line up by prepending a tab"),
+  N_("    --diff-program=PROGRAM  use PROGRAM to compare files"),
+  N_("-L, --label=LABEL           use LABEL instead of file name\n"
+     "                                (can be repeated up to three times)"),
+  "",
+  N_("    --help                  display this help and exit"),
+  N_("-v, --version               output version information and exit"),
   0
 };
 
@@ -454,11 +459,25 @@ usage (void)
   printf (_("Usage: %s [OPTION]... MYFILE OLDFILE YOURFILE\n"),
 	  program_name);
   printf ("%s\n\n", _("Compare three files line by line."));
+
+  fputs (_("\
+Mandatory arguments to long options are mandatory for short options too.\n\
+"), stdout);
   for (p = option_help_msgid;  *p;  p++)
     if (**p)
       printf ("  %s\n", _(*p));
     else
       putchar ('\n');
+  fputs (_("\n\
+The default output format is a somewhat human-readable representation of\n\
+the changes.\n\
+\n\
+The -e, -E, -x, -X (and corresponding long) options cause an ed script\n\
+to be output instead of the default.\n\
+\n\
+Finally, the -m (--merge) option causes diff3 to do the merge internally\n\
+and output the actual merged file.  For unusual input, this is more\n\
+robust than using ed.\n"), stdout);
   printf ("\n%s\n%s\n",
 	  _("If a FILE is `-', read standard input."),
 	  _("Exit status is 0 if successful, 1 if conflicts, 2 if trouble."));
diff --git a/src/sdiff.c b/src/sdiff.c
index d2b1f3c..2d53d2f 100644
--- a/src/sdiff.c
+++ b/src/sdiff.c
@@ -166,30 +166,30 @@ check_stdout (void)
 }
 
 static char const * const option_help_msgid[] = {
-  N_("-o FILE  --output=FILE  Operate interactively, sending output to FILE."),
+  N_("-o, --output=FILE            operate interactively, sending output to FILE"),
   "",
-  N_("-i  --ignore-case  Consider upper- and lower-case to be the same."),
-  N_("-E  --ignore-tab-expansion  Ignore changes due to tab expansion."),
-  N_("-b  --ignore-space-change  Ignore changes in the amount of white space."),
-  N_("-W  --ignore-all-space  Ignore all white space."),
-  N_("-B  --ignore-blank-lines  Ignore changes whose lines are all blank."),
-  N_("-I RE  --ignore-matching-lines=RE  Ignore changes whose lines all match RE."),
-  N_("--strip-trailing-cr  Strip trailing carriage return on input."),
-  N_("-a  --text  Treat all files as text."),
+  N_("-i, --ignore-case            consider upper- and lower-case to be the same"),
+  N_("-E, --ignore-tab-expansion   ignore changes due to tab expansion"),
+  N_("-b, --ignore-space-change    ignore changes in the amount of white space"),
+  N_("-W, --ignore-all-space       ignore all white space"),
+  N_("-B, --ignore-blank-lines     ignore changes whose lines are all blank"),
+  N_("-I, --ignore-matching-lines=RE  ignore changes whose lines all match RE"),
+  N_("    --strip-trailing-cr      strip trailing carriage return on input"),
+  N_("-a, --text                   treat all files as text"),
   "",
-  N_("-w NUM  --width=NUM  Output at most NUM (default 130) print columns."),
-  N_("-l  --left-column  Output only the left column of common lines."),
-  N_("-s  --suppress-common-lines  Do not output common lines."),
+  N_("-w, --width=NUM              output at most NUM (default 130) print columns"),
+  N_("-l, --left-column            output only the left column of common lines"),
+  N_("-s, --suppress-common-lines  do not output common lines"),
   "",
-  N_("-t  --expand-tabs  Expand tabs to spaces in output."),
-  N_("--tabsize=NUM  Tab stops are every NUM (default 8) print columns."),
+  N_("-t, --expand-tabs            expand tabs to spaces in output"),
+  N_("    --tabsize=NUM            tab stops at every NUM (default 8) print columns"),
   "",
-  N_("-d  --minimal  Try hard to find a smaller set of changes."),
-  N_("-H  --speed-large-files  Assume large files and many scattered small changes."),
-  N_("--diff-program=PROGRAM  Use PROGRAM to compare files."),
+  N_("-d, --minimal                try hard to find a smaller set of changes"),
+  N_("-H, --speed-large-files      assume large files, many scattered small changes"),
+  N_("    --diff-program=PROGRAM   use PROGRAM to compare files"),
   "",
-  N_("-v  --version  Output version info."),
-  N_("--help  Output this help."),
+  N_("    --help                   display this help and exit"),
+  N_("-v, --version                output version information and exit"),
   0
 };
 
@@ -199,7 +199,12 @@ usage (void)
   char const * const *p;
 
   printf (_("Usage: %s [OPTION]... FILE1 FILE2\n"), program_name);
-  printf ("%s\n\n", _("Side-by-side merge of file differences."));
+  printf ("%s\n\n",
+          _("Side-by-side merge of differences between FILE1 and FILE2."));
+
+  fputs (_("\
+Mandatory arguments to long options are mandatory for short options too.\n\
+"), stdout);
   for (p = option_help_msgid;  *p;  p++)
     if (**p)
       printf ("  %s\n", _(*p));