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###########################################################################
26=begin comment
28This script generates the man page.
30Example: managen <command> [files] > curl.1
32Dev notes:
34We open *input* files in :crlf translation (a no-op on many platforms) in
35case we have CRLF line endings in Windows but a perl that defaults to LF.
36Unfortunately it seems some perls like msysgit cannot handle a global input-only
37:crlf so it has to be specified on each file open for text input.
39=end comment
40=cut
42use strict;
43use warnings;
45my %optshort;
46my %optlong;
47my %helplong;
48my %arglong;
49my %redirlong;
50my %protolong;
51my %catlong;
53use POSIX qw(strftime);
54my @ts;
55if(defined($ENV{SOURCE_DATE_EPOCH})) {
56 @ts = gmtime($ENV{SOURCE_DATE_EPOCH});
57}
58else {
59 @ts = localtime;
60}
61my $date = strftime "%Y-%m-%d", @ts;
62my $year = strftime "%Y", @ts;
63my $version = "unknown";
64my $globals;
65my $error = 0;
66my $indent = 4;
68# get the long name version, return the man page string
69sub manpageify {
70 my ($k, $manpage) = @_;
71 my $trail = '';
72 # the matching pattern might include a trailing dot that cannot be part of
73 # the option name
74 if($k =~ s/\.$//) {
75 # cut off trailing dot
76 $trail = ".";
77 }
78 if($manpage) {
79 my $klong = $k;
80 # quote "bare" minuses in the long name
81 $klong =~ s/-/\\-/g;
83 # only long
84 return "\\fI\\-\\-$klong\\fP$trail";
85 }
86 return "--$k$trail";
87}
89my $colwidth = 79; # max number of columns
91sub prefixline {
92 my ($num) = @_;
93 print "\t" x ($num / 8);
94 print ' ' x ($num % 8);
95}
97sub justline {
98 my ($lvl, @line) = @_;
99 my $w = -1;
100 my $spaces = -1;
101 my $width = $colwidth - ($lvl * $indent);
102 for(@line) {
103 $w += length($_);
104 $w++;
105 $spaces++;
106 }
107 my $inject = $width - $w;
108 my $ratio = 0; # stay at zero if no spaces at all
109 if($spaces) {
110 $ratio = $inject / $spaces;
111 }
112 my $spare = 0;
113 prefixline($lvl * $indent);
114 my $prev;
115 for(@line) {
116 while($spare >= 0.90) {
117 print " ";
118 $spare--;
119 }
120 printf "%s%s", $prev ? " " : "", $_;
121 $prev = 1;
122 $spare += $ratio;
123 }
124 print "\n";
125}
127sub lastline {
128 my ($lvl, @line) = @_;
129 my $l = 0;
130 $line[0] =~ s/^( +)//;
131 $l = length($1) if($1);
132 prefixline($lvl * $indent + $l);
133 my $prev = 0;
134 for(@line) {
135 printf "%s%s", $prev ? " " : "", $_;
136 $prev = 1;
137 }
138 print "\n";
139}
141sub outputpara {
142 my ($lvl, $f) = @_;
143 $f =~ s/\n/ /g;
145 my $w = 0;
146 my @words = split(/ */, $f);
147 my $width = $colwidth - ($lvl * $indent);
149 my @line;
150 for my $e (@words) {
151 my $l = length($e);
152 my $spaces = scalar(@line);
153 if(($w + $l + $spaces) >= $width) {
154 justline($lvl, @line);
155 undef @line;
156 $w = 0;
157 }
159 push @line, $e;
160 $w += $l; # new width
161 }
162 if($w) {
163 lastline($lvl, @line);
164 print "\n";
165 }
166}
168sub printdesc {
169 my ($manpage, $baselvl, @desc) = @_;
171 if($manpage) {
172 for my $d (@desc) {
173 print $d;
174 }
175 }
176 else {
177 my $p = -1;
178 my $pnum;
179 my $para = '';
180 for my $l (@desc) {
181 my $lvl = 0;
182 my $lvlnum;
183 if($l !~ /^[\n\r]+/) {
184 # get the indent level off the string
185 $l =~ s/^\[([0-9q]*)\]//;
186 $lvl = $1;
187 }
188 if(($p =~ /q/) && ($lvl !~ /q/)) {
189 # the previous was quoted, this is not
190 print "\n";
191 }
192 if($lvl ne $p) {
193 $pnum = $p;
194 $pnum =~ s/q$//;
195 outputpara($baselvl + $pnum, $para);
196 $para = "";
197 }
198 if($lvl =~ /q/) {
199 # quoted, do not right-justify
200 chomp $l;
201 $lvlnum = $lvl;
202 $lvlnum =~ s/q$//;
203 lastline($baselvl + $lvlnum + 1, $l);
204 my $w = ($baselvl + $lvlnum + 1) * $indent + length($l);
205 if($w > $colwidth) {
206 print STDERR "ERROR: $w columns is too long\n";
207 print STDERR "$l\n";
208 $error++;
209 }
210 }
211 else {
212 $para .= $l;
213 }
215 $p = $lvl;
216 }
217 $pnum = $p;
218 $pnum =~ s/q$//;
219 outputpara($baselvl + $pnum, $para);
220 }
221}
223sub seealso {
224 my($standalone, $data) = @_;
225 if($standalone) {
226 return sprintf
227 ".SH \"SEE ALSO\"\n$data\n";
228 }
229 else {
230 return "See also $data. ";
231 }
232}
234sub overrides {
235 my ($standalone, $data) = @_;
236 if($standalone) {
237 return ".SH \"OVERRIDES\"\n$data\n";
238 }
239 else {
240 return $data;
241 }
242}
244my %protexists = (
245 'DNS' => 1,
246 'FILE' => 1,
247 'FTP' => 1,
248 'FTPS' => 1,
249 'GSS/kerberos' => 1,
250 'HTTP' => 1,
251 'HTTPS' => 1,
252 'IMAP' => 1,
253 'IPFS' => 1,
254 'LDAP' => 1,
255 'MQTT' => 1,
256 'POP3' => 1,
257 'SCP' => 1,
258 'SFTP' => 1,
259 'SMTP' => 1,
260 'SSL' => 2, # deprecated
261 'TELNET' => 1,
262 'TFTP' => 1,
263 'TLS' => 1,
264 );
266sub protocols {
267 my ($f, $line, $manpage, $standalone, $data) = @_;
268 my @e = split(/ +/, $data);
269 for my $pr (@e) {
270 if(!$protexists{$pr}) {
272 print STDERR "$f:$line:1:ERROR: unrecognized protocol: $pr\n";
273 exit 2;
274 }
275 }
276 if($standalone) {
277 return ".SH \"PROTOCOLS\"\n$data\n";
278 }
279 else {
280 return "($data) " if($manpage);
281 return "[1]($data) " if(!$manpage);
282 }
283}
285sub too_old {
286 my ($version) = @_;
287 my $a = 999999;
288 if($version =~ /^(\d+)\.(\d+)\.(\d+)/) {
289 $a = $1 * 1000 + $2 * 10 + $3;
290 }
291 elsif($version =~ /^(\d+)\.(\d+)/) {
292 $a = $1 * 1000 + $2 * 10;
293 }
294 if($a < 7660) {
295 # we consider everything before 7.66.0 to be too old to mention
296 # specific changes for
297 return 1;
298 }
299 return 0;
300}
302sub added {
303 my ($standalone, $data) = @_;
304 if(too_old($data)) {
305 # do not mention ancient additions
306 return "";
307 }
308 if($standalone) {
309 return ".SH \"ADDED\"\nAdded in curl version $data\n";
310 }
311 else {
312 return "Added in $data. ";
313 }
314}
316sub render {
317 my ($manpage, $fh, $f, $line) = @_;
318 my @desc;
319 my $tablemode = 0;
320 my $header = 0;
321 # if $top is TRUE, it means a top-level page and not a command line option
322 my $top = ($line == 1);
323 my $quote = 0;
324 my $level = 0;
325 my $finalblank;
326 my $blankline = 0;
327 my $start = 0;
329 while(<$fh>) {
330 my $d = $_;
331 $line++;
332 $finalblank = ($d eq "\n");
333 if($d =~ /^\.(SH|BR|IP|B)/) {
334 print STDERR "$f:$line:1:ERROR: nroff instruction in input: \".$1\"\n";
335 return 4;
336 }
337 if(/^ *<!--/) {
338 # skip comments
339 next;
340 }
341 if((!$start) && ($_ =~ /^[\r\n]*\z/)) {
342 # skip leading blank lines
343 next;
344 }
346 $start = 1;
348 if(/^[ \t]*\n/) {
349 # count and ignore blank lines
350 $blankline++;
351 next;
352 }
353 elsif($d =~ /^ (.*)/) {
354 my $word = $1;
355 if(!$quote && $manpage) {
356 push @desc, "\n" if($blankline);
357 push @desc, ".nf\n";
358 $blankline = 0;
359 }
360 $quote = 1;
361 $d = "$word\n";
362 }
363 elsif($d =~ /^(```|~~~)/) {
364 if(!$quote) {
365 if($manpage) {
366 push @desc, "\n" if($blankline);
367 push @desc, ".nf\n";
368 $blankline = 0;
369 }
370 $quote = 2;
371 }
372 else {
373 # end of quote
374 push @desc, ".fi\n" if($manpage);
375 $quote = 0;
376 }
377 next;
378 }
379 elsif($quote == 1) {
380 # end of quote
381 push @desc, ".fi\n" if($manpage);
382 $quote = 0;
383 }
385 if(/^# (.*)/) {
386 $header = 1;
387 if($top != 1) {
388 # ignored for command line options
389 $blankline++;
390 next;
391 }
392 push @desc, ".SH $1\n" if($manpage);
393 push @desc, "[0]$1\n" if(!$manpage);
394 next;
395 }
396 elsif(/^###/) {
397 print STDERR "$f:$line:1:ERROR: ### header is not supported\n";
398 exit 3;
399 }
400 elsif(/^## (.*)/) {
401 my $word = $1;
402 my $nontick = $word;
403 # if there are enclosing quotes, remove them first
404 $word =~ s/[\"\'](.*)[\"\']\z/$1/;
406 # remove backticks from headers
407 $word =~ s/\`//g;
409 # remove backticked sections
410 $nontick =~ s/\`[^\`]*\`//g;
411 if($nontick =~ /[^\\][\<\>]/) {
412 print STDERR "$f:$line:1:WARN: un-escaped < or > used: $nontick\n";
413 }
415 # if there is a space, it needs quotes for man page
416 if(($word =~ / /) && $manpage) {
417 $word = "\"$word\"";
418 }
419 $level = 1;
420 if($top == 1) {
421 push @desc, ".IP $word\n" if($manpage);
422 push @desc, "\n" if(!$manpage);
423 push @desc, "[1]$word\n" if(!$manpage);
424 }
425 else {
426 if(!$tablemode) {
427 push @desc, ".RS\n" if($manpage);
428 $tablemode = 1;
429 }
430 push @desc, ".IP $word\n" if($manpage);
431 push @desc, "\n" if(!$manpage);
432 push @desc, "[1]$word\n" if(!$manpage);
433 }
434 $header = 1;
435 next;
436 }
437 elsif(/^##/) {
438 if($top == 1) {
439 print STDERR "$f:$line:1:ERROR: ## empty header top-level mode\n";
440 exit 3;
441 }
442 if($tablemode) {
443 # end of table
444 push @desc, ".RE\n.IP\n" if($manpage);
445 push @desc, "\n" if(!$manpage);
446 $tablemode = 0;
447 $level = 0;
448 }
449 $header = 1;
450 next;
451 }
452 elsif(/^\.(IP|RS|RE)/) {
453 my ($cmd) = ($1);
454 print STDERR "$f:$line:1:ERROR: $cmd detected, use ##-style\n";
455 return 3;
456 }
458 $d =~ s/`%DATE`/$date/g;
459 $d =~ s/`%VERSION`/$version/g;
460 $d =~ s/`%GLOBALS`/$globals/g;
462 if(!$quote) {
463 if($d =~ /^(.*) /) {
464 printf STDERR "$f:$line:%d:ERROR: 2 spaces detected\n",
465 length($1);
466 return 3;
467 }
468 my $back = $d;
470 # remove all backticked pieces
471 $back =~ s/\`(.*?)\`//g;
473 if($back =~ /[^\\][\<\>]/) {
474 print STDERR "$f:$line:1:WARN: un-escaped < or > used: $back\n";
475 return 3;
476 }
477 }
479 # convert backticks to double quotes
480 $d =~ s/\`/\"/g;
482 if($d =~ /\(added in(.*)/i) {
483 if(length($1) < 2) {
484 print STDERR "$f:$line:1:ERROR: broken up added-in line:\n";
485 print STDERR "$f:$line:1:ERROR: $d";
486 return 3;
487 }
488 }
489 again:
490 if($d =~ /\(Added in ([0-9.]+)\)/i) {
491 my $ver = $1;
492 if(too_old($ver)) {
493 $d =~ s/ *\(Added in $ver\)//gi;
494 goto again;
495 }
496 }
498 # convert backslash-'<' or '> to the second character
499 $d =~ s/\\([><])/$1/g;
500 # convert single backslash to double-backslash
501 $d =~ s/\\/\\\\/g if($manpage);
503 if($manpage) {
504 if(!$quote && $d =~ /--/) {
505 $d =~ s/--([a-z0-9.-]+)/manpageify($1, 1)/ge;
506 }
508 # quote minuses in the output
509 $d =~ s/([^\\])-/$1\\-/g;
510 # replace single quotes
511 $d =~ s/\'/\\(aq/g;
512 # handle double quotes or periods first on the line
513 $d =~ s/^([\.\"])/\\&$1/;
514 # **bold**
515 $d =~ s/\*\*(\S.*?)\*\*/\\fB$1\\fP/g;
516 # *italics*
517 $d =~ s/\*(\S.*?)\*/\\fI$1\\fP/g;
518 }
519 else {
520 # **bold**
521 $d =~ s/\*\*(\S.*?)\*\*/$1/g;
522 # *italics*
523 $d =~ s/\*(\S.*?)\*/$1/g;
524 }
525 # trim trailing spaces
526 $d =~ s/[ \t]+\z//;
527 push @desc, "\n" if($blankline && !$header);
528 $blankline = 0;
529 push @desc, $d if($manpage);
530 my $qstr = $quote ? "q" : "";
531 push @desc, "[" . (1 + $level) . "$qstr]$d" if(!$manpage);
532 $header = 0;
533 }
534 if($finalblank) {
535 print STDERR "$f:$line:1:ERROR: trailing blank line\n";
536 exit 3;
537 }
538 if($quote) {
539 # do not leave the quote "hanging"
540 push @desc, ".fi\n" if($manpage);
541 }
542 if($tablemode) {
543 # end of table
544 push @desc, ".RE\n.IP\n" if($manpage);
545 }
546 return @desc;
547}
549sub maybespace {
550 my ($string) = @_;
552 if(($string =~ /(.* )(.*)/) &&
553 (length($2) <= 20)) {
554 return $1;
555 }
556 if(($string =~ /(.*:)(.*)/) &&
557 (length($2) <= 20)) {
558 return $1;
559 }
560 return $string;
561}
563sub single {
564 my ($dir, $manpage, $f, $standalone) = @_;
565 my $fh;
566 open($fh, "<:crlf", "$dir/$f") or
567 die "could not find $dir/$f";
568 my $short;
569 my $long;
570 my $tags;
571 my $added;
572 my $protocols;
573 my $arg;
574 my $mutexed;
575 my $requires;
576 my $category;
577 my @seealso;
578 my $copyright;
579 my $spdx;
580 my @examples; # there can be more than one
581 my $magic; # cmdline special option
582 my $line;
583 my $dline;
584 my $multi = "";
585 my $scope;
586 my $experimental;
587 my $start = 0;
588 my $list; # identifies the list, 1 example, 2 see-also
589 while(<$fh>) {
590 $line++;
591 if(/^ *<!--/) {
592 next;
593 }
594 if(!$start) {
595 if(/^---/) {
596 $start = 1;
597 }
598 next;
599 }
600 if(/^Short: *(.)/i) {
601 $short = $1;
602 }
603 elsif(/^Long: *(.*)/i) {
604 $long = $1;
605 }
606 elsif(/^Added: *(.*)/i) {
607 $added = $1;
608 }
609 elsif(/^Tags: *(.*)/i) {
610 $tags = $1;
611 }
612 elsif(/^Arg: *(.*)/i) {
613 $arg = $1;
614 }
615 elsif(/^Magic: *(.*)/i) {
616 $magic = $1;
617 }
618 elsif(/^Mutexed: *(.*)/i) {
619 $mutexed = $1;
620 }
621 elsif(/^Protocols: *(.*)/i) {
622 $protocols = $1;
623 }
624 elsif(/^See-also: +(.+)/i) {
625 if(@seealso) {
626 print STDERR "ERROR: duplicated See-also in $f\n";
627 return 1;
628 }
629 push @seealso, $1;
630 }
631 elsif(/^See-also:/i) {
632 $list = 2;
633 }
634 elsif(/^ *- (.*)/i && ($list == 2)) {
635 push @seealso, $1;
636 }
637 elsif(/^Requires: *(.*)/i) {
638 $requires = $1;
639 }
640 elsif(/^Category: *(.*)/i) {
641 $category = $1;
642 }
643 elsif(/^Example: +(.+)/i) {
644 push @examples, $1;
645 }
646 elsif(/^Example:/i) {
647 # '1' is the example list
648 $list = 1;
649 }
650 elsif(/^ *- (.*)/i && ($list == 1)) {
651 push @examples, $1;
652 }
653 elsif(/^Multi: *(.*)/i) {
654 $multi = $1;
655 }
656 elsif(/^Scope: *(.*)/i) {
657 $scope = $1;
658 }
659 elsif(/^Experimental: yes/i) {
660 $experimental = 1;
661 }
662 # REUSE-IgnoreStart
663 elsif(/^C: (.*)/i) {
664 $copyright = $1;
665 }
666 elsif(/^SPDX-License-Identifier: (.*)/i) {
667 $spdx = $1;
668 }
669 # REUSE-IgnoreEnd
670 elsif(/^Help: *(.*)/i) {
671 ;
672 }
673 elsif(/^---/) {
674 $start++;
675 if(!$long) {
676 print STDERR "ERROR: no 'Long:' in $f\n";
677 return 1;
678 }
679 if(!$category) {
680 print STDERR "ERROR: no 'Category:' in $f\n";
681 return 2;
682 }
683 if(!$examples[0]) {
684 print STDERR "$f:$line:1:ERROR: no 'Example:' present\n";
685 return 2;
686 }
687 if(!$added) {
688 print STDERR "$f:$line:1:ERROR: no 'Added:' version present\n";
689 return 2;
690 }
691 if(!$seealso[0]) {
692 print STDERR "$f:$line:1:ERROR: no 'See-also:' field present\n";
693 return 2;
694 }
695 if(!$copyright) {
696 print STDERR "$f:$line:1:ERROR: no 'C:' field present\n";
697 return 2;
698 }
699 if(!$spdx) {
700 # REUSE-IgnoreStart
701 print STDERR "$f:$line:1:ERROR: no 'SPDX-License-Identifier:' field present\n";
702 # REUSE-IgnoreEnd
703 return 2;
704 }
705 last;
706 }
707 else {
708 chomp;
709 print STDERR "$f:$line:1:WARN: unrecognized line in $f, ignoring: '$_';\n";
710 }
711 }
713 if($start < 2) {
714 print STDERR "$f:1:1:ERROR: no proper meta-data header\n";
715 return 2;
716 }
718 my @desc = render($manpage, $fh, $f, $line);
719 close($fh);
720 my $opt;
722 if(defined($short) && $long) {
723 $opt = "-$short, --$long";
724 }
725 elsif($short && !$long) {
726 $opt = "-$short";
727 }
728 elsif($long && !$short) {
729 $opt = "--$long";
730 }
732 if($arg) {
733 $opt .= " $arg";
734 }
736 # quote "bare" minuses in opt
737 $opt =~ s/-/\\-/g if($manpage);
738 if($standalone) {
739 print ".TH curl 1 \"30 Nov 2016\" \"curl 7.52.0\" \"curl manual\"\n";
740 print ".SH OPTION\n";
741 print "curl $opt\n";
742 }
743 elsif($manpage) {
744 print ".IP \"$opt\"\n";
745 }
746 else {
747 lastline(1, $opt);
748 }
749 my @leading;
750 if($protocols) {
751 push @leading, protocols($f, $line, $manpage, $standalone, $protocols);
752 }
754 if($standalone) {
755 print ".SH DESCRIPTION\n";
756 }
758 if($experimental) {
759 my $pref = $manpage ? "" : "[1]";
760 push @leading, "$pref**WARNING**: this option is experimental. Do not use in production.\n\n";
761 }
763 my $pre = $manpage ? "\n" : "[1]";
765 if($scope) {
766 if($category !~ /global/) {
767 print STDERR "$f:$line:1:ERROR: global scope option does not have global category\n";
768 return 2;
769 }
770 if($scope eq "global") {
771 push @desc, "\n" if(!$manpage);
772 push @desc,
773 sprintf("${pre}This option is global and does not need to be specified for each use of %s.\n",
774 manpageify("next", $manpage));
775 }
776 else {
777 print STDERR "$f:$line:1:ERROR: unrecognized scope: '$scope'\n";
778 return 2;
779 }
780 }
782 my @extra;
783 if($multi eq "single") {
784 push @extra,
785 sprintf("${pre}If %s is provided several times, the last set " .
786 "value is used.\n",
787 manpageify($long, $manpage));
788 }
789 elsif($multi eq "append") {
790 push @extra,
791 sprintf("${pre}%s can be used several times in a command line.\n",
792 manpageify($long, $manpage));
793 }
794 elsif($multi eq "boolean") {
795 my $rev = "no-$long";
796 # for options that start with "no-" the reverse is then without
797 # the no- prefix
798 if($long =~ /^no-/) {
799 $rev = $long;
800 $rev =~ s/^no-//;
801 }
802 my $dashes = $manpage ? "\\-\\-" : "--";
803 push @extra,
804 sprintf("${pre}Providing %s multiple times has no extra effect.\n" .
805 "Disable it again with $dashes$rev.\n",
806 manpageify($long, $manpage));
807 }
808 elsif($multi eq "mutex") {
809 push @extra,
810 sprintf("${pre}Providing %s multiple times has no extra effect.\n",
811 manpageify($long, $manpage));
812 }
813 elsif($multi eq "custom") {
814 ; # left for the text to describe
815 }
816 elsif($multi eq "per-URL") {
817 push @extra,
818 sprintf("${pre}%s is associated with a single URL. Use it once per URL " .
819 "when you use several URLs in a command line.\n",
820 manpageify($long, $manpage));
821 }
822 elsif($multi) {
823 print STDERR "$f:$line:1:ERROR: unrecognized Multi: '$multi'\n";
824 return 2;
825 }
827 printdesc($manpage, 2, (@leading, @desc, @extra));
828 undef @desc;
830 my @foot;
832 my $mstr;
833 my $and = 0;
834 my $num = scalar(@seealso);
835 if($num > 2) {
836 # use commas up to this point
837 $and = $num - 1;
838 }
839 my $i = 0;
840 for my $k (@seealso) {
841 if(!$helplong{$k}) {
842 print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n";
843 }
844 my $l = manpageify($k, $manpage);
845 my $sep = " and";
846 if($and && ($i < $and)) {
847 $sep = ",";
848 }
849 $mstr .= sprintf "%s$l", $mstr ? "$sep " : "";
850 $i++;
851 }
853 if($requires) {
854 my $l = manpageify($long, $manpage);
855 push @foot, "For $l to work, it requires that the underlying libcurl" .
856 " is built to support $requires.\n";
857 }
858 if($mutexed) {
859 my @m = split(/ /, $mutexed);
860 my $mstr;
861 my $num = scalar(@m);
862 my $count = 0;
863 for my $k (@m) {
864 if(!$helplong{$k}) {
865 print STDERR "WARN: $f mutexes a non-existing option: $k\n";
866 }
867 my $l = manpageify($k, $manpage);
868 my $sep = ", ";
869 if($count == ($num -1)) {
870 $sep = " and ";
871 }
872 $mstr .= sprintf "%s$l", $mstr ? $sep : "";
873 $count++;
874 }
875 push @foot, overrides($standalone,
876 "This option is mutually exclusive with $mstr.\n");
877 }
878 if($examples[0]) {
879 my $s = "";
880 $s = "s" if($examples[1]);
881 foreach my $e (@examples) {
882 my $check = $e;
883 # verify the used options
884 for my $e (split(/ /, $check)) {
885 if($e =~ /^-([^- ])/) {
886 my $opt = $1;
887 if(!$optshort{$opt}) {
888 print STDERR "$f:$line:1:ERROR: unknown option in " .
889 "example: -$opt\n";
890 return 2;
891 }
892 }
893 elsif($e =~ /^--([^ =]*)/) {
894 my $opt = $1;
895 $opt =~ s/^expand-//g;
896 if(!$helplong{$opt}) {
897 print STDERR "$f:$line:1:ERROR: unknown option in " .
898 "example: '--$opt'\n";
899 return 2;
900 }
901 }
902 }
903 }
904 if($manpage) {
905 print "\nExample$s:\n";
906 print ".nf\n";
907 foreach my $e (@examples) {
908 $e =~ s!\$URL!https://example.com!g;
909 # convert single backslashes to doubles
910 $e =~ s/\\/\\\\/g;
911 print "curl $e\n";
912 }
913 print ".fi\n";
914 }
915 else {
916 my @ex;
917 push @ex, "[0q]Example$s:\n";
918 #
919 # long ASCII examples are wrapped. Preferably at the last space
920 # before the margin. Or at a colon. Otherwise it cuts at the
921 # exact boundary.
922 #
923 foreach my $e (@examples) {
924 $e =~ s!\$URL!https://example.com!g;
925 my $maxwidth = 60; # plus the " curl " 18 col prefix
926 if(length($e) > $maxwidth) {
927 # a long example, shorten it
928 my $p = substr($e, 0, $maxwidth);
929 $p = maybespace($p);
930 push @ex, "[0q] curl " . $p . "\\";
931 $e = substr($e, length($p));
932 do {
933 my $r = substr($e, 0, $maxwidth);
934 if(length($e) > $maxwidth) {
935 $r = maybespace($r);
936 }
937 my $slash = "";
938 $e = substr($e, length($r));
939 if(length($e) > 0) {
940 $slash = "\\";
941 }
943 push @ex, "[0q] $r$slash" if($r);
944 } while(length($e));
945 }
946 else {
947 push @ex, "[0q] curl $e\n";
948 }
949 }
950 printdesc($manpage, 2, @ex);
951 }
952 }
953 if($added) {
954 push @foot, added($standalone, $added);
955 }
956 push @foot, seealso($standalone, $mstr);
958 print "\n";
959 my $ft = join("", @foot);
960 if($manpage) {
961 $ft =~ s/ +\z//; # remove trailing space
962 print "$ft\n";
963 }
964 else {
965 printdesc($manpage, 2, "[1]$ft");
966 }
967 return 0;
968}
970sub getshortlong {
971 my ($dir, $f) = @_;
972 $f =~ s/^.*\///;
973 open(F, "<:crlf", "$dir/$f") or
974 die "could not find $dir/$f";
975 my $short;
976 my $long;
977 my $help;
978 my $arg;
979 my $protocols;
980 my $category;
981 my $start = 0;
982 my $line = 0;
983 while(<F>) {
984 $line++;
985 if(!$start) {
986 if(/^---/) {
987 $start = 1;
988 }
989 next;
990 }
991 if(/^Short: (.)/i) {
992 $short = $1;
993 }
994 elsif(/^Long: (.*)/i) {
995 $long = $1;
996 }
997 elsif(/^Help: (.*)/i) {
998 $help = $1;
999 my $len = length($help);
1000 if($len >= 49) {
1001 printf STDERR "$f:$line:1:WARN: oversized help text: %d characters\n",
1002 $len;
1003 }
1004 }
1005 elsif(/^Arg: (.*)/i) {
1006 $arg = $1;
1007 }
1008 elsif(/^Protocols: (.*)/i) {
1009 $protocols = $1;
1010 }
1011 elsif(/^Category: (.*)/i) {
1012 $category = $1;
1013 }
1014 elsif(/^---/) {
1015 last;
1016 }
1017 }
1018 close(F);
1019 if($short) {
1020 $optshort{$short} = $long;
1021 }
1022 if($long) {
1023 $optlong{$long} = $short;
1024 $helplong{$long} = $help;
1025 $arglong{$long} = $arg;
1026 $protolong{$long} = $protocols;
1027 $catlong{$long} = $category;
1028 }
1029}
1031sub indexoptions {
1032 my ($dir, @files) = @_;
1033 foreach my $file (@files) {
1034 getshortlong($dir, $file);
1035 }
1036}
1038sub header {
1039 my ($dir, $manpage, $f) = @_;
1040 my $fh;
1041 open($fh, "<:crlf", "$dir/$f") or
1042 die "could not find $dir/$f";
1043 my @d = render($manpage, $fh, $f, 1);
1044 close($fh);
1045 printdesc($manpage, 0, @d);
1046}
1048sub sourcecategories {
1049 my ($dir) = @_;
1050 my %cats;
1051 open(H, "<", "$dir/../../src/tool_help.h") or
1052 die "cannot find the header file";
1053 while(<H>) {
1054 if(/^\#define CURLHELP_([A-Z0-9]*)/) {
1055 $cats{lc($1)}++;
1056 }
1057 }
1058 close(H);
1059 return %cats;
1060}
1062sub listhelp {
1063 my ($dir) = @_;
1064 my %cats = sourcecategories($dir);
1066 print <<HEAD
1067/***************************************************************************
1068 * _ _ ____ _
1069 * Project ___| | | | _ \\| |
1070 * / __| | | | |_) | |
1071 * | (__| |_| | _ <| |___
1072 * \\___|\\___/|_| \\_\\_____|
1073 *
1074 * Copyright (C) Daniel Stenberg, <daniel\@haxx.se>, et al.
1075 *
1076 * This software is licensed as described in the file COPYING, which
1077 * you should have received as part of this distribution. The terms
1078 * are also available at https://curl.se/docs/copyright.html.
1079 *
1080 * You may opt to use, copy, modify, merge, publish, distribute and/or sell
1081 * copies of the Software, and permit persons to whom the Software is
1082 * furnished to do so, under the terms of the COPYING file.
1083 *
1084 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
1085 * KIND, either express or implied.
1086 *
1087 * SPDX-License-Identifier: curl
1088 *
1089 ***************************************************************************/
1090#include "tool_setup.h"
1092#include "tool_help.h"
1094/*
1095 * DO NOT edit tool_listhelp.c manually.
1096 * This source file is generated with the following command in an autotools
1097 * build:
1098 *
1099 * "make listhelp"
1100 */
1102const struct helptxt helptext[] = {
1103HEAD
1104 ;
1105 foreach my $f (sort keys %helplong) {
1106 my $long = $f;
1107 my $short = $optlong{$long};
1108 my @categories = split(' ', $catlong{$long});
1109 my $bitmask = ' ';
1110 my $opt;
1112 if(defined($short) && $long) {
1113 $opt = "-$short, --$long";
1114 }
1115 elsif($long && !$short) {
1116 $opt = " --$long";
1117 }
1118 for my $i (0 .. $#categories) {
1119 if(!$cats{ $categories[$i] }) {
1120 printf STDERR "$f.md:ERROR: Unknown category '%s'\n",
1121 $categories[$i];
1122 exit 3;
1123 }
1125 $bitmask .= 'CURLHELP_' . uc $categories[$i];
1126 # If not last element, append |
1127 if($i < $#categories) {
1128 $bitmask .= ' | ';
1129 }
1130 }
1131 $bitmask =~ s/(?=.{75}).{1,75}\|/$&\n /g;
1132 my $arg = $arglong{$long};
1133 if($arg) {
1134 $opt .= " $arg";
1135 }
1136 my $desc = $helplong{$f};
1137 $desc =~ s/\"/\\\"/g; # escape double quotes
1139 my $line = sprintf " { \"%s\",\n \"%s\",\n %s },\n", $opt, $desc, $bitmask;
1141 if(length($opt) > 78) {
1142 print STDERR "WARN: the --$long name is too long\n";
1143 }
1144 elsif(length($desc) > 78) {
1145 print STDERR "WARN: the --$long description is too long\n";
1146 }
1147 my $ifdef = "";
1148 my $endif = "";
1150 if($long =~ /^(ipfs|httpsig)/) {
1151 $ifdef = sprintf "#ifndef CURL_DISABLE_%s\n", uc($1);
1152 $endif = "#endif\n";
1153 }
1154 print $ifdef.$line.$endif;
1155 }
1156 print <<FOOT
1157 { NULL, NULL, 0 }
1158};
1159FOOT
1160 ;
1161}
1163sub listcats {
1164 my %allcats;
1165 foreach my $f (sort keys %helplong) {
1166 my @categories = split(' ', $catlong{$f});
1167 foreach (@categories) {
1168 $allcats{$_} = undef;
1169 }
1170 }
1171 my @categories;
1172 foreach my $key (keys %allcats) {
1173 push @categories, $key;
1174 }
1175 @categories = sort @categories;
1176 for my $i (0..$#categories) {
1177 printf("#define CURLHELP_%-10s (%s)\n",
1178 uc($categories[$i]), "1 << ${i}");
1179 }
1180}
1182sub listglobals {
1183 my ($dir, @files) = @_;
1184 my @globalopts;
1186 # Find all global options and output them
1187 foreach my $f (sort @files) {
1188 open(F, "<:crlf", "$dir/$f") or
1189 die "could not read $dir/$f";
1190 my $long;
1191 my $start = 0;
1192 while(<F>) {
1193 if(/^---/) {
1194 if(!$start) {
1195 $start = 1;
1196 next;
1197 }
1198 else {
1199 last;
1200 }
1201 }
1202 if(/^Long: *(.*)/i) {
1203 $long = $1;
1204 }
1205 elsif(/^Scope: global/i) {
1206 push @globalopts, $long;
1207 last;
1208 }
1209 }
1210 close(F);
1211 }
1212 for my $e (0 .. $#globalopts) {
1213 $globals .= sprintf "%s--%s", $e ? ($globalopts[$e + 1] ? ", " : " and ") : "",
1214 $globalopts[$e],;
1215 }
1216}
1218sub noext {
1219 my $in = $_[0];
1220 $in =~ s/\.md//;
1221 return $in;
1222}
1224sub sortnames {
1225 return noext($a) cmp noext($b);
1226}
1228sub mainpage {
1229 my ($dir, $manpage, @files) = @_;
1230 # $manpage is 1 for nroff, 0 for ASCII
1231 my $ret;
1232 my $fh;
1233 open($fh, "<:crlf", "$dir/mainpage.idx") or
1234 die "no $dir/mainpage.idx file";
1236 print <<HEADER
1237.\\" **************************************************************************
1238.\\" * _ _ ____ _
1239.\\" * Project ___| | | | _ \\| |
1240.\\" * / __| | | | |_) | |
1241.\\" * | (__| |_| | _ <| |___
1242.\\" * \\___|\\___/|_| \\_\\_____|
1243.\\" *
1244.\\" * Copyright (C) Daniel Stenberg, <daniel\@haxx.se>, et al.
1245.\\" *
1246.\\" * This software is licensed as described in the file COPYING, which
1247.\\" * you should have received as part of this distribution. The terms
1248.\\" * are also available at https://curl.se/docs/copyright.html.
1249.\\" *
1250.\\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
1251.\\" * copies of the Software, and permit persons to whom the Software is
1252.\\" * furnished to do so, under the terms of the COPYING file.
1253.\\" *
1254.\\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
1255.\\" * KIND, either express or implied.
1256.\\" *
1257.\\" * SPDX-License-Identifier: curl
1258.\\" *
1259.\\" **************************************************************************
1260.\\"
1261.\\" DO NOT EDIT. Generated by the curl project managen man page generator.
1262.\\"
1263.TH curl 1 "$date" "curl $version" "curl Manual"
1264HEADER
1265 if($manpage);
1267 while(<$fh>) {
1268 my $f = $_;
1269 chomp $f;
1270 if($f =~ /^#/) {
1271 # standard comment
1272 next;
1273 }
1274 if(/^%options/) {
1275 # output docs for all options
1276 foreach my $f (sort sortnames @files) {
1277 $ret += single($dir, $manpage, $f, 0);
1278 }
1279 }
1280 else {
1281 # render the file
1282 header($dir, $manpage, $f);
1283 }
1284 }
1285 close($fh);
1286 exit $ret if($ret);
1287}
1289sub showonly {
1290 my ($dir, $f) = @_;
1291 if(single($dir, 1, $f, 1)) {
1292 print STDERR "$f: failed\n";
1293 }
1294}
1296sub showprotocols {
1297 my %prots;
1298 foreach my $f (keys %optlong) {
1299 my @p = split(/ /, $protolong{$f});
1300 for my $p (@p) {
1301 $prots{$p}++;
1302 }
1303 }
1304 for(sort keys %prots) {
1305 printf "$_ (%d options)\n", $prots{$_};
1306 }
1307}
1309sub getargs {
1310 my ($dir, $f, @s) = @_;
1311 if($f eq "mainpage") {
1312 listglobals($dir, @s);
1313 mainpage($dir, 1, @s);
1314 return;
1315 }
1316 elsif($f eq "ascii") {
1317 listglobals($dir, @s);
1318 mainpage($dir, 0, @s);
1319 return;
1320 }
1321 elsif($f eq "listhelp") {
1322 listhelp($dir);
1323 return;
1324 }
1325 elsif($f eq "single") {
1326 showonly($dir, $s[0]);
1327 return;
1328 }
1329 elsif($f eq "protos") {
1330 showprotocols();
1331 return;
1332 }
1333 elsif($f eq "listcats") {
1334 listcats();
1335 return;
1336 }
1338 print "Usage: managen " .
1339 "[-d dir] <mainpage/ascii/listhelp/single FILE/protos/listcats> [files]\n";
1340}
1342#------------------------------------------------------------------------
1344my $dir = ".";
1345my $include = "../../include";
1346my $cmd = shift @ARGV || '';
1348while(1) {
1349 if($cmd eq "-d") {
1350 # specifies source directory
1351 $dir = shift @ARGV;
1352 $cmd = shift @ARGV;
1353 }
1354 elsif($cmd eq "-I") {
1355 # include path root
1356 $include = shift @ARGV;
1357 $cmd = shift @ARGV;
1358 }
1359 elsif($cmd eq "-c") {
1360 # Column width
1361 $colwidth = 0 + shift @ARGV;
1362 $cmd = shift @ARGV;
1363 }
1364 else {
1365 last;
1366 }
1367}
1369my @files = @ARGV; # the rest are the files
1371# can be overridden for releases
1372if($ENV{'CURL_MAKETGZ_VERSION'}) {
1373 $version = $ENV{'CURL_MAKETGZ_VERSION'};
1374}
1375else {
1376 open(INC, "<", "$include/curl/curlver.h") or die "no $include/curl/curlver.h";
1377 while(<INC>) {
1378 if($_ =~ /^#define LIBCURL_VERSION \"([0-9.]*)/) {
1379 $version = $1;
1380 last;
1381 }
1382 }
1383 close(INC);
1384}
1386# learn all existing options
1387indexoptions($dir, @files);
1389getargs($dir, $cmd, @files);
1391exit $error;
Diagnostics4 git calls · 27 ms
CallStatusSizeTime027 ms
discover200152 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 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 · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=149 git.response.cache=HIT git.response.duration_ms=2 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 · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=23 git.response.bytes=293470 git.response.cache=HIT git.response.duration_ms=2 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
fetch20010 KiB · hit23 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=10552 git.response.cache=HIT git.response.duration_ms=23 git.fetch.wants=412616d41c2ef4b8e7c6e50c6f571c7b05c6870d 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=10552 git.pkt.payload.max=10531 git.sideband.band1.bytes=10530 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
- a5e2632c4e7b224d
- Request
- df7b198e…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format