Update configurable sigalgs documentation for providers

[openssl.git] / util / find-doc-nits

diff --git a/util/find-doc-nits b/util/find-doc-nits
index 7498ac6865a11b066c9e8549671b7b584f275d85..7d1cdb59b1dbd6e1845200237ffe5d6bed48fb51 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,5 +1,5 @@
 #! /usr/bin/env perl
-# Copyright 2002-2021 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
 #
 # Licensed under the Apache License 2.0 (the "License").  You may not use
 # this file except in compliance with the License.  You can obtain a copy
@@ -86,10 +86,10 @@ die "Argument of -m option may contain only man1, man3, man5, and/or man7"
 my @sections = ( split /[, ]/, $opt_m );
 
 my %mandatory_sections = (
-    '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
-    1   => [ 'SYNOPSIS', 'OPTIONS' ],
-    3   => [ 'SYNOPSIS', 'RETURN VALUES' ],
-    5   => [ ],
+    '*' => [ 'NAME', 'COPYRIGHT' ],
+    1   => [ 'DESCRIPTION', 'SYNOPSIS', 'OPTIONS' ],
+    3   => [ 'DESCRIPTION', 'SYNOPSIS', 'RETURN VALUES' ],
+    5   => [ 'DESCRIPTION' ],
     7   => [ ]
                          );
 
@@ -105,7 +105,7 @@ my $ignored = qr/(?| ^i2d_
                  |   ^sk_
                  |   ^SKM_DEFINE_STACK_OF_INTERNAL
                  |   ^lh_
-                 |   ^DEFINE_LHASH_OF_INTERNAL
+                 |   ^DEFINE_LHASH_OF_(INTERNAL|DEPRECATED)
                  )/x;
 
 # A common regexp for C symbol names
@@ -701,17 +701,21 @@ sub check {
     my $dirname = basename(dirname($filename));
     my $contents = $podinfo{contents};
 
+    # Find what section this page is in; presume 3.
+    my $mansect = 3;
+    $mansect = $1 if $filename =~ /man([1-9])/;
+
     my $id = "${filename}:1:";
     check_head_style($id, $contents);
 
     # Check ordering of some sections in man3
-    if ( $filename =~ m|man3/| ) {
+    if ( $mansect == 3 ) {
         check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
         check_section_location($id, $contents, "SEE ALSO", "HISTORY");
         check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
     }
 
-    # Make sure every link has a section.
+    # Make sure every link has a man section number.
     while ( $contents =~ /$markup_re/msg ) {
         my $target = $1;
         next unless $target =~ /^L<(.*)>$/;     # Skip if not L<...>
@@ -722,7 +726,7 @@ sub check {
         next if $target =~ /::/;                #   links to a Perl module, or
         next if $target =~ /^https?:/;          #   is a URL link, or
         next if $target =~ /\([1357]\)$/;       #   it has a section
-        err($id, "Section missing in $target")
+        err($id, "Missing man section number (likely, $mansect) in L<$target>")
     }
     # Check for proper links to commands.
     while ( $contents =~ /L<([^>]*)\(1\)(?:\/.*)?>/g ) {
@@ -730,7 +734,6 @@ sub check {
         next if $target =~ /openssl-?/;
         next if ( grep { basename($_) eq "$target.pod" }
                   files(TAGS => [ 'manual', 'man1' ]) );
-        # TODO: Filter out "foreign manual" links.
         next if $target =~ /ps|apropos|sha1sum|procmail|perl/;
         err($id, "Bad command link L<$target(1)>") if grep /man1/, @sections;
     }
@@ -742,10 +745,10 @@ sub check {
     }
 
     unless ( $contents =~ /^=for openssl generic/ms ) {
-        if ( $filename =~ m|man3/| ) {
+        if ( $mansect == 3 ) {
             name_synopsis($id, $filename, $contents);
             functionname_check($id, $filename, $contents);
-        } elsif ( $filename =~ m|man1/| ) {
+        } elsif ( $mansect == 1 ) {
             option_check($id, $filename, $contents)
         }
     }
@@ -809,7 +812,7 @@ sub check {
     close $OUT;
     unlink $temp || warn "Can't remove $temp, $!";
 
-    # Find what section this page is in; assume 3.
+    # Find what section this page is in; presume 3.
     my $section = 3;
     $section = $1 if $dirname =~ /man([1-9])/;
 
@@ -1080,7 +1083,7 @@ sub checkflags {
                 err("$cmd does not implement help for -$expect_helpstr") unless m/^\s*"/;
                 $expect_helpstr = "";
             }
-            if (m/\{\s*"([^"]+)"\s*,\s*OPT_[A-Z0-9_]+\s*,\s*('[-\/:<>cEfFlMnNpsuU]'|0)(.*)$/
+            if (m/\{\s*"([^"]+)"\s*,\s*OPT_[A-Z0-9_]+\s*,\s*('[-\/:<>cAEfFlMnNpsuU]'|0)(.*)$/
                     && !($cmd eq "s_client" && $1 eq "wdebug")) {
                 push @cmdopts, $1;
                 $expect_helpstr = $1;
@@ -1119,7 +1122,7 @@ sub checkflags {
         err("$doc: undocumented $cmd option -$_");
     }
 
-    # See what's in the command not the manpage.
+    # See what's in the manpage not the command.
     my @unimpl = sort grep { my $e = $_; !(grep /^\Q$e\E$/, @cmdopts) } keys %docopts;
     foreach ( @unimpl ) {
         next if $_ eq "-"; # Skip the -- end-of-flags marker
@@ -1140,7 +1143,7 @@ if ( $opt_c ) {
 
     # Get the lists of generic options.
     my $active = "";
-    open OFH, "apps/include/opt.h"
+    open OFH, catdir($config{sourcedir}, "apps/include/opt.h")
         or die "Can't open apps/include/opt.h to list generic options, $!";
     while ( <OFH> ) {
         chop;