groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: G. Branden Robinson
Subject: Re: Plan 9 man added a new macro for man page references
Date: Sun, 1 Aug 2021 21:09:39 +1000
User-agent: NeoMutt/20180716

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" .

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.

> > [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

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]