man*/: srcfix

PATCH Superseded G. Branden Robinson 2 participants 6 messages Jul 31, 2023 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

G. Branden Robinson

author

2023-07-31 17:48 UTC #0 lore raw

PATCH v3 1/1 man*/: srcfix

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.

Signed-off-by "G. Branden Robinson" <[email protected]>

---
 man2/eventfd.2         |  4 +++-
 man2/open.2            |  9 +++++++--
 man2/perf_event_open.2 |  7 ++++++-
 man2/signalfd.2        |  4 +++-
 man2/timerfd_create.2  |  4 +++-
 man5/proc.5            |  4 +++-
 man7/credentials.7     | 15 ++++++++++-----
 man7/pty.7             |  5 ++++-
 man7/spufs.7           |  6 +++++-
 9 files changed, 44 insertions(+), 14 deletions(-)

man2/eventfd.2 +3 -1

index 2bd781bdf..003a64eb6 100644
@@ -142,7 +142,9 @@ .SH DESCRIPTION
 if the size of the supplied buffer is less than 8 bytes,
 or if an attempt is made to write the value 0xffffffffffffffff.
 .TP
-.BR poll "(2), " select "(2) (and similar)"
+.BR poll (2),\~\c
+.BR select (2)\~\c
+(and similar)
 The returned file descriptor supports
 .BR poll (2)
 (and analogously

man2/open.2 +7 -2

index 4c921723c..6603dfdff 100644
@@ -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.
 .PP

man2/perf_event_open.2 +6 -1

index aa23a4977..40686917b 100644
@@ -32,7 +32,12 @@ .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.)."
+(\c
+.BR read (2),
+.BR mmap (2),
+.BR prctl (2),
+.BR fcntl (2),
+etc.).
 .PP
 A call to
 .BR perf_event_open ()

man2/signalfd.2 +3 -1

index 2b97c4640..9d0708799 100644
@@ -131,7 +131,9 @@ .SH DESCRIPTION
 .B EAGAIN
 if the file descriptor has been made nonblocking.
 .TP
-.BR poll "(2), " select "(2) (and similar)"
+.BR poll (2),\~\c
+.BR select (2)\~\c
+(and similar)
 The file descriptor is readable
 (the
 .BR select (2)

man2/timerfd_create.2 +3 -1

index d68206b05..9ba0dd315 100644
@@ -317,7 +317,9 @@ .SS Operating on a timer file descriptor
 .BR read (2)
 on the file descriptor.
 .TP
-.BR poll "(2), " select "(2) (and similar)"
+.BR poll (2),\~\c
+.BR select (2)\~\c
+(and similar)
 The file descriptor is readable
 (the
 .BR select (2)

man5/proc.5 +3 -1

index 04b45ccb7..fd51dcec0 100644
@@ -3459,7 +3459,9 @@ .SS Files and directories
 .TP
 .I /proc/locks
 This file shows current file locks
-.RB ( flock "(2) and " fcntl (2))
+.RB ( flock (2)
+and
+.BR fcntl (2))
 and leases
 .RB ( fcntl (2)).
 .IP

man7/credentials.7 +10 -5

index 77cb5e0ef..b07f150bd 100644
@@ -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)

man7/pty.7 +4 -1

index bef60e931..3f23be44d 100644
@@ -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),

man7/spufs.7 +5 -1

index 39fdf583a..96b100b8c 100644
@@ -119,7 +119,11 @@ .SS Files
 file are:
 .RS
 .TP
-.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2)
+.BR read (2),\~\c
+.BR pread (2),\~\c
+.BR write (2),\~\c
+.BR pwrite (2),\~\c
+.BR lseek (2)
 These operate as usual, with the exception that
 .BR lseek (2),
 .BR write (2),

Signature · 4 lines

2.30.2

v3: Resubmitted; no change.  A revision to "MR.sed" handles this case.
v2: Fix goof that boldfaced some opening parentheses in credentials(7).

Alejandro Colomar

maintainer

2023-07-31 19:56 UTC #1 lore raw

Hi Branden,

Quoted 23 lines · G. Branden Robinson

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.
Signed-off-by "G. Branden Robinson" <[email protected]>
---
 man2/eventfd.2         |  4 +++-
 man2/open.2            |  9 +++++++--
 man2/perf_event_open.2 |  7 ++++++-
 man2/signalfd.2        |  4 +++-
 man2/timerfd_create.2  |  4 +++-
 man5/proc.5            |  4 +++-
 man7/credentials.7     | 15 ++++++++++-----
 man7/pty.7             |  5 ++++-
 man7/spufs.7           |  6 +++++-
 9 files changed, 44 insertions(+), 14 deletions(-)

[...]

man5/proc.5 .SS Files and directories · line 3462

Quoted 10 lines

man5/proc.5 +1 -1

index 04b45ccb7..fd51dcec0 100644
@@ -3459,7 +3459,9 @@ .SS Files and directories
 .TP
 .I /proc/locks
 This file shows current file locks
