From: Rich Salz <rsalz@akamai.com>
Date: Fri, 20 Sep 2019 01:33:17 +0000 (-0400)
Subject: Document command parameters.
X-Git-Tag: openssl-3.0.0-alpha1~931
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=92de469fbd62a77a36dad5fde3a0ac7034071a59;p=oweals%2Fopenssl.git

Document command parameters.

Add documentation for all commands that have parameters.
Fix a couple of minor doc and programming bugs, too.

Fixes #10313

Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10371)
---

diff --git a/apps/ca.c b/apps/ca.c
index 824c022502..f201efe3af 100644
--- a/apps/ca.c
+++ b/apps/ca.c
@@ -154,6 +154,8 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS ca_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [certreq...]\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
     {"verbose", OPT_VERBOSE, '-', "Verbose output during processing"},
@@ -235,6 +237,9 @@ const OPTIONS ca_options[] = {
     {"revoke", OPT_REVOKE, '<', "Revoke a cert (given in file)"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"certreq", 0, 0, "Certificate requests to be signed (optional)"},
     {NULL}
 };
 
diff --git a/apps/ciphers.c b/apps/ciphers.c
index c2ac40a3b5..280a5ab477 100644
--- a/apps/ciphers.c
+++ b/apps/ciphers.c
@@ -31,6 +31,8 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS ciphers_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [cipher]\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
 
@@ -65,6 +67,9 @@ const OPTIONS ciphers_options[] = {
 #endif
     {"ciphersuites", OPT_CIPHERSUITES, 's',
      "Configure the TLSv1.3 ciphersuites to use"},
+
+    OPT_PARAMETERS(),
+    {"cipher", 0, 0, "Cipher string to decode (optional)"},
     {NULL}
 };
 
diff --git a/apps/cms.c b/apps/cms.c
index c30bd62bb1..d67116d3fc 100644
--- a/apps/cms.c
+++ b/apps/cms.c
@@ -88,9 +88,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS cms_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [options] cert.pem...\n"},
-    {OPT_HELP_STR, 1, '-',
-        "  cert.pem... recipient certs for encryption\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [cert...]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -219,6 +217,9 @@ const OPTIONS cms_options[] = {
 
     OPT_R_OPTIONS,
     OPT_V_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"cert", 0, 0, "Recipient certs (optional; used only when encrypting)"},
     {NULL}
 };
 
