Use EXAMPLES not EXAMPLE for section title

And update find-doc-nits to complain if "=head1 EXAMPLE" is found.

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)

doc/man1/engine.pod

@@ -64,7 +64,7 @@ See the example below.
 
 =back
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 To list all the commands available to a dynamic engine:
 

doc/man1/errstr.pod

@@ -20,7 +20,7 @@ second colon.
 
 None.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The error code:
 

doc/man1/pkeyparam.pod

@@ -60,7 +60,7 @@ This option checks the correctness of parameters.
 
 =back
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Print out text version of parameters:
 

doc/man3/ASYNC_start_job.pod

@@ -174,7 +174,7 @@ is included, commonly as one of the first included headers. Therefore
 it is defined as an application developer's responsibility to include
 windows.h prior to async.h.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The following example demonstrates how to use most of the core async APIs:
 

doc/man3/BIO_find_type.pod

@@ -40,7 +40,7 @@ BIO_next() returns the next BIO in a chain.
 
 BIO_method_type() returns the type of the BIO B<b>.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Traverse a chain looking for digest BIOs:
 

doc/man3/BIO_new.pod

@@ -53,7 +53,7 @@ on it other than the discarded return value.
 
 BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Create a memory BIO:
 

doc/man3/BIO_s_accept.pod

@@ -174,7 +174,7 @@ BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
 
 BIO_new_accept() returns a BIO or NULL on error.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example accepts two connections on port 4444, sends messages
 down each and finally closes both down.

doc/man3/BIO_s_bio.pod

@@ -133,7 +133,7 @@ locations for B<bio1> and B<bio2>. Check the error stack for more information.
 
 [XXXXX: More return values need to be added here]
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The BIO pair can be used to have full control over the network access of an
 application. The application can call select() on the socket as required

doc/man3/BIO_s_connect.pod

@@ -163,7 +163,7 @@ BIO_set_nbio() always returns 1.
 BIO_do_connect() returns 1 if the connection was successfully
 established and 0 or -1 if the connection failed.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This is example connects to a webserver on the local host and attempts
 to retrieve a page and copy the result to standard output.

doc/man3/BIO_s_fd.pod

@@ -68,7 +68,7 @@ been initialized.
 BIO_new_fd() returns the newly allocated BIO or NULL is an error
 occurred.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This is a file descriptor BIO version of "Hello World":
 

doc/man3/BIO_set_callback.pod

@@ -223,7 +223,7 @@ via a call to BIO_set_callback_arg().
 BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
 operations.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The BIO_debug_callback() function is a good example, its source is
 in crypto/bio/bio_cb.c

doc/man3/CRYPTO_THREAD_run_once.pod

@@ -97,7 +97,7 @@ one of the first included headers. Therefore it is defined as an
 application developer's responsibility to include windows.h prior to
 crypto.h where use of CRYPTO_THREAD_* types and functions is required.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example safely initializes and uses a lock.
 

doc/man3/EVP_DigestInit.pod

@@ -494,7 +494,7 @@ as macros.
 EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration
 or control.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example digests the data "Test Message\n" and "Hello World\n", using the
 digest name passed on the command line.

doc/man3/EVP_MAC.pod

@@ -272,7 +272,7 @@ If it isn't set, a call to EVP_MAC_init() should get it set.
 
 EVP_MAC_do_all_ex() returns nothing at all.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
   #include <stdlib.h>
   #include <stdio.h>

doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod

@@ -121,7 +121,7 @@ All these functions return 1 for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using SHA-256 with the secret key "secret",
 salt value "salt" and info value "label":

doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod

@@ -70,7 +70,7 @@ All these functions return 1 for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using SHA-256 with the secret key "secret"
 and seed value "seed":

doc/man3/EVP_PKEY_decrypt.pod

@@ -41,7 +41,7 @@ EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Decrypt data using OAEP (for RSA keys):
 

doc/man3/EVP_PKEY_derive.pod

@@ -56,7 +56,7 @@ for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Derive shared secret (for example DH or EC keys):
 

doc/man3/EVP_PKEY_encrypt.pod

