Hi all, I'm pleased to announce the addition, in discussion for over a year[1], of a new semantic macro for the GNU implementation of man(7), prompted by and compatible with Plan 9 troff, for man page cross references: MR.
The OSC 8 work on grotty(1), announced earlier this week, laid the
foundation for this work, enabling us to deliver true hyperlinked cross
references for output drivers other than grohtml, as opposed to mere
typeface changes.
Because man(7) culture is conservative, I have summarized the multiple
rationales for and expected benefits of this change in its NEWS item.
o The an (man) macro package supports a new macro, "MR", intended for
use by man page cross references in preference to the font style
alternation macros historically used. Where before you would write
.BR ls (1).
or
.IR ls (1).
you should now write
.MR ls 1 .
(the third argument, typically used for trailing punctuation, is
optional). Because the macro semantically identifies a man page, it
also creates a clickable hyperlink ("man:ls(1)" for the above example)
on supporting devices. A new string, MF, defines the font to be used
for setting man page titles (the first argument to .MR and .TH),
permitting its configuration by distributions, sites, and users.
The MR macro is offered for compatibility with Plan 9 troff, which
introduced it in August 2020, and to ameliorate several long-standing
problems with man page cross references: (1) the package's lack of
inherent hyperlink support for them; (2) false-positive identification
of strings resembling man page cross references (as can happen with
"exit(1)", "while(1)", "sleep(5)", "time(0)" and others) by terminal
emulators and other programs; (3) the unwanted intrusion of hyphens in
man page names, which frustrates copy-and-paste operations (this
problem has always been avoidable through use of the \% escape
sequence, but cross references are frequent in man pages and some page
authors are inexpert *roff users); and (4) deep divisions in man page
maintenance communities over which typeface should be used to set the
man page title (italics, roman, or bold).
Here's the documentation of this feature in groff_man_style(7)
(groff_man(7) omits the examples and differs slightly in wording).
[...]
Hyperlink macros
Man page cross references like ls(1) are best presented with .MR.
Email addresses are bracketed with .MT/.ME and other forms of hy‐
perlink with .UR/.UE. Hyperlinked text is supported on the html
and tty output devices; terminals and pager programs must support
EMCA-48 OSC 8 escape sequences (see grotty(1)). When device sup‐
port is unavailable or disabled with the U register (see section
“Options” below), .MT and .UR URIs are rendered after the linked
text.
.MT, .ME, .UR, and .UE are GNU extensions not defined on systems
running AT&T, Plan 9, or Solaris troff; see an-ext.tmac in sec‐
tion “Files” below. Plan 9 troff implements .MR.
.MR page-title page-section [trailing-text]
Set a man page cross reference as “page-title(page-sec‐
tion)”. If trailing-text (typically punctuation) is spec‐
ified, it follows the closing parenthesis without inter‐
vening space. Hyphenation is disabled while the cross
reference is set. page-title is set in the font specified
by the MF string. The cross reference hyperlinks to a URI
of the form “man:page-title(page-section)”.
The output driver
.MR grops 1
produces Postscript from
.I troff
output.
.
The Ghostscript program (\c
.MR gs 1)
interprets Postscript and PDF.
[...]
Options
The following groff options set registers (with -r) and strings
(with -d) recognized and used by the man macro package.
[...]
-dMF=man-page-title-font
Set the font used for man page titles named in .TH and .MR
calls; the default is “I” (italic). Any valid argument to
groff’s “.ft” request may be used; see groff(7). If the
MF string ends in “I”, it is assumed to be an oblique
typeface, and italic corrections are applied before and
after man page titles.
[...]
Files
[...]
/usr/local/share/groff/1.23.0/tmac/an-ext.tmac
The extension macro definitions for .SY, .YS, .TQ,
.EX/.EE, .UR/.UE, and .MT/.ME are contained in this file;
if the formatter is not GNU troff, it also provides an .MR
implementation that does not attempt hyperlinking. These
macros are written to be compatible with AT&T troff and
permissively licensed—not copylefted.
[...]
I'll start migrating our own man pages from .BR and .IR to .MR in the
coming days.
Regards,
Branden
[1] https://lists.gnu.org/archive/html/groff/2020-08/msg00068.html
https://lists.gnu.org/archive/html/groff/2021-07/msg00132.html
signature.asc
Description: PGP signature
