Use EXAMPLES not EXAMPLE for section title
authorRich Salz <rsalz@akamai.com>
Thu, 15 Aug 2019 18:26:08 +0000 (14:26 -0400)
committerDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Sun, 18 Aug 2019 22:06:39 +0000 (00:06 +0200)
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)

44 files changed:
doc/man1/engine.pod
doc/man1/errstr.pod
doc/man1/pkeyparam.pod
doc/man3/ASYNC_start_job.pod
doc/man3/BIO_find_type.pod
doc/man3/BIO_new.pod
doc/man3/BIO_s_accept.pod
doc/man3/BIO_s_bio.pod
doc/man3/BIO_s_connect.pod
doc/man3/BIO_s_fd.pod
doc/man3/BIO_set_callback.pod
doc/man3/CRYPTO_THREAD_run_once.pod
doc/man3/EVP_DigestInit.pod
doc/man3/EVP_MAC.pod
doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod
doc/man3/EVP_PKEY_decrypt.pod
doc/man3/EVP_PKEY_derive.pod
doc/man3/EVP_PKEY_encrypt.pod
doc/man3/EVP_PKEY_sign.pod
doc/man3/EVP_PKEY_verify.pod
doc/man3/EVP_PKEY_verify_recover.pod
doc/man3/OCSP_REQUEST_new.pod
doc/man3/OSSL_CMP_ITAV_set0.pod
doc/man3/OSSL_CRMF_pbmp_new.pod
doc/man3/OSSL_PARAM_construct_from_text.pod
doc/man3/PKCS12_newpass.pod
doc/man3/SSL_CTX_config.pod
doc/man3/SSL_CTX_dane_enable.pod
doc/man3/SSL_CTX_get0_param.pod
doc/man3/SSL_set1_host.pod
doc/man3/X509_VERIFY_PARAM_set_flags.pod
doc/man7/EVP_KDF_HKDF.pod
doc/man7/EVP_KDF_SCRYPT.pod
doc/man7/EVP_KDF_SS.pod
doc/man7/EVP_KDF_SSHKDF.pod
doc/man7/EVP_KDF_TLS1_PRF.pod
doc/man7/EVP_KDF_X942.pod
doc/man7/EVP_KDF_X963.pod
doc/man7/Ed25519.pod
doc/man7/SM2.pod
doc/man7/X25519.pod
doc/man7/bio.pod
util/find-doc-nits

index 446b198..e0f881a 100644 (file)
@@ -64,7 +64,7 @@ See the example below.
 
 =back
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 To list all the commands available to a dynamic engine:
 
index ba6fc81..9ba2091 100644 (file)
@@ -20,7 +20,7 @@ second colon.
 
 None.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The error code:
 
index 048a1f2..32dbe51 100644 (file)
@@ -60,7 +60,7 @@ This option checks the correctness of parameters.
 
 =back
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Print out text version of parameters:
 
index 5ac368d..c8c30bf 100644 (file)
@@ -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:
 
index 7a84b6d..354e347 100644 (file)
@@ -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:
 
index db1e060..d75e63b 100644 (file)
@@ -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:
 
index c50d32f..e6ad95b 100644 (file)
@@ -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.
index a457153..bad818c 100644 (file)
@@ -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
index eb11557..01fae19 100644 (file)
@@ -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.
index c9d29bc..f4f4239 100644 (file)
@@ -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":
 
index afa482d..9537a2e 100644 (file)
@@ -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
index 8ccd05e..ee413e7 100644 (file)
@@ -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.
 
index 1cc07b1..bdc48c3 100644 (file)
@@ -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.
index 6cc28a7..4358ca3 100644 (file)
@@ -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>
index 72a5b0f..7fc833e 100644 (file)
@@ -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":
index cc87c00..e0629ac 100644 (file)
@@ -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":
index a2363af..a78c1ee 100644 (file)
@@ -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):
 
index 8d54326..d6516e7 100644 (file)
@@ -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):
 
index 1e9742d..73ca8ba 100644 (file)
@@ -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
index b9211b8..d48edb5 100644 (file)
@@ -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:
 
index 5b0d15a..0212202 100644 (file)
@@ -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:
 
index 22538fd..2b425a3 100644 (file)
@@ -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:
 
index db670dc..e9d260f 100644 (file)
@@ -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>:
index 082b0bf..348f47f 100644 (file)
@@ -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
index cdd30ff..4ebfa69 100644 (file)
@@ -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";
index 5dc08bd..6c7ff81 100644 (file)
@@ -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:
 
index 14cfcdf..491fbcb 100644 (file)
@@ -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.
index a05009e..dfdc3d2 100644 (file)
@@ -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:
 
index f051c5a..c43d6f9 100644 (file)
@@ -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.
index 795bbf0..19e7f18 100644 (file)
@@ -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:
 
index 3fc6ec3..98bc6fd 100644 (file)
@@ -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
index d8ee7f6..1b5aaa6 100644 (file)
@@ -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>:
index 2188b13..c511c7c 100644 (file)
@@ -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":
index a44dc63..aa50164 100644 (file)
@@ -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.
index 958089d..5c56fbd 100644 (file)
@@ -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:
 
index e233e86..04a646c 100644 (file)
@@ -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:
index 4c73139..02331ec 100644 (file)
@@ -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":
index df93e86..644cad8 100644 (file)
@@ -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:
index 77b878f..130c923 100644 (file)
@@ -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":
index 12bc64b..8269f2f 100644 (file)
@@ -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:
index 05c8a34..31f58db 100644 (file)
@@ -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:
index 7f0bdff..6af40c6 100644 (file)
@@ -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:
index 18f1125..bc1fb1e 100644 (file)
@@ -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:
 
index 563a695..690d940 100755 (executable)
@@ -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"