Re: Plan 9 man added a new macro for man page references

[John Gardner]

> Embedding a full URL in man pages sources to an inherently relocatable
page hierarchy is a bad idea.

I'm sorry, what.

man://1/grep
man://grep/1
man:grep(1)


Syntactic bikeshedding notwithstanding, I fail to see why using the `
*scheme*:*path*` syntax could be construed as a bad idea. (Unless, of
course, you were referring to `file://` or `http://` URIs).

On Sun, 16 Aug 2020, 11:26 am Russ Cox, <rsc@swtch.com> wrote:

> On Sat, Aug 15, 2020 at 7:27 AM G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
> >
> > Plan 9 went and did an interesting thing[1].  They implemented a macro
> > just for man page cross-references.
>
> I am amazed you found that so quickly.
>
> > * Uses \X escapes to throw X commands at the output device enabling the
> >   synthesis of a URL with appropriately placed link text boundaries.
>
> This I did back in 2004, for what it's worth.
>
> > Here's what I would have done differently or in addition.
> >
> > * Named the macro MR ("manual reference") to give it even more semantic
> >   weight.  If "IM" is mnemonic for something, I haven't figured out
> >   what.
>
> It was "italic manual reference", but I took your suggestion and
> changed it to MR.
> Thanks!
>
> > * Implemented that string macro, and probably called it MF ("manref
> >   font") or "RF" (reference font).
> > * Broken the syntactical parallel with .IR, thus:
> >     .MR page-name section [hidden-page-anchor]
>
> I broke the parallel with IR as well, but differently.
> $3 is the roman punctuation to follow (without spaces)
> after the manual reference (1). Like:
>
> See
> .IR cat (1) .
>
> > * Added support for another string, perhaps 'MB' ("manref base"?),
> >   supplying a base URL which can be set at page-generation time.
> >   Embedding a full URL in man pages sources to an inherently relocatable
> >   page hierarchy is a bad idea.
>
> For what it's worth, there is no full URL embedded in the sources.
> The references are all from other manual pages, so the refs inserted
> are just relative links like "../man1/cat.html".
>
> > [2] Actually I'm a little puzzled here--as I read the diff, the .nh
> >     request is retained in .IR, rather than being moved to the new .IM).
>
> That was a copy-paste error. I've added the .nh to IM as well.
> (It's in all the macros; it wasn't specific to IR.) Thanks!
>
> Best,
> Russ
>
>