groff
[Top][All Lists]
Advanced

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

Plan 9 man added a new macro for man page references


From: G. Branden Robinson
Subject: Plan 9 man added a new macro for man page references
Date: Sat, 15 Aug 2020 21:26:57 +1000
User-agent: NeoMutt/20180716

[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
  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]
* 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.  ;-)

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?

Regards,
Branden

[1] 
https://github.com/9fans/plan9port/commit/977b25a76ae8263e53fb4eb1abfc395769f23e3d

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

Attachment: signature.asc
Description: PGP signature


reply via email to

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