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 ee9f313b9c9a17fdce01b3d7cb0db4da09e65e2d..8a4cc85bfa91be7337d770d5a74af214adb76326 100755 (executable)
--- 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