[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
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.
So an example of usage would be:
.MR membarrier 2
right?
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.
Cheers,
Alex
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.
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: Plan 9 man added a new macro for man page references,
Alejandro Colomar (man-pages) <=