[manpage] emit OSC 8 hyperlinks via groff (#12108)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

CHANGES.rst

@@ -35,6 +35,12 @@ Features added
 * #11981: Improve rendering of signatures using ``slice`` syntax,
   e.g., ``def foo(arg: np.float64[:,:]) -> None: ...``.
 
+* The manpage builder now adds `OSC 8`_ anchors to hyperlinks, using
+  the `groff`_ device control command.
+
+  .. _OSC 8: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
+  .. _groff: https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html
+
 Bugs fixed
 ----------
 

sphinx/writers/manpage.py

@@ -308,13 +308,17 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):
 
     # overwritten -- don't visit inner marked up nodes
     def visit_reference(self, node: Element) -> None:
+        uri = node.get('refuri', '')
+        if uri:
+            # OSC 8 link start (using groff's device control directive).
+            self.body.append(fr"\X'tty: link {uri}'")
+
         self.body.append(self.defs['reference'][0])
         # avoid repeating escaping code... fine since
         # visit_Text calls astext() and only works on that afterwards
         self.visit_Text(node)  # type: ignore[arg-type]
         self.body.append(self.defs['reference'][1])
 
-        uri = node.get('refuri', '')
         if uri.startswith(('mailto:', 'http:', 'https:', 'ftp:')):
             # if configured, put the URL after the link
             if self.config.man_show_urls and node.astext() != uri:
@@ -324,6 +328,9 @@ class ManualPageTranslator(SphinxTranslator, BaseTranslator):
                     ' <',
                     self.defs['strong'][0], uri, self.defs['strong'][1],
                     '>'])
+        if uri:
+            # OSC 8 link end.
+            self.body.append(r"\X'tty: link'")
         raise nodes.SkipNode
 
     def visit_number_reference(self, node: Element) -> None: