Hi Pádraig, At 2026-05-30T09:53:01+0100, Pádraig Brady wrote: > TIL man:foo(1) links are supported and on my system, redirect to > gnome-help 'man:foo(1)'
Yes! The `MR` man(7) macro, new to groff 1.23.0 (July 2023) makes their
generation nearly seamless.
groff_man(7):
.MR topic [manual‐section [trailing‐text]]
(since groff 1.23) Set a man page cross reference as
“topic(manual‐section)”. If manual‐section is absent, the
package omits the surrounding parentheses. If trailing‐text
(typically punctuation) is specified, it follows the closing
parenthesis without intervening space. Hyphenation is
disabled while the cross reference is set. topic is set in
the font specified by the MF string. If manual‐section is
present, the cross reference hyperlinks to a URI of the form
“man:topic(manual‐section)”.
...and as you noticed, this works just fine with terminal emulators that
interpret OSC 8 escape sequences and have handlers for the "man" schema.
With respect to _this_ feature--the `MR` macro--and not others, some
consideration to non-groff deployments, or deployments of groff 1.22.4
or earlier must be given, due to the semantics of undefined macros in
*roff formatters (arguments are discarded). groff's own man pages
"protect" themselves from mis-rendering by old versions of itself.[0]
> > So in your case you want to either edit "/etc/groff/man.local" (and
> > likely "/etc/groff/mdoc.local" too) to add:
> >
> > .nr U 1
> >
> > or, if you're using man-db man(1):
> >
> > export MANROFFOPT=-rU1
> >
> > Either should suffice to turn on the OSC 8 hyperlinks.
>
> Ah right.
> 1.24 was released March 2026, so too new to rely on that behavior yet.
Well, the _register_ is supported since groff 1.23, and setting it to
any value is a harmless no-op in any version of groff that doesn't
recognize it.
> We really want to avoid displaying the actual URL because:
> - It's long, redundant, and interferes when reading text
I get what you're saying but it's hard to solve this problem in a man(7)
document's source.
First, it's noisy and strains portability to write *roff control
structures to alter formatted output based on the identity of the output
device. Admittedly, one of groff's own man pages does this in one
place.
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/contrib/gpinyin/gpinyin.1.man?h=1.24.1#n246
Second, there is at present no way to express a conditional in the
document source branching based on a terminal device's support for
hyperlinking. Even the path to getting to such a state is unclear and
is going to require much coöperation from projects other than groff,
like ncurses (to define a "user capability" for OSC 8 support[1]) and
authors of terminal emulators.
And authors of certain...shall we say, "fashionable" new terminal
emulators...have an established track record of alternately breaking
terminfo API conventions and commanding Thomas Dickey to adapt to their
stated needs without much evident understanding of how terminfo
works.[4]
> - With wrapping enabled with \: in the URI, it can become unclickable
The initial part of it, prior to the first break, should always remain
clickable. It's up to the application (terminal emulator) to "make hot"
the text on subsequent lines until the "link closing" OSC 8 syntax is
encountered.
Historically, there has been some disagreement in the *nix community
over whether SGR sequences should be treated as automatically
self-disabling at the end of a line in the terminal emulator (an implied
"tput sgr0", or not.
The latter approach is more block-structured and more closely resembles
HTML. It's also more economical in terms of the bandwidth consumed by
the data channel to the (emulated) device, but the bandwidth available
to such devices hasn't been a barrier for most of the period during
which SGR escape sequences, for say, setting foreground and background
colors have come to be commonly observed in terminal sessions.
(Possibly, I am confusing cause and effect.)
The former approach is _much_ nicer for users of diff(1), and given
Unix's strong line-orientation in its tooling tradition, I lean that
way myself.
I _could_ in fact alter grotty(1) to synthesize and reissue the OSC 8
link sequence when a hyperlink breaks across lines. In fact, doing so
would handle such line-continued hyperlinks more intelligently than
gnome-terminal(1) et al., because grotty knows where the "words" on a
line in the document begin with greater reliability than a terminal
emulator. (Further, we have an auxiliary data channel available between
the formatter, GNU troff(1) and grotty, and the formatter knows with
_absolute_ reliability where the words are on a page, because that
information is central to its mission.)
On the third hand, a terminal emulator can recognize leading spaces in
the character cells of a line of its own rendering window pretty easily,
and I know of no one actually complaining about them getting marked up
as "hot" with a hyperlink.
So far, the crude method of marking up the spaces on a line and making
them "hot", as I've seen in gnome-terminal, hasn't bothered me more than
a tiny bit, and no one has requested the foregoing speculative feature.
> - Without wrapping enabled it interferes in adjacent text justification
Yes. This is a problem with any lengthy unbreakable text.[2] URLs have
been a headache for professional writing for over a generation.[3]
> So we may use the more abstract .UR in future,
> but I don't think it's the best option currently.
Because you can't know whether the URLs you write in a document will
appear as formatted text or not, and the answer to that question can
vary from one user command to the next in a terminal session:
$ man -Tpdf ls
$ man ls
$ MANROFFOPT=-rU1 man ls
...my advice to you is to delegate the problem to the `UR` macro and let
the rendering environment figure out what to do. An ugly URL formatted
as text is often better than a URL that has disappeared without a trace.
> I will add some notes and TODOs though.
Please hit me with any questions or challenges to my reasoning. :)
Regards,
Branden
[0]
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/src/utils/addftinfo/addftinfo.1.man?h=1.24.1#n35
[1] https://invisible-island.net/ncurses/man/user_caps.5.html
[2] https://www.gnu.org/software/groff/manual/groff.html.node/Breaking.html
[3]
"Guidelines on Breaking
As long as the URL is accurately recorded, writers of unpublished
material should not worry about how a URL breaks. To ensure that a URL
is accurately reproduced, never introduce a hyphen or space in it. Note
that the freely available formatting guidelines on this site advise
writers to turn off their word processors’ automatic hyphenation
features for just this reason.
Professionally typeset publications in fixed formats, like print or PDF,
normally follow rigorous conventions for breaking URLs. Publishers vary
in their practices. In its own professionally typeset publications, the
MLA breaks URLs before a period and before or after any other
punctuation or symbol (e.g., /, //, _, @). We do not break URLs after a
hyphen in such publications, to avoid ambiguity."
https://style.mla.org/urls-some-practical-advice/
groff offers its own advice.
groff_man_style(7):
Hyperlink macros
...
Prepare arguments to MR, MT, and UR for typesetting; they can
appear in the output. Use special character escape sequences to
encode Unicode basic Latin characters where necessary, particularly
the hyphen‐minus. (See subsection “Portability” below.) URIs can
be lengthy; rendering them can result in jarring adjustment or
variations in line length, or troff warnings when one is longer
than an output line. The application of non‐printing break point
escape sequences \: after each slash (or series thereof), and
before each dot (or series thereof) is recommended as a rule of
thumb. The former practice avoids forcing a trailing slash in a
URI onto a separate output line, and the latter helps the reader to
avoid mistakenly interpreting a dot at the end of a line as a
period (or multiple dots as an ellipsis). Thus,
.UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
has several potential break points in the URI shown. Consider
adding break points before or after at signs in email addresses,
and question marks, ampersands, and number signs in HTTP(S) URIs.
[4] https://lists.gnu.org/archive/html/bug-ncurses/2018-09/msg00011.html
signature.asc
Description: PGP signature
