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)
diff --git a/doc/man1/openssl-ca.pod b/doc/man1/openssl-ca.pod
index 3159ee2..c53ba4f 100644
--- a/doc/man1/openssl-ca.pod
+++ b/doc/man1/openssl-ca.pod
@@ -59,6 +59,8 @@
[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 332b507..0ed7d14 100644
--- a/doc/man1/openssl-ciphers.pod
+++ b/doc/man1/openssl-ciphers.pod
@@ -24,6 +24,8 @@
[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 ddb0edf..36b075c 100644
--- a/doc/man1/openssl-cms.pod
+++ b/doc/man1/openssl-cms.pod
@@ -103,6 +103,8 @@
[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 abf2a2e..11ec7b0 100644
--- a/doc/man1/openssl-crl.pod
+++ b/doc/man1/openssl-crl.pod
@@ -22,6 +22,8 @@
[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 b575473..26b080f 100644
--- a/doc/man1/openssl-dhparam.pod
+++ b/doc/man1/openssl-dhparam.pod
@@ -25,6 +25,8 @@
[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 9d33809..9c34dde 100644
--- a/doc/man1/openssl-dsa.pod
+++ b/doc/man1/openssl-dsa.pod
@@ -33,6 +33,8 @@
[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 56ff0dc..b43af6d 100644
--- a/doc/man1/openssl-ec.pod
+++ b/doc/man1/openssl-ec.pod
@@ -28,6 +28,8 @@
[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 1f17f02..bd946f1 100644
--- a/doc/man1/openssl-ecparam.pod
+++ b/doc/man1/openssl-ecparam.pod
@@ -27,6 +27,8 @@
[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 6ece5a5..d0f8769 100644
--- a/doc/man1/openssl-enc.pod
+++ b/doc/man1/openssl-enc.pod
@@ -39,6 +39,8 @@
[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 0cc354a..a5d001a 100644
--- a/doc/man1/openssl-gendsa.pod
+++ b/doc/man1/openssl-gendsa.pod
@@ -27,6 +27,8 @@
[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 dab170c..6139077 100644
--- a/doc/man1/openssl-genpkey.pod
+++ b/doc/man1/openssl-genpkey.pod
@@ -19,6 +19,8 @@
[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 b963dd7..81ede1b 100644
--- a/doc/man1/openssl-genrsa.pod
+++ b/doc/man1/openssl-genrsa.pod
@@ -31,6 +31,8 @@
[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 80c2e1f..e26218c 100644
--- a/doc/man1/openssl-info.pod
+++ b/doc/man1/openssl-info.pod
@@ -12,7 +12,7 @@
[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 f2a0e49..dc66134 100644
--- a/doc/man1/openssl-ocsp.pod
+++ b/doc/man1/openssl-ocsp.pod
@@ -90,6 +90,8 @@
[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 da4c73c..755e80a 100644
--- a/doc/man1/openssl-passwd.pod
+++ b/doc/man1/openssl-passwd.pod
@@ -24,6 +24,8 @@
[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 44052d1..f309bcd 100644
--- a/doc/man1/openssl-pkcs12.pod
+++ b/doc/man1/openssl-pkcs12.pod
@@ -44,6 +44,8 @@
[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 f02a1cc..680cec7 100644
--- a/doc/man1/openssl-pkcs7.pod
+++ b/doc/man1/openssl-pkcs7.pod
@@ -17,6 +17,8 @@
[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 1004a2d..99299f1 100644
--- a/doc/man1/openssl-pkcs8.pod
+++ b/doc/man1/openssl-pkcs8.pod
@@ -30,6 +30,8 @@
[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 161eef4..fa9ea11 100644
--- a/doc/man1/openssl-pkey.pod
+++ b/doc/man1/openssl-pkey.pod
@@ -25,6 +25,8 @@
[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 c1d2911..34ae7c9 100644
--- a/doc/man1/openssl-pkeyparam.pod
+++ b/doc/man1/openssl-pkeyparam.pod
@@ -15,6 +15,8 @@
[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 a99f3dc..a0f4555 100644
--- a/doc/man1/openssl-pkeyutl.pod
+++ b/doc/man1/openssl-pkeyutl.pod
@@ -38,6 +38,8 @@
[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 6c71d1c..a16c418 100644
--- a/doc/man1/openssl-provider.pod
+++ b/doc/man1/openssl-provider.pod
@@ -7,6 +7,7 @@
=head1 SYNOPSIS
B<openssl provider>
+[B<-help>]
[B<-v>]
[B<-vv>]
[B<-vvv>]
@@ -21,6 +22,10 @@
=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 2595bc6..4d57265 100644
--- a/doc/man1/openssl-rand.pod
+++ b/doc/man1/openssl-rand.pod
@@ -15,6 +15,8 @@
[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 5a4cf27..70d1213 100644
--- a/doc/man1/openssl-req.pod
+++ b/doc/man1/openssl-req.pod
@@ -52,6 +52,8 @@
[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 cc129e4..6b8fa44 100644
--- a/doc/man1/openssl-rsa.pod
+++ b/doc/man1/openssl-rsa.pod
@@ -36,6 +36,8 @@
[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 2d4fadc..2122066 100644
--- a/doc/man1/openssl-rsautl.pod
+++ b/doc/man1/openssl-rsautl.pod
@@ -26,6 +26,8 @@
[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 4e8fdfb..3baacd3 100644
--- a/doc/man1/openssl-s_client.pod
+++ b/doc/man1/openssl-s_client.pod
@@ -139,6 +139,16 @@
[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 0c7c3db..df61331 100644
--- a/doc/man1/openssl-s_server.pod
+++ b/doc/man1/openssl-s_server.pod
@@ -185,6 +185,16 @@
[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 c6b05c9..fa3dd68 100644
--- a/doc/man1/openssl-s_time.pod
+++ b/doc/man1/openssl-s_time.pod
@@ -30,6 +30,8 @@
[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 52aa0b3..b15baa2 100644
--- a/doc/man1/openssl-smime.pod
+++ b/doc/man1/openssl-smime.pod
@@ -70,6 +70,8 @@
[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 2b6eb06..c7577f5 100644
--- a/doc/man1/openssl-speed.pod
+++ b/doc/man1/openssl-speed.pod
@@ -21,6 +21,8 @@
[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 9c9ab67..03df087 100644
--- a/doc/man1/openssl-spkac.pod
+++ b/doc/man1/openssl-spkac.pod
@@ -21,6 +21,8 @@
[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 cb98f85..62a27c3 100644
--- a/doc/man1/openssl-srp.pod
+++ b/doc/man1/openssl-srp.pod
@@ -22,6 +22,8 @@
[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 6247cc7..ec1d296 100644
--- a/doc/man1/openssl-ts.pod
+++ b/doc/man1/openssl-ts.pod
@@ -82,6 +82,8 @@
[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 cdc1da8..0635576 100644
--- a/doc/man1/openssl-verify.pod
+++ b/doc/man1/openssl-verify.pod
@@ -54,6 +54,8 @@
[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 be369ea..cb34715 100644
--- a/doc/man1/openssl-x509.pod
+++ b/doc/man1/openssl-x509.pod
@@ -68,6 +68,8 @@
[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 6641a23..67a2ee3 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -538,6 +538,7 @@
}
}
+# Cipher/digests to skip if not documented
my %skips = (
'aes128' => 1,
'aes192' => 1,
@@ -551,8 +552,8 @@
'des' => 1,
'des3' => 1,
'idea' => 1,
- '[cipher]' => 1,
- '[digest]' => 1,
+ 'cipher' => 1,
+ 'digest' => 1,
);
sub checkflags {
@@ -560,6 +561,7 @@
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 @@
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 @@
}
if ( scalar @undocced > 0 ) {
foreach ( @undocced ) {
- err("doc/man1/$cmd.pod: Missing -$_");
+ err("$doc: undocumented option -$_");
}
}
@@ -600,8 +610,8 @@
}
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 -$_");
}
}
}
