Re: [BUG] .MR: hyperlink only on html, but not on pdf or terminal

[G. Branden Robinson]

Hi Alex,

At 2022-01-24T22:22:21+0100, Alejandro Colomar wrote:
> Hi Branden,
> 
> I used the shiny new .MR macro from groff git HEAD, and I like it :)

Great!  I'm thrilled to hear it.

> However, I miss the hyperlink on non-html output.  I tried PDF (groff
> -T pdf), HTML (groff -T html), and the terminal (man), and I only saw
> the link on the HTML page.

That's expected.  There are two issues.  The one with the terminal is
expected, and you _can_ get what you want.

From NEWS:

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.

  Use a command like
    printf '\033]8;;man:grotty(1)\033\\grotty(1)\033]8;;\033\\\n' | more
  to check your terminal and pager for OSC 8 support.  If you see
  "grotty(1)" and no additional garbage characters, then you may wish to
  edit "man.local" to remove the lines that disable this feature.

So you might want to add -U1 to your groff command line to check it out.
And possibly edit /etc/groff/man.local (or wherever that file is
installed per GNU configure options) to make the enablement permanent.

Also, from groff_man(7):
   Hyperlink macros
       Man page cross references are best presented with .MR.  Email
       addresses are bracketed with .MT/.ME and other forms of hyperlink
       with .UR/.UE.  Hyperlinked text is supported on the html, tty,
       and xhtml output devices; terminals and pager programs must
       support ECMA-48 OSC 8 escape sequences (see grotty(1)).  When
       device support is unavailable or disabled with the U register
       (see section “Options” below), .MT and .UR URIs are rendered
       between angle brackets after the linked text.
[...]
       -rU1   Enable generation of URI hyperlinks in the grohtml and
              grotty output drivers.  grohtml enables them by default;
              grotty does not, pending more widespread pager support for
              OSC 8 escape sequences.  Use -rU0 to disable hyperlinks;
              this will make the arguments to MT and UR calls visible in
              the document text produced by link-capable drivers.

Is there some other good place I can put this information?

> Would you mind adding it to the other devices?

PDF is the other issue.  It just hasn't been done yet.  groff's output
driver for PDF, gropdf(1) is a complex beast with a bewildering array of
options.

I _think_ what I want is the 'pdfhref' device control command, but I'm
not certain.

I had been postponing this work until (A) a volunteer saved me the
trouble or (B) I achieved my long-awaited dream of shipping a typeset
version of all of groff's man pages.

(B) just happened this week.  Even it will require 2 stages.  (1)
Enablement of general URLs; (2) special trickery to render MR links as
internal links within the ~380-page document.  Deri James has done stuff
like this before, so I know it's possible.  It's just something I need
to learn, though my preference would be for someone to give me a fish
while I consider what sort of bait and tackle I'd like to have someday.
;-)

This could be a Savannah ticket, too, but only file it if you want to: I
was going to work on this anyway, as noted.

Regards,
Branden

signature.asc
Description: PGP signature