@@ -41,7 +41,7 @@ EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
 L<d2i_X509(3)> for means to load a public key. You may also simply

doc/man3/EVP_PKEY_sign.pod

@@ -46,7 +46,7 @@ EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Sign data using RSA with PKCS#1 padding and SHA256 digest:
 

doc/man3/EVP_PKEY_verify.pod

@@ -44,7 +44,7 @@ A negative value indicates an error other that signature verification failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Verify signature using PKCS#1 and SHA256 digest:
 

doc/man3/EVP_PKEY_verify_recover.pod

@@ -49,7 +49,7 @@ EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for succes
 and 0 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Recover digest originally signed using PKCS#1 and SHA256 digest:
 

doc/man3/OCSP_REQUEST_new.pod

@@ -75,7 +75,7 @@ corresponding to each certificate.
 OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
 OCSP responders.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
 B<issuer>:

doc/man3/OSSL_CMP_ITAV_set0.pod

@@ -59,7 +59,7 @@ return the respective pointer or NULL if their input is NULL.
 
 OSSL_CMP_ITAV_push0_stack_item() returns 1 on success, 0 on error.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The following code creates and sets a structure representing a generic
 InfoTypeAndValue sequence, using an OID created from text as type, and an

doc/man3/OSSL_CRMF_pbmp_new.pod

@@ -49,7 +49,7 @@ OSSL_CRMF_pbm_new() returns 1 on success, 0 on error.
 OSSL_CRMF_pbmp_new() returns a new and initialized OSSL_CRMF_PBMPARAMETER
 structure, or NULL on error.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
  OSSL_CRMF_PBMPARAMETER *pbm = NULL;
  unsigned char *msg = "Hello";

doc/man3/OSSL_PARAM_construct_from_text.pod

@@ -81,7 +81,7 @@ All other attributes are ignored.
 The I<data_size> attribute can be zero, meaning that the parameter it
 describes expects arbitrary length data.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Code that looked like this:
 

doc/man3/PKCS12_newpass.pod

@@ -34,7 +34,7 @@ L<UI_OpenSSL(3)>, for example.
 PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
 retrieve the most recent error from PKCS12_newpass() with ERR_get_error().
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example loads a PKCS#12 file, changes its password and writes out
 the result to a new file.

doc/man3/SSL_CTX_config.pod

@@ -33,7 +33,7 @@ file syntax.
 SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
 occurred.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 If the file "config.cnf" contains the following:
 

doc/man3/SSL_CTX_dane_enable.pod

@@ -181,7 +181,7 @@ The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(),
 SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
 before they were called.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
 DNSSEC-validated TLSA records.

doc/man3/SSL_CTX_get0_param.pod

@@ -37,7 +37,7 @@ B<X509_VERIFY_PARAM> structure.
 SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
 for failure.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Check hostname matches "www.foo.com" in peer certificate:
 

doc/man3/SSL_set1_host.pod

@@ -71,7 +71,7 @@ applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
 matched.  Otherwise, it returns the matched peername.  To determine
 whether verification succeeded call L<SSL_get_verify_result(3)>.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Suppose "smtp.example.com" is the MX host of the domain "example.com".
 The calls below will arrange to match either the MX hostname or the

doc/man3/X509_VERIFY_PARAM_set_flags.pod

@@ -346,7 +346,7 @@ If CRLs checking is enable CRLs are expected to be available in the
 corresponding B<X509_STORE> structure. No attempt is made to download
 CRLs from the CRL distribution points extension.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Enable CRL checking when performing certificate verification during SSL
 connections associated with an B<SSL_CTX> structure B<ctx>:

doc/man7/EVP_KDF_HKDF.pod

@@ -126,7 +126,7 @@ the intermediate fixed-length pseudorandom key otherwise an error will occur.
 For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
 after setting the mode and digest on the C<EVP_KDF_CTX>.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using SHA-256 with the secret key "secret",
 salt value "salt" and info value "label":

doc/man7/EVP_KDF_SCRYPT.pod

