From 1738c0ce44e4e2d29a859555caf62415022a3b0e Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sun, 22 Sep 2019 19:49:25 -0400 Subject: [PATCH] Add '=for comment ifdef' to pod pages Make find-doc-nits understand that =for comment ifdef ssl3 ... in a POD page means that the "-ssl3" flag might be ifdef'd out in the local environment, and not to complain about it. Reviewed-by: Tomas Mraz Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/9974) --- doc/man1/openssl-ca.pod | 2 ++ doc/man1/openssl-ciphers.pod | 2 ++ doc/man1/openssl-cms.pod | 2 ++ doc/man1/openssl-crl.pod | 2 ++ doc/man1/openssl-dhparam.pod | 2 ++ doc/man1/openssl-dsa.pod | 2 ++ doc/man1/openssl-ec.pod | 2 ++ doc/man1/openssl-ecparam.pod | 2 ++ doc/man1/openssl-enc.pod | 2 ++ doc/man1/openssl-gendsa.pod | 2 ++ doc/man1/openssl-genpkey.pod | 2 ++ doc/man1/openssl-genrsa.pod | 2 ++ doc/man1/openssl-info.pod | 2 +- doc/man1/openssl-ocsp.pod | 2 ++ doc/man1/openssl-passwd.pod | 2 ++ doc/man1/openssl-pkcs12.pod | 2 ++ doc/man1/openssl-pkcs7.pod | 2 ++ doc/man1/openssl-pkcs8.pod | 2 ++ doc/man1/openssl-pkey.pod | 2 ++ doc/man1/openssl-pkeyparam.pod | 2 ++ doc/man1/openssl-pkeyutl.pod | 2 ++ doc/man1/openssl-provider.pod | 5 +++++ doc/man1/openssl-rand.pod | 2 ++ doc/man1/openssl-req.pod | 2 ++ doc/man1/openssl-rsa.pod | 2 ++ doc/man1/openssl-rsautl.pod | 2 ++ doc/man1/openssl-s_client.pod | 10 ++++++++++ doc/man1/openssl-s_server.pod | 10 ++++++++++ doc/man1/openssl-s_time.pod | 2 ++ doc/man1/openssl-smime.pod | 2 ++ doc/man1/openssl-speed.pod | 2 ++ doc/man1/openssl-spkac.pod | 2 ++ doc/man1/openssl-srp.pod | 2 ++ doc/man1/openssl-ts.pod | 2 ++ doc/man1/openssl-verify.pod | 2 ++ doc/man1/openssl-x509.pod | 2 ++ util/find-doc-nits | 20 +++++++++++++++----- 37 files changed, 105 insertions(+), 6 deletions(-) diff --git a/doc/man1/openssl-ca.pod b/doc/man1/openssl-ca.pod index 3159ee21f2..c53ba4fa33 100644 --- a/doc/man1/openssl-ca.pod +++ b/doc/man1/openssl-ca.pod @@ -59,6 +59,8 @@ B B [B<-sm2-id> I] [B<-sm2-hex-id> I] +=for comment ifdef engine sm2-id sm2-hex-id + =head1 DESCRIPTION The B command is a minimal CA application. It can be used diff --git a/doc/man1/openssl-ciphers.pod b/doc/man1/openssl-ciphers.pod index 332b507a9d..0ed7d14eaf 100644 --- a/doc/man1/openssl-ciphers.pod +++ b/doc/man1/openssl-ciphers.pod @@ -24,6 +24,8 @@ B B [B<-ciphersuites> I] [B] +=for comment ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 psk srp + =head1 DESCRIPTION The B command converts textual OpenSSL cipher lists into ordered diff --git a/doc/man1/openssl-cms.pod b/doc/man1/openssl-cms.pod index ddb0edf5a0..36b075c655 100644 --- a/doc/man1/openssl-cms.pod +++ b/doc/man1/openssl-cms.pod @@ -103,6 +103,8 @@ B B [B<-subject> I] [I] +=for comment ifdef des-wrap engine + =head1 DESCRIPTION The B command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and diff --git a/doc/man1/openssl-crl.pod b/doc/man1/openssl-crl.pod index abf2a2e87a..11ec7b07b0 100644 --- a/doc/man1/openssl-crl.pod +++ b/doc/man1/openssl-crl.pod @@ -22,6 +22,8 @@ B B [B<-CAfile> I] [B<-CApath> I] +=for comment ifdef hash_old + =head1 DESCRIPTION The B command processes CRL files in DER or PEM format. diff --git a/doc/man1/openssl-dhparam.pod b/doc/man1/openssl-dhparam.pod index b575473d96..26b080f4f6 100644 --- a/doc/man1/openssl-dhparam.pod +++ b/doc/man1/openssl-dhparam.pod @@ -25,6 +25,8 @@ B [B<-engine> I] [I] +=for comment ifdef dsaparam engine + =head1 DESCRIPTION This command is used to manipulate DH parameter files. diff --git a/doc/man1/openssl-dsa.pod b/doc/man1/openssl-dsa.pod index 9d33809cb3..9c34dde658 100644 --- a/doc/man1/openssl-dsa.pod +++ b/doc/man1/openssl-dsa.pod @@ -33,6 +33,8 @@ B B [B<-pubout>] [B<-engine> I] +=for comment ifdef pvk-string pvk-weak pvk-none engine + =head1 DESCRIPTION The B command processes DSA keys. They can be converted between various diff --git a/doc/man1/openssl-ec.pod b/doc/man1/openssl-ec.pod index 56ff0dce6a..b43af6df52 100644 --- a/doc/man1/openssl-ec.pod +++ b/doc/man1/openssl-ec.pod @@ -28,6 +28,8 @@ B B [B<-check>] [B<-engine> I] +=for comment ifdef engine + =head1 DESCRIPTION The B command processes EC keys. They can be converted between various diff --git a/doc/man1/openssl-ecparam.pod b/doc/man1/openssl-ecparam.pod index 1f17f02561..bd946f10c5 100644 --- a/doc/man1/openssl-ecparam.pod +++ b/doc/man1/openssl-ecparam.pod @@ -27,6 +27,8 @@ B [B<-genkey>] [B<-engine> I] +=for comment ifdef engine + =head1 DESCRIPTION This command is used to manipulate or generate EC parameter files. diff --git a/doc/man1/openssl-enc.pod b/doc/man1/openssl-enc.pod index 6ece5a542a..d0f876949a 100644 --- a/doc/man1/openssl-enc.pod +++ b/doc/man1/openssl-enc.pod @@ -39,6 +39,8 @@ B [B<-writerand> I] [B<-engine> I] +=for comment ifdef z engine + B I [B<...>] =head1 DESCRIPTION diff --git a/doc/man1/openssl-gendsa.pod b/doc/man1/openssl-gendsa.pod index 0cc354a066..a5d001acc6 100644 --- a/doc/man1/openssl-gendsa.pod +++ b/doc/man1/openssl-gendsa.pod @@ -27,6 +27,8 @@ B B [B<-verbose>] [B] +=for comment ifdef engine + =head1 DESCRIPTION The B command generates a DSA private key from a DSA parameter file diff --git a/doc/man1/openssl-genpkey.pod b/doc/man1/openssl-genpkey.pod index dab170cb83..61390777f4 100644 --- a/doc/man1/openssl-genpkey.pod +++ b/doc/man1/openssl-genpkey.pod @@ -19,6 +19,8 @@ B B [B<-genparam>] [B<-text>] +=for comment ifdef engine + =head1 DESCRIPTION The B command generates a private key. diff --git a/doc/man1/openssl-genrsa.pod b/doc/man1/openssl-genrsa.pod index b963dd742d..81ede1b8c6 100644 --- a/doc/man1/openssl-genrsa.pod +++ b/doc/man1/openssl-genrsa.pod @@ -31,6 +31,8 @@ B B [B<-verbose>] [B] +=for comment ifdef engine + =head1 DESCRIPTION The B command generates an RSA private key. diff --git a/doc/man1/openssl-info.pod b/doc/man1/openssl-info.pod index 80c2e1fa62..e26218c417 100644 --- a/doc/man1/openssl-info.pod +++ b/doc/man1/openssl-info.pod @@ -12,7 +12,7 @@ B [B<-enginesdir>] [B<-modulesdir> ] [B<-dsoext>] -[B<-dirfilesep>] +[B<-dirnamesep>] [B<-listsep>] [B<-seeds>] [B<-cpusettings>] diff --git a/doc/man1/openssl-ocsp.pod b/doc/man1/openssl-ocsp.pod index f2a0e49c08..dc66134e36 100644 --- a/doc/man1/openssl-ocsp.pod +++ b/doc/man1/openssl-ocsp.pod @@ -90,6 +90,8 @@ B B [B<-rcid> I] [B<->I] +=for comment ifdef multi + =head1 DESCRIPTION The Online Certificate Status Protocol (OCSP) enables applications to diff --git a/doc/man1/openssl-passwd.pod b/doc/man1/openssl-passwd.pod index da4c73cf1c..755e80a22e 100644 --- a/doc/man1/openssl-passwd.pod +++ b/doc/man1/openssl-passwd.pod @@ -24,6 +24,8 @@ B [B<-writerand> I] {I} +=for comment ifdef crypt + =head1 DESCRIPTION The B command computes the hash of a password typed at diff --git a/doc/man1/openssl-pkcs12.pod b/doc/man1/openssl-pkcs12.pod index 44052d130d..f309bcd1b8 100644 --- a/doc/man1/openssl-pkcs12.pod +++ b/doc/man1/openssl-pkcs12.pod @@ -44,6 +44,8 @@ B B [B<-no-CApath>] [B<-CSP> I] +=for comment ifdef engine + =head1 DESCRIPTION The B command allows PKCS#12 files (sometimes referred to as diff --git a/doc/man1/openssl-pkcs7.pod b/doc/man1/openssl-pkcs7.pod index f02a1cc298..680cec70a3 100644 --- a/doc/man1/openssl-pkcs7.pod +++ b/doc/man1/openssl-pkcs7.pod @@ -17,6 +17,8 @@ B B [B<-noout>] [B<-engine> I] +=for comment ifdef engine + =head1 DESCRIPTION The B command processes PKCS#7 files in DER or PEM format. diff --git a/doc/man1/openssl-pkcs8.pod b/doc/man1/openssl-pkcs8.pod index 1004a2d766..99299f1044 100644 --- a/doc/man1/openssl-pkcs8.pod +++ b/doc/man1/openssl-pkcs8.pod @@ -30,6 +30,8 @@ B B [B<-scrypt_r> I] [B<-scrypt_p> I

] +=for comment ifdef engine scrypt scrypt_N scrypt_r scrypt_p + =head1 DESCRIPTION The B command processes private keys in PKCS#8 format. It can handle diff --git a/doc/man1/openssl-pkey.pod b/doc/man1/openssl-pkey.pod index 161eef40ee..fa9ea11f9c 100644 --- a/doc/man1/openssl-pkey.pod +++ b/doc/man1/openssl-pkey.pod @@ -25,6 +25,8 @@ B B [B<-check>] [B<-pubcheck>] +=for comment ifdef engine + =head1 DESCRIPTION The B command processes public or private keys. They can be converted diff --git a/doc/man1/openssl-pkeyparam.pod b/doc/man1/openssl-pkeyparam.pod index c1d2911d2b..34ae7c97c2 100644 --- a/doc/man1/openssl-pkeyparam.pod +++ b/doc/man1/openssl-pkeyparam.pod @@ -15,6 +15,8 @@ B B [B<-engine> I] [B<-check>] +=for comment ifdef engine + =head1 DESCRIPTION The B command processes public key algorithm parameters. diff --git a/doc/man1/openssl-pkeyutl.pod b/doc/man1/openssl-pkeyutl.pod index a99f3dcc07..a0f4555764 100644 --- a/doc/man1/openssl-pkeyutl.pod +++ b/doc/man1/openssl-pkeyutl.pod @@ -38,6 +38,8 @@ B B [B<-engine> I] [B<-engine_impl>] +=for comment ifdef engine engine_impl + =head1 DESCRIPTION The B command can be used to perform low level public key operations diff --git a/doc/man1/openssl-provider.pod b/doc/man1/openssl-provider.pod index 6c71d1cd64..a16c41845d 100644 --- a/doc/man1/openssl-provider.pod +++ b/doc/man1/openssl-provider.pod @@ -7,6 +7,7 @@ openssl-provider - load and query providers =head1 SYNOPSIS B +[B<-help>] [B<-v>] [B<-vv>] [B<-vvv>] @@ -21,6 +22,10 @@ I's. =over 4 +=item B<-help> + +Print out a usage message. + =item B<-v> B<-vv> B<-vvv> Provides information about each specified provider. diff --git a/doc/man1/openssl-rand.pod b/doc/man1/openssl-rand.pod index 2595bc65d2..4d57265b13 100644 --- a/doc/man1/openssl-rand.pod +++ b/doc/man1/openssl-rand.pod @@ -15,6 +15,8 @@ B [B<-hex>] I +=for comment ifdef engine + =head1 DESCRIPTION The B command outputs I pseudo-random bytes after seeding diff --git a/doc/man1/openssl-req.pod b/doc/man1/openssl-req.pod index 5a4cf2703e..70d121360a 100644 --- a/doc/man1/openssl-req.pod +++ b/doc/man1/openssl-req.pod @@ -52,6 +52,8 @@ B B [B<-sm2-id> I] [B<-sm2-hex-id> I] +=for comment ifdef engine keygen_engine sm2-id sm2-hex-id + =head1 DESCRIPTION The B command primarily creates and processes certificate requests diff --git a/doc/man1/openssl-rsa.pod b/doc/man1/openssl-rsa.pod index cc129e46c9..6b8fa44c60 100644 --- a/doc/man1/openssl-rsa.pod +++ b/doc/man1/openssl-rsa.pod @@ -36,6 +36,8 @@ B B [B<-RSAPublicKey_out>] [B<-engine> I] +=for comment ifdef pvk-strong pvk-weak pvk-none engine + =head1 DESCRIPTION The B command processes RSA keys. They can be converted between various diff --git a/doc/man1/openssl-rsautl.pod b/doc/man1/openssl-rsautl.pod index 2d4fadc5b2..2122066270 100644 --- a/doc/man1/openssl-rsautl.pod +++ b/doc/man1/openssl-rsautl.pod @@ -26,6 +26,8 @@ B B [B<-hexdump>] [B<-asn1parse>] +=for comment ifdef engine + =head1 DESCRIPTION The B command can be used to sign, verify, encrypt and decrypt diff --git a/doc/man1/openssl-s_client.pod b/doc/man1/openssl-s_client.pod index 4e8fdfb0d5..3baacd3f73 100644 --- a/doc/man1/openssl-s_client.pod +++ b/doc/man1/openssl-s_client.pod @@ -139,6 +139,16 @@ B B [B<-enable_pha>] [I:I] +=for comment ifdef engine ssl_client_engine ct noct ctlogfile + +=for comment ifdef ssl3 unix 4 6 use_srtp status trace wdebug nextprotoneg + +=for comment ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 dtls mtu dtls1 dtls1_2 + +=for comment ifdef sctp_label_bug sctp + +=for comment ifdef srpuser srppass srp_lateuser srp_moregroups srp_strength + =head1 DESCRIPTION The B command implements a generic SSL/TLS client which connects diff --git a/doc/man1/openssl-s_server.pod b/doc/man1/openssl-s_server.pod index 0c7c3db8e1..df613311ed 100644 --- a/doc/man1/openssl-s_server.pod +++ b/doc/man1/openssl-s_server.pod @@ -185,6 +185,16 @@ B B [B<-no_anti_replay>] [B<-http_server_binmode>] +=for comment ifdef unix 4 6 unlink no_dhe nextprotoneg use_srtp engine + +=for comment ifdef status status_verbose status_timeout status_url status_file + +=for comment ifdef psk_hint srpvfile srpuserseed sctp sctp_label_bug + +=for comment ifdef sctp sctp_label_bug trace mtu timeout listen + +=for comment ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 dtls mtu dtls1 dtls1_2 + =head1 DESCRIPTION The B command implements a generic SSL/TLS server which listens diff --git a/doc/man1/openssl-s_time.pod b/doc/man1/openssl-s_time.pod index c6b05c9f4a..fa3dd685b7 100644 --- a/doc/man1/openssl-s_time.pod +++ b/doc/man1/openssl-s_time.pod @@ -30,6 +30,8 @@ B B [B<-cipher> I] [B<-ciphersuites> I] +=for comment ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 + =head1 DESCRIPTION The B command implements a generic SSL/TLS client which connects to a diff --git a/doc/man1/openssl-smime.pod b/doc/man1/openssl-smime.pod index 52aa0b3783..b15baa2dc7 100644 --- a/doc/man1/openssl-smime.pod +++ b/doc/man1/openssl-smime.pod @@ -70,6 +70,8 @@ B B [B<-md> I] [cert.pem]... +=for comment ifdef engine + =head1 DESCRIPTION The B command handles S/MIME mail. It can encrypt, decrypt, sign and diff --git a/doc/man1/openssl-speed.pod b/doc/man1/openssl-speed.pod index 2b6eb06bf4..c7577f5557 100644 --- a/doc/man1/openssl-speed.pod +++ b/doc/man1/openssl-speed.pod @@ -21,6 +21,8 @@ B [B<-bytes> I] [B] +=for comment ifdef cmac multi async_jobs engine + =head1 DESCRIPTION This command is used to test the performance of cryptographic algorithms. diff --git a/doc/man1/openssl-spkac.pod b/doc/man1/openssl-spkac.pod index 9c9ab67157..03df087ee0 100644 --- a/doc/man1/openssl-spkac.pod +++ b/doc/man1/openssl-spkac.pod @@ -21,6 +21,8 @@ B B [B<-verify>] [B<-engine> I] +=for comment ifdef engine + =head1 DESCRIPTION The B command processes Netscape signed public key and challenge diff --git a/doc/man1/openssl-srp.pod b/doc/man1/openssl-srp.pod index cb98f85678..62a27c37ef 100644 --- a/doc/man1/openssl-srp.pod +++ b/doc/man1/openssl-srp.pod @@ -22,6 +22,8 @@ B [B<-passout> I] [I] +=for comment ifdef engine + =head1 DESCRIPTION The B command is used to maintain an SRP (secure remote password) diff --git a/doc/man1/openssl-ts.pod b/doc/man1/openssl-ts.pod index 6247cc786d..ec1d296c94 100644 --- a/doc/man1/openssl-ts.pod +++ b/doc/man1/openssl-ts.pod @@ -82,6 +82,8 @@ I [B<-verify_name> I] [B<-x509_strict>] +=for comment ifdef engine + =head1 DESCRIPTION The B command is a basic Time Stamping Authority (TSA) client and server diff --git a/doc/man1/openssl-verify.pod b/doc/man1/openssl-verify.pod index cdc1da8ecd..0635576c87 100644 --- a/doc/man1/openssl-verify.pod +++ b/doc/man1/openssl-verify.pod @@ -54,6 +54,8 @@ B B [B<->] [certificates] +=for comment ifdef engine sm2-id sm2-hex-id + =head1 DESCRIPTION The B command verifies certificate chains. diff --git a/doc/man1/openssl-x509.pod b/doc/man1/openssl-x509.pod index be369eae16..cb347151da 100644 --- a/doc/man1/openssl-x509.pod +++ b/doc/man1/openssl-x509.pod @@ -68,6 +68,8 @@ B B [B<-engine> I] [B<-preserve_dates>] +=for comment ifdef engine subject_hash_old issuer_hash_old + =head1 DESCRIPTION The B command is a multi purpose certificate utility. It can be diff --git a/util/find-doc-nits b/util/find-doc-nits index 6641a238d8..67a2ee365c 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -538,6 +538,7 @@ sub publicize { } } +# Cipher/digests to skip if not documented my %skips = ( 'aes128' => 1, 'aes192' => 1, @@ -551,8 +552,8 @@ my %skips = ( 'des' => 1, 'des3' => 1, 'idea' => 1, - '[cipher]' => 1, - '[digest]' => 1, + 'cipher' => 1, + 'digest' => 1, ); sub checkflags { @@ -560,6 +561,7 @@ sub checkflags { my $doc = shift; my %cmdopts; my %docopts; + my %localskips; # Get the list of options in the command. open CFH, "./apps/openssl list --options $cmd|" @@ -577,7 +579,15 @@ sub checkflags { while ( ) { chop; last if /DESCRIPTION/; + if ( /=for comment ifdef (.*)/ ) { + foreach my $f ( split / /, $1 ) { + $localskips{$f} = 1; + } + next; + } next unless /\[B<-([^ >]+)/; + my $opt = $1; + $opt = $1 if $opt =~ /I<(.*)/; $docopts{$1} = 1; } close CFH; @@ -589,7 +599,7 @@ sub checkflags { } if ( scalar @undocced > 0 ) { foreach ( @undocced ) { - err("doc/man1/$cmd.pod: Missing -$_"); + err("$doc: undocumented option -$_"); } } @@ -600,8 +610,8 @@ sub checkflags { } if ( scalar @unimpl > 0 ) { foreach ( @unimpl ) { - next if defined $skips{$_}; - err("doc/man1/$cmd.pod: Not implemented -$_"); + next if defined $skips{$_} || defined $localskips{$_}; + err("$cmd documented but not implemented -$_"); } } } -- 2.25.1