[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.
signature.asc
Description: PGP signature
- Plan 9 man added a new macro for man page references,
G. Branden Robinson <=