[PATCH v6] man*/: srcfix

[PATCH v6] man*/: srcfix

[G. Branden Robinson]

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

Clean up in preparation for "MR sed".

Format only one man page cross reference per input line.

Begin parentheticals on their own input lines.

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>

Changes since v5:

* Begin parentheticals on their own input lines.

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      |  8 ++++++--
 man7/credentials.7     | 15 ++++++++++-----
 man7/pty.7             |  5 ++++-
 5 files changed, 34 insertions(+), 12 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..63ea8c766 100644
--- a/man5/proc_locks.5
+++ b/man5/proc_locks.5
@@ -11,9 +11,13 @@ .SH DESCRIPTION
 .TP
 .I /proc/locks
 This file shows current file locks
-.RB ( flock "(2) and " fcntl (2))
+(\c
+.BR flock (2)
+and
+.BR fcntl (2))
 and leases
-.RB ( fcntl (2)).
+(\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

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

Re: [PATCH v6] man*/: srcfix

[Alejandro Colomar]

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

Hi Branden,

On Tue, Nov 07, 2023 at 12:49:12PM -0600, G. Branden Robinson wrote:
> Clean up in preparation for "MR sed".
> 
> Format only one man page cross reference per input line.
> 
> Begin parentheticals on their own input lines.
> 
> 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>

Patch applied.  Thanks!

Cheers,
Alex

> 
> Changes since v5:
> 
> * Begin parentheticals on their own input lines.
> 
> 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      |  8 ++++++--
>  man7/credentials.7     | 15 ++++++++++-----
>  man7/pty.7             |  5 ++++-
>  5 files changed, 34 insertions(+), 12 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..63ea8c766 100644
> --- a/man5/proc_locks.5
> +++ b/man5/proc_locks.5
> @@ -11,9 +11,13 @@ .SH DESCRIPTION
>  .TP
>  .I /proc/locks
>  This file shows current file locks
> -.RB ( flock "(2) and " fcntl (2))
> +(\c
> +.BR flock (2)
> +and
> +.BR fcntl (2))
>  and leases
> -.RB ( fcntl (2)).
> +(\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



-- 
<https://www.alejandro-colomar.es/>

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