Synchronize command-line option documentation

Command-line options are described in the following places:

- .rst file "SYNOPSIS" section
- .rst file "OPTIONS" section
- parameters to getopt()
- results of getopt() that are actually handled
- a usage() or xusage() function
- occasionally, a long form in usage()/xusage()
- occasionally, libss subcommand specifications

Over time, these have drifted.  Make an effort to correct this drift,
marking deprecated options as such.  For consistency, remove mention
of long arguments that have an equivalent short form.

(cherry picked from commit bd912c8583261f1f2521a06e5c05757cec032580)

ticket: 8987
version_fixed: 1.19.1

9 files changed, 33 insertions, 52 deletions

diff --git a/src/build-tools/krb5-config.in b/src/build-tools/krb5-config.in
index 9f96a87..dead0dd 100755
--- a/src/build-tools/krb5-config.in
+++ b/src/build-tools/krb5-config.in
@@ -70,8 +70,7 @@ while test $# != 0; do
 	--defktname)
 	    do_defktname=1
 	    ;;
-	--deps)
-	    do_deps=1
+	--deps) # historically a no-op
 	    ;;
 	--exec-prefix)
 	    do_exec_prefix=1
diff --git a/src/clients/kinit/kinit.c b/src/clients/kinit/kinit.c
index e5ebeb8..d1f5d74 100644
--- a/src/clients/kinit/kinit.c
+++ b/src/clients/kinit/kinit.c
@@ -139,32 +139,20 @@ const char *shopts = "r:fpFPn54aAVl:s:c:kit:T:RS:vX:CEI:";
 static void
 usage()
 {
-    fprintf(stderr, "Usage: %s [-V] "
-            "[-l lifetime] [-s start_time] "
-            USAGE_BREAK
-            "[-r renewable_life] "
-            "[-f | -F | --forwardable | --noforwardable] "
-            USAGE_BREAK
-            "[-p | -P | --proxiable | --noproxiable] "
-            USAGE_BREAK
-            "-n "
-            "[-a | -A | --addresses | --noaddresses] "
-            USAGE_BREAK
-            "[--request-pac | --no-request-pac] "
-            USAGE_BREAK
-            "[-C | --canonicalize] "
-            USAGE_BREAK
-            "[-E | --enterprise] "
-            USAGE_BREAK
-            "[-v] [-R] "
-            "[-k [-i|-t keytab_file]] "
-            "[-c cachename] "
-            USAGE_BREAK
-            "[-S service_name] [-T ticket_armor_cache]"
-            USAGE_BREAK
-            "[-X <attribute>[=<value>]] [principal]"
-            "\n\n",
-            progname);
+    fprintf(stderr,
+            _("Usage: %s [-V] [-l lifetime] [-s start_time] "
+              "[-r renewable_life]"
+              USAGE_BREAK
+              "[-f | -F] [-p | -P] [-n] [-a | -A] [-C] [-E]"
+              USAGE_BREAK
+              "[--request-pac | --no-request-pac] "
+              USAGE_BREAK
+              "[-v] [-R] [-k [-i|-t keytab_file]] [-c cachename]"
+              USAGE_BREAK
+              "[-S service_name] [-I input_ccache] [-T ticket_armor_cache]"
+              USAGE_BREAK
+              "[-X <attribute>[=<value>]] [principal]"
+              "\n\n"), progname);
 
     fprintf(stderr, "    options:\n");
     fprintf(stderr, _("\t-V verbose\n"));
@@ -187,8 +175,11 @@ usage()
     fprintf(stderr, _("\t-t filename of keytab to use\n"));
     fprintf(stderr, _("\t-c Kerberos 5 cache name\n"));
     fprintf(stderr, _("\t-S service\n"));
+    fprintf(stderr, _("\t-I input credential cache\n"));
     fprintf(stderr, _("\t-T armor credential cache\n"));
     fprintf(stderr, _("\t-X <attribute>[=<value>]\n"));
+    fprintf(stderr,
+            _("\t--{,no}-request-pac request KDC include/exclude a PAC\n"));
     exit(2);
 }
 
