]> git.ipfire.org Git - thirdparty/openssl.git/commitdiff
Add '=for comment ifdef' to pod pages
authorRich Salz <rsalz@akamai.com>
Sun, 22 Sep 2019 23:49:25 +0000 (19:49 -0400)
committerRichard Levitte <levitte@openssl.org>
Tue, 1 Oct 2019 21:42:33 +0000 (23:42 +0200)
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:
doc/man1/openssl-ca.pod
doc/man1/openssl-ciphers.pod
doc/man1/openssl-cms.pod
doc/man1/openssl-crl.pod
doc/man1/openssl-dhparam.pod
doc/man1/openssl-dsa.pod
doc/man1/openssl-ec.pod
doc/man1/openssl-ecparam.pod
doc/man1/openssl-enc.pod
doc/man1/openssl-gendsa.pod
doc/man1/openssl-genpkey.pod
doc/man1/openssl-genrsa.pod
doc/man1/openssl-info.pod
doc/man1/openssl-ocsp.pod
doc/man1/openssl-passwd.pod
doc/man1/openssl-pkcs12.pod
doc/man1/openssl-pkcs7.pod
doc/man1/openssl-pkcs8.pod
doc/man1/openssl-pkey.pod
doc/man1/openssl-pkeyparam.pod
doc/man1/openssl-pkeyutl.pod
doc/man1/openssl-provider.pod
doc/man1/openssl-rand.pod
doc/man1/openssl-req.pod
doc/man1/openssl-rsa.pod
doc/man1/openssl-rsautl.pod
doc/man1/openssl-s_client.pod
doc/man1/openssl-s_server.pod
doc/man1/openssl-s_time.pod
doc/man1/openssl-smime.pod
doc/man1/openssl-speed.pod
doc/man1/openssl-spkac.pod
doc/man1/openssl-srp.pod
doc/man1/openssl-ts.pod
doc/man1/openssl-verify.pod
doc/man1/openssl-x509.pod
util/find-doc-nits

index 3159ee21f2cbe79011a92fd977501a50989b68ee..c53ba4fa330b0569958d3cdb96ca160153652477 100644 (file)
@@ -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
index 332b507a9d1c04a98a18b192b9a13eda4654ea0a..0ed7d14eafa6967be945de21df0797a75078b02d 100644 (file)
@@ -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
index ddb0edf5a0189b0da25ac7c130ba9769923243c6..36b075c6556c751b0a60fdac75263ec25f5a6ed4 100644 (file)
@@ -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
index abf2a2e87a991ba0943593975bec78613a62f3fa..11ec7b07b0045d8a58b9b16d56a3adfe3047e527 100644 (file)
@@ -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.
index b575473d968eaea586816aae872db9da2654cf6c..26b080f4f6cb52dad648e6ad2fdf47a0fec8cb25 100644 (file)
@@ -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.
index 9d33809cb32a56e300c25a8d92776804d316a3db..9c34dde6588d790ff2617b2a1233d283b0f7c57b 100644 (file)
@@ -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
index 56ff0dce6aedccbd309832e9a011240cf482b814..b43af6df52fec208316832ce3af5bfe8d33a5df7 100644 (file)
@@ -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
index 1f17f02561fc9ad2cbc9c10685a4ee905cc94925..bd946f10c5eeddc29c149287e7d6cb2072a17f26 100644 (file)
@@ -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.
index 6ece5a542a2e5cd534ced7a99e94100a3df738fa..d0f876949a573c66e01e08f651425a3589f38a75 100644 (file)
@@ -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
index 0cc354a066c372ea3ac64901938c2445d8af89db..a5d001acc62c7e3ec8e194124da9628c8e7b94a6 100644 (file)
@@ -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
index dab170cb834c54007080e9b7d7a047b343dfd47d..61390777f48fde63506e4310a00d5c1f719aa8b8 100644 (file)
@@ -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.
index b963dd742de69551f632e72a2f9e98ab371fa41b..81ede1b8c68e6bf6ec48962bf3b5792032b52f04 100644 (file)
@@ -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.
index 80c2e1fa62f36f8985bac1808fdbcb7a14df0216..e26218c417ce1fde534f3fe553c06109347d4e33 100644 (file)
@@ -12,7 +12,7 @@ B<openssl info>
 [B<-enginesdir>]
 [B<-modulesdir> ]
 [B<-dsoext>]
