Refactor -engine documentation

Common wording courtesy Richard Levitte.

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10128)

28 files changed, 139 insertions, 198 deletions

diff --git a/doc/man1/openssl-ca.pod.in b/doc/man1/openssl-ca.pod.in
index ca8ebb8c70..44e581e0d9 100644
--- a/doc/man1/openssl-ca.pod.in
+++ b/doc/man1/openssl-ca.pod.in
@@ -48,7 +48,6 @@ B<openssl> B<ca>
 [B<-msie_hack>]
 [B<-extensions> I<section>]
 [B<-extfile> I<section>]
-[B<-engine> I<id>]
 [B<-subj> I<arg>]
 [B<-utf8>]
 [B<-sigopt> I<nm>:I<v>]
@@ -58,6 +57,7 @@ B<openssl> B<ca>
 [B<-sm2-id> I<string>]
 [B<-sm2-hex-id> I<hex-string>]
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 [I<certreq>...]
 
 =for openssl ifdef engine sm2-id sm2-hex-id
@@ -253,13 +253,6 @@ An additional configuration file to read certificate extensions from
 (using the default section unless the B<-extensions> option is also
 used).
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause B<ca>
-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.
-
 =item B<-subj> I<arg>
 
 Supersedes subject name given in the request.
@@ -310,6 +303,8 @@ certificate. The argument for this option is string of hexadecimal digits.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 CRL OPTIONS
diff --git a/doc/man1/openssl-dgst.pod.in b/doc/man1/openssl-dgst.pod.in
index 4472b2ffe0..4563ad1d5e 100644
--- a/doc/man1/openssl-dgst.pod.in
+++ b/doc/man1/openssl-dgst.pod.in
@@ -27,7 +27,7 @@ B<openssl> B<dgst>|I<digest>
 [B<-hmac> I<key>]
 [B<-fips-fingerprint>]
 [B<-engine> I<id>]
