Make check_example_location() in find-doc-nits generic

Change to check_section_location(), a generic function to ensure that
section SECTION appears before section BEFORE in the man pages.

Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(cherry picked from commit 95f92d57755a9bfc83135a585da69d497f7293d9)

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

diff --git a/util/find-doc-nits b/util/find-doc-nits
index deae76ce0f102cc02e1a424c7798a72a2a5f8d3c..da629194544c22aa7ca768196a976cc96c1e2526 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,5 +1,5 @@
 #! /usr/bin/env perl
-# Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 2002-2019 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
@@ -137,16 +137,18 @@ sub name_synopsis()
     }
 }
 
-# Check if EXAMPLES is located after RETURN VALUES section.
-sub check_example_location()
+# Check if SECTION is located before BEFORE
+sub check_section_location()
 {
     my $filename = shift;
     my $contents = shift;
+    my $section = shift;
+    my $before = shift;
 
-    return unless $contents =~ /=head1 RETURN VALUES/
-        and $contents =~ /=head1 EXAMPLES/;
-    print "$filename: RETURN VAULES should be placed before EXAMPLES section\n"
-        if $contents =~ /=head1 EXAMPLES.*=head1 RETURN VALUES/ms;
+    return unless $contents =~ /=head1 $section/
+        and $contents =~ /=head1 $before/;
+    print "$filename: $section should be placed before $before section\n"
+        if $contents =~ /=head1 $before.*=head1 $section/ms;
 }
 
 sub check()
@@ -162,7 +164,8 @@ sub check()
         close POD;
     }
 
-    &check_example_location($filename, $contents) if $filename =~ m|man3/|;
+    # Check if EXAMPLES is located after RETURN VALUES section.
+    &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
 
     my $id = "${filename}:1:";