@@ -78,7 +78,7 @@ A context for scrypt can be obtained by calling:
 The output length of an scrypt key derivation is specified via the
 B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives a 64-byte long test vector using scrypt with the password
 "password", salt "NaCl" and N = 1024, r = 8, p = 16.

doc/man7/EVP_KDF_SS.pod

@@ -102,7 +102,7 @@ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
 The output length of an SSKDF is specified via the C<keylen>
 parameter to the L<EVP_KDF_derive(3)> function.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
 and fixedinfo value "label":
@@ -127,8 +127,6 @@ and fixedinfo value "label":
 
   EVP_KDF_CTX_free(kctx);
 
-=head1 EXAMPLE
-
 This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
 fixedinfo value "label" and salt "salt":
 
@@ -158,8 +156,6 @@ fixedinfo value "label" and salt "salt":
 
   EVP_KDF_CTX_free(kctx);
 
-=head1 EXAMPLE
-
 This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
 fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
 

doc/man7/EVP_KDF_SSHKDF.pod

@@ -120,7 +120,7 @@ to obtain the requisite length is not meaningful. The caller must
 allocate a buffer of the desired length, and pass that buffer to the
 L<EVP_KDF_derive(3)> function along with the desired length.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
 "xcghash" and "session_id" values:

doc/man7/EVP_KDF_TLS1_PRF.pod

@@ -97,7 +97,7 @@ an error will occur.
 The output length of the PRF is specified by the C<keylen> parameter to the
 EVP_KDF_derive() function.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using SHA-256 with the secret key "secret"
 and seed value "seed":

doc/man7/EVP_KDF_X942.pod

@@ -90,7 +90,7 @@ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
 The output length of an X942KDF is specified via the C<keylen>
 parameter to the L<EVP_KDF_derive(3)> function.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 24 bytes, with the secret key "secret" and a random user
 keying material:

doc/man7/EVP_KDF_X963.pod

@@ -81,7 +81,7 @@ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963);
 The output length of an X963KDF is specified via the C<keylen>
 parameter to the L<EVP_KDF_derive(3)> function.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes, with the secret key "secret" and sharedinfo
 value "label":

doc/man7/Ed25519.pod

@@ -53,7 +53,7 @@ Ed25519 and Ed448 can be tested within L<speed(1)> application since version 1.1
 Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is
 specified, then both Ed25519 and Ed448 are benchmarked.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example generates an B<ED25519> private key and writes it to standard
 output in PEM format:

doc/man7/SM2.pod

@@ -41,7 +41,7 @@ done by calling:
 And normally there is no need to pass a B<pctx> parameter to EVP_DigestSignInit()
 or EVP_DigestVerifyInit() in such a scenario.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify
 a message with the SM2 signature algorithm and the SM3 hash algorithm:

doc/man7/X25519.pod

@@ -37,7 +37,7 @@ X25519 or X448 public keys can be set directly using
 L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
 structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example generates an B<X25519> private key and writes it to standard
 output in PEM format:

doc/man7/bio.pod

@@ -52,7 +52,7 @@ pointer to a BIO_METHOD. There is a naming convention for such functions:
 a source/sink BIO is normally called BIO_s_*() and a filter BIO
 BIO_f_*();
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Create a memory BIO:
 

util/find-doc-nits

@@ -182,9 +182,9 @@ sub check()
 
     # Check ordering of some sections in man3
     if ( $filename =~ m|man3/| ) {
-        &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLE");
+        &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
         &check_section_location($id, $contents, "SEE ALSO", "HISTORY");
-        &check_section_location($id, $contents, "EXAMPLE", "SEE ALSO");
+        &check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
     }
 
     &name_synopsis($id, $filename, $contents)
@@ -197,6 +197,8 @@ sub check()
         if $contents !~ /=cut\n$/;
     print "$id more than one cut line.\n"
         if $contents =~ /=cut.*=cut/ms;
+    print "$id EXAMPLE not EXAMPLES section.\n"
+        if $contents =~ /=head1 EXAMPLE[^S]/;
     print "$id missing copyright\n"
         if $contents !~ /Copyright .* The OpenSSL Project Authors/;
     print "$id copyright not last\n"