Do not have duplicate section heads

Change find-doc-nits to complain if a section header is repeated,
within a parent header (i.e., duplicate =head2 within a =head1).
In almost all cases, we just remove the duplicate header, as
it was a "continuation" of the =head1 that was already in affect.
In some cases, just remove "=head1 NOTES", possibly moving text
around, because the "NOTES" were really important parts of the
DESCRIPTION section.

No =headX sections should end with a period.
All =head1 labels should be in all uppercase.
No sub-head (=head2, etc) should be in all uppercase.
Update find-doc-nits to reject the above.

Fixup an internal POD link

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Paul Yang <kaishen.yy@antfin.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9631)

doc/man1/openssl-ciphers.pod

@@ -508,7 +508,7 @@ Note: these ciphers can also be used in SSL v3.
 
  TLS_DHE_DSS_WITH_RC4_128_SHA            DHE-DSS-RC4-SHA
 
-=head2 Elliptic curve cipher suites.
+=head2 Elliptic curve cipher suites
 
  TLS_ECDHE_RSA_WITH_NULL_SHA             ECDHE-RSA-NULL-SHA
  TLS_ECDHE_RSA_WITH_RC4_128_SHA          ECDHE-RSA-RC4-SHA

doc/man1/openssl-cms.pod

@@ -559,7 +559,7 @@ The B<-debug_decrypt> option can be used to disable the MMA attack protection
 and return an error if no recipient can be found: this option should be used
 with caution. For a fuller description see L<CMS_decrypt(3)>).
 
-=head1 CAdES Basic Electronic Signature (CAdES-BES)
+=head1 CADES BASIC ELECTRONIC SIGNATURE (CADES-BES)
 
 A CAdES Basic Electronic Signature (CAdES-BES), as defined in the European Standard ETSI EN 319 122-1 V1.1.1, contains:
 
@@ -625,7 +625,7 @@ the signers certificates.
 
 =back
 
-=head1 COMPATIBILITY WITH PKCS#7 format.
+=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

doc/man1/openssl-ocsp.pod

@@ -392,7 +392,7 @@ immediately available.
 
 =back
 
-=head1 OCSP Response verification.
+=head1 OCSP RESPONSE VERIFICATION
 
 OCSP Response follows the rules specified in RFC2560.
 

doc/man1/openssl-pkcs8.pod

@@ -209,7 +209,7 @@ It is possible to write out DER encoded encrypted private keys in
 PKCS#8 format because the encryption details are included at an ASN1
 level whereas the traditional format includes them at a PEM level.
 
-=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
+=head1 PKCS#5 V1.5 AND PKCS#12 ALGORITHMS
 
 Various algorithms can be used with the B<-v1> command line option,
 including PKCS#5 v1.5 and PKCS#12. These are described in more detail

doc/man1/openssl-pkeyutl.pod

@@ -309,12 +309,12 @@ The EC algorithm supports sign, verify and derive operations. The sign and
 verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for
 the B<-pkeyopt> B<digest> option.
 
-=head1 X25519 and X448 ALGORITHMS
+=head1 X25519 AND X448 ALGORITHMS
 
 The X25519 and X448 algorithms support key derivation only. Currently there are
 no additional options.
 
-=head1 Ed25519 and Ed448 ALGORITHMS
+=head1 ED25519 AND ED448 ALGORITHMS
 
 These algorithms only support signing and verifying. OpenSSL only implements the
 "pure" variants of these algorithms so raw data can be passed directly to them

doc/man3/CMS_compress.pod

@@ -17,8 +17,6 @@ is the compression algorithm to use or B<NID_undef> to use the default
 algorithm (zlib compression). B<in> is the content to be compressed.
 B<flags> is an optional set of flags.
 
-=head1 NOTES
-
 The only currently supported compression algorithm is zlib using the NID
 NID_zlib_compression.
 
@@ -41,8 +39,6 @@ The compressed data is included in the CMS_ContentInfo structure, unless
 B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
 practice and is not supported by SMIME_write_CMS().
 
-=head1 NOTES
-
 If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
 B<not> complete and outputting its contents via a function that does not
 properly finalize the B<CMS_ContentInfo> structure will give unpredictable

doc/man3/CMS_encrypt.pod

@@ -17,8 +17,6 @@ CMS_encrypt() creates and returns a CMS EnvelopedData structure. B<certs>
 is a list of recipient certificates. B<in> is the content to be encrypted.
 B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
 
-=head1 NOTES
-
 Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this
 function.
 
@@ -60,8 +58,6 @@ The data being encrypted is included in the CMS_ContentInfo structure, unless
 B<CMS_DETACHED> is set in which case it is omitted. This is rarely used in
 practice and is not supported by SMIME_write_CMS().
 
