From 5c5e5ca29b20877614d9b1c025b86707e67e548b Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Tue, 11 Jan 2022 15:52:58 -0500 Subject: [PATCH] Document how to add a command-line argument --- README-maintainer | 25 +++++++++++++++++++++++++ job.sums | 4 ++-- job.yml | 1 + libqpdf/QPDFJob_argv.cc | 2 ++ manual/cli.rst | 2 ++ qpdf/qpdf.cc | 1 + 6 files changed, 33 insertions(+), 2 deletions(-) diff --git a/README-maintainer b/README-maintainer index 31634229..d5801070 100644 --- a/README-maintainer +++ b/README-maintainer @@ -122,6 +122,31 @@ CODING RULES since those have to get copied around a lot. +HOW TO ADD A COMMAND-LINE ARGUMENT + +Command-line arguments are closely coupled with QPDFJob. To add a new +command-line argument, add the option to the appropriate table in +job.yml. This will automatically declare a method in the private +ArgParser class in QPDFJob_argv.cc which you have to implement. The +implementation should make calls to methods in QPDFJob. + +The build will fail until the new option is documented in +manual/cli.rst. To do that, create documentation for the option by +adding a ".. qpdf:option::" directive followed by a magic help comment +as described at the top of manual/cli.rst. Put this in the correct +help topic. Help topics roughly correspond with sections in that +chapter and are created using a special ".. help-topic" comment. +Follow the example of other options for style. + +When done, the following should happen: + +* qpdf --new-option should work as expected +* qpdf --help=--new-option should show the help from the comment in cli.rst +* qpdf --help=topic should list --new-option for the correct topic +* --new-option should appear in the manual +* --new-option should be in the command-line option index in the manual + + RELEASE PREPARATION * Each year, update copyright notices. This will find all relevant diff --git a/job.sums b/job.sums index 0e168ab3..b2742e66 100644 --- a/job.sums +++ b/job.sums @@ -1,8 +1,8 @@ # Generated by generate_auto_job generate_auto_job 466aa9211549cebeb3fedc6413108981aeeddd89936621095f5f5223cee9880b -job.yml 25c85cba1ae01dac9cd0f9cb7b734e7e3e531c0023ea2b892dc0d40bda1c1146 +job.yml 8177cadf41096efdc174f04daadfe5d98c592ad44ad10cb96537521fd79a801a libqpdf/qpdf/auto_job_decl.hh 97395ecbe590b23ae04d6cce2080dbd0e998917ff5eeaa5c6aafa91041d3cd6a libqpdf/qpdf/auto_job_help.hh fa7ff1d1f6289881ac3a485107d15240c4992c59cff506be425354557108d184 libqpdf/qpdf/auto_job_init.hh 465bf46769559ceb77110d1b9d3293ba9b3595850b49848c31aeabd10aadb4ad manual/_ext/qpdf.py 855fe12de5af7a10bb24be6ecc4d5dff4c84ac58cf388a13be6bbb394346a67d -manual/cli.rst c26e877d2065ac917edffdd6a037d2191b64d7c25beb4e8df1acc174b20b3ff4 +manual/cli.rst 7a36de7413b5c2867de573b5a9beff862e28c46123b72d08e3971ddf5bdf3bbe diff --git a/job.yml b/job.yml index dfe64dd8..fa15e290 100644 --- a/job.yml +++ b/job.yml @@ -1,3 +1,4 @@ +# See "HOW TO ADD A COMMAND-LINE ARGUMENT" in README-maintainer. choices: yn: - "y" diff --git a/libqpdf/QPDFJob_argv.cc b/libqpdf/QPDFJob_argv.cc index da0bcd4a..647311bf 100644 --- a/libqpdf/QPDFJob_argv.cc +++ b/libqpdf/QPDFJob_argv.cc @@ -1,5 +1,7 @@ #include +// See "HOW TO ADD A COMMAND-LINE ARGUMENT" in README-maintainer. + #include #include #include diff --git a/manual/cli.rst b/manual/cli.rst index ebeaed81..7ae4c485 100644 --- a/manual/cli.rst +++ b/manual/cli.rst @@ -1,5 +1,7 @@ .. NOTES + See "HOW TO ADD A COMMAND-LINE ARGUMENT" in README-maintainer. + This file contains text that is used for help file generation. Lines that start with the magic comment ".. help topic x: y" introduce a help topic called "x" with short text "y". The contents diff --git a/qpdf/qpdf.cc b/qpdf/qpdf.cc index bb57e88b..77fb8cb1 100644 --- a/qpdf/qpdf.cc +++ b/qpdf/qpdf.cc @@ -43,6 +43,7 @@ int realmain(int argc, char* argv[]) bool errors = false; try { + // See "HOW TO ADD A COMMAND-LINE ARGUMENT" in README-maintainer. j.initializeFromArgv(argc, argv); j.run(); }