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 <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10048)

diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
index 7917c4c812af5835f2682d0d6ece8102f1410e6d..a78193c2e2218a0ddb60c1363f079396ab7a5c40 100644 (file)
--- 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 5179a8d64a1c025a4085995efae771e145302f9b..062e2c293c39e7d4c23541510c0020502b3f228d 100644 (file)
--- 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 5c4f06e1de7af5bf8f2ba08210e0b8fac8ab91d0..9f7d6c654d4b4b3955875c32087082f81939d41c 100644 (file)
--- 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<openssl> I<cmd> B<-help> | [I<-option> | I<-option> I<arg>] ... [I<arg>] ...
 

diff --git a/doc/man1/openssl-ts.pod b/doc/man1/openssl-ts.pod
index c97909d52684a271b4ef286c244fd8ae36d1b4ab..2e095d4d1343b7765505294cbd012800e004e6b5 100644 (file)
--- 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 19c689ef6c7bf308727b4581ae5be8888295a136..d006198c67a1fde21fb901aaf484502f4d1d7a4c 100644 (file)
--- 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<openssl(1)>,
 L<openssl-ts(1)>,

diff --git a/doc/man3/BIO_f_base64.pod b/doc/man3/BIO_f_base64.pod
index 6ac98e953e0d6331be9f6509f01400bb11d4bdb7..69de0077f72da6d54799967c06fcc083d42ed8ec 100644 (file)
--- 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 <openssl/bio.h>
  #include <openssl/evp.h>

diff --git a/doc/man3/BIO_f_cipher.pod b/doc/man3/BIO_f_cipher.pod
index 6f5dc15c65f72dcf01defd5cd14312ec48191292..c1f1ff8a75430b2e29119370b3599a7b01341b9c 100644 (file)
--- 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 <openssl/bio.h>
  #include <openssl/evp.h>

diff --git a/doc/man3/BIO_f_md.pod b/doc/man3/BIO_f_md.pod
index cd45730ac5568b4ba8ffdec5138cfdbaa7a67786..8ad694853f00e7d10280ce470a8fc91fc4cdf247 100644 (file)
--- 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 <openssl/bio.h>
  #include <openssl/evp.h>

diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod
index 82bb16c5ba7f3a310a072fc87a2c49a4189018ec..6b896e2a2b1b9d8d0cca842a3973e6f529a04e3d 100644 (file)
--- 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 <openssl/bio.h>
  #include <openssl/ssl.h>

diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod
index 0d1fb5b64b61130d4ee75d7192e55565f2277ace..60f49f7e304feb92e6af4b71be41f4ef6cc28fc3 100644 (file)
--- 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 <openssl/x509.h>
 

diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod
index a3e9e73f554834f75db2fb3b49cb362a847622c4..4dd3de843f80dbf481936a48a4ba3d1b8276140d 100644 (file)
--- 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 <openssl/safestack.h>
 

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 0f04fe0d91fbd7c72c7ba34dd4e1363141f73b1d..3e668206b1bbf4cee5bbaad822677495540c17ad 100644 (file)
--- 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 <openssl/evp.h>
 

diff --git a/doc/man3/EVP_aes.pod b/doc/man3/EVP_aes.pod
index 5a2be9add5f2ae62eb4ad3841b8f6489e3ebefe9..1ca893a738a8ac056860bd2202d129d0befc1aaf 100644 (file)
--- 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 <openssl/evp.h>
 

diff --git a/doc/man3/EVP_aria.pod b/doc/man3/EVP_aria.pod
index b686edf5c4575407966739ff26973dff403d1a30..6471acb2495409e6554a5453434d85e778f178eb 100644 (file)
--- 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 <openssl/evp.h>
 

diff --git a/doc/man3/EVP_camellia.pod b/doc/man3/EVP_camellia.pod
index 9ea3d9a351bd03ac9b5f8c8211a77379f1b9b292..4a57f79512c44e0797641fcef110145fc7da37c1 100644 (file)
--- 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 <openssl/evp.h>
 

diff --git a/doc/man3/EVP_des.pod b/doc/man3/EVP_des.pod
index 1911ff6f8b84f0076262219466242d606a25e601..d00179eacb3d5121355ac51b926ec04a9a5686e9 100644 (file)
--- 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 <openssl/evp.h>
 

diff --git a/doc/man3/OPENSSL_LH_COMPFUNC.pod b/doc/man3/OPENSSL_LH_COMPFUNC.pod
index 804891d0128ffd9c8c1c36ae313dd9c530e448cb..412a4f8800f7a8137e15f813a10e91518db37383 100644 (file)
--- 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 <openssl/lhash.h>
 

diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index 991b3d1212fa204db23a41b4066662508c4428ca..8d4aa90c6d0838f6def92f2d5a21054ebb87891d 100644 (file)
--- 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 <openssl/params.h>
 

diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod
index 2ced3d412fbd4c3040b7c8d332dc61fe91529e4b..d49a77936b12777380bce8d7dee1bdebe7641e9e 100644 (file)
--- 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 <openssl/trace.h>
 

diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod
index f214abdb40c3bbcd8ba3d99bd7c4c4656e2f4543..ad06b4c2fd956bf738b19d4fbfae9b16c7d70194 100644 (file)
--- 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 a18856c81b4373be27feb0e067edd14d8facd8da..5cc32517534f8323b80f580b2973fc00a6c7d6f9 100644 (file)
--- 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 <openssl/pem.h>
 

diff --git a/doc/man3/SSL_get_all_async_fds.pod b/doc/man3/SSL_get_all_async_fds.pod
index 5adfe90eb519777f73ae8b420a4bea79f769d0e4..03cd0e88e2608f090bd087b73a64a988465d770a 100644 (file)
--- 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 <openssl/async.h>
  #include <openssl/ssl.h>

diff --git a/doc/man3/SSL_set_async_callback.pod b/doc/man3/SSL_set_async_callback.pod
index 46d29234bd8a4460e25e0adddf29deaeb4f78ca3..541b743973ca3bade572042f9a123e8e3b0e5670 100644 (file)
--- 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 <openssl/ssl.h>
 

diff --git a/doc/man3/X509_dup.pod b/doc/man3/X509_dup.pod
index e190100d92d90c77de7e483f9525445323734fcf..d7d84778969ccae02d64b1a044c2a3539f5939ec 100644 (file)
--- 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 <openssl/asn1t.h>
 

diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 12baaa9c37a07bb8afc70223a69c0b610559fbf6..62e6b245a7435d27f4116dfe02a092aeee2cd57c 100644 (file)
--- 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 63380bce574f52dd50d9eb042608511a159cfc89..bb23e569612f07d71c6e2e7411a37f58f8417b86 100644 (file)
--- 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 <openssl/bio.h>
 

diff --git a/doc/man7/ossl_store-file.pod b/doc/man7/ossl_store-file.pod
index d6ea27bedfa9b551baf2a92f475be817c45690c9..d4d163eabbe971bedb8a968d44e7b8c6e462a335 100644 (file)
--- 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 <openssl/store.h>
 

diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
index 148ceef3eae3924f3ba0afb6e7caca0b09de496e..68503cd0929df1a832a6837ca6cc4410d7843e25 100644 (file)
--- 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 <openssl/store.h>
 

diff --git a/doc/man7/provider-cipher.pod b/doc/man7/provider-cipher.pod
index 2da3aa2a84b29fe82f9a6161b4907be56a711717..af97735730d59d85fd46ab309733e5a0f88ec12f 100644 (file)
--- a/doc/man7/provider-cipher.pod
+++ b/doc/man7/provider-cipher.pod
@@ -6,7 +6,7 @@ provider-cipher - The cipher library E<lt>-E<gt> provider functions
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/core_numbers.h>
  #include <openssl/core_names.h>

diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod
index 089c0e2082b6190c4b4bdd61a734af85dd99a930..7ee58c2dd621cfe595bc695cfb4fc6d0960c095b 100644 (file)
--- a/doc/man7/provider-digest.pod
+++ b/doc/man7/provider-digest.pod
@@ -6,7 +6,7 @@ provider-digest - The digest library E<lt>-E<gt> provider functions
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/core_numbers.h>
  #include <openssl/core_names.h>

diff --git a/doc/man7/provider-keyexch.pod b/doc/man7/provider-keyexch.pod
index c4cb021185803080c9c4f41bc7b35266d755052a..0f7752cf8f7a2d8c6ac3af64721a75520a7a63ce 100644 (file)
--- a/doc/man7/provider-keyexch.pod
+++ b/doc/man7/provider-keyexch.pod
@@ -6,7 +6,7 @@ provider-keyexch - The keyexch library E<lt>-E<gt> provider functions
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/core_numbers.h>
  #include <openssl/core_names.h>

diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 70653e37f3722df59c8be4263597ffb8e0b562c3..ef6837426a26a6e332a7f1c30d000d41befd43c3 100644 (file)
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -6,7 +6,7 @@ provider-mac - The mac library E<lt>-E<gt> provider functions
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/core_numbers.h>
  #include <openssl/core_names.h>

diff --git a/doc/man7/provider-signature.pod b/doc/man7/provider-signature.pod
index 73d573a9f27d008253b7631b1ac12042ef4e249b..fa446737bbee85bdddb5579ac0ba3c781fcf5964 100644 (file)
--- a/doc/man7/provider-signature.pod
+++ b/doc/man7/provider-signature.pod
@@ -6,7 +6,7 @@ provider-signature - The signature library E<lt>-E<gt> provider functions
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/core_numbers.h>
  #include <openssl/core_names.h>

diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
index 87a908715afbec9de0f3a7c338d11a3f06d03c10..f13418d0d0b4f850eee726851bf37e7d32e9444d 100644 (file)
--- 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 <openssl/provider.h>
 
@@ -123,8 +123,6 @@ The number for this operation is B<OSSL_OP_CIPHER>.
 The functions the provider can offer are described in
 L<provider-cipher(7)>
 
-=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<OSSL_OP_MAC>.
 The functions the provider can offer are described in
 L<provider-mac(7)>
 
-=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<OSSL_OP_KDF>.
 The functions the provider can offer are described in
 L<provider-kdf(7)>
 
-=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 eac87dedd0cb561c564e7a56dbf7a5adaf508d09..30cdd77fe60c7cf41b3d15ba9b475c2535a74054 100755 (executable)
--- 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 ) {