diff options
author | Rich Salz <rsalz@openssl.org> | 2017-04-03 15:39:09 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2017-04-07 14:51:18 -0400 |
commit | 74c29dc6eac1f6f8a8c2ca28f8c01a43beb8c15b (patch) | |
tree | ef4e887705d8a933c44e42bdc5ade8306da3d9de | |
parent | ae9b7e02ecb06def1ccc1d132bd9ba7de1347518 (diff) |
Standardize on =over 4 and check for it.
(cherry picked from commit dfc63ccebd8262648640fc6e35fffa132102b967)
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3117)
-rw-r--r-- | doc/apps/dgst.pod | 38 | ||||
-rw-r--r-- | doc/apps/openssl.pod | 43 | ||||
-rw-r--r-- | doc/apps/rehash.pod | 2 | ||||
-rw-r--r-- | doc/crypto/ASN1_generate_nconf.pod | 6 | ||||
-rw-r--r-- | doc/crypto/BIO_set_callback.pod | 2 | ||||
-rw-r--r-- | doc/crypto/CT_POLICY_EVAL_CTX_new.pod | 36 | ||||
-rw-r--r-- | doc/crypto/EVP_CIPHER_meth_new.pod | 2 | ||||
-rw-r--r-- | doc/crypto/OPENSSL_ia32cap.pod | 4 | ||||
-rw-r--r-- | doc/crypto/SCT_new.pod | 55 | ||||
-rw-r--r-- | doc/crypto/SCT_validate.pod | 14 | ||||
-rw-r--r-- | doc/crypto/d2i_X509.pod | 6 | ||||
-rw-r--r-- | doc/crypto/des_modes.pod | 19 | ||||
-rw-r--r-- | doc/crypto/evp.pod | 2 | ||||
-rwxr-xr-x | util/find-doc-nits | 376 |
14 files changed, 88 insertions, 517 deletions
diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod index 3f1b02ca51..677f2b21ef 100644 --- a/doc/apps/dgst.pod +++ b/doc/apps/dgst.pod @@ -59,34 +59,34 @@ supported digests, use the command I<list --digest-commands>. =item B<-c> -print out the digest in two digit groups separated by colons, only relevant if +Print out the digest in two digit groups separated by colons, only relevant if B<hex> format output is used. =item B<-d> -print out BIO debugging information. +Print out BIO debugging information. =item B<-hex> -digest is to be output as a hex dump. This is the default case for a "normal" +Digest is to be output as a hex dump. This is the default case for a "normal" digest as opposed to a digital signature. See NOTES below for digital signatures using B<-hex>. =item B<-binary> -output the digest or signature in binary form. +Output the digest or signature in binary form. =item B<-r> -output the digest in the "coreutils" format used by programs like B<sha1sum>. +Output the digest in the "coreutils" format used by programs like B<sha1sum>. =item B<-out filename> -filename to output to, or standard output by default. +Filename to output to, or standard output by default. =item B<-sign filename> -digitally sign the digest using the private key in "filename". +Digitally sign the digest using the private key in "filename". =item B<-keyform arg> @@ -98,32 +98,31 @@ and ENGINE formats are supported. Pass options to the signature algorithm during sign or verify operations. Names and values of these options are algorithm-specific. - =item B<-passin arg> -the private key password source. For more information about the format of B<arg> +The private key password source. For more information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. =item B<-verify filename> -verify the signature using the public key in "filename". +Verify the signature using the public key in "filename". The output is either "Verification OK" or "Verification Failure". =item B<-prverify filename> -verify the signature using the private key in "filename". +Verify the signature using the private key in "filename". =item B<-signature filename> -the actual signature to verify. +The actual signature to verify. =item B<-hmac key> -create a hashed MAC using "key". +Create a hashed MAC using "key". =item B<-mac alg> -create MAC (keyed Message Authentication Code). The most popular MAC +Create MAC (keyed Message Authentication Code). The most popular MAC algorithm is HMAC (hash-based MAC), but there are other MAC algorithms which are not based on hash, for instance B<gost-mac> algorithm, supported by B<ccgost> engine. MAC keys and other options should be set @@ -134,7 +133,7 @@ via B<-macopt> parameter. Passes options to MAC algorithm, specified by B<-mac> key. Following options are supported by both by B<HMAC> and B<gost-mac>: -=over 8 +=over 4 =item B<key:string> @@ -152,7 +151,7 @@ for example exactly 32 chars for gost-mac. =item B<-rand file(s)> -a file or files containing random data used to seed the random number +A file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)>). Multiple files can be specified separated by an OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for @@ -160,8 +159,7 @@ all others. =item B<-fips-fingerprint> -compute HMAC using a specific key -for certain OpenSSL-FIPS operations. +Compute HMAC using a specific key for certain OpenSSL-FIPS operations. =item B<-engine id> @@ -177,7 +175,7 @@ engine B<id> for digest operations. =item B<file...> -file or files to digest. If no files are specified then standard input is +File or files to digest. If no files are specified then standard input is used. =back @@ -230,7 +228,7 @@ The FIPS-related options were removed in OpenSSL 1.1.0 =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod index da07cd5caf..7fc53c9bae 100644 --- a/doc/apps/openssl.pod +++ b/doc/apps/openssl.pod @@ -75,7 +75,7 @@ B<list>, or B<no->I<XXX> itself.) =head2 Standard Commands -=over 10 +=over 4 =item L<B<asn1parse>|asn1parse(1)> @@ -91,7 +91,7 @@ Cipher Suite Description Determination. =item L<B<cms>|cms(1)> -CMS (Cryptographic Message Syntax) utility +CMS (Cryptographic Message Syntax) utility. =item L<B<crl>|crl(1)> @@ -113,8 +113,7 @@ Obsoleted by L<B<dhparam>|dhparam(1)>. =item L<B<dhparam>|dhparam(1)> Generation and Management of Diffie-Hellman Parameters. Superseded by -L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)> - +L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>. =item L<B<dsa>|dsa(1)> @@ -123,15 +122,15 @@ DSA Data Management. =item L<B<dsaparam>|dsaparam(1)> DSA Parameter Generation and Management. Superseded by -L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)> +L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>. =item L<B<ec>|ec(1)> -EC (Elliptic curve) key processing +EC (Elliptic curve) key processing. =item L<B<ecparam>|ecparam(1)> -EC parameter manipulation and generation +EC parameter manipulation and generation. =item L<B<enc>|enc(1)> @@ -153,7 +152,7 @@ Obsoleted by L<B<dhparam>|dhparam(1)>. =item L<B<gendsa>|gendsa(1)> Generation of DSA Private Key from Parameters. Superseded by -L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)> +L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>. =item L<B<genpkey>|genpkey(1)> @@ -165,7 +164,7 @@ Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>. =item L<B<nseq>|nseq(1)> -Create or examine a Netscape certificate sequence +Create or examine a Netscape certificate sequence. =item L<B<ocsp>|ocsp(1)> @@ -211,7 +210,7 @@ RSA key management. =item L<B<rsautl>|rsautl(1)> RSA utility for signing, verification, encryption, and decryption. Superseded -by L<B<pkeyutl>|pkeyutl(1)> +by L<B<pkeyutl>|pkeyutl(1)>. =item L<B<s_client>|s_client(1)> @@ -247,11 +246,11 @@ Algorithm Speed Measurement. =item L<B<spkac>|spkac(1)> -SPKAC printing and generating utility +SPKAC printing and generating utility. =item L<B<ts>|ts(1)> -Time Stamping Authority tool (client/server) +Time Stamping Authority tool (client/server). =item L<B<verify>|verify(1)> @@ -269,7 +268,7 @@ X.509 Certificate Data Management. =head2 Message Digest Commands -=over 10 +=over 4 =item B<md2> @@ -315,7 +314,7 @@ SHA-512 Digest =head2 Encoding and Cipher Commands -=over 10 +=over 4 =item B<base64> @@ -366,7 +365,7 @@ This section describes some common options with common behavior. =head2 Common Options -=over 10 +=over 4 =item B<-help> @@ -384,23 +383,23 @@ password argument is given and a password is required then the user is prompted to enter one: this will typically be read from the current terminal with echoing turned off. -=over 10 +=over 4 =item B<pass:password> -the actual password is B<password>. Since the password is visible +The actual password is B<password>. Since the password is visible to utilities (like 'ps' under Unix) this form should only be used where security is not important. =item B<env:var> -obtain the password from the environment variable B<var>. Since +Obtain the password from the environment variable B<var>. Since the environment of other processes is visible on certain platforms (e.g. ps under certain Unix OSes) this option should be used with caution. =item B<file:pathname> -the first line of B<pathname> is the password. If the same B<pathname> +The first line of B<pathname> is the password. If the same B<pathname> argument is supplied to B<-passin> and B<-passout> arguments then the first line will be used for the input password and the next line for the output password. B<pathname> need not refer to a regular file: it could for example @@ -408,12 +407,12 @@ refer to a device or named pipe. =item B<fd:number> -read the password from the file descriptor B<number>. This can be used to +Read the password from the file descriptor B<number>. This can be used to send the data via a pipe for example. =item B<stdin> -read the password from standard input. +Read the password from standard input. =back @@ -441,7 +440,7 @@ manual pages. =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/apps/rehash.pod b/doc/apps/rehash.pod index 936fda6180..1dca9b5341 100644 --- a/doc/apps/rehash.pod +++ b/doc/apps/rehash.pod @@ -107,7 +107,7 @@ By default, B<rehash> only lists each directory as it is processed. =head1 ENVIRONMENT -=over +=over 4 =item B<OPENSSL> diff --git a/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod index 92f624fa24..bf29af62f7 100644 --- a/doc/crypto/ASN1_generate_nconf.pod +++ b/doc/crypto/ASN1_generate_nconf.pod @@ -30,7 +30,7 @@ The actual data encoded is determined by the string B<str> and the configuration information. The general format of the string is: -=over 2 +=over 4 =item B<[modifier,]type[:value]> @@ -45,7 +45,7 @@ B<value> and B<modifier> are explained below. The supported types are listed below. Unless otherwise specified only the B<ASCII> format is permissible. -=over 2 +=over 4 =item B<BOOLEAN>, B<BOOL> @@ -126,7 +126,7 @@ add EXPLICIT or IMPLICIT tagging, add wrappers or to change the string format of the final type and value. The supported formats are documented below. -=over 2 +=over 4 =item B<EXPLICIT>, B<EXP> diff --git a/doc/crypto/BIO_set_callback.pod b/doc/crypto/BIO_set_callback.pod index ed395fa0ab..3d15859406 100644 --- a/doc/crypto/BIO_set_callback.pod +++ b/doc/crypto/BIO_set_callback.pod @@ -52,7 +52,7 @@ BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn() is the type of the old format callback function. The meaning of each argument is described below: -=over +=over 4 =item B<b> diff --git a/doc/crypto/CT_POLICY_EVAL_CTX_new.pod b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod index 4d0cae3bbf..7839fd393a 100644 --- a/doc/crypto/CT_POLICY_EVAL_CTX_new.pod +++ b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod @@ -32,23 +32,15 @@ This policy may be, for example, that at least one valid SCT is available. To determine this, an SCT's timestamp and signature must be verified. This requires: -=over 2 +=over 4 -=item * +=item * the public key of the log that issued the SCT -the public key of the log that issued the SCT +=item * the certificate that the SCT was issued for -=item * +=item * the issuer certificate (if the SCT was issued for a pre-certificate) -the certificate that the SCT was issued for - -=item * - -the issuer certificate (if the SCT was issued for a pre-certificate) - -=item * - -the current time +=item * the current time =back @@ -57,30 +49,22 @@ The above requirements are met using the setters described below. CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This should then be populated using: -=over 2 +=over 4 -=item * - -CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for +=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for Increments the reference count of the certificate. -=item * - -CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate +=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate Increments the reference count of the certificate. -=item * - -CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs +=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the CT_POLICY_EVAL_CTX. -=item * - -CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid +=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid The SCT timestamp will be compared to this time to check whether the SCT was issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose diff --git a/doc/crypto/EVP_CIPHER_meth_new.pod b/doc/crypto/EVP_CIPHER_meth_new.pod index 6e18ed5412..ef47f0fdb3 100644 --- a/doc/crypto/EVP_CIPHER_meth_new.pod +++ b/doc/crypto/EVP_CIPHER_meth_new.pod @@ -82,7 +82,7 @@ With the exception of cipher modes, of which only one may be present, several flags can be or'd together. The available flags are: -=over +=over 4 =item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod index 7ea70c0fae..b0ab0ce551 100644 --- a/doc/crypto/OPENSSL_ia32cap.pod +++ b/doc/crypto/OPENSSL_ia32cap.pod @@ -19,7 +19,7 @@ between different code paths to provide optimal performance across wide range of processors. For the moment of this writing following bits are significant: -=over +=over 4 =item bit #4 denoting presence of Time-Stamp Counter. @@ -86,7 +86,7 @@ are applied, most notably in AES assembler module. The capability vector is further extended with EBX value returned by CPUID with EAX=7 and ECX=0 as input. Following bits are significant: -=over +=over 4 =item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN; diff --git a/doc/crypto/SCT_new.pod b/doc/crypto/SCT_new.pod index e85b21ca1b..23595e1056 100644 --- a/doc/crypto/SCT_new.pod +++ b/doc/crypto/SCT_new.pod @@ -84,45 +84,31 @@ An internal representation of an SCT can be created in one of two ways. The first option is to create a blank SCT, using SCT_new(), and then populate it using: -=over 2 +=over 4 -=item * - -SCT_set_version() to set the SCT version. +=item * SCT_set_version() to set the SCT version. Only SCT_VERSION_V1 is currently supported. -=item * - -SCT_set_log_entry_type() to set the type of certificate the SCT was issued for: +=item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for: B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. -=item * - -SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from. +=item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from. The former takes ownership, whereas the latter makes a copy. See RFC 6962, Section 3.2 for the definition of LogID. -=item * - -SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds). - -=item * - -SCT_set_signature_nid() to set the NID of the signature. +=item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds). -=item * +=item * SCT_set_signature_nid() to set the NID of the signature. -SCT_set0_signature() or SCT_set1_signature() to set the raw signature value. +=item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value. The former takes ownership, whereas the latter makes a copy. -=item * - -SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions. +=item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions. The former takes ownership, whereas the latter makes a copy. @@ -131,33 +117,22 @@ The former takes ownership, whereas the latter makes a copy. Alternatively, the SCT can be pre-populated from the following data using SCT_new_from_base64(): -=over 2 - -=item * - -The SCT version (only SCT_VERSION_V1 is currently supported). +=over 4 -=item * +=item * The SCT version (only SCT_VERSION_V1 is currently supported). -The LogID (see RFC 6962, Section 3.2), base64 encoded. +=item * The LogID (see RFC 6962, Section 3.2), base64 encoded. -=item * +=item * The type of certificate the SCT was issued for: -The type of certificate the SCT was issued for: B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. -=item * - -The time that the SCT was issued (epoch time in milliseconds). - -=item * - -The SCT extensions, base64 encoded. +=item * The time that the SCT was issued (epoch time in milliseconds). -=item * +=item * The SCT extensions, base64 encoded. -The SCT signature, base64 encoded. +=item * The SCT signature, base64 encoded. =back diff --git a/doc/crypto/SCT_validate.pod b/doc/crypto/SCT_validate.pod index 5ff0e8c459..3c03e97287 100644 --- a/doc/crypto/SCT_validate.pod +++ b/doc/crypto/SCT_validate.pod @@ -31,26 +31,20 @@ SCT_get_validation_status(). A CT_POLICY_EVAL_CTX must be provided that specifies: -=over 2 +=over 4 -=item * - -The certificate the SCT was issued for. +=item * The certificate the SCT was issued for. Failure to provide the certificate will result in the validation status being SCT_VALIDATION_STATUS_UNVERIFIED. -=item * - -The issuer of that certificate. +=item * The issuer of that certificate. This is only required if the SCT was issued for a pre-certificate (see RFC 6962). If it is required but not provided, the validation status will be SCT_VALIDATION_STATUS_UNVERIFIED. -=item * - -A CTLOG_STORE that contains the CT log that issued this SCT. +=item * A CTLOG_STORE that contains the CT log that issued this SCT. If the SCT was issued by a log that is not in this CTLOG_STORE, the validation status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG. diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod index 06546a4875..f78d02065c 100644 --- a/doc/crypto/d2i_X509.pod +++ b/doc/crypto/d2i_X509.pod @@ -349,10 +349,10 @@ i2d_X509_SIG, i2d_X509_VAL, - convert objects from/to ASN.1/DER representation -=for comment generic - =head1 SYNOPSIS +=for comment generic + TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length); TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); @@ -436,7 +436,7 @@ another will be processed after it. The following points about the data types might be useful: -=over +=over 4 =item B<ASN1_OBJECT> diff --git a/doc/crypto/des_modes.pod b/doc/crypto/des_modes.pod index 5107b77c8d..7c1796980b 100644 --- a/doc/crypto/des_modes.pod +++ b/doc/crypto/des_modes.pod @@ -1,5 +1,4 @@ =pod - =for comment openssl_manual_section:7 =head1 NAME @@ -18,7 +17,7 @@ other things. Normally, this is found as the function I<algorithm>_ecb_encrypt(). -=over 2 +=over 4 =item * @@ -45,7 +44,7 @@ Normally, this is found as the function I<algorithm>_cbc_encrypt(). Be aware that des_cbc_encrypt() is not really DES CBC (it does not update the IV); use des_ncbc_encrypt() instead. -=over 2 +=over 4 =item * @@ -77,7 +76,7 @@ An error will affect the current and the following ciphertext blocks. Normally, this is found as the function I<algorithm>_cfb_encrypt(). -=over 2 +=over 4 =item * @@ -124,7 +123,7 @@ An error will affect the current and the following ciphertext variables. Normally, this is found as the function I<algorithm>_ofb_encrypt(). -=over 2 +=over 4 =item * @@ -185,7 +184,7 @@ susceptible to a 'known plaintext' attack. Normally, this is found as the function I<algorithm>_ecb3_encrypt(). -=over 2 +=over 4 =item * @@ -220,8 +219,7 @@ ecb mode. Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt(). -=over 2 - +=over 4 =item * @@ -248,12 +246,11 @@ it to: =head1 SEE ALSO -L<blowfish(3)>, L<des(3)>, L<idea(3)>, -L<rc2(3)> +L<BF_encrypt(3)>, L<DES_crypt(3)> =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. Licensed under the OpenSSL license (the "License"). You may not use this file except in compliance with the License. You can obtain a copy diff --git a/doc/crypto/evp.pod b/doc/crypto/evp.pod index 31f459084d..02051df6bc 100644 --- a/doc/crypto/evp.pod +++ b/doc/crypto/evp.pod @@ -38,7 +38,7 @@ L<EVP_PKEY_print_private(3)>. The EVP_PKEY functions support the full range of asymmetric algorithm operations: -=over +=over 4 =item For key agreement see L<EVP_PKEY_derive(3)> diff --git a/util/find-doc-nits b/util/find-doc-nits deleted file mode 100755 index 63698801d7..0000000000 --- a/util/find-doc-nits +++ /dev/null @@ -1,376 +0,0 @@ -#! /usr/bin/env perl -# Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. -# -# Licensed under the OpenSSL license (the "License"). You may not use -# this file except in compliance with the License. You can obtain a copy -# in the file LICENSE in the source distribution or at -# https://www.openssl.org/source/license.html - - -require 5.10.0; -use warnings; -use strict; -use Pod::Checker; -use File::Find; -use File::Basename; -use File::Spec::Functions; -use Getopt::Std; -use lib catdir(dirname($0), "perl"); -use OpenSSL::Util::Pod; - -# Options. -our($opt_s); -our($opt_u); -our($opt_h); -our($opt_n); -our($opt_l); - -sub help() -{ - print <<EOF; -Find small errors (nits) in documentation. Options: - -l Print bogus links - -n Print nits in POD pages - -s Also print missing sections in POD pages (implies -n) - -u List undocumented functions - -h Print this help message -EOF - exit; -} - -my $temp = '/tmp/docnits.txt'; -my $OUT; - -my %mandatory_sections = - ( '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ], - 1 => [ 'SYNOPSIS', 'OPTIONS' ], - 3 => [ 'SYNOPSIS', 'RETURN VALUES' ], - 5 => [ ], - 7 => [ ] ); - -# Cross-check functions in the NAME and SYNOPSIS section. -sub name_synopsis() -{ - my $id = shift; - my $filename = shift; - my $contents = shift; - - # Get NAME section and all words in it. - return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms; - my $tmp = $1; - $tmp =~ tr/\n/ /; - print "$id trailing comma before - in NAME\n" if $tmp =~ /, *-/; - $tmp =~ s/-.*//g; - $tmp =~ s/,//g; - - my $dirname = dirname($filename); - my $simplename = basename($filename); - $simplename =~ s/.pod$//; - my $foundfilename = 0; - my %foundfilenames = (); - my %names; - foreach my $n ( split ' ', $tmp ) { - $names{$n} = 1; - $foundfilename++ if $n eq $simplename; - $foundfilenames{$n} = 1 - if -f "$dirname/$n.pod" && $n ne $simplename; - } - print "$id the following exist as other .pod files:\n", - join(" ", sort keys %foundfilenames), "\n" - if %foundfilenames; - print "$id $simplename (filename) missing from NAME section\n", - unless $foundfilename; - - # Find all functions in SYNOPSIS - return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms; - my $syn = $1; - foreach my $line ( split /\n+/, $syn ) { - my $sym; - $line =~ s/STACK_OF\([^)]+\)/int/g; - $line =~ s/__declspec\([^)]+\)//; - if ( $line =~ /env (\S*)=/ ) { - # environment variable env NAME=... - $sym = $1; - } elsif ( $line =~ /typedef.*\(\*(\S+)\)\(.*/ ) { - # a callback function: typedef ... (*NAME)(... - $sym = $1; - } elsif ( $line =~ /typedef.* (\S+);/ ) { - # a simple typedef: typedef ... NAME; - $sym = $1; - } elsif ( $line =~ /enum (\S*) \{/ ) { - # an enumeration: enum ... { - $sym = $1; - } elsif ( $line =~ /#define ([A-Za-z0-9_]+)/ ) { - $sym = $1; - } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) { - $sym = $1; - } - else { - next; - } - print "$id $sym missing from NAME section\n" - unless defined $names{$sym}; - $names{$sym} = 2; - - # Do some sanity checks on the prototype. - print "$id prototype missing spaces around commas: $line\n" - if ( $line =~ /[a-z0-9],[^ ]/ ); - } - - foreach my $n ( keys %names ) { - next if $names{$n} == 2; - print "$id $n missing from SYNOPSIS\n"; - } -} - -sub check() -{ - my $filename = shift; - my $dirname = basename(dirname($filename)); - - my $contents = ''; - { - local $/ = undef; - open POD, $filename or die "Couldn't open $filename, $!"; - $contents = <POD>; - close POD; - } - - my $id = "${filename}:1:"; - - &name_synopsis($id, $filename, $contents) - unless $contents =~ /=for comment generic/ - or $filename =~ m@man[157]/@; - - print "$id doesn't start with =pod\n" - if $contents !~ /^=pod/; - print "$id doesn't end with =cut\n" - if $contents !~ /=cut\n$/; - print "$id more than one cut line.\n" - if $contents =~ /=cut.*=cut/ms; - print "$id missing copyright\n" - if $contents !~ /Copyright .* The OpenSSL Project Authors/; - print "$id copyright not last\n" - if $contents =~ /head1 COPYRIGHT.*=head/ms; - print "$id head2 in All uppercase\n" - if $contents =~ /head2\s+[A-Z ]+\n/; - print "$id extra space after head\n" - if $contents =~ /=head\d\s\s+/; - print "$id period in NAME section\n" - if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms; - print "$id POD markup in NAME section\n" - if $contents =~ /=head1 NAME.*[<>].*=head1 SYNOPSIS/ms; - print "$id Duplicate $1 in L<>\n" - if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2; - print "$id Bad =over $1\n" - if $contents =~ /=over([^ ][^24])/; - - # Look for multiple consecutive openssl #include lines. - # Consecutive because of files like md5.pod. Sometimes it's okay - # or necessary, as in ssl/SSL_set1_host.pod - if ( $contents !~ /=for comment multiple includes/ ) { - if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) { - my $count = 0; - foreach my $line ( split /\n+/, $1 ) { - if ( $line =~ m@include <openssl/@ ) { - if ( ++$count == 2 ) { - print "$id has multiple includes\n"; - } - } else { - $count = 0; - } - } - } - } - - return unless $opt_s; - - # Find what section this page is in. If run from "." assume - # section 3. - my $section = 3; - $section = $1 if $dirname =~ /man([1-9])/; - - foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) { - print "$id: missing $_ head1 section\n" - if $contents !~ /^=head1\s+${_}\s*$/m; - } - - open my $OUT, '>', $temp - or die "Can't open $temp, $!"; - podchecker($filename, $OUT); - close $OUT; - open $OUT, '<', $temp - or die "Can't read $temp, $!"; - while ( <$OUT> ) { - next if /\(section\) in.*deprecated/; - print; - } - close $OUT; - unlink $temp || warn "Can't remove $temp, $!"; -} - -my %dups; - -sub pa |