[groff] 04/04: [man]: Use OSC 8 hyperlinks.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5c250cc6e79c998135b5c30582d28d9565693846
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Oct 1 21:43:31 2021 +1000

    [man]: Use OSC 8 hyperlinks.
    
    * tmac/an.tmac: Add registers `mY` (output driver is "grotty") and `U`
      (generate hyperlinks).  `U` is intended to apply to hyperlinking
      support in general, not just grotty's OSC 8 feature.  If the output
      driver is either grohtml or grotty, make `U` true (`man.local` is read
      subsequently and can override it).
    
      (UR, MT): Conditionalize diversion production on hyperlink support,
      not grohtml use per se.
    
      (UE, ME): Generate device control commands for `tty` device to emit
      hyperlinks.
    
    * tmac/groff_man.7.man.in (Options): Document -U.
    
      (Files) [style]: Add example of `U` register enablement.
    
    * tmac/man.local: Disable `U` register by default, except on the `html`
      device.
    
    * NEWS: Add item.
---
 ChangeLog               | 22 ++++++++++++++++++++++
 NEWS                    |  8 ++++++++
 tmac/an-ext.tmac        | 50 +++++++++++++++++++++++++++++++++++++------------
 tmac/groff_man.7.man.in | 42 +++++++++++++++++++++++++++++++++--------
 tmac/man.local          |  5 +++++
 5 files changed, 107 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f1c5fca..0663091 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,27 @@
 2021-10-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       [man]: Use OSC 8 hyperlinks.
+
+       * tmac/an.tmac: Add registers `mY` (output driver is "grotty")
+       and `U` (generate hyperlinks).  `U` is intended to apply to
+       hyperlinking support in general, not just grotty's OSC 8
+       feature.  If the output driver is either grohtml or grotty, make
+       `U` true (`man.local` is read subsequently and can override it).
+       (UR, MT): Conditionalize diversion production on hyperlink
+       support, not grohtml use per se.
+       (UE, ME): Generate device control commands for `tty` device to
+       emit hyperlinks.
+
+       * tmac/groff_man.7.man.in (Options): Document -U.
+       (Files) [style]: Add example of `U` register enablement.
+
+       * tmac/man.local: Disable `U` register by default, except on the
+       `html` device.
+
+       * NEWS: Add item.
+
+2021-10-01  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        [grotty]: Add OSC 8 hyperlink support.
 
        * src/devices/grotty/tty.cpp: Do it.  Define `OSC` (Operating
diff --git a/NEWS b/NEWS
index 2ef7d9c..4eebea1 100644
--- a/NEWS
+++ b/NEWS
@@ -122,6 +122,14 @@ o The new rfc1345 macro package, contributed by Dorai 
Sitaram, defines
   some additions from Vim, which itself uses RFC 1345 for its digraphs).
   It is documented in the groff_rfc1345(7) man page.
 
+o The an (man) macro package can now produce clickable hyperlinks within
+  terminal emulators, using the OSC 8 support added to grotty(1) (see
+  below).  The groff man(7) extension macros "UR" and "MT", present
+  since 2007, expose this feature.  At present the feature is disabled
+  by default in "man.local" pending more widespread recognition of OSC 8
+  sequences in pager programs.  The package now recognizes a "U"
+  register to configure hyperlink support for any output driver.
+
 o Part of the an (man) macro package has been renamed from "an-old.tmac"
   to "an.tmac", replacing a file that sourced the "andoc.tmac" wrapper.
   This means that the "-man" argument to groff (or nroff, or troff) will
diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac
index 956d288..4726e77 100644
--- a/tmac/an-ext.tmac
+++ b/tmac/an-ext.tmac
@@ -1,6 +1,6 @@
 .\" an-ext.tmac
 .\"
-.\" Copyright (C) 2007-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 2007-2021 Free Software Foundation, Inc.
 .\"
 .\" Written by Eric S. Raymond <esr@thyrsus.com>
 .\"            Werner Lemberg <wl@gnu.org>
