Various doc fixes

Fix a =head1 section name
Fix a typo in POD label
Remove a spurious =back
Add a missing blank line
Avoid 'legacy' -- use 'deprecated' if still needed if we cannot just reword.
Always do strict checking
Do not warn about missing "RETURN VALUES" unless -s is set.
Change OpenSSL version 1.1 -> 1.1.0

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3830)

17 files changed, 62 insertions, 60 deletions

diff --git a/doc/man1/ca.pod b/doc/man1/ca.pod
index f2c003b880..26d648e924 100644
--- a/doc/man1/ca.pod
+++ b/doc/man1/ca.pod
@@ -188,11 +188,10 @@ for more information.
 
 =item B<-msie_hack>
 
-This is a legacy option to make B<ca> work with very old versions of
+This is a deprecated option to make B<ca> 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. The newer control "Xenroll" does not
-need this option.
+its use is strongly discouraged.
 
 =item B<-preserveDN>
 
diff --git a/doc/man1/enc.pod b/doc/man1/enc.pod
index 5691785cd5..13f1272d81 100644
--- a/doc/man1/enc.pod
+++ b/doc/man1/enc.pod
@@ -349,7 +349,7 @@ certain parameters. So if, for example, you want to use RC2 with a
 
 =head1 HISTORY
 
-The default digest was changed from MD5 to SHA256 in Openssl 1.1.
+The default digest was changed from MD5 to SHA256 in Openssl 1.1.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man1/storeutl.pod b/doc/man1/storeutl.pod
index 8874f34967..2792a554fa 100644
--- a/doc/man1/storeutl.pod
+++ b/doc/man1/storeutl.pod
@@ -20,7 +20,7 @@ B<uri> ...
 The B<storeutl> command can be used to display the contents (after decryption
 as the case may be) fetched from the given URIs.
 
-=head1 COMMAND OPTIONS
+=head1 OPTIONS
 
 =over 4
 
diff --git a/doc/man3/ASN1_STRING_print_ex.pod b/doc/man3/ASN1_STRING_print_ex.pod
index a521f78ea9..401de9b5d6 100644
--- a/doc/man3/ASN1_STRING_print_ex.pod
+++ b/doc/man3/ASN1_STRING_print_ex.pod
@@ -32,7 +32,8 @@ ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
 
 =head1 NOTES
 
-ASN1_STRING_print() is a legacy function which should be avoided in new applications.
+ASN1_STRING_print() is a deprecated function which should be avoided; use
+ASN1_STRING_print_ex() instead.
 
 Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
 suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod
index bb1047a347..91dcab1178 100644
--- a/doc/man3/BIO_connect.pod
+++ b/doc/man3/BIO_connect.pod
@@ -93,8 +93,8 @@ error.
 =head1 HISTORY
 
 BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
-BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL
-1.1.  Use the functions described above instead.
+BIO_get_accept_socket() and BIO_accept() were deprecated in
+OpenSSL 1.1.0.  Use the functions described above instead.
 
 =head1 SEE ALSO
 
diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod
index 8251dda94f..1a4ad52de0 100644
--- a/doc/man3/CRYPTO_get_ex_new_index.pod
+++ b/doc/man3/CRYPTO_get_ex_new_index.pod
@@ -143,8 +143,7 @@ will fail.
 
 =head1 RETURN VALUES
 
-CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the
-value B<0> is reserved for the legacy "app_data" API's.
+CRYPTO_get_ex_new_index() returns a new index or -1 on failure.
 
 CRYPTO_free_ex_index() and
 CRYPTO_set_ex_data() return 1 on success or 0 on failure.
diff --git a/doc/man3/EVP_CIPHER_meth_new.pod b/doc/man3/EVP_CIPHER_meth_new.pod
index f8478e38d4..e1583c5c55 100644
--- a/doc/man3/EVP_CIPHER_meth_new.pod
+++ b/doc/man3/EVP_CIPHER_meth_new.pod
@@ -222,9 +222,7 @@ L<EVP_EncryptInit>
 
 =head1 HISTORY
 
-The B<EVP_CIPHER> structure was openly available in OpenSSL before version
-1.1.
-The functions described here were added in OpenSSL version 1.1.
+The functions described here were added in OpenSSL version 1.1.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index d0bb33713a..933ffb2122 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -241,15 +241,13 @@ L<evp(7)>
 
 =head1 HISTORY
 
-B<EVP_MD_CTX> became opaque in OpenSSL 1.1.  Consequently, stack
-allocated B<EVP_MD_CTX>s are no longer supported.
-
 EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to
-EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.
+EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0.
 
 The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
-later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1()
-was removed in OpenSSL 1.1.0
+later, so now EVP_sha1() can be used with RSA and DSA.
+
+EVP_dss1() was removed in OpenSSL 1.1.0
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/OPENSSL_LH_stats.pod b/doc/man3/OPENSSL_LH_stats.pod
index f7118ff4fc..49351f4dce 100644
--- a/doc/man3/OPENSSL_LH_stats.pod
+++ b/doc/man3/OPENSSL_LH_stats.pod
@@ -21,9 +21,7 @@ OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics
 =head1 DESCRIPTION
 
 The B<LHASH> structure records statistics about most aspects of
-accessing the hash table.  This is mostly a legacy of Eric Young
-writing this library for the reasons of implementing what looked like
-a nice algorithm rather than for a particular software product.
+accessing the hash table.
 
 OPENSSL_LH_stats() prints out statistics on the size of the hash table, how
 many entries are in it, and the number and result of calls to the
diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 5fb14e9cef..b2130c8646 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -170,8 +170,9 @@ EVP_PKEY structure. The write routines use PKCS#8 private key format and are
 equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
 handle traditional and PKCS#8 format encrypted and unencrypted keys.
 
-PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy
-"traditional" format.
+PEM_write_bio_PrivateKey_traditional() writes out a private key in the
+"traditional" format with a simple private key marker and should only
+be used for compatibility with legacy programs.
 
 PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
 key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
@@ -459,7 +460,7 @@ The write routines return 1 for success or 0 for failure.
 =head1 HISTORY
 
 The old Netscape certificate sequences were no longer documented
-in OpenSSL 1.1; applications should use the PKCS7 standard instead
+in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
 as they will be formally deprecated in a future releases.
 
 =head1 SEE ALSO
diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod
index 9c2f9e19a6..ffddf81a59 100644
--- a/doc/man3/RAND_bytes.pod
+++ b/doc/man3/RAND_bytes.pod
@@ -30,7 +30,7 @@ RAND_bytes() returns 1 on success, -1 if not supported by the current
 RAND method, or 0 on other failure. The error code can be
 obtained by L<ERR_get_error(3)>.
 
-=head HISTORY
+=head1 HISTORY
 
 RAND_pseudo_bytes() was deprecated in OpenSSL 1.1.0.
 
diff --git a/doc/man3/SSL_CTX_set0_CA_list.pod b/doc/man3/SSL_CTX_set0_CA_list.pod
index 5e94f5c954..0f8b7da7e1 100644
--- a/doc/man3/SSL_CTX_set0_CA_list.pod
+++ b/doc/man3/SSL_CTX_set0_CA_list.pod
@@ -72,8 +72,6 @@ for failure.
 SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
 B<NULL> or an empty stack if no list was sent.
 
-=back
-
 =head1 SEE ALSO
 
 L<ssl(7)>,
diff --git a/doc/man3/SSL_set_bio.pod b/doc/man3/SSL_set_bio.pod
index 4230940bdb..01617521bf 100644
--- a/doc/man3/SSL_set_bio.pod
+++ b/doc/man3/SSL_set_bio.pod
@@ -30,58 +30,64 @@ ownership of one reference. Therefore it may be necessary to increment the
 number of references available using L<BIO_up_ref(3)> before calling the set0
 functions.
 
-SSL_set_bio() does a similar job as SSL_set0_rbio() and SSL_set0_wbio() except
-that it connects both the B<rbio> and the B<wbio> at the same time. This
-function transfers the ownership of B<rbio> and B<wbio> to B<ssl> except that
-the rules for this are much more complex. For this reason this function is
-considered a legacy function and SSL_set0_rbio() and SSL_set0_wbio() should be
-used in preference. The ownership rules are as follows:
+SSL_set_bio() is similar to SSL_set0_rbio() and SSL_set0_wbio() except
+that it connects both the B<rbio> and the B<wbio> at the same time, and
+transfers the ownership of B<rbio> and B<wbio> to B<ssl> according to
+the following set of rules:
 
 =over 2
 
 =item *
 
-If neither the rbio or wbio have changed from their previous values then nothing
-is done.
+If neither the B<rbio> or B<wbio> have changed from their previous values
+then nothing is done.
 
 =item *
 
-If the rbio and wbio parameters are different and both are different to their
+If the B<rbio> and B<wbio> parameters are different and both are different
+to their
 previously set values then one reference is consumed for the rbio and one
 reference is consumed for the wbio.
 
 =item *
 
