From e2fdbea10a4d662ddff90bad9605083e1cd63226 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <P@draigBrady.com>
Date: Mon, 29 Dec 2025 20:58:30 +0000
Subject: [PATCH] doc: help2man: convert OSC hyperlinks

* man/help2man: Convert OSC hyperlinks to roff \X escapes,
which will be converted back to OSC hyperlinks when
the man page is displayed on the terminal.
Note formatting is removed from hyperlinked text by default,
thus relying on how the terminal highlights hyperlinks,
but --bold-refs is honored in this case, in which hyperlinked
text will be marked up as bold, which matches the default
markup used for non hyperlinked options.
---
 man/help2man | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/man/help2man b/man/help2man
index 5ce8c34a3..35ff3803e 100755
--- a/man/help2man
+++ b/man/help2man
@@ -724,6 +724,19 @@ my @post = (_('ENVIRONMENT'), _('FILES'), _('AUTHOR'),
     _('REPORTING BUGS'), _('COPYRIGHT'), _('SEE ALSO'));
 my %filter = map { $_ => 1 } @pre, @post;
 
+# Global storage for OSC 8 hyperlink URLs
+our @hyperlink_urls;
+
+# Helper to convert hyperlink markers to roff \X escapes
+sub convert_hyperlink {
+    my ($dashes, $idx, $text) = @_;
+    my $url = $hyperlink_urls[$idx];
+    my $full = $dashes . $text;
+    $full =~ s/\\f[BIRP]//g;
+    $full = "\\fB$full\\fP" if $opt_bold_refs;
+    return "\\X'tty: link $url'$full\\X'tty: link'";
+}
+
 # Output content.
 my %done;
 for my $sect (@pre, (grep !$filter{$_}, @sections), @post)
@@ -751,6 +764,10 @@ for my $sect (@pre, (grep !$filter{$_}, @sections), @post)
 	    s/\x82/\\e/g;
 	    s/\x83/\\-/g;
 
+	    # Convert hyperlink markers to roff \X escape sequences
+	    s{((?:\\f.)?\\-(?:\\-)?(?:\\f.)?)\x01(\d+)\x02(.*?)\x03}
+	     {convert_hyperlink($1, $2, $3)}gse;
+
 	    # Convert some latin1 chars to troff equivalents.
 	    s/\xa0/\\ /g;  # non-breaking space
 
@@ -796,9 +813,13 @@ sub get_option_value
     # Strip ANSI SGR formatting codes (colors, bold, etc.)
     $value =~ s/\x1b\[[0-9;]*m//g;
 
-    # Strip OSC 8 hyperlinks (keep just the display text)
-    # TODO: Convert to roff \X escapes while preserving help2man's formatting
-    $value =~ s/\x1b\]8;;[^\x07]*\x07(.*?)\x1b\]8;;\x07/$1/gs;
+    # Convert OSC 8 hyperlinks to markers placed after leading dashes
+    # This preserves help2man's option detection (which looks for /^  +[-+]/)
+    $value =~ s/\x1b\]8;;([^\x07]*)\x07(--?)(.*?)\x1b\]8;;\x07/{
+        my $idx = scalar @hyperlink_urls;
+        push @hyperlink_urls, $1;
+        "$2\x01$idx\x02$3\x03";
+    }/gse;
 
     $value;
 }