Command docs: fix up command references

Almost all OpenSSL commands are in reality 'openssl cmd', so make sure
they are refered to like that and not just as the sub-command.

Self-references are avoided as much as is possible, and replaced with
"this command".  In some cases, we even avoid that with a slight
rewrite of the sentence or paragrah they were in.  However, in the few
cases where a self-reference is still admissible, they are done in
bold, i.e. openssl-speed.pod references itself like this:

    B<openssl speed>

References to other commands are done as manual links, i.e. CA.pl.pod
references 'openssl req' like this: L<openssl-req(1)>

Some commands are examples rather than references; we enclose those in
C<>.

While we are it, we abolish "utility", replacing it with "command", or
remove it entirely in some cases.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10065)

53 files changed, 334 insertions, 332 deletions

diff --git a/doc/man1/CA.pl.pod b/doc/man1/CA.pl.pod
index 1e4d223ddb..235e341886 100644
--- a/doc/man1/CA.pl.pod
+++ b/doc/man1/CA.pl.pod
@@ -32,7 +32,7 @@ B<CA.pl> B<-revoke> [B<-extra-ca> I<extra-params>] I<certfile> [I<reason>]
 =head1 DESCRIPTION
 
 The B<CA.pl> script is a perl script that supplies the relevant command line
-arguments to the B<openssl> command for some common certificate operations.
+arguments to the L<openssl(1)> command for some common certificate operations.
 It is intended to simplify the process of certificate creation and management
 by the use of some simple options.
 
@@ -48,18 +48,18 @@ Prints a usage message.
 
 Creates a new self signed certificate. The private key is written to the file
 "newkey.pem" and the request written to the file "newreq.pem".
-This argument invokes B<openssl req> command.
+This argument invokes L<openssl-req(1)> command.
 
 =item B<-newreq>
 
 Creates a new certificate request. The private key is written to the file
 "newkey.pem" and the request written to the file "newreq.pem".
-Executes B<openssl req> command below the hood.
+Executes L<openssl-req(1)> command below the hood.
 
 =item B<-newreq-nodes>
 
 Is like B<-newreq> except that the private key will not be encrypted.
-Uses B<openssl req> command.
+Uses L<openssl-req(1)> command.
 
 =item B<-newca>
 
@@ -68,7 +68,7 @@ and B<-xsign> options). The user is prompted to enter the filename of the CA
 certificates (which should also contain the private key) or by hitting ENTER
 details of the CA will be prompted for. The relevant files and directories
 are created in a directory called "demoCA" in the current directory.
-B<openssl req> and B<openssl ca> commands are get invoked.
+L<openssl-req(1)> and L<openssl-ca(1)> commands are get invoked.
 
 =item B<-pkcs12>
 
@@ -80,31 +80,31 @@ B<-sign> option. The PKCS#12 file can be imported directly into a browser.
 If there is an additional argument on the command line it will be used as the
 "friendly name" for the certificate (which is typically displayed in the browser
 list box), otherwise the name "My Certificate" is used.
-Delegates work to B<openssl pkcs12> command.
+Delegates work to L<openssl-pkcs12(1)> command.
 
 =item B<-sign>, B<-signcert>, B<-xsign>
 
-Calls the B<ca> program to sign a certificate request. It expects the request
-to be in the file "newreq.pem". The new certificate is written to the file
-"newcert.pem" except in the case of the B<-xsign> option when it is written
-to standard output. Leverages B<openssl ca> command.
+Calls the L<openssl-ca(1)> command to sign a certificate request. It expects the
+request to be in the file "newreq.pem". The new certificate is written to the
+file "newcert.pem" except in the case of the B<-xsign> option when it is
+written to standard output. Leverages L<openssl-ca(1)> command.
 
 =item B<-signCA>
 
 This option is the same as the B<-signreq> option except it uses the
 configuration file section B<v3_ca> and so makes the signed request a
 valid CA certificate. This is useful when creating intermediate CA from
-a root CA.  Extra params are passed on to B<openssl ca> command.
+a root CA.  Extra params are passed on to L<openssl-ca(1)> command.
 
 =item B<-signcert>
 
 This option is the same as B<-sign> except it expects a self signed certificate
 to be present in the file "newreq.pem".
