Hi Jakub,
At 2023-08-01T00:16:41+0200, Jakub Wilk wrote:
> * G. Branden Robinson <g.branden.robinson@xxxxxxxxx>, 2023-07-31 12:52:
> > Use the man(7) macro `MR`, new to groff 1.23.0,
>
> Given that this version of groff was released approximately
> yesterday¹, this is very premature.
>
> NACK from me.
>
> ¹ More precisely, about a month ago.
5 July UTC, to be (a little) more precise.
Linux man-pages release scheduling is Alex's prerogative, not mine. He
asked me (a long time ago) to deliver this after groff 1.23.0 was
released. That is what I have tried to do.
> > When the text of all Linux man-pages documents (excluding those
> > containing only `so` requests) is dumped, with adjustment mode 'l'
> > ("-dAD=l") and automatic hyphenation disabled ("-rHY=0") before and
> > after this change, there is no change to rendered output.
>
> That's not what I'm seeing with Debian groff 1.22.4-10 (which seems to
> have .MR backported).
Not exactly. It has a compatible stopgap measure to keep Debian stable
from going wrong in the event that any package using `MR` in its man
pages gets backported to bookworm (Debian 12).
https://salsa.debian.org/debian/groff/-/merge_requests/4
groff 1.22.4 man(7) does not support the `MF` string (see below). That
could be backported too, but there seems no point before there is a
concrete need.
> After applying the patch, the man page references are typeset in
> italics,
For great justice! (See below.)
> which is ugly
See my recent exchanges with Lennart Jablonka on this list.
> and against man-pages(7) recommendations.
Not all man pages are bound by man-pages(7) style suggestions.
Further, /etc/groff/man.local is a conffile, and assuming it's stock (to
simplify the pattern matching below), you can do this:
sed -i -e 's/IR/BR/' /etc/groff/man.local
And that way, even if someone backports groff 1.23.0 itself to Debian
stable, you will not be disturbed by the choice of font for man page
cross references.
It might be helpful to recap the `MR` feature description from the
1.23.0 NEWS file and release announcement. One of its objectives is to
_stop_ prescribing a typeface for these things, though of course it has
a default, as it must.
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
can create a clickable hyperlink ("man:ls(1)" for the above example)
on supporting devices. Furthermore, a new string, `MF`, defines the
font to be used for setting the man page topic (the first argument to
`MR` and `TH`), permitting configuration by distributions, sites, and
users.
Inclusion of the `MR` macro was prompted by its introduction to
Plan 9 from User Space's troff in August 2020. Its purpose is 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 into man page topics,
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
topic (italics, roman, or bold).
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