-[B<-engine_impl>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
 [I<file> ...]
 
@@ -168,13 +168,6 @@ option.
 
 Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
 
-=item B<-engine> I<id>
-
-Use engine I<id> for operations (including private key storage).
-This engine is not used as source for digest algorithms, unless it is
-also specified in the configuration file or B<-engine_impl> is also
-specified.
-
 =item B<-engine_impl>
 
 When used with the B<-engine> option, it specifies to also use
@@ -182,6 +175,10 @@ engine I<id> for digest operations.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+The engine is not used for digests unless the B<-engine_impl> option is
+used or it is configured to do so, see L<config(5)/Engine Configuration Module>.
+
 =item I<file> ...
 
 File or files to digest. If no files are specified then standard input is
diff --git a/doc/man1/openssl-dhparam.pod.in b/doc/man1/openssl-dhparam.pod.in
index d55931fae8..e125330b36 100644
--- a/doc/man1/openssl-dhparam.pod.in
+++ b/doc/man1/openssl-dhparam.pod.in
@@ -21,7 +21,7 @@ B<openssl dhparam>
 [B<-2>]
 [B<-3>]
 [B<-5>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
 [I<numbits>]
 
@@ -102,12 +102,7 @@ This option prints out the DH parameters in human readable form.
 This option converts the parameters into C code. The parameters can then
 be loaded by calling the get_dhNNNN() function.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause B<dhparam>
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 {- $OpenSSL::safe::opt_r_item -}
 
diff --git a/doc/man1/openssl-dsa.pod b/doc/man1/openssl-dsa.pod.in
index 8c7b03781e..548d36874f 100644
--- a/doc/man1/openssl-dsa.pod
+++ b/doc/man1/openssl-dsa.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-dsa - DSA key processing
@@ -31,7 +36,7 @@ B<openssl> B<dsa>
 [B<-modulus>]
 [B<-pubin>]
 [B<-pubout>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef pvk-string pvk-weak pvk-none engine
 
@@ -113,12 +118,7 @@ By default, a private key is output. With this option a public
 key will be output instead. This option is automatically set if the input is
 a public key.
 
-=item B<-engine> I<id>
-
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 =back
 
diff --git a/doc/man1/openssl-dsaparam.pod.in b/doc/man1/openssl-dsaparam.pod.in
index cfe7c31e59..bab743672f 100644
--- a/doc/man1/openssl-dsaparam.pod.in
+++ b/doc/man1/openssl-dsaparam.pod.in
@@ -17,9 +17,9 @@ B<openssl dsaparam>
 [B<-text>]
 [B<-C>]
 [B<-genkey>]
-[B<-engine> I<id>]
 [B<-verbose>]
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 [I<numbits>]
 
 =head1 DESCRIPTION
@@ -75,12 +75,6 @@ be loaded by calling the get_dsaXXX() function.
 This option will generate a DSA either using the specified or generated
 parameters.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
 
 =item B<-verbose>
 
@@ -88,6 +82,8 @@ Print extra details about the operations being performed.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =item I<numbits>
 
 This option specifies that a parameter set should be generated of size
diff --git a/doc/man1/openssl-ec.pod b/doc/man1/openssl-ec.pod.in
index 2646c126b5..d20b49afcf 100644
--- a/doc/man1/openssl-ec.pod
+++ b/doc/man1/openssl-ec.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-ec - EC key processing
@@ -26,7 +31,7 @@ B<openssl> B<ec>
 [B<-param_enc> I<arg>]
 [B<-no_public>]
 [B<-check>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine
 
@@ -131,12 +136,7 @@ This option omits the public key components from the private key output.
 
 This option checks the consistency of an EC private or public key.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 =back
 
diff --git a/doc/man1/openssl-ecparam.pod.in b/doc/man1/openssl-ecparam.pod.in
index 823ca51273..ae2240ca59 100644
--- a/doc/man1/openssl-ecparam.pod.in
+++ b/doc/man1/openssl-ecparam.pod.in
@@ -24,7 +24,7 @@ B<openssl ecparam>
 [B<-param_enc> I<arg>]
 [B<-no_seed>]
 [B<-genkey>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
 
 =for openssl ifdef engine
@@ -122,12 +122,7 @@ is included in the ECParameters structure (see RFC 3279).
 
 This option will generate an EC private key using the specified parameters.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause B<ecparam>
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 {- $OpenSSL::safe::opt_r_item -}
 
diff --git a/doc/man1/openssl-enc.pod.in b/doc/man1/openssl-enc.pod.in
index 0f1508e97a..cff127d211 100644
--- a/doc/man1/openssl-enc.pod.in
+++ b/doc/man1/openssl-enc.pod.in
@@ -37,7 +37,7 @@ B<openssl> B<enc>|I<cipher>
 [B<-nopad>]
 [B<-debug>]
 [B<-none>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
 
 =for openssl ifdef z engine
@@ -192,6 +192,8 @@ Use NULL cipher (no encryption or decryption of input).
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 NOTES
@@ -204,8 +206,8 @@ Use the L<openssl-list(1)> command to get a list of supported ciphers.
 
 Engines which provide entirely new encryption algorithms (such as the ccgost
 engine which provides gost89 algorithm) should be configured in the
-configuration file. Engines specified on the command line using -engine
-options can only be used for hardware-assisted implementations of
+configuration file. Engines specified on the command line using B<-engine>
+option can only be used for hardware-assisted implementations of
 ciphers which are supported by the OpenSSL core or another engine specified
 in the configuration file.
 
diff --git a/doc/man1/openssl-gendsa.pod.in b/doc/man1/openssl-gendsa.pod.in
index c15fdc9d03..46b9c70bba 100644
--- a/doc/man1/openssl-gendsa.pod.in
+++ b/doc/man1/openssl-gendsa.pod.in
@@ -22,9 +22,9 @@ B<openssl> B<gendsa>
 [B<-des>]
 [B<-des3>]
 [B<-idea>]
-[B<-engine> I<id>]
 [B<-verbose>]
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 [I<paramfile>]
 
 =for openssl ifdef engine
@@ -53,25 +53,20 @@ These options encrypt the private key with specified
 cipher before outputting it. A pass phrase is prompted for.
 If none of these options is specified no encryption is used.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
-
 =item B<-verbose>
 
 Print extra details about the operations being performed.
 
+{- $OpenSSL::safe::opt_r_item -}
+
+{- $OpenSSL::safe::opt_engine_item -}
+
 =item I<paramfile>
 
 The DSA parameter file to use. The parameters in this file determine
 the size of the private key. DSA parameters can be generated and
 examined using the L<openssl-dsaparam(1)> command.
 
-{- $OpenSSL::safe::opt_r_item -}
-
 =back
 
 =head1 NOTES
diff --git a/doc/man1/openssl-genpkey.pod b/doc/man1/openssl-genpkey.pod.in
index 69c642cdf7..c031f238af 100644
--- a/doc/man1/openssl-genpkey.pod
+++ b/doc/man1/openssl-genpkey.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-genpkey - generate a private key
@@ -12,12 +17,12 @@ B<openssl> B<genpkey>
 [B<-outform> B<DER>|B<PEM>]
 [B<-pass> I<arg>]
 [B<-I<cipher>>]
-[B<-engine> I<id>]
 [B<-paramfile> I<file>]
 [B<-algorithm> I<alg>]
 [B<-pkeyopt> I<opt>:I<value>]
 [B<-genparam>]
 [B<-text>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine
 
@@ -53,14 +58,6 @@ see L<openssl(1)/Pass Phrase Options>.
 This option encrypts the private key with the supplied cipher. Any algorithm
 name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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. If used this option should precede all other
-options.
-
 =item B<-algorithm> I<alg>
 
 Public key algorithm to use such as RSA, DSA or DH. If used this option must
@@ -105,6 +102,8 @@ are mutually exclusive.
 Print an (unencrypted) text representation of private and public keys and
 parameters along with the PEM or DER structure.
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 KEY GENERATION OPTIONS
diff --git a/doc/man1/openssl-genrsa.pod.in b/doc/man1/openssl-genrsa.pod.in
index 16b887be99..8a815ee960 100644
--- a/doc/man1/openssl-genrsa.pod.in
+++ b/doc/man1/openssl-genrsa.pod.in
@@ -24,10 +24,10 @@ B<openssl> B<genrsa>
 [B<-des3>]
 [B<-idea>]
 [B<-f4>|B<-3>]
-[B<-engine> I<id>]
 [B<-primes> I<num>]
 [B<-verbose>]
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 [B<numbits>]
 
 =for openssl ifdef engine
@@ -65,13 +65,6 @@ for if it is not supplied via the B<-passout> argument.
 
 The public exponent to use, either 65537 or 3. The default is 65537.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
-
 =item B<-primes> I<num>
 
 Specify the number of primes to use while generating the RSA key. The I<num>
@@ -85,6 +78,8 @@ Print extra details about the operations being performed.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =item B<numbits>
 
 The size of the private key to generate in bits. This must be the last option
diff --git a/doc/man1/openssl-pkcs12.pod.in b/doc/man1/openssl-pkcs12.pod.in
index 86c9de4670..bc2f4963d5 100644
--- a/doc/man1/openssl-pkcs12.pod.in
+++ b/doc/man1/openssl-pkcs12.pod.in
@@ -41,6 +41,7 @@ B<openssl> B<pkcs12>
 [B<-CSP> I<name>]
 {- $OpenSSL::safe::opt_trust_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine
 
@@ -271,6 +272,8 @@ Write I<name> as a Microsoft CSP name.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 NOTES
diff --git a/doc/man1/openssl-pkcs7.pod b/doc/man1/openssl-pkcs7.pod.in
index adfe54ec0e..f62b69b52b 100644
--- a/doc/man1/openssl-pkcs7.pod
+++ b/doc/man1/openssl-pkcs7.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-pkcs7 - PKCS#7 utility
@@ -15,7 +20,7 @@ B<openssl> B<pkcs7>
 [B<-print_certs>]
 [B<-text>]
 [B<-noout>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine
 
@@ -67,12 +72,7 @@ issuer names.
 Don't output the encoded version of the PKCS#7 structure (or certificates
 is B<-print_certs> is set).
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 =back
 
diff --git a/doc/man1/openssl-pkcs8.pod.in b/doc/man1/openssl-pkcs8.pod.in
index b53f0ee8ce..34b469ddbc 100644
--- a/doc/man1/openssl-pkcs8.pod.in
+++ b/doc/man1/openssl-pkcs8.pod.in
@@ -23,12 +23,12 @@ B<openssl> B<pkcs8>
 [B<-v2> I<alg>]
 [B<-v2prf> I<alg>]
 [B<-v1> I<alg>]
-[B<-engine> I<id>]
 [B<-scrypt>]
 [B<-scrypt_N> I<N>]
 [B<-scrypt_r> I<r>]
 [B<-scrypt_p> I<p>]
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine scrypt scrypt_N scrypt_r scrypt_p
 
@@ -135,13 +135,6 @@ This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used.  Some
 older implementations may not support PKCS#5 v2.0 and may require this option.
 If not specified PKCS#5 v2.0 form is used.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
-
 =item B<-scrypt>
 
 Uses the B<scrypt> algorithm for private key encryption using default
@@ -155,6 +148,8 @@ Sets the scrypt I<N>, I<r> or I<p> parameters.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 NOTES
diff --git a/doc/man1/openssl-pkey.pod b/doc/man1/openssl-pkey.pod.in
index b1aa4af454..e2905b6934 100644
--- a/doc/man1/openssl-pkey.pod
+++ b/doc/man1/openssl-pkey.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-pkey - public or private key processing tool
@@ -21,9 +26,9 @@ B<openssl> B<pkey>
 [B<-noout>]
 [B<-pubin>]
 [B<-pubout>]
-[B<-engine> I<id>]
 [B<-check>]
 [B<-pubcheck>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine
 
@@ -99,13 +104,6 @@ By default a private key is output: with this option a public
 key will be output instead. This option is automatically set if
 the input is a public key.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
-
 =item B<-check>
 
 This option checks the consistency of a key pair for both public and private
@@ -116,6 +114,8 @@ components.
 This option checks the correctness of either a public key or the public component
 of a key pair.
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 EXAMPLES
diff --git a/doc/man1/openssl-pkeyparam.pod b/doc/man1/openssl-pkeyparam.pod.in
index 36ff7f5245..4488119121 100644
--- a/doc/man1/openssl-pkeyparam.pod
+++ b/doc/man1/openssl-pkeyparam.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-pkeyparam - public key algorithm parameter processing tool
@@ -12,8 +17,8 @@ B<openssl> B<pkeyparam>
 [B<-out> I<filename>]
 [B<-text>]
 [B<-noout>]
-[B<-engine> I<id>]
 [B<-check>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine
 
@@ -48,17 +53,12 @@ Prints out the parameters in plain text in addition to the encoded version.
 
 Do not output the encoded version of the parameters.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
-
 =item B<-check>
 
 This option checks the correctness of parameters.
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 EXAMPLES
diff --git a/doc/man1/openssl-pkeyutl.pod.in b/doc/man1/openssl-pkeyutl.pod.in
index 27f1d26ac8..c239a0469a 100644
--- a/doc/man1/openssl-pkeyutl.pod.in
+++ b/doc/man1/openssl-pkeyutl.pod.in
@@ -34,7 +34,7 @@ B<openssl> B<pkeyutl>
 [B<-pkeyopt_passin> I<opt>[:I<passarg>]]
 [B<-hexdump>]
 [B<-asn1parse>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 [B<-engine_impl>]
 {- $OpenSSL::safe::opt_r_synopsis -}
 
@@ -179,12 +179,7 @@ hex dump the output data.
 Parse the ASN.1 output data, this is useful when combined with the
 B<-verifyrecover> option when an ASN1 structure is signed.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 =item B<-engine_impl>
 
diff --git a/doc/man1/openssl-req.pod.in b/doc/man1/openssl-req.pod.in
index 17ffe9ade6..cd49679d04 100644
--- a/doc/man1/openssl-req.pod.in
+++ b/doc/man1/openssl-req.pod.in
@@ -45,11 +45,11 @@ B<openssl> B<req>
 [B<-sigopt> I<nm>:I<v>]
 [B<-batch>]
 [B<-verbose>]
-[B<-engine> I<id>]
 [B<-sm2-id> I<string>]
 [B<-sm2-hex-id> I<hex-string>]
 {- $OpenSSL::safe::opt_name_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef engine keygen_engine sm2-id sm2-hex-id
 
@@ -301,13 +301,6 @@ Non-interactive mode.
 
 Print extra details about the operations being performed.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
-
 =item B<-keygen_engine> I<id>
 
 Specifies an engine (by its unique I<id> string) which would be used
@@ -327,6 +320,8 @@ argument for this option is string of hexadecimal digits.
 
 {- $OpenSSL::safe::opt_r_item -}
 
+{- $OpenSSL::safe::opt_engine_item -}
+
 =back
 
 =head1 CONFIGURATION FILE FORMAT
diff --git a/doc/man1/openssl-rsa.pod b/doc/man1/openssl-rsa.pod.in
index 9e1be94a26..b391487719 100644
--- a/doc/man1/openssl-rsa.pod
+++ b/doc/man1/openssl-rsa.pod.in
@@ -1,5 +1,10 @@
 =pod
 
+=begin comment
+{- join("\n", @autowarntext) -}
+
+=end comment
+
 =head1 NAME
 
 openssl-rsa - RSA key processing tool
@@ -34,7 +39,7 @@ B<openssl> B<rsa>
 [B<-pubout>]
 [B<-RSAPublicKey_in>]
 [B<-RSAPublicKey_out>]
-[B<-engine> I<id>]
+{- $OpenSSL::safe::opt_engine_synopsis -}
 
 =for openssl ifdef pvk-strong pvk-weak pvk-none engine
 
@@ -126,12 +131,7 @@ the input is a public key.
 
 Like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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.
+{- $OpenSSL::safe::opt_engine_item -}
 
 =back
 
diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in
index f010e60679..8bd6c9eec1 100644
--- a/doc/man1/openssl-s_client.pod.in
+++ b/doc/man1/openssl-s_client.pod.in
@@ -112,7 +112,6 @@ B<openssl> B<s_client>
 [B<-starttls> I<protocol>]
 [B<-xmpphost> I<hostname>]
 [B<-name> I<hostname>]
-[B<-engine> I<id>]
 [B<-tlsextdebug>]
 [B<-no_ticket>]
 [B<-sess_out> I<filename>]
@@ -131,6 +130,7 @@ B<openssl> B<s_client>
 {- $OpenSSL::safe::opt_x_synopsis -}
 {- $OpenSSL::safe::opt_trust_synopsis -}
 {- $OpenSSL::safe::opt_r_synopsis -}
+{- $OpenSSL::safe::opt_engine_synopsis -}
 [I<host>:I<port>]
 
 =for openssl ifdef engine ssl_client_engine ct noct ctlogfile
@@ -628,13 +628,6 @@ Output SSL session to I<filename>.
 Load SSL session from I<filename>. The client will attempt to resume a
 connection from this session.
 
-=item B<-engine> I<id>
-
-Specifying an engine (by its unique I<id> string) will cause this command
-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 ava