git-market/curl-curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-04-11 12:01:42 +08:00
Code Issues Actions 14 Packages Projects Releases Wiki Activity

managen: render better manpage references/links

Browse Source 
- 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
This commit is contained in:
Daniel Stenberg 2025-09-17 11:53:33 +02:00
parent 0a27a506b1
commit dbe4e28d57
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
2 changed files with 34 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
scripts/managen
View File

@ -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 ";

8
tests/data/test1705
View File

@ -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.