[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: We have OSC 8 terminal hyperlink support now
From: |
John Gardner |
Subject: |
Re: We have OSC 8 terminal hyperlink support now |
Date: |
Sat, 2 Oct 2021 14:24:08 +1000 |
Hi Brandon,
That's one small step for a man... one giant leap for man(1)-kind. ;-)
Brilliant work!
I can't wait to update Mono.tmac <http://github.com/Alhadis/Mono.tmac> to
include it! Is there any reliable way for a macro-package to detect support
for this at runtime?
Also, I spotted a typo in the third sentence under the description of \X'tty:
link [uri [key=value] ...]'
When uri is *is* present,
>
s/(is )\K\1//;
— John
On Sat, 2 Oct 2021 at 14:02, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:
> Hi all,
>
> I'm pleased to report that I've landed a new feature in groff Git HEAD.
>
> The grotty(1) output driver now recognizes a new "link" device control
> subcommand and uses it to synthesize ECMA-48 OSC 8 escape sequences to
> pass hyperlink information to the terminal device. This means that, on
> terminal emulators that support OSC 8, groff documents can embed
> clickable hyperlinks.
>
> I tested this feature with gnome-terminal 3.30.2. (My daily driver,
> xterm, doesn't support OSC 8 yet.)
>
> Here's how I've documented it in grotty(1). It's linked with SGR
> support, another ECMA-48 feature.
>
> [...]
> By default, grotty emits SGR escape sequences (from ISO 6429,
> popularly called “ANSI escapes”) to change text attributes (bold,
> italic, underline, reverse-video, and colors). Devices support‐
> ing the appropriate sequences can view roff documents using eight
> different background and foreground colors. Following ISO 6429,
> the following colors are defined in tty.tmac: black, white, red,
> green, blue, yellow, magenta, and cyan. Unrecognized colors are
> mapped to the default color, which is dependent on the settings
> of the terminal. OSC 8 hyperlinks are produced for these de‐
> vices.
> [...]
> SGR and OSC support in pagers
> When paging grotty’s output with less(1), the latter program must
> be instructed to pass SGR and OSC sequences through to the de‐
> vice; its -R option is one way to achieve this (less version 566
> or later is required for OSC 8 support). Consequently, programs
> like man(1) which page roff documents with less must call it with
> an appopriate option.
> [...]
> Device control commands
> grotty understands the following device control functions pro‐
> duced using the roff \X escape sequence in a document.
>
> \X'tty: link [uri [key=value] ...]'
> Embed a hyperlink using the OSC 8 terminal escape se‐
> quence. Specifying uri starts hyperlinked text, and omit‐
> ting it ends the hyperlink. When uri is is present, any
> number of additional key/value pairs can be specified;
> their interpretation is the responsibility of the terminal
> emulator. Spaces or tabs cannot appear literally in uri,
> key, or value; they must be represented in an alternate
> form.
> [...]
> Options
> [...]
> -c Use grotty’s legacy output format (see subsection “Legacy
> output format” above). OSC 8 hyperlink terminal escape
> sequences are not emitted.
> [...]
>
> Having already thus belabored the point, I trust the reader to infer
> that setting $GROFF_NO_SGR will also prevent the emission of OSC 8
> escape sequences. (I say it here for the sake of future web searches.)
>
> People who maintain their own macro packages or eschew their use can put
> grotty(1)'s OSC 8 support to work immediately; it's a "git pull" away.
>
> To further demonstrate this feature, I have enhanced the groff man(7) UR
> and MT macro ("URL" and "mailto") implementations to use device control
> escape sequences to exercise it. As planned and desired, this required
> to changes to any man page text; the hyperlinks simply appear. When
> rendered, the link content will no longer be formatted as output (the
> hyperlinked _text_ of course, if any, will continue to be).
>
> The lack of universal support for OSC 8 and the absence of a means for
> the formatter to query terminal capabilities at runtime (a major
> architectural challenge given *roff design) however, means that I have
> disabled our man(7) implementation's use of the aforementioned device
> control by default for the time being, in the man.local file.
>
> Moreover, lack of terminal emulator support isn't even the biggest
> problem facing this feature; well-coded terminal emulators silently
> ignore OSC escape sequences they don't understand. Unfortunately,
> another party often interposes itself in communications between
> grotty(1) and the terminal device--that would be the pager. less(1)
> only developed OSC 8 support in version 566, released about one year
> ago. Versions prior to that misinterpreted the OSC 8 escape sequence
> and would write parts of it to the terminal window, an unsightly mess
> that would be sure to displease users. I haven't checked, but I fear
> that the behavior of other pagers (more, most, pg--are there others?) is
> similarly poor, and, worse, that their development is moribund.
>
> I expect and encourage groff users, particularly OS distributors, to
> survey their systems' pager and terminal emulator offerings and delete
> the only non-comment lines in the man.local we ship to expose this handy
> feature to users.
>
> The means of this support is a new register, "U", recognized by our
> man(7) implementation. You can think of it as mnemonic for "URL
> support". For orthogonality I applied its recognition to our man(7)
> support for the "html" output device as well. (It is thus now possible
> to render to HTML without hyperlinked text[1].)
>
> Future Directions
> -----------------
>
> Obvious next steps to me include:
>
> (1) Hook up our man(7) UR and MT macros to gropdf(1).
> (2) It might be nice to make this "link" device control command
> applicable across output drivers. Maybe we could promote "link" to
> a "name space" instead of having it be device-specific, then have
> grohtml(1), grotty(1), and gropdf(1) all support it with a common
> syntax.
> (3) Get the feature working with other macro packages when they render
> in nroff mode. ms(7) has no native support for hyperlinks, but our
> "www" package, demonstrated in out example document "webpage.ms",
> continues to work, so I reckon that would be the first place to
> hack.
> (4) Work on the man(7) MR macro for man page cross references, using the
> "man:" schema by default to avoid file name resolution issues.
>
> I appreciate feedback, including suggestions regarding relative
> priorities of the next steps (or additions to that list).
>
> Regards,
> Branden
>
> [1] Thanks to the "devtag" package, internal anchors are still placed
> for section headings, but at present nothing in man(7)'s HTML
> support generates links to them.
>
- We have OSC 8 terminal hyperlink support now, G. Branden Robinson, 2021/10/02
- Re: We have OSC 8 terminal hyperlink support now,
John Gardner <=
- Re: We have OSC 8 terminal hyperlink support now, John Gardner, 2021/10/02
- Re: We have OSC 8 terminal hyperlink support now, G. Branden Robinson, 2021/10/02
- Re: We have OSC 8 terminal hyperlink support now, Alejandro Colomar (man-pages), 2021/10/02
- Re: We have OSC 8 terminal hyperlink support now, G. Branden Robinson, 2021/10/02
- Re: We have OSC 8 terminal hyperlink support now, Alejandro Colomar (man-pages), 2021/10/02
- Re: We have OSC 8 terminal hyperlink support now, G. Branden Robinson, 2021/10/06
- Re: We have OSC 8 terminal hyperlink support now, Alejandro Colomar (man-pages), 2021/10/06
- Re: We have OSC 8 terminal hyperlink support now, Alejandro Colomar (man-pages), 2021/10/06
- Re: We have OSC 8 terminal hyperlink support now, James K. Lowden, 2021/10/04