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

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 8/1/21 1:09 PM, G. Branden Robinson wrote:
> Hi, Alex!
>
> Welcome to the groff list!
>
> At 2021-07-31T16:54:43+0200, Alejandro Colomar (man-pages) wrote:
> > > 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.
> > > * 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'm not sure what the hidden-page-anchor is.
>
> An idea in my head.  It's some text that would "deeply" link into a man
> page document, like a section or subsection heading, but possibly more
> precise than that.  It would be "hidden" because it would not be visibly
> rendered (by default) on a hyperlinking output device.  In a generated
> URI, it might be like <man:/usr/share/man/man2/membarrer.2#THIS>.
>
> However, Russ Cox of Plan 9 troff pointed out, and I think implemented,
> a third argument that is text to be interpolated immediately after the
> manual reference--much like the groff man(7) .ME and .UE macros.
>
> That is not fatal to my evil plans; the internal anchor reference could
> be appended to the section somehow, or as, God forbid, an optional
> fourth argument.  But I'd prefer perverting the second argument to keep
> things close together, like this.
>
>         For more on what can go wrong you when you screw up concurrency,
>         see
>         .MR membarrier 2#Errors .
>
> or
>
>         For more on what can go wrong you when you screw up concurrency,
>         see
>         .MR membarrier "2 Errors" .

Interesting.  You could make it search for SH and SS coincidences.  I 
think a 3rd (or maybe a 4th if the 3rd corresponds to the punctuation) 
argument would be better, as it doesn't have very much relation to the 
2nd one.  It will be simpler to understand in separate arguments.

> Incidentally, Russ changed the name of the macro to MR per my
> suggestion.  I'd like to remain compatible (if possibly extending) what
> Plan 9 troff supports.
>
> > So an example of usage would be:
> >
> > .MR membarrier 2
> >
> > right?
>
> Yes.
>
> > What is the third argument?  A link?  If so, can't the parser
> > construct that link from the first two fields as ../man2/membarrier.2?
>
> Absolutely.  But that will only get them to the top of the page, and
> some man pages are very long.
>
> > > * 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.
> > > * Solicited Michael Kerrisk's support for this revolutionary act.
> > >    ;-)
> >
> > I support this plan ;-)
>
> Cool!  I'm glad to see some discussion about it...it would be _so nice_
> to land this and OSC 8 hyperlinks for terminal emulators in grotty(1)
> for the next groff release.  Those would be new features we could really
> trumpet.
>
> "30 years after Sir Tim Berners-Lee brought you HTML, groff is hot on
> his heels!"
>
> Well, maybe not.  You can see why I'm not in sales.

:-)

> > If there are any updates to this, please CC me.
>
> I'm happy to, but I would also encourage you to subscribe to this one.
> groff@ is pretty low-traffic.

I also subscribed myself to groff@, but from a different email address.

I have alx.manpages@ for normal usage, and then alx.mailinglists@ for 
subscribing to mailing lists.  That way I avoid noise in the other one 
(I'm subscribed to libc-alpha@, linux-man@, linux-api@, which are 
very-high traffic).  And groff@ mails may get lost between many of those 
linux-api@ and libc-alpha@ mails.  That's also why I prefer that people 
CC me in patches instead of sending them only to linux-man@ (there they 
may get lost) (Michael too BTW, for similar reasons).

> > > [3] Going back to the Ur-source of all correct practice, Version 7
> > >      Unix, is not as dispositive as it might be.  Of the 641
> > >      cross-references I count in its corpus, only 345 (53.8%) set the
> > >      page name in italics.  The remainder simply use roman.  The
> > >      barbarism of setting the parenthetical section number in bold or
> > >      italics is not in evidence.
>
> I should go ahead and mention that I'm resolved to implement a string
> called (probably) MF, so make the font used for setting man page names
> configurable at rendering time.
>
> Regards,
> Branden

Kind regards,

Alex


--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/