I know it's probably a bit early for this discussion, but somebody on GitHub raised a good question <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda#gistcomment-3914435> :
Why x-man-page? dnf reports that yelp & khelpcenter provide man:// - but > has no providers for x-man-page:// > He was referring to an example I gave of a hyperlinked man page reference ( x-man-page://awk.1), which is supported on macOS (Terminal.app and iTerm2), but not universally <https://github.com/Alhadis/Roff.js/blob/ba9b904b944c028033b4b4f584521436a34a5d57/lib/utils/general.mjs#L15-L23>. Which invites the question—how are we going to hyperlink man page references, specifically? On Sat, 2 Oct 2021 at 14:02, G. Branden Robinson < g.branden.robin...@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. >