@@ -26,11 +26,17 @@
 .if \n(mX>1 \
 .  nx
 .
-.\" Check whether we are using grohtml.
+.\" Check if we're using grohtml or grotty, and therefore support URIs.
 .nr mH 0
-.if \n(.g \
+.nr mY 0
+.nr U 0
+.if \n(.g \{\
 .  if '\*(.T'html' \
 .    nr mH 1
+.  if '\*(.T'utf8' \
+.    nr mY 1
+.  nr U \n(mH+\n(mY
+.\}
 .
 .
 .\" Map mono-width fonts to standard fonts for groff's TTY device.
@@ -88,7 +94,7 @@
 .\" Start URL.
 .de UR
 .  ds m1 \\$1\"
-.  if \\n(mH \{\
+.  if \\nU \{\
 .    \" Start diversion in a new environment.
 .    do ev link-text-env
 .    do di link-text-div
@@ -98,22 +104,32 @@
 .
 .\" End URL.
 .de UE
-.  ie \\n(mH \{\
+.  ie \\nU \{\
 .    br
 .    di
 .    ev
 .
-.    \" Has there been one or more input lines for the link text?
+.    \" Has there been at least one input line of hyperlinked text?
 .    ie \\n(dn \{\
+.      if \\n(mH \
 \X^html:<a href="\\*(m1">^\c
-.      \" Yes, strip off final newline of diversion and emit it.
+.      if \\n(mY \
+\X^tty: link \\*(m1^\c
+.      \" Strip off the final newline of the diversion and emit it.
 .      do chop link-text-div
 .      do link-text-div
 \c
+.      if \\n(mH \
 \X^html:</a>^\c
+.      if \\n(mY \
+\X^tty: link^\c
 .    \}
-.    el \
+.    el \{\
+.      if \\n(mH \
 \X^html:<a href="\\*(m1">\\*(m1</a>^\c
+.      if \\n(mY \
+\X^tty: link \\*(m1^\\*(m1\X^tty: link^\c
+.    \}
 \&\\$*\"
 .  \}
 .  el \{\
@@ -129,7 +145,7 @@
 .\" Start email address.
 .de MT
 .  ds m1 \\$1\"
-.  if \\n(mH \{\
+.  if \\nU \{\
 .    \" Start diversion in a new environment.
 .    do ev link-text-env
 .    do di link-text-div
@@ -139,22 +155,32 @@
 .
 .\" End email address.
 .de ME
-.  ie \\n(mH \{\
+.  ie \\nU \{\
 .    br
 .    di
 .    ev
 .
-.    \" Has there been one or more input lines for the link text?
+.    \" Has there been at least one input line of hyperlinked text?
 .    ie \\n(dn \{\
+.      if \\n(mH \
 \X^html:<a href="mailto:\\*(m1">^\c
+.      if \\n(mY \
+\X^tty: link mailto:\\*(m1^\c
 .      \" Yes, strip off final newline of diversion and emit it.
 .      do chop link-text-div
 .      do link-text-div
 \c
+.      if \\n(mH \
 \X^html:</a>^\c
+.      if \\n(mY \
+\X^tty: link^\c
 .    \}
-.    el \
+.    el \{\
+.      if \\n(mH \
 \X^html:<a href="mailto:\\*(m1">\\*(m1</a>^\c
+.      if \\n(mY \
+\X^tty: link mailto:\\*(m1^\\*(m1\X^tty: link^\c
+.    \}
 \&\\$*\"
 .  \}
 .  el \{\
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index fb855c0..046c815 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1155,10 +1155,10 @@ argument to
 is placed at the end of the link text without intervening space.
 .
 .I address
-may not be visible in the output text,
-particularly if the man page is being viewed as HTML.
+may not be visible in the rendered document if the output driver
+supports hyperlinks.
 .
-On a device that is not a browser,
+If it does not,
 .I address
 is set in angle brackets after the link text and before
 .IR punctuation .
@@ -1168,7 +1168,7 @@ _ifstyle()dnl
 .IP
 When rendered by
 .I groff
-to a terminal or PostScript device,
+to a PostScript device,
 .RS
 .IP
 .EX
@@ -1216,10 +1216,10 @@ argument to
 is placed at the end of the link text without intervening space.
 .
 .I URL
-may not be visible in the output text,
-particularly if the man page is being viewed as HTML.
+may not be visible in the rendered document if the output driver
+supports hyperlinks.
 .
-On a device that is not a browser,
+If it does not,
 .I URL
 is set in angle brackets after the link text and before
 .IR punctuation .
@@ -1229,7 +1229,7 @@ _ifstyle()dnl
 .IP
 When rendered by
 .I groff
-to a terminal or PostScript device,
+to a PostScript device,
 .RS
 .IP
 .EX
@@ -3149,6 +3149,30 @@ default.
 .
 .
 .TP
+.B \-rU1
+Enable generation of URI hyperlinks in the
+.I grohtml
+and
+.I grotty
+output drivers.
+.
+.I grohtml
+enables them by default;
+.I grotty
+does not,
+pending more widespread pager support for OSC\~8 escape sequences.
+.
+Use
+.B \-rU0
+to disable hyperlinks;
+this will make the arguments to
+.B MT
+and
+.B UR
+calls visible in the document text produced by link-capable drivers.
+.
+.
+.TP
 .BI \-rX p
 After
 .RI page\~ p ,
@@ -3296,6 +3320,8 @@ _ifstyle()dnl
 \&.ss 12 0 \e" See groff(@MAN7EXT@).
 \&.\e" Keep pages narrow even on wide terminals.
 \&.if n .if \(rsn[LL]>78 .nr LL 78n
+\&.\e" Ensure hyperlinks are enabled for terminals.
+\&.nr U 1
 .EE
 .RE
 .RE
diff --git a/tmac/man.local b/tmac/man.local
index 8cb0be2..83cec5c 100644
--- a/tmac/man.local
+++ b/tmac/man.local
@@ -2,3 +2,8 @@
 .\"
 .\" This file is loaded after an.tmac.
 .\" Put any local modifications to an.tmac here.
+.\"
+.\" Change "0" to "1" to enable OSC 8 links on SGR-capable grotty(1)
+.\" output devices.
+.if !'\*[.T]'html' \
+.  nr U 0