-=head1 NOTES
-
 If the flag B<CMS_STREAM> is set the returned B<CMS_ContentInfo> structure is
 B<not> complete and outputting its contents via a function that does not
 properly finalize the B<CMS_ContentInfo> structure will give unpredictable

doc/man3/CRYPTO_THREAD_run_once.pod

@@ -99,6 +99,15 @@ crypto.h where use of CRYPTO_THREAD_* types and functions is required.
 
 =head1 EXAMPLES
 
+You can find out if OpenSSL was configured with thread support:
+
+ #include <openssl/opensslconf.h>
+ #if defined(OPENSSL_THREADS)
+     /* thread support enabled */
+ #else
+     /* no thread support */
+ #endif
+
 This example safely initializes and uses a lock.
 
  #ifdef _WIN32
@@ -144,17 +153,6 @@ no longer in use and is unloaded.
 The simplest solution is to just "leak" the lock in applications and not
 repeatedly load/unload shared libraries that allocate locks.
 
-=head1 NOTES
-
-You can find out if OpenSSL was configured with thread support:
-
- #include <openssl/opensslconf.h>
- #if defined(OPENSSL_THREADS)
-     /* thread support enabled */
- #else
-     /* no thread support */
- #endif
-
 =head1 SEE ALSO
 
 L<crypto(7)>

doc/man3/EVP_EncryptInit.pod

@@ -406,7 +406,7 @@ Null cipher: does nothing.
 
 =back
 
-=head1 AEAD Interface
+=head1 AEAD INTERFACE
 
 The EVP interface for Authenticated Encryption with Associated Data (AEAD)
 modes are subtly altered and several additional I<ctrl> operations are supported
@@ -485,7 +485,7 @@ the length of the tag (with the C<tag> parameter set to NULL) when encrypting.
 The tag length is often referred to as B<M>. If not set a default value is
 used (12 for AES). When decrypting, the tag needs to be set before passing
 in data to be decrypted, but as in GCM and OCB mode, it can be set after
-passing additional authenticated data (see L<AEAD Interface>).
+passing additional authenticated data (see L</AEAD INTERFACE>).
 
 =item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL)
 

doc/man3/OSSL_trace_set_channel.pod

@@ -214,7 +214,7 @@ the following:
      BIO_dump(trc_out, bar, sizeof(bar));
  } OSSL_TRACE_END(TLS);
 
-=head1 Simple example
+=head2 Simple example
 
 An example with just a channel and constant prefix / suffix.
 

doc/man3/PKCS12_newpass.pod

@@ -17,8 +17,6 @@ PKCS12_newpass() changes the password of a PKCS12 structure.
 B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password
 and B<newpass> is the new password.
 
-=head1 NOTES
-
 Each of B<oldpass> and B<newpass> is independently interpreted as a string in
 the UTF-8 encoding. If it is not valid UTF-8, it is assumed to be ISO8859-1
 instead.
@@ -29,6 +27,15 @@ use. This may include passwords from local text files, or input from
 the terminal or command line. Refer to the documentation of
 L<UI_OpenSSL(3)>, for example.
 
+If the PKCS#12 structure does not have a password, then you must use the empty
+string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
+PKCS12_newpass() failure.
+
+If the wrong password is used for B<oldpass> then the function will fail,
+with a MAC verification error. In rare cases the PKCS12 structure does not
+contain a MAC: in this case it will usually fail with a decryption padding
+error.
+
 =head1 RETURN VALUES
 
 PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
@@ -83,17 +90,6 @@ the result to a new file.
  }
 
 
-=head1 NOTES
-
-If the PKCS#12 structure does not have a password, then you must use the empty
-string "" for B<oldpass>. Using NULL for B<oldpass> will result in a
-PKCS12_newpass() failure.
-
-If the wrong password is used for B<oldpass> then the function will fail,
-with a MAC verification error. In rare cases the PKCS12 structure does not
-contain a MAC: in this case it will usually fail with a decryption padding
-error.
-
 =head1 BUGS
 
 The password format is a NULL terminated ASCII string which is converted to

doc/man3/PKCS7_encrypt.pod

@@ -17,8 +17,6 @@ PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs>
 is a list of recipient certificates. B<in> is the content to be encrypted.
 B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags.
 
-=head1 NOTES
-
 Only RSA keys are supported in PKCS#7 and envelopedData so the recipient
 certificates supplied to this function must all contain RSA public keys, though
 they do not have to be signed using the RSA algorithm.
@@ -52,8 +50,6 @@ B<PKCS7_TEXT> is ignored.
 If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output
 suitable for streaming I/O: no data is read from the BIO B<in>.
 
-=head1 NOTES
-
 If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
 complete and outputting its contents via a function that does not
 properly finalize the B<PKCS7> structure will give unpredictable

doc/man3/PKCS7_sign.pod