-Extra params are passed on to B<openssl x509> and B<openssl ca> commands.
+Extra params are passed on to L<openssl-x509(1)> and L<openssl-ca(1)> commands.
 
 =item B<-crl>
 
-Generate a CRL. Executes B<openssl ca> command.
+Generate a CRL. Executes L<openssl-ca(1)> command.
 
 =item B<-revoke> I<certfile> [I<reason>]
 
@@ -112,23 +112,23 @@ Revoke the certificate contained in the specified B<certfile>. An optional
 reason may be specified, and must be one of: B<unspecified>,
 B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
 B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
-Leverages B<openssl ca> command.
+Leverages L<openssl-ca(1)> command.
 
 =item B<-verify>
 
 Verifies certificates against the CA certificate for "demoCA". If no
 certificates are specified on the command line it tries to verify the file
-"newcert.pem".  Invokes B<openssl verify> command.
+"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 B<openssl> that this command executes. The B<-extra-cmd> are specific to the
-option being used and the B<openssl> command getting invoked. For example
-when this command invokes B<openssl req> extra parameters can be passed on
+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
-B<openssl> commands being invoked per option are documented below.
-Users should consult B<openssl> command documentation for more information.
+L<openssl(1)> commands being invoked per option are documented below.
+Users should consult L<openssl(1)> command documentation for more information.
 
 =back
 
@@ -193,9 +193,10 @@ be wrong. In this case the command:
 can be used and the B<OPENSSL_CONF> environment variable changed to point to
 the correct path of the configuration file.
 
-The script is intended as a simple front end for the B<openssl> program for use
-by a beginner. Its behaviour isn't always what is wanted. For more control over the
-behaviour of the certificate commands call the B<openssl> command directly.
+The script is intended as a simple front end for the L<openssl(1)> program for
+use by a beginner. Its behaviour isn't always what is wanted. For more control
+over the behaviour of the certificate commands call the L<openssl(1)> command
+directly.
 
 =head1 SEE ALSO
 
diff --git a/doc/man1/openssl-asn1parse.pod b/doc/man1/openssl-asn1parse.pod
index 7b81c51f49..4b99338ccd 100644
--- a/doc/man1/openssl-asn1parse.pod
+++ b/doc/man1/openssl-asn1parse.pod
@@ -26,8 +26,8 @@ B<openssl> B<asn1parse>
 
 =head1 DESCRIPTION
 
-The B<asn1parse> command is a diagnostic utility that can parse ASN.1
-structures. It can also be used to extract data from ASN.1 formatted data.
+This command is a diagnostic utility that can parse ASN.1 structures.
+It can also be used to extract data from ASN.1 formatted data.
 
 =head1 OPTIONS
 
@@ -157,7 +157,7 @@ allows additional OIDs to be included. Each line consists of three columns,
 the first column is the OID in numerical format and should be followed by white
 space. The second column is the "short name" which is a single word followed
 by white space. The final column is the rest of the line and is the
-"long name". B<asn1parse> displays the long name. Example:
+"long name". Example:
 
 C<1.2.3.4       shortName       A long name>
 
diff --git a/doc/man1/openssl-ca.pod b/doc/man1/openssl-ca.pod
index 4780f2aa97..bf5dc57034 100644
--- a/doc/man1/openssl-ca.pod
+++ b/doc/man1/openssl-ca.pod
@@ -63,7 +63,7 @@ B<openssl> B<ca>
 
 =head1 DESCRIPTION
 
-The B<ca> command is a minimal CA application. It can be used
+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
 and their status.
@@ -193,7 +193,7 @@ The number of days to certify the certificate for.
 =item B<-md> I<alg>
 
 The message digest to use.
-Any digest supported by the OpenSSL B<dgst> command can be used. For signing
+Any digest supported by the L<openssl-dgst(1)> command can be used. For signing
 algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message
 digest that is set is ignored. This option also applies to CRLs.
 
@@ -206,8 +206,8 @@ for more information.
 
 =item B<-msie_hack>
 
-This is a deprecated option to make B<ca> work with very old versions of
-the IE certificate enrollment control "certenr3". It used UniversalStrings
+This is a deprecated option to make this command work with very old versions
+of the IE certificate enrollment control "certenr3". It used UniversalStrings
 for almost everything. Since the old control has various security bugs
 its use is strongly discouraged.
 
