Re: macOS Terminal man page URL format

[John Gardner]

Knowing Apple, the *x-man-page://* scheme was intended for internal use
between userland programs; a similar protocol exists for looking up a
word's definition: *x-dictionary:harangue*. However, the nature of macOS's
LaunchServices makes it impossible (or at least incredibly difficult) for
any supported URL scheme to be hidden from users. People likely
"discovered" x-man-page whilst snooping through files such as
~/Library/Preferences/com.apple.LaunchServices/com.apple.launchservices.secure.plist
.

Regardless of the scheme's origin, the likelihood of Apple dropping support
forit is precisely zero. macOS inherits a load of weirdness for the sake of
legacy compatibility, which natrally includes schemes like x-man-page. This
doesn't mean man:page(1) and x-man-page://1/page won't some day be
supported side-by-side, however.

In any case, I just realised there's a much bigger hurdle: macOS switched
to mandoc(1) in version 11 (November 2020), and patched their /usr/bin/man
binary to use hardcoded paths like /usr/bin/mandoc. The exact changes Apple
made to man-1.6g can be examined on GitHub
<https://github.com/apple-oss-distributions/man/compare/d1a6cf2..34c45d6>
(or by running `git show d1a6cf2...34c45d6
<https://github.com/apple-oss-distributions/man/compare/d1a6cf2..34c45d6>`
on a local checkout of the apple-oss-distributions/man
<https://github.com/apple-oss-distributions/man> mirror). So, erh, yeah…
this complicates things…

You can see that I'd very much like to get into an argument with whoever
> coded this into Terminal.app in the first place.
>

It's not so much a part of Terminal.app as it is the default handler for
x-man-page URLs (in the same way that Thunderbird handles mailto: URLs).
It's theoretically possible to register a different app, although the
procedure appears complicated (and I've yet to read up on it myself: it's
on my to-do list under *"Weaponise lsappinfo(8)"*).


On Tue, 7 Feb 2023 at 08:03, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

> Hi John,
>
> At 2023-02-07T07:24:52+1100, John Gardner wrote:
> [I wrote:]
> > > I would prefer to hold macOS up to ridicule in this respect in hopes
> > > of motivating its users (and developers) to standardize on
> > > something.
> >
> > By "standardise", are you specifically referring to a *de jure*
> > standard?
>
> Well, nearly as _jure_ as we get in Internet world, which I guess would
> be an RFC.  (This doesn't really seem like POSIX's bailiwick, but they
> do produce a true standard.)
>
> > macOS's x-man-page:// scheme is only a *de facto* standard, but it's
> > by far the oldest, best-known, and widely-supported man-page URL
> > scheme on macOS, even recently.
>
> Okay.  I don't aim to not support it so much as harangue Apple partisans
> into calling for man:page(section) support in Terminal.app...so that I
> can, at some point down the road, _then_ unsupport x-man-page.  The
> leading "x-" acknowledges that it was a stopgap measure, or I miss my
> guess.  (It is reminiscent of nonstandard MIME types.)  I see that the
> "x-" prefix itself is now, apparently, deprecated[1], and more to the
> point, the scheme part of a URL is not an appropriate place to express
> the _content_ of a delivered data stream, but rather the _transport
> mechanism_ by which it is fulfilled.
>
> What is the mechanism by which a man page is resolved to a deliverable
> document, given a page name and section identifier?
>
> Why, that would be the "man" librarian program.
>
> The availability of something that delivers the man page document to a
> browser is implied by the fact of its encoding in a URL in the first
> place.
>
> You can see that I'd very much like to get into an argument with whoever
> coded this into Terminal.app in the first place.  I expect either a
> sheepish admission that something intended as a quick hack raged out of
> control (I've had those, and I am loath to name them), or to find
> someone with a cowboy hat and a lot of bullshit to peddle.
>
> > Yes, but you have actually encountered these in practical experience.
> >
> > It wasn't a practical encounter. I was actively researching how
> > authors have approached the issue of man-page hyperlinks in the past
> > (not just on macOS, but *any* Unix-like system). I did this to make
> > Roff.js's URI handling functions as airtight as possible.
>
> That _is_ practice, my good sir.  Your did your homework in service of
> pursuing a clean design.
>
> > BTW, what file should I apply your patch to? I'm getting an error when
> > I > attempt to apply it:
> >
> > $ git apply ~/Downloads/macOS-man-grief.diff
> > error: patch failed: tmac/man.local:14
> > error: tmac/man.local: patch does not apply
> >
> > Remember, this is with the latest Groff sources, which still aren't
> > building successfully on macOS…
>
> Right, sorry.  You'll have to apply the patches to a system _in situ_
> and I forgot about that.
>
> On my Debian system, an.tmac lives in /usr/share/groff/1.22.4, and
> man.local in /etc/groff.
>
> Looking at your configuration report in Savannah #63767, I would expect
> to find the relevant files in
>
> /usr/local/share/groff/1.23.0/tmac/an.tmac
>
> and
>
> /usr/local/share/groff/site-tmac/man.local
>
> respectively.
>
> Let me know if you have trouble and maybe I can help you track them
> down.  The groff_man(7) page from a recent prior installation of groff
> Git should also identify these locations (in the section "Files").
>
> Regards,
> Branden
>
> [1] https://www.rfc-editor.org/rfc/rfc6648
>