-If the rbio and wbio parameters are the same and the rbio is not the same as the
-previously set value then one reference is consumed.
+If the B<rbio> and B<wbio> parameters are the same and the B<rbio> is not
+the same as the previously set value then one reference is consumed.
 
 =item *
 
-If the rbio and wbio parameters are the same and the rbio is the same as the
-previously set value, then no additional references are consumed.
+If the B<rbio> and B<wbio> parameters are the same and the B<rbio> is the
+same as the previously set value, then no additional references are consumed.
 
 =item *
 
-If the rbio and wbio parameters are different and the rbio is the same as the
-previously set value then one reference is consumed for the wbio and no
-references are consumed for the rbio.
+If the B<rbio> and B<wbio> parameters are different and the B<rbio> is the
+same as the
+previously set value then one reference is consumed for the B<wbio> and no
+references are consumed for the B<rbio>.
 
 =item *
 
-If the rbio and wbio parameters are different and the wbio is the same as the
-previously set value and the old rbio and wbio values were the same as each
-other then one reference is consumed for the rbio and no references are consumed
-for the wbio.
+If the B<rbio> and B<wbio> parameters are different and the B<wbio> is the
+same as the previously set value and the old B<rbio> and B<wbio> values
+were the same as each other then one reference is consumed for the B<rbio>
+and no references are consumed for the B<wbio>.
 
 =item *
 
-If the rbio and wbio parameters are different and the wbio is the same as the
-previously set value and the old rbio and wbio values were different to each
-other then one reference is consumed for the rbio and one reference is consumed
-for the wbio.
+If the B<rbio> and B<wbio> parameters are different and the B<wbio>
+is the same as the
+previously set value and the old B<rbio> and B<wbio> values were different
+to each
+other then one reference is consumed for the B<rbio> and one reference
+is consumed
+for the B<wbio>.
 
 =back
 
+Because of this complexity, this function should be avoided;
+use SSL_set0_rbio() and SSL_set0_wbio() instead.
+
 =head1 RETURN VALUES
 
 SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail.
diff --git a/doc/man3/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod
index be68b265eb..5579dabb77 100644
--- a/doc/man3/X509_NAME_get_index_by_NID.pod
+++ b/doc/man3/X509_NAME_get_index_by_NID.pod
@@ -48,8 +48,9 @@ of space needed in B<buf> (excluding the final null) is returned.
 
 =head1 NOTES
 
-X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are
-legacy functions which have various limitations which make them
+X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() should be
+considered deprecaated because they
+have various limitations which make them
 of minimal use in practice. They can only find the first matching
 entry and will copy the contents of the field verbatim: this can
 be highly confusing if the target is a multicharacter string type
diff --git a/doc/man3/X509_NAME_print_ex.pod b/doc/man3/X509_NAME_print_ex.pod
index e59512dc58..ad5009e715 100644
--- a/doc/man3/X509_NAME_print_ex.pod
+++ b/doc/man3/X509_NAME_print_ex.pod
@@ -35,10 +35,11 @@ characters. Multiple lines are used if the output (including indent) exceeds
 
 =head1 NOTES
 
-The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which
+The functions X509_NAME_oneline() and X509_NAME_print()
 produce a non standard output form, they don't handle multi character fields and
-have various quirks and inconsistencies. Their use is strongly discouraged in new
-applications.
+have various quirks and inconsistencies.
+Their use is strongly discouraged in new applications and they could
+be deprecated in a future release.
 
 Although there are a large number of possible flags for most purposes
 B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice.
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index e8428e1c57..a4e30614cd 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -292,8 +292,9 @@ of ORed.
 =head1 NOTES
 
 The above functions should be used to manipulate verification parameters
-instead of legacy functions which work in specific structures such as
-X509_STORE_CTX_set_flags().
+instead of functions which work in specific structures such as
+X509_STORE_CTX_set_flags() which are likely to be deprecated in a future
+release.
 
 =head1 BUGS
 
@@ -327,7 +328,7 @@ L<X509_check_ip(3)>
 =head1 HISTORY
 
 The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
-The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of
+The flag B<X509_V_FLAG_CB_ISSUER_CHECK> was deprecated in
 OpenSSL 1.1.0, and has no effect.
 
 =head1 COPYRIGHT
diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
index b4b76dd503..59cfc7cea7 100644
--- a/doc/man7/ossl_store.pod
+++ b/doc/man7/ossl_store.pod
@@ -89,6 +89,7 @@ only).
  OSSL_STORE_close(ctx);
 
 =head1 SEE ALSO
+
 L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
 
 =head1 COPYRIGHT