@@ -393,7 +393,7 @@ extension section format.
 
 =head1 CONFIGURATION FILE OPTIONS
 
-The section of the configuration file containing options for B<ca>
+The section of the configuration file containing options for this command
 is found as follows: If the B<-name> command line option is used,
 then it names the section to be used. Otherwise the section to
 be used must be named in the B<default_ca> option of the B<ca> section
@@ -581,7 +581,7 @@ this can be regarded more of a quirk than intended behaviour.
 The input to the B<-spkac> command line option is a Netscape
 signed public key and challenge. This will usually come from
 the B<KEYGEN> tag in an HTML form to create a new private key.
-It is however possible to create SPKACs using the B<spkac> utility.
+It is however possible to create SPKACs using L<openssl-spkac(1)>.
 
 The file should contain the variable SPKAC set to the value of
 the SPKAC and also the required DN components as name value pairs.
@@ -594,11 +594,11 @@ flag is used.
 
 =head1 EXAMPLES
 
-Note: these examples assume that the B<ca> directory structure is
-already set up and the relevant files already exist. This usually
-involves creating a CA certificate and private key with B<req>, a
-serial number file and an empty index file and placing them in
-the relevant directories.
+Note: these examples assume that the directory structure this command
+assumes is already set up and the relevant files already exist. This
+usually involves creating a CA certificate and private key with
+L<openssl-req(1)>, a serial number file and an empty index file and
+placing them in the relevant directories.
 
 To use the sample configuration file below the directories demoCA,
 demoCA/private and demoCA/newcerts would be created. The CA
@@ -640,7 +640,7 @@ A sample SPKAC file (the SPKAC line has been truncated for clarity):
  0.OU=OpenSSL Group
  1.OU=Another Group
 
-A sample configuration file with the relevant sections for B<ca>:
+A sample configuration file with the relevant sections for this command:
 
  [ ca ]
  default_ca      = CA_default            # The default ca section
@@ -711,7 +711,7 @@ The use of an in-memory text database can cause problems when large
 numbers of certificates are present because, as the name implies
 the database has to be kept in memory.
 
-The B<ca> command really needs rewriting or the required functionality
+This command really needs rewriting or the required functionality
 exposed at either a command or interface level so a more friendly utility
 (perl script or GUI) can handle things properly. The script
 B<CA.pl> helps a little but not very much.
@@ -728,15 +728,15 @@ create an empty file.
 
 =head1 WARNINGS
 
-The B<ca> command is quirky and at times downright unfriendly.
+This command is quirky and at times downright unfriendly.
 
-The B<ca> utility was originally meant as an example of how to do things
-in a CA. It was not supposed to be used as a full blown CA itself:
+This command was originally meant as an example of how to do
+things in a CA. It was not supposed to be used as a full blown CA itself:
 nevertheless some people are using it for this purpose.
 
-The B<ca> command is effectively a single user command: no locking is
-done on the various files and attempts to run more than one B<ca> command
-on the same database can have unpredictable results.
+This command command is effectively a single user command: no locking
+is done on the various files and attempts to run more than one B<openssl ca>
+command on the same database can have unpredictable results.
 
 The B<copy_extensions> option should be used with caution. If care is
 not taken then it can be a security risk. For example if a certificate
diff --git a/doc/man1/openssl-ciphers.pod b/doc/man1/openssl-ciphers.pod
index ca1f8fc0c4..bfc6ff0b70 100644
--- a/doc/man1/openssl-ciphers.pod
+++ b/doc/man1/openssl-ciphers.pod
@@ -28,9 +28,9 @@ B<openssl> B<ciphers>
 
 =head1 DESCRIPTION
 
-The B<ciphers> command converts textual OpenSSL cipher lists into ordered
-SSL cipher preference lists. It can be used as a test tool to determine
-the appropriate cipherlist.
+This command converts textual OpenSSL cipher lists into
+ordered SSL cipher preference lists. It can be used as a test tool to
+determine the appropriate cipherlist.
 
 =head1 OPTIONS
 
@@ -761,7 +761,7 @@ L<ssl(7)>
 
 =head1 HISTORY
 
-The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
+The B<-V> option was added in OpenSSL 1.0.0.
 
 The B<-stdname> is only available if OpenSSL is built with tracing enabled
 (B<enable-ssl-trace> argument to Configure) before OpenSSL 1.1.1.
