opt-docs: verify man page sections + order

In every libcurl option man page there are now 8 mandatory sections that
must use the right name in the correct order and test 1173 verifies
this. Only 14 man pages needed adjustments.

The sections and the order is as follows:

 - NAME
 - SYNOPSIS
 - DESCRIPTION
 - PROTOCOLS
 - EXAMPLE
 - AVAILABILITY
 - RETURN VALUE
 - SEE ALSO

Reviewed-by: Daniel Gustafsson
Closes #7656

1 files changed, 68 insertions, 5 deletions

diff --git a/tests/manpage-syntax.pl b/tests/manpage-syntax.pl
index 5a3bcec0d..1609ba220 100644
--- a/tests/manpage-syntax.pl
+++ b/tests/manpage-syntax.pl
@@ -32,11 +32,27 @@ use warnings;
 my @manpages=@ARGV;
 my $errors = 0;
 
+my %blessed;
+my @order = (
+    'NAME',
+    'SYNOPSIS',
+    'DESCRIPTION',
+     #'DEFAULT', # CURLINFO_ has no default
+    'PROTOCOLS',
+    'EXAMPLE',
+    'AVAILABILITY',
+    'RETURN VALUE',
+    'SEE ALSO'
+    );
+my %shline; # section => line number
+
 sub scanmanpage {
     my ($file) = @_;
     my $reqex = 0;
     my $inex = 0;
     my $exsize = 0;
+    my $shc = 0;
+    my @sh;
 
     print "Check $file\n";
     open(M, "<$file") || die "no such file: $file";
@@ -46,15 +62,22 @@ sub scanmanpage {
     }
     my $line = 1;
     while(<M>) {
-        if($_ =~ /^.SH EXAMPLE/) {
+        if($_ =~ /^.SH EXAMPLE/i) {
             $inex = 1;
         }
-        elsif($_ =~ /^.SH/) {
+        elsif($_ =~ /^.SH/i) {
             $inex = 0;
         }
         elsif($inex)  {
             $exsize++;
         }
+        if($_ =~ /^.SH (.*)/i) {
+            my $n = $1;
+            # remove enclosing quotes
+            $n =~ s/\"(.*)\"\z/$1/;
+            push @sh, $n;
+            $shline{$n} = $line;
+        }
 
         if($_ =~ /^\'/) {
             print STDERR "$file:$line line starts with single quote!\n";
@@ -75,12 +98,52 @@ sub scanmanpage {
     }
     close(M);
 
-    if($reqex && ($exsize < 2)) {
-        print STDERR "$file:$line missing EXAMPLE section\n";
-        $errors++;
+    if($reqex) {
+        # only for libcurl options man-pages
+
+        if($exsize < 2) {
+            print STDERR "$file:$line missing EXAMPLE section\n";
+            $errors++;
+        }
+
+        my $got;
+        my $i = 0;
+        my $shused = 1;
+        do {
+            $got = shift(@sh);
+            if($got) {
+                $i = $blessed{$got};
+            }
+            if($i && $got) {
+                # mandatory section
+
+                if($i != $shused) {
+                    printf STDERR "$file:%u Got $got, when %s was expected\n",
+                        $shline{$got},
+                        $order[$shused-1];
+                    $errors++;
+                    return;
+                }
+                $shused++;
+                if($i == 9) {
+                    # last mandatory one, exit
+                    $got="";
+                }
+            }
+        } while($got);
+
+        if($i != 8) {
+            printf STDERR "$file:$line missing mandatory section: %s\n",
+                $order[$i];
+            $errors++;
+        }
     }
 }
 
+my $ind = 1;
+for my $s (@order) {
+    $blessed{$s} = $ind++
+}
 
 for my $m (@manpages) {
     scanmanpage($m);