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

Co-authored-by: Bénédikt Tran <[email protected]>

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 @@ def visit_image(self, node: Element) -> None:
 
  # 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 @@ def visit_reference(self, node: Element) -> None:
  ' <',
  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: