diff options
author | Rich Salz <rsalz@akamai.com> | 2019-09-22 19:49:25 -0400 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-10-01 23:42:33 +0200 |
commit | 1738c0ce44e4e2d29a859555caf62415022a3b0e (patch) | |
tree | d6cbca6746ced4c174ef4ceae8a0855e9887e25b | |
parent | 776cb8358ebaea254d0537cf57cbafe65ac6f5cf (diff) |
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 <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9974)
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<openssl> B<ca> [B<-sm2-id> I<string>] [B<-sm2-hex-id> I<hex-string>] +=for comment ifdef engine sm2-id sm2-hex-id + =head1 DESCRIPTION The B<ca> 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<openssl> B<ciphers> [B<-ciphersuites> I<val>] [B<cipherlist>] +=for comment ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 psk srp + =head1 DESCRIPTION The B<ciphers> 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<openssl> B<cms> [B<-subject> I<subj>] [I<cert.pem ...>] +=for comment ifdef des-wrap engine + =head1 DESCRIPTION The B<cms> 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<openssl> B<crl> [B<-CAfile> I<file>] [B<-CApath> I<dir>] +=for comment ifdef hash_old + =head1 DESCRIPTION The B<crl> 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<openssl dhparam> [B<-engine> I<id>] [I<numbits>] +=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<openssl> B<dsa> [B<-pubout>] [B<-engine> I<id>] +=for comment ifdef pvk-string pvk-weak pvk-none engine + =head1 DESCRIPTION The B<dsa> 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<openssl> B<ec> [B<-check>] [B<-engine> I<id>] +=for comment ifdef engine + =head1 DESCRIPTION The B<ec> 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<openssl ecparam> [B<-genkey>] [B<-engine> I<id>] +=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<openssl> [B<-writerand> I<file>] [B<-engine> I<id>] +=for comment ifdef z engine + B<openssl> I<cipher> [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<openssl> B<gendsa> [B<-verbose>] [B<paramfile>] +=for comment ifdef engine + =head1 DESCRIPTION The B<gendsa> 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<openssl> B<genpkey> [B<-genparam>] [B<-text>] +=for comment ifdef engine + =head1 DESCRIPTION The B<genpkey> 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<openssl> B<genrsa> [B<-verbose>] [B<numbits>] +=for comment ifdef engine + =head1 DESCRIPTION The B<genrsa> 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<openssl info> [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<openssl> B<ocsp> [B<-rcid> I<digest>] [B<->I<digest>] +=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<openssl passwd> [B<-writerand> I<file>] {I<password>} +=for comment ifdef crypt + =head1 DESCRIPTION The B<passwd> 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<openssl> B<pkcs12> [B<-no-CApath>] [B<-CSP> I<name>] +=for comment ifdef engine + =head1 DESCRIPTION The B<pkcs12> 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<openssl> B<pkcs7> [B<-noout>] [B<-engine> I<id>] +=for comment ifdef engine + =head1 DESCRIPTION The B<pkcs7> 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<openssl> B<pkcs8> [B<-scrypt_r> I<r>] [B<-scrypt_p> I<p>] +=for comment ifdef engine scrypt scrypt_N scrypt_r scrypt_p + =head1 DESCRIPTION The B<pkcs8> 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<openssl> B<pkey> [B<-check>] [B<-pubcheck>] +=for comment ifdef engine + =head1 DESCRIPTION The B<pkey> 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<openssl> B<pkeyparam> [B<-engine> I<id>] [B<-check>] +=for comment ifdef engine + =head1 DESCRIPTION The B<pkeyparam> 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<openssl> B<pkeyutl> [B<-engine> I<id>] [B<-engine_impl>] +=for comment ifdef engine engine_impl + =head1 DESCRIPTION The B<pkeyutl> 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<openssl provider> +[B<-help>] [B<-v>] [B<-vv>] [B<-vvv>] @@ -21,6 +22,10 @@ I<provider>'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<openssl rand> [B<-hex>] I<num> +=for comment ifdef engine + =head1 DESCRIPTION The B<rand> command outputs I<num> 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<openssl> B<req> [B<-sm2-id> I<string>] [B<-sm2-hex-id> I<hex-string>] +=for comment ifdef engine keygen_engine sm2-id sm2-hex-id + =head1 DESCRIPTION The B<req> 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<openssl> B<rsa> [B<-RSAPublicKey_out>] [B<-engine> I<id>] +=for comment ifdef pvk-strong pvk-weak pvk-none engine + =head1 DESCRIPTION The B<rsa> 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<openssl> B<rsautl> [B<-hexdump>] [B<-asn1parse>] +=for comment ifdef engine + =head1 DESCRIPTION The B<rsautl> 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<openssl> B<s_client> [B<-enable_pha>] [I<host>:I<port>] +=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<s_client> 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<openssl> B<s_server> [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<s_server> 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<openssl> B<s_time> [B<-cipher> I<cipherlist>] [B<-ciphersuites> I<val>] +=for comment ifdef ssl3 tls1 tls1_1 tls1_2 tls1_3 + =head1 DESCRIPTION The B<s_time> 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<openssl> B<smime> [B<-md> I<digest>] [cert.pem]... +=for comment ifdef engine + =head1 DESCRIPTION The B<smime> 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<openssl speed> [B<-bytes> I<num>] [B<algorithm...>] +=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<openssl> B<spkac> [B<-verify>] [B<-engine> I<id>] +=for comment ifdef engine + =head1 DESCRIPTION The B<spkac> 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<openssl srp> [B<-passout> I<arg>] [I<user...>] +=for comment ifdef engine + =head1 DESCRIPTION The B<srp> 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<verify options:> [B<-verify_name> I<name>] [B<-x509_strict>] +=for comment ifdef engine + =head1 DESCRIPTION The B<ts> 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<openssl> B<verify> [B<->] [certificates] +=for comment ifdef engine sm2-id sm2-hex-id + =head1 DESCRIPTION The B<verify> 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<openssl> B<x509> [B<-engine> I<id>] [B<-preserve_dates>] +=for comment ifdef engine subject_hash_old issuer_hash_old + =head1 DESCRIPTION The B<x509> 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 ( <CFH> ) { 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 -$_"); } } } |