diff --git a/apps/dgst.c b/apps/dgst.c
index 7e1afb9bba..21f0f01787 100644
--- a/apps/dgst.c
+++ b/apps/dgst.c
@@ -47,8 +47,7 @@ typedef enum OPTION_choice {
 
 const OPTIONS dgst_options[] = {
     {OPT_HELP_STR, 1, '-', "Usage: %s [options] [file...]\n"},
-    {OPT_HELP_STR, 1, '-',
-        "  file... files to digest (default is stdin)\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
     {"list", OPT_LIST, '-', "List digests"},
@@ -83,6 +82,9 @@ const OPTIONS dgst_options[] = {
      "Compute HMAC with the key used in OpenSSL-FIPS fingerprint"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"file", 0, 0, "Files to digest (optional; default is stdin)"},
     {NULL}
 };
 
diff --git a/apps/dhparam.c b/apps/dhparam.c
index 74758a5dee..7a61241f92 100644
--- a/apps/dhparam.c
+++ b/apps/dhparam.c
@@ -42,7 +42,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS dhparam_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [flags] [numbits]\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [numbits]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -70,6 +70,9 @@ const OPTIONS dhparam_options[] = {
     {"5", OPT_5, '-', "Generate parameters using 5 as the generator value"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"numbits", 0, 0, "Number of bits if generating parameters (optional)"},
     {NULL}
 };
 
diff --git a/apps/dsaparam.c b/apps/dsaparam.c
index bea5de3dba..17068fb9d0 100644
--- a/apps/dsaparam.c
+++ b/apps/dsaparam.c
@@ -37,6 +37,8 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS dsaparam_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [numbits]\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
 # ifndef OPENSSL_NO_ENGINE
@@ -57,6 +59,9 @@ const OPTIONS dsaparam_options[] = {
     {"genkey", OPT_GENKEY, '-', "Generate a DSA key"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"numbits", 0, 0, "Number of bits if generating parameters (optional)"},
     {NULL}
 };
 
diff --git a/apps/engine.c b/apps/engine.c
index 24dff22c54..a71e111016 100644
--- a/apps/engine.c
+++ b/apps/engine.c
@@ -30,8 +30,6 @@ typedef enum OPTION_choice {
 
 const OPTIONS engine_options[] = {
     {OPT_HELP_STR, 1, '-', "Usage: %s [options] engine...\n"},
-    {OPT_HELP_STR, 1, '-',
-        "  engine... Engines to load\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -48,6 +46,9 @@ const OPTIONS engine_options[] = {
     {"tt", OPT_TT, '-', "Display error trace for unavailable engines"},
     {OPT_MORE_STR, OPT_EOF, 1,
      "Commands are like \"SO_PATH:/lib/libdriver.so\""},
+
+    OPT_PARAMETERS(),
+    {"engine", 0, 0, "ID of engine(s) to load"},
     {NULL}
 };
 
diff --git a/apps/errstr.c b/apps/errstr.c
index 212b7293cd..9e97698be3 100644
--- a/apps/errstr.c
+++ b/apps/errstr.c
@@ -22,10 +22,12 @@ typedef enum OPTION_choice {
 
 const OPTIONS errstr_options[] = {
     {OPT_HELP_STR, 1, '-', "Usage: %s [options] errnum...\n"},
-    {OPT_HELP_STR, 1, '-', "  errnum  Error number\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
+
+    OPT_PARAMETERS(),
+    {"errnum", 0, 0, "Error number(s) to decode"},
     {NULL}
 };
 
diff --git a/apps/fipsinstall.c b/apps/fipsinstall.c
index 8846779932..3b19ef15a8 100644
--- a/apps/fipsinstall.c
+++ b/apps/fipsinstall.c
@@ -34,8 +34,8 @@ typedef enum OPTION_choice {
 const OPTIONS fipsinstall_options[] = {
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
-    {"verify", OPT_VERIFY, '-', "Verification mode, i.e verify a config file "
-     "instead of generating one"},
+    {"verify", OPT_VERIFY, '-',
+        "Verify a config file instead of generating one"},
     {"module", OPT_MODULE, '<', "File name of the provider module"},
     {"provider_name", OPT_PROV_NAME, 's', "FIPS provider name"},
     {"section_name", OPT_SECTION_NAME, 's',
diff --git a/apps/gendsa.c b/apps/gendsa.c
index 45ae815fd4..12806ef2dd 100644
--- a/apps/gendsa.c
+++ b/apps/gendsa.c
@@ -32,7 +32,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS gendsa_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [args] dsaparam-file\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] dsaparam-file\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -46,6 +46,9 @@ const OPTIONS gendsa_options[] = {
     OPT_R_OPTIONS,
     {"", OPT_CIPHER, '-', "Encrypt the output with any supported cipher"},
     {"verbose", OPT_VERBOSE, '-', "Verbose output"},
+
+    OPT_PARAMETERS(),
+    {"dsaparam-file", 0, 0, "File containing DSA parameters"},
     {NULL}
 };
 
diff --git a/apps/genrsa.c b/apps/genrsa.c
index fe57547f33..96fb23aaf5 100644
--- a/apps/genrsa.c
+++ b/apps/genrsa.c
@@ -42,6 +42,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS genrsa_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] numbits\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -62,6 +63,9 @@ const OPTIONS genrsa_options[] = {
     {"", OPT_CIPHER, '-', "Encrypt the output with any supported cipher"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"numbits", 0, 0, "Size of key in bits"},
     {NULL}
 };
 
diff --git a/apps/include/opt.h b/apps/include/opt.h
index 59bfdcfefb..ac2c236024 100644
--- a/apps/include/opt.h
+++ b/apps/include/opt.h
@@ -271,6 +271,8 @@
 extern const char OPT_HELP_STR[];
 extern const char OPT_MORE_STR[];
 extern const char OPT_SECTION_STR[];
+extern const char OPT_PARAM_STR[];
+
 typedef struct options_st {
     const char *name;
     int retval;
@@ -314,6 +316,7 @@ typedef struct string_int_pair_st {
 
 /* Divide options into sections when displaying usage */
 #define OPT_SECTION(sec) { OPT_SECTION_STR, 1, '-', sec " options:\n" }
+#define OPT_PARAMETERS() { OPT_PARAM_STR, 1, '-', "Parameters:\n" }
 
 char *opt_progname(const char *argv0);
 char *opt_getprog(void);
@@ -346,7 +349,7 @@ int opt_num_rest(void);
 int opt_verify(int i, X509_VERIFY_PARAM *vpm);
 int opt_rand(int i);
 void opt_help(const OPTIONS * list);
-void opt_print(const OPTIONS * opt, int width);
+void opt_print(const OPTIONS * opt, int doingparams, int width);
 int opt_format_error(const char *s, unsigned long flags);
 int opt_isdir(const char *name);
 int opt_printf_stderr(const char *fmt, ...);
diff --git a/apps/kdf.c b/apps/kdf.c
index abd21cee51..66e7e7a7c1 100644
--- a/apps/kdf.c
+++ b/apps/kdf.c
@@ -24,18 +24,20 @@ typedef enum OPTION_choice {
 
 const OPTIONS kdf_options[] = {
     {OPT_HELP_STR, 1, '-', "Usage: %s [options] kdf_name\n"},
-    {OPT_HELP_STR, 1, '-', "kdf_name\t KDF algorithm.\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
-    {"kdfopt", OPT_KDFOPT, 's', "KDF algorithm control parameters in n:v form."},
-    {OPT_HELP_STR, 1, '-', "See 'Supported Controls' in the EVP_KDF_ docs"},
+    {"kdfopt", OPT_KDFOPT, 's', "KDF algorithm control parameters in n:v form"},
+    {OPT_MORE_STR, 1, '-', "See 'Supported Controls' in the EVP_KDF_ docs\n"},
     {"keylen", OPT_KEYLEN, 's', "The size of the output derived key"},
 
     OPT_SECTION("Output"),
     {"out", OPT_OUT, '>', "Output to filename rather than stdout"},
-    {"binary", OPT_BIN, '-', "Output in binary format (Default is hexadecimal "
-                             "output)"},
+    {"binary", OPT_BIN, '-',
+        "Output in binary format (default is hexadecimal)"},
+
+    OPT_PARAMETERS(),
+    {"kdf_name", 0, 0, "Name of the KDF algorithm"},
     {NULL}
 };
 
diff --git a/apps/lib/opt.c b/apps/lib/opt.c
index 2b9c922135..2a80e7ebf4 100644
--- a/apps/lib/opt.c
+++ b/apps/lib/opt.c
@@ -26,9 +26,10 @@
 #include <openssl/x509v3.h>
 
 #define MAX_OPT_HELP_WIDTH 30
-const char OPT_HELP_STR[] = "--";
-const char OPT_MORE_STR[] = "---";
-const char OPT_SECTION_STR[] = "----";
+const char OPT_HELP_STR[] = "-H";
+const char OPT_MORE_STR[] = "-M";
+const char OPT_SECTION_STR[] = "-S";
+const char OPT_PARAM_STR[] = "-P";
 
 /* Our state */
 static char **argv;
@@ -128,7 +129,8 @@ char *opt_init(int ac, char **av, const OPTIONS *o)
     opt_progname(av[0]);
     unknown = NULL;
 
-    for (; o->name; ++o) {
+    /* Check all options up until the PARAM marker (if present) */
+    for (; o->name != NULL && o->name != OPT_PARAM_STR; ++o) {
 #ifndef NDEBUG
         const OPTIONS *next;
         int duplicated, i;
@@ -838,7 +840,7 @@ static const char *valtype2param(const OPTIONS *o)
     return "parm";
 }
 
-void opt_print(const OPTIONS *o, int width)
+void opt_print(const OPTIONS *o, int doingparams, int width)
 {
     const char* help;
     char start[80 + 1];
@@ -854,6 +856,10 @@ void opt_print(const OPTIONS *o, int width)
             opt_printf_stderr(help, prog);
             return;
         }
+        if (o->name == OPT_PARAM_STR) {
+            opt_printf_stderr("\nParameters:\n");
+            return;
+        }
 
         /* Pad out prefix */
         memset(start, ' ', sizeof(start) - 1);
@@ -869,7 +875,8 @@ void opt_print(const OPTIONS *o, int width)
         /* Build up the "-flag [param]" part. */
         p = start;
         *p++ = ' ';
-        *p++ = '-';
+        if (!doingparams)
+            *p++ = '-';
         if (o->name[0])
             p += strlen(strcpy(p, o->name));
         else
@@ -891,9 +898,8 @@ void opt_print(const OPTIONS *o, int width)
 void opt_help(const OPTIONS *list)
 {
     const OPTIONS *o;
-    int i;
+    int i, sawparams = 0, width = 5;
     int standard_prolog;
-    int width = 5;
     char start[80 + 1];
 
     /* Starts with its own help message? */
@@ -919,7 +925,9 @@ void opt_help(const OPTIONS *list)
 
     /* Now let's print. */
     for (o = list; o->name; o++) {
-        opt_print(o, width);
+        if (o->name == OPT_PARAM_STR)
+            sawparams = 1;
+        opt_print(o, sawparams, width);
     }
 }
 
diff --git a/apps/list.c b/apps/list.c
index a260db80fd..a5382ac24f 100644
--- a/apps/list.c
+++ b/apps/list.c
@@ -367,6 +367,7 @@ static void list_options_for_command(const char *command)
         if (o->name == OPT_HELP_STR
                 || o->name == OPT_MORE_STR
                 || o->name == OPT_SECTION_STR
+                || o->name == OPT_PARAM_STR
                 || o->name[0] == '\0')
             continue;
         BIO_printf(bio_out, "%s %c\n", o->name, c == '\0' ? '-' : c);
diff --git a/apps/mac.c b/apps/mac.c
index 0cd3323f3b..6abcfcd4e8 100644
--- a/apps/mac.c
+++ b/apps/mac.c
@@ -26,21 +26,22 @@ typedef enum OPTION_choice {
 
 const OPTIONS mac_options[] = {
     {OPT_HELP_STR, 1, '-', "Usage: %s [options] mac_name\n"},
-    {OPT_HELP_STR, 1, '-', "mac_name\t\t MAC algorithm (See list "
-                           "-mac-algorithms)"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
-    {"macopt", OPT_MACOPT, 's', "MAC algorithm parameters in n:v form. "
-                                "See 'PARAMETER NAMES' in the EVP_MAC_ docs"},
+    {"macopt", OPT_MACOPT, 's', "MAC algorithm parameters in n:v form"},
+    {OPT_MORE_STR, 1, '-', "See 'PARAMETER NAMES' in the EVP_MAC_ docs"},
 
     OPT_SECTION("Input"),
     {"in", OPT_IN, '<', "Input file to MAC (default is stdin)"},
 
     OPT_SECTION("Output"),
     {"out", OPT_OUT, '>', "Output to filename rather than stdout"},
-    {"binary", OPT_BIN, '-', "Output in binary format (Default is hexadecimal "
-                             "output)"},
+    {"binary", OPT_BIN, '-',
+        "Output in binary format (default is hexadecimal)"},
+
+    OPT_PARAMETERS(),
+    {"mac_name", 0, 0, "MAC algorithm"},
     {NULL}
 };
 
diff --git a/apps/openssl.c b/apps/openssl.c
index 9aabad5e09..66189ca434 100644
--- a/apps/openssl.c
+++ b/apps/openssl.c
@@ -384,11 +384,13 @@ typedef enum HELP_CHOICE {
 } HELP_CHOICE;
 
 const OPTIONS help_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: help [options]\n"},
-    {OPT_HELP_STR, 1, '-', "       help [command]\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: help [options] [command]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_hHELP, '-', "Display this summary"},
+
+    OPT_PARAMETERS(),
+    {"command", 0, 0, "Name of command to display help (optional)"},
     {NULL}
 };
 
diff --git a/apps/passwd.c b/apps/passwd.c
index e305bd268d..3b1d2ce3ca 100644
--- a/apps/passwd.c
+++ b/apps/passwd.c
@@ -59,6 +59,8 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS passwd_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [password]\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
 
@@ -85,6 +87,9 @@ const OPTIONS passwd_options[] = {
 #endif
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"password", 0, 0, "Password text to digest (optional)"},
     {NULL}
 };
 
diff --git a/apps/prime.c b/apps/prime.c
index 5df9ee0363..5345e5b6d0 100644
--- a/apps/prime.c
+++ b/apps/prime.c
@@ -20,8 +20,6 @@ typedef enum OPTION_choice {
 
 const OPTIONS prime_options[] = {
     {OPT_HELP_STR, 1, '-', "Usage: %s [options] [number...]\n"},
-    {OPT_HELP_STR, 1, '-',
-        "  number Number to check for primality\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -33,6 +31,9 @@ const OPTIONS prime_options[] = {
     {"generate", OPT_GENERATE, '-', "Generate a prime"},
     {"safe", OPT_SAFE, '-',
      "When used with -generate, generate a safe prime"},
+
+    OPT_PARAMETERS(),
+    {"number", 0, 0, "Number(s) to check for primality if not generating"},
     {NULL}
 };
 
diff --git a/apps/provider.c b/apps/provider.c
index 47bc056b63..87231cd2df 100644
--- a/apps/provider.c
+++ b/apps/provider.c
@@ -26,8 +26,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS provider_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [options] provider...\n"},
-    {OPT_HELP_STR, 1, '-', "  provider... Providers to load\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [provider...]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -38,6 +37,9 @@ const OPTIONS provider_options[] = {
     {OPT_MORE_STR, 0, '-', "categorised by operation type"},
     {"vvv", OPT_VVV, '-', "List the algorithm names of specified provider"},
     {OPT_MORE_STR, 0, '-', "one at a time, and list all known parameters"},
+
+    OPT_PARAMETERS(),
+    {"provider", 0, 0, "Provider(s) to load"},
     {NULL}
 };
 
@@ -268,6 +270,7 @@ int provider_main(int argc, char **argv)
     argc = opt_num_rest();
     argv = opt_rest();
     for ( ; *argv; argv++) {
+        /* This isn't necessary since -- is supported. */
         if (**argv == '-') {
             BIO_printf(bio_err, "%s: Cannot mix flags and provider names.\n",
                        prog);
diff --git a/apps/rand.c b/apps/rand.c
index 8b23a03f6e..421ebfc203 100644
--- a/apps/rand.c
+++ b/apps/rand.c
@@ -25,7 +25,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS rand_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [flags] num\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] num\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -39,6 +39,9 @@ const OPTIONS rand_options[] = {
     {"hex", OPT_HEX, '-', "Hex encode output"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"num", 0, 0, "Number of bytes to generate"},
     {NULL}
 };
 
diff --git a/apps/rehash.c b/apps/rehash.c
index ec1cf07506..b7e6e7ec18 100644
--- a/apps/rehash.c
+++ b/apps/rehash.c
@@ -451,7 +451,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS rehash_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [cert-directory...]\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [directory...]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -462,6 +462,9 @@ const OPTIONS rehash_options[] = {
 
     OPT_SECTION("Output"),
     {"v", OPT_VERBOSE, '-', "Verbose output"},
+
+    OPT_PARAMETERS(),
+    {"directory", 0, 0, "One or more directories to process (optional)"},
     {NULL}
 };
 
diff --git a/apps/s_client.c b/apps/s_client.c
index ee1951834b..a0668bc927 100644
--- a/apps/s_client.c
+++ b/apps/s_client.c
@@ -605,6 +605,8 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS s_client_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [host:port]\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
 #ifndef OPENSSL_NO_ENGINE
@@ -816,6 +818,9 @@ const OPTIONS s_client_options[] = {
     {"chainCAfile", OPT_CHAINCAFILE, '<',
      "CA file for certificate chain (PEM format)"},
     OPT_X_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"host:port", 0, 0, "Where to connect; same as -connect option"},
     {NULL}
 };
 
diff --git a/apps/smime.c b/apps/smime.c
index ec36ea1867..149d3151ee 100644
--- a/apps/smime.c
+++ b/apps/smime.c
@@ -49,9 +49,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS smime_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [options] cert.pem...\n"},
-    {OPT_HELP_STR, 1, '-',
-        "  cert.pem... recipient certs for encryption\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [cert...]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -123,6 +121,9 @@ const OPTIONS smime_options[] = {
 
     OPT_R_OPTIONS,
     OPT_V_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"cert", 0, 0, "Recipient certs, used when encrypting"},
     {NULL}
 };
 
diff --git a/apps/speed.c b/apps/speed.c
index 45cee2c2c5..53ae4c4e58 100644
--- a/apps/speed.c
+++ b/apps/speed.c
@@ -315,7 +315,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS speed_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [options] ciphers...\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [algorithm...]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -356,6 +356,9 @@ const OPTIONS speed_options[] = {
      "Use specified offset to mis-align buffers"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"algorithm", 0, 0, "Algorithm(s) to test (optional; otherwise tests all)"},
     {NULL}
 };
 
diff --git a/apps/srp.c b/apps/srp.c
index b980ecbbb5..e7a18d68cb 100644
--- a/apps/srp.c
+++ b/apps/srp.c
@@ -197,6 +197,8 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS srp_options[] = {
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [user...]\n"},
+
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
     {"verbose", OPT_VERBOSE, '-', "Talk a lot while doing things"},
@@ -220,6 +222,9 @@ const OPTIONS srp_options[] = {
     {"passout", OPT_PASSOUT, 's', "Output file pass phrase source"},
 
     OPT_R_OPTIONS,
+
+    OPT_PARAMETERS(),
+    {"user", 0, 0, "Username(s) to process (optional)"},
     {NULL}
 };
 
diff --git a/apps/storeutl.c b/apps/storeutl.c
index 980120a39d..85fb1ed860 100644
--- a/apps/storeutl.c
+++ b/apps/storeutl.c
@@ -58,6 +58,9 @@ const OPTIONS storeutl_options[] = {
     {"out", OPT_OUT, '>', "Output file - default stdout"},
     {"text", OPT_TEXT, '-', "Print a text form of the objects"},
     {"noout", OPT_NOOUT, '-', "No PEM output, just status"},
+
+    OPT_PARAMETERS(),
+    {"uri", 0, 0, "URI of the store object"},
     {NULL}
 };
 
diff --git a/apps/verify.c b/apps/verify.c
index bb8f84c84d..5c5042117d 100644
--- a/apps/verify.c
+++ b/apps/verify.c
@@ -35,7 +35,7 @@ typedef enum OPTION_choice {
 } OPTION_CHOICE;
 
 const OPTIONS verify_options[] = {
-    {OPT_HELP_STR, 1, '-', "Usage: %s [options] cert.pem...\n"},
+    {OPT_HELP_STR, 1, '-', "Usage: %s [options] [cert...]\n"},
 
     OPT_SECTION("General"),
     {"help", OPT_HELP, '-', "Display this summary"},
@@ -72,6 +72,9 @@ const OPTIONS verify_options[] = {
     {"sm2-hex-id", OPT_SM2HEXID, 's',
      "Specify a hex ID string to verify an SM2 certificate"},
 #endif
+
+    OPT_PARAMETERS(),
+    {"cert", 0, 0, "Certificate(s) to verify (optional; stdin used otherwise)"},
     {NULL}
 };
 
@@ -102,20 +105,20 @@ int verify_main(int argc, char **argv)
             goto end;
         case OPT_HELP:
             opt_help(verify_options);
-            BIO_printf(bio_err, "Recognized usages:\n");
+            BIO_printf(bio_err, "\nRecognized certificate chain purposes:\n");
             for (i = 0; i < X509_PURPOSE_get_count(); i++) {
-                X509_PURPOSE *ptmp;
-                ptmp = X509_PURPOSE_get0(i);
-                BIO_printf(bio_err, "\t%-10s\t%s\n",
+                X509_PURPOSE *ptmp = X509_PURPOSE_get0(i);
+
+                BIO_printf(bio_err, "  %-15s  %s\n",
                         X509_PURPOSE_get0_sname(ptmp),
                         X509_PURPOSE_get0_name(ptmp));
             }
 
-            BIO_printf(bio_err, "Recognized verify names:\n");
+            BIO_printf(bio_err, "Recognized certificate policy names:\n");
             for (i = 0; i < X509_VERIFY_PARAM_get_count(); i++) {
-                const X509_VERIFY_PARAM *vptmp;
-                vptmp = X509_VERIFY_PARAM_get0(i);
-                BIO_printf(bio_err, "\t%-10s\n",
+                const X509_VERIFY_PARAM *vptmp = X509_VERIFY_PARAM_get0(i);
+
+                BIO_printf(bio_err, "  %s\n",
                         X509_VERIFY_PARAM_get0_name(vptmp));
             }
             ret = 0;
diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in
index 81d1186d23..6df41d897f 100644
--- a/doc/man1/openssl-ca.pod.in
+++ b/doc/man1/openssl-ca.pod.in
@@ -62,6 +62,7 @@ B<openssl> B<ca>
 [B<-sm2-id> I<string>]
 [B<-sm2-hex-id> I<hex-string>]
 {- $OpenSSL::safe::opt_r_synopsis -}
+[I<certreq>...]
 
 =for openssl ifdef engine sm2-id sm2-hex-id
 
@@ -69,8 +70,11 @@ B<openssl> B<ca>
 
 This command is a minimal CA application. It can be used
 to sign certificate requests in a variety of forms and generate
-CRLs it also maintains a text database of issued certificates
+CRLs. It also maintains a text database of issued certificates
 and their status.
+When signing certificates, a single certificate request can be specified
+with the B<-in> option, or multiple requests can be processed by
+specifying a set of B<certreq> files after all options.
 
 The options descriptions will be divided into each purpose.
 
diff --git a/doc/man1/openssl-passwd.pod.in b/doc/man1/openssl-passwd.pod.in
index 2fa8e97f13..dee50df229 100644
--- a/doc/man1/openssl-passwd.pod.in
+++ b/doc/man1/openssl-passwd.pod.in
@@ -26,7 +26,7 @@ B<openssl passwd>
 [B<-quiet>]
 [B<-table>]
 {- $OpenSSL::safe::opt_r_synopsis -}
-{I<password>}
+[I<password>]
 
 =for openssl ifdef crypt