From 0e909bab8e6eabb96b0bbe8063138d04d5a4ac7f Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Fri, 28 Jan 2022 07:48:22 -0500 Subject: [PATCH] Improve top-level help information --- generate_auto_job | 2 +- job.sums | 6 +++--- libqpdf/QPDFArgParser.cc | 2 +- libqpdf/qpdf/auto_job_help.hh | 4 ++-- libtests/qtest/arg_parser/help-all.out | 2 +- libtests/qtest/arg_parser/help.out | 2 +- manual/cli.rst | 6 +++--- qpdf/qpdf.cc | 10 +++++++++- qpdf/qtest/qpdf/split-pages-stdout.out | 6 +++++- 9 files changed, 26 insertions(+), 14 deletions(-) diff --git a/generate_auto_job b/generate_auto_job index 4dfd93cd..e7477fa4 100755 --- a/generate_auto_job +++ b/generate_auto_job @@ -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): diff --git a/job.sums b/job.sums index 42b88cc1..1a1ed40f 100644 --- a/job.sums +++ b/job.sums @@ -1,5 +1,5 @@ # 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 diff --git a/libqpdf/QPDFArgParser.cc b/libqpdf/QPDFArgParser.cc index 4018d4e1..194f5b16 100644 --- a/libqpdf/QPDFArgParser.cc +++ b/libqpdf/QPDFArgParser.cc @@ -920,7 +920,7 @@ QPDFArgParser::getTopHelp(std::ostringstream& 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 diff --git a/libqpdf/qpdf/auto_job_help.hh b/libqpdf/qpdf/auto_job_help.hh index f6d9ecc5..b50025e4 100644 --- a/libqpdf/qpdf/auto_job_help.hh +++ b/libqpdf/qpdf/auto_job_help.hh @@ -8,8 +8,8 @@ static void add_help_1(QPDFArgParser& 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. diff --git a/libtests/qtest/arg_parser/help-all.out b/libtests/qtest/arg_parser/help-all.out index 3f1d0d16..d8fcf075 100644 --- a/libtests/qtest/arg_parser/help-all.out +++ b/libtests/qtest/arg_parser/help-all.out @@ -1,5 +1,5 @@ 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: diff --git a/libtests/qtest/arg_parser/help.out b/libtests/qtest/arg_parser/help.out index 0accbe67..d019b080 100644 --- a/libtests/qtest/arg_parser/help.out +++ b/libtests/qtest/arg_parser/help.out @@ -1,5 +1,5 @@ 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: diff --git a/manual/cli.rst b/manual/cli.rst index 2150df70..1c283598 100644 --- a/manual/cli.rst +++ b/manual/cli.rst @@ -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 diff --git a/qpdf/qpdf.cc b/qpdf/qpdf.cc index 508fb579..953d0291 100644 --- a/qpdf/qpdf.cc +++ b/qpdf/qpdf.cc @@ -23,7 +23,15 @@ static void usageExit(std::string const& 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); } diff --git a/qpdf/qtest/qpdf/split-pages-stdout.out b/qpdf/qtest/qpdf/split-pages-stdout.out index 67dfdb6d..212006f6 100644 --- a/qpdf/qtest/qpdf/split-pages-stdout.out +++ b/qpdf/qtest/qpdf/split-pages-stdout.out @@ -1,5 +1,9 @@ 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