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>
(Merged from https://github.com/openssl/openssl/pull/8729)

diff --git a/util/find-doc-nits b/util/find-doc-nits
index 5d5c2d05b2790fe4ade677e2cd2d18fbf68bb8bb..1957eeb7a1aef757ab27c63e785e0ec670f7a4fa 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,5 +1,5 @@
 #! /usr/bin/env perl
 #! /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 Apache License 2.0 (the "License").  You may not use
 # this file except in compliance with the License.  You can obtain a copy
 #
 # 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


@@ -142,16 +142,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 $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()
 }
 
 sub check()


@@ -167,7 +169,8 @@ sub check()
         close POD;
     }
 
         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:";
 
 
     my $id = "${filename}:1:";