romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-08-06 01:36:13 +03:00
Code Issues Projects Releases Packages Wiki Activity

opt-docs: verify man page sections + order

Browse source 
In every libcurl option man page there are now 8 mandatory sections that
must use the right name in the correct order and test 1173 verifies
this. Only 14 man pages needed adjustments.

The sections and the order is as follows:

 - NAME
 - SYNOPSIS
 - DESCRIPTION
 - PROTOCOLS
 - EXAMPLE
 - AVAILABILITY
 - RETURN VALUE
 - SEE ALSO

Reviewed-by: Daniel Gustafsson
Closes #7656
This commit is contained in:
Daniel Stenberg 2021-09-01 10:26:36 +02:00
parent 1731a77989
commit 12a2ed970f
No known key found for this signature in database
GPG key ID: 5CC908FDB71E12C2
16 changed files with 149 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

73
tests/manpage-syntax.pl
View file

@ -32,11 +32,27 @@ use warnings;
my @manpages=@ARGV;
my $errors = 0;
my %blessed;
my @order = (
'NAME',
'SYNOPSIS',
'DESCRIPTION',
#'DEFAULT', # CURLINFO_ has no default
'PROTOCOLS',
'EXAMPLE',
'AVAILABILITY',
'RETURN VALUE',
'SEE ALSO'
);
my %shline; # section => line number
sub scanmanpage {
my ($file) = @_;
my $reqex = 0;
my $inex = 0;
my $exsize = 0;
my $shc = 0;
my @sh;
print "Check $file\n";
open(M, "<$file") || die "no such file: $file";
@ -46,15 +62,22 @@ sub scanmanpage {
}
my $line = 1;
while(<M>) {
if($_ =~ /^.SH EXAMPLE/) {
if($_ =~ /^.SH EXAMPLE/i) {
$inex = 1;
}
elsif($_ =~ /^.SH/) {
elsif($_ =~ /^.SH/i) {
$inex = 0;
}
elsif($inex) {
$exsize++;
}
if($_ =~ /^.SH (.*)/i) {
my $n = $1;
# remove enclosing quotes
$n =~ s/\"(.*)\"\z/$1/;
push @sh, $n;
$shline{$n} = $line;
}
if($_ =~ /^\'/) {
print STDERR "$file:$line line starts with single quote!\n";
@ -75,12 +98,52 @@ sub scanmanpage {
}
close(M);
if($reqex && ($exsize < 2)) {
print STDERR "$file:$line missing EXAMPLE section\n";
$errors++;
if($reqex) {
# only for libcurl options man-pages
if($exsize < 2) {
print STDERR "$file:$line missing EXAMPLE section\n";
$errors++;
}
my $got;
my $i = 0;
my $shused = 1;
do {
$got = shift(@sh);
if($got) {
$i = $blessed{$got};
}
if($i && $got) {
# mandatory section
if($i != $shused) {
printf STDERR "$file:%u Got $got, when %s was expected\n",
$shline{$got},
$order[$shused-1];
$errors++;
return;
}
$shused++;
if($i == 9) {
# last mandatory one, exit
$got="";
}
}
} while($got);
if($i != 8) {
printf STDERR "$file:$line missing mandatory section: %s\n",
$order[$i];
$errors++;
}
}
}
my $ind = 1;
for my $s (@order) {
$blessed{$s} = $ind++
}
for my $m (@manpages) {
scanmanpage($m);