On 20/12/2025 21:16, Egmont Koblinger wrote:
Hi Pádraig, others,
Thanks for the heads-up, and for this work!
tl;dr with the attached you can follow links from: src/ls --help
I love this feature and would love to see more utilities adopting it
(not just within coreutills but much more broadly). Although, as one
of the key people in implementing and popularizing the weblink feature
of terminals, I am definitely biased :)
Having each --option hyperlinked also gives a visual distinction
between the --option text and description, which makes --help
quite a bit easier to read IMHO.
Speaking of visuals, you've also changed the affected text to have
bold typeface. I have mixed feelings about it. On one hand, I really
like the resulting visual look. On the other hand, it shouldn't be
necessary, terminals _should_ somehow denote if the given text is a
hyperlink.
Which means: I'd love the bold typeface feature if it was independent
from the hyperlink, as in: independent decision to wish for that look,
not for the sake of emphasizing the hyperlink, and preferably a
separate commit. I wouldn't like it that much if its purpose was to
emphasize that the given text is clickable, that's the terminal's job
to pick a certain look for that.
Agreed. I've made the bold format conditional on the existing
./configure --disable-bold-man-page-references setting.
We only output --option links if stdout is a tty currently,
though it would be nice to support piping to e.g., less -R.
Perhaps keying on stdin would be better then, or maybe support --help[=WHEN],
though options on --help do seem like overkill.
I understand your dilemma and it's surely not an easy question.
Another possibility is to piggyback on the existing --hyperlink
feature. This way existing aliases (e.g. alias ls='ls --hyperlink')
would work. But this also takes us to the question of the _default_
value.
Currently ls defaults to no hyperlinks when listing regular files, but
(with this patch) to do use hyperlinks in --help. Would you prefer to
keep it this way? I think if the main operation doesn't use hyperlinks
or colors by default (it's left for aliases to enable them) then it's
reasonable for --help to follow that, too. Also, using bold typeface
isn't subject to --color in --help, that's another inconsistency
between --help vs. real operation.
It would be preferable to find a solution that scales well to other
tools, including non-coreutils ones, e.g. grep with its already
existing --color similarly to ls.
I don't have a firm opinion what would be a great solution here, but I
think reusing --hyperlink (or introducing it to other tools) might be
a viable option.
But then again, _if_ you choose to go bold too, then would you need
two options (--hyperlink=... and --color=...) to turn on/off them
both? Doesn't sound that great. Surely a single option controlling
them would be better.
I've gone with always outputting the ansi codes,
as really all that post processes --help is help2man
and I've adjusted that to handle all output formats.
Any further grepping/paging should work fine with the codes.
This will result in each option being translated separately.
That seems better anyway, and is something we've already been
gradually adjusting to over the last few years.
Many of the existing translations will not need to change.
Would it be reasonable to split existing translations in a
(semi-)automated way, so that translators don't have to manually do
this (and possibly introduce new wording)?
I've not looked into propagating these URLs to man pages.
It would be useful if man pages did support it, but after a very
quick search it seems that they might not, which is fine but a pity.
Man pages do support weblinks, see
https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html
grep for \X'tty in your manuals, e.g. dig(1) / nsupdate(1) have links
to RFCs in their SEE ALSO section, just to randomly pick one out of
maybe a handful of matching packages on my system.
Ah cool. It was relatively easy to adjust help2man with the 2 attached patches
to convert from these OSC hyperlinks to roff \X escapes.
Thanks for the input, it was really helpful.
cheers,
Padraig
From 6fb4b55bc5ccea0e36a44fd4a6ad17bca984a88c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Mon, 29 Dec 2025 16:46:15 +0000
Subject: [PATCH 1/2] doc: help2man: strip ANSI codes
* man/help2man: With these ANSI codes, output is corrupted,
so it's best to strip these, which allows --help to
outputting formatting and hyperlinks by default.
---
man/help2man | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/man/help2man b/man/help2man
index e021ff8dc..37e02333a 100755
--- a/man/help2man
+++ b/man/help2man
@@ -793,6 +793,13 @@ sub get_option_value
kark $err, $this_program, $opt, $prog, $extra;
}
+ # 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;
+
$value;
}
--
2.52.0
From 627bc63f89abd221ccf42a00c15b46f321f1f74a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Mon, 29 Dec 2025 20:58:30 +0000
Subject: [PATCH 2/2] 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 | 26 +++++++++++++++++++++++---
1 file changed, 23 insertions(+), 3 deletions(-)
diff --git a/man/help2man b/man/help2man
index 37e02333a..262e06d04 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,9 @@ 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 +812,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;
}
--
2.52.0
