Do not have duplicate section heads

Change find-doc-nits to complain if a section header is repeated,
within a parent header (i.e., duplicate =head2 within a =head1).
In almost all cases, we just remove the duplicate header, as
it was a "continuation" of the =head1 that was already in affect.
In some cases, just remove "=head1 NOTES", possibly moving text
around, because the "NOTES" were really important parts of the
DESCRIPTION section.

No =headX sections should end with a period.
All =head1 labels should be in all uppercase.
No sub-head (=head2, etc) should be in all uppercase.
Update find-doc-nits to reject the above.

Fixup an internal POD link

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Paul Yang <kaishen.yy@antfin.com>
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9631)

1 files changed, 36 insertions, 3 deletions

diff --git a/util/find-doc-nits b/util/find-doc-nits
index 1b9a2333a3..9126e73586 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -159,12 +159,44 @@ sub check_section_location()
     my $section = shift;
     my $before = shift;
 
-    return
-        unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/;
-    print "$id $section should be placed before $before section\n"
+    return unless $contents =~ /=head1 $section/
+        and $contents =~ /=head1 $before/;
+    print "$id $section should appear before $before section\n"
         if $contents =~ /=head1 $before.*=head1 $section/ms;
 }
 
+# Check if a =head1 is duplicated, or a =headX is duplicated within a
+# =head1.  Treats =head2 =head3 as equivalent -- it doesn't reset the head3
+# sets if it finds a =head2 -- but that is good enough for now. Also check
+# for proper capitalization, trailing periods, etc.
+sub check_head_style()
+{
+    my $id = shift;
+    my $contents = shift;
+    my %head1;
+    my %subheads;
+
+    foreach my $line ( split /\n+/, $contents ) {
+        next unless $line =~ /^=head/;
+        if ( $line =~ /head1/ ) {
+            print "$id duplicate section $line\n"
+                if defined $head1{$line};
+            $head1{$line} = 1;
+            %subheads = ();
+        } else {
+            print "$id duplicate subsection $line\n"
+                if defined $subheads{$line};
+            $subheads{$line} = 1;
+        }
+        print "$id period in =head\n"
+            if $line =~ /\.[^\w]/ or $line =~ /\.$/;
+        print "$id not all uppercase in =head1\n"
+            if $line =~ /head1.*[a-z]/;
+        print "$id all uppercase in subhead\n"
+            if $line =~ /head[234][ A-Z0-9]+$/;
+    }
+}
+
 sub check()
 {
     my $filename = shift;
@@ -179,6 +211,7 @@ sub check()
     }
 
     my $id = "${filename}:1:";
+    &check_head_style($id, $contents);
 
     # Check ordering of some sections in man3
     if ( $filename =~ m|man3/| ) {