manpage-syntax.pl: verify SEE ALSO syntax

- Enforce a single reference per .BR line
- Skip the quotes around the section number for example (3)
- Insist on trailing commas on all lines except the last
- Error on comma on the last SEE ALSO entry

- List the entries alpha-sorted, not enforced just recommended

Closes #11957

tests/manpage-syntax.pl

@@ -93,6 +93,7 @@ sub allsymbols {
 sub scanmanpage {
     my ($file) = @_;
     my $reqex = 0;
+    my $inseealso = 0;
     my $inex = 0;
     my $insynop = 0;
     my $exsize = 0;
@@ -101,6 +102,8 @@ sub scanmanpage {
     my $optpage = 0; # option or function
     my @sh;
     my $SH="";
+    my @separators;
+    my @sepline;
 
     open(my $m, "<", "$file") || die "no such file: $file";
     if($file =~ /[\/\\](CURL|curl_)[^\/\\]*.3/) {
@@ -127,10 +130,40 @@ sub scanmanpage {
             $insynop = 0;
             $inex = 1;
         }
+        elsif($_ =~ /^\.SH \"SEE ALSO\"/i) {
+            $inseealso = 1;
+        }
         elsif($_ =~ /^\.SH/i) {
             $insynop = 0;
             $inex = 0;
         }
+        elsif($inseealso) {
+            if($_ =~ /^\.BR (.*)/i) {
+                my $f = $1;
+                if($f =~ /^(lib|)curl/i) {
+                    $f =~ s/[\n\r]//g;
+                    if($f =~ s/([a-z_0-9-]*) \([13]\)([, ]*)//i) {
+                        push @separators, $2;
+                        push @sepline, $line;
+
+                    }
+                    if($f !~ /^ *$/) {
+                        print STDERR "$file:$line bad SEE ALSO format\n";
+                        $errors++;
+                    }
+                }
+                else {
+                    if($f =~ /.*(, *)\z/) {
+                        push @separators, $1;
+                        push @sepline, $line;
+                    }
+                    else {
+                        push @separators, " ";
+                        push @sepline, $line;
+                    }
+                }
+            }
+        }
         elsif($inex)  {
             $exsize++;
             if($_ =~ /[^\\]\\n/) {
@@ -202,6 +235,26 @@ sub scanmanpage {
     }
     close($m);
 
+    if(@separators) {
+        # all except the last one need comma
+        for(0 .. $#separators - 1) {
+            my $l = $_;
+            my $sep = $separators[$l];
+            if($sep ne ",") {
+                printf STDERR "$file:%d: bad not-last SEE ALSO separator: '%s'\n",
+                    $sepline[$l], $sep;
+                $errors++;
+            }
+        }
+        # the last one should not do comma
+        my $sep = $separators[$#separators];
+        if($sep eq ",") {
+            printf STDERR "$file:%d: superfluous comma separator\n",
+                $sepline[$#separators];
+            $errors++;
+        }
+    }
+
     if($reqex) {
         # only for libcurl options man-pages