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 768c632d4bdf4cc15db54064a37bbd7bad5a9532..9290680670991b42ec5c3b4f5d4e52367c4f0e94 100755 (executable)
--- 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 b56982ae40f51c3d8ce1421b304c59fa6bb4239a..7c21ffa3493999942b92790e01c2abdb2efe5aa5 100644 (file)
--- 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.