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: Alejandro Colomar (man-pages)
Subject: Re: Plan 9 man added a new macro for man page references
Date: Sun, 1 Aug 2021 14:06:38 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0

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/



reply via email to

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