@@ -22,8 +22,6 @@ The data to be signed is read from BIO B<data>.
 
 B<flags> is an optional set of flags.
 
-=head1 NOTES
-
 Any of the following flags (ored together) can be passed in the B<flags>
 parameter.
 
@@ -66,8 +64,6 @@ way data can be signed in a single pass.
 If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to
 which additional signers and capabilities can be added before finalization.
 
-=head1 NOTES
-
 If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not>
 complete and outputting its contents via a function that does not properly
 finalize the B<PKCS7> structure will give unpredictable results.

doc/man3/SSL_CTX_set_options.pod

@@ -313,7 +313,7 @@ unaware of the unpatched nature of the client.
 If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
 renegotiation B<always> succeeds.
 
-=head2 Patched OpenSSL client and unpatched server.
+=head2 Patched OpenSSL client and unpatched server
 
 If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
 B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections

doc/man3/SSL_CTX_use_psk_identity_hint.pod

@@ -85,8 +85,6 @@ check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or
 SSL_set_psk_server_callback() and use that. In this case the handshake digest
 will default to SHA-256 for any returned PSK.
 
-=head1 NOTES
-
 A connection established via a TLSv1.3 PSK will appear as if session resumption
 has occurred so that L<SSL_session_reused(3)> will return true.
 

doc/man3/SSL_shutdown.pod

@@ -15,8 +15,6 @@ SSL_shutdown - shut down a TLS/SSL connection
 SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
 close_notify shutdown alert to the peer.
 
-=head1 NOTES
-
 SSL_shutdown() tries to send the close_notify shutdown alert to the peer.
 Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
 a currently open session is considered closed and good and will be kept in the
@@ -52,6 +50,32 @@ SSL_shutdown() only closes the write direction.
 It is not possible to call SSL_write() after calling SSL_shutdown().
 The read direction is closed by the peer.
 
+The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
+If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
+handshake step has been finished or an error occurred.
+
+If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
+when the underlying BIO could not satisfy the needs of SSL_shutdown()
+to continue the handshake. In this case a call to SSL_get_error() with the
+return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
+B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
+taking appropriate action to satisfy the needs of SSL_shutdown().
+The action depends on the underlying BIO. When using a non-blocking socket,
+nothing is to be done, but select() can be used to check for the required
+condition. When using a buffering BIO, like a BIO pair, data must be written
+into or retrieved out of the BIO before being able to continue.
+
+After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
+to wait for the peer's close_notify alert.
+SSL_shutdown() will return 1 in that case.
+However, it is recommended to wait for it using SSL_read() instead.
+
+SSL_shutdown() can be modified to only set the connection to "shutdown"
+state but not actually send the close_notify alert messages,
+see L<SSL_CTX_set_quiet_shutdown(3)>.
+When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
+and return 1.
+
 =head2 First to close the connection
 
 When the application is the first party to send the close_notify
@@ -89,34 +113,6 @@ If successful, SSL_shutdown() will return 1.
 Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
 SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
 
-=head1 NOTES
-
-The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
-If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
-handshake step has been finished or an error occurred.
-
-If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
-when the underlying BIO could not satisfy the needs of SSL_shutdown()
-to continue the handshake. In this case a call to SSL_get_error() with the
-return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or
-B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
-taking appropriate action to satisfy the needs of SSL_shutdown().
-The action depends on the underlying BIO. When using a non-blocking socket,
-nothing is to be done, but select() can be used to check for the required
-condition. When using a buffering BIO, like a BIO pair, data must be written
-into or retrieved out of the BIO before being able to continue.
-
-After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
-to wait for the peer's close_notify alert.
-SSL_shutdown() will return 1 in that case.
-However, it is recommended to wait for it using SSL_read() instead.
-
-SSL_shutdown() can be modified to only set the connection to "shutdown"
-state but not actually send the close_notify alert messages,
-see L<SSL_CTX_set_quiet_shutdown(3)>.
-When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
-and return 1.
-
 =head1 RETURN VALUES
 
 The following return values can occur:

doc/man5/x509v3_config.pod

@@ -56,7 +56,7 @@ must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section fo
 
 The following sections describe each supported extension in detail.
 
-=head2 Basic Constraints.
+=head2 Basic Constraints
 
 This is a multi valued extension which indicates whether a certificate is
 a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
@@ -81,7 +81,7 @@ below this one in a chain. So if you have a CA with a pathlen of zero it can
 only be used to sign end user certificates and not further CAs.
 
 
-=head2 Key Usage.
+=head2 Key Usage
 
 Key usage is a multi valued extension consisting of a list of names of the
 permitted key usages.
@@ -97,7 +97,7 @@ Examples:
  keyUsage=critical, keyCertSign
 
 
