symbol-scan.pl: scan and verify .3 man pages

This script now also finds all .3 man pages in docs/include and
docs/include/opts, extracts all uses of CURL* symbols and verifies that all
symbols mentioned in docs are defined in public headers.

A "global symbol" is one of those matching a known prefix and the script makes
an attempt to check all/most of them. Just using *all* symbols that match
CURL* proved matching a little too many other references as well and turned
difficult turning into something useful.

Closes #9544

tests/symbol-scan.pl

@@ -57,6 +57,7 @@ my $verbose=0;
 my $summary=0;
 my $misses=0;
 
+my @manrefs;
 my @syms;
 my %doc;
 my %rem;
@@ -73,7 +74,6 @@ sub scanenum {
             chomp;
             s/[,\s].*//;
             push @syms, $_;
-            print STDERR "$_\n";
         }
     }
     close H_IN || die "Error preprocessing $file";
@@ -102,11 +102,46 @@ sub scanallheaders {
     }
 }
 
+sub checkmanpage {
+    my ($m) = @_;
+
+    open(M, "<$m");
+    my $line = 1;
+    while(<M>) {
+        # strip off formatting
+        $_ =~ s/\\f[BPRI]//;
+        # detect global-looking 'CURL[BLABLA]_*' symbols
+        while(s/\W(CURL(AUTH|E|H|MOPT|OPT|SHOPT|UE|M|SSH|SSLBACKEND|HEADER|FORM|FTP|PIPE|MIMEOPT|GSSAPI|ALTSVC|PROTO|PROXY|UPART|USESSL|_READFUNC|_WRITEFUNC|_CSELECT|_FORMADD|_IPRESOLVE|_REDIR|_RTSPREQ|_TIMECOND|_VERSION)_[a-zA-Z0-9_]+)//) {
+            my $s = $1;
+            # skip two "special" ones
+            if($s !~ /^(CURLE_OBSOLETE|CURLOPT_TEMPLATE)/) {
+                push @manrefs, "$1:$m:$line";
+            }
+        }
+        $line++;
+    }
+    close(M);
+}
+
+sub scanman3dir {
+    my ($d) = @_;
+    opendir(my $dh, $d) ||
+        die "Can't opendir: $!";
+    my @mans = grep { /.3\z/ } readdir($dh);
+    closedir $dh;
+    for my $m (@mans) {
+        checkmanpage("$d/$m");
+    }
+}
+
+
 scanallheaders();
+scanman3dir("$root/docs/libcurl");
+scanman3dir("$root/docs/libcurl/opts");
 
 open S, "<$root/docs/libcurl/symbols-in-versions";
 while(<S>) {
-    if(/(^[^ \n]*) *(.*)/) {
+    if(/(^[^ \n]+) +(.*)/) {
         my ($sym, $rest)=($1, $2);
         if($doc{$sym}) {
             print "Detected duplicate symbol: $sym\n";
@@ -179,6 +214,17 @@ for my $e (sort keys %doc) {
     }
 }
 
+my %warned;
+for my $r (@manrefs) {
+    if($r =~ /^([^:]+):(.*)/) {
+        my ($sym, $file)=($1, $2);
+        if(!$doc{$sym} && !$warned{$sym, $file}) {
+            print "$file: $sym is not a public symbol\n";
+            $warned{$sym, $file} = 1;
+        }
+    }
+}
+
 if($summary) {
     print "Summary:\n";
     printf "%d symbols in headers (out of which %d are ignored)\n", scalar(@syms),