[PATCH 11/42] find.1: quote multi-word `SH`, `SS` call arguments

"G. Branden Robinson" <[email protected]> Tue, 18 Nov 2025 21:45:41 -0600
Newsgroups	gmane.comp.gnu.findutils.bugs
Message-ID	<20251119034541.c2jrtcrhckssmhiy@illithid>
The man(7) macro package from AT&T troff and most of its descendants,
including those in DWB, Plan 9, and Solaris troffs, support at most six
arguments to any macro call.

Quote all multi-word arguments to these macros, not just those in excess
of six arguments, as a reminder of defensive practice to document
maintainers.

Before and after on Plan 9 from User Space troff:

$ diff -b -U0 find-plan9port-[12].txt
--- find-plan9port-1.txt        2025-11-18 20:20:08.388887375 -0600
+++ find-plan9port-2.txt        2025-11-18 20:20:14.712881949 -0600
@@ -2068 +2068 @@
-       Safer `find -print0 | xargs -0`
+       Safer `find -print0 | xargs -0` approach
@@ -2129 +2129,2 @@
-       Traversing the filesystem just once en
+       Traversing the filesystem just once en for 2 different actions
---
 find/find.1 | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/find/find.1 b/find/find.1
index 3680bd8d..cada7798 100644
--- a/find/find.1
+++ b/find/find.1
@@ -430,7 +430,7 @@ .SH EXPRESSION
 action also acts like an option (since it implies
 .BR \-depth ).
 .
-.SS POSITIONAL OPTIONS
+.SS "POSITIONAL OPTIONS"
 Positional options always return true.  They affect only tests occurring
 later on the command line.
 .
@@ -518,7 +518,7 @@ .SS POSITIONAL OPTIONS
 .B \-warn
 is also used, it is not specified which, if any, warnings will be active.
 .
-.SS GLOBAL OPTIONS
+.SS "GLOBAL OPTIONS"
 Global options always return true.
 Global options take effect even for tests which occur earlier on the
 command line.  To prevent confusion, global options should be specified
@@ -672,7 +672,7 @@ .SS GLOBAL OPTIONS
 .IP \-xdev
 Don't descend directories on other filesystems.
 .
-.SS TESTS
+.SS "TESTS"
 Some tests, for example
 .B \-newerXY
 and
@@ -1220,7 +1220,7 @@ .SS TESTS
 (SELinux only) Security context of the file matches glob
 .IR pattern .
 .
-.SS ACTIONS
+.SS "ACTIONS"
 .IP "\-delete \&"
 Delete files or directories; true if removal succeeded.
 If the removal failed, an error message is issued and
@@ -1862,7 +1862,7 @@ .SS ACTIONS
 .fi
 .in
 .
-.SS OPERATORS
+.SS "OPERATORS"
 Listed in order of decreasing precedence:
 .
 .IP "( \fIexpr\fR )"
@@ -1926,7 +1926,7 @@ .SS OPERATORS
 will never print
 .IR afile .
 .
-.SH UNUSUAL FILENAMES
+.SH "UNUSUAL FILENAMES"
 Many of the actions of
 .B find
 result in the printing of data which is under the control of other
@@ -1994,7 +1994,7 @@ .SH UNUSUAL FILENAMES
 .B \-okdir
 actions print the current filename as-is.  This may change in a future release.
 .
-.SH STANDARDS CONFORMANCE
+.SH "STANDARDS CONFORMANCE"
 For closest compliance to the POSIX standard, you should set the
 .B POSIXLY_CORRECT
 environment variable.
@@ -2146,7 +2146,7 @@ .SH STANDARDS CONFORMANCE
 .B \-iregex
 tests because those tests aren't specified in the POSIX standard.
 .
-.SH ENVIRONMENT VARIABLES
+.SH "ENVIRONMENT VARIABLES"
 .
 .IP LANG
 Provides a default value for the internationalization variables that
@@ -2261,7 +2261,7 @@ .SH ENVIRONMENT VARIABLES
 .
 .SH EXAMPLES
 .\" A bulleted \(bu list of examples.
-.SS Simple `find|xargs` approach
+.SS "Simple `find|xargs` approach"
 .IP \(bu 4n
 Find files named
 .I core
@@ -2278,7 +2278,7 @@ .SS Simple `find|xargs` approach
 Note that this will work incorrectly if there are
 any filenames containing newlines, single or double quotes, or spaces.
 .
-.SS Safer `find \-print0 | xargs \-0` approach
+.SS "Safer `find \-print0 | xargs \-0` approach"
 .IP \(bu 4n
 Find files named \fIcore\fP in or below the directory \fI/tmp\fP
 and delete them, processing filenames in such a way that file or
@@ -2306,7 +2306,7 @@ .SS Safer `find \-print0 | xargs \-0` approach
 .B xargs
 works with that file.
 .
-.SS Processing arbitrary starting points
+.SS "Processing arbitrary starting points"
 .IP \(bu 4n
 Given that another program \fIproggy\fR pre-filters and creates a huge
 NUL-separated list of files, process those as starting points, and find
@@ -2350,7 +2350,7 @@ .SS Processing arbitrary starting points
 .B `\-execdir\ \&...\&\ +`
 syntax for performance and security reasons.
 .
-.SS Traversing the filesystem just once \(en for 2 different actions
+.SS "Traversing the filesystem just once \(en for 2 different actions"
 .IP \(bu 4n
 Traverse the filesystem just once, listing set-user-ID files and
 directories into
@@ -2652,7 +2652,7 @@ .SS Traversing the filesystem just once \(en for 2 different actions
 .in
 .fi
 .
-.SH EXIT STATUS
+.SH "EXIT STATUS"
 .B find
 exits with status 0 if all files are processed successfully, greater
 than 0 if errors occur.
@@ -2694,7 +2694,7 @@ .SH HISTORY
 came from Dan Bernstein.
 .
 .SH COMPATIBILITY
-.SS Feature Additions
+.SS "Feature Additions"
 .TS
 l l l l .
 Feature	Added in	Year	Also occurs in
@@ -2726,7 +2726,7 @@ .SS Feature Additions
 \-iregex	3.8	1993
 \-print0	2.0	1990	POSIX (from Issue 8, IEEE Std 1003.1\-2024)
 .TE
-.SS Functional Changes
+.SS "Functional Changes"
 .TS
 l l l .
 Version	Year	Change
@@ -2770,7 +2770,7 @@ .SS Functional Changes
 .P
 .
 .SH NON-BUGS
-.SS Operator precedence surprises
+.SS "Operator precedence surprises"
 The command
 .B find .\& \-name afile \-o \-name bfile \-print
 will never print
@@ -2784,7 +2784,7 @@ .SS Operator precedence surprises
 and when there is no operator specified between tests,
 .B \-a
 is assumed.
-.SS \(lqpaths must precede expression\(rq error message
+.SS "\(lqpaths must precede expression\(rq error message"
 .nf
 .B $ find .\& \-name *.c \-print
 find: paths must precede expression
@@ -2833,7 +2833,7 @@ .SH BUGS
 .B \-ok
 action.
 .
-.SH REPORTING BUGS
+.SH "REPORTING BUGS"
 GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help>
 .br
 Report any translation bugs to <https://translationproject.org/team/>
@@ -2856,7 +2856,7 @@ .SH COPYRIGHT
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law.
 .
-.SH SEE ALSO
+.SH "SEE ALSO"
 .BR chmod (1),
 .BR locate (1),
 .BR ls (1),
-- 
2.30.2
signature.asc (application/pgp-signature, 833 B)