[Top][All Lists]

[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: Sat, 31 Jul 2021 16:54:43 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0

Sorry for missing CCs. I'm new to this mailing list, and didn't know how to find the list of CCs.

Hi Branden,

[CCing Russ Cox out of the blue; Russ, I work on GNU roff]

Hi folks,

Plan 9 went and did an interesting thing[1].  They implemented a macro
just for man page cross-references.

As you may recall, I've been itching since 2017 to similarly improve our
own man(7) implementation.  I wish I had known Russ's work was in
development, because I would have hopped on the design committee.  Here
are some good things it already does:

* Provides man page references their own semantic tag, rather than
  "overloading .IR" as the motivating bug report states.
* Turns hyphenation off.  Nobody wants the link text (and certainly not
  the URL) in a man page reference hyphenated.
* Uses \X escapes to throw X commands at the output device enabling the
  synthesis of a URL with appropriately placed link text boundaries.
* Enables definition of a string like our HF to control the font style
  used for marking up the page name.  There is a notorious split in
  conventions here: X11, Plan 9, and I prefer italics; Kerrisk (Linx man
  pages project), SunOS 4, and Werner Lemberg prefer bold.[3]

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

So an example of usage would be:

.MR membarrier 2


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?

* 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 ;-)

If there are any updates to this, please CC me.



If implemented, this would of course go in the permissively-licensed
an-ext.tmac, so that others can use it, even those wary of copyleft.

If someone would only support this in exchange for the deprecation of
another GNU extension to the man(7) macro namespace, I have something in
mind.  Let me know.

What do people think?



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

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

Alejandro Colomar
Linux man-pages comaintainer;

reply via email to

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