Re: macOS Terminal man page URL format

[G. Branden Robinson]

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

signature.asc
Description: PGP signature