manpage-syntax: verify curl man page references

1. References to curl symbols are now checked that they indeed exist as
   man pages. This for \f references as well as the names referenced in the
   SEE ALSO section.

   Allowlist curl.1 since it is not always built in builds

2. References to curl symbols that lack section now causes warning, since that
   will prevent them from getting linked properly

3. Check for "bare" references to curl functions and warn, they should be
   references

Closes #11963

tests/manpage-syntax.pl

@@ -29,6 +29,7 @@
 
 use strict;
 use warnings;
+use File::Basename;
 
 # get the file name first
 my $symbolsinversions=shift @ARGV;
@@ -37,6 +38,7 @@ my $symbolsinversions=shift @ARGV;
 my @manpages=@ARGV;
 my $errors = 0;
 
+my %docsdirs;
 my %optblessed;
 my %funcblessed;
 my @optorder = (
@@ -90,6 +92,31 @@ sub allsymbols {
     close($f);
 }
 
+
+my %ref = (
+    'curl.1' => 1
+    );
+sub checkref {
+    my ($f, $sec, $file, $line)=@_;
+    my $present = 0;
+    #print STDERR "check $f.$sec\n";
+    if($ref{"$f.$sec"}) {
+        # present
+        return;
+    }
+    foreach my $d (keys %docsdirs) {
+        if( -f "$d/$f.$sec") {
+            $present = 1;
+            $ref{"$f.$sec"}=1;
+            last;
+        }
+    }
+    if(!$present) {
+        print STDERR "$file:$line broken reference to $f($sec)\n";
+        $errors++;
+    }
+}
+
 sub scanmanpage {
     my ($file) = @_;
     my $reqex = 0;
@@ -142,10 +169,10 @@ sub scanmanpage {
                 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;
+                    if($f =~ s/([a-z_0-9-]*) \(([13])\)([, ]*)//i) {
+                        push @separators, $3;
                         push @sepline, $line;
-
+                        checkref($1, $2, $file, $line);
                     }
                     if($f !~ /^ *$/) {
                         print STDERR "$file:$line bad SEE ALSO format\n";
@@ -196,6 +223,15 @@ sub scanmanpage {
                 $errors++;
             }
         }
+        my $c = $_;
+        while($c =~ s/\\f([BI])((lib|)curl[a-z_0-9-]*)\(([13])\)//i) {
+            checkref($2, $4, $file, $line);
+        }
+        if(($_ =~ /\\f([BI])((libcurl|CURLOPT_|CURLSHOPT_|CURLINFO_|CURLMOPT_|curl_easy_|curl_multi_|curl_url|curl_mime|curl_global|curl_share)[a-zA-Z_0-9-]+)(.)/) &&
+           ($4 ne "(")) {
+            print STDERR "$file:$line curl ref to $2 without section\n";
+            $errors++;
+        }
         if($_ =~ /(.*)\\f([^BIP])/) {
             my ($pre, $format) = ($1, $2);
             if($pre !~ /\\\z/) {
@@ -204,8 +240,16 @@ sub scanmanpage {
                 $errors++;
             }
         }
+        if(($SH =~ /^(DESCRIPTION|RETURN VALUE|AVAILABILITY)/i) &&
+           ($_ =~ /(.*)((curl_multi|curl_easy|curl_url|curl_global|curl_url|curl_share)[a-zA-Z_0-9-]+)/) &&
+           ($1 !~ /\\fI$/)) {
+            print STDERR "$file:$line unrefed curl call: $2\n";
+            $errors++;
+        }
+
+
         if($optpage && $SH && ($SH !~ /^(SYNOPSIS|EXAMPLE|NAME|SEE ALSO)/i) &&
-           ($_ =~ /(.*)(CURL(OPT_|MOPT_|INFO_)[A-Z0-9_]*)/)) {
+           ($_ =~ /(.*)(CURL(OPT_|MOPT_|INFO_|SHOPT_)[A-Z0-9_]*)/)) {
             # an option with its own man page, check that it is tagged
             # for linking
             my ($pref, $symbol) = ($1, $2);
@@ -221,16 +265,6 @@ sub scanmanpage {
             print STDERR "$file:$line trailing whitespace\n";
             $errors++;
         }
-        if($_ =~ /\\f([BI])([^\\]*)\\fP/) {
-            my $r = $2;
-            if($r =~ /^(CURL.*)\(3\)/) {
-                my $rr = $1;
-                if(!$symbol{$rr}) {
-                    print STDERR "$file:$line link to non-libcurl option $rr!\n";
-                    $errors++;
-                }
-            }
-        }
         $line++;
     }
     close($m);
@@ -332,6 +366,10 @@ for my $s (@funcorder) {
     $funcblessed{$s} = $ind++
 }
 
+for my $m (@manpages) {
+    $docsdirs{dirname($m)}++;
+}
+
 for my $m (@manpages) {
     scanmanpage($m);
 }