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