380 lines
10 KiB
Perl
380 lines
10 KiB
Perl
|
#!/usr/bin/env perl
|
||
|
|
#***************************************************************************
|
||
|
|
# _ _ ____ _
|
||
|
|
# Project ___| | | | _ \| |
|
||
|
|
# / __| | | | |_) | |
|
||
|
|
# | (__| |_| | _ <| |___
|
||
|
|
# \___|\___/|_| \_\_____|
|
||
|
|
#
|
||
|
|
# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
||
|
|
#
|
||
|
|
# This software is licensed as described in the file COPYING, which
|
||
|
|
# you should have received as part of this distribution. The terms
|
||
|
|
# are also available at https://curl.se/docs/copyright.html.
|
||
|
|
#
|
||
|
|
# You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
||
|
|
# copies of the Software, and permit persons to whom the Software is
|
||
|
|
# furnished to do so, under the terms of the COPYING file.
|
||
|
|
#
|
||
|
|
# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
||
|
|
# KIND, either express or implied.
|
||
|
|
#
|
||
|
|
# SPDX-License-Identifier: curl
|
||
|
|
#
|
||
|
|
###########################################################################
|
||
|
|
#
|
||
|
|
# Scan man page(s) and detect some simple and yet common formatting mistakes.
|
||
|
|
#
|
||
|
|
# Output all deviances to stderr.
|
||
|
|
|
||
|
|
use strict;
|
||
|
|
use warnings;
|
||
|
|
use File::Basename;
|
||
|
|
|
||
|
|
# get the file name first
|
||
|
|
my $symbolsinversions=shift @ARGV;
|
||
|
|
|
||
|
|
# we may get the dir roots pointed out
|
||
|
|
my @manpages=@ARGV;
|
||
|
|
my $errors = 0;
|
||
|
|
|
||
|
|
my %docsdirs;
|
||
|
|
my %optblessed;
|
||
|
|
my %funcblessed;
|
||
|
|
my @optorder = (
|
||
|
|
'NAME',
|
||
|
|
'SYNOPSIS',
|
||
|
|
'DESCRIPTION',
|
||
|
|
#'DEFAULT', # CURLINFO_ has no default
|
||
|
|
'PROTOCOLS',
|
||
|
|
'EXAMPLE',
|
||
|
|
'AVAILABILITY',
|
||
|
|
'RETURN VALUE',
|
||
|
|
'SEE ALSO'
|
||
|
|
);
|
||
|
|
my @funcorder = (
|
||
|
|
'NAME',
|
||
|
|
'SYNOPSIS',
|
||
|
|
'DESCRIPTION',
|
||
|
|
'EXAMPLE',
|
||
|
|
'AVAILABILITY',
|
||
|
|
'RETURN VALUE',
|
||
|
|
'SEE ALSO'
|
||
|
|
);
|
||
|
|
my %shline; # section => line number
|
||
|
|
|
||
|
|
my %symbol;
|
||
|
|
|
||
|
|
# some CURLINFO_ symbols are not actual options for curl_easy_getinfo,
|
||
|
|
# mark them as "deprecated" to hide them from link-warnings
|
||
|
|
my %deprecated = (
|
||
|
|
CURLINFO_TEXT => 1,
|
||
|
|
CURLINFO_HEADER_IN => 1,
|
||
|
|
CURLINFO_HEADER_OUT => 1,
|
||
|
|
CURLINFO_DATA_IN => 1,
|
||
|
|
CURLINFO_DATA_OUT => 1,
|
||
|
|
CURLINFO_SSL_DATA_IN => 1,
|
||
|
|
CURLINFO_SSL_DATA_OUT => 1,
|
||
|
|
);
|
||
|
|
sub allsymbols {
|
||
|
|
open(my $f, "<", "$symbolsinversions") ||
|
||
|
|
die "$symbolsinversions: $|";
|
||
|
|
while(<$f>) {
|
||
|
|
if($_ =~ /^([^ ]*) +(.*)/) {
|
||
|
|
my ($name, $info) = ($1, $2);
|
||
|
|
$symbol{$name}=$name;
|
||
|
|
|
||
|
|
if($info =~ /([0-9.]+) +([0-9.]+)/) {
|
||
|
|
$deprecated{$name}=$info;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
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;
|
||
|
|
my $inseealso = 0;
|
||
|
|
my $inex = 0;
|
||
|
|
my $insynop = 0;
|
||
|
|
my $exsize = 0;
|
||
|
|
my $synopsize = 0;
|
||
|
|
my $shc = 0;
|
||
|
|
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/) {
|
||
|
|
# This is a man page for libcurl. It requires an example!
|
||
|
|
$reqex = 1;
|
||
|
|
if($1 eq "CURL") {
|
||
|
|
$optpage = 1;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
my $line = 1;
|
||
|
|
while(<$m>) {
|
||
|
|
chomp;
|
||
|
|
if($_ =~ /^.so /) {
|
||
|
|
# this man page is just a referral
|
||
|
|
close($m);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
if(($_ =~ /^\.SH SYNOPSIS/i) && ($reqex)) {
|
||
|
|
# this is for libcurl man page SYNOPSIS checks
|
||
|
|
$insynop = 1;
|
||
|
|
$inex = 0;
|
||
|
|
}
|
||
|
|
elsif($_ =~ /^\.SH EXAMPLE/i) {
|
||
|
|
$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, $3;
|
||
|
|
push @sepline, $line;
|
||
|
|
checkref($1, $2, $file, $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/) {
|
||
|
|
print STDERR "$file:$line '\\n' need to be '\\\\n'!\n";
|
||
|
|
}
|
||
|
|
}
|
||
|
|
elsif($insynop) {
|
||
|
|
$synopsize++;
|
||
|
|
if(($synopsize == 1) && ($_ !~ /\.nf/)) {
|
||
|
|
print STDERR "$file:$line:1:ERROR: be .nf for proper formatting\n";
|
||
|
|
}
|
||
|
|
}
|
||
|
|
if($_ =~ /^\.SH ([^\r\n]*)/i) {
|
||
|
|
my $n = $1;
|
||
|
|
# remove enclosing quotes
|
||
|
|
$n =~ s/\"(.*)\"\z/$1/;
|
||
|
|
push @sh, $n;
|
||
|
|
$shline{$n} = $line;
|
||
|
|
$SH = $n;
|
||
|
|
}
|
||
|
|
|
||
|
|
if($_ =~ /^\'/) {
|
||
|
|
print STDERR "$file:$line line starts with single quote!\n";
|
||
|
|
$errors++;
|
||
|
|
}
|
||
|
|
if($_ =~ /\\f([BI])(.*)/) {
|
||
|
|
my ($format, $rest) = ($1, $2);
|
||
|
|
if($rest !~ /\\fP/) {
|
||
|
|
print STDERR "$file:$line missing \\f${format} terminator!\n";
|
||
|
|
$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/) {
|
||
|
|
# only if there wasn't another backslash before the \f
|
||
|
|
print STDERR "$file:$line suspicious \\f format!\n";
|
||
|
|
$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_|SHOPT_)[A-Z0-9_]*)/)) {
|
||
|
|
# an option with its own man page, check that it is tagged
|
||
|
|
# for linking
|
||
|
|
my ($pref, $symbol) = ($1, $2);
|
||
|
|
if($deprecated{$symbol}) {
|
||
|
|
# let it be
|
||
|
|
}
|
||
|
|
elsif($pref !~ /\\fI\z/) {
|
||
|
|
print STDERR "$file:$line option $symbol missing \\fI tagging\n";
|
||
|
|
$errors++;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
if($_ =~ /[ \t]+$/) {
|
||
|
|
print STDERR "$file:$line trailing whitespace\n";
|
||
|
|
$errors++;
|
||
|
|
}
|
||
|
|
$line++;
|
||
|
|
}
|
||
|
|
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
|
||
|
|
|
||
|
|
my $shcount = scalar(@sh); # before @sh gets shifted
|
||
|
|
if($exsize < 2) {
|
||
|
|
print STDERR "$file:$line missing EXAMPLE section\n";
|
||
|
|
$errors++;
|
||
|
|
}
|
||
|
|
|
||
|
|
if($shcount < 3) {
|
||
|
|
print STDERR "$file:$line too few man page sections!\n";
|
||
|
|
$errors++;
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
my $got = "start";
|
||
|
|
my $i = 0;
|
||
|
|
my $shused = 1;
|
||
|
|
my @shorig = @sh;
|
||
|
|
my @order = $optpage ? @optorder : @funcorder;
|
||
|
|
my $blessed = $optpage ? \%optblessed : \%funcblessed;
|
||
|
|
|
||
|
|
while($got) {
|
||
|
|
my $finesh;
|
||
|
|
$got = shift(@sh);
|
||
|
|
if($got) {
|
||
|
|
if($$blessed{$got}) {
|
||
|
|
$i = $$blessed{$got};
|
||
|
|
$finesh = $got; # a mandatory one
|
||
|
|
}
|
||
|
|
}
|
||
|
|
if($i && defined($finesh)) {
|
||
|
|
# mandatory section
|
||
|
|
|
||
|
|
if($i != $shused) {
|
||
|
|
printf STDERR "$file:%u Got %s, when %s was expected\n",
|
||
|
|
$shline{$finesh},
|
||
|
|
$finesh,
|
||
|
|
$order[$shused-1];
|
||
|
|
$errors++;
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
$shused++;
|
||
|
|
if($i == scalar(@order)) {
|
||
|
|
# last mandatory one, exit
|
||
|
|
last;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
if($i != scalar(@order)) {
|
||
|
|
printf STDERR "$file:$line missing mandatory section: %s\n",
|
||
|
|
$order[$i];
|
||
|
|
printf STDERR "$file:$line section found at index %u: '%s'\n",
|
||
|
|
$i, $shorig[$i];
|
||
|
|
printf STDERR " Found %u used sections\n", $shcount;
|
||
|
|
$errors++;
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
allsymbols();
|
||
|
|
|
||
|
|
if(!$symbol{'CURLALTSVC_H1'}) {
|
||
|
|
print STDERR "didn't get the symbols-in-version!\n";
|
||
|
|
exit;
|
||
|
|
}
|
||
|
|
|
||
|
|
my $ind = 1;
|
||
|
|
for my $s (@optorder) {
|
||
|
|
$optblessed{$s} = $ind++
|
||
|
|
}
|
||
|
|
$ind = 1;
|
||
|
|
for my $s (@funcorder) {
|
||
|
|
$funcblessed{$s} = $ind++
|
||
|
|
}
|
||
|
|
|
||
|
|
for my $m (@manpages) {
|
||
|
|
$docsdirs{dirname($m)}++;
|
||
|
|
}
|
||
|
|
|
||
|
|
for my $m (@manpages) {
|
||
|
|
scanmanpage($m);
|
||
|
|
}
|
||
|
|
|
||
|
|
print STDERR "ok\n" if(!$errors);
|
||
|
|
|
||
|
|
exit $errors;
|