Clean up in preparation for "MR.sed".
Format only one man page cross reference per input line.
Also, groff 1.23.0's (and Plan 9 from User Space's) `MR` is not a font
style alternation macro; there is no "reversed" form as with `BR` and
`RB`. So when a man page cross reference must be immediately preceded
by punctuation, put that punctuation on the previous text line and use
the `\c` escape sequence to connect them.
With this decoupling accomplished, "MR.sed" can be run at any fortuitous
time on all but a few pages (see below).
As a preview and yet another heads-up, I am also attaching the "MR.sed"
script and the commit message that I prepared to accompany the change it
makes.
Signed-off-by: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
Changes since v4:
* Drop the big `MR` migration part of the patch itself, which is
entirely sed-driven. I had already taken care of the proc_locks(5)
change that Alex had requested in v4, but neither of us noticed this.
It's still a benefit to apply this preparatory source fix.
Changes since v3:
* Resync the preparatory patch (1/2) [all that is left now] with recent
adoption of `TQ` macro in more places, reducing the number of manual
preparations needed.
* Stop trying to migrate tzfile(5), tzselect(8), zdump(8), zic(8), and
time2posix(3); and bpf-helpers(7), which are externally maintained.
Thanks to Brian Inglis. [no longer applicable to v5]
Changes since v2:
* No changes to this part. [The sed script grew an additional case,
IIRC.]
Changes since v1:
* Add `\c` before flock(2) reference in proc(5) [now proc_locks(5)].
---
man2/open.2 | 9 +++++++--
man2/perf_event_open.2 | 9 +++++++--
man5/proc_locks.5 | 10 ++++++----
man7/credentials.7 | 15 ++++++++++-----
man7/pty.7 | 5 ++++-
5 files changed, 34 insertions(+), 14 deletions(-)
diff --git a/man2/open.2 b/man2/open.2
index 381da6235..f37ddbed0 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -82,8 +82,13 @@ .SH DESCRIPTION
to an entry in the process's table of open file descriptors.
The file descriptor is used
in subsequent system calls
-.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
-etc.) to refer to the open file.
+(\c
+.BR read (2),
+.BR write (2),
+.BR lseek (2),
+.BR fcntl (2),
+etc.)
+to refer to the open file.
The file descriptor returned by a successful call will be
the lowest-numbered file descriptor not currently open for the process.
.P
diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 2b2fc2596..5f68f5204 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -32,8 +32,13 @@ .SH DESCRIPTION
Given a list of parameters,
.BR perf_event_open ()
returns a file descriptor, for use in subsequent system calls
-.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)."
-.P
+(\c
+.BR read (2),
+.BR mmap (2),
+.BR prctl (2),
+.BR fcntl (2),
+etc.).
+.PP
A call to
.BR perf_event_open ()
creates a file descriptor that allows measuring performance
diff --git a/man5/proc_locks.5 b/man5/proc_locks.5
index cf4ff678c..a938e4ad7 100644
--- a/man5/proc_locks.5
+++ b/man5/proc_locks.5
@@ -10,10 +10,12 @@ .SH NAME
.SH DESCRIPTION
.TP
.I /proc/locks
-This file shows current file locks
-.RB ( flock "(2) and " fcntl (2))
-and leases
-.RB ( fcntl (2)).
+This file shows current file locks (\c
+.BR flock (2)
+and
+.BR fcntl (2))
+and leases (\c
+.BR fcntl (2)).
.IP
An example of the content shown in this file is the following:
.IP
diff --git a/man7/credentials.7 b/man7/credentials.7
index 32d8a3243..02427a9e5 100644
--- a/man7/credentials.7
+++ b/man7/credentials.7
@@ -267,21 +267,26 @@ .SS Modifying process user and group IDs
Subject to rules described in the relevant manual pages,
a process can use the following APIs to modify its user and group IDs:
.TP
-.BR setuid "(2) (" setgid (2))
+.BR setuid (2)\~(\c
+.BR setgid (2))
Modify the process's real (and possibly effective and saved-set)
user (group) IDs.
.TP
-.BR seteuid "(2) (" setegid (2))
+.BR seteuid (2)\~(\c
+.BR setegid (2))
Modify the process's effective user (group) ID.
.TP
-.BR setfsuid "(2) (" setfsgid (2))
+.BR setfsuid (2)\~(\c
+.BR setfsgid (2))
Modify the process's filesystem user (group) ID.
.TP
-.BR setreuid "(2) (" setregid (2))
+.BR setreuid (2)\~(\c
+.BR setregid (2))
Modify the process's real and effective (and possibly saved-set)
user (group) IDs.
.TP
-.BR setresuid "(2) (" setresgid (2))
+.BR setresuid (2)\~(\c
+.BR setresgid (2))
Modify the process's real, effective, and saved-set user (group) IDs.
.TP
.BR setgroups (2)
diff --git a/man7/pty.7 b/man7/pty.7
index ef8974f47..7f47ce550 100644
--- a/man7/pty.7
+++ b/man7/pty.7
@@ -122,7 +122,10 @@ .SH FILES
BSD slave devices
.SH NOTES
Pseudoterminals are used by applications such as network login services
-.RB ( ssh "(1), " rlogin "(1), " telnet (1)),
+(\c
+.BR ssh (1),
+.BR rlogin (1),
+.BR telnet (1)),
terminal emulators such as
.BR xterm (1),
.BR script (1),
--
2.30.2
# Handle simplest cases: ".BR foo (1)" and ".IR foo (1)". s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))$/.MR \2 \3/ # Handle case: trailing punctuation, as in ".IR foo (1),". s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/.MR \2 \3 \4/ # Handle case: leading punctuation, as in ".RI ( foo (1)". s/^.R[BI] \(\\%\)*\([^[:space:]]\+\) \([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/\\%\2\\c\n.MR \3 \4 \5/ # Handle case: 3rd+ arguments or trailing comments. This case is rare # and will require manual fixup if there are 4+ arguments to MR. Use # groff -man -rCHECKSTYLE=1 to have them automatically reported. s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\( .*\)/.MR \2 \3\4/
man*/: ffix (migrate to `MR`)
Use the man(7) macro `MR`, new to groff 1.23.0, instead of font style
alternation macros to mark up man page cross reference.
Depending on your configuration of groff man(7), this change may also
alter the typeface that is used to mark up man page topic names (that
is, the "ls" in "ls(1)". groff by default sets these italics (which
often appear underlined on terminals), in concord with the original AT&T
Unix troff man(7) implementation in 1979. A motivational excursus is
available.[1] To change this typeface selection, see the end of this
commit message.
Background (from the groff 1.23.0 release announcement and "NEWS" file):
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).
[...]
o The an (man) macro package can now produce clickable hyperlinks within
terminal emulators, using the OSC 8 support added to grotty(1) (see
below). The groff man(7) extension macros `UR` and `MT`, present
since 2007, expose this feature. At present the feature is disabled
by default in `man.local` pending more widespread recognition of OSC 8
sequences in pager programs. The package now recognizes a `U`
register to enable hyperlinks in any output driver supporting them.
Use a command like
printf '\033]8;;man:grotty(1)\033\\grotty(1)\033]8;;\033\\\n' | more
to check your terminal and pager for OSC 8 support. If you see
"grotty(1)" and no additional garbage characters, then you may wish to
edit "man.local" to remove the lines that disable this feature.
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.
When automatic hyphenation is enabled, this change suppresses
hyphenation of approximately 3,100+ man page names when cross referenced
when using the default terminal width of 80 (meaning that the text
is formatted for a line length of 78 for historical reasons).
I prepared this change with the following GNU sed script.
\# Handle simplest cases: ".BR foo (1)" and ".IR foo (1)".
s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))$/.MR \2 \3/
\# Handle case: trailing punctuation, as in ".IR foo (1),".
s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/.MR \2 \3 \4/
\# Handle case: leading punctuation, as in ".RI ( foo (1)".
s/^.R[BI] \(\\%\)*\([^[:space:]]\+\) \([.@_[:alnum:]\\-]\+\) (\([1-9a-z]\+\))\([^[:space:]]\+\)$/\\%\2\\c\n.MR \3 \4 \5/
\# Handle case: 3rd+ arguments or trailing comments. This case is rare
\# and will require manual fixup if there are 4+ arguments to MR. Use
\# groff -man -rCHECKSTYLE=1 to have them automatically reported.
s/^.[BI]R \(\\%\)*\([.@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\( .*\)/.MR \2 \3\4/
(The sed comment characters are escaped because they are also comments
in Git commit messages.)
$ sed -i -f MR.sed man*/*
Confirm no errors arising in the `MR` argument count as follows.
$ groff --version | head -n 1
GNU groff version 1.23.0
$ groff -z -t -rCHECKSTYLE=1 -m andoc -T utf8 -P -cbou \
$(grep -L '^\.so ' man*/* | sort) 2>&1 | grep -q MR \
|| echo "IT'S CLEAN"
IT'S CLEAN
To get the man page topic names to render in bold again as the Linux
man-pages have historically done, set the *roff "MF" string to "B".
1. man-db man(1) supports an environment variable for passing options
to the formatter.
MANROFFOPT="-dMF=B"
You might wish to set this in your shell startup file and export the
variable.
2. When rendering pages directly with groff, nroff, or troff, you can
set the string on the command line.
nroff -dMF=B -mandoc man1/getent.1
3. You can set this string in groff man(7)'s site-local configuration
file. Its location depends on groff's build-time parameters, but is
documented in the groff_man(7) page. On Debian-based systems, it's
in /etc/groff/man.local. Add the following line (with no leading
spaces).
.ds MF B\"
(The trailing '\"' is a safety measure.[2])
[1] https://lore.kernel.org/linux-man/20230803175738.dqpxy3dirl3bpznv@illithid/T/#u
[2] https://www.gnu.org/software/groff/manual/groff.html.node/Strings.html
Signed-off-by: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
Attachment:
signature.asc
Description: PGP signature