-=head2 Extended Key Usage.
+=head2 Extended Key Usage
 
 This extensions consists of a list of usages indicating purposes for which
 the certificate public key can be used for,
@@ -126,7 +126,7 @@ Examples:
  extendedKeyUsage=serverAuth,clientAuth
 
 
-=head2 Subject Key Identifier.
+=head2 Subject Key Identifier
 
 This is really a string extension and can take two possible values. Either
 the word B<hash> which will automatically follow the guidelines in RFC3280
@@ -138,7 +138,7 @@ Example:
  subjectKeyIdentifier=hash
 
 
-=head2 Authority Key Identifier.
+=head2 Authority Key Identifier
 
 The authority key identifier extension permits two options. keyid and issuer:
 both can take the optional value "always".
@@ -156,7 +156,7 @@ Example:
  authorityKeyIdentifier=keyid,issuer
 
 
-=head2 Subject Alternative Name.
+=head2 Subject Alternative Name
 
 The subject alternative name extension allows various literal values to be
 included in the configuration file. These include B<email> (an email address)
@@ -195,7 +195,7 @@ Examples:
  CN=My Name
 
 
-=head2 Issuer Alternative Name.
+=head2 Issuer Alternative Name
 
 The issuer alternative name option supports all the literal options of
 subject alternative name. It does B<not> support the email:copy option because
@@ -208,7 +208,7 @@ Example:
  issuerAltName = issuer:copy
 
 
-=head2 Authority Info Access.
+=head2 Authority Info Access
 
 The authority information access extension gives details about how to access
 certain information relating to the CA. Its syntax is accessOID;location
@@ -300,7 +300,7 @@ Example:
  CN=Some Name
 
 
-=head2 Certificate Policies.
+=head2 Certificate Policies
 
 This is a I<raw> extension. All the fields of this extension can be set by
 using the appropriate syntax.
@@ -424,7 +424,7 @@ Example:
 The following extensions are non standard, Netscape specific and largely
 obsolete. Their use in new applications is discouraged.
 
-=head2 Netscape String extensions.
+=head2 Netscape String extensions
 
 Netscape Comment (B<nsComment>) is a string extension containing a comment
 which will be displayed when the certificate is viewed in some browsers.

doc/man7/RAND_DRBG.pod

@@ -209,7 +209,7 @@ The last feature has been added to support the common practice used with
 previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
 
 
-=head2 Entropy Input vs. Additional Data
+=head2 Entropy Input and Additional Data
 
 The DRBG distinguishes two different types of random input: I<entropy>,
 which comes from a trusted source, and I<additional input>',

doc/man7/provider.pod

@@ -204,7 +204,7 @@ an implementation.
 The method object that is fetched can then be used with diverse other
 functions that use them, for example L<EVP_DigestInit_ex(3)>.
 
-=head2 Implicit fetch
+=head3 Implicit fetch
 
 I<NOTE: This section is mostly interesting to OpenSSL users.>
 

util/find-doc-nits

@@ -159,12 +159,44 @@ sub check_section_location()
     my $section = shift;
     my $before = shift;
 
-    return
+    return unless $contents =~ /=head1 $section/
-        unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/;
+        and $contents =~ /=head1 $before/;
-    print "$id $section should be placed before $before section\n"
+    print "$id $section should appear before $before section\n"
         if $contents =~ /=head1 $before.*=head1 $section/ms;
 }
 
+# Check if a =head1 is duplicated, or a =headX is duplicated within a
+# =head1.  Treats =head2 =head3 as equivalent -- it doesn't reset the head3
+# sets if it finds a =head2 -- but that is good enough for now. Also check
+# for proper capitalization, trailing periods, etc.
+sub check_head_style()
+{
+    my $id = shift;
+    my $contents = shift;
+    my %head1;
+    my %subheads;
+
+    foreach my $line ( split /\n+/, $contents ) {
+        next unless $line =~ /^=head/;
+        if ( $line =~ /head1/ ) {
+            print "$id duplicate section $line\n"
+                if defined $head1{$line};
+            $head1{$line} = 1;
+            %subheads = ();
+        } else {
+            print "$id duplicate subsection $line\n"
+                if defined $subheads{$line};
+            $subheads{$line} = 1;
+        }
+        print "$id period in =head\n"
+            if $line =~ /\.[^\w]/ or $line =~ /\.$/;
+        print "$id not all uppercase in =head1\n"
+            if $line =~ /head1.*[a-z]/;
+        print "$id all uppercase in subhead\n"
+            if $line =~ /head[234][ A-Z0-9]+$/;
+    }
+}
+
 sub check()
 {
     my $filename = shift;
@@ -179,6 +211,7 @@ sub check()
     }
 
     my $id = "${filename}:1:";
+    &check_head_style($id, $contents);
 
     # Check ordering of some sections in man3
     if ( $filename =~ m|man3/| ) {