Add -p (public only) flag to find-doc-nits

=pod

=head1 NAME

i2d_Netscape_RSA,

d2i_Netscape_RSA

- insecure RSA public and private key encoding functions

=head1 SYNOPSIS

 #include <openssl/rsa.h>

 int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)());

 RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)());

=head1 DESCRIPTION

These functions decode and encode an RSA private

key in NET format.  These functions are present to provide compatibility

with very old software. This format has some severe security weaknesses

and should be avoided if possible.

These functions are similar to the B<d2i_RSAPrivateKey> functions.

=head1 SEE ALSO

L<d2i_RSAPrivateKey(3)>

=head1 COPYRIGHT

Copyright 2000-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

L<https://www.openssl.org/source/license.html>.

=cut

our($opt_h);

our($opt_n);

our($opt_l);

our($opt_p);

sub help()

{

    -l Print bogus links

    -n Print nits in POD pages

    -s Also print missing sections in POD pages (implies -n)

    -p Warn if non-public name documented (implies -n)

    -u List undocumented functions

    -h Print this help message

EOF

my $temp = '/tmp/docnits.txt';

my $OUT;

my %public;

my %mandatory_sections =

    ( '*'    => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],

    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",

    print "$id $simplename (filename) missing from NAME section\n"

        unless $foundfilename;

    print "$id $simplename is not public\n"

        if $opt_p and !defined $public{$simplename};

    # Find all functions in SYNOPSIS

    return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;

        or die "Can't open $file, $!, stopped";

    while ( <$IN> ) {

        next if /^#/;

        next if /\bNOEXIST\b/;

        next if /\bEXPORT_VAR_AS_FUNC\b/;

        push @apis, $1 if /([^\s]+).\s/;

    close $IN;

    print "# Found ", scalar(@apis), " in $file\n";

    print "# Found ", scalar(@apis), " in $file\n" unless $opt_p;

    return sort @apis;

}

    }

}

getopts('lnshu');

sub publicize() {

    foreach my $name ( &parsenum('util/libcrypto.num') ) {

        $public{$name} = 1;

    }

    foreach my $name ( &parsenum('util/libssl.num') ) {

        $public{$name} = 1;

    }

    foreach my $name ( &parsenum('util/private.num') ) {

        $public{$name} = 1;

    }

}

getopts('lnsphu');

&help() if $opt_h;

&help() if ( $opt_h );

die "Need one of -l -n -s -p or -u flags.\n"

    unless $opt_l or $opt_n or $opt_s or $opt_p or $opt_u;

die "Need one of -l -n -s or -u flags.\n"

    unless $opt_l or $opt_n or $opt_s or $opt_u;

$opt_n = 1 if $opt_s or $opt_p;

if ( $opt_n or $opt_s ) {

if ( $opt_n ) {

    &publicize() if $opt_p;

    foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {

        &check($_);

    }

# This isn't a library ".num" file but is a list of documented items

# that don't appear in lib*.num -- because they are define's, in

# assembly language, etc.

BIO_ADDR                                datatype

BIO_ADDRINFO                            datatype

UI_STRING                               datatype

X509_STORE_set_verify_cb_func           datatype

OPENSSL_Applink                         external

OPENSSL_ia32cap                         environment

OPENSSL_instrument_bus                  assembler

BIO_should_retry                        define

BN_num_bytes                            define

BN_zero                                 define

DTLS_get_link_min_mtu                   define

DTLS_set_link_mtu                       define

ERR_GET_LIB                             define

EVP_PKEY_CTX_add1_tls1_prf_seed         define

EVP_PKEY_CTX_set1_hkdf_key              define

EVP_PKEY_CTX_set1_hkdf_salt             define

EVP_PKEY_CTX_set1_tls1_prf_secret       define

EVP_PKEY_CTX_set_hkdf_md                define

EVP_PKEY_CTX_set_tls1_prf_md            define

EVP_SignInit                            define

EVP_VerifyInit                          define

OPENSSL_VERSION_NUMBER                  define

OPENSSL_malloc                          define

OPENSSL_secure_malloc                   define

SSL_CTX_add1_chain_cert                 define

SSL_CTX_add_extra_chain_cert            define

SSL_CTX_clear_mode                      define

SSL_CTX_get_mode                        define

SSL_CTX_sess_number                     define

SSL_CTX_sess_set_cache_size             define

SSL_CTX_set1_curves                     define

SSL_CTX_set1_sigalgs                    define

SSL_CTX_set1_verify_cert_store          define

SSL_CTX_set_max_cert_list               define

SSL_CTX_set_min_proto_version           define

SSL_CTX_set_mode                        define

SSL_CTX_set_read_ahead                  define

SSL_CTX_set_session_cache_mode          define

SSL_CTX_set_split_send_fragment         define

SSL_CTX_set_tlsext_servername_callback  define

SSL_CTX_set_tlsext_status_cb            define

SSL_CTX_set_tlsext_ticket_key_cb        define

SSL_clear_mode                          define

SSL_get_extms_support                   define

SSL_get_mode                            define

SSL_get_peer_signature_nid              define

SSL_get_server_tmp_key                  define

SSL_set_mode                            define

SSL_set_mtu                             define