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: NMatt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3830)

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>
 

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
 

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
 

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>.

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
 

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.

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
 

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
 

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

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

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.
 

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)>,

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.

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

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.

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

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

util/find-doc-nits

@@ -174,17 +174,14 @@ sub check()
     print "$id Bad =over $1\n"
         if $contents =~ /=over([^ ][^24])/;
 
-    # Look for multiple consecutive openssl #include lines.
-    # Consecutive because of files like md5.pod. Sometimes it's okay
-    # or necessary, as in ssl/SSL_set1_host.pod
     if ( $contents !~ /=for comment multiple includes/ ) {
+        # Look for multiple consecutive openssl #include lines
+        # (non-consecutive lines are okay; see man3/MD5.pod).
         if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
             my $count = 0;
             foreach my $line ( split /\n+/, $1 ) {
                 if ( $line =~ m@include <openssl/@ ) {
-                    if ( ++$count == 2 ) {
-                        print "$id has multiple includes\n";
-                    }
+                    print "$id has multiple includes\n" if ++$count == 2;
                 } else {
                     $count = 0;
                 }
@@ -192,18 +189,6 @@ sub check()
         }
     }
 
-    return unless $opt_s;
-
-    # Find what section this page is in.  If run from "." assume
-    # section 3.
-    my $section = 3;
-    $section = $1 if $dirname =~ /man([1-9])/;
-
-    foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
-        print "$id: missing $_ head1 section\n"
-            if $contents !~ /^=head1\s+${_}\s*$/m;
-    }
-
     open my $OUT, '>', $temp
         or die "Can't open $temp, $!";
     podchecker($filename, $OUT);
@@ -216,6 +201,17 @@ sub check()
     }
     close $OUT;
     unlink $temp || warn "Can't remove $temp, $!";
+
+    # Find what section this page is in; assume 3.
+    my $section = 3;
+    $section = $1 if $dirname =~ /man([1-9])/;
+
+    foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
+        # Skip "return values" if not -s
+        next if $_ eq 'RETURN VALUES' and not $opt_s;
+        print "$id: missing $_ head1 section\n"
+            if $contents !~ /^=head1\s+${_}\s*$/m;
+    }
 }
 
 my %dups;