Document how to add a command-line argument

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 <qpdf/QPDFJob.hh>
 
+// See "HOW TO ADD A COMMAND-LINE ARGUMENT" in README-maintainer.
+
 #include <iostream>
 #include <string.h>
 #include <stdlib.h>
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();
     }