From bb82531f6592f0e9af28d3502346191a465374a3 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sun, 29 Sep 2019 17:10:59 +0200 Subject: [PATCH] POD: stop abusing comment OpenSSL uses some POD directives masquerading as 'comment' ('=for comment' etc). This is abusive and confusing. Instead, we use our own keyword. =for openssl whatever =begin openssl whatever =end openssl (we have never used the multiline form, but might start one day) Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/10048) --- doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod | 2 +- doc/internal/man3/ossl_param_bld_init.pod | 2 +- doc/man1/openssl-cmds.pod | 2 +- doc/man1/openssl-ts.pod | 2 +- doc/man1/tsget.pod | 2 +- doc/man3/BIO_f_base64.pod | 2 +- doc/man3/BIO_f_cipher.pod | 2 +- doc/man3/BIO_f_md.pod | 2 +- doc/man3/BIO_f_ssl.pod | 2 +- doc/man3/BIO_get_ex_new_index.pod | 2 +- doc/man3/DEFINE_STACK_OF.pod | 2 +- doc/man3/EVP_EncryptInit.pod | 2 +- doc/man3/EVP_aes.pod | 2 +- doc/man3/EVP_aria.pod | 2 +- doc/man3/EVP_camellia.pod | 2 +- doc/man3/EVP_des.pod | 2 +- doc/man3/OPENSSL_LH_COMPFUNC.pod | 2 +- doc/man3/OSSL_PARAM_int.pod | 2 +- doc/man3/OSSL_trace_enabled.pod | 2 +- doc/man3/OSSL_trace_set_channel.pod | 2 +- doc/man3/PEM_read_CMS.pod | 2 +- doc/man3/SSL_get_all_async_fds.pod | 2 +- doc/man3/SSL_set_async_callback.pod | 2 +- doc/man3/X509_dup.pod | 2 +- doc/man3/d2i_X509.pod | 2 +- doc/man7/bio.pod | 2 +- doc/man7/ossl_store-file.pod | 2 +- doc/man7/ossl_store.pod | 2 +- doc/man7/provider-cipher.pod | 2 +- doc/man7/provider-digest.pod | 2 +- doc/man7/provider-keyexch.pod | 2 +- doc/man7/provider-mac.pod | 2 +- doc/man7/provider-signature.pod | 2 +- doc/man7/provider.pod | 10 +--------- util/find-doc-nits | 4 ++-- 35 files changed, 36 insertions(+), 44 deletions(-) diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod index 7917c4c812..a78193c2e2 100644 --- a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod +++ b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod @@ -9,7 +9,7 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set =head1 SYNOPSIS -=for comment generic +=for openssl generic #include "crypto/sparse_array.h" diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod index 5179a8d64a..062e2c293c 100644 --- a/doc/internal/man3/ossl_param_bld_init.pod +++ b/doc/internal/man3/ossl_param_bld_init.pod @@ -15,7 +15,7 @@ ossl_param_bld_push_octet_ptr =head1 SYNOPSIS -=for comment generic +=for openssl generic #include "internal/params_build.h" diff --git a/doc/man1/openssl-cmds.pod b/doc/man1/openssl-cmds.pod index 5c4f06e1de..9f7d6c654d 100644 --- a/doc/man1/openssl-cmds.pod +++ b/doc/man1/openssl-cmds.pod @@ -55,7 +55,7 @@ x509 =head1 SYNOPSIS -=for comment generic +=for openssl generic B I B<-help> | [I<-option> | I<-option> I] ... [I] ... diff --git a/doc/man1/openssl-ts.pod b/doc/man1/openssl-ts.pod index c97909d526..2e095d4d13 100644 --- a/doc/man1/openssl-ts.pod +++ b/doc/man1/openssl-ts.pod @@ -623,7 +623,7 @@ You could also look at the 'test' directory for more examples. =head1 BUGS -=for comment foreign manuals: procmail(1), perl(1) +=for openssl foreign manuals: procmail(1), perl(1) =over 2 diff --git a/doc/man1/tsget.pod b/doc/man1/tsget.pod index 19c689ef6c..d006198c67 100644 --- a/doc/man1/tsget.pod +++ b/doc/man1/tsget.pod @@ -185,7 +185,7 @@ example: =head1 SEE ALSO -=for comment foreign manuals: WWW::Curl::Easy +=for openssl foreign manuals: WWW::Curl::Easy L, L, diff --git a/doc/man3/BIO_f_base64.pod b/doc/man3/BIO_f_base64.pod index 6ac98e953e..69de0077f7 100644 --- a/doc/man3/BIO_f_base64.pod +++ b/doc/man3/BIO_f_base64.pod @@ -6,7 +6,7 @@ BIO_f_base64 - base64 BIO filter =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man3/BIO_f_cipher.pod b/doc/man3/BIO_f_cipher.pod index 6f5dc15c65..c1f1ff8a75 100644 --- a/doc/man3/BIO_f_cipher.pod +++ b/doc/man3/BIO_f_cipher.pod @@ -6,7 +6,7 @@ BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man3/BIO_f_md.pod b/doc/man3/BIO_f_md.pod index cd45730ac5..8ad694853f 100644 --- a/doc/man3/BIO_f_md.pod +++ b/doc/man3/BIO_f_md.pod @@ -6,7 +6,7 @@ BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod index 82bb16c5ba..6b896e2a2b 100644 --- a/doc/man3/BIO_f_ssl.pod +++ b/doc/man3/BIO_f_ssl.pod @@ -11,7 +11,7 @@ BIO_ssl_shutdown - SSL BIO =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod index 0d1fb5b64b..60f49f7e30 100644 --- a/doc/man3/BIO_get_ex_new_index.pod +++ b/doc/man3/BIO_get_ex_new_index.pod @@ -17,7 +17,7 @@ RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod index a3e9e73f55..4dd3de843f 100644 --- a/doc/man3/DEFINE_STACK_OF.pod +++ b/doc/man3/DEFINE_STACK_OF.pod @@ -14,7 +14,7 @@ sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func, sk_TYPE_new_reserve =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 0f04fe0d91..3e668206b1 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -65,7 +65,7 @@ EVP_CIPHER_do_all_ex =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/EVP_aes.pod b/doc/man3/EVP_aes.pod index 5a2be9add5..1ca893a738 100644 --- a/doc/man3/EVP_aes.pod +++ b/doc/man3/EVP_aes.pod @@ -51,7 +51,7 @@ EVP_aes_256_xts =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/EVP_aria.pod b/doc/man3/EVP_aria.pod index b686edf5c4..6471acb249 100644 --- a/doc/man3/EVP_aria.pod +++ b/doc/man3/EVP_aria.pod @@ -36,7 +36,7 @@ EVP_aria_256_gcm, =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/EVP_camellia.pod b/doc/man3/EVP_camellia.pod index 9ea3d9a351..4a57f79512 100644 --- a/doc/man3/EVP_camellia.pod +++ b/doc/man3/EVP_camellia.pod @@ -30,7 +30,7 @@ EVP_camellia_256_ofb =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/EVP_des.pod b/doc/man3/EVP_des.pod index 1911ff6f8b..d00179eacb 100644 --- a/doc/man3/EVP_des.pod +++ b/doc/man3/EVP_des.pod @@ -28,7 +28,7 @@ EVP_des_ede3_wrap =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod index 804891d012..412a4f8800 100644 --- a/doc/man3/OPENSSL_LH_COMPFUNC.pod +++ b/doc/man3/OPENSSL_LH_COMPFUNC.pod @@ -12,7 +12,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index 991b3d1212..8d4aa90c6d 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -32,7 +32,7 @@ OSSL_PARAM_set_octet_ptr =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod index 2ced3d412f..d49a77936b 100644 --- a/doc/man3/OSSL_trace_enabled.pod +++ b/doc/man3/OSSL_trace_enabled.pod @@ -12,7 +12,7 @@ OSSL_TRACE_ENABLED =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod index f214abdb40..ad06b4c2fd 100644 --- a/doc/man3/OSSL_trace_set_channel.pod +++ b/doc/man3/OSSL_trace_set_channel.pod @@ -1,6 +1,6 @@ =pod -=for comment foreign manuals: atexit(3) +=for openssl foreign manuals: atexit(3) =head1 NAME diff --git a/doc/man3/PEM_read_CMS.pod b/doc/man3/PEM_read_CMS.pod index a18856c81b..5cc3251753 100644 --- a/doc/man3/PEM_read_CMS.pod +++ b/doc/man3/PEM_read_CMS.pod @@ -40,7 +40,7 @@ PEM_write_bio_SSL_SESSION =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/SSL_get_all_async_fds.pod b/doc/man3/SSL_get_all_async_fds.pod index 5adfe90eb5..03cd0e88e2 100644 --- a/doc/man3/SSL_get_all_async_fds.pod +++ b/doc/man3/SSL_get_all_async_fds.pod @@ -9,7 +9,7 @@ SSL_get_changed_async_fds =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man3/SSL_set_async_callback.pod b/doc/man3/SSL_set_async_callback.pod index 46d29234bd..541b743973 100644 --- a/doc/man3/SSL_set_async_callback.pod +++ b/doc/man3/SSL_set_async_callback.pod @@ -12,7 +12,7 @@ SSL_async_callback_fn =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include diff --git a/doc/man3/X509_dup.pod b/doc/man3/X509_dup.pod index e190100d92..d7d8477896 100644 --- a/doc/man3/X509_dup.pod +++ b/doc/man3/X509_dup.pod @@ -287,7 +287,7 @@ X509_dup, =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 12baaa9c37..62e6b245a7 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -387,7 +387,7 @@ i2d_X509_VAL, =head1 SYNOPSIS -=for comment generic +=for openssl generic TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length); TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod index 63380bce57..bb23e56961 100644 --- a/doc/man7/bio.pod +++ b/doc/man7/bio.pod @@ -6,7 +6,7 @@ bio - Basic I/O abstraction =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man7/ossl_store-file.pod b/doc/man7/ossl_store-file.pod index d6ea27bedf..d4d163eabb 100644 --- a/doc/man7/ossl_store-file.pod +++ b/doc/man7/ossl_store-file.pod @@ -14,7 +14,7 @@ ossl_store-file - The store 'file' scheme loader =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod index 148ceef3ea..68503cd092 100644 --- a/doc/man7/ossl_store.pod +++ b/doc/man7/ossl_store.pod @@ -6,7 +6,7 @@ ossl_store - Store retrieval functions =head1 SYNOPSIS -=for comment generic +=for openssl generic #include diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod index 2da3aa2a84..af97735730 100644 --- a/doc/man7/provider-cipher.pod +++ b/doc/man7/provider-cipher.pod @@ -6,7 +6,7 @@ provider-cipher - The cipher library E-E provider functions =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index 089c0e2082..7ee58c2dd6 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -6,7 +6,7 @@ provider-digest - The digest library E-E provider functions =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod index c4cb021185..0f7752cf8f 100644 --- a/doc/man7/provider-keyexch.pod +++ b/doc/man7/provider-keyexch.pod @@ -6,7 +6,7 @@ provider-keyexch - The keyexch library E-E provider functions =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod index 70653e37f3..ef6837426a 100644 --- a/doc/man7/provider-mac.pod +++ b/doc/man7/provider-mac.pod @@ -6,7 +6,7 @@ provider-mac - The mac library E-E provider functions =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod index 73d573a9f2..fa446737bb 100644 --- a/doc/man7/provider-signature.pod +++ b/doc/man7/provider-signature.pod @@ -6,7 +6,7 @@ provider-signature - The signature library E-E provider functions =head1 SYNOPSIS -=for comment multiple includes +=for openssl multiple includes #include #include diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod index 87a908715a..f13418d0d0 100644 --- a/doc/man7/provider.pod +++ b/doc/man7/provider.pod @@ -6,7 +6,7 @@ provider - OpenSSL operation implementation providers =head1 SYNOPSIS -=for comment generic +=for openssl generic #include @@ -123,8 +123,6 @@ The number for this operation is B. The functions the provider can offer are described in L -=begin comment NOT AVAILABLE YET - =item Message Authentication Code (MAC) In the OpenSSL libraries, the corresponding method object is @@ -133,10 +131,6 @@ The number for this operation is B. The functions the provider can offer are described in L -=end comment - -=begin comment NOT AVAILABLE YET - =item Key Derivation Function (KDF) In the OpenSSL libraries, the corresponding method object is @@ -145,8 +139,6 @@ The number for this operation is B. The functions the provider can offer are described in L -=end comment - =item Key Exchange In the OpenSSL libraries, the corresponding method object is diff --git a/util/find-doc-nits b/util/find-doc-nits index eac87dedd0..30cdd77fe6 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -444,7 +444,7 @@ sub check { check_section_location($id, $contents, "EXAMPLES", "SEE ALSO"); } - unless ( $contents =~ /=for comment generic/ ) { + unless ( $contents =~ /=for openssl generic/ ) { if ( $filename =~ m|man3/| ) { name_synopsis($id, $filename, $contents); functionname_check($id, $filename, $contents); @@ -482,7 +482,7 @@ sub check { err($id, "Possible version style issue") if $contents =~ /OpenSSL version [019]/; - if ( $contents !~ /=for comment multiple includes/ ) { + if ( $contents !~ /=for openssl 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 ) { -- 2.25.1