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