git-market/curl-curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-04-11 12:01:42 +08:00
Code Issues Actions 14 Packages Projects Releases Wiki Activity

manpage-syntax: verify curl man page references

Browse Source 
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
This commit is contained in:
Daniel Stenberg 2023-09-27 11:33:45 +02:00
parent 290622cea6
commit 2b8937ce3a
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
1 changed files with 52 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
tests/manpage-syntax.pl
View File

@ -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);
}