[PATCH v3] man*/: srcfix

[PATCH v3] man*/: srcfix

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5790 bytes --]

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" <g.branden.robinson@gmail.com>
---
 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(-)

diff --git a/man2/eventfd.2 b/man2/eventfd.2
index 2bd781bdf..003a64eb6 100644
--- a/man2/eventfd.2
+++ b/man2/eventfd.2
@@ -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
diff --git a/man2/open.2 b/man2/open.2
index 4c921723c..6603dfdff 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.
 .PP
diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index aa23a4977..40686917b 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -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 ()
diff --git a/man2/signalfd.2 b/man2/signalfd.2
index 2b97c4640..9d0708799 100644
--- a/man2/signalfd.2
+++ b/man2/signalfd.2
@@ -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)
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index d68206b05..9ba0dd315 100644
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -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)
diff --git a/man5/proc.5 b/man5/proc.5
index 04b45ccb7..fd51dcec0 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -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
diff --git a/man7/credentials.7 b/man7/credentials.7
index 77cb5e0ef..b07f150bd 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 bef60e931..3f23be44d 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),
diff --git a/man7/spufs.7 b/man7/spufs.7
index 39fdf583a..96b100b8c 100644
--- a/man7/spufs.7
+++ b/man7/spufs.7
@@ -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),
-- 
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).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man*/: srcfix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3710 bytes --]

Hi Branden,

On 2023-07-31 19:48, G. Branden Robinson wrote:
> 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" <g.branden.robinson@gmail.com>
> ---
>  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(-)
> 

[...]

> diff --git a/man5/proc.5 b/man5/proc.5
> index 04b45ccb7..fd51dcec0 100644
> --- a/man5/proc.5
> +++ b/man5/proc.5
> @@ -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

> +and
> +.BR fcntl (2))
>  and leases
>  .RB ( fcntl (2)).
>  .IP
> diff --git a/man7/credentials.7 b/man7/credentials.7
> index 77cb5e0ef..b07f150bd 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 bef60e931..3f23be44d 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),
> diff --git a/man7/spufs.7 b/man7/spufs.7
> index 39fdf583a..96b100b8c 100644
> --- a/man7/spufs.7
> +++ b/man7/spufs.7
> @@ -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),

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man*/: srcfix

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 316 bytes --]

Hi Alex,

At 2023-07-31T21:56:27+0200, Alejandro Colomar wrote:
> 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.

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

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man*/: srcfix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1570 bytes --]

Hi Branden,

On 2023-07-31 22:19, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-31T21:56:27+0200, Alejandro Colomar wrote:
>> 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--.

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

Okay; your prerogative.  Free Britney!  :-}

Cheers,
Alex

> 
> Regards,
> Branden

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man*/: srcfix

[G. Branden Robinson]

[-- Attachment #1.1: Type: text/plain, Size: 743 bytes --]

Hi Alex,

At 2023-07-31T22:38:45+0200, Alejandro Colomar wrote:
> 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.

> >>> 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

[-- Attachment #1.2: the-v3-situation.png --]
[-- Type: image/png, Size: 45095 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man*/: srcfix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1486 bytes --]

Hi Branden,

On 2023-08-01 00:23, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-31T22:38:45+0200, Alejandro Colomar wrote:
>> 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.

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/7c0279c1-bbb8-c623-14d2-bb4d25966d28@kernel.org/T/#mce831a3201a832ba3dc8517b934a42a5a5976e98>

Cheers,
Alex


> 
>>>>> 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

> 
> Regards,
> Branden

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]