From: Pádraig Brady <P@draigBrady.com>
Date: Sat, 30 May 2026 11:05:45 +0000 (+0100)
Subject: maint: document .UR man macro
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=08207e93d89c29d4600bd0fcb845670598c1dea9;p=thirdparty%2Fcoreutils.git

maint: document .UR man macro

We currently prefer the 'tty: link' style for representing URIs
in man pages, as this falls back to _not_ displaying the URI
where not supported, whereas the .UR macro generally does fall back
to showing the URI, which has these disadvantages:
- They're long, redundant, and interfere when reading text
- With wrapping enabled with \: in the URI, it can become unclickable
- Without wrapping enabled it interferes in adjacent text justification

Note with groff >= 1.24 (March 2026), the .UR macro results
in OSC 8 hyperlinks being used, and thus the awkward URI is not
displayed.

* man/viewman: Configure groff 1.23 to display .UR macros
with OSC 8 hyperlinks.

See: https://lists.gnu.org/r/coreutils/2026-05/msg00080.html
---

diff --git a/man/viewman b/man/viewman
index ee9f313b9c..8a4cc85bfa 100755
--- a/man/viewman
+++ b/man/viewman
@@ -3,7 +3,7 @@
 # Generate and view man page with less, for passed command name
 
 # Note to get man to behave like this you can also:
-# export MANROFFOPT=-P-i
+# export MANROFFOPT='-P-i -rU1'
 # export LESS=-R
 # export MANPAGER=less
 
@@ -28,5 +28,5 @@ test "$1" = 'ginstall' && man='install'
   --loose-indent \
   "$hdir"/../src/$cmd |
 preconv | # convert utf-8 chars like in Author names to groff compat
-groff -Tutf8 -man -P-i -rLL=${MANWIDTH:-$COLUMNS}n |
+groff -Tutf8 -man -P-i -rU1 -rLL=${MANWIDTH:-$COLUMNS}n |
 less -R