From a424f7c064b3886446d278498a3431eb1e9834b8 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 30 Mar 2020 14:49:20 +0200
Subject: [PATCH] openat2.2: srcfix: Disfavor multiargument .BR and .IR usage

For me, source lines such as:

    .BR perf_setattr "(2), " perf_event_open "(2), and " clone3 (2).

is harder to read than:

    .BR perf_setattr (2),
    .BR perf_event_open (2),
    and
    .BR clone3 (2).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/openat2.2 | 53 +++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 13 deletions(-)

diff --git a/man2/openat2.2 b/man2/openat2.2
index c6a09a145..8a866188d 100644
--- a/man2/openat2.2
+++ b/man2/openat2.2
@@ -93,7 +93,9 @@ The
 argument specifies how
 .I pathname
 should be opened, and acts as a superset of the
-.IR flags " and " mode
+.IR flags
+and
+.IR mode
 arguments to
 .BR openat (2).
 This argument is a pointer to a structure of the following form:
@@ -166,9 +168,13 @@ contains bits other than
 Similarly, an error is returned if
 .BR openat2 ()
 is called with a non-zero
-.IR how.mode " and " how.flags
+.IR how.mode
+and
+.IR how.flags
 does not contain
-.BR O_CREAT " or " O_TMPFILE .
+.BR O_CREAT
+or
+.BR O_TMPFILE .
 .TP
 .I resolve
 This is a bit-mask of flags that modify the way in which
@@ -209,7 +215,9 @@ If the trailing component (i.e., basename) of
 is a symbolic link, and
 .I how.flags
 contains both
-.BR O_PATH " and " O_NOFOLLOW ","
+.BR O_PATH
+and
+.BR O_NOFOLLOW ,
 then an
 .B O_PATH
 file descriptor referencing the symbolic link will be returned.
@@ -230,7 +238,9 @@ If the trailing component (i.e., basename) of
 is a magic link, and
 .I how.flags
 contains both
-.BR O_PATH " and " O_NOFOLLOW ","
+.BR O_PATH
+and
+.BR O_NOFOLLOW ,
 then an
 .B O_PATH
 file descriptor referencing the magic link will be returned.
@@ -238,7 +248,9 @@ file descriptor referencing the magic link will be returned.
 Magic-links are symbolic link-like objects that are most notably found in
 .BR proc (5)
 (examples include
-.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* ).
+.IR /proc/[pid]/exe
+and
+.IR /proc/[pid]/fd/* ).
 Due to the potential danger of unknowingly opening these magic links,
 it may be
 preferable for users to disable their resolution entirely.
@@ -329,7 +341,9 @@ for more detail on how extensions are handled.)
 .B EAGAIN
 .I how.resolve
 contains either
-.BR RESOLVE_IN_ROOT " or " RESOLVE_BENEATH ,
+.BR RESOLVE_IN_ROOT
+or
+.BR RESOLVE_BENEATH ,
 and the kernel could not ensure that a ".." component didn't escape (due to a
 race condition or potential attack).
 The caller may choose to retry the
@@ -345,7 +359,9 @@ An unknown flag or invalid value was specified in
 is non-zero, but
 .I how.flags
 does not contain
-.BR O_CREAT " or " O_TMPFILE .
+.BR O_CREAT
+or
+.BR O_TMPFILE .
 .TP
 .B EINVAL
 .I size
@@ -367,7 +383,9 @@ and one of the path components was a magic link.
 .B EXDEV
 .I how.resolve
 contains either
-.BR RESOLVE_IN_ROOT " or " RESOLVE_BENEATH ,
+.BR RESOLVE_IN_ROOT
+or
+.BR RESOLVE_BENEATH ,
 and an escape from the root during path resolution was detected.
 .TP
 .B EXDEV
@@ -403,7 +421,10 @@ acting as an implicit version number.
 (Because new extension fields will always
 be appended, the structure size will always increase.)
 This extensibility design is very similar to other system calls such as
-.BR perf_setattr "(2), " perf_event_open "(2), and " clone3 (2).
+.BR perf_setattr (2),
+.BR perf_event_open (2),
+and
+.BR clone3 (2).
 .PP
 If we let
 .I usize
@@ -413,13 +434,17 @@ be the size of the structure which the kernel supports, then there are
 three cases to consider:
 .IP \(bu 2
 If
-.IR ksize " equals " usize ,
+.IR ksize
+equals
+.IR usize ,
 then there is no version mismatch and
 .I how
 can be used verbatim.
 .IP \(bu
 If
-.IR ksize " is larger than " usize ,
+.IR ksize
+is larger than
+.IR usize ,
 then there are some extension fields that the kernel supports
 which the user-space application
 is unaware of.
@@ -430,7 +455,9 @@ as having zero values.
 This provides backwards-compatibility.
 .IP \(bu
 If
-.IR ksize " is smaller than " usize ,
+.IR ksize
+is smaller than
+.IR usize ,
 then there are some extension fields which the user-space application
 is aware of but which the kernel does not support.
 Because any extension field must have its zero values signify a no-op,