master
1#!/usr/bin/env perl
2#***************************************************************************
3# _ _ ____ _
4# Project ___| | | | _ \| |
5# / __| | | | |_) | |
6# | (__| |_| | _ <| |___
7# \___|\___/|_| \_\_____|
8#
9# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
10#
11# This software is licensed as described in the file COPYING, which
12# you should have received as part of this distribution. The terms
13# are also available at https://curl.se/docs/copyright.html.
14#
15# You may opt to use, copy, modify, merge, publish, distribute and/or sell
16# copies of the Software, and permit persons to whom the Software is
17# furnished to do so, under the terms of the COPYING file.
18#
19# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
20# KIND, either express or implied.
21#
22# SPDX-License-Identifier: curl
23#
24###########################################################################
25#
26# Scan man page(s) and detect some simple and yet common formatting mistakes.
27#
28# Output all deviances to stderr.
30use strict;
31use warnings;
32use File::Basename;
34# get the filename first
35my $symbolsinversions = shift @ARGV;
37# we may get the directory roots pointed out
38my @manpages = @ARGV;
39my $errors = 0;
41my %docsdirs;
42my %optblessed;
43my %funcblessed;
44my @optorder = (
45 'NAME',
46 'SYNOPSIS',
47 'DESCRIPTION',
48 #'DEFAULT', # CURLINFO_ has no default
49 'PROTOCOLS',
50 'EXAMPLE',
51 'AVAILABILITY',
52 'RETURN VALUE',
53 'SEE ALSO'
54 );
55my @funcorder = (
56 'NAME',
57 'SYNOPSIS',
58 'DESCRIPTION',
59 'EXAMPLE',
60 'AVAILABILITY',
61 'RETURN VALUE',
62 'SEE ALSO'
63 );
64my %shline; # section => line number
66my %symbol;
68# some CURLINFO_ symbols are not actual options for curl_easy_getinfo,
69# mark them as "deprecated" to hide them from link-warnings
70my %deprecated = (
71 CURLINFO_TEXT => 1,
72 CURLINFO_HEADER_IN => 1,
73 CURLINFO_HEADER_OUT => 1,
74 CURLINFO_DATA_IN => 1,
75 CURLINFO_DATA_OUT => 1,
76 CURLINFO_SSL_DATA_IN => 1,
77 CURLINFO_SSL_DATA_OUT => 1,
78 CURLOPT_EGDSOCKET => 1,
79 CURLOPT_RANDOM_FILE => 1,
80 );
81sub allsymbols {
82 open(my $f, "<", $symbolsinversions) or die "$symbolsinversions: $|";
83 while(<$f>) {
84 if($_ =~ /^([^ ]*) +(.*)/) {
85 my ($name, $info) = ($1, $2);
86 $symbol{$name} = $name;
88 if($info =~ /([0-9.]+) +([0-9.]+)/) {
89 $deprecated{$name} = $info;
90 }
91 }
92 }
93 close($f);
94}
96my %ref = (
97 'curl.1' => 1
98 );
99sub checkref {
100 my ($f, $sec, $file, $line) = @_;
101 my $present = 0;
102 #print STDERR "check $f.$sec\n";
103 if($ref{"$f.$sec"}) {
104 # present
105 return;
106 }
107 foreach my $d (keys %docsdirs) {
108 if(-f "$d/$f.$sec") {
109 $present = 1;
110 $ref{"$f.$sec"} = 1;
111 last;
112 }
113 }
114 if(!$present) {
115 print STDERR "$file:$line broken reference to $f($sec)\n";
116 $errors++;
117 }
118}
120# option-looking words that are not options
121my %allownonref = (
122 'CURLINFO_TEXT' => 1,
123 'CURLINFO_HEADER_IN' => 1,
124 'CURLINFO_HEADER_OUT' => 1,
125 'CURLINFO_DATA_IN' => 1,
126 'CURLINFO_DATA_OUT' => 1,
127 'CURLINFO_SSL_DATA_IN' => 1,
128 'CURLINFO_SSL_DATA_OUT' => 1,
129 );
131sub scanmanpage {
132 my ($file) = @_;
133 my $reqex = 0;
134 my $inseealso = 0;
135 my $inexample = 0;
136 my $insynop = 0;
137 my $exsize = 0;
138 my $synopsize = 0;
139 my $shc = 0;
140 my $optpage = 0; # option or function
141 my @sh;
142 my $SH = "";
143 my @separators;
144 my @sepline;
146 open(my $m, "<", $file) or die "test1173.pl could not open $file";
147 if($file =~ /[\/\\](CURL|curl_)([^\/\\]*).3/) {
148 # This is a man page for libcurl. It requires an example unless it is
149 # considered deprecated.
150 $reqex = 1 unless defined $deprecated{'CURL' . $2};
151 if($1 eq "CURL") {
152 $optpage = 1;
153 }
154 }
155 my $line = 1;
156 while(<$m>) {
157 chomp;
158 if($_ =~ /^.so /) {
159 # this man page is a referral
160 close($m);
161 return;
162 }
163 if(($_ =~ /^\.SH SYNOPSIS/i) && ($reqex)) {
164 # this is for libcurl man page SYNOPSIS checks
165 $insynop = 1;
166 $inexample = 0;
167 }
168 elsif($_ =~ /^\.SH EXAMPLE/i) {
169 $insynop = 0;
170 $inexample = 1;
171 }
172 elsif($_ =~ /^\.SH \"SEE ALSO\"/i) {
173 $inseealso = 1;
174 }
175 elsif($_ =~ /^\.SH/i) {
176 $insynop = 0;
177 $inexample = 0;
178 }
179 elsif($inseealso) {
180 if($_ =~ /^\.BR (.*)/i) {
181 my $f = $1;
182 if($f =~ /^(lib|)curl/i) {
183 $f =~ s/[\n\r]//g;
184 if($f =~ s/([a-z_0-9-]*) \(([13])\)([, ]*)//i) {
185 push @separators, $3;
186 push @sepline, $line;
187 checkref($1, $2, $file, $line);
188 }
189 if($f !~ /^ *$/) {
190 print STDERR "$file:$line bad SEE ALSO format\n";
191 $errors++;
192 }
193 }
194 else {
195 if($f =~ /.*(, *)\z/) {
196 push @separators, $1;
197 push @sepline, $line;
198 }
199 else {
200 push @separators, " ";
201 push @sepline, $line;
202 }
203 }
204 }
205 }
206 elsif($inexample) {
207 $exsize++;
208 if($_ =~ /[^\\]\\n/) {
209 print STDERR "$file:$line '\\n' need to be '\\\\n'!\n";
210 }
211 }
212 elsif($insynop) {
213 $synopsize++;
214 if(($synopsize == 1) && ($_ !~ /\.nf/)) {
215 print STDERR "$file:$line:1:ERROR: be .nf for proper formatting\n";
216 }
217 }
218 if($_ =~ /^\.SH ([^\r\n]*)/i) {
219 my $n = $1;
220 # remove enclosing quotes
221 $n =~ s/\"(.*)\"\z/$1/;
222 push @sh, $n;
223 $shline{$n} = $line;
224 $SH = $n;
225 }
227 if($_ =~ /^\'/) {
228 print STDERR "$file:$line line starts with single quote!\n";
229 $errors++;
230 }
231 if($_ =~ /\\f([BI])(.*)/) {
232 my ($format, $rest) = ($1, $2);
233 if($rest !~ /\\fP/) {
234 print STDERR "$file:$line missing \\f${format} terminator!\n";
235 $errors++;
236 }
237 }
238 my $c = $_;
239 while($c =~ s/\\f([BI])((lib|)curl[a-z_0-9-]*)\(([13])\)//i) {
240 checkref($2, $4, $file, $line);
241 }
242 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-]+)(.)/) &&
243 ($4 ne "(")) {
244 my $word = $2;
246 if(!$allownonref{$word}) {
247 print STDERR "$file:$line curl ref to $word without section\n";
248 $errors++;
249 }
250 }
251 if($_ =~ /(.*)\\f([^BIP])/) {
252 my ($pre, $format) = ($1, $2);
253 if($pre !~ /\\\z/) {
254 # only if there was not another backslash before the \f
255 print STDERR "$file:$line suspicious \\f format!\n";
256 $errors++;
257 }
258 }
259 if(($SH =~ /^(DESCRIPTION|RETURN VALUE|AVAILABILITY)/i) &&
260 ($_ =~ /(.*)((curl_multi|curl_easy|curl_url|curl_global|curl_url|curl_share)[a-zA-Z_0-9-]+)/) &&
261 ($1 !~ /\\fI$/)) {
262 print STDERR "$file:$line unrefed curl call: $2\n";
263 $errors++;
264 }
266 if($optpage && $SH && ($SH !~ /^(SYNOPSIS|EXAMPLE|NAME|SEE ALSO)/i) &&
267 ($_ =~ /(.*)(CURL(OPT_|MOPT_|INFO_|SHOPT_)[A-Z0-9_]*)/)) {
268 # an option with its own man page, check that it is tagged
269 # for linking
270 my ($pref, $symbol) = ($1, $2);
271 if($deprecated{$symbol}) {
272 # let it be
273 }
274 elsif($pref !~ /\\fI\z/) {
275 print STDERR "$file:$line option $symbol missing \\fI tagging\n";
276 $errors++;
277 }
278 }
279 if($_ =~ /[ \t]+$/) {
280 print STDERR "$file:$line trailing whitespace\n";
281 $errors++;
282 }
283 $line++;
284 }
285 close($m);
287 if(@separators) {
288 # all except the last one need comma
289 for(0 .. $#separators - 1) {
290 my $l = $_;
291 my $sep = $separators[$l];
292 if($sep ne ",") {
293 printf STDERR "$file:%d: bad not-last SEE ALSO separator: '%s'\n",
294 $sepline[$l], $sep;
295 $errors++;
296 }
297 }
298 # the last one should not do comma
299 my $sep = $separators[$#separators];
300 if($sep eq ",") {
301 printf STDERR "$file:%d: superfluous comma separator\n",
302 $sepline[$#separators];
303 $errors++;
304 }
305 }
307 if($reqex) {
308 # only for libcurl options man-pages
310 my $shcount = scalar(@sh); # before @sh gets shifted
311 if($exsize < 2) {
312 print STDERR "$file:$line missing EXAMPLE section\n";
313 $errors++;
314 }
316 if($shcount < 3) {
317 print STDERR "$file:$line too few man page sections!\n";
318 $errors++;
319 return;
320 }
322 my $got = "start";
323 my $i = 0;
324 my $shused = 1;
325 my @shorig = @sh;
326 my @order = $optpage ? @optorder : @funcorder;
327 my $blessed = $optpage ? \%optblessed : \%funcblessed;
329 while($got) {
330 my $finesh;
331 $got = shift(@sh);
332 if($got) {
333 if($$blessed{$got}) {
334 $i = $$blessed{$got};
335 $finesh = $got; # a mandatory one
336 }
337 }
338 if($i && defined($finesh)) {
339 # mandatory section
341 if($i != $shused) {
342 printf STDERR "$file:%u Got %s, when %s was expected\n",
343 $shline{$finesh},
344 $finesh,
345 $order[$shused - 1];
346 $errors++;
347 return;
348 }
349 $shused++;
350 if($i == scalar(@order)) {
351 # last mandatory one, exit
352 last;
353 }
354 }
355 }
357 if($i != scalar(@order)) {
358 printf STDERR "$file:$line missing mandatory section: %s\n",
359 $order[$i];
360 printf STDERR "$file:$line section found at index %u: '%s'\n",
361 $i, $shorig[$i];
362 printf STDERR " Found %u used sections\n", $shcount;
363 $errors++;
364 }
365 }
366}
368allsymbols();
370if(!$symbol{'CURLALTSVC_H1'}) {
371 print STDERR "did not get the symbols-in-version!\n";
372 exit;
373}
375my $ind = 1;
376for my $s (@optorder) {
377 $optblessed{$s} = $ind++
378}
379$ind = 1;
380for my $s (@funcorder) {
381 $funcblessed{$s} = $ind++
382}
384for my $m (@manpages) {
385 $docsdirs{dirname($m)}++;
386}
388for my $m (@manpages) {
389 scanmanpage($m);
390}
392print STDERR "ok\n" if(!$errors);
394exit $errors;
Diagnostics4 git calls · 28 ms
CallStatusSizeTime028 ms
discover200152 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=152 git.server.agent=gitty/1.0 git.server.object_format=sha1 git.server.caps=agent ls-refs fetch object-format git.server.fetch=shallow filter sideband-all git.protocol.version=2 git.pkt.frames=8 git.pkt.data=6 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=152 git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=149 git.response.cache=HIT git.response.duration_ms=3 git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=149 git.pkt.payload.max=78 git.ls_refs.count=2 git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=293470 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=blob:none git.fetch.filter.requested=tree:0 git.fetch.filter.fallback=blob:none git.fetch.filter.learned=false git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=10 git.pkt.data=8 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=293470 git.pkt.payload.max=65516 git.sideband.band1.bytes=293354 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=87 git.pack.bytes=293354 git.pack.ofs_delta=0 git.pack.ref_delta=1 git.pack.chain.max=1 git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0 git.pack.full=86Open pack map
fetch2003.7 KiB · hit22 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=22 git.response.bytes=3823 git.response.cache=HIT git.response.duration_ms=22 git.fetch.wants=18351f0e0dcc72bcb65b8682e094c9f3cfc2503e git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=3823 git.pkt.payload.max=3802 git.sideband.band1.bytes=3801 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
- Ref
- refs/heads/master
- Commit
- 31c911efe5652725e930f4d2e60c9060e5f6646d
- cf-ray
- a5e1c36458d636cd
- Request
- 3062aec4…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format