Move error-stack text to top of usage display (#1564)

* Move error-stack text to top of usage display

* Add optional tag ti list

* format changes

* Revert incorrect change

6 files changed, 48 insertions, 27 deletions

diff --git a/tools/src/h5copy/h5copy.c b/tools/src/h5copy/h5copy.c
index 6f10fee..eacd05b 100644
--- a/tools/src/h5copy/h5copy.c
+++ b/tools/src/h5copy/h5copy.c
@@ -19,7 +19,7 @@
 #define PROGRAMNAME "h5copy"
 
 /* command-line options: short and long-named parameters */
-static const char *           s_opts    = "d:f:hi:o:ps:vVE";
+static const char *           s_opts    = "d:f:hi:o:ps:vVE*";
 static struct h5_long_options l_opts[]  = {{"destination", require_arg, 'd'},
                                           {"flag", require_arg, 'f'},
                                           {"help", no_arg, 'h'},
@@ -29,7 +29,7 @@ static struct h5_long_options l_opts[]  = {{"destination", require_arg, 'd'},
                                           {"source", require_arg, 's'},
                                           {"verbose", no_arg, 'v'},
                                           {"version", no_arg, 'V'},
-                                          {"enable-error-stack", no_arg, 'E'},
+                                          {"enable-error-stack", optional_arg, 'E'},
                                           {NULL, 0, '\0'}};
 char *                        fname_src = NULL;
 char *                        fname_dst = NULL;
@@ -93,15 +93,17 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "      -o, --output       output file name\n");
     PRINTVALSTREAM(rawoutstream, "      -s, --source       source object name\n");
     PRINTVALSTREAM(rawoutstream, "      -d, --destination  destination object name\n");
+    PRINTVALSTREAM(rawoutstream, "   ERROR\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "     --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "                          Optional value 2 also prints file open errors.\n");
     PRINTVALSTREAM(rawoutstream, "   OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "      -h, --help         Print a usage message and exit\n");
     PRINTVALSTREAM(rawoutstream,
                    "      -p, --parents      No error if existing, make parent groups as needed\n");
     PRINTVALSTREAM(rawoutstream, "      -v, --verbose      Print information about OBJECTS and OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "      -V, --version      Print version number and exit\n");
-    PRINTVALSTREAM(rawoutstream, "      --enable-error-stack\n");
-    PRINTVALSTREAM(rawoutstream,
-                   "                  Prints messages from the HDF5 error stack as they occur.\n");
     PRINTVALSTREAM(rawoutstream, "      -f, --flag         Flag type\n\n");
     PRINTVALSTREAM(rawoutstream, "      Flag type is one of the following strings:\n\n");
     PRINTVALSTREAM(rawoutstream, "      shallow     Copy only immediate members for groups\n\n");
@@ -288,7 +290,10 @@ main(int argc, char *argv[])
                 break;
 
             case 'E':
-                enable_error_stack = 1;
+                if (H5_optarg != NULL)
+                    enable_error_stack = HDatoi(H5_optarg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             default:
diff --git a/tools/src/h5diff/h5diff_common.c b/tools/src/h5diff/h5diff_common.c
index 77a6785..2619a9d 100644
--- a/tools/src/h5diff/h5diff_common.c
+++ b/tools/src/h5diff/h5diff_common.c
@@ -25,7 +25,7 @@ static int check_d_input(const char *);
  * Command-line options: The user can specify short or long-named
  * parameters.
  */
-static const char *           s_opts   = "hVrv*qn:d:p:NcelxE:A:S";
+static const char *           s_opts   = "hVrv*qn:d:p:NcelxE:A:S*";
 static struct h5_long_options l_opts[] = {{"help", no_arg, 'h'},
                                           {"version", no_arg, 'V'},
                                           {"report", no_arg, 'r'},
@@ -41,7 +41,7 @@ static struct h5_long_options l_opts[] = {{"help", no_arg, 'h'},
                                           {"no-dangling-links", no_arg, 'x'},
                                           {"exclude-path", require_arg, 'E'},
                                           {"exclude-attribute", require_arg, 'A'},
-                                          {"enable-error-stack", no_arg, 'S'},
+                                          {"enable-error-stack", optional_arg, 'S'},
                                           {"vol-value-1", require_arg, '1'},
                                           {"vol-name-1", require_arg, '2'},
                                           {"vol-info-1", require_arg, '3'},
@@ -300,7 +300,10 @@ parse_command_line(int argc, const char *const *argv, const char **fname1, const
                 break;
 
             case 'S':
-                enable_error_stack = 1;
+                if (H5_optarg != NULL)
+                    enable_error_stack = HDatoi(H5_optarg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             case 'E':
@@ -652,6 +655,10 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "  [obj1]            Name of an HDF5 object, in absolute path\n");
     PRINTVALSTREAM(rawoutstream, "  [obj2]            Name of an HDF5 object, in absolute path\n");
     PRINTVALSTREAM(rawoutstream, "\n");
+    PRINTVALSTREAM(rawoutstream, "  ERROR\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "   --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream, "                        Optional value 2 also prints file open errors.\n");
     PRINTVALSTREAM(rawoutstream, "  OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "   -h, --help\n");
     PRINTVALSTREAM(rawoutstream, "         Print a usage message and exit.\n");
@@ -674,9 +681,6 @@ usage(void)
     PRINTVALSTREAM(rawoutstream, "          3 : All level 2 information plus file names.\n");
     PRINTVALSTREAM(rawoutstream, "   -q, --quiet\n");
     PRINTVALSTREAM(rawoutstream, "         Quiet mode. Do not produce output.\n");
-    PRINTVALSTREAM(rawoutstream, "   --enable-error-stack\n");
-    PRINTVALSTREAM(rawoutstream,
-                   "                   Prints messages from the HDF5 error stack as they occur.\n");
     PRINTVALSTREAM(rawoutstream,
                    "   --vol-value-1           Value (ID) of the VOL connector to use for opening the\n");
     PRINTVALSTREAM(rawoutstream, "                           first HDF5 file specified\n");
diff --git a/tools/src/h5dump/h5dump.c b/tools/src/h5dump/h5dump.c
index 8c04bc7..d82ea94 100644
--- a/tools/src/h5dump/h5dump.c
+++ b/tools/src/h5dump/h5dump.c
@@ -165,6 +165,12 @@ usage(const char *prog)
     PRINTVALSTREAM(rawoutstream, "  OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "     -h,   --help         Print a usage message and exit\n");
     PRINTVALSTREAM(rawoutstream, "     -V,   --version      Print version number and exit\n");
+    PRINTVALSTREAM(rawoutstream, "--------------- Error Options ---------------\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "     --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "                          Optional value 2 also prints file open errors.\n");
+    PRINTVALSTREAM(rawoutstream, "                          Default setting disables any error reporting.\n");
     PRINTVALSTREAM(rawoutstream, "--------------- File Options ---------------\n");
     PRINTVALSTREAM(rawoutstream, "     -n,   --contents     Print a list of the file contents and exit\n");
     PRINTVALSTREAM(rawoutstream, "                          Optional value 1 also prints attributes.\n");
@@ -254,10 +260,6 @@ usage(const char *prog)
     PRINTVALSTREAM(rawoutstream, "     -q Q, --sort_by=Q    Sort groups and attributes by index Q\n");
     PRINTVALSTREAM(rawoutstream, "     -z Z, --sort_order=Z Sort groups and attributes by order Z\n");
     PRINTVALSTREAM(rawoutstream,
-                   "     --enable-error-stack Prints messages from the HDF5 error stack as they occur.\n");
-    PRINTVALSTREAM(rawoutstream,
-                   "                          Optional value 2 also prints file open errors.\n");
-    PRINTVALSTREAM(rawoutstream,
                    "     --no-compact-subset  Disable compact form of subsetting and allow the use\n");
     PRINTVALSTREAM(rawoutstream, "                          of \"[\" in dataset names.\n");
     PRINTVALSTREAM(rawoutstream,
diff --git a/tools/src/h5ls/h5ls.c b/tools/src/h5ls/h5ls.c
index ca4de28..c30c08f 100644
--- a/tools/src/h5ls/h5ls.c
+++ b/tools/src/h5ls/h5ls.c
@@ -2718,9 +2718,9 @@ main(int argc, char *argv[])
         }
         else if (!HDstrcmp(argv[argno], "--enable-error-stack")) {
             enable_error_stack = 1;
-            /* deprecated --errors */
         }
         else if (!HDstrcmp(argv[argno], "--errors")) {
+            /* deprecated --errors */
             enable_error_stack = 1;
         }
         else if (!HDstrcmp(argv[argno], "--follow-symlinks")) {
diff --git a/tools/src/h5repack/h5repack_main.c b/tools/src/h5repack/h5repack_main.c
index 4c88bd7..a805b3d 100644
--- a/tools/src/h5repack/h5repack_main.c
+++ b/tools/src/h5repack/h5repack_main.c
@@ -31,7 +31,7 @@ const char *outfile = NULL;
  * Command-line options: The user can specify short or long-named
  * parameters.
  */
-static const char *s_opts = "a:b:c:d:e:f:hi:j:k:l:m:no:q:s:t:u:v*z:EG:LM:P:S:T:VXWY:Z:1:2:3:4:5:6:7:8:9:0:";
+static const char *s_opts = "a:b:c:d:e:f:hi:j:k:l:m:no:q:s:t:u:v*z:E*G:LM:P:S:T:VXWY:Z:1:2:3:4:5:6:7:8:9:0:";
 static struct h5_long_options l_opts[] = {{"alignment", require_arg, 'a'},
                                           {"block", require_arg, 'b'},
                                           {"compact", require_arg, 'c'},
@@ -52,7 +52,7 @@ static struct h5_long_options l_opts[] = {{"alignment", require_arg, 'a'},
                                           {"ublock", require_arg, 'u'},
                                           {"verbose", optional_arg, 'v'},
                                           {"sort_order", require_arg, 'z'},
-                                          {"enable-error-stack", no_arg, 'E'},
+                                          {"enable-error-stack", optional_arg, 'E'},
                                           {"fs_pagesize", require_arg, 'G'},
                                           {"latest", no_arg, 'L'},
                                           {"metadata_block_size", require_arg, 'M'},
@@ -92,6 +92,11 @@ usage(const char *prog)
     PRINTSTREAM(rawoutstream, "usage: %s [OPTIONS] file1 file2\n", prog);
     PRINTVALSTREAM(rawoutstream, "  file1                    Input HDF5 File\n");
     PRINTVALSTREAM(rawoutstream, "  file2                    Output HDF5 File\n");
+    PRINTVALSTREAM(rawoutstream, "  ERROR\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "   --enable-error-stack    Prints messages from the HDF5 error stack as they occur.\n");
+    PRINTVALSTREAM(rawoutstream,
+                   "                           Optional value 2 also prints file open errors.\n");
     PRINTVALSTREAM(rawoutstream, "  OPTIONS\n");
     PRINTVALSTREAM(rawoutstream, "   -h, --help              Print a usage message and exit\n");
     PRINTVALSTREAM(rawoutstream, "   -v N, --verbose=N       Verbose mode, print object information.\n");
@@ -99,9 +104,6 @@ usage(const char *prog)
     PRINTVALSTREAM(rawoutstream, "   -V, --version           Print version number and exit\n");
     PRINTVALSTREAM(rawoutstream, "   -n, --native            Use a native HDF5 type when repacking\n");
     PRINTVALSTREAM(rawoutstream,
-                   "   --enable-error-stack    Prints messages from the HDF5 error stack as they\n");
-    PRINTVALSTREAM(rawoutstream, "                           occur\n");
-    PRINTVALSTREAM(rawoutstream,
                    "   --src-vol-value         Value (ID) of the VOL connector to use for opening the\n");
     PRINTVALSTREAM(rawoutstream, "                           input HDF5 file specified\n");
     PRINTVALSTREAM(rawoutstream,
@@ -771,7 +773,10 @@ parse_command_line(int argc, const char *const *argv, pack_opt_t *options)
                 break;
 
             case 'E':
-                enable_error_stack = 1;
+                if (H5_optarg != NULL)
+                    enable_error_stack = HDatoi(H5_optarg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             case '1':
diff --git a/tools/src/h5stat/h5stat.c b/tools/src/h5stat/h5stat.c
index d277356..e42af10 100644
--- a/tools/src/h5stat/h5stat.c
+++ b/tools/src/h5stat/h5stat.c
@@ -169,7 +169,7 @@ struct handler_t {
     char **obj;
 };
 
-static const char *s_opts = "Aa:Ddm:EFfhGgl:sSTO:Vw:H:";
+static const char *s_opts = "Aa:Ddm:E*FfhGgl:sSTO:Vw:H:";
 /* e.g. "filemetadata" has to precede "file"; "groupmetadata" has to precede "group" etc. */
 static struct h5_long_options l_opts[] = {{"help", no_arg, 'h'},
                                           {"filemetadata", no_arg, 'F'},
@@ -181,7 +181,7 @@ static struct h5_long_options l_opts[] = {{"help", no_arg, 'h'},
                                           {"object", require_arg, 'O'},
                                           {"version", no_arg, 'V'},
                                           {"attribute", no_arg, 'A'},
-                                          {"enable-error-stack", no_arg, 'E'},
+                                          {"enable-error-stack", optional_arg, 'E'},
                                           {"numattrs", require_arg, 'a'},
                                           {"freespace", no_arg, 's'},
                                           {"summary", no_arg, 'S'},
@@ -211,6 +211,9 @@ usage(const char *prog)
     HDfflush(stdout);
     HDfprintf(stdout, "Usage: %s [OPTIONS] file\n", prog);
     HDfprintf(stdout, "\n");
+    HDfprintf(stdout, "      ERROR\n");
+    HDfprintf(stdout, "     --enable-error-stack  Prints messages from the HDF5 error stack as they occur\n");
+    HDfprintf(stdout, "                           Optional value 2 also prints file open errors\n");
     HDfprintf(stdout, "      OPTIONS\n");
     HDfprintf(stdout, "     -h, --help            Print a usage message and exit\n");
     HDfprintf(stdout, "     -V, --version         Print version number and exit\n");
@@ -235,7 +238,6 @@ usage(const char *prog)
     HDfprintf(stdout, "                           than 0.  The default threshold is 10.\n");
     HDfprintf(stdout, "     -s, --freespace       Print free space information\n");
     HDfprintf(stdout, "     -S, --summary         Print summary of file space information\n");
-    HDfprintf(stdout, "     --enable-error-stack  Prints messages from the HDF5 error stack as they occur\n");
     HDfprintf(stdout, "     --s3-cred=<cred>      Access file on S3, using provided credential\n");
     HDfprintf(stdout, "                           <cred> :: (region,id,key)\n");
     HDfprintf(stdout, "                           If <cred> == \"(,,)\", no authentication is used.\n");
@@ -852,7 +854,10 @@ parse_command_line(int argc, const char *const *argv, struct handler_t **hand_re
                 break;
 
             case 'E':
-                enable_error_stack = 1;
+                if (H5_optarg != NULL)
+                    enable_error_stack = HDatoi(H5_optarg);
+                else
+                    enable_error_stack = 1;
                 break;
 
             case 'F':