xref: /freebsd/crypto/openssl/util/find-doc-nits (revision e7be843b4a162e68651d3911f0357ed464915629)
1#! /usr/bin/env perl
2# Copyright 2002-2025 The OpenSSL Project Authors. All Rights Reserved.
3#
4# Licensed under the Apache License 2.0 (the "License").  You may not use
5# this file except in compliance with the License.  You can obtain a copy
6# in the file LICENSE in the source distribution or at
7# https://www.openssl.org/source/license.html
8
9
10require 5.10.0;
11use warnings;
12use strict;
13
14use Carp qw(:DEFAULT cluck);
15use Pod::Checker;
16use File::Find;
17use File::Basename;
18use File::Spec::Functions;
19use Getopt::Std;
20use FindBin;
21use lib "$FindBin::Bin/perl";
22
23use OpenSSL::Util::Pod;
24
25use lib '.';
26use configdata;
27
28# Set to 1 for debug output
29my $debug = 0;
30
31# Options.
32our($opt_d);
33our($opt_e);
34our($opt_s);
35our($opt_o);
36our($opt_h);
37our($opt_l);
38our($opt_m);
39our($opt_n);
40our($opt_p);
41our($opt_u);
42our($opt_v);
43our($opt_c);
44our($opt_i);
45
46# Print usage message and exit.
47sub help {
48    print <<EOF;
49Find small errors (nits) in documentation.  Options:
50    -c List undocumented commands, undocumented options and unimplemented options.
51    -d Detailed list of undocumented (implies -u)
52    -e Detailed list of new undocumented (implies -v)
53    -h Print this help message
54    -l Print bogus links
55    -m Name(s) of manuals to focus on. Default: man1,man3,man5,man7
56    -n Print nits in POD pages
57    -o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v)
58    -i Checks for history entries available for symbols added since 3.0.0 as new
59    -u Count undocumented functions
60    -v Count new undocumented functions
61EOF
62    exit;
63}
64
65getopts('cdehlm:noiuv');
66
67help() if $opt_h;
68$opt_u = 1 if $opt_d;
69$opt_v = 1 if $opt_o || $opt_e;
70die "Cannot use both -u and -v"
71    if $opt_u && $opt_v;
72die "Cannot use both -d and -e"
73    if $opt_d && $opt_e;
74
75# We only need to check c, l, n, u and v.
76# Options d, e, o imply one of the above.
77die "Need one of -[cdehlnouv] flags.\n"
78    unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v;
79
80
81my $temp = '/tmp/docnits.txt';
82my $OUT;
83my $status = 0;
84
85$opt_m = "man1,man3,man5,man7" unless $opt_m;
86die "Argument of -m option may contain only man1, man3, man5, and/or man7"
87    unless $opt_m =~ /^(man[1357][, ]?)*$/;
88my @sections = ( split /[, ]/, $opt_m );
89
90my %mandatory_sections = (
91    '*' => [ 'NAME', 'COPYRIGHT' ],
92    1   => [ 'DESCRIPTION', 'SYNOPSIS', 'OPTIONS' ],
93    3   => [ 'DESCRIPTION', 'SYNOPSIS', 'RETURN VALUES' ],
94    5   => [ 'DESCRIPTION' ],
95    7   => [ ]
96                         );
97
98# Symbols that we ignored.
99# They are reserved macros that we currently don't document
100my $ignored = qr/(?| ^i2d_
101                 |   ^d2i_
102                 |   ^DEPRECATEDIN
103                 |   ^OSSL_DEPRECATED
104                 |   \Q_fnsig(3)\E$
105                 |   ^IMPLEMENT_
106                 |   ^_?DECLARE_
107                 |   ^sk_
108                 |   ^SKM_DEFINE_STACK_OF_INTERNAL
109                 |   ^lh_
110                 |   ^DEFINE_LHASH_OF_(INTERNAL|DEPRECATED)
111                 |   ^OSSL_HTO[BL]E(16|32|64)   # undefed
112                 |   ^OSSL_[BL]E(16|32|64)TOH   # undefed
113                 )/x;
114
115# A common regexp for C symbol names
116my $C_symbol = qr/\b[[:alpha:]][_[:alnum:]]*\b/;
117
118# Collect all POD files, both internal and public, and regardless of location
119# We collect them in a hash table with each file being a key, so we can attach
120# tags to them.  For example, internal docs will have the word "internal"
121# attached to them.
122my %files = ();
123# We collect files names on the fly, on known tag basis
124my %collected_tags = ();
125# We cache results based on tags
126my %collected_results = ();
127
128# files OPTIONS
129#
130# Example:
131#
132#       files(TAGS => 'manual');
133#       files(TAGS => [ 'manual', 'man1' ]);
134#
135# This function returns an array of files corresponding to a set of tags
136# given with the options "TAGS".  The value of this option can be a single
137# word, or an array of several words, which work as inclusive or exclusive
138# selectors.  Inclusive selectors are used to add one more set of files to
139# the returned array, while exclusive selectors limit the set of files added
140# to the array.  The recognised tag values are:
141#
142# 'public_manual'       - inclusive selector, adds public manuals to the
143#                         returned array of files.
144# 'internal_manual'     - inclusive selector, adds internal manuals to the
145#                         returned array of files.
146# 'manual'              - inclusive selector, adds any manual to the returned
147#                         array of files.  This is really a shorthand for
148#                         'public_manual' and 'internal_manual' combined.
149# 'public_header'       - inclusive selector, adds public headers to the
150#                         returned array of files.
151# 'header'              - inclusive selector, adds any header file to the
152#                         returned array of files.  Since we currently only
153#                         care about public headers, this is exactly
154#                         equivalent to 'public_header', but is present for
155#                         consistency.
156#
157# 'man1', 'man3', 'man5', 'man7'
158#                       - exclusive selectors, only applicable together with
159#                         any of the manual selectors.  If any of these are
160#                         present, only the manuals from the given sections
161#                         will be included.  If none of these are present,
162#                         the manuals from all sections will be returned.
163#
164# All returned manual files come from configdata.pm.
165# All returned header files come from looking inside
166# "$config{sourcedir}/include/openssl"
167#
168sub files {
169    my %opts = ( @_ );          # Make a copy of the arguments
170
171    $opts{TAGS} = [ $opts{TAGS} ] if ref($opts{TAGS}) eq '';
172
173    croak "No tags given, or not an array"
174        unless exists $opts{TAGS} && ref($opts{TAGS}) eq 'ARRAY';
175
176    my %tags = map { $_ => 1 } @{$opts{TAGS}};
177    $tags{public_manual} = 1
178        if $tags{manual} && ($tags{public} // !$tags{internal});
179    $tags{internal_manual} = 1
180        if $tags{manual} && ($tags{internal} // !$tags{public});
181    $tags{public_header} = 1
182        if $tags{header} && ($tags{public} // !$tags{internal});
183    delete $tags{manual};
184    delete $tags{header};
185    delete $tags{public};
186    delete $tags{internal};
187
188    my $tags_as_key = join(':', sort keys %tags);
189
190    cluck  "DEBUG[files]: This is how we got here!" if $debug;
191    print STDERR "DEBUG[files]: tags: $tags_as_key\n" if $debug;
192
193    my %tags_to_collect = ( map { $_ => 1 }
194                            grep { !exists $collected_tags{$_} }
195                            keys %tags );
196
197    if ($tags_to_collect{public_manual}) {
198        print STDERR "DEBUG[files]: collecting public manuals\n"
199            if $debug;
200
201        # The structure in configdata.pm is that $unified_info{mandocs}
202        # contains lists of man files, and in turn, $unified_info{depends}
203        # contains hash tables showing which POD file each of those man
204        # files depend on.  We use that information to find the POD files,
205        # and to attach the man section they belong to as tags
206        foreach my $mansect ( @sections ) {
207            foreach ( map { @{$unified_info{depends}->{$_}} }
208                      @{$unified_info{mandocs}->{$mansect}} ) {
209                $files{$_} = { $mansect => 1, public_manual => 1 };
210            }
211        }
212        $collected_tags{public_manual} = 1;
213    }
214
215    if ($tags_to_collect{internal_manual}) {
216        print STDERR "DEBUG[files]: collecting internal manuals\n"
217            if $debug;
218
219        # We don't have the internal docs in configdata.pm.  However, they
220        # are all in the source tree, so they're easy to find.
221        foreach my $mansect ( @sections ) {
222            foreach ( glob(catfile($config{sourcedir},
223                                   'doc', 'internal', $mansect, '*.pod')) ) {
224                $files{$_} = { $mansect => 1, internal_manual => 1 };
225            }
226        }
227        $collected_tags{internal_manual} = 1;
228    }
229
230    if ($tags_to_collect{public_header}) {
231        print STDERR "DEBUG[files]: collecting public headers\n"
232            if $debug;
233
234        foreach ( glob(catfile($config{sourcedir},
235                               'include', 'openssl', '*.h')) ) {
236            $files{$_} = { public_header => 1 };
237        }
238    }
239
240    my @result = @{$collected_results{$tags_as_key} // []};
241
242    if (!@result) {
243        # Produce a result based on caller tags
244        foreach my $type ( ( 'public_manual', 'internal_manual' ) ) {
245            next unless $tags{$type};
246
247            # If caller asked for specific sections, we care about sections.
248            # Otherwise, we give back all of them.
249            my @selected_sections =
250                grep { $tags{$_} } @sections;
251            @selected_sections = @sections unless @selected_sections;
252
253            foreach my $section ( ( @selected_sections ) ) {
254                push @result,
255                    ( sort { basename($a) cmp basename($b) }
256                      grep { $files{$_}->{$type} && $files{$_}->{$section} }
257                      keys %files );
258            }
259        }
260        if ($tags{public_header}) {
261            push @result,
262                ( sort { basename($a) cmp basename($b) }
263                  grep { $files{$_}->{public_header} }
264                  keys %files );
265        }
266
267        if ($debug) {
268            print STDERR "DEBUG[files]: result:\n";
269            print STDERR "DEBUG[files]:     $_\n" foreach @result;
270        }
271        $collected_results{$tags_as_key} = [ @result ];
272    }
273
274    return @result;
275}
276
277# Print error message, set $status.
278sub err {
279    my $t = join(" ", @_);
280    $t =~ s/\n//g;
281    print $t, "\n";
282    $status = 1
283}
284
285# Cross-check functions in the NAME and SYNOPSIS section.
286sub name_synopsis {
287    my $id = shift;
288    my $filename = shift;
289    my $contents = shift;
290
291    # Get NAME section and all words in it.
292    return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms;
293    my $tmp = $1;
294    $tmp =~ tr/\n/ /;
295    err($id, "Trailing comma before - in NAME")
296        if $tmp =~ /, *-/;
297    $tmp =~ s/ -.*//g;
298    err($id, "POD markup among the names in NAME")
299        if $tmp =~ /[<>]/;
300    $tmp =~ s/  */ /g;
301    err($id, "Missing comma in NAME")
302        if $tmp =~ /[^,] /;
303
304    my $dirname = dirname($filename);
305    my $section = basename($dirname);
306    my $simplename = basename($filename, ".pod");
307    my $foundfilename = 0;
308    my %foundfilenames = ();
309    my %names;
310    foreach my $n ( split ',', $tmp ) {
311        $n =~ s/^\s+//;
312        $n =~ s/\s+$//;
313        err($id, "The name '$n' contains white-space")
314            if $n =~ /\s/;
315        $names{$n} = 1;
316        $foundfilename++ if $n eq $simplename;
317        $foundfilenames{$n} = 1
318            if ( ( grep { basename($_) eq "$n.pod" }
319                   files(TAGS => [ 'manual', $section ]) )
320                 && $n ne $simplename );
321    }
322    err($id, "The following exist as other .pod files:",
323         sort keys %foundfilenames)
324        if %foundfilenames;
325    err($id, "$simplename (filename) missing from NAME section")
326        unless $foundfilename;
327
328    # Find all functions in SYNOPSIS
329    return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
330    my $syn = $1;
331    my $ignore_until = undef;   # If defined, this is a regexp
332    # Remove all non-code lines
333    $syn =~ s/^(?:\s*?|\S.*?)$//msg;
334    # Remove all comments
335    $syn =~ s/\/\*.*?\*\///msg;
336    while ( $syn ) {
337        # "env" lines end at a newline.
338        # Preprocessor lines start with a # and end at a newline.
339        # Other lines end with a semicolon, and may cover more than
340        # one physical line.
341        if ( $syn !~ /^ \s*(env .*?|#.*?|.*?;)\s*$/ms ) {
342            err($id, "Can't parse rest of synopsis:\n$syn\n(declarations not ending with a semicolon (;)?)");
343            last;
344        }
345        my $line = $1;
346        $syn = $';
347
348        print STDERR "DEBUG[name_synopsis] \$line = '$line'\n" if $debug;
349
350        # Special code to skip over documented structures
351        if ( defined $ignore_until) {
352            next if $line !~ /$ignore_until/;
353            $ignore_until = undef;
354            next;
355        }
356        if ( $line =~ /^\s*(?:typedef\s+)?struct(?:\s+\S+)\s*\{/ ) {
357            $ignore_until = qr/\}.*?;/;
358            next;
359        }
360
361        my $sym;
362        my $is_prototype = 1;
363        $line =~ s/LHASH_OF\([^)]+\)/int/g;
364        $line =~ s/STACK_OF\([^)]+\)/int/g;
365        $line =~ s/SPARSE_ARRAY_OF\([^)]+\)/int/g;
366        $line =~ s/__declspec\([^)]+\)//;
367
368        ## We don't prohibit that space, to allow typedefs looking like
369        ## this:
370        ##
371        ## typedef int (fantastically_long_name_breaks_80char_limit)
372        ##     (fantastically_long_name_breaks_80char_limit *something);
373        ##
374        #if ( $line =~ /typedef.*\(\*?\S+\)\s+\(/ ) {
375        #    # a callback function with whitespace before the argument list:
376        #    # typedef ... (*NAME) (...
377        #    # typedef ... (NAME) (...
378        #    err($id, "Function typedef has space before arg list: $line");
379        #}
380
381        if ( $line =~ /env (\S*)=/ ) {
382            # environment variable env NAME=...
383            $sym = $1;
384        } elsif ( $line =~ /typedef.*\(\*?($C_symbol)\)\s*\(/ ) {
385            # a callback function pointer: typedef ... (*NAME)(...
386            # a callback function signature: typedef ... (NAME)(...
387            $sym = $1;
388        } elsif ( $line =~ /typedef.*($C_symbol)\s*\(/ ) {
389            # a callback function signature: typedef ... NAME(...
390            $sym = $1;
391        } elsif ( $line =~ /typedef.*($C_symbol);/ ) {
392            # a simple typedef: typedef ... NAME;
393            $is_prototype = 0;
394            $sym = $1;
395        } elsif ( $line =~ /enum ($C_symbol) \{/ ) {
396            # an enumeration: enum ... {
397            $sym = $1;
398        } elsif ( $line =~ /#\s*(?:define|undef) ($C_symbol)/ ) {
399            $is_prototype = 0;
400            $sym = $1;
401        } elsif ( $line =~ /^[^\(]*?\(\*($C_symbol)\s*\(/ ) {
402            # a function returning a function pointer: TYPE (*NAME(args))(args)
403            $sym = $1;
404        } elsif ( $line =~ /^[^\(]*?($C_symbol)\s*\(/ ) {
405            # a simple function declaration
406            $sym = $1;
407        }
408        else {
409            next;
410        }
411
412        print STDERR "DEBUG[name_synopsis] \$sym = '$sym'\n" if $debug;
413
414        err($id, "$sym missing from NAME section")
415            unless defined $names{$sym};
416        $names{$sym} = 2;
417
418        # Do some sanity checks on the prototype.
419        err($id, "Prototype missing spaces around commas: $line")
420            if $is_prototype && $line =~ /[a-z0-9],[^\s]/;
421    }
422
423    foreach my $n ( keys %names ) {
424        next if $names{$n} == 2;
425        err($id, "$n missing from SYNOPSIS")
426    }
427}
428
429# Check if SECTION ($3) is located before BEFORE ($4)
430sub check_section_location {
431    my $id = shift;
432    my $contents = shift;
433    my $section = shift;
434    my $before = shift;
435
436    return unless $contents =~ /=head1 $section/
437        and $contents =~ /=head1 $before/;
438    err($id, "$section should appear before $before section")
439        if $contents =~ /=head1 $before.*=head1 $section/ms;
440}
441
442# Check if HISTORY section is present and functionname ($2) is present in it
443# or a generic "(f)unction* added" term hints at several new functions in
444# the documentation (yes, this is an approximation only but it works :)
445sub find_functionname_in_history_section {
446    my $contents = shift;
447    my $functionname = shift;
448    my (undef, $rest) = split('=head1 HISTORY\s*', $contents);
449
450    if (not $rest) {
451        # No HISTORY section is a clear error now
452        return 0;
453    }
454    else {
455        my ($histsect, undef) = split('=head1 COPYRIGHT\s*', $rest);
456        if (index($histsect, $functionname) == -1) {
457            # OK, functionname is not in HISTORY section...
458            # last try: Check for presence of "*unction*added*"
459            return 0 if (not $histsect =~ /unction.*added.*/g);
460        }
461    }
462    return 1;
463}
464
465# Check if a =head1 is duplicated, or a =headX is duplicated within a
466# =head1.  Treats =head2 =head3 as equivalent -- it doesn't reset the head3
467# sets if it finds a =head2 -- but that is good enough for now. Also check
468# for proper capitalization, trailing periods, etc.
469sub check_head_style {
470    my $id = shift;
471    my $contents = shift;
472    my %head1;
473    my %subheads;
474
475    foreach my $line ( split /\n+/, $contents ) {
476        next unless $line =~ /^=head/;
477        if ( $line =~ /head1/ ) {
478            err($id, "Duplicate section $line")
479                if defined $head1{$line};
480            $head1{$line} = 1;
481            %subheads = ();
482        } else {
483            err($id, "Duplicate subsection $line")
484                if defined $subheads{$line};
485            $subheads{$line} = 1;
486        }
487        err($id, "Period in =head")
488            if $line =~ /\.[^\w]/ or $line =~ /\.$/;
489        err($id, "not all uppercase in =head1")
490            if $line =~ /head1.*[a-z]/;
491        err($id, "All uppercase in subhead")
492            if $line =~ /head[234][ A-Z0-9]+$/;
493    }
494}
495
496# Because we have options and symbols with extra markup, we need
497# to take that into account, so we need a regexp that extracts
498# markup chunks, including recursive markup.
499# please read up on /(?R)/ in perlre(1)
500# (note: order is important, (?R) needs to come before .)
501# (note: non-greedy is important, or something like 'B<foo> and B<bar>'
502# will be captured as one item)
503my $markup_re =
504    qr/(                        # Capture group
505           [BIL]<               # The start of what we recurse on
506           (?:(?-1)|.)*?        # recurse the whole regexp (referring to
507                                # the last opened capture group, i.e. the
508                                # start of this regexp), or pick next
509                                # character.  Do NOT be greedy!
510           >                    # The end of what we recurse on
511       )/x;                     # (the x allows this sort of split up regexp)
512
513# Options must start with a dash, followed by a letter, possibly
514# followed by letters, digits, dashes and underscores, and the last
515# character must be a letter or a digit.
516# We do also accept the single -? or -n, where n is a digit
517my $option_re =
518    qr/(?:
519            \?                  # Single question mark
520            |
521            \d                  # Single digit
522            |
523            -                   # Single dash (--)
524            |
525            [[:alpha:]](?:[-_[:alnum:]]*?[[:alnum:]])?
526       )/x;
527
528# Helper function to check if a given $thing is properly marked up
529# option.  It returns one of these values:
530#     undef         if it's not an option
531#     ""            if it's a malformed option
532#     $unwrapped    the option with the outermost B<> wrapping removed.
533sub normalise_option {
534    my $id = shift;
535    my $filename = shift;
536    my $thing = shift;
537
538    my $unwrapped = $thing;
539    my $unmarked = $thing;
540
541    # $unwrapped is the option with the outer B<> markup removed
542    $unwrapped =~ s/^B<//;
543    $unwrapped =~ s/>$//;
544    # $unmarked is the option with *all* markup removed
545    $unmarked =~ s/[BIL]<|>//msg;
546
547
548    # If we found an option, check it, collect it
549    if ( $unwrapped =~ /^\s*-/ ) {
550        return $unwrapped       # return option with outer B<> removed
551            if $unmarked =~ /^-${option_re}$/;
552        return "";              # Malformed option
553    }
554    return undef;               # Something else
555}
556
557# Checks of command option (man1) formatting.  The man1 checks are
558# restricted to the SYNOPSIS and OPTIONS sections, the rest is too
559# free form, we simply cannot be too strict there.
560
561sub option_check {
562    my $id = shift;
563    my $filename = shift;
564    my $contents = shift;
565    my $nodups = 1;
566
567    my $synopsis = ($contents =~ /=head1\s+SYNOPSIS(.*?)=head1/s, $1);
568    $nodups = 0 if $synopsis =~ /=for\s+openssl\s+duplicate\s+options/s;
569
570    # Some pages have more than one OPTIONS section, let's make sure
571    # to get them all
572    my $options = '';
573    while ( $contents =~ /=head1\s+[A-Z ]*?OPTIONS$(.*?)(?==head1)/msg ) {
574        $options .= $1;
575    }
576
577    # Look for options with no or incorrect markup
578    while ( $synopsis =~
579            /(?<![-<[:alnum:]])-(?:$markup_re|.)*(?![->[:alnum:]])/msg ) {
580        err($id, "Malformed option [1] in SYNOPSIS: $&");
581    }
582
583    my @synopsis;
584    my %listed;
585    while ( $synopsis =~ /$markup_re/msg ) {
586        my $found = $&;
587        push @synopsis, $found if $found =~ /^B<-/;
588        print STDERR "$id:DEBUG[option_check] SYNOPSIS: found $found\n"
589            if $debug;
590        my $option_uw = normalise_option($id, $filename, $found);
591        if ( defined $option_uw ) {
592            err($id, "Malformed option [2] in SYNOPSIS: $found")
593                if $option_uw eq '';
594            err($id, "Duplicate option in SYNOPSIS $option_uw\n")
595                if $nodups && defined $listed{$option_uw};
596            $listed{$option_uw} = 1;
597        }
598    }
599
600    # In OPTIONS, we look for =item paragraphs.
601    # (?=^\s*$) detects an empty line.
602    my @options;
603    my %described;
604    while ( $options =~ /=item\s+(.*?)(?=^\s*$)/msg ) {
605        my $item = $&;
606
607        while ( $item =~ /(\[\s*)?($markup_re)/msg ) {
608            my $found = $2;
609            print STDERR "$id:DEBUG[option_check] OPTIONS: found $&\n"
610                if $debug;
611            err($id, "Unexpected bracket in OPTIONS =item: $item")
612                if ($1 // '') ne '' && $found =~ /^B<\s*-/;
613
614            my $option_uw = normalise_option($id, $filename, $found);
615            if ( defined $option_uw ) {
616                err($id, "Malformed option in OPTIONS: $found")
617                    if $option_uw eq '';
618                err($id, "Duplicate option in OPTIONS $option_uw\n")
619                    if $nodups && defined $described{$option_uw};
620                $described{$option_uw} = 1;
621            }
622            if ($found =~ /^B<-/) {
623                push @options, $found;
624                err($id, "OPTIONS entry $found missing from SYNOPSIS")
625                    unless (grep /^\Q$found\E$/, @synopsis)
626                         || $id =~ /(openssl|-options)\.pod:1:$/;
627            }
628        }
629    }
630    foreach (@synopsis) {
631        my $option = $_;
632        err($id, "SYNOPSIS entry $option missing from OPTIONS")
633            unless (grep /^\Q$option\E$/, @options);
634    }
635}
636
637# Normal symbol form
638my $symbol_re = qr/[[:alpha:]_][_[:alnum:]]*?/;
639
640# Checks of function name (man3) formatting.  The man3 checks are
641# easier than the man1 checks, we only check the names followed by (),
642# and only the names that have POD markup.
643sub functionname_check {
644    my $id = shift;
645    my $filename = shift;
646    my $contents = shift;
647
648    while ( $contents =~ /($markup_re)\(\)/msg ) {
649        print STDERR "$id:DEBUG[functionname_check] SYNOPSIS: found $&\n"
650            if $debug;
651
652        my $symbol = $1;
653        my $unmarked = $symbol;
654        $unmarked =~ s/[BIL]<|>//msg;
655
656        err($id, "Malformed symbol: $symbol")
657            unless $symbol =~ /^B<.*?>$/ && $unmarked =~ /^${symbol_re}$/
658    }
659
660    # We can't do the kind of collecting coolness that option_check()
661    # does, because there are too many things that can't be found in
662    # name repositories like the NAME sections, such as symbol names
663    # with a variable part (typically marked up as B<foo_I<TYPE>_bar>
664}
665
666# This is from http://man7.org/linux/man-pages/man7/man-pages.7.html
667my %preferred_words = (
668    '16bit'         => '16-bit',
669    'a.k.a.'        => 'aka',
670    'bitmask'       => 'bit mask',
671    'builtin'       => 'built-in',
672   #'epoch'         => 'Epoch', # handled specially, below
673    'fall-back'     => 'fallback',
674    'file name'     => 'filename',
675    'file system'   => 'filesystem',
676    'host name'     => 'hostname',
677    'i-node'        => 'inode',
678    'lower case'    => 'lowercase',
679    'lower-case'    => 'lowercase',
680    'manpage'       => 'man page',
681    'non-blocking'  => 'nonblocking',
682    'non-default'   => 'nondefault',
683    'non-empty'     => 'nonempty',
684    'non-negative'  => 'nonnegative',
685    'non-zero'      => 'nonzero',
686    'path name'     => 'pathname',
687    'pre-allocated' => 'preallocated',
688    'pseudo-terminal' => 'pseudoterminal',
689    'real time'     => 'real-time',
690    'realtime'      => 'real-time',
691    'reserved port' => 'privileged port',
692    'runtime'       => 'run time',
693    'saved group ID'=> 'saved set-group-ID',
694    'saved set-GID' => 'saved set-group-ID',
695    'saved set-UID' => 'saved set-user-ID',
696    'saved user ID' => 'saved set-user-ID',
697    'set-GID'       => 'set-group-ID',
698    'set-UID'       => 'set-user-ID',
699    'setgid'        => 'set-group-ID',
700    'setuid'        => 'set-user-ID',
701    'sub-system'    => 'subsystem',
702    'super block'   => 'superblock',
703    'super-block'   => 'superblock',
704    'super user'    => 'superuser',
705    'super-user'    => 'superuser',
706    'system port'   => 'privileged port',
707    'time stamp'    => 'timestamp',
708    'time zone'     => 'timezone',
709    'upper case'    => 'uppercase',
710    'upper-case'    => 'uppercase',
711    'useable'       => 'usable',
712    'user name'     => 'username',
713    'userspace'     => 'user space',
714    'zeroes'        => 'zeros'
715);
716
717# Search manpage for words that have a different preferred use.
718sub wording {
719    my $id = shift;
720    my $contents = shift;
721
722    foreach my $k ( keys %preferred_words ) {
723        # Sigh, trademark
724        next if $k eq 'file system'
725            and $contents =~ /Microsoft Encrypted File System/;
726        err($id, "Found '$k' should use '$preferred_words{$k}'")
727            if $contents =~ /\b\Q$k\E\b/i;
728    }
729    err($id, "Found 'epoch' should use 'Epoch'")
730        if $contents =~ /\bepoch\b/;
731    if ( $id =~ m@man1/@ ) {
732        err($id, "found 'tool' in NAME, should use 'command'")
733            if $contents =~ /=head1 NAME.*\btool\b.*=head1 SYNOPSIS/s;
734        err($id, "found 'utility' in NAME, should use 'command'")
735            if $contents =~ /NAME.*\butility\b.*=head1 SYNOPSIS/s;
736
737    }
738}
739
740# Perform all sorts of nit/error checks on a manpage
741sub check {
742    my %podinfo = @_;
743    my $filename = $podinfo{filename};
744    my $dirname = basename(dirname($filename));
745    my $contents = $podinfo{contents};
746
747    # Find what section this page is in; presume 3.
748    my $mansect = 3;
749    $mansect = $1 if $filename =~ /man([1-9])/;
750
751    my $id = "${filename}:1:";
752    check_head_style($id, $contents);
753
754    # Check ordering of some sections in man3
755    if ( $mansect == 3 ) {
756        check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
757        check_section_location($id, $contents, "SEE ALSO", "HISTORY");
758        check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
759    }
760
761    # Make sure every link has a man section number.
762    while ( $contents =~ /$markup_re/msg ) {
763        my $target = $1;
764        next unless $target =~ /^L<(.*)>$/;     # Skip if not L<...>
765        $target = $1;                           # Peal away L< and >
766        $target =~ s/\/[^\/]*$//;               # Peal away possible anchor
767        $target =~ s/.*\|//g;                   # Peal away possible link text
768        next if $target eq '';                  # Skip if links within page, or
769        next if $target =~ /::/;                #   links to a Perl module, or
770        next if $target =~ /^https?:/;          #   is a URL link, or
771        next if $target =~ /\([1357]\)$/;       #   it has a section
772        err($id, "Missing man section number (likely, $mansect) in L<$target>")
773    }
774    # Check for proper links to commands.
775    while ( $contents =~ /L<([^>]*)\(1\)(?:\/.*)?>/g ) {
776        my $target = $1;
777        next if $target =~ /openssl-?/;
778        next if ( grep { basename($_) eq "$target.pod" }
779                  files(TAGS => [ 'manual', 'man1' ]) );
780        next if $target =~ /ps|apropos|sha1sum|procmail|perl/;
781        err($id, "Bad command link L<$target(1)>") if grep /man1/, @sections;
782    }
783    # Check for proper in-man-3 API links.
784    while ( $contents =~ /L<([^>]*)\(3\)(?:\/.*)?>/g ) {
785        my $target = $1;
786        err($id, "Bad L<$target>")
787            unless $target =~ /^[_[:alpha:]][_[:alnum:]]*$/
788    }
789
790    unless ( $contents =~ /^=for openssl generic/ms ) {
791        if ( $mansect == 3 ) {
792            name_synopsis($id, $filename, $contents);
793            functionname_check($id, $filename, $contents);
794        } elsif ( $mansect == 1 ) {
795            option_check($id, $filename, $contents)
796        }
797    }
798
799    wording($id, $contents);
800
801    err($id, "Doesn't start with =pod")
802        if $contents !~ /^=pod/;
803    err($id, "Doesn't end with =cut")
804        if $contents !~ /=cut\n$/;
805    err($id, "More than one cut line.")
806        if $contents =~ /=cut.*=cut/ms;
807    err($id, "EXAMPLE not EXAMPLES section.")
808        if $contents =~ /=head1 EXAMPLE[^S]/;
809    err($id, "WARNING not WARNINGS section.")
810        if $contents =~ /=head1 WARNING[^S]/;
811    err($id, "Missing copyright")
812        if $contents !~ /Copyright .* The OpenSSL Project Authors/;
813    err($id, "Copyright not last")
814        if $contents =~ /head1 COPYRIGHT.*=head/ms;
815    err($id, "head2 in All uppercase")
816        if $contents =~ /head2\s+[A-Z ]+\n/;
817    err($id, "Extra space after head")
818        if $contents =~ /=head\d\s\s+/;
819    err($id, "Period in NAME section")
820        if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms;
821    err($id, "Duplicate $1 in L<>")
822        if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2;
823    err($id, "Bad =over $1")
824        if $contents =~ /=over([^ ][^24])/;
825    err($id, "Possible version style issue")
826        if $contents =~ /OpenSSL version [019]/;
827
828    if ( $contents !~ /=for openssl multiple includes/ ) {
829        # Look for multiple consecutive openssl #include lines
830        # (non-consecutive lines are okay; see man3/MD5.pod).
831        if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
832            my $count = 0;
833            foreach my $line ( split /\n+/, $1 ) {
834                if ( $line =~ m@include <openssl/@ ) {
835                    err($id, "Has multiple includes")
836                        if ++$count == 2;
837                } else {
838                    $count = 0;
839                }
840            }
841        }
842    }
843
844    open my $OUT, '>', $temp
845        or die "Can't open $temp, $!";
846    err($id, "POD errors")
847        if podchecker($filename, $OUT) != 0;
848    close $OUT;
849    open $OUT, '<', $temp
850        or die "Can't read $temp, $!";
851    while ( <$OUT> ) {
852        next if /\(section\) in.*deprecated/;
853        print;
854    }
855    close $OUT;
856    unlink $temp || warn "Can't remove $temp, $!";
857
858    # Find what section this page is in; presume 3.
859    my $section = 3;
860    $section = $1 if $dirname =~ /man([1-9])/;
861
862    foreach ( (@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}}) ) {
863        err($id, "Missing $_ head1 section")
864            if $contents !~ /^=head1\s+${_}\s*$/m;
865    }
866}
867
868# Information database ###############################################
869
870# Map of links in each POD file; filename => [ "foo(1)", "bar(3)", ... ]
871my %link_map = ();
872# Map of names in each POD file or from "missing" files; possible values are:
873# If found in a POD files, "name(s)" => filename
874# If found in a "missing" file or external, "name(s)" => ''
875my %name_map = ();
876
877# State of man-page names.
878# %state is affected by loading util/*.num and util/*.syms
879# Values may be one of:
880# 'crypto' : belongs in libcrypto (loaded from libcrypto.num)
881# 'ssl' : belongs in libssl (loaded from libssl.num)
882# 'other' : belongs in libcrypto or libssl (loaded from other.syms)
883# 'internal' : Internal
884# 'public' : Public (generic name or external documentation)
885# Any of these values except 'public' may be prefixed with 'missing_'
886# to indicate that they are known to be missing.
887my %state;
888# history contains the same as state above for entries with version info != 3_0_0
889my %history;
890# %missing is affected by loading util/missing*.txt.  Values may be one of:
891# 'crypto' : belongs in libcrypto (loaded from libcrypto.num)
892# 'ssl' : belongs in libssl (loaded from libssl.num)
893# 'other' : belongs in libcrypto or libssl (loaded from other.syms)
894# 'internal' : Internal
895my %missing;
896
897# Parse libcrypto.num, etc., and return sorted list of what's there.
898sub loadnum ($;$) {
899    my $file = shift;
900    my $type = shift;
901    my @symbols;
902
903    open my $IN, '<', catfile($config{sourcedir}, $file)
904        or die "Can't open $file, $!, stopped";
905
906    while ( <$IN> ) {
907        next if /^#/;
908        next if /\bNOEXIST\b/;
909        my @fields = split();
910        if ($type && ($type eq "crypto" || $type eq "ssl")) {
911            # 3rd field is version
912            if (not $fields[2] eq "3_0_0") {
913                $history{$fields[0].'(3)'} = $type.$fields[2];
914            }
915        }
916        die "Malformed line $. in $file: $_"
917            if scalar @fields != 2 && scalar @fields != 4;
918        $state{$fields[0].'(3)'} = $type // 'internal';
919    }
920    close $IN;
921}
922
923# Load file of symbol names that we know aren't documented.
924sub loadmissing($;$)
925{
926    my $missingfile = shift;
927    my $type = shift;
928
929    open FH, catfile($config{sourcedir}, $missingfile)
930        or die "Can't open $missingfile";
931    while ( <FH> ) {
932        chomp;
933        next if /^#/;
934        $missing{$_} = $type // 'internal';
935    }
936    close FH;
937}
938
939# Check that we have consistent public / internal documentation and declaration
940sub checkstate () {
941    # Collect all known names, no matter where they come from
942    my %names = map { $_ => 1 } (keys %name_map, keys %state, keys %missing);
943
944    # Check section 3, i.e. functions and macros
945    foreach ( grep { $_ =~ /\(3\)$/ } sort keys %names ) {
946        next if ( $name_map{$_} // '') eq '' || $_ =~ /$ignored/;
947
948        # If a man-page isn't recorded public or if it's recorded missing
949        # and internal, it's declared to be internal.
950        my $declared_internal =
951            ($state{$_} // 'internal') eq 'internal'
952            || ($missing{$_} // '') eq 'internal';
953        # If a man-page isn't recorded internal or if it's recorded missing
954        # and not internal, it's declared to be public
955        my $declared_public =
956            ($state{$_} // 'internal') ne 'internal'
957            || ($missing{$_} // 'internal') ne 'internal';
958
959        err("$_ is supposedly public but is documented as internal")
960            if ( $declared_public && $name_map{$_} =~ /\/internal\// );
961        err("$_ is supposedly internal (maybe missing from other.syms) but is documented as public")
962            if ( $declared_internal && $name_map{$_} !~ /\/internal\// );
963    }
964}
965
966# Check for undocumented macros; ignore those in the "missing" file
967# and do simple check for #define in our header files.
968sub checkmacros {
969    my $count = 0;
970    my %seen;
971
972    foreach my $f ( files(TAGS => 'public_header') ) {
973        # Skip some internals we don't want to document yet.
974        my $b = basename($f);
975        next if $b eq 'asn1.h';
976        next if $b eq 'asn1t.h';
977        next if $b eq 'err.h';
978        open(IN, $f)
979            or die "Can't open $f, $!";
980        while ( <IN> ) {
981            next unless /^#\s*define\s*(\S+)\(/;
982            my $macro = "$1(3)"; # We know they're all in section 3
983            next if defined $name_map{$macro}
984                || defined $missing{$macro}
985                || defined $seen{$macro}
986                || $macro =~ /$ignored/;
987
988            err("$f:", "macro $macro undocumented")
989                if $opt_d || $opt_e;
990            $count++;
991            $seen{$macro} = 1;
992        }
993        close(IN);
994    }
995    err("# $count macros undocumented (count is approximate)")
996        if $count > 0;
997}
998
999# Find out what is undocumented (filtering out the known missing ones)
1000# and display them.
1001sub printem ($) {
1002    my $type = shift;
1003    my $count = 0;
1004
1005    foreach my $func ( grep { $state{$_} eq $type } sort keys %state ) {
1006        err("$type:", "function $func not in any history section")
1007            if ($opt_i && defined $history{$func});
1008        next if defined $name_map{$func}
1009            || defined $missing{$func};
1010
1011        err("$type:", "function $func undocumented")
1012            if $opt_d || $opt_e;
1013        $count++;
1014    }
1015    err("# $count lib$type names are not documented")
1016        if $count > 0;
1017}
1018
1019# Collect all the names in a manpage.
1020sub collectnames {
1021    my %podinfo = @_;
1022    my $filename = $podinfo{filename};
1023    $filename =~ m|man(\d)/|;
1024    my $section = $1;
1025    my $simplename = basename($filename, ".pod");
1026    my $id = "${filename}:1:";
1027    my $is_generic = $podinfo{contents} =~ /^=for openssl generic/ms;
1028
1029    unless ( grep { $simplename eq $_ } @{$podinfo{names}} ) {
1030        err($id, "$simplename not in NAME section");
1031        push @{$podinfo{names}}, $simplename;
1032    }
1033    foreach my $name ( @{$podinfo{names}} ) {
1034        next if $name eq "";
1035        err($id, "'$name' contains whitespace")
1036            if $name =~ /\s/;
1037        my $name_sec = "$name($section)";
1038        if ( !defined $name_map{$name_sec} ) {
1039            $name_map{$name_sec} = $filename;
1040            if ($history{$name_sec}) {
1041                my $funcname = $name_sec;
1042                my $contents = $podinfo{contents};
1043                $funcname =~ s/\(.*//;
1044                if (find_functionname_in_history_section($contents, $funcname)) {
1045                    # mark this function as found/no longer of interest
1046                    $history{$name_sec} = undef;
1047                }
1048            }
1049            $state{$name_sec} //=
1050                ( $filename =~ /\/internal\// ? 'internal' : 'public' )
1051                if $is_generic;
1052        } elsif ( $filename eq $name_map{$name_sec} ) {
1053            err($id, "$name_sec duplicated in NAME section of",
1054                 $name_map{$name_sec});
1055        } elsif ( $name_map{$name_sec} ne '' ) {
1056            err($id, "$name_sec also in NAME section of",
1057                 $name_map{$name_sec});
1058        }
1059    }
1060
1061    if ( $podinfo{contents} =~ /=for openssl foreign manual (.*)\n/ ) {
1062        foreach my $f ( split / /, $1 ) {
1063            $name_map{$f} = ''; # It still exists!
1064            $state{$f} = 'public'; # We assume!
1065        }
1066    }
1067
1068    my @links = ();
1069    # Don't use this regexp directly on $podinfo{contents}, as it causes
1070    # a regexp recursion, which fails on really big PODs.  Instead, use
1071    # $markup_re to pick up general markup, and use this regexp to check
1072    # that the markup that was found is indeed a link.
1073    my $linkre = qr/L<
1074                    # if the link is of the form L<something|name(s)>,
1075                    # then remove 'something'.  Note that 'something'
1076                    # may contain POD codes as well...
1077                    (?:(?:[^\|]|<[^>]*>)*\|)?
1078                    # we're only interested in references that have
1079                    # a one digit section number
1080                    ([^\/>\(]+\(\d\))
1081                   /x;
1082    while ( $podinfo{contents} =~ /$markup_re/msg ) {
1083        my $x = $1;
1084
1085        if ($x =~ $linkre) {
1086            push @links, $1;
1087        }
1088    }
1089    $link_map{$filename} = [ @links ];
1090}
1091
1092# Look for L<> ("link") references that point to files that do not exist.
1093sub checklinks {
1094    foreach my $filename ( sort keys %link_map ) {
1095        foreach my $link ( @{$link_map{$filename}} ) {
1096            err("${filename}:1:", "reference to non-existing $link")
1097                unless defined $name_map{$link} || defined $missing{$link};
1098            err("${filename}:1:", "reference of internal $link in public documentation $filename")
1099                if ( ( ($state{$link} // '') eq 'internal'
1100                       || ($missing{$link} // '') eq 'internal' )
1101                     && $filename !~ /\/internal\// );
1102        }
1103    }
1104}
1105
1106# Cipher/digests to skip if they show up as "not implemented"
1107# because they are, via the "-*" construct.
1108my %skips = (
1109    'aes128' => 1,
1110    'aes192' => 1,
1111    'aes256' => 1,
1112    'aria128' => 1,
1113    'aria192' => 1,
1114    'aria256' => 1,
1115    'camellia128' => 1,
1116    'camellia192' => 1,
1117    'camellia256' => 1,
1118    'des' => 1,
1119    'des3' => 1,
1120    'idea' => 1,
1121    'cipher' => 1,
1122    'digest' => 1,
1123);
1124
1125my %genopts; # generic options parsed from apps/include/opt.h
1126
1127# Check the flags of a command and see if everything is in the manpage
1128sub checkflags {
1129    my $cmd = shift;
1130    my $doc = shift;
1131    my @cmdopts;
1132    my %docopts;
1133
1134    # Get the list of options in the command source file.
1135    my $active = 0;
1136    my $expect_helpstr = "";
1137    open CFH, "apps/$cmd.c"
1138        or die "Can't open apps/$cmd.c to list options for $cmd, $!";
1139    while ( <CFH> ) {
1140        chop;
1141        if ($active) {
1142            last if m/^\s*};/;
1143            if ($expect_helpstr ne "") {
1144                next if m/^\s*#\s*if/;
1145                err("$cmd does not implement help for -$expect_helpstr") unless m/^\s*"/;
1146                $expect_helpstr = "";
1147            }
1148            if (m/\{\s*"([^"]+)"\s*,\s*OPT_[A-Z0-9_]+\s*,\s*('[-\/:<>cAEfFlMnNpsuU]'|0)(.*)$/
1149                    && !($cmd eq "s_client" && $1 eq "wdebug")) {
1150                push @cmdopts, $1;
1151                $expect_helpstr = $1;
1152                $expect_helpstr = "" if $3 =~ m/^\s*,\s*"/;
1153            } elsif (m/[\s,](OPT_[A-Z]+_OPTIONS?)\s*(,|$)/) {
1154                push @cmdopts, @{ $genopts{$1} };
1155            }
1156        } elsif (m/^const\s+OPTIONS\s*/) {
1157            $active = 1;
1158        }
1159    }
1160    close CFH;
1161
1162    # Get the list of flags from the synopsis
1163    open CFH, "<$doc"
1164        or die "Can't open $doc, $!";
1165    while ( <CFH> ) {
1166        chop;
1167        last if /DESCRIPTION/;
1168        my $opt;
1169        if ( /\[B<-([^ >]+)/ ) {
1170            $opt = $1;
1171        } elsif ( /^B<-([^ >]+)/ ) {
1172            $opt = $1;
1173        } else {
1174            next;
1175        }
1176        $opt = $1 if $opt =~ /I<(.*)/;
1177        $docopts{$1} = 1;
1178    }
1179    close CFH;
1180
1181    # See what's in the command not the manpage.
1182    my @undocced = sort grep { !defined $docopts{$_} } @cmdopts;
1183    foreach ( @undocced ) {
1184        err("$doc: undocumented $cmd option -$_");
1185    }
1186
1187    # See what's in the manpage not the command.
1188    my @unimpl = sort grep { my $e = $_; !(grep /^\Q$e\E$/, @cmdopts) } keys %docopts;
1189    foreach ( @unimpl ) {
1190        next if $_ eq "-"; # Skip the -- end-of-flags marker
1191        next if defined $skips{$_};
1192        err("$doc: $cmd does not implement -$_");
1193    }
1194}
1195
1196##
1197##  MAIN()
1198##  Do the work requested by the various getopt flags.
1199##  The flags are parsed in alphabetical order, just because we have
1200##  to have *some way* of listing them.
1201##
1202
1203if ( $opt_c ) {
1204    my @commands = ();
1205
1206    # Get the lists of generic options.
1207    my $active = "";
1208    open OFH, catdir($config{sourcedir}, "apps/include/opt.h")
1209        or die "Can't open apps/include/opt.h to list generic options, $!";
1210    while ( <OFH> ) {
1211        chop;
1212        push @{ $genopts{$active} }, $1 if $active ne "" && m/^\s+\{\s*"([^"]+)"\s*,\s*OPT_/;
1213        $active = $1 if m/^\s*#\s*define\s+(OPT_[A-Z]+_OPTIONS?)\s*\\\s*$/;
1214        $active = "" if m/^\s*$/;
1215    }
1216    close OFH;
1217
1218    # Get list of commands.
1219    opendir(DIR, "apps");
1220    @commands = grep(/\.c$/, readdir(DIR));
1221    closedir(DIR);
1222
1223    # See if each has a manpage.
1224    foreach my $cmd ( @commands ) {
1225        $cmd =~ s/\.c$//;
1226        next if $cmd eq 'progs' || $cmd eq 'vms_decc_init';
1227        my @doc = ( grep { basename($_) eq "openssl-$cmd.pod"
1228                           # For "tsget" and "CA.pl" pod pages
1229                           || basename($_) eq "$cmd.pod" }
1230                    files(TAGS => [ 'manual', 'man1' ]) );
1231        my $num = scalar @doc;
1232        if ($num > 1) {
1233            err("$num manuals for 'openssl $cmd': ".join(", ", @doc));
1234        } elsif ($num < 1) {
1235            err("no manual for 'openssl $cmd'");
1236        } else {
1237            checkflags($cmd, @doc);
1238        }
1239    }
1240}
1241
1242# Populate %state
1243loadnum('util/libcrypto.num', 'crypto');
1244loadnum('util/libssl.num', 'ssl');
1245loadnum('util/other.syms', 'other');
1246loadnum('util/other-internal.syms');
1247if ( $opt_o ) {
1248    loadmissing('util/missingmacro111.txt', 'crypto');
1249    loadmissing('util/missingcrypto111.txt', 'crypto');
1250    loadmissing('util/missingssl111.txt', 'ssl');
1251} elsif ( !$opt_u ) {
1252    loadmissing('util/missingmacro.txt', 'crypto');
1253    loadmissing('util/missingcrypto.txt', 'crypto');
1254    loadmissing('util/missingssl.txt', 'ssl');
1255    loadmissing('util/missingcrypto-internal.txt');
1256    loadmissing('util/missingssl-internal.txt');
1257}
1258
1259if ( $opt_n || $opt_l || $opt_u || $opt_v ) {
1260    my @files_to_read = ( $opt_n && @ARGV ) ? @ARGV : files(TAGS => 'manual');
1261
1262    foreach (@files_to_read) {
1263        my %podinfo = extract_pod_info($_, { debug => $debug });
1264
1265        collectnames(%podinfo)
1266            if ( $opt_l || $opt_u || $opt_v );
1267
1268        check(%podinfo)
1269            if ( $opt_n );
1270    }
1271}
1272
1273if ( $opt_l ) {
1274    checklinks();
1275}
1276
1277if ( $opt_n ) {
1278    # If not given args, check that all man1 commands are named properly.
1279    if ( scalar @ARGV == 0 && grep /man1/, @sections ) {
1280        foreach ( files(TAGS => [ 'public_manual', 'man1' ]) ) {
1281            next if /openssl\.pod/
1282                || /CA\.pl/ || /tsget\.pod/; # these commands are special cases
1283            err("$_ doesn't start with openssl-") unless /openssl-/;
1284        }
1285    }
1286}
1287
1288checkstate();
1289
1290if ( $opt_u || $opt_v) {
1291    printem('crypto');
1292    printem('ssl');
1293    checkmacros();
1294}
1295
1296exit $status;
1297