diff --git a/src/clients/klist/klist.c b/src/clients/klist/klist.c
index a54e378..dcdc5a2 100644
--- a/src/clients/klist/klist.c
+++ b/src/clients/klist/klist.c
@@ -83,7 +83,8 @@ static void
 usage()
 {
     fprintf(stderr, _("Usage: %s [-e] [-V] [[-c] [-l] [-A] [-d] [-f] [-s] "
-                      "[-a [-n]]] [-k [-t] [-K]] [name]\n"), progname);
+                      "[-a [-n]]] [-k [-i] [-t] [-K]] [-C] [name]\n"),
+            progname);
     fprintf(stderr, _("\t-c specifies credentials cache\n"));
     fprintf(stderr, _("\t-k specifies keytab\n"));
     fprintf(stderr, _("\t   (Default is credentials cache)\n"));
@@ -103,6 +104,7 @@ usage()
     fprintf(stderr, _("\toptions for keytabs:\n"));
     fprintf(stderr, _("\t\t-t shows keytab entry timestamps\n"));
     fprintf(stderr, _("\t\t-K shows keytab entry keys\n"));
+    fprintf(stderr, _("\t\t-C includes configuration data entries\n"));
     exit(1);
 }
 
diff --git a/src/kadmin/cli/kadmin.c b/src/kadmin/cli/kadmin.c
index 225cd2b..f3ea6fa 100644
--- a/src/kadmin/cli/kadmin.c
+++ b/src/kadmin/cli/kadmin.c
@@ -104,9 +104,9 @@ usage()
             "[clnt|local args]\n"
             "              [command args...]\n"
             "\tclnt args: [-s admin_server[:port]] "
-            "[[-c ccache]|[-k [-t keytab]]]|[-n]\n"
+            "[[-c ccache]|[-k [-t keytab]]]|[-n] [-O | -N]\n"
             "\tlocal args: [-x db_args]* [-d dbname] "
-            "[-e \"enc:salt ...\"] [-m]"
+            "[-e \"enc:salt ...\"] [-m] [-w password] "
             "where,\n\t[-x db_args]* - any number of database specific "
             "arguments.\n"
             "\t\t\tLook at each database documentation for supported "
diff --git a/src/kadmin/dbutil/dump.c b/src/kadmin/dbutil/dump.c
index ff2f250..634ba4a 100644
--- a/src/kadmin/dbutil/dump.c
+++ b/src/kadmin/dbutil/dump.c
@@ -1161,12 +1161,6 @@ current_dump_sno_in_ulog(krb5_context context, const char *ifile)
     return status == UPDATE_OK || status == UPDATE_NIL;
 }
 
