Improve top-level help information

Jay Berkenbilt
1 parent 03640247
Showing 9 changed files with 26 additions and 14 deletions
generate_auto_job
job.sums
libqpdf/QPDFArgParser.cc
libqpdf/qpdf/auto_job_help.hh
libtests/qtest/arg_parser/help-all.out
libtests/qtest/arg_parser/help.out
manual/cli.rst
qpdf/qpdf.cc
qpdf/qtest/qpdf/split-pages-stdout.out
@@ -159,7 +159,7 @@ class Main:
                 if long_text == '':
                     raise Exception(f'missing long text for {topic}')
                 long_text += '\n'
-                if topic != '--help':
+                if 'help' not in topic:
                     # Help for --help itself has --help=... not
                     # referring to specific options.
                     for i in re.finditer(r'--help=([^\.\s]+)', long_text):
 # Generated by generate_auto_job
-generate_auto_job bc2f0e8cecebe8b11950cf37714a646fd5a1d294839b748d1c499353226dd642
+generate_auto_job 27d219c995864896b1c4a42f303bc3bebb198d9b90d275b727645013c8f6a33e
 include/qpdf/auto_job_c_att.hh 7ad43bb374c1370ef32ebdcdcb7b73a61d281f7f4e3f12755585872ab30fb60e
 include/qpdf/auto_job_c_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee
 include/qpdf/auto_job_c_enc.hh 72e138c7b96ed5aacdce78c1dec04b1c20d361faec4f8faf52f64c1d6be99265
@@ -8,8 +8,8 @@ include/qpdf/auto_job_c_pages.hh 931840b329a36ca0e41401190e04537b47f2867671a6643
 include/qpdf/auto_job_c_uo.hh 0585b7de459fa479d9e51a45fa92de0ff6dee748efc9ec1cedd0dde6cee1ad50
 job.yml 1590fd16fd17ed40db9aa56b6713c844cfd61b3a6d0441a3ccd122b7371c68e9
 libqpdf/qpdf/auto_job_decl.hh 9f79396ec459f191be4c5fe34cf88c265cf47355a1a945fa39169d1c94cf04f6
-libqpdf/qpdf/auto_job_help.hh 05cddfb81ed7fb58a8249b912890e560cb76bd51389d64eae6c662ca552c87d9
+libqpdf/qpdf/auto_job_help.hh 30dd97f36c6cd748fc53fcb8d864140e32274437ffdf12f609ed04150ad61858
 libqpdf/qpdf/auto_job_init.hh 3b6323189480a7d782563c9d2b5bc29b8dcd19c6dcc89840b207e38cb503d3f1
 libqpdf/qpdf/auto_job_schema.hh 1c3b4b5488270f8d200ed345573e3a241f15baff6fb7e97ec3d044103b2546d9
 manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3
-manual/cli.rst 9aecd2905844fbda5cd528afd7fedef693ac0958bcb20e235f1c8e10a1896abe
+manual/cli.rst 1cf74ad0956e51e919287f9dc93574764510856f562333a195775407551958a2
@@ -920,7 +920,7 @@ QPDFArgParser::getTopHelp(std::ostringstream&amp; msg)
     msg << "Run \"" << this->m->whoami
         << " --help=topic\" for help on a topic." << std::endl
         << "Run \"" << this->m->whoami
-        << " --help=option\" for help on an option." << std::endl
+        << " --help=--option\" for help on an option." << std::endl
         << "Run \"" << this->m->whoami
         << " --help=all\" to see all available help." << std::endl
         << std::endl
@@ -8,8 +8,8 @@ static void add_help_1(QPDFArgParser&amp; ap)
 ap.addHelpTopic("usage", "basic invocation", R"(Read a PDF file, apply transformations or modifications, and write
 a new PDF file.
-Usage: qpdf infile [options] [outfile]
-   OR  qpdf help-option
+Usage: qpdf [infile] [options] [outfile]
+   OR  qpdf --help[={topic|--option}]
 - infile, options, and outfile may be in any order as long as infile
   precedes outfile.
 Run "arg_parser --help=topic" for help on a topic.
-Run "arg_parser --help=option" for help on an option.
+Run "arg_parser --help=--option" for help on an option.
 Run "arg_parser --help=all" to see all available help.
 Topics:
 Run "arg_parser --help=topic" for help on a topic.
-Run "arg_parser --help=option" for help on an option.
+Run "arg_parser --help=--option" for help on an option.
 Run "arg_parser --help=all" to see all available help.
 Topics:
@@ -68,8 +68,8 @@ Basic Invocation
    Read a PDF file, apply transformations or modifications, and write
    a new PDF file.
-   Usage: qpdf infile [options] [outfile]
-      OR  qpdf help-option
+   Usage: qpdf [infile] [options] [outfile]
+      OR  qpdf --help[={topic|--option}]
    - infile, options, and outfile may be in any order as long as infile
      precedes outfile.
@@ -84,7 +84,7 @@ Basic Invocation
 ::
-   Usage: qpdf infile [options] [outfile]
+   Usage: qpdf [infile] [options] [outfile]
 The :command:`qpdf` command reads the PDF file :samp:`{infile}`,
 applies various transformations or modifications to the file in
@@ -23,7 +23,15 @@ static void usageExit(std::string const&amp; msg)
 	<< std::endl
 	<< whoami << ": " << msg << std::endl
 	<< std::endl
-	<< "For detailed help, run " << whoami << " --help" << std::endl
+	<< "For help:" << std::endl
+        << "  " << whoami << "--help=usage       usage information"
+        << std::endl
+        << "  " << whoami << "--help=topic       help on a topic"
+        << std::endl
+        << "  " << whoami << "--help=--option    help on an option"
+        << std::endl
+        << "  " << whoami << "--help             general help and a topic list"
+        << std::endl
 	<< std::endl;
     exit(EXIT_ERROR);
 }
 qpdf: --split-pages may not be used when writing to standard output
-For detailed help, run qpdf --help
+For help:
+  qpdf--help=usage       usage information
+  qpdf--help=topic       help on a topic
+  qpdf--help=--option    help on an option
+  qpdf--help             general help and a topic list