Re: macOS Terminal man page URL format

[G. Branden Robinson]

Hi John!

At 2023-02-06T15:19:10+1100, John Gardner wrote:
> > The an (man) macro package can now produce clickable hyperlinks
> > within terminal emulators
> 
> It might be worth clarifying for macOS users that the hyperlinks use a
> protocol incompatible with Apple's: “*man:printf(3)*” is used instead
> of “ *x-man-page://3/printf*” (the latter scheme is ancient and
> documented in detail here
> <https://github.com/donmccaughey/ManOpen/blob/master/Documentation/x-man-page_URL_Scheme.md>
> ).

Thanks for testing things out.

But...ugh!  I don't remember this coming up before, but it could have.
Also, what an ugly convention!  The only thing better than trying to
encode MIME types in the schema of a URL against every relevant RFC ever
is doing so in an undocumented way. :/

> If you agree, I can have a crack at documenting a workaround for macOS
> users, but since it's essentially an opt-in feature, such a thing
> might be overkill at this point. Let me know.

I think I'd prefer to have an internal string for this, called
`an*MR-scheme` or something.  I don't want to clutter the man page with
this, maybe just in the example man.local file.  And since it's specific
to the macOS Terminal application, that means man.local should make it
conditional on "n" (nroff mode) as well.  We don't want the URLs to have
that "x-man-page" business when formatting HTML or, in the near
post-1.23 future I hope, PDF.

I will also need to take this into account when I get around to wiring
up mdoc(7)'s `Xr` macro to OSC 8 as well.

Please file a Savannah ticket for this.

Regards,
Branden

signature.asc
Description: PGP signature