util/find-doc-nits: fixups

- Treat .pod.in files as well, and parse out the base name for those
  too.
- Correct the detection of the description part in the NAME section
  (the separating dash MUST be preceeded with a space)
- Allow slahes in names of the NAME section (convert them to dashes
  for file name comparison).  This allows manual pages for some of our
  header files, such as openssl/core.h.
- Properly detect repeated names in the NAME section.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9407)

diff --git a/util/find-doc-nits b/util/find-doc-nits
index ecd9f9af5174aab7a0e3ac093ac2ce241f389434..499a68fdc4042465d3465f24e74e461db6add04d 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -79,8 +79,7 @@ sub name_synopsis()
     print "$id missing comma in NAME\n" if $tmp =~ /[^,] /;
 
     my $dirname = dirname($filename);
     print "$id missing comma in NAME\n" if $tmp =~ /[^,] /;
 
     my $dirname = dirname($filename);

-    my $simplename = basename($filename);
-    $simplename =~ s/.pod$//;
+    my $simplename = basename(basename($filename, ".in"), ".pod");

     my $foundfilename = 0;
     my %foundfilenames = ();
     my %names;
     my $foundfilename = 0;
     my %foundfilenames = ();
     my %names;


@@ -92,9 +91,10 @@ sub name_synopsis()
         $names{$n} = 1;
         $foundfilename++ if $n eq $simplename;
         $foundfilenames{$n} = 1
         $names{$n} = 1;
         $foundfilename++ if $n eq $simplename;
         $foundfilenames{$n} = 1

-            if -f "$dirname/$n.pod" && $n ne $simplename;
+            if ((-f "$dirname/$n.pod.in" || -f "$dirname/$n.pod")
+                && $n ne $simplename);

     }
     }

-    print "$id the following exist as other .pod files:\n",
+    print "$id the following exist as other .pod or .pod.in files:\n",

         join(" ", sort keys %foundfilenames), "\n"
         if %foundfilenames;
     print "$id $simplename (filename) missing from NAME section\n"
         join(" ", sort keys %foundfilenames), "\n"
         if %foundfilenames;
     print "$id $simplename (filename) missing from NAME section\n"


@@ -283,7 +283,7 @@ sub getdocced
     my $dir = shift;
     my %return;
 
     my $dir = shift;
     my %return;
 

-    foreach my $pod ( glob("$dir/*.pod") ) {
+    foreach my $pod ( glob("$dir/*.pod"), glob("$dir/*.pod.in") ) {

         my %podinfo = extract_pod_info($pod);
         foreach my $n ( @{$podinfo{names}} ) {
             $return{$n} = $pod;
         my %podinfo = extract_pod_info($pod);
         foreach my $n ( @{$podinfo{names}} ) {
             $return{$n} = $pod;


@@ -394,7 +394,7 @@ sub collectnames {
     my $filename = shift;
     $filename =~ m|man(\d)/|;
     my $section = $1;
     my $filename = shift;
     $filename =~ m|man(\d)/|;
     my $section = $1;

-    my $simplename = basename($filename, ".pod");
+    my $simplename = basename(basename($filename, ".in"), ".pod");

     my $id = "${filename}:1:";
 
     my $contents = '';
     my $id = "${filename}:1:";
 
     my $contents = '';


@@ -412,9 +412,12 @@ sub collectnames {
         return;
     }
     $tmp =~ tr/\n/ /;
         return;
     }
     $tmp =~ tr/\n/ /;

-    $tmp =~ s/-.*//g;
+    $tmp =~ s/ -.*//g;

 
 

-    my @names = map { s/^\s+//g; s/\s+$//g; $_ } split(/,/, $tmp);
+    my @names =
+        map { s|/|-|g; $_ }              # Treat slash as dash
+        map { s/^\s+//g; s/\s+$//g; $_ } # Trim prefix and suffix blanks
+        split(/,/, $tmp);

     unless (grep { $simplename eq $_ } @names) {
         print "$id missing $simplename\n";
         push @names, $simplename;
     unless (grep { $simplename eq $_ } @names) {
         print "$id missing $simplename\n";
         push @names, $simplename;


@@ -427,8 +430,10 @@ sub collectnames {
         my $name_sec = "$name($section)";
         if (! exists $name_collection{$name_sec}) {
             $name_collection{$name_sec} = $filename;
         my $name_sec = "$name($section)";
         if (! exists $name_collection{$name_sec}) {
             $name_collection{$name_sec} = $filename;

-        } else { #elsif ($filename ne $name_collection{$name_sec}) {
-            print "$id $name_sec also in $name_collection{$name_sec}\n";
+        } elsif ($filename eq $name_collection{$name_sec}) {
+            print "$id $name_sec repeated in NAME section of $name_collection{$name_sec}\n"
+        } else {
+            print "$id $name_sec also in NAME section of $name_collection{$name_sec}\n";

         }
     }
 
         }
     }
 


@@ -600,7 +605,7 @@ if ( $opt_c ) {
 }
 
 if ( $opt_l ) {
 }
 
 if ( $opt_l ) {

-    foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'),
+    foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'), glob('doc/*/*.pod.in'),

                               glob('doc/internal/*/*.pod'))) {
         collectnames($_);
     }
                               glob('doc/internal/*/*.pod'))) {
         collectnames($_);
     }


@@ -609,7 +614,7 @@ if ( $opt_l ) {
 
 if ( $opt_n ) {
     &publicize() if $opt_p;
 
 if ( $opt_n ) {
     &publicize() if $opt_p;

-    foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
+    foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'), glob('doc/*/*.pod.in'))) {

         &check($_);
     }
     {
         &check($_);
     }
     {