-/*
- * usage is:
- *      dump_db [-b7] [-r13] [-r18] [-verbose] [-mkey_convert]
- *              [-new_mkey_file mkey_file] [-rev] [-recurse]
- *              [filename [principals...]]
- */
 void
 dump_db(int argc, char **argv)
 {
@@ -1205,6 +1199,7 @@ dump_db(int argc, char **argv)
         } else if (!strcmp(argv[aindex], "-r18")) {
             dump = &r1_8_version;
         } else if (!strncmp(argv[aindex], "-i", 2)) {
+            /* Intentionally undocumented - only used by kadmin. */
             if (log_ctx && log_ctx->iproprole) {
                 /* ipropx_version is the maximum version acceptable. */
                 ipropx_version = atoi(argv[aindex] + 2);
@@ -1411,9 +1406,6 @@ restore_dump(krb5_context context, char *dumpfile, FILE *f,
     return 0;
 }
 
-/*
- * Usage: load_db [-b7] [-r13] [-r18] [-verbose] [-update] [-hash] filename
- */
 void
 load_db(int argc, char **argv)
 {
@@ -1443,6 +1435,7 @@ load_db(int argc, char **argv)
         } else if (!strcmp(argv[aindex], "-r18")){
             load = &r1_8_version;
         } else if (!strcmp(argv[aindex], "-i")) {
+            /* Intentionally undocumented - only used by kadmin. */
             if (log_ctx && log_ctx->iproprole) {
                 load = &iprop_version;
                 iprop_load = TRUE;
diff --git a/src/kadmin/dbutil/kdb5_util.c b/src/kadmin/dbutil/kdb5_util.c
index 024edb1..19a5925 100644
--- a/src/kadmin/dbutil/kdb5_util.c
+++ b/src/kadmin/dbutil/kdb5_util.c
@@ -85,10 +85,10 @@ void usage()
               "\tcreate  [-s]\n"
               "\tdestroy [-f]\n"
               "\tstash   [-f keyfile]\n"
-              "\tdump    [-old|-b6|-b7|-r13|-r18] [-verbose]\n"
+              "\tdump    [-b7|-r13|-r18] [-verbose]\n"
               "\t        [-mkey_convert] [-new_mkey_file mkey_file]\n"
               "\t        [-rev] [-recurse] [filename [princs...]]\n"
-              "\tload    [-old|-b6|-b7|-r13|-r18] [-verbose] [-update] "
+              "\tload    [-b7|-r13|-r18] [-hash] [-verbose] [-update] "
               "filename\n"
               "\tark     [-e etype_list] principal\n"
               "\tadd_mkey [-e etype] [-s]\n"
diff --git a/src/kadmin/dbutil/tabdump.c b/src/kadmin/dbutil/tabdump.c
index 2f313db..da55c2d 100644
--- a/src/kadmin/dbutil/tabdump.c
+++ b/src/kadmin/dbutil/tabdump.c
@@ -602,10 +602,6 @@ cleanup_args(struct rec_args *args)
         fclose(args->f);
 }
 
-/*
- * Usaage is:
- *     tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype
- */
 void
 tabdump(int argc, char **argv)
 {
diff --git a/src/kdc/main.c b/src/kdc/main.c
index 27aa10d..3be6dcb 100644
--- a/src/kdc/main.c
+++ b/src/kdc/main.c
@@ -605,7 +605,7 @@ usage(char *name)
 {
     fprintf(stderr,
             _("usage: %s [-x db_args]* [-d dbpathname] [-r dbrealmname]\n"
-              "\t\t[-R replaycachename] [-m] [-k masterenctype]\n"
+              "\t\t[-T time_offset] [-m] [-k masterenctype]\n"
               "\t\t[-M masterkeyname] [-p port] [-P pid_file]\n"
               "\t\t[-n] [-w numworkers] [/]\n\n"
               "where,\n"
@@ -697,7 +697,7 @@ initialize_realms(krb5_context kcontext, int argc, char **argv,
      * twice if worker processes are used, so we must initialize optind.
      */
     optind = 1;
-    while ((c = getopt(argc, argv, "x:r:d:mM:k:R:e:P:p:s:nw:4:T:X3")) != -1) {
+    while ((c = getopt(argc, argv, "x:r:d:mM:k:R:P:p:nw:4:T:X3")) != -1) {
         switch(c) {
         case 'x':
             db_args_size++;
diff --git a/src/kprop/kpropd.c b/src/kprop/kpropd.c
index 874ba13..498ca59 100644
--- a/src/kprop/kpropd.c
+++ b/src/kprop/kpropd.c
@@ -167,11 +167,11 @@ static void
 usage()
 {
     fprintf(stderr,
-            _("\nUsage: %s [-r realm] [-s keytab] [-dS] [-f replica_file]\n"),
+            _("\nUsage: %s [-r realm] [-s keytab] [-d] [-D] [-S]\n"
+              "\t[-f replica_file] [-F kerberos_db_file ]\n"
+              "\t[-p kdb5_util_pathname] [-x db_args]* [-P port]\n"
+              "\t[-a acl_file] [-A admin_server] [--pid-file=pid_file]\n"),
             progname);
-    fprintf(stderr, _("\t[-F kerberos_db_file ] [-p kdb5_util_pathname]\n"));
-    fprintf(stderr, _("\t[-x db_args]* [-P port] [-a acl_file]\n"));
-    fprintf(stderr, _("\t[-A admin_server] [--pid-file=pid_file]\n"));
     exit(1);
 }