From b2bdfb63eb16431aabe93ef59364d41125db255e Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Tue, 1 Oct 2019 21:10:17 +0200
Subject: [PATCH] Command docs: diverse small fixes

Better synopsis for 'openssl dgst' and 'openssl enc', correct names
for 'openssl rehash' ('c_rehash' is mentioned there too), correct
option end marker for 'openssl verify', and finally, refer to
sub-commands as sub-commands.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10065)
---
 doc/man1/CA.pl.pod             | 13 ++++++-------
 doc/man1/openssl-asn1parse.pod |  8 ++++++--
 doc/man1/openssl-dgst.pod      |  4 +---
 doc/man1/openssl-enc.pod       |  2 +-
 doc/man1/openssl-engine.pod    |  3 +--
 doc/man1/openssl-rehash.pod    | 10 ++++++++--
 doc/man1/openssl-req.pod       |  2 +-
 doc/man1/openssl-verify.pod    |  2 +-
 doc/man1/openssl.pod           | 16 ++++++++++++----
 9 files changed, 37 insertions(+), 23 deletions(-)

diff --git a/doc/man1/CA.pl.pod b/doc/man1/CA.pl.pod
index 129bf35407..c0ecabc538 100644
--- a/doc/man1/CA.pl.pod
+++ b/doc/man1/CA.pl.pod
@@ -122,12 +122,10 @@ F<newcert.pem>.  Invokes L<openssl-verify(1)> command.
 
 =item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> I<extra-params>
 
-The purpose of these parameters is to allow optional parameters to be supplied
-to L<openssl(1)> that this command executes. The B<-extra-cmd> are specific to
-the option being used and the L<openssl(1)> command getting invoked. For example
-when this command invokes L<openssl-req(1)> extra parameters can be passed on
-with the B<-extra-req> parameter. The
-L<openssl(1)> commands being invoked per option are documented below.
+For each option B<extra-I<cmd>>, pass I<extra-params> to the L<openssl(1)>
+sub-command with the same name as I<cmd>, if that sub-command is invoked.
+For example, if L<openssl-req(1)> is invoked, the I<extra-params> given with
+B<-extra-req> will be passed to it.
 Users should consult L<openssl(1)> command documentation for more information.
 
 =back
@@ -164,7 +162,8 @@ Create the CA directories and files:
 
  CA.pl -newca
 
-enter a filename (for example F<cacert.pem>) when prompted for the CA filename.
+enter a filename (for example, F<cacert.pem>) when prompted for the CA file
+name.
 
 Create a DSA certificate request and private key (a different set of parameters
 can optionally be created first):
diff --git a/doc/man1/openssl-asn1parse.pod b/doc/man1/openssl-asn1parse.pod
index 183f5134ac..5e755596c2 100644
--- a/doc/man1/openssl-asn1parse.pod
+++ b/doc/man1/openssl-asn1parse.pod
@@ -105,8 +105,9 @@ END marker in a PEM file.
 
 =item B<-item> I<name>
 
-Attempt to decode and print the data as B<ASN1_ITEM> I<name>. This can be used
-to print out the fields of any supported ASN.1 structure if the type is known.
+Attempt to decode and print the data as an B<ASN1_ITEM> I<name>. This can be
+used to print out the fields of any supported ASN.1 structure if the type is
+known.
 
 =back
 
@@ -161,6 +162,9 @@ by white space. The final column is the rest of the line and is the
 
 C<1.2.3.4       shortName       A long name>
 
+For any OID with an associated short and long name, this command will display
+the long name.
+
 =head1 EXAMPLES
 
 Parse a file:
diff --git a/doc/man1/openssl-dgst.pod b/doc/man1/openssl-dgst.pod
index f83c2ac516..5f836f9cb5 100644
--- a/doc/man1/openssl-dgst.pod
+++ b/doc/man1/openssl-dgst.pod
@@ -6,7 +6,7 @@ openssl-dgst - perform digest operations
 
 =head1 SYNOPSIS
 
-B<openssl dgst>
+B<openssl> B<dgst>|I<digest>
 [B<-I<digest>>]
 [B<-help>]
 [B<-c>]
@@ -29,8 +29,6 @@ B<openssl dgst>
 [B<-engine_impl>]
 [I<file> ...]
 
-B<openssl> I<digest> [B<...>]
-
 =head1 DESCRIPTION
 
 This command output the message digest of a supplied file or files
