Re: Groff macro to make .UR and .UE links clickable in PDF?

[Ingo Schwarze]

Hi,

B 9 wrote on Mon, Jun 15, 2020 at 05:03:32PM -0700:
> Jan Stary <hans@stare.cz> wrote:

>> You say mdoc; shouldn't the links be Lk?

In mdoc(7): yes, absolutely.
Use .Lk in mdoc(7), .UR is not supported by mdoc(7) at all.

> Good question. I had tried Lk first and it didn't seem work any better
> and was less well documented. The man page for 'mdoc' which comes with
> GNU/Linux systems (kernel.org/doc/man-pages) mentions UR and UE,
> but omits Lk.

Oh no.  In general, the Linux man pages project maintained by Michael
Kerrisk contains lots of decent manual pages for Linux and is well
maintained.  But the mdoc(7) manual they had was an outlier.  It
was incomplete, misleading in several respects, and outdated by a
few decades (yes, literally unmaintained for more than 20 years).

Besides, mdoc(7) has nothing to do with Linux.  For that reason,
we recently convinced the Linux man pages project to delete that
bad page, and they did.  Some old 4.xx distibutions of the Linux
man pages project still contain the bad mdoc(7) page, but newer
5.xx distributions no longer have it.


> On the other hand, 'man groff_mdoc' doesn't mention UR or UE,
> and says Lk is "To be written."

The groff_mdoc(7) page is quite good in general but has a few minor
defects; .Lk not being properly documented is one of them.

I'd recommend this one as the authoritative mdoc(7) reference:

  https://man.bsd.lv/mdoc.7

> Do you have any insight on making a macro, whether via Lk or UR/UE,
> that will create PDF links?

One person already recommended a way to make normal .Lk in mdoc(7)
and normal .UR in man(7) produce PDF links with groff, but i suggest
a different perspective.  Decide what it is that you really want:
if you want excellent typography from an mdoc(7) document, use
groff(1) PDF output.  If you want perfect linking on the web, PDF
is not the ideal format.  In that case, use mandoc(1) HTML output,
which is much better for the web.  You can see that output on
man.bsd.lv, produced with the program from mandoc.bsd.lv.  It gives
you much more linking and better linking than PDF ever could.

Yours,
  Ingo