From 2b8937ce3a5268cbd072d14760698c7ff8232428 Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Wed, 27 Sep 2023 11:33:45 +0200
Subject: [PATCH] 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 | 66 ++++++++++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 14 deletions(-)

diff --git a/tests/manpage-syntax.pl b/tests/manpage-syntax.pl
index a6c934b588..7457c7d44c 100755
--- a/tests/manpage-syntax.pl
+++ b/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);
 }