-.RB ( flock "(2) and " fcntl (2))
+.RB ( flock (2)

Is this that you'll do it in MR sed, or that you forgot to fix it? :D

Cheers,
Alex

Quoted 74 lines

man5/proc.5 +2 -0

+and
+.BR fcntl (2))
 and leases
 .RB ( fcntl (2)).
 .IP

man7/credentials.7 +10 -5

index 77cb5e0ef..b07f150bd 100644
@@ -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)

man7/pty.7 +4 -1

index bef60e931..3f23be44d 100644
@@ -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),

man7/spufs.7 +5 -1

index 39fdf583a..96b100b8c 100644
@@ -119,7 +119,11 @@ .SS Files
 file are:
 .RS
 .TP
-.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2)
+.BR read (2),\~\c
+.BR pread (2),\~\c
+.BR write (2),\~\c
+.BR pwrite (2),\~\c
+.BR lseek (2)
 These operate as usual, with the exception that
 .BR lseek (2),
 .BR write (2),

Signature · 2 lines

<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

G. Branden Robinson

author

2023-07-31 20:19 UTC #2 lore raw

Hi Alex,

Quoted 1 line · Alejandro Colomar

Is this that you'll do it in MR sed, or that you forgot to fix it? :D

Yes, that's what I meant to indicate by the v3 annotation at the end of the mail.

Quoted 2 lines

Quoted 2 lines
v3: Resubmitted; no change. A revision to "MR.sed" handles this case.

Regards,
Branden

Alejandro Colomar

maintainer

2023-07-31 20:38 UTC #3 lore raw

Hi Branden,

Quoted 7 lines · G. Branden Robinson

Hi Alex,
Quoted 1 line · Alejandro Colomar
Is this that you'll do it in MR sed, or that you forgot to fix it? :D
Yes, that's what I meant to indicate by the v3 annotation at the end of the mail.

Ahh, I'll tell you my usual routine for reviewing patches, which will probably explain why I didn't notice:

I first try to find the signature. If there's anything not generated by git(1) right below the "---" and before the list of files, I read that first (of course after the Subject) --that's where I would have expected your comment to go--.

Then I may have a fast look at the patch before applying it, especially if I suspect I won't like it at a first glance. But if I trust the sender, I'll directly apply it; reading diffs in the email is not very pleasant, and git will color it nicely for me. And then I review the patch as applied.

So, the only chance that I read personal messages like "This is just a resend" or "I didn't provide the diff; apply the attachment" is putting it there, right below the "---" that goes after your signature. That part is mostly ignored by git(1) --unless the content can be confused with a patch, I guess--.

Quoted 3 lines

Quoted 3 lines
Quoted 3 lines
v3: Resubmitted; no change. A revision to "MR.sed" handles this case.

Okay; your prerogative. Free Britney! :-}

Cheers,
Alex

Quoted 3 lines

Regards,
Branden

Signature · 2 lines

<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

G. Branden Robinson

author

2023-07-31 22:23 UTC #4 lore raw

Hi Alex,

Quoted 7 lines · Alejandro Colomar

Ahh, I'll tell you my usual routine for reviewing patches, which will probably explain why I didn't notice:
I first try to find the signature. If there's anything not generated by git(1) right below the "---" and before the list of files, I read that first (of course after the Subject) --that's where I would have expected your comment to go--.

I am pretty confused. That's where I thought I put it. See screenshot.

Quoted 4 lines

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
v3: Resubmitted; no change. A revision to "MR.sed" handles this case.
Okay; your prerogative. Free Britney! :-}

Always happy to solve with sed what could be done interactively. :D

Regards,
Branden

Alejandro Colomar

maintainer

2023-07-31 22:55 UTC #5 lore raw

Hi Branden,

Quoted 6 lines · G. Branden Robinson

Hi Alex,
Quoted 3 lines · Alejandro Colomar
Ahh, I'll tell you my usual routine for reviewing patches, which will probably explain why I didn't notice:

Quoted 6 lines

Quoted 4 lines
I first try to find the signature. If there's anything not generated by git(1) right below the "---" and before the list of files, I read that first (of course after the Subject) --that's where I would have expected your comment to go--.
I am pretty confused. That's where I thought I put it. See screenshot.

Sorry, I didn't use precise-enough language.

I first try to find the "Signed-off-by". The "---" (3 dashes) below marks where the commit message ends, so anything after it --and before the diff itself-- is ignored by git(1).

It's more or less the same as putting it in the email signature at the end, but I don't have to scroll to the very end.

See an example:
<https://lore.kernel.org/linux-man/[email protected]/T/#mce831a3201a832ba3dc8517b934a42a5a5976e98>

Cheers,
Alex

Quoted 7 lines

Quoted 5 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
v3: Resubmitted; no change. A revision to "MR.sed" handles this case.
Okay; your prerogative. Free Britney! :-}
Always happy to solve with sed what could be done interactively. :D

Troo. :D

Quoted 3 lines

Regards,
Branden

Signature · 2 lines

<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5