-[B<-dirfilesep>]
+[B<-dirnamesep>]
 [B<-listsep>]
 [B<-seeds>]
 [B<-cpusettings>]
index f2a0e49c082e39bff0844eea05cd4fc6f2a80a89..dc66134e3628f2e405f208d5af073b67f30f9732 100644 (file)
@@ -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
index da4c73cf1c53a7e24518ba38732ecef9cf0b5994..755e80a22e0d52e7b22f4901ac9b77dcbf65263f 100644 (file)
@@ -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
index 44052d130dac73c52f4998beff40c4cedac0f34c..f309bcd1b82520a3094347d772e22ec1e436cb83 100644 (file)
@@ -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
index f02a1cc298412574a72099b457c2354ddd168a13..680cec70a3746b6051014f7f208a05763a2a0482 100644 (file)
@@ -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.
index 1004a2d7665afffe5128eb0012920165d7487e5e..99299f10447a8d5fced3023570d6defcc8dabc14 100644 (file)
@@ -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
index 161eef40ee5077f0e30077bbe5735d2f8bf193b2..fa9ea11f9ca7f1ea1872af4075f8a6193386892c 100644 (file)
@@ -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
index c1d2911d2bf3f805c21d75f02ceaa8a930cf40dd..34ae7c97c25291b353cff72dab7a9ae23c1bf55c 100644 (file)
@@ -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.
index a99f3dcc07756c58951643d6cba365c73391322f..a0f4555764ea9f7bc5824763439cd1a9aad50c83 100644 (file)
@@ -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
index 6c71d1cd64712339cc235f7236c43bcbf08d9d91..a16c41845deed380ba921b28c4f13ead006fab88 100644 (file)
@@ -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.
index 2595bc65d27b19db7a690e52de9ee000f2167502..4d57265b13826333e106ff6e4a6e616e1dd7826b 100644 (file)
@@ -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
index 5a4cf2703e7f12b94c598cf6828e373f84d9564b..70d121360ad2381def0cedc60cd4652f5714ccf7 100644 (file)
@@ -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
index cc129e46c91a2cc22cb45f29e45c914cf797b0b4..6b8fa44c6050ac11e871b1e7e40d5f13a6bb598f 100644 (file)
@@ -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
index 2d4fadc5b2c561094b0c3113c7643d78572a7aa8..21220662705679645c94849c35b74cf07a4cfd0a 100644 (file)
@@ -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
index 4e8fdfb0d525e2e47b498b826198837d1e6ad3e4..3baacd3f7306a9d4aedeca757cdb16f7be29d35e 100644 (file)
@@ -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
index 0c7c3db8e196ef62312c00714cbf7c8c760f3382..df613311ed3323e9a2c723ede337639b455caa5b 100644 (file)
@@ -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
index c6b05c9f4aa9a0c3639fb467145748f8a3335c17..fa3dd685b7ef5bcc91f41856fff25e3dc1a9e5c0 100644 (file)
@@ -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
index 52aa0b3783f09a53cf631d0cf1d7f089a65d6802..b15baa2dc785e799d3ca3170b6b733bfb91f911e 100644 (file)
@@ -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
index 2b6eb06bf42b65aa2a35692dc4c692e951993de7..c7577f5557e6b41d3ed366cc69e9842f591282f8 100644 (file)
@@ -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.
index 9c9ab67157cbcc81ada0fc2778222ed6b7d3a32d..03df087ee0c5bf97f6a2a7a872c3b52d30ce7d69 100644 (file)
@@ -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
index cb98f85678f0e439553a0cb74b86dc032ce66933..62a27c37ef92bcf84416ee5a31c31cfd906e47d3 100644 (file)
@@ -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)
index 6247cc786d08bb144fbb896bf3c6b288cba93d59..ec1d296c94ae77fb63b0d0a8569b44dfff6bc2d1 100644 (file)
@@ -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
index cdc1da8ecdc9c7e8ed55ec75ca517a248e402a1c..0635576c8700388ad207276ed9f368adf8198c3d 100644 (file)
@@ -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.
index be369eae16c397ae423f335feb3438f131b21b17..cb347151dab76cd8a21d150206244eedcb5b7858 100644 (file)
@@ -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
index 6641a238d8e7bc4a7c39d496d0f818f4046d8e33..67a2ee365c2d563aa23f18c777d5839c47517991 100755 (executable)
@@ -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 -$_");
         }
     }
 }