diff --git a/doc/man1/openssl-cms.pod b/doc/man1/openssl-cms.pod
index 24cf797702..ddadbc5bb3 100644
--- a/doc/man1/openssl-cms.pod
+++ b/doc/man1/openssl-cms.pod
@@ -107,8 +107,8 @@ B<openssl> B<cms>
 
 =head1 DESCRIPTION
 
-The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
-verify, compress and uncompress S/MIME messages.
+This command handles S/MIME v3.1 mail. It can encrypt, decrypt,
+sign and verify, compress and uncompress S/MIME messages.
 
 =head1 OPTIONS
 
@@ -629,10 +629,10 @@ the signers certificates.
 
 =head1 COMPATIBILITY WITH PKCS#7 FORMAT
 
-The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
-utility supports Cryptographic Message Syntax format. Use of some features
-will result in messages which cannot be processed by applications which only
-support the older format. These are detailed below.
+L<openssl-smime(1)> can only process the older B<PKCS#7> format.
+B<openssl cms> supports Cryptographic Message Syntax format.
+Use of some features will result in messages which cannot be processed by
+applications which only support the older format. These are detailed below.
 
 The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
 
@@ -647,7 +647,7 @@ The use of PSS with B<-sign>.
 The use of OAEP or non-RSA keys with B<-encrypt>.
 
 Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
-be processed by the older B<smime> command.
+be processed by the older L<openssl-smime(1)> command.
 
 =head1 EXAMPLES
 
diff --git a/doc/man1/openssl-crl.pod b/doc/man1/openssl-crl.pod
index acf3465b55..5394a2af1c 100644
--- a/doc/man1/openssl-crl.pod
+++ b/doc/man1/openssl-crl.pod
@@ -26,7 +26,7 @@ B<openssl> B<crl>
 
 =head1 DESCRIPTION
 
-The B<crl> command processes CRL files in DER or PEM format.
+This command processes CRL files in DER or PEM format.
 
 =head1 OPTIONS
 
@@ -101,8 +101,8 @@ I<file>.
 
 Verify the signature on a CRL by looking up the issuing certificate in
 I<dir>. This directory must be a standard certificate directory: that
-is a hash of each subject name (using B<x509 -hash>) should be linked
-to each certificate.
+is a hash of each subject name (using the L<openssl-x509(1)> B<-hash> option)
+should be linked to each certificate.
 
 =back
 
diff --git a/doc/man1/openssl-crl2pkcs7.pod b/doc/man1/openssl-crl2pkcs7.pod
index 32248e5e21..8b0f33bbd1 100644
--- a/doc/man1/openssl-crl2pkcs7.pod
+++ b/doc/man1/openssl-crl2pkcs7.pod
@@ -17,7 +17,7 @@ B<openssl> B<crl2pkcs7>
 
 =head1 DESCRIPTION
 
-The B<crl2pkcs7> command takes an optional CRL and one or more
+This command takes an optional CRL and one or more
 certificates and converts them into a PKCS#7 degenerate "certificates
 only" structure.
 
@@ -82,7 +82,7 @@ different certificates:
 The output file is a PKCS#7 signed data structure containing no signers and
 just certificates and an optional CRL.
 
-This utility can be used to send certificates and CAs to Netscape as part of
+This command can be used to send certificates and CAs to Netscape as part of
 the certificate enrollment process. This involves sending the DER encoded output
 as MIME type application/x-x509-user-cert.
 
diff --git a/doc/man1/openssl-dgst.pod b/doc/man1/openssl-dgst.pod
index 436b2fd1fe..729548a4c1 100644
--- a/doc/man1/openssl-dgst.pod
+++ b/doc/man1/openssl-dgst.pod
@@ -33,16 +33,15 @@ B<openssl> I<digest> [B<...>]
 
 =head1 DESCRIPTION
 
-The digest functions output the message digest of a supplied file or files
-in hexadecimal.  The digest functions also generate and verify digital
+This command output the message digest of a supplied file or files
+in hexadecimal, and also generates and verifies digital
 signatures using message digests.
 
-The generic name, B<dgst>, may be used with an option specifying the
+The generic name, B<openssl dgst>, may be used with an option specifying the
 algorithm to be used.
 The default digest is B<sha256>.