diff --git a/doc/man1/openssl-enc.pod b/doc/man1/openssl-enc.pod
index 5a992046f8..f2608a59f7 100644
--- a/doc/man1/openssl-enc.pod
+++ b/doc/man1/openssl-enc.pod
@@ -6,7 +6,7 @@ openssl-enc - symmetric cipher routines
 
 =head1 SYNOPSIS
 
-B<openssl>
+B<openssl> B<enc>|I<cipher>
 [B<-I<cipher>>]
 [B<-help>]
 [B<-ciphers>]
diff --git a/doc/man1/openssl-engine.pod b/doc/man1/openssl-engine.pod
index ea5cf4d2f2..30e391fd4e 100644
--- a/doc/man1/openssl-engine.pod
+++ b/doc/man1/openssl-engine.pod
@@ -10,8 +10,7 @@ B<openssl engine>
 [B<-v>]
 [B<-vv>]
 [B<-vvv>]
-[B<-vvv>]
-[B<-vvv>]
+[B<-vvvv>]
 [B<-c>]
 [B<-t>]
 [B<-tt>]
diff --git a/doc/man1/openssl-rehash.pod b/doc/man1/openssl-rehash.pod
index d813faacb9..eed2864446 100644
--- a/doc/man1/openssl-rehash.pod
+++ b/doc/man1/openssl-rehash.pod
@@ -5,7 +5,8 @@ Original text by James Westby, contributed under the OpenSSL license.
 
 =head1 NAME
 
-openssl-c_rehash - Create symbolic links to files named by the hash values
+openssl-rehash, c_rehash - Create symbolic links to files named by the hash
+values
 
 =head1 SYNOPSIS
 
@@ -19,7 +20,12 @@ B<rehash>
 [I<directory>] ...
 
 B<c_rehash>
-I<flags...>
+[B<-h>]
+[B<-help>]
+[B<-old>]
+[B<-n>]
+[B<-v>]
+[I<directory>] ...
 
 =head1 DESCRIPTION
 
diff --git a/doc/man1/openssl-req.pod b/doc/man1/openssl-req.pod
index 2449a580bc..877e9362ea 100644
--- a/doc/man1/openssl-req.pod
+++ b/doc/man1/openssl-req.pod
@@ -665,7 +665,7 @@ The following messages are frequently asked about:
         Using configuration from /some/path/openssl.cnf
         Unable to load config info
 
-This is followed some time later by...
+This is followed some time later by:
 
         unable to find 'distinguished_name' in config
         problems making Certificate Request
diff --git a/doc/man1/openssl-verify.pod b/doc/man1/openssl-verify.pod
index 81493a0fb4..f89461e3bd 100644
--- a/doc/man1/openssl-verify.pod
+++ b/doc/man1/openssl-verify.pod
@@ -333,7 +333,7 @@ certificate. The argument for this option is string of hexadecimal digits.
 
 Indicates the last option. All arguments following this are assumed to be
 certificate files. This is useful if the first certificate filename begins
-with a B<->.
+with a B<-->.
 
 =item I<certificate> ...
 
diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 8a31f09ceb..10d38c9343 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -11,7 +11,15 @@ I<command>
 [ I<command_opts> ... ]
 [ I<command_args> ... ]
 
-B<openssl> B<list> [ B<-standard-commands> | B<-digest-commands> | B<-cipher-commands> | B<-cipher-algorithms> | B<-digest-algorithms> | B<-mac-algorithms> | B<-public-key-algorithms>]
+B<openssl>
+B<list>
+B<-standard-commands> |
+B<-digest-commands> |
+B<-cipher-commands> |
+B<-cipher-algorithms> |
+B<-digest-algorithms> |
+B<-mac-algorithms> |
+B<-public-key-algorithms>
 
 B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
 
@@ -36,8 +44,8 @@ It can be used for
 
 =head1 COMMAND SUMMARY
 
-The B<openssl> program provides a rich variety of commands (I<command> in the
-SYNOPSIS above), each of which often has a wealth of options and arguments
+The B<openssl> program provides a rich variety of sub-commands (I<command> in
+the SYNOPSIS above), each of which often has a wealth of options and arguments
 (I<command_opts> and I<command_args> in the SYNOPSIS).
 
 Detailed documentation and use cases for most standard subcommands are available
@@ -77,7 +85,7 @@ availability of ciphers in the B<openssl> program.  (B<no->I<XXX> is
 not able to detect pseudo-commands such as B<quit>,
 B<list>, or B<no->I<XXX> itself.)
 
-=head2 Standard Commands
+=head2 Standard Sub-commands
 
 =over 4
 
-- 
2.25.1