From: Daniel Stenberg Date: Wed, 17 Sep 2025 09:53:33 +0000 (+0200) Subject: managen: render better manpage references/links X-Git-Tag: rc-8_17_0-1~368 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=dbe4e28d57f76b5ad96241bc5865d043679575d8;p=thirdparty%2Fcurl.git managen: render better manpage references/links - When an option name is used in text, this script no longer outputs the short plus long version in the manpage output. It makes the text much more readable. This always showing both verions was previously done primarily to make sure roffit would linkify it correctly, but since roffit 0.17 it should link both long or short names correctly. - When managen outputs generic text about options at the end of the description it now highlights them properly so that they too get linkified correctly in the HTML version. For consistency. Closes #18580 --- diff --git a/scripts/managen b/scripts/managen index 768c632d4b..9290680670 100755 --- a/scripts/managen +++ b/scripts/managen @@ -66,8 +66,7 @@ my $indent = 4; # get the long name version, return the manpage string sub manpageify { - my ($k)=@_; - my $l; + my ($k, $manpage)=@_; my $trail = ''; # the matching pattern might include a trailing dot that cannot be part of # the option name @@ -75,18 +74,15 @@ sub manpageify { # cut off trailing dot $trail = "."; } - my $klong = $k; - # quote "bare" minuses in the long name - $klong =~ s/-/\\-/g; - if($optlong{$k}) { - # both short + long - $l = "\\fI-".$optlong{$k}.", \\-\\-$klong\\fP$trail"; - } - else { + if($manpage) { + my $klong = $k; + # quote "bare" minuses in the long name + $klong =~ s/-/\\-/g; + # only long - $l = "\\fI\\-\\-$klong\\fP$trail"; + return "\\fI\\-\\-$klong\\fP$trail"; } - return $l; + return "--$k$trail"; } @@ -477,7 +473,7 @@ sub render { if($manpage) { if(!$quote && $d =~ /--/) { - $d =~ s/--([a-z0-9.-]+)/manpageify($1)/ge; + $d =~ s/--([a-z0-9.-]+)/manpageify($1, 1)/ge; } # quote minuses in the output @@ -741,7 +737,9 @@ sub single { } if($scope eq "global") { push @desc, "\n" if(!$manpage); - push @desc, "${pre}This option is global and does not need to be specified for each use of --next.\n"; + push @desc, + sprintf("${pre}This option is global and does not need to be specified for each use of %s.\n", + manpageify("next", $manpage)); } else { print STDERR "$f:$line:1:ERROR: unrecognized scope: '$scope'\n"; @@ -751,11 +749,15 @@ sub single { my @extra; if($multi eq "single") { - push @extra, "${pre}If --$long is provided several times, the last set ". - "value is used.\n"; + push @extra, + sprintf("${pre}If %s is provided several times, the last set ". + "value is used.\n", + manpageify($long, $manpage)); } elsif($multi eq "append") { - push @extra, "${pre}--$long can be used several times in a command line\n"; + push @extra, + sprintf("${pre}%s can be used several times in a command line\n", + manpageify($long, $manpage)); } elsif($multi eq "boolean") { my $rev = "no-$long"; @@ -767,20 +769,23 @@ sub single { } my $dashes = $manpage ? "\\-\\-" : "--"; push @extra, - "${pre}Providing --$long multiple times has no extra effect.\n". - "Disable it again with $dashes$rev.\n"; + sprintf("${pre}Providing %s multiple times has no extra effect.\n". + "Disable it again with $dashes$rev.\n", + manpageify($long, $manpage)); } elsif($multi eq "mutex") { push @extra, - "${pre}Providing --$long multiple times has no extra effect.\n"; + sprintf("${pre}Providing %s multiple times has no extra effect.\n", + manpageify($long, $manpage)); } elsif($multi eq "custom") { ; # left for the text to describe } elsif($multi eq "per-URL") { push @extra, - "${pre}--$long is associated with a single URL. Use it once per URL ". - "when you use several URLs in a command line.\n"; + sprintf("${pre}%s is associated with a single URL. Use it once per URL ". + "when you use several URLs in a command line.\n", + manpageify($long, $manpage)); } else { print STDERR "$f:$line:1:ERROR: unrecognized Multi: '$multi'\n"; @@ -804,7 +809,7 @@ sub single { if(!$helplong{$k}) { print STDERR "$f:$line:1:WARN: see-also a non-existing option: $k\n"; } - my $l = $manpage ? manpageify($k) : "--$k"; + my $l = manpageify($k, $manpage); my $sep = " and"; if($and && ($i < $and)) { $sep = ","; @@ -814,7 +819,7 @@ sub single { } if($requires) { - my $l = $manpage ? manpageify($long) : "--$long"; + my $l = manpageify($long, $manpage); push @foot, "$l requires that libcurl". " is built to support $requires.\n"; } @@ -827,7 +832,7 @@ sub single { if(!$helplong{$k}) { print STDERR "WARN: $f mutexes a non-existing option: $k\n"; } - my $l = $manpage ? manpageify($k) : "--$k"; + my $l = manpageify($k, $manpage); my $sep = ", "; if($count == ($num -1)) { $sep = " and "; diff --git a/tests/data/test1705 b/tests/data/test1705 index b56982ae40..7c21ffa349 100644 --- a/tests/data/test1705 +++ b/tests/data/test1705 @@ -224,9 +224,9 @@ End with a quote hello .fi -This option is global and does not need to be specified for each use of --next. +This option is global and does not need to be specified for each use of \fI\-\-next\fP. -Providing --fakeitreal multiple times has no extra effect. +Providing \fI\-\-fakeitreal\fP multiple times has no extra effect. Disable it again with \-\-no-fakeitreal. Example: @@ -265,14 +265,14 @@ relying upon support for that protocol being built into curl to avoid an error. This option can be used multiple times, in which case the effect is the same as concatenating the protocols into one instance of the option. -If --proto is provided several times, the last set value is used. +If \fI\-\-proto\fP is provided several times, the last set value is used. Example: .nf curl --proto =http,https,sftp https://example.com .fi -See also \fI-v, \-\-fakeitreal\fP and \fI\-\-proto\-default\fP. +See also \fI\-\-fakeitreal\fP and \fI\-\-proto\-default\fP. .SH PROXY PROTOCOL PREFIXES The proxy string may be specified with a protocol:// prefix to specify alternative proxy protocols.