-A supported I<digest> name may also be used as the command name.
-To see the list of supported algorithms, use the I<list --digest-commands>
-command.
+A supported I<digest> name may also be used as the sub-command name.
+To see the list of supported algorithms, use C<openssl list -digest-commands>
 
 =head1 OPTIONS
 
@@ -79,7 +78,7 @@ Output the digest or signature in binary form.
 =item B<-r>
 
 Output the digest in the "coreutils" format, including newlines.
-Used by programs like B<sha1sum>.
+Used by programs like L<sha1sum(1)>.
 
 =item B<-out> I<filename>
 
@@ -88,8 +87,8 @@ Filename to output to, or standard output by default.
 =item B<-sign> I<filename>
 
 Digitally sign the digest using the private key in "filename". Note this option
-does not support Ed25519 or Ed448 private keys. Use the B<pkeyutl> command
-instead for this.
+does not support Ed25519 or Ed448 private keys. Use the L<openssl-pkeyutl(1)>
+command instead for this.
 
 =item B<-keyform> I<arg>
 
@@ -215,13 +214,13 @@ To verify a signature:
 
 The digest mechanisms that are available will depend on the options
 used when building OpenSSL.
-The B<list digest-commands> command can be used to list them.
+The C<openssl list -digest-commands> command can be used to list them.
 
 New or agile applications should use probably use SHA-256. Other digests,
 particularly SHA-1 and MD5, are still widely used for interoperating
 with existing formats and protocols.
 
-When signing a file, B<dgst> will automatically determine the algorithm
+When signing a file, this command will automatically determine the algorithm
 (RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
 When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
 itself, not the related data to identify the signer and algorithm used in
diff --git a/doc/man1/openssl-dhparam.pod b/doc/man1/openssl-dhparam.pod
index 0abd0d9748..01eab5cc91 100644
--- a/doc/man1/openssl-dhparam.pod
+++ b/doc/man1/openssl-dhparam.pod
@@ -131,10 +131,10 @@ for all available algorithms.
 
 =head1 WARNINGS
 
-The program B<dhparam> combines the functionality of the programs B<dh> and
-B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh>
-programs are retained for now but may have different purposes in future
-versions of OpenSSL.
+This command combines the functionality of the L<openssl-dh(1)> and the
+L<openssl-gendh(1)> commands in previous OpenSSL versions.
+The L<openssl-dh(1)> and L<openssl-gendh(1)> commands are retained for now but
+may have different purposes in future versions of OpenSSL.
 
 =head1 NOTES
 
diff --git a/doc/man1/openssl-dsa.pod b/doc/man1/openssl-dsa.pod
index 6f7ccb6ef7..55127db6e9 100644
--- a/doc/man1/openssl-dsa.pod
+++ b/doc/man1/openssl-dsa.pod
@@ -37,7 +37,7 @@ B<openssl> B<dsa>
 
 =head1 DESCRIPTION
 
-The B<dsa> command processes DSA keys. They can be converted between various
+This command processes DSA keys. They can be converted between various
 forms and their components printed out. B<Note> This command uses the
 traditional SSLeay compatible format for private key encryption: newer
 applications should use the more secure PKCS#8 format using the B<pkcs8>
@@ -95,9 +95,9 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 These options encrypt the private key with the specified
 cipher before outputting it. A pass phrase is prompted for.
 If none of these options is specified the key is written in plain text. This
-means that using the B<dsa> utility to read in an encrypted key with no
-encryption option can be used to remove the pass phrase from a key, or by
-setting the encryption options it can be use to add or change the pass phrase.
+means that this command can be used to remove the pass phrase from a key
+by not giving any encryption option is given, or to add or change the pass
+phrase by setting them.
 These options can only be used with PEM format output files.
 
 =item B<-text>
@@ -125,7 +125,7 @@ a public key.
 
 =item B<-engine> I<id>
 
-Specifying an engine (by its unique I<id> string) will cause B<dsa>
+Specifying an engine (by its unique I<id> string) will cause L<openssl-dsa(1)>
 to attempt to obtain a functional reference to the specified engine,
 thus initialising it if needed. The engine will then be set as the default
 for all available algorithms.
diff --git a/doc/man1/openssl-dsaparam.pod b/doc/man1/openssl-dsaparam.pod
index 5ae64ae83a..cc5570f333 100644
--- a/doc/man1/openssl-